doc: cleanup, use src.tag where it make sense, add missing phase hooks, use finalAttrs pattern

doc/build-helpers/special/checkpoint-build.section.md

@@ -36,7 +36,11 @@ let
   changedHello = pkgs.hello.overrideAttrs (_: {
     doCheck = false;
     patchPhase = ''
+      runHook prePatch
+
       sed -i 's/Hello, world!/Hello, Nix!/g' src/hello.c
+
+      runHook postPatch
     '';
   });
 in mkCheckpointBuild changedHello helloCheckpoint

doc/build-helpers/trivial-build-helpers.chapter.md

@@ -378,7 +378,11 @@ writeTextFile {
   executable = true;
   destination = "/some/subpath/my-cool-script";
   checkPhase = ''
+    runHook preCheck
+
     ${pkgs.shellcheck}/bin/shellcheck $out/some/subpath/my-cool-script
+
+    runHook postCheck
   '';
   meta = {
     license = pkgs.lib.licenses.cc0;

doc/doc-support/lib-function-docs.nix

@@ -102,6 +102,8 @@ stdenvNoCC.mkDerivation {
   ];
 
   installPhase = ''
+    runHook preInstall
+
     cd ..
 
     export NIX_STATE_DIR=$(mktemp -d)
@@ -143,5 +145,7 @@ stdenvNoCC.mkDerivation {
     ) libsets}
 
     echo '```' >> "$out/index.md"
+
+    runHook postInstall
   '';
 }

doc/doc-support/package.nix

@@ -48,6 +48,8 @@ stdenvNoCC.mkDerivation (
     '';
 
     buildPhase = ''
+      runHook preBuild
+
       substituteInPlace ./languages-frameworks/python.section.md \
         --subst-var-by python-interpreter-table "$(<"${pythonInterpreterTable}")"
 
@@ -83,9 +85,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"
@@ -96,6 +102,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/hooks/tauri.section.md

@@ -23,16 +23,16 @@ 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}";
-    inherit src;
+    name = "${finalAttrs.pname}-npm-deps-${finalAttrs.version}";
+    inherit (finalAttrs) src;
     hash = "...";
   };
 
@@ -62,7 +62,7 @@ rustPlatform.buildRustPackage rec {
   buildAndTestSubdir = cargoRoot;
 
   # . . .
-}
+})
 ```
 
 ## Variables controlling cargo-tauri {#tauri-hook-variables-controlling}

doc/languages-frameworks/agda.section.md

@@ -51,7 +51,7 @@ agda.withPackages (p: [
     src =  fetchFromGitHub {
       repo = "agda-stdlib";
       owner = "agda";
-      rev = "v1.5";
+      tag = "v1.5";
       hash = "sha256-nEyxYGSWIDNJqBfGpRDLiOAnlHJKEKAOMnIaqfVZzJk=";
     };
   }))
@@ -82,7 +82,7 @@ agda.withPackages (p: [
       repo = "repo";
       owner = "owner";
       version = "...";
-      rev = "...";
+      tag = "...";
       hash = "...";
     };
   })
@@ -200,8 +200,12 @@ mkDerivation {
   libraryName = "IAL-1.3";
 
   buildPhase = ''
+    runHook preBuild
+
     patchShebangs find-deps.sh
     make
+
+    runHook postBuild
   '';
 }
 ```

doc/languages-frameworks/android.section.md

@@ -255,10 +255,12 @@ let
 
   # Use buildToolsVersion when you define androidComposition
   androidComposition = <...>;
-in
-pkgs.mkShell rec {
+
   ANDROID_HOME = "${androidComposition.androidsdk}/libexec/android-sdk";
   ANDROID_NDK_ROOT = "${ANDROID_HOME}/ndk-bundle";
+in
+pkgs.mkShell {
+  inherit ANDROID_HOME ANDROID_NDK_ROOT;
 
   # Use the same buildToolsVersion here
   GRADLE_OPTS = "-Dorg.gradle.project.android.aapt2FromMavenOverride=${ANDROID_HOME}/build-tools/${buildToolsVersion}/aapt2";
@@ -275,10 +277,12 @@ let
 
   # Use cmakeVersion when you define androidComposition
   androidComposition = <...>;
-in
-pkgs.mkShell rec {
+
   ANDROID_HOME = "${androidComposition.androidsdk}/libexec/android-sdk";
   ANDROID_NDK_ROOT = "${ANDROID_HOME}/ndk-bundle";
+in
+pkgs.mkShell {
+  inherit ANDROID_HOME ANDROID_NDK_ROOT;
 
   # Use the same cmakeVersion here
   shellHook = ''

doc/languages-frameworks/bower.section.md

@@ -97,12 +97,22 @@ pkgs.stdenv.mkDerivation {
   };
 
   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";
+  installPhase = ''
+    runHook preInstall
+
+    mv gulpdist $out
+
+    runHook postInstall
+  '';
 }
 ```
 

doc/languages-frameworks/dart.section.md

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

doc/languages-frameworks/dlang.section.md

@@ -36,7 +36,9 @@ buildDubPackage rec {
 
   installPhase = ''
     runHook preInstall
+
     install -Dm755 btdu -t $out/bin
+
     runHook postInstall
   '';
 }

doc/languages-frameworks/emscripten.section.md

@@ -45,9 +45,11 @@ One advantage is that when `pkgs.zlib` is updated, it will automatically update
   buildInputs = old.buildInputs ++ [ pkg-config ];
   # we need to reset this setting!
   env = (old.env or { }) // { NIX_CFLAGS_COMPILE = ""; };
+
+  # Some tests require writing at $HOME
+  nativeBuildInputs = old.nativeBuildInputs ++ [ writableTmpDirAsHomeHook ];
+
   configurePhase = ''
-    # FIXME: Some tests require writing at $HOME
-    HOME=$TMPDIR
     runHook preConfigure
 
     #export EMCC_DEBUG=2
@@ -58,12 +60,22 @@ One advantage is that when `pkgs.zlib` is updated, it will automatically update
   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"
@@ -82,6 +94,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 ''

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 ];
     };
-  };
+  });
 }
 ```
 
@@ -69,7 +69,6 @@ You can read more about [vendoring in the Go documentation](https://go.dev/ref/m
 To obtain the hash, set `vendorHash = lib.fakeHash;` and run the build. ([more details here](#sec-source-hashes)).
 Another way is to use use `nix-prefetch` to obtain the hash. The following command gets the value of `vendorHash` for package `pet`:
 
-
 ```sh
 cd path/to/nixpkgs
 nix-prefetch -E "{ sha256 }: ((import ./. { }).my-package.overrideAttrs { vendorHash = sha256; }).goModules"
@@ -84,7 +83,7 @@ nix-prefetch -E "{ sha256 }: ((import ./. { }).my-package.overrideAttrs { vendor
       version = "0.4.0";
       src = fetchFromGitHub {
         inherit (previousAttrs.src) owner repo;
-        rev = "v${finalAttrs.version}";
+        tag = "v${finalAttrs.version}";
         hash = "sha256-gVTpzmXekQxGMucDKskGi+e+34nJwwsXwvQTjRO6Gdg=";
       };
       vendorHash = "sha256-dUvp7FEW09V0xMuhewPGw3TuAic/sD7xyXEYviZ2Ivs=";
@@ -104,13 +103,11 @@ if any dependency has case-insensitive conflicts which will produce platform-dep
 
 Defaults to `false`.
 
-
 ### `modPostBuild` {#var-go-modPostBuild}
 
 Shell commands to run after the build of the goModules executes `go mod vendor`, and before calculating fixed output derivation's `vendorHash`.
 Note that if you change this attribute, you need to update `vendorHash` attribute.
 
-
 ### `modRoot` {#var-go-modRoot}
 
 The root directory of the Go module that contains the `go.mod` file.
@@ -133,7 +130,7 @@ The most common use case for this argument is to make the resulting executable a
 
 ### `tags` {#var-go-tags}
 
-A string list of [Go build tags (also called build constraints)](https://pkg.go.dev/cmd/go#hdr-Build_constraints) that are passed via the `-tags` argument of `go build`.  These constraints control whether Go files from the source should be included in the build. For example:
+A string list of [Go build tags (also called build constraints)](https://pkg.go.dev/cmd/go#hdr-Build_constraints) that are passed via the `-tags` argument of `go build`. These constraints control whether Go files from the source should be included in the build. For example:
 
 ```nix
 {

doc/languages-frameworks/gradle.section.md

@@ -41,13 +41,17 @@ stdenv.mkDerivation (finalAttrs: {
   doCheck = true;
 
   installPhase = ''
+    runHook preInstall
+
     mkdir -p $out/{bin,share/pdftk}
     cp build/libs/pdftk-all.jar $out/share/pdftk
 
     makeWrapper ${lib.getExe jre} $out/bin/pdftk \
       --add-flags "-jar $out/share/pdftk/pdftk-all.jar"
 
     cp ${finalAttrs.src}/pdftk.1 $out/share/man/man1
+
+    runHook postInstall
   '';
 
   meta.sourceProvenance = with lib.sourceTypes; [

doc/languages-frameworks/java.section.md

@@ -17,7 +17,9 @@ stdenv.mkDerivation {
 
   buildPhase = ''
     runHook preBuild
+
     ant # build the project using ant
+
     runHook postBuild
   '';