doc: cleanup (#400164)

doc/build-helpers/images/appimagetools.section.md

@@ -33,7 +33,7 @@ let
   version = "0.6.30";
 
   src = fetchurl {
-    url = "https://github.com/nukeop/nuclear/releases/download/v${version}/${pname}-v${version}.AppImage";
+    url = "https://github.com/nukeop/nuclear/releases/download/v${version}/nuclear-v${version}.AppImage";
     hash = "sha256-he1uGC1M/nFcKpMM9JKY4oeexJcnzV0ZRxhTjtJz6xw=";
   };
 in

doc/doc-support/package.nix

@@ -49,6 +49,8 @@ stdenvNoCC.mkDerivation (
     '';
 
     buildPhase = ''
+      runHook preBuild
+
       substituteInPlace ./languages-frameworks/python.section.md \
         --subst-var-by python-interpreter-table "$(<"${pythonInterpreterTable}")"
 
@@ -84,9 +86,13 @@ stdenvNoCC.mkDerivation (
         --section-toc-depth 1 \
         manual.md \
         out/index.html
+
+      runHook postBuild
     '';
 
     installPhase = ''
+      runHook preInstall
+
       dest="$out/share/doc/nixpkgs"
       mkdir -p "$(dirname "$dest")"
       mv out "$dest"
@@ -97,6 +103,8 @@ stdenvNoCC.mkDerivation (
       mkdir -p $out/nix-support/
       echo "doc manual $dest manual.html" >> $out/nix-support/hydra-build-products
       echo "doc manual $dest nixpkgs-manual.epub" >> $out/nix-support/hydra-build-products
+
+      runHook postInstall
     '';
 
     passthru = {

doc/functions/generators.section.md

@@ -27,8 +27,8 @@ let
     } ":";
   };
 
-  # the INI file can now be given as plain old nix values
 in
+# the INI file can now be given as plain old nix values
 customToINI {
   main = {
     pushinfo = true;

doc/hooks/tauri.section.md

@@ -23,15 +23,15 @@ In Nixpkgs, `cargo-tauri.hook` overrides the default build and install phases.
   wrapGAppsHook4,
 }:
 
-rustPlatform.buildRustPackage rec {
+rustPlatform.buildRustPackage (finalAttrs: {
-  # . . .
+  # ...
 
   useFetchCargoVendor = true;
   cargoHash = "...";
 
   # Assuming our app's frontend uses `npm` as a package manager
   npmDeps = fetchNpmDeps {
-    name = "${pname}-npm-deps-${version}";
+    name = "${finalAttrs.pname}-npm-deps-${finalAttrs.version}";
     inherit src;
     hash = "...";
   };
@@ -61,8 +61,8 @@ rustPlatform.buildRustPackage rec {
   # And make sure we build there too
   buildAndTestSubdir = cargoRoot;
 
-  # . . .
+  # ...
-}
+})
 ```
 
 ## Variables controlling cargo-tauri {#tauri-hook-variables-controlling}

doc/languages-frameworks/agda.section.md

@@ -208,8 +208,12 @@ mkDerivation {
   libraryName = "IAL-1.3";
 
   buildPhase = ''
+    runHook preBuild
+
     patchShebangs find-deps.sh
     make
+
+    runHook postBuild
   '';
 }
 ```

doc/languages-frameworks/bower.section.md

@@ -105,10 +105,17 @@ pkgs.stdenv.mkDerivation {
     src = myWebApp;
   };
 
+  nativeBuildInputs = [
+    writableTmpDirAsHomeHook # note 3
+  ];
+
   buildPhase = ''
+    runHook preBuild
+
     cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . # note 2
-    export HOME=$PWD # note 3
     ${pkgs.nodePackages.gulp}/bin/gulp build # note 4
+
+    runHook postBuild
   '';
 
   installPhase = "mv gulpdist $out";

doc/languages-frameworks/dart.section.md

@@ -42,8 +42,8 @@ buildDartApplication rec {
 
   src = fetchFromGitHub {
     owner = "sass";
-    repo = pname;
+    repo = "dart-sass";
-    rev = version;
+    tag = version;
     hash = "sha256-U6enz8yJcc4Wf8m54eYIAnVg/jsGi247Wy8lp1r1wg4=";
   };
 

doc/languages-frameworks/dlang.section.md

@@ -22,7 +22,7 @@ buildDubPackage rec {
   src = fetchFromGitHub {
     owner = "CyberShadow";
     repo = "btdu";
-    rev = "v${version}";
+    tag = "v${version}";
     hash = "sha256-3sSZq+5UJH02IO0Y1yL3BLHDb4lk8k6awb5ZysBQciE=";
   };
 

doc/languages-frameworks/emscripten.section.md

@@ -41,12 +41,13 @@ One advantage is that when `pkgs.zlib` is updated, it will automatically update
 (pkgs.zlib.override {
   stdenv = pkgs.emscriptenStdenv;
 }).overrideAttrs
-  (old: rec {
+  (old: {
     buildInputs = old.buildInputs ++ [ pkg-config ];
     # we need to reset this setting!
     env = (old.env or { }) // {
       NIX_CFLAGS_COMPILE = "";
     };
+
     configurePhase = ''
       # FIXME: Some tests require writing at $HOME
       HOME=$TMPDIR
@@ -57,15 +58,29 @@ One advantage is that when `pkgs.zlib` is updated, it will automatically update
 
       runHook postConfigure
     '';
+
     dontStrip = true;
     outputs = [ "out" ];
+
     buildPhase = ''
+      runHook preBuild
+
       emmake make
+
+      runHook postBuild
     '';
+
     installPhase = ''
+      runHook preInstall
+
       emmake make install
+
+      runHook postInstall
     '';
+
     checkPhase = ''
+      runHook preCheck
+
       echo "================= testing zlib using node ================="
 
       echo "Compiling a custom test"
@@ -84,6 +99,8 @@ One advantage is that when `pkgs.zlib` is updated, it will automatically update
         echo "it seems to work! very good."
       fi
       echo "================= /testing zlib using node ================="
+
+      runHook postCheck
     '';
 
     postPatch = pkgs.lib.optionalString pkgs.stdenv.hostPlatform.isDarwin ''
@@ -102,8 +119,9 @@ One advantage is that when `pkgs.zlib` is updated, it will automatically update
 This `xmlmirror` example features an Emscripten package that is defined completely from this context and no `pkgs.zlib.override` is used.
 
 ```nix
-pkgs.buildEmscriptenPackage rec {
+pkgs.buildEmscriptenPackage {
-  name = "xmlmirror";
+  pname = "xmlmirror";
+  version = "1.2.3";
 
   buildInputs = [
     pkg-config
@@ -116,8 +134,10 @@ pkgs.buildEmscriptenPackage rec {
     openjdk
     json_c
   ];
+
   nativeBuildInputs = [
     pkg-config
+    writableTmpDirAsHomeHook
     zlib
   ];
 
@@ -128,6 +148,8 @@ pkgs.buildEmscriptenPackage rec {
   };
 
   configurePhase = ''
+    runHook preConfigure
+
     rm -f fastXmlLint.js*
     # a fix for ERROR:root:For asm.js, TOTAL_MEMORY must be a multiple of 16MB, was 234217728
     # https://gitlab.com/odfplugfest/xmlmirror/issues/8
@@ -137,11 +159,16 @@ pkgs.buildEmscriptenPackage rec {
     sed -e "s/\$(JSONC_LDFLAGS) \$(ZLIB_LDFLAGS) \$(LIBXML20_LDFLAGS)/\$(JSONC_LDFLAGS) \$(LIBXML20_LDFLAGS) \$(ZLIB_LDFLAGS) /g" -i Makefile.emEnv
     # https://gitlab.com/odfplugfest/xmlmirror/issues/11
     sed -e "s/-o fastXmlLint.js/-s EXTRA_EXPORTED_RUNTIME_METHODS='[\"ccall\", \"cwrap\"]' -o fastXmlLint.js/g" -i Makefile.emEnv
+
+    runHook postConfigure
   '';
 
   buildPhase = ''
-    HOME=$TMPDIR
+    runHook preBuild
+
     make -f Makefile.emEnv
+
+    runHook postBuild
   '';
 
   outputs = [
@@ -150,6 +177,8 @@ pkgs.buildEmscriptenPackage rec {
   ];
 
   installPhase = ''
+    runHook preInstall
+
     mkdir -p $out/share
     mkdir -p $doc/share/${name}
 
@@ -163,9 +192,13 @@ pkgs.buildEmscriptenPackage rec {
     cp *.json $out/share
     cp *.rng $out/share
     cp README.md $doc/share/${name}
+    runHook postInstall
   '';
-  checkPhase = ''
 
+  checkPhase = ''
+    runHook preCheck
+
+    runHook postCheck
   '';
 }
 ```

doc/languages-frameworks/go.section.md

@@ -13,14 +13,14 @@ The following is an example expression using `buildGoModule`:
 
 ```nix
 {
-  pet = buildGoModule rec {
+  pet = buildGoModule (finalAttrs: {
     pname = "pet";
     version = "0.3.4";
 
     src = fetchFromGitHub {
       owner = "knqyf263";
       repo = "pet";
-      rev = "v${version}";
+      tag = "v${finalAttrs.version}";
       hash = "sha256-Gjw1dRrgM8D3G7v6WIM2+50r4HmTXvx0Xxme2fH9TlQ=";
     };
 
@@ -32,7 +32,7 @@ The following is an example expression using `buildGoModule`:
       license = lib.licenses.mit;
       maintainers = with lib.maintainers; [ kalbasit ];
     };
-  };
+  });
 }
 ```
 

doc/languages-frameworks/javascript.section.md

@@ -198,14 +198,14 @@ Here's an example:
   fetchFromGitHub,
 }:
 
-buildNpmPackage rec {
+buildNpmPackage (finalAttrs: {
   pname = "flood";
   version = "4.7.0";
 
   src = fetchFromGitHub {
     owner = "jesec";
-    repo = pname;
+    repo = "flood";
-    rev = "v${version}";
+    tag = "v${finalAttrs.version}";
     hash = "sha256-BR+ZGkBBfd0dSQqAvujsbgsEPFYw/ThrylxUbOksYxM=";
   };
 
@@ -222,7 +222,7 @@ buildNpmPackage rec {
     license = lib.licenses.gpl3Only;
     maintainers = with lib.maintainers; [ winter ];
   };
-}
+})
 ```
 
 In the default `installPhase` set by `buildNpmPackage`, it uses `npm pack --json --dry-run` to decide what files to install in `$out/lib/node_modules/$name/`, where `$name` is the `name` string defined in the package's `package.json`.
@@ -646,9 +646,16 @@ It's important to use the `--offline` flag. For example if you script is `"build
 
 ```nix
 {
+  nativeBuildInputs = [
+    writableTmpDirAsHomeHook
+  ];
+
   buildPhase = ''
-    export HOME=$(mktemp -d)
+    runHook preBuild
+
     yarn --offline build
+
+    runHook postBuild
   '';
 }
 ```

doc/languages-frameworks/lisp.section.md

@@ -135,7 +135,6 @@ During Quicklisp import:
 - names starting with a number have a `_` prepended (`3d-vectors`->`_3d-vectors`)
 - `_` in names is converted to `__` for reversibility
 
-
 ## Defining packages manually inside Nixpkgs {#lisp-defining-packages-inside}
 
 Packages that for some reason are not in Quicklisp, and so cannot be
@@ -185,7 +184,7 @@ let
       domain = "gitlab.common-lisp.net";
       owner = "alexandria";
       repo = "alexandria";
-      rev = "v${version}";
+      tag = "v${version}";
       hash = "sha256-1Hzxt65dZvgOFIljjjlSGgKYkj+YBLwJCACi5DZsKmQ=";
     };
   };
@@ -212,7 +211,7 @@ sbcl.pkgs.alexandria.overrideLispAttrs (oldAttrs: rec {
     domain = "gitlab.common-lisp.net";
     owner = "alexandria";
     repo = "alexandria";
-    rev = "v${version}";
+    tag = "v${version}";
     hash = "sha256-1Hzxt65dZvgOFIljjjlSGgKYkj+YBLwJCACi5DZsKmQ=";
   };
 })

doc/languages-frameworks/maven.section.md

@@ -23,8 +23,8 @@ maven.buildMavenPackage rec {
 
   src = fetchFromGitHub {
     owner = "intoolswetrust";
-    repo = pname;
+    repo = "jd-cli";
-    rev = "${pname}-${version}";
+    tag = "jd-cli-${version}";
     hash = "sha256-rRttA5H0A0c44loBzbKH7Waoted3IsOgxGCD2VM0U/Q=";
   };
 
@@ -33,11 +33,15 @@ maven.buildMavenPackage rec {
   nativeBuildInputs = [ makeWrapper ];
 
   installPhase = ''
+    runHook preInstall
+
     mkdir -p $out/bin $out/share/jd-cli
     install -Dm644 jd-cli/target/jd-cli.jar $out/share/jd-cli
 
     makeWrapper ${jre}/bin/java $out/bin/jd-cli \
       --add-flags "-jar $out/share/jd-cli/jd-cli.jar"
+
+    runHook postInstall
   '';
 
   meta = {
@@ -301,16 +305,24 @@ stdenv.mkDerivation {
   buildInputs = [ maven ];
   src = ./.; # or fetchFromGitHub, cleanSourceWith, etc
   buildPhase = ''
+    runHook preBuild
+
     mvn package -Dmaven.repo.local=$out
+
+    runHook postBuild
   '';
 
   # keep only *.{pom,jar,sha1,nbm} and delete all ephemeral files with lastModified timestamps inside
   installPhase = ''
+    runHook preInstall
+
     find $out -type f \
       -name \*.lastUpdated -or \
       -name resolver-status.properties -or \
       -name _remote.repositories \
       -delete
+
+    runHook postInstall
   '';
 
   # don't do any fixup
@@ -354,11 +366,11 @@ Regardless of which strategy is chosen above, the step to build the derivation i
   maven,
   callPackage,
 }:
-# pick a repository derivation, here we will use buildMaven
 let
+  # pick a repository derivation, here we will use buildMaven
   repository = callPackage ./build-maven-repository.nix { };
 in
-stdenv.mkDerivation rec {
+stdenv.mkDerivation (finalAttrs: {
   pname = "maven-demo";
   version = "1.0";
 
@@ -366,14 +378,22 @@ stdenv.mkDerivation rec {
   buildInputs = [ maven ];
 
   buildPhase = ''
+    runHook preBuild
+
     echo "Using repository ${repository}"
     mvn --offline -Dmaven.repo.local=${repository} package;
+
+    runHook postBuild
   '';
 
   installPhase = ''
-    install -Dm644 target/${pname}-${version}.jar $out/share/java
+    runHook preInstall
+
+    install -Dm644 target/${finalAttrs.pname}-${finalAttrs.version}.jar $out/share/java
+
+    runHook postInstall
   '';
-}
+})
 ```
 
 ::: {.tip}
@@ -421,7 +441,7 @@ We make sure to provide this classpath to the `makeWrapper`.
 let
   repository = callPackage ./build-maven-repository.nix { };
 in
-stdenv.mkDerivation rec {
+stdenv.mkDerivation (finalAttrs: {
   pname = "maven-demo";
   version = "1.0";
 
@@ -430,22 +450,30 @@ stdenv.mkDerivation rec {
   buildInputs = [ maven ];
 
   buildPhase = ''
+    runHook preBuild
+
     echo "Using repository ${repository}"
     mvn --offline -Dmaven.repo.local=${repository} package;
+
+    runHook postBuild
   '';
 
   installPhase = ''
+    runHook preInstall
+
     mkdir -p $out/bin
 
     classpath=$(find ${repository} -name "*.jar" -printf ':%h/%f');
-    install -Dm644 target/${pname}-${version}.jar $out/share/java
+    install -Dm644 target/maven-demo-${finalAttrs.version}.jar $out/share/java
     # create a wrapper that will automatically set the classpath
     # this should be the paths from the dependency derivation
-    makeWrapper ${jre}/bin/java $out/bin/${pname} \
+    makeWrapper ${jre}/bin/java $out/bin/maven-demo \
-          --add-flags "-classpath $out/share/java/${pname}-${version}.jar:''${classpath#:}" \
+          --add-flags "-classpath $out/share/java/maven-demo-${finalAttrs.version}.jar:''${classpath#:}" \
           --add-flags "Main"
+
+    runHook postInstall
   '';
-}
+})
 ```
 
 #### MANIFEST file via Maven Plugin {#manifest-file-via-maven-plugin}
@@ -502,11 +530,11 @@ We will modify the derivation above to add a symlink to our repository so that i
   makeWrapper,
   jre,
 }:
-# pick a repository derivation, here we will use buildMaven
 let
+  # pick a repository derivation, here we will use buildMaven
   repository = callPackage ./build-maven-repository.nix { };
 in
-stdenv.mkDerivation rec {
+stdenv.mkDerivation (finalAttrs: {
   pname = "maven-demo";
   version = "1.0";
 
@@ -515,23 +543,31 @@ stdenv.mkDerivation rec {
   buildInputs = [ maven ];
 
   buildPhase = ''
+    runHook preBuild
+
     echo "Using repository ${repository}"
     mvn --offline -Dmaven.repo.local=${repository} package;
+
+    runHook postBuild
   '';
 
   installPhase = ''
+    runHook preInstall
+
     mkdir -p $out/bin
 
     # create a symbolic link for the repository directory
     ln -s ${repository} $out/repository
 
-    install -Dm644 target/${pname}-${version}.jar $out/share/java
+    install -Dm644 target/maven-demo-${finalAttrs.version}.jar $out/share/java
     # create a wrapper that will automatically set the classpath
     # this should be the paths from the dependency derivation
-    makeWrapper ${jre}/bin/java $out/bin/${pname} \
+    makeWrapper ${jre}/bin/java $out/bin/maven-demo \
-          --add-flags "-jar $out/share/java/${pname}-${version}.jar"
+          --add-flags "-jar $out/share/java/maven-demo-${finalAttrs.version}.jar"
+
+    runHook postInstall
   '';
-}
+})
 ```
 ::: {.note}
 Our script produces a dependency on `jre` rather than `jdk` to restrict the runtime closure necessary to run the application.

doc/languages-frameworks/ocaml.section.md

@@ -83,8 +83,8 @@ buildDunePackage rec {
 
   src = fetchFromGitHub {
     owner = "inhabitedtype";
-    repo = pname;
+    repo = "angstrom";
-    rev = version;
+    tag = version;
     hash = "sha256-MK8o+iPGANEhrrTc1Kz9LBilx2bDPQt7Pp5P2libucI=";
   };
 
@@ -124,7 +124,7 @@ buildDunePackage rec {
   minimalOCamlVersion = "4.02";
 
   src = fetchurl {
-    url = "https://github.com/flowtype/ocaml-${pname}/releases/download/v${version}/${pname}-v${version}.tbz";
+    url = "https://github.com/flowtype/ocaml-wtf8/releases/download/v${version}/wtf8-v${version}.tbz";
     hash = "sha256-d5/3KUBAWRj8tntr4RkJ74KWW7wvn/B/m1nx0npnzyc=";
   };
 

doc/languages-frameworks/perl.section.md

@@ -39,7 +39,7 @@ Perl packages from CPAN are defined in [pkgs/top-level/perl-packages.nix](https:
     pname = "Class-C3";
     version = "0.21";
     src = fetchurl {
-      url = "mirror://cpan/authors/id/F/FL/FLORA/${pname}-${version}.tar.gz";
+      url = "mirror://cpan/authors/id/F/FL/FLORA/Class-C3-${version}.tar.gz";
       hash = "sha256-/5GE5xHT0uYGOQxroqj6LMU7CtKn2s6vMVoSXxL4iK4=";
     };
   };
@@ -88,7 +88,7 @@ buildPerlPackage rec {
   version = "0.36";
 
   src = fetchurl {
-    url = "mirror://cpan/authors/id/P/PM/PMQS/${pname}-${version}.tar.gz";
+    url = "mirror://cpan/authors/id/P/PM/PMQS/BerkeleyDB-${version}.tar.gz";
     hash = "sha256-4Y+HGgGQqcOfdiKcFIyMrWBEccVNVAMDBWZlFTMorh8=";
   };
 
@@ -107,7 +107,7 @@ Dependencies on other Perl packages can be specified in the `buildInputs` and `p
     pname = "Class-C3-Componentised";
     version = "1.0004";
     src = fetchurl {
-      url = "mirror://cpan/authors/id/A/AS/ASH/${pname}-${version}.tar.gz";
+      url = "mirror://cpan/authors/id/A/AS/ASH/Class-C3-Componentised-${version}.tar.gz";
       hash = "sha256-ASO9rV/FzJYZ0BH572Fxm2ZrFLMZLFATJng1NuU4FHc=";
     };
     propagatedBuildInputs = [
@@ -137,7 +137,7 @@ On Darwin, if a script has too many `-Idir` flags in its first line (its “sheb
     version = "12.50";
 
     src = fetchurl {
-      url = "https://exiftool.org/${pname}-${version}.tar.gz";
+      url = "https://exiftool.org/Image-ExifTool-${version}.tar.gz";
       hash = "sha256-vOhB/FwQMC8PPvdnjDvxRpU6jAZcC6GMQfc0AH4uwKg=";
     };
 

doc/languages-frameworks/python.section.md

@@ -2135,8 +2135,9 @@ Occasionally packages don't make use of a common test framework, which may then
 
 #### Common issues {#common-issues}
 
-* Tests that attempt to access `$HOME` can be fixed by using the following
+* Tests that attempt to access `$HOME` can be fixed by using `writableTmpDirAsHomeHook` in
-  work-around before running tests (e.g. `preCheck`): `export HOME=$(mktemp -d)`
+  `nativeCheckInputs`, which sets up a writable temporary directory as the home directory. Alternatively,
+  you can achieve the same effect manually (e.g. in `preCheck`) with: `export HOME=$(mktemp -d)`.
 * Compiling with Cython causes tests to fail with a `ModuleNotLoadedError`.
   This can be fixed with two changes in the derivation: 1) replacing `pytest` with
   `pytestCheckHook` and 2) adding a `preCheck` containing `cd $out` to run

doc/languages-frameworks/rust.section.md

@@ -28,14 +28,14 @@ Rust applications are packaged by using the `buildRustPackage` helper from `rust
   rustPlatform,
 }:
 
-rustPlatform.buildRustPackage rec {
+rustPlatform.buildRustPackage (finalAttrs: {
   pname = "ripgrep";
   version = "14.1.1";
 
   src = fetchFromGitHub {
     owner = "BurntSushi";
-    repo = pname;
+    repo = "ripgrep";
-    rev = version;
+    tag = finalAttrs.version;
     hash = "sha256-gyWnahj1A+iXUQlQ1O1H1u7K5euYQOld9qWm99Vjaeg=";
   };
 
@@ -48,7 +48,7 @@ rustPlatform.buildRustPackage rec {
     license = lib.licenses.unlicense;
     maintainers = [ ];
   };
-}
+})
 ```
 
 `buildRustPackage` requires a `cargoHash` attribute, computed over all crate sources of this package.
@@ -104,21 +104,21 @@ be made invariant to the version by setting `cargoDepsName` to
 `pname`:
 
 ```nix
-rustPlatform.buildRustPackage rec {
+rustPlatform.buildRustPackage (finalAttrs: {
   pname = "broot";
   version = "1.2.0";
 
   src = fetchCrate {
-    inherit pname version;
+    inherit (finalAttrs) pname version;
     hash = "sha256-aDQA4A5mScX9or3Lyiv/5GyAehidnpKKE0grhbP1Ctc=";
   };
 
   useFetchCargoVendor = true;
   cargoHash = "sha256-iDYh52rj1M5Uupvbx2WeDd/jvQZ+2A50V5rp5e2t7q4=";
-  cargoDepsName = pname;
+  cargoDepsName = finalAttrs.pname;
 
   # ...
-}
+})
 ```
 
 ### Importing a `Cargo.lock` file {#importing-a-cargo.lock-file}
@@ -184,7 +184,7 @@ The output hash of each dependency that uses a git source must be
 specified in the `outputHashes` attribute. For example:
 
 ```nix
-rustPlatform.buildRustPackage rec {
+rustPlatform.buildRustPackage {
   pname = "myproject";
   version = "1.0.0";
 
@@ -209,7 +209,7 @@ For usage outside nixpkgs, `allowBuiltinFetchGit` could be used to
 avoid having to specify `outputHashes`. For example:
 
 ```nix
-rustPlatform.buildRustPackage rec {
+rustPlatform.buildRustPackage {
   pname = "myproject";
   version = "1.0.0";
 
@@ -235,7 +235,7 @@ If you want to use different features for check phase, you can use
 For example:
 
 ```nix
-rustPlatform.buildRustPackage rec {
+rustPlatform.buildRustPackage {
   pname = "myproject";
   version = "1.0.0";
 
@@ -427,7 +427,7 @@ source code in a reproducible way. If it is missing or out-of-date one can use
 the `cargoPatches` attribute to update or add it.
 
 ```nix
-rustPlatform.buildRustPackage rec {
+rustPlatform.buildRustPackage {
   # ...
   cargoPatches = [
     # a patch file to add/update Cargo.lock in the source code
@@ -575,8 +575,8 @@ buildPythonPackage rec {
 
   src = fetchFromGitHub {
     owner = "huggingface";
-    repo = pname;
+    repo = "tokenizers";
-    rev = "python-v${version}";
+    tag = "python-v${version}";
     hash = "sha256-rQ2hRV52naEf6PvRsWVCTN7B1oXAQGmnpJw4iIdhamw=";
   };
 
@@ -665,7 +665,7 @@ buildPythonPackage rec {
   src = fetchFromGitHub {
     owner = "Qiskit";
     repo = "retworkx";
-    rev = version;
+    tag = version;
     hash = "sha256-11n30ldg3y3y6qxg3hbj837pnbwjkqw3nxq6frds647mmmprrd20=";
   };
 
@@ -705,7 +705,7 @@ Some projects, especially GNOME applications, are built with the Meson Build Sys
   tinysparql,
 }:
 
-stdenv.mkDerivation rec {
+stdenv.mkDerivation (finalAttrs: {
   pname = "health";
   version = "0.95.0";
 
@@ -713,12 +713,12 @@ stdenv.mkDerivation rec {
     domain = "gitlab.gnome.org";
     owner = "World";
     repo = "health";
-    rev = version;
+    tag = finalAttrs.version;
     hash = "sha256-PrNPprSS98yN8b8yw2G6hzTSaoE65VbsM3q7FVB4mds=";
   };
 
   cargoDeps = rustPlatform.fetchCargoVendor {
-    inherit pname version src;
+    inherit (finalAttrs) pname version src;
     hash = "sha256-eR1ZGtTZQNhofFUEjI7IX16sMKPJmAl7aIFfPJukecg=";
   };
 
@@ -740,7 +740,7 @@ stdenv.mkDerivation rec {
   ];
 
   # ...
-}
+})
 ```
 
 ## `buildRustCrate`: Compiling Rust crates using Nix instead of Cargo {#compiling-rust-crates-using-nix-instead-of-cargo}
@@ -1000,20 +1000,21 @@ let
   };
 in
 
-rustPlatform.buildRustPackage rec {
+rustPlatform.buildRustPackage (finalAttrs: {
   pname = "ripgrep";
   version = "14.1.1";
 
   src = fetchFromGitHub {
     owner = "BurntSushi";
     repo = "ripgrep";
-    rev = version;
+    tag = finalAttrs.version;
     hash = "sha256-gyWnahj1A+iXUQlQ1O1H1u7K5euYQOld9qWm99Vjaeg=";
   };
 
   useFetchCargoVendor = true;
   cargoHash = "sha256-9atn5qyBDy4P6iUoHFhg+TV6Ur71fiah4oTJbBMeEy4=";
 
+  # Tests require network access. Skipping.
   doCheck = false;
 
   meta = {
@@ -1025,7 +1026,7 @@ rustPlatform.buildRustPackage rec {
     ];
     maintainers = with lib.maintainers; [ ];
   };
-}
+})
 ```
 
 Follow the below steps to try that snippet.

doc/languages-frameworks/swift.section.md

@@ -82,15 +82,15 @@ let
   generated = swiftpm2nix.helpers ./nix;
 in
 
-stdenv.mkDerivation rec {
+stdenv.mkDerivation (finalAttrs: {
   pname = "myproject";
   version = "0.0.0";
 
   src = fetchFromGitHub {
     owner = "nixos";
-    repo = pname;
+    repo = "myproject";
-    rev = version;
+    tag = finalAttrs.version;
-    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+    hash = "";
   };
 
   # Including SwiftPM as a nativeBuildInput provides a buildPhase for you.
@@ -106,14 +106,18 @@ stdenv.mkDerivation rec {
   configurePhase = generated.configure;
 
   installPhase = ''
+    runHook preInstall
+
     # This is a special function that invokes swiftpm to find the location
     # of the binaries it produced.
     binPath="$(swiftpmBinPath)"
     # Now perform any installation steps.
     mkdir -p $out/bin
     cp $binPath/myproject $out/bin/
+
+    runHook postInstall
   '';
-}
+})
 ```
 
 ### Custom build flags {#ssec-swiftpm-custom-build-flags}

doc/languages-frameworks/texlive.section.md

@@ -94,18 +94,18 @@ Release 23.11 ships with a new interface that will eventually replace `texlive.c
 - TeX Live packages are also available under `texlive.pkgs` as derivations with outputs `out`, `tex`, `texdoc`, `texsource`, `tlpkg`, `man`, `info`. They cannot be installed outside of `texlive.combine` but are available for other uses. To repackage a font, for instance, use
 
   ```nix
-  stdenvNoCC.mkDerivation rec {
+  stdenvNoCC.mkDerivation (finalAttrs: {
     src = texlive.pkgs.iwona;
     dontUnpack = true;
 
-    inherit (src) pname version;
+    inherit (finalAttrs.src) pname version;
 
     installPhase = ''
       runHook preInstall
       install -Dm644 $src/fonts/opentype/nowacki/iwona/*.otf -t $out/share/fonts/opentype
       runHook postInstall
     '';
-  }
+  })
   ```
 
   See `biber`, `iwona` for complete examples.
@@ -173,6 +173,7 @@ let
       (writeShellScript "force-tex-output.sh" ''
         out="''${tex-}"
       '')
+      writableTmpDirAsHomeHook # Need a writable $HOME for latexmk
     ];
 
     dontConfigure = true;
@@ -184,7 +185,6 @@ let
       latex foiltex.ins
 
       # Generate the documentation
-      export HOME=.
       latexmk -pdf foiltex.dtx
 
       runHook postBuild

doc/packages/emacs.section.md

@@ -28,80 +28,79 @@ You can install it like any other packages via `nix-env -iA myEmacs`. However, t
 
 ```nix
 {
-  packageOverrides =
+  packageOverrides = pkgs: {
-    pkgs: with pkgs; rec {
+    myEmacsConfig = pkgs.writeText "default.el" ''
-      myEmacsConfig = writeText "default.el" ''
+      (eval-when-compile
-        (eval-when-compile
+        (require 'use-package))
-          (require 'use-package))
 
-        ;; load some packages
+      ;; load some packages
 
-        (use-package company
+      (use-package company
-          :bind ("<C-tab>" . company-complete)
+        :bind ("<C-tab>" . company-complete)
-          :diminish company-mode
+        :diminish company-mode
-          :commands (company-mode global-company-mode)
+        :commands (company-mode global-company-mode)
-          :defer 1
+        :defer 1
-          :config
+        :config
-          (global-company-mode))
+        (global-company-mode))
 
-        (use-package counsel
+      (use-package counsel
-          :commands (counsel-descbinds)
+        :commands (counsel-descbinds)
-          :bind (([remap execute-extended-command] . counsel-M-x)
+        :bind (([remap execute-extended-command] . counsel-M-x)
-                 ("C-x C-f" . counsel-find-file)
+               ("C-x C-f" . counsel-find-file)
-                 ("C-c g" . counsel-git)
+               ("C-c g" . counsel-git)
-                 ("C-c j" . counsel-git-grep)
+               ("C-c j" . counsel-git-grep)
-                 ("C-c k" . counsel-ag)
+               ("C-c k" . counsel-ag)
-                 ("C-x l" . counsel-locate)
+               ("C-x l" . counsel-locate)
-                 ("M-y" . counsel-yank-pop)))
+               ("M-y" . counsel-yank-pop)))
 
-        (use-package flycheck
+      (use-package flycheck
-          :defer 2
+        :defer 2
-          :config (global-flycheck-mode))
+        :config (global-flycheck-mode))
 
-        (use-package ivy
+      (use-package ivy
-          :defer 1
+        :defer 1
-          :bind (("C-c C-r" . ivy-resume)
+        :bind (("C-c C-r" . ivy-resume)
-                 ("C-x C-b" . ivy-switch-buffer)
+               ("C-x C-b" . ivy-switch-buffer)
-                 :map ivy-minibuffer-map
+               :map ivy-minibuffer-map
-                 ("C-j" . ivy-call))
+               ("C-j" . ivy-call))
-          :diminish ivy-mode
+        :diminish ivy-mode
-          :commands ivy-mode
+        :commands ivy-mode
-          :config
+        :config
-          (ivy-mode 1))
+        (ivy-mode 1))
 
-        (use-package magit
+      (use-package magit
-          :defer
+        :defer
-          :if (executable-find "git")
+        :if (executable-find "git")
-          :bind (("C-x g" . magit-status)
+        :bind (("C-x g" . magit-status)
-                 ("C-x G" . magit-dispatch-popup))
+               ("C-x G" . magit-dispatch-popup))
-          :init
+        :init
-          (setq magit-completing-read-function 'ivy-completing-read))
+        (setq magit-completing-read-function 'ivy-completing-read))
 
-        (use-package projectile
+      (use-package projectile
-          :commands projectile-mode
+        :commands projectile-mode
-          :bind-keymap ("C-c p" . projectile-command-map)
+        :bind-keymap ("C-c p" . projectile-command-map)
-          :defer 5
+        :defer 5
-          :config
+        :config
-          (projectile-global-mode))
+        (projectile-global-mode))
-      '';
+    '';
 
-      myEmacs = emacs.pkgs.withPackages (
+    myEmacs = emacs.pkgs.withPackages (
-        epkgs:
+      epkgs:
-        (with epkgs.melpaStablePackages; [
+      (with epkgs.melpaStablePackages; [
-          (runCommand "default.el" { } ''
+        (runCommand "default.el" { } ''
-            mkdir -p $out/share/emacs/site-lisp
+          mkdir -p $out/share/emacs/site-lisp
-            cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
+          cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
-          '')
+        '')
-          company
+        company
-          counsel
+        counsel
-          flycheck
+        flycheck
-          ivy
+        ivy
-          magit
+        magit
-          projectile
+        projectile
-          use-package
+        use-package
-        ])
+      ])
-      );
+    );
-    };
+  };
 }
 ```
 

doc/stdenv/stdenv.chapter.md

@@ -20,14 +20,14 @@ stdenv.mkDerivation {
 **Since [RFC 0035](https://github.com/NixOS/rfcs/pull/35), this is preferred for packages in Nixpkgs**, as it allows us to reuse the version easily:
 
 ```nix
-stdenv.mkDerivation rec {
+stdenv.mkDerivation (finalAttrs: {
   pname = "libfoo";
   version = "1.2.3";
   src = fetchurl {
-    url = "http://example.org/libfoo-source-${version}.tar.bz2";
+    url = "http://example.org/libfoo-source-${finalAttrs.version}.tar.bz2";
     hash = "sha256-tWxU/LANbQE32my+9AXyt3nCT7NBVfJ45CX757EMT3Q=";
   };
-}
+})
 ```
 
 Many packages have dependencies that are not provided in the standard environment. It’s usually sufficient to specify those dependencies in the `buildInputs` attribute:
@@ -53,13 +53,24 @@ Often it is necessary to override or modify some aspect of the build. To make th
 stdenv.mkDerivation {
   pname = "fnord";
   version = "4.5";
+
   # ...
+
   buildPhase = ''
+    runHook preBuild
+
     gcc foo.c -o foo
+
+    runHook postBuild
   '';
+
   installPhase = ''
+    runHook preInstall
+
     mkdir -p $out/bin
     cp foo $out/bin
+
+    runHook postInstall
   '';
 }
 ```
@@ -212,12 +223,12 @@ These dependencies are only injected when [`doCheck`](#var-stdenv-doCheck) is se
 
 Consider for example this simplified derivation for `solo5`, a sandboxing tool:
 ```nix
-stdenv.mkDerivation rec {
+stdenv.mkDerivation (finalAttrs: {
   pname = "solo5";
   version = "0.7.5";
 
   src = fetchurl {
-    url = "https://github.com/Solo5/solo5/releases/download/v${version}/solo5-v${version}.tar.gz";
+    url = "https://github.com/Solo5/solo5/releases/download/v${finalAttrs.version}/solo5-v${finalAttrs.version}.tar.gz";
     hash = "sha256-viwrS9lnaU8sTGuzK/+L/PlMM/xRRtgVuK5pixVeDEw=";
   };
 
@@ -225,6 +236,7 @@ stdenv.mkDerivation rec {
     makeWrapper
     pkg-config
   ];
+
   buildInputs = [ libseccomp ];
 
   postInstall = ''
@@ -249,8 +261,8 @@ stdenv.mkDerivation rec {
     util-linux
     qemu
   ];
-  checkPhase = ''[elided] '';
+  checkPhase = ''[elided]'';
-}
+})
 ```
 
 - `makeWrapper` is a setup hook, i.e., a shell script sourced by the generic builder of `stdenv`.

doc/using/configuration.chapter.md

@@ -300,42 +300,41 @@ This provides us with some useful documentation for using our packages.  However
 
 ```nix
 {
-  packageOverrides =
+  packageOverrides = pkgs: {
-    pkgs: with pkgs; rec {
+    myProfile = pkgs.writeText "my-profile" ''
-      myProfile = writeText "my-profile" ''
+      export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
-        export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
+      export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
-        export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
+    '';
-      '';
+    myPackages = pkgs.buildEnv {
-      myPackages = pkgs.buildEnv {
+      name = "my-packages";
-        name = "my-packages";
+      paths = with pkgs; [
-        paths = [
+        (runCommand "profile" { } ''
-          (runCommand "profile" { } ''
+          mkdir -p $out/etc/profile.d
-            mkdir -p $out/etc/profile.d
+          cp ${myProfile} $out/etc/profile.d/my-profile.sh
-            cp ${myProfile} $out/etc/profile.d/my-profile.sh
+        '')
-          '')
+        aspell
-          aspell
+        bc
-          bc
+        coreutils
-          coreutils
+        ffmpeg
-          ffmpeg
+        man
-          man
+        nix
-          nix
+        emscripten
-          emscripten
+        jq
-          jq
+        nox
-          nox
+        silver-searcher
-          silver-searcher
+      ];
-        ];
+      pathsToLink = [
-        pathsToLink = [
+        "/share/man"
-          "/share/man"
+        "/share/doc"
-          "/share/doc"
+        "/bin"
-          "/bin"
+        "/etc"
-          "/etc"
+      ];
-        ];
+      extraOutputsToInstall = [
-        extraOutputsToInstall = [
+        "man"
-          "man"
+        "doc"
-          "doc"
+      ];
-        ];
-      };
     };
+  };
 }
 ```
 
@@ -360,54 +359,53 @@ Configuring GNU info is a little bit trickier than man pages. To work correctly,
 
 ```nix
 {
-  packageOverrides =
+  packageOverrides = pkgs: {
-    pkgs: with pkgs; rec {
+    myProfile = pkgs.writeText "my-profile" ''
-      myProfile = writeText "my-profile" ''
+      export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
-        export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
+      export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
-        export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
+      export INFOPATH=$HOME/.nix-profile/share/info:/nix/var/nix/profiles/default/share/info:/usr/share/info
-        export INFOPATH=$HOME/.nix-profile/share/info:/nix/var/nix/profiles/default/share/info:/usr/share/info
+    '';
+    myPackages = pkgs.buildEnv {
+      name = "my-packages";
+      paths = with pkgs; [
+        (runCommand "profile" { } ''
+          mkdir -p $out/etc/profile.d
+          cp ${myProfile} $out/etc/profile.d/my-profile.sh
+        '')
+        aspell
+        bc
+        coreutils
+        ffmpeg
+        man
+        nix
+        emscripten
+        jq
+        nox
+        silver-searcher
+        texinfoInteractive
+      ];
+      pathsToLink = [
+        "/share/man"
+        "/share/doc"
+        "/share/info"
+        "/bin"
+        "/etc"
+      ];
+      extraOutputsToInstall = [
+        "man"
+        "doc"
+        "info"
+      ];
+      postBuild = ''
+        if [ -x $out/bin/install-info -a -w $out/share/info ]; then
+          shopt -s nullglob
+          for i in $out/share/info/*.info $out/share/info/*.info.gz; do
+              $out/bin/install-info $i $out/share/info/dir
+          done
+        fi
       '';
-      myPackages = pkgs.buildEnv {
-        name = "my-packages";
-        paths = [
-          (runCommand "profile" { } ''
-            mkdir -p $out/etc/profile.d
-            cp ${myProfile} $out/etc/profile.d/my-profile.sh
-          '')
-          aspell
-          bc
-          coreutils
-          ffmpeg
-          man
-          nix
-          emscripten
-          jq
-          nox
-          silver-searcher
-          texinfoInteractive
-        ];
-        pathsToLink = [
-          "/share/man"
-          "/share/doc"
-          "/share/info"
-          "/bin"
-          "/etc"
-        ];
-        extraOutputsToInstall = [
-          "man"
-          "doc"
-          "info"
-        ];
-        postBuild = ''
-          if [ -x $out/bin/install-info -a -w $out/share/info ]; then
-            shopt -s nullglob
-            for i in $out/share/info/*.info $out/share/info/*.info.gz; do
-                $out/bin/install-info $i $out/share/info/dir
-            done
-          fi
-        '';
-      };
     };
+  };
 }
 ```