Merge branch 'nixos-unstable-small' of https://github.com/NixOS/nixpkgs

4 files changed, 95 insertions, 80 deletions

diff --git a/nixpkgs/doc/build-helpers/images/dockertools.section.md b/nixpkgs/doc/build-helpers/images/dockertools.section.md
index 9317146b8f94..a1d1f2cb2012 100644
--- a/nixpkgs/doc/build-helpers/images/dockertools.section.md
+++ b/nixpkgs/doc/build-helpers/images/dockertools.section.md
@@ -6,7 +6,7 @@ Docker itself is not used to perform any of the operations done by these functio
 ## buildImage {#ssec-pkgs-dockerTools-buildImage}
 
 This function builds a Docker-compatible repository tarball containing a single image.
-As such, the result is suitable for being loaded in Docker with `docker load` (see [](#ex-dockerTools-buildImage) for how to do this).
+As such, the result is suitable for being loaded in Docker with `docker image load` (see [](#ex-dockerTools-buildImage) for how to do this).
 
 This function will create a single layer for all files (and dependencies) that are specified in its argument.
 Only new dependencies that are not already in the existing layers will be copied.
@@ -43,7 +43,7 @@ Similarly, if you encounter errors similar to `Error_Protocol ("certificate has
 `fromImage` (Path or Null; _optional_)
 
 : The repository tarball of an image to be used as the base for the generated image.
-  It must be a valid Docker image, such as one exported by `docker save`, or another image built with the `dockerTools` utility functions.
+  It must be a valid Docker image, such as one exported by `docker image save`, or another image built with the `dockerTools` utility functions.
   This can be seen as an equivalent of `FROM fromImage` in a `Dockerfile`.
   A value of `null` can be seen as an equivalent of `FROM scratch`.
 
@@ -123,7 +123,7 @@ Similarly, if you encounter errors similar to `Error_Protocol ("certificate has
 
   _Default value:_ `""`.
 
-`config` (Attribute Set; _optional_)
+`config` (Attribute Set or Null; _optional_)
 
 : Used to specify the configuration of the containers that will be started off the generated image.
   Must be an attribute set, with each attribute as listed in the [Docker Image Specification v1.3.0](https://github.com/moby/moby/blob/46f7ab808b9504d735d600e259ca0723f76fb164/image/spec/spec.md#image-json-field-descriptions).
@@ -178,6 +178,13 @@ Similarly, if you encounter errors similar to `Error_Protocol ("certificate has
 
   _Default value:_ 0.
 
+`compressor` (String; _optional_)
+
+: Selects the algorithm used to compress the image.
+
+  _Default value:_ `"gz"`.\
+  _Possible values:_ `"none"`, `"gz"`, `"zstd"`.
+
 `contents` **DEPRECATED**
 
 : This attribute is deprecated, and users are encouraged to use `copyToRoot` instead.
@@ -247,7 +254,7 @@ Cooking the image...
 Finished.
 /nix/store/p4dsg62inh9d2ksy3c7bv58xa851dasr-docker-image-redis.tar.gz
 
-$ docker load -i /nix/store/p4dsg62inh9d2ksy3c7bv58xa851dasr-docker-image-redis.tar.gz
+$ docker image load -i /nix/store/p4dsg62inh9d2ksy3c7bv58xa851dasr-docker-image-redis.tar.gz
 (some output removed for clarity)
 Loaded image: redis:latest
 ```
@@ -345,8 +352,8 @@ dockerTools.buildImage {
 
 After importing the generated repository tarball with Docker, its CLI will display a reasonable date and sort the images as expected:
 
-```ShellSession
-$ docker images
+```shell
+$ docker image ls
 REPOSITORY   TAG      IMAGE ID       CREATED              SIZE
 hello        latest   de2bf4786de6   About a minute ago   25.2MB
 ```
@@ -364,7 +371,7 @@ Despite the similar name, [`buildImage`](#ssec-pkgs-dockerTools-buildImage) work
 Even though some of the arguments may seem related, they cannot be interchanged.
 :::
 
-You can use this function to load an image in Docker with `docker load`.
+You can load the result of this function in Docker with `docker image load`.
 See [](#ex-dockerTools-buildLayeredImage-hello) to see how to do that.
 
 ### Examples {#ssec-pkgs-dockerTools-buildLayeredImage-examples}
@@ -404,7 +411,7 @@ Adding manifests...
 Done.
 /nix/store/hxcz7snvw7f8rzhbh6mv8jq39d992905-hello.tar.gz
 
-$ docker load -i /nix/store/hxcz7snvw7f8rzhbh6mv8jq39d992905-hello.tar.gz
+$ docker image load -i /nix/store/hxcz7snvw7f8rzhbh6mv8jq39d992905-hello.tar.gz
 (some output removed for clarity)
 Loaded image: hello:latest
 ```
@@ -415,7 +422,7 @@ Loaded image: hello:latest
 `streamLayeredImage` builds a **script** which, when run, will stream to stdout a Docker-compatible repository tarball containing a single image, using multiple layers to improve sharing between images.
 This means that `streamLayeredImage` does not output an image into the Nix store, but only a script that builds the image, saving on IO and disk/cache space, particularly with large images.
 
-You can use this function to load an image in Docker with `docker load`.
+You can load the result of this function in Docker with `docker image load`.
 See [](#ex-dockerTools-streamLayeredImage-hello) to see how to do that.
 
 For this function, you specify a [store path](https://nixos.org/manual/nix/stable/store/store-path) or a list of store paths to be added to the image, and the functions will automatically include any dependencies of those paths in the image.
@@ -440,7 +447,7 @@ This allows the function to produce reproducible images.
 
 : The name of the generated image.
 
-`tag` (String; _optional_)
+`tag` (String or Null; _optional_)
 
 : Tag of the generated image.
   If `null`, the hash of the nix derivation will be used as the tag.
@@ -450,7 +457,7 @@ This allows the function to produce reproducible images.
 `fromImage`(Path or Null; _optional_)
 
 : The repository tarball of an image to be used as the base for the generated image.
-  It must be a valid Docker image, such as one exported by `docker save`, or another image built with the `dockerTools` utility functions.
+  It must be a valid Docker image, such as one exported by `docker image save`, or another image built with the `dockerTools` utility functions.
   This can be seen as an equivalent of `FROM fromImage` in a `Dockerfile`.
   A value of `null` can be seen as an equivalent of `FROM scratch`.
 
@@ -470,7 +477,7 @@ This allows the function to produce reproducible images.
 
   _Default value:_ `[]`
 
-`config` (Attribute Set; _optional_) []{#dockerTools-buildLayeredImage-arg-config}
+`config` (Attribute Set or Null; _optional_) []{#dockerTools-buildLayeredImage-arg-config}
 
 : Used to specify the configuration of the containers that will be started off the generated image.
   Must be an attribute set, with each attribute as listed in the [Docker Image Specification v1.3.0](https://github.com/moby/moby/blob/46f7ab808b9504d735d600e259ca0723f76fb164/image/spec/spec.md#image-json-field-descriptions).
@@ -594,7 +601,7 @@ dockerTools.streamLayeredImage {
 ```
 
 The result of building this package is a script.
-Running this script and piping it into `docker load` gives you the same image that was built in [](#ex-dockerTools-buildLayeredImage-hello).
+Running this script and piping it into `docker image load` gives you the same image that was built in [](#ex-dockerTools-buildLayeredImage-hello).
 Note that in this case, the image is never added to the Nix store, but instead streamed directly into Docker.
 
 ```shell
@@ -602,7 +609,7 @@ $ nix-build
 (output removed for clarity)
 /nix/store/wsz2xl8ckxnlb769irvq6jv1280dfvxd-stream-hello
 
-$ /nix/store/wsz2xl8ckxnlb769irvq6jv1280dfvxd-stream-hello | docker load
+$ /nix/store/wsz2xl8ckxnlb769irvq6jv1280dfvxd-stream-hello | docker image load
 No 'fromImage' provided
 Creating layer 1 from paths: ['/nix/store/i93s7xxblavsacpy82zdbn4kplsyq48l-libunistring-1.1']
 Creating layer 2 from paths: ['/nix/store/ji01n9vinnj22nbrb86nx8a1ssgpilx8-libidn2-2.3.4']
@@ -718,7 +725,7 @@ dockerTools.streamLayeredImage {
 []{#ssec-pkgs-dockerTools-fetchFromRegistry}
 ## pullImage {#ssec-pkgs-dockerTools-pullImage}
 
-This function is similar to the `docker pull` command, which means it can be used to pull a Docker image from a registry that implements the [Docker Registry HTTP API V2](https://distribution.github.io/distribution/spec/api/).
+This function is similar to the `docker image pull` command, which means it can be used to pull a Docker image from a registry that implements the [Docker Registry HTTP API V2](https://distribution.github.io/distribution/spec/api/).
 By default, the `docker.io` registry is used.
 
 The image will be downloaded as an uncompressed Docker-compatible repository tarball, which is suitable for use with other `dockerTools` functions such as [`buildImage`](#ssec-pkgs-dockerTools-buildImage), [`buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage), and [`streamLayeredImage`](#ssec-pkgs-dockerTools-streamLayeredImage).
@@ -1105,7 +1112,7 @@ This is currently implemented by linking to the `env` binary from the `coreutils
 ### binSh {#sssec-pkgs-dockerTools-helpers-binSh}
 
 This provides a `/bin/sh` link to the `bash` binary from the `bashInteractive` package.
-Because of this, it supports cases such as running a command interactively in a container (for example by running `docker run -it <image_name>`).
+Because of this, it supports cases such as running a command interactively in a container (for example by running `docker container run -it <image_name>`).
 
 ### caCertificates {#sssec-pkgs-dockerTools-helpers-caCertificates}
 
@@ -1169,9 +1176,9 @@ This is made possible by `binSh`.
 $ nix-build
 (some output removed for clarity)
 /nix/store/2p0i3i04cgjlk71hsn7ll4kxaxxiv4qg-docker-image-env-helpers.tar.gz
-$ docker load -i /nix/store/2p0i3i04cgjlk71hsn7ll4kxaxxiv4qg-docker-image-env-helpers.tar.gz
+$ docker image load -i /nix/store/2p0i3i04cgjlk71hsn7ll4kxaxxiv4qg-docker-image-env-helpers.tar.gz
 (output removed for clarity)
-$ docker run --rm -it env-helpers:latest /bin/sh
+$ docker container run --rm -it env-helpers:latest /bin/sh
 sh-5.2# help
 GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)
 (rest of output removed for clarity)
@@ -1209,9 +1216,9 @@ This is made possible by `binSh`.
 $ nix-build
 (some output removed for clarity)
 /nix/store/rpf47f4z5b9qr4db4ach9yr4b85hjhxq-env-helpers.tar.gz
-$ docker load -i /nix/store/rpf47f4z5b9qr4db4ach9yr4b85hjhxq-env-helpers.tar.gz
+$ docker image load -i /nix/store/rpf47f4z5b9qr4db4ach9yr4b85hjhxq-env-helpers.tar.gz
 (output removed for clarity)
-$ docker run --rm -it env-helpers:latest /bin/sh
+$ docker container run --rm -it env-helpers:latest /bin/sh
 sh-5.2# help
 GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)
 (rest of output removed for clarity)
@@ -1315,7 +1322,7 @@ $ nix-build
 (some output removed for clarity)
 /nix/store/pkj1sgzaz31wl0pbvbg3yp5b3kxndqms-hello-2.12.1-env.tar.gz
 
-$ docker load -i /nix/store/pkj1sgzaz31wl0pbvbg3yp5b3kxndqms-hello-2.12.1-env.tar.gz
+$ docker image load -i /nix/store/pkj1sgzaz31wl0pbvbg3yp5b3kxndqms-hello-2.12.1-env.tar.gz
 (some output removed for clarity)
 Loaded image: hello-2.12.1-env:latest
 ```
@@ -1323,7 +1330,7 @@ Loaded image: hello-2.12.1-env:latest
 After starting an interactive container, the derivation can be built by running `buildDerivation`, and the output can be executed as expected:
 
 ```shell
-$ docker run -it hello-2.12.1-env:latest
+$ docker container run -it hello-2.12.1-env:latest
 [nix-shell:~]$ buildDerivation
 Running phase: unpackPhase
 unpacking source archive /nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz
@@ -1443,14 +1450,14 @@ dockerTools.streamNixShellImage {
 ```
 
 The result of building this package is a script.
-Running this script and piping it into `docker load` gives you the same image that was built in [](#ex-dockerTools-buildNixShellImage-hello).
+Running this script and piping it into `docker image load` gives you the same image that was built in [](#ex-dockerTools-buildNixShellImage-hello).
 
 ```shell
 $ nix-build
 (some output removed for clarity)
 /nix/store/8vhznpz2frqazxnd8pgdvf38jscdypax-stream-hello-2.12.1-env
 
-$ /nix/store/8vhznpz2frqazxnd8pgdvf38jscdypax-stream-hello-2.12.1-env | docker load
+$ /nix/store/8vhznpz2frqazxnd8pgdvf38jscdypax-stream-hello-2.12.1-env | docker image load
 (some output removed for clarity)
 Loaded image: hello-2.12.1-env:latest
 ```
@@ -1458,7 +1465,7 @@ Loaded image: hello-2.12.1-env:latest
 After starting an interactive container, the derivation can be built by running `buildDerivation`, and the output can be executed as expected:
 
 ```shell
-$ docker run -it hello-2.12.1-env:latest
+$ docker container run -it hello-2.12.1-env:latest
 [nix-shell:~]$ buildDerivation
 Running phase: unpackPhase
 unpacking source archive /nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz
@@ -1497,14 +1504,14 @@ dockerTools.streamNixShellImage {
 }
 ```
 
-The result of building this package is a script which can be run and piped into `docker load` to load the generated image.
+The result of building this package is a script which can be run and piped into `docker image load` to load the generated image.
 
 ```shell
 $ nix-build
 (some output removed for clarity)
 /nix/store/h5abh0vljgzg381lna922gqknx6yc0v7-stream-hello-2.12.1-env
 
-$ /nix/store/h5abh0vljgzg381lna922gqknx6yc0v7-stream-hello-2.12.1-env | docker load
+$ /nix/store/h5abh0vljgzg381lna922gqknx6yc0v7-stream-hello-2.12.1-env | docker image load
 (some output removed for clarity)
 Loaded image: hello-2.12.1-env:latest
 ```
@@ -1512,7 +1519,7 @@ Loaded image: hello-2.12.1-env:latest
 After starting an interactive container, we can verify the extra package is available by running `cowsay`:
 
 ```shell
-$ docker run -it hello-2.12.1-env:latest
+$ docker container run -it hello-2.12.1-env:latest
 [nix-shell:~]$ cowsay "Hello, world!"
  _______________
 < Hello, world! >
@@ -1546,14 +1553,14 @@ dockerTools.streamNixShellImage {
 }
 ```
 
-The result of building this package is a script which can be run and piped into `docker load` to load the generated image.
+The result of building this package is a script which can be run and piped into `docker image load` to load the generated image.
 
 ```shell
 $ nix-build
 (some output removed for clarity)
 /nix/store/iz4dhdvgzazl5vrgyz719iwjzjy6xlx1-stream-hello-2.12.1-env
 
-$ /nix/store/iz4dhdvgzazl5vrgyz719iwjzjy6xlx1-stream-hello-2.12.1-env | docker load
+$ /nix/store/iz4dhdvgzazl5vrgyz719iwjzjy6xlx1-stream-hello-2.12.1-env | docker image load
 (some output removed for clarity)
 Loaded image: hello-2.12.1-env:latest
 ```
@@ -1561,7 +1568,7 @@ Loaded image: hello-2.12.1-env:latest
 After starting an interactive container, we can see the result of the `shellHook`:
 
 ```shell
-$ docker run -it hello-2.12.1-env:latest
+$ docker container run -it hello-2.12.1-env:latest
 Hello, world!
 
 [nix-shell:~]$
diff --git a/nixpkgs/doc/languages-frameworks/python.section.md b/nixpkgs/doc/languages-frameworks/python.section.md
index 0849aacdf166..da06fe1d69b5 100644
--- a/nixpkgs/doc/languages-frameworks/python.section.md
+++ b/nixpkgs/doc/languages-frameworks/python.section.md
@@ -116,11 +116,11 @@ buildPythonPackage rec {
     rm testing/test_argcomplete.py
   '';
 
-  nativeBuildInputs = [
+  build-system = [
     setuptools-scm
   ];
 
-  propagatedBuildInputs = [
+  dependencies = [
     attrs
     py
     setuptools
@@ -172,7 +172,7 @@ following are specific to `buildPythonPackage`:
   variable in wrapped programs.
 * `pyproject`: Whether the pyproject format should be used. When set to `true`,
   `pypaBuildHook` will be used, and you can add the required build dependencies
-  from `build-system.requires` to `nativeBuildInputs`. Note that the pyproject
+  from `build-system.requires` to `build-system`. Note that the pyproject
   format falls back to using `setuptools`, so you can use `pyproject = true`
   even if the package only has a `setup.py`. When set to `false`, you can
   use the existing [hooks](#setup-hooks0 or provide your own logic to build the
@@ -206,17 +206,22 @@ build inputs (see "Specifying dependencies"). The following are of special
 interest for Python packages, either because these are primarily used, or
 because their behaviour is different:
 
-* `nativeBuildInputs ? []`: Build-time only dependencies. Typically executables
-  as well as the items listed in `setup_requires`.
+* `nativeBuildInputs ? []`: Build-time only dependencies. Typically executables.
+* `build-system ? []`: Build-time only Python dependencies. Items listed in `build-system.requires`/`setup_requires`.
 * `buildInputs ? []`: Build and/or run-time dependencies that need to be
   compiled for the host machine. Typically non-Python libraries which are being
   linked.
 * `nativeCheckInputs ? []`: Dependencies needed for running the [`checkPhase`](#ssec-check-phase). These
   are added to [`nativeBuildInputs`](#var-stdenv-nativeBuildInputs) when [`doCheck = true`](#var-stdenv-doCheck). Items listed in
   `tests_require` go here.
-* `propagatedBuildInputs ? []`: Aside from propagating dependencies,
+* `dependencies ? []`: Aside from propagating dependencies,
   `buildPythonPackage` also injects code into and wraps executables with the
   paths included in this list. Items listed in `install_requires` go here.
+* `optional-dependencies ? { }`: Optional feature flagged dependencies.  Items listed in `extras_requires` go here.
+
+Aside from propagating dependencies,
+  `buildPythonPackage` also injects code into and wraps executables with the
+  paths included in this list. Items listed in `extras_requires` go here.
 
 ##### Overriding Python packages {#overriding-python-packages}
 
@@ -299,11 +304,12 @@ python3Packages.buildPythonApplication rec {
     hash  = "sha256-Pe229rT0aHwA98s+nTHQMEFKZPo/yw6sot8MivFDvAw=";
   };
 
-  nativeBuildInputs = with python3Packages; [
+  build-system = with python3Packages; [
     setuptools
+    wheel
   ];
 
-  propagatedBuildInputs = with python3Packages; [
+  dependencies = with python3Packages; [
     tornado
     python-daemon
   ];
@@ -462,11 +468,11 @@ are used in [`buildPythonPackage`](#buildpythonpackage-function).
 - `eggBuildHook` to skip building for eggs.
 - `eggInstallHook` to install eggs.
 - `pipBuildHook` to build a wheel using `pip` and PEP 517. Note a build system
-  (e.g. `setuptools` or `flit`) should still be added as `nativeBuildInput`.
+  (e.g. `setuptools` or `flit`) should still be added as `build-system`.
 - `pypaBuildHook` to build a wheel using
   [`pypa/build`](https://pypa-build.readthedocs.io/en/latest/index.html) and
   PEP 517/518. Note a build system (e.g. `setuptools` or `flit`) should still
-  be added as `nativeBuildInput`.
+  be added as `build-system`.
 - `pipInstallHook` to install wheels.
 - `pytestCheckHook` to run tests with `pytest`. See [example usage](#using-pytestcheckhook).
 - `pythonCatchConflictsHook` to check whether a Python package is not already existing.
@@ -881,7 +887,7 @@ buildPythonPackage rec {
     hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
   };
 
-  nativeBuildInputs = [
+  build-system = [
     setuptools
     wheel
   ];
@@ -941,7 +947,7 @@ with import <nixpkgs> {};
         hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
       };
 
-      nativeBuildInputs = [
+      build-system = [
         python311.pkgs.setuptools
         python311.pkgs.wheel
       ];
@@ -977,13 +983,15 @@ that we introduced with the `let` expression.
 
 #### Handling dependencies {#handling-dependencies}
 
-Our example, `toolz`, does not have any dependencies on other Python packages or
-system libraries. According to the manual, [`buildPythonPackage`](#buildpythonpackage-function) uses the
-arguments [`buildInputs`](#var-stdenv-buildInputs) and [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs) to specify dependencies. If
-something is exclusively a build-time dependency, then the dependency should be
-included in [`buildInputs`](#var-stdenv-buildInputs), but if it is (also) a runtime dependency, then it
-should be added to [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs). Test dependencies are considered
-build-time dependencies and passed to [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs).
+Our example, `toolz`, does not have any dependencies on other Python packages or system libraries.
+[`buildPythonPackage`](#buildpythonpackage-function) uses the the following arguments in the following circumstances:
+
+- `dependencies` - For Python runtime dependencies.
+- `build-system` - For Python build-time requirements.
+- [`buildInputs`](#var-stdenv-buildInputs) - For non-Python build-time requirements.
+- [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs) - For test dependencies
+
+Dependencies can belong to multiple arguments, for example if something is both a build time requirement & a runtime dependency.
 
 The following example shows which arguments are given to [`buildPythonPackage`](#buildpythonpackage-function) in
 order to build [`datashape`](https://github.com/blaze/datashape).
@@ -1013,12 +1021,12 @@ buildPythonPackage rec {
     hash = "sha256-FLLvdm1MllKrgTGC6Gb0k0deZeVYvtCCLji/B7uhong=";
   };
 
-  nativeBuildInputs = [
+  build-system = [
     setuptools
     wheel
   ];
 
-  propagatedBuildInputs = [
+  dependencies = [
     multipledispatch
     numpy
     python-dateutil
@@ -1041,7 +1049,7 @@ buildPythonPackage rec {
 We can see several runtime dependencies, `numpy`, `multipledispatch`, and
 `python-dateutil`. Furthermore, we have [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs) with `pytest`.
 `pytest` is a test runner and is only used during the [`checkPhase`](#ssec-check-phase) and is
-therefore not added to [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs).
+therefore not added to `dependencies`.
 
 In the previous case we had only dependencies on other Python packages to consider.
 Occasionally you have also system libraries to consider. E.g., `lxml` provides
@@ -1068,7 +1076,7 @@ buildPythonPackage rec {
     hash = "sha256-s9NiusRxFydHzaNRMjjxFcvWxfi45jGb9ql6eJJyQJk=";
   };
 
-  nativeBuildInputs = [
+  build-system = [
     setuptools
     wheel
   ];
@@ -1125,7 +1133,7 @@ buildPythonPackage rec {
     hash = "sha256-9ru2r6kwhUCaskiFoaPNuJCfCVoUL01J40byvRt4kHQ=";
   };
 
-  nativeBuildInputs = [
+  build-system = [
     setuptools
     wheel
   ];
@@ -1136,7 +1144,7 @@ buildPythonPackage rec {
     fftwLongDouble
   ];
 
-  propagatedBuildInputs = [
+  dependencies = [
     numpy
     scipy
   ];
@@ -1459,9 +1467,7 @@ mode is activated.
 
 In the following example, we create a simple environment that has a Python 3.11
 version of our package in it, as well as its dependencies and other packages we
-like to have in the environment, all specified with [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs).
-Indeed, we can just add any package we like to have in our environment to
-[`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs).
+like to have in the environment, all specified with `dependencies`.
 
 ```nix
 with import <nixpkgs> {};
@@ -1470,9 +1476,11 @@ with python311Packages;
 buildPythonPackage rec {
   name = "mypackage";
   src = ./path/to/package/source;
-  propagatedBuildInputs = [
+  dependencies = [
     pytest
     numpy
+  ];
+  propagatedBuildInputs = [
     pkgs.libsndfile
   ];
 }
@@ -1519,7 +1527,7 @@ buildPythonPackage rec {
     hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
   };
 
-  nativeBuildInputs = [
+  build-system = [
     setuptools
     wheel
   ];
@@ -1903,8 +1911,8 @@ configure alternatives](#sec-overlays-alternatives-blas-lapack)".
 
 In a `setup.py` or `setup.cfg` it is common to declare dependencies:
 
-* `setup_requires` corresponds to [`nativeBuildInputs`](#var-stdenv-nativeBuildInputs)
-* `install_requires` corresponds to [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs)
+* `setup_requires` corresponds to `build-system`
+* `install_requires` corresponds to `dependencies`
 * `tests_require` corresponds to [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs)
 
 ### How to enable interpreter optimizations? {#optimizations}
@@ -1928,12 +1936,10 @@ in mypython
 
 Some packages define optional dependencies for additional features. With
 `setuptools` this is called `extras_require` and `flit` calls it
-`extras-require`, while PEP 621 calls these `optional-dependencies`. A
-method for supporting this is by declaring the extras of a package in its
-`passthru`, e.g. in case of the package `dask`
+`extras-require`, while PEP 621 calls these `optional-dependencies`.
 
 ```nix
-passthru.optional-dependencies = {
+optional-dependencies = {
   complete = [ distributed ];
 };
 ```
@@ -1941,11 +1947,13 @@ passthru.optional-dependencies = {
 and letting the package requiring the extra add the list to its dependencies
 
 ```nix
-propagatedBuildInputs = [
+dependencies = [
   ...
 ] ++ dask.optional-dependencies.complete;
 ```
 
+This method is using `passthru`, meaning that changing `optional-dependencies` of a package won't cause it to rebuild.
+
 Note this method is preferred over adding parameters to builders, as that can
 result in packages depending on different variants and thereby causing
 collisions.
diff --git a/nixpkgs/doc/languages-frameworks/rust.section.md b/nixpkgs/doc/languages-frameworks/rust.section.md
index 72bade25a9fb..76ac7b6cb2d2 100644
--- a/nixpkgs/doc/languages-frameworks/rust.section.md
+++ b/nixpkgs/doc/languages-frameworks/rust.section.md
@@ -44,11 +44,11 @@ rustPlatform.buildRustPackage rec {
 }
 ```
 
-`buildRustPackage` requires either the `cargoHash` or the `cargoSha256`
-attribute which is computed over all crate sources of this package.
-`cargoSha256` is used for traditional Nix SHA-256 hashes. `cargoHash` should
-instead be used for [SRI](https://www.w3.org/TR/SRI/) hashes and should be
-preferred. For example:
+`buildRustPackage` requires either a `cargoHash` (preferred) or a
+`cargoSha256` attribute, computed over all crate sources of this package.
+`cargoHash` supports [SRI](https://www.w3.org/TR/SRI/) hashes and should be
+preferred over `cargoSha256` which was used for traditional Nix SHA-256 hashes.
+For example:
 
 ```nix
   cargoHash = "sha256-l1vL2ZdtDRxSGvP0X/l3nMw8+6WF67KPutJEzUROjg8=";
@@ -64,16 +64,16 @@ Both types of hashes are permitted when contributing to nixpkgs. The
 Cargo hash is obtained by inserting a fake checksum into the
 expression and building the package once. The correct checksum can
 then be taken from the failed build. A fake hash can be used for
-`cargoSha256` as follows:
+`cargoHash` as follows:
 
 ```nix
-  cargoSha256 = lib.fakeSha256;
+  cargoHash = lib.fakeHash;
 ```
 
-For `cargoHash` you can use:
+For `cargoSha256` you can use:
 
 ```nix
-  cargoHash = lib.fakeHash;
+  cargoSha256 = lib.fakeSha256;
 ```
 
 Per the instructions in the [Cargo Book](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)
@@ -90,7 +90,7 @@ directory into a tar.gz archive.
 The tarball with vendored dependencies contains a directory with the
 package's `name`, which is normally composed of `pname` and
 `version`. This means that the vendored dependencies hash
-(`cargoSha256`/`cargoHash`) is dependent on the package name and
+(`cargoHash`/`cargoSha256`) is dependent on the package name and
 version. The `cargoDepsName` attribute can be used to use another name
 for the directory of vendored dependencies. For example, the hash can
 be made invariant to the version by setting `cargoDepsName` to
@@ -115,7 +115,7 @@ rustPlatform.buildRustPackage rec {
 
 ### Importing a `Cargo.lock` file {#importing-a-cargo.lock-file}
 
-Using `cargoSha256` or `cargoHash` is tedious when using
+Using a vendored hash (`cargoHash`/`cargoSha256`) is tedious when using
 `buildRustPackage` within a project, since it requires that the hash
 is updated after every change to `Cargo.lock`. Therefore,
 `buildRustPackage` also supports vendoring dependencies directly from
diff --git a/nixpkgs/doc/packages/darwin-builder.section.md b/nixpkgs/doc/packages/darwin-builder.section.md
index 0c5323705345..bf6ef906ca5a 100644
--- a/nixpkgs/doc/packages/darwin-builder.section.md
+++ b/nixpkgs/doc/packages/darwin-builder.section.md
@@ -98,7 +98,7 @@ $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
             host.pkgs = pkgs;
             darwin-builder.workingDirectory = "/var/lib/darwin-builder";
           };
-        };
+        }
       ];
     };
   in {