From b08ee51cc7dc57e104698e446a45bbb8e962fe07 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Tue, 1 Feb 2022 16:46:18 +0100 Subject: [PATCH 1/3] stdenv.md: Remove off topic phase propaganda Phases are cool, I get it, but the reader will enjoy it when they see it. And they'll see it sooner if they don't have to read about it. --- doc/stdenv/stdenv.chapter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index 6d72bd0deb4f..9c78539945fd 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -319,7 +319,7 @@ For information about how to run the updates, execute `nix-shell maintainers/scr ## Phases {#sec-stdenv-phases} -The generic builder has a number of *phases*. Package builds are split into phases to make it easier to override specific parts of the build (e.g., unpacking the sources or installing the binaries). Furthermore, it allows a nicer presentation of build logs in the Nix build farm. +The generic builder has a number of *phases*. Package builds are split into phases to make it easier to override specific parts of the build (e.g., unpacking the sources or installing the binaries). Each phase can be overridden in its entirety either by setting the environment variable `namePhase` to a string containing some shell commands to be executed, or by redefining the shell function `namePhase`. The former is convenient to override a phase from the derivation, while the latter is convenient from a build script. However, typically one only wants to *add* some commands to a phase, e.g. by defining `postInstall` or `preFixup`, as skipping some of the default actions may have unexpected consequences. The default script for each phase is defined in the file `pkgs/stdenv/generic/setup.sh`. From 0838f79f0b5fd3e9c8067e9debce3ce38c635190 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Tue, 1 Feb 2022 16:52:32 +0100 Subject: [PATCH 2/3] stdenv.md: Document genericBuild --- doc/stdenv/stdenv.chapter.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index 9c78539945fd..5e2248918753 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -319,10 +319,14 @@ For information about how to run the updates, execute `nix-shell maintainers/scr ## Phases {#sec-stdenv-phases} -The generic builder has a number of *phases*. Package builds are split into phases to make it easier to override specific parts of the build (e.g., unpacking the sources or installing the binaries). +`stdenv.mkDerivation` sets the Nix [derivation](https://nixos.org/manual/nix/stable/expressions/derivations.html#derivations)'s builder to a script that loads the stdenv `setup.sh` bash library and calls `genericBuild`. Most packaging functions rely on this default builder. + +This generic command invokes a number of *phases*. Package builds are split into phases to make it easier to override specific parts of the build (e.g., unpacking the sources or installing the binaries). Each phase can be overridden in its entirety either by setting the environment variable `namePhase` to a string containing some shell commands to be executed, or by redefining the shell function `namePhase`. The former is convenient to override a phase from the derivation, while the latter is convenient from a build script. However, typically one only wants to *add* some commands to a phase, e.g. by defining `postInstall` or `preFixup`, as skipping some of the default actions may have unexpected consequences. The default script for each phase is defined in the file `pkgs/stdenv/generic/setup.sh`. +If you want to run all phases in `nix-shell`, you can invoke `genericBuild` yourself in the interactive shell. + ### Controlling phases {#ssec-controlling-phases} There are a number of variables that control what phases are executed and in what order: From c9b3d27be060e6ae86aab03a6ac0c390a1676e13 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Wed, 2 Feb 2022 23:45:51 +0100 Subject: [PATCH 3/3] stdenv.md: Call out that genericBuild has correct order Co-authored-by: Cole Helbling --- doc/stdenv/stdenv.chapter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index 5e2248918753..974f8747936a 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -325,7 +325,7 @@ This generic command invokes a number of *phases*. Package builds are split into Each phase can be overridden in its entirety either by setting the environment variable `namePhase` to a string containing some shell commands to be executed, or by redefining the shell function `namePhase`. The former is convenient to override a phase from the derivation, while the latter is convenient from a build script. However, typically one only wants to *add* some commands to a phase, e.g. by defining `postInstall` or `preFixup`, as skipping some of the default actions may have unexpected consequences. The default script for each phase is defined in the file `pkgs/stdenv/generic/setup.sh`. -If you want to run all phases in `nix-shell`, you can invoke `genericBuild` yourself in the interactive shell. +While inside an interactive `nix-shell`, if you wanted to run all phases in the order they would be run in an actual build, you can invoke `genericBuild` yourself. ### Controlling phases {#ssec-controlling-phases}