staging-next 2025-04-03

doc/hooks/memcached-test-hook.section.md

@@ -0,0 +1,53 @@
+
+# `memcachedTestHook` {#sec-memcachedTestHook}
+
+This hook starts a Memcached server during `checkPhase`. Example:
+
+```nix
+{
+  stdenv,
+  memcachedTestHook,
+}:
+stdenv.mkDerivation {
+
+  # ...
+
+  nativeCheckInputs = [
+    memcachedTestHook
+  ];
+}
+```
+
+If you use a custom `checkPhase`, remember to add the `runHook` calls:
+```nix
+  checkPhase ''
+    runHook preCheck
+
+    # ... your tests
+
+    runHook postCheck
+  ''
+```
+
+## Variables {#sec-memcachedTestHook-variables}
+
+Bash-only variables:
+
+ - `memcachedTestPort`: Port to use by Memcached. Defaults to `11211`
+
+Example usage:
+
+```nix
+{ stdenv, memcachedTestHook }:
+stdenv.mkDerivation {
+
+  # ...
+
+  nativeCheckInputs = [
+    memcachedTestHook
+  ];
+
+  preCheck = ''
+    memcachedTestPort=1234
+  ''
+}

doc/hooks/redis-test-hook.section.md

@@ -0,0 +1,60 @@
+
+# `redisTestHook` {#sec-redisTestHook}
+
+This hook starts a Redis server during `checkPhase`. Example:
+
+```nix
+{
+  stdenv,
+  redis,
+  redisTestHook
+}:
+stdenv.mkDerivation {
+
+  # ...
+
+  nativeCheckInputs = [
+    redisTestHook
+  ];
+}
+```
+
+If you use a custom `checkPhase`, remember to add the `runHook` calls:
+```nix
+  checkPhase ''
+    runHook preCheck
+
+    # ... your tests
+
+    runHook postCheck
+  ''
+```
+
+## Variables {#sec-redisTestHook-variables}
+
+The hook logic will read the following variables and set them to a default value if unset or empty.
+
+Exported variables:
+
+- `REDIS_SOCKET`: UNIX domain socket path
+
+Bash-only variables:
+
+ - `redisTestPort`: Port to use by Redis. Defaults to `6379`
+
+Example usage:
+
+```nix
+{ stdenv, redis, redisTestHook }:
+stdenv.mkDerivation {
+
+  # ...
+
+  nativeCheckInputs = [
+    redisTestHook
+  ];
+
+  preCheck = ''
+    redisTestPort=6390
+  ''
+}

doc/hooks/waf.section.md

@@ -14,7 +14,7 @@ The variables below are exclusive of `wafHook`.
 
 Location of the `waf` tool. It defaults to `./waf`, to honor software projects that include it directly inside their source trees.
 
-If `wafPath` doesn't exist, then `wafHook` will copy the `waf` provided from Nixpkgs to it.
+If the file pointed by `wafPath` doesn't exist, then `waf` provided by Nixpkgs will be used.
 
 #### `wafFlags` {#waf-flags}
 

doc/languages-frameworks/python.section.md

@@ -1232,73 +1232,131 @@ test run would be:
 However, many repositories' test suites do not translate well to nix's build
 sandbox, and will generally need many tests to be disabled.
 
-To filter tests using pytest, one can do the following:
+This is achievable by
+- Including paths or test items (`path/to/file.py::MyClass` or `path/to/file.py::MyClass::test_method`) with positional arguments.
+- Excluding paths with `--ignore` or globbed paths with `--ignore-glob`.
+- Excluding test items using the `--deselect` flag.
+- Including or excluding classes or test methods by their name using the `-k` flag.
+- Including or excluding test by their marks using the `-m` flag.
 
-```nix
-{
-  nativeCheckInputs = [ pytest ];
-  # avoid tests which need additional data or touch network
-  checkPhase = ''
-    runHook preCheck
+We highly recommend `pytestCheckHook` for an easier and more structural setup.
 
-    pytest tests/ --ignore=tests/integration -k 'not download and not update' --ignore=tests/test_failing.py
+#### Using pytestCheckHook {#using-pytestcheckhook}
 
-    runHook postCheck
-  '';
+`pytestCheckHook` is a convenient hook which will set up (or configure)
+a [`checkPhase`](#ssec-check-phase) to run `pytest`. This is also beneficial
+when a package may need many items disabled to run the test suite.
+Most packages use `pytest` or `unittest`, which is compatible with `pytest`,
+so you will most likely use `pytestCheckHook`.
+
+To use `pytestCheckHook`, add it to `nativeCheckInputs`.
+Adding `pytest` is not required, since it is included with `pytestCheckHook`.
+
+```nix
+{
+  nativeCheckInputs = [
+    pytestCheckHook
+  ];
 }
 ```
 
-`--ignore` will tell pytest to ignore that file or directory from being
-collected as part of a test run. This is useful is a file uses a package
-which is not available in nixpkgs, thus skipping that test file is much
-easier than having to create a new package.
+`pytestCheckHook` recognizes the following attributes:
 
-`-k` is used to define a predicate for test names. In this example, we are
-filtering out tests which contain `download` or `update` in their test case name.
-Only one `-k` argument is allowed, and thus a long predicate should be concatenated
-with “\\” and wrapped to the next line.
+`enabledTestPaths` and `disabledTestPaths`
 
-::: {.note}
-In pytest==6.0.1, the use of “\\” to continue a line (e.g. `-k 'not download \'`) has
-been removed, in this case, it's recommended to use `pytestCheckHook`.
-:::
+:   To specify path globs (files or directories) or test items.
 
-#### Using pytestCheckHook {#using-pytestcheckhook}
+`enabledTests` and `disabledTests`
 
-`pytestCheckHook` is a convenient hook which will set up (or configure)
-a [`checkPhase`](#ssec-check-phase) to run `pytest`. This is also beneficial
-when a package may need many items disabled to run the test suite.
-Most packages use `pytest` or `unittest`, which is compatible with `pytest`,
-so you will most likely use `pytestCheckHook`.
+:   To specify keywords for class names or test method names.
+
+`enabledTestMarks` and `disabledTestMarks`
+
+:   To specify test marks.
 
-Using the example above, the analogous `pytestCheckHook` usage would be:
+`pytestFlags`
+
+:   To append additional command-line arguments to `pytest`.
+
+By default, `pytest` automatically discovers which tests to run.
+If tests are explicitly enabled, only those tests will run.
+A test, that is both enabled and disabled, will not run.
+
+The following example demonstrates usage of various `pytestCheckHook` attributes:
 
 ```nix
 {
   nativeCheckInputs = [
     pytestCheckHook
   ];
 
-  # requires additional data
-  pytestFlags = [
+  # Allow running the following test paths and test objects.
+  enabledTestPaths = [
+    # Find tests under the tests directory.
+    # The trailing slash is not necessary.
     "tests/"
-    "--ignore=tests/integration"
+
+    # Additionally run test_foo
+    "other-tests/test_foo.py::Foo::test_foo"
   ];
 
+  # Override the above-enabled test paths and test objects.
+  disabledTestPaths = [
+    # Tests under tests/integration requires additional data.
+    "tests/integration"
+  ];
+
+  # Allow tests by keywords matching their class names or method names.
+  enabledTests = [
+    # pytest by default only runs test methods begin with "test_" or end with "_test".
+    # This includes all functions whose name contains "test".
+    "test"
+  ];
+
+  # Override the above-enabled tests by keywords matching their class names or method names.
   disabledTests = [
-    # touches network
+    # Tests touching networks.
+    "upload"
     "download"
-    "update"
   ];
 
-  disabledTestPaths = [
-    "tests/test_failing.py"
+  # Additional pytest flags
+  pytestFlags = [
+    # Disable benchmarks and run benchmarking tests only once.
+    "--benchmark-disable"
+  ];
+}
+```
+
+These attributes are all passed into the derivation directly
+and added to the `pytest` command without additional Bash expansion.
+It requires `__structuredAttrs = true` to pass list elements containing spaces.
+
+The `<enabled/disabled>TestsPaths` attributes expand Unix-style globs.
+If a test path contains characters like `*`, `?`, `[`, or `]`, you can
+quote them with square brackets (`[*]`, `[?]`, `[[]`, and `[]]`) to match literally.
+
+The `<enabled/disabled>Tests` and `<enabled/disabled>TestMarks` attribute pairs
+form a logical expression `((included_element1) or (included_element2)) and not (excluded_element1) and not (excluded_element2)`
+which will be passed to pytest's `-k` and `-m` flags respectively.
+With `__structuredAttrs = true` enabled, they additionally support sub-expressions.
+
+For example, you could disable test items like `TestFoo::test_bar_functionality`
+by disabling tests that match both `"Foo"` **and** `"bar"`:
+
+```nix
+{
+  __structuredAttrs = true;
+
+  disabledTests = [
+    "Foo and bar"
   ];
 }
 ```
 
-This is especially useful when tests need to be conditionally disabled,
-for example:
+The main benefits of using `pytestCheckHook` to construct `pytest` commands
+is structuralization and eval-time accessibility.
+This is especially helpful to select tests or specify flags conditionally:
 
 ```nix
 {
@@ -1316,10 +1374,6 @@ for example:
 }
 ```
 
-Trying to concatenate the related strings to disable tests in a regular
-[`checkPhase`](#ssec-check-phase) would be much harder to read. This also enables us to comment on
-why specific tests are disabled.
-
 #### Using pythonImportsCheck {#using-pythonimportscheck}
 
 Although unit tests are highly preferred to validate correctness of a package, not
@@ -2007,36 +2061,6 @@ Occasionally packages don't make use of a common test framework, which may then
 
 #### Common issues {#common-issues}
 
-* Non-working tests can often be deselected. Most Python modules
-  do follow the standard test protocol where the pytest runner can be used.
-  `pytest` supports the `-k` and `--ignore-glob` parameters to ignore test
-  methods or classes as well as whole files. For `pytestCheckHook` these are
-  conveniently exposed as `disabledTests` and `disabledTestPaths` respectively.
-
-  ```nix
-  buildPythonPackage {
-    # ...
-    nativeCheckInputs = [
-      pytestCheckHook
-    ];
-
-    disabledTests = [
-      "function_name"
-      "other_function"
-    ];
-
-    disabledTestPaths = [
-      "path/to/performance.py"
-      "path/to/connect-*.py"
-    ];
-  }
-  ```
-
-  ::: {.note}
-  If the test path to disable contains characters like `*`, `?`, `[`, and `]`,
-  quote them with square brackets (`[*]`, `[?]`, `[[]`, and `[]]`) to match literally.
-  :::
-
 * Tests that attempt to access `$HOME` can be fixed by using the following
   work-around before running tests (e.g. `preCheck`): `export HOME=$(mktemp -d)`
 * Compiling with Cython causes tests to fail with a `ModuleNotLoadedError`.

doc/languages-frameworks/ruby.section.md

@@ -154,7 +154,7 @@ let
     defaultGemConfig = pkgs.defaultGemConfig // {
       pg = attrs: {
         buildFlags =
-        [ "--with-pg-config=${lib.getDev pkgs."postgresql_${pg_version}"}/bin/pg_config" ];
+        [ "--with-pg-config=${pkgs."postgresql_${pg_version}".pg_config}/bin/pg_config" ];
       };
     };
   };
@@ -172,7 +172,7 @@ let
     gemConfig = pkgs.defaultGemConfig // {
       pg = attrs: {
         buildFlags =
-        [ "--with-pg-config=${lib.getDev pkgs."postgresql_${pg_version}"}/bin/pg_config" ];
+        [ "--with-pg-config=${pkgs."postgresql_${pg_version}".pg_config}/bin/pg_config" ];
       };
     };
   };
@@ -190,7 +190,7 @@ let
         defaultGemConfig = super.defaultGemConfig // {
           pg = attrs: {
             buildFlags = [
-              "--with-pg-config=${lib.getDev pkgs."postgresql_${pg_version}"}/bin/pg_config"
+              "--with-pg-config=${pkgs."postgresql_${pg_version}".pg_config}/bin/pg_config"
             ];
           };
         };

doc/manpage-urls.json

@@ -228,6 +228,8 @@
   "systemd-socket-activate(1)": "https://www.freedesktop.org/software/systemd/man/systemd-socket-activate.html",
   "systemd-socket-proxyd(8)": "https://www.freedesktop.org/software/systemd/man/systemd-socket-proxyd.html",
   "systemd-soft-reboot.service(8)": "https://www.freedesktop.org/software/systemd/man/systemd-soft-reboot.service.html",
+  "systemd-ssh-generator(8)": "https://www.freedesktop.org/software/systemd/man/systemd-ssh-generator.html",
+  "systemd-ssh-proxy(1)": "https://www.freedesktop.org/software/systemd/man/systemd-ssh-proxy.html",
   "systemd-stdio-bridge(1)": "https://www.freedesktop.org/software/systemd/man/systemd-stdio-bridge.html",
   "systemd-stub(7)": "https://www.freedesktop.org/software/systemd/man/systemd-stub.html",
   "systemd-suspend-then-hibernate.service(8)": "https://www.freedesktop.org/software/systemd/man/systemd-suspend-then-hibernate.service.html",

doc/packages/index.md

@@ -24,6 +24,7 @@ etc-files.section.md
 nginx.section.md
 opengl.section.md
 shell-helpers.section.md
+python-tree-sitter.section.md
 steam.section.md
 cataclysm-dda.section.md
 urxvt.section.md