From 02a8d5984cf597032e4797d2fc19355026427c7d Mon Sep 17 00:00:00 2001 From: Guillaume Girol Date: Fri, 11 Feb 2022 12:00:00 +0000 Subject: doc: discourage setting `phases`, document/encourage runHook instead. Source: https://matrix.to/#/!kjdutkOsheZdjqYmqp:nixos.org/$mff3KCoPY5sfgsUhKn0e4va7hnz7KMXARaO2_UaLNM4?via=nixos.org&via=matrix.org&via=nixos.dev --- doc/stdenv/stdenv.chapter.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'doc/stdenv/stdenv.chapter.md') diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index 974f8747936..51330f1ec9d 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -325,6 +325,8 @@ 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`. +When overriding a phase, for example `installPhase`, it is important to start with `runHook preInstall` and end it with `runHook postInstall`, otherwise `preInstall` and `postInstall` will not be run. Even if you don't use them directly, it is good practice to do so anyways for downstream users who would want to add a `postInstall` by overriding your derivation. + 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} @@ -337,7 +339,8 @@ There are a number of variables that control what phases are executed and in wha Specifies the phases. You can change the order in which phases are executed, or add new phases, by setting this variable. If it’s not set, the default value is used, which is `$prePhases unpackPhase patchPhase $preConfigurePhases configurePhase $preBuildPhases buildPhase checkPhase $preInstallPhases installPhase fixupPhase installCheckPhase $preDistPhases distPhase $postPhases`. -Usually, if you just want to add a few phases, it’s more convenient to set one of the variables below (such as `preInstallPhases`), as you then don’t specify all the normal phases. +It is discouraged to set this variable, as it is easy to miss some important functionality hidden in some of the less obviously needed phases (like `fixupPhase` which patches the shebang of scripts). +Usually, if you just want to add a few phases, it’s more convenient to set one of the variables below (such as `preInstallPhases`). ##### `prePhases` {#var-stdenv-prePhases} -- cgit 1.4.1 From f16a62bd63bbe01b795bb990de5f135bcafe318a Mon Sep 17 00:00:00 2001 From: Guillaume Girol Date: Fri, 11 Feb 2022 12:00:00 +0000 Subject: doc: document remove-references-to --- doc/stdenv/stdenv.chapter.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'doc/stdenv/stdenv.chapter.md') diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index 974f8747936..bf9ac8d50be 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -794,7 +794,7 @@ Hook executed at the start of the distribution phase. Hook executed at the end of the distribution phase. -## Shell functions {#ssec-stdenv-functions} +## Shell functions and utilities {#ssec-stdenv-functions} The standard environment provides a number of useful functions. @@ -818,6 +818,19 @@ There’s many more kinds of arguments, they are documented in `nixpkgs/pkgs/bui Using the `makeBinaryWrapper` implementation is usually preferred, as it creates a tiny _compiled_ wrapper executable, that can be used as a shebang interpreter. This is needed mostly on Darwin, where shebangs cannot point to scripts, [due to a limitation with the `execve`-syscall](https://stackoverflow.com/questions/67100831/macos-shebang-with-absolute-path-not-working). Compiled wrappers generated by `makeBinaryWrapper` can be inspected with `less ` - by scrolling past the binary data you should be able to see the shell command that generated the executable and there see the environment variables that were injected into the wrapper. +### `remove-references-to -t` \ [ `-t` \ ... ] \ ... {#fun-remove-references-to} + +Removes the references of the specified files to the specified store files. This is done without changing the size of the file by replacing the hash by `eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`, and should work on compiled executables. This is meant to be used to remove the dependency of the output on inputs that are known to be unnecessary at runtime. Of course, reckless usage will break the patched programs. +To use this, add `removeReferencesTo` to `nativeBuildInputs`. + +As `remove-references-to` is an actual executable and not a shell function, it can be used with `find`. +Example removing all references to the compiler in the output: +```nix +postInstall = '' + find "$out" -type f -exec remove-references-to -t ${stdenv.cc} '{}' + +''; +``` + ### `substitute` \ \ \ {#fun-substitute} Performs string substitution on the contents of \, writing the result to \. The substitutions in \ are of the following form: -- cgit 1.4.1