diff options
author | Wael Nasreddine <wael.nasreddine@gmail.com> | 2019-03-08 21:07:11 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-03-08 21:07:11 -0800 |
commit | a7f4fd00149d30651d1b16f708a95e5b76950d63 (patch) | |
tree | 188709a40edd03fac4b2770e4f128d049696549c /doc/stdenv.xml | |
parent | b7ebfec61f2f93e922ecdff60ac80a08e911b443 (diff) | |
download | nixpkgs-a7f4fd00149d30651d1b16f708a95e5b76950d63.tar nixpkgs-a7f4fd00149d30651d1b16f708a95e5b76950d63.tar.gz nixpkgs-a7f4fd00149d30651d1b16f708a95e5b76950d63.tar.bz2 nixpkgs-a7f4fd00149d30651d1b16f708a95e5b76950d63.tar.lz nixpkgs-a7f4fd00149d30651d1b16f708a95e5b76950d63.tar.xz nixpkgs-a7f4fd00149d30651d1b16f708a95e5b76950d63.tar.zst nixpkgs-a7f4fd00149d30651d1b16f708a95e5b76950d63.zip |
doc: format the documentation (#57102)
Diffstat (limited to 'doc/stdenv.xml')
-rw-r--r-- | doc/stdenv.xml | 570 |
1 files changed, 290 insertions, 280 deletions
diff --git a/doc/stdenv.xml b/doc/stdenv.xml index 81bd4556193..68a3282d7d6 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -228,18 +228,17 @@ genericBuild </para> <para> - The extension of <envar>PATH</envar> with dependencies, alluded to - above, proceeds according to the relative platforms alone. The - process is carried out only for dependencies whose host platform - matches the new derivation's build platform i.e. dependencies which - run on the platform where the new derivation will be built. + The extension of <envar>PATH</envar> with dependencies, alluded to above, + proceeds according to the relative platforms alone. The process is carried + out only for dependencies whose host platform matches the new derivation's + build platform i.e. dependencies which run on the platform where the new + derivation will be built. <footnote xml:id="footnote-stdenv-native-dependencies-in-path"> <para> - Currently, this means for native builds all dependencies are put - on the <envar>PATH</envar>. But in the future that may not be the - case for sake of matching cross: the platforms would be assumed - to be unique for native and cross builds alike, so only the - <varname>depsBuild*</varname> and + Currently, this means for native builds all dependencies are put on the + <envar>PATH</envar>. But in the future that may not be the case for sake + of matching cross: the platforms would be assumed to be unique for native + and cross builds alike, so only the <varname>depsBuild*</varname> and <varname>nativeBuildInputs</varname> would be added to the <envar>PATH</envar>. </para> @@ -252,9 +251,10 @@ genericBuild <para> The dependency is propagated when it forces some of its other-transitive (non-immediate) downstream dependencies to also take it on as an immediate - dependency. Nix itself already takes a package's transitive dependencies into - account, but this propagation ensures nixpkgs-specific infrastructure like - setup hooks (mentioned above) also are run as if the propagated dependency. + dependency. Nix itself already takes a package's transitive dependencies + into account, but this propagation ensures nixpkgs-specific infrastructure + like setup hooks (mentioned above) also are run as if the propagated + dependency. </para> <para> @@ -270,9 +270,9 @@ genericBuild described by the current dependency's platform offsets. This results in sort a transitive closure of the dependency relation, with the offsets being approximately summed when two dependency links are combined. We also prune - transitive dependencies whose combined offsets go out-of-bounds, which can be - viewed as a filter over that transitive closure removing dependencies that - are blatantly absurd. + transitive dependencies whose combined offsets go out-of-bounds, which can + be viewed as a filter over that transitive closure removing dependencies + that are blatantly absurd. </para> <para> @@ -287,8 +287,8 @@ genericBuild propagation logic. </para> </footnote> - They're confusing in very different ways so... hopefully if something doesn't - make sense in one presentation, it will in the other! + They're confusing in very different ways so... hopefully if something + doesn't make sense in one presentation, it will in the other! <programlisting> let mapOffset(h, t, i) = i + (if i <= 0 then h else t - 1) @@ -324,31 +324,31 @@ let f(h, h + 1, i) = i + (if i <= 0 then h else (h + 1) - 1) let f(h, h + 1, i) = i + (if i <= 0 then h else h) let f(h, h + 1, i) = i + h </programlisting> - This is where "sum-like" comes in from above: We can just sum all of the host - offsets to get the host offset of the transitive dependency. The target - offset is the transitive dependency is simply the host offset + 1, just as it - was with the dependencies composed to make this transitive one; it can be + This is where "sum-like" comes in from above: We can just sum all of the + host offsets to get the host offset of the transitive dependency. The target + offset is the transitive dependency is simply the host offset + 1, just as + it was with the dependencies composed to make this transitive one; it can be ignored as it doesn't add any new information. </para> <para> - Because of the bounds checks, the uncommon cases are <literal>h = t</literal> - and <literal>h + 2 = t</literal>. In the former case, the motivation for - <function>mapOffset</function> is that since its host and target platforms - are the same, no transitive dependency of it should be able to "discover" an - offset greater than its reduced target offsets. + Because of the bounds checks, the uncommon cases are <literal>h = + t</literal> and <literal>h + 2 = t</literal>. In the former case, the + motivation for <function>mapOffset</function> is that since its host and + target platforms are the same, no transitive dependency of it should be able + to "discover" an offset greater than its reduced target offsets. <function>mapOffset</function> effectively "squashes" all its transitive dependencies' offsets so that none will ever be greater than the target offset of the original <literal>h = t</literal> package. In the other case, - <literal>h + 1</literal> is skipped over between the host and target offsets. - Instead of squashing the offsets, we need to "rip" them apart so no + <literal>h + 1</literal> is skipped over between the host and target + offsets. Instead of squashing the offsets, we need to "rip" them apart so no transitive dependencies' offset is that one. </para> <para> - Overall, the unifying theme here is that propagation shouldn't be introducing - transitive dependencies involving platforms the depending package is unaware - of. The offset bounds checking and definition of + Overall, the unifying theme here is that propagation shouldn't be + introducing transitive dependencies involving platforms the depending + package is unaware of. The offset bounds checking and definition of <function>mapOffset</function> together ensure that this is the case. Discovering a new offset is discovering a new platform, and since those platforms weren't in the derivation "spec" of the needing package, they @@ -381,8 +381,8 @@ let f(h, h + 1, i) = i + h Since these packages are able to be run at build-time, they are always added to the <envar>PATH</envar>, as described above. But since these packages are only guaranteed to be able to run then, they shouldn't - persist as run-time dependencies. This isn't currently enforced, but could - be in the future. + persist as run-time dependencies. This isn't currently enforced, but + could be in the future. </para> </listitem> </varlistentry> @@ -396,10 +396,10 @@ let f(h, h + 1, i) = i + h platform, and target platform is the new derivation's host platform. This means a <literal>-1</literal> host offset and <literal>0</literal> target offset from the new derivation's platforms. These are programs and - libraries used at build-time that, if they are a compiler or similar tool, - produce code to run at run-time—i.e. tools used to build the new - derivation. If the dependency doesn't care about the target platform (i.e. - isn't a compiler or similar tool), put it here, rather than in + libraries used at build-time that, if they are a compiler or similar + tool, produce code to run at run-time—i.e. tools used to build the new + derivation. If the dependency doesn't care about the target platform + (i.e. isn't a compiler or similar tool), put it here, rather than in <varname>depsBuildBuild</varname> or <varname>depsBuildTarget</varname>. This could be called <varname>depsBuildHost</varname> but <varname>nativeBuildInputs</varname> is used for historical continuity. @@ -407,8 +407,9 @@ let f(h, h + 1, i) = i + h <para> Since these packages are able to be run at build-time, they are added to the <envar>PATH</envar>, as described above. But since these packages are - only guaranteed to be able to run then, they shouldn't persist as run-time - dependencies. This isn't currently enforced, but could be in the future. + only guaranteed to be able to run then, they shouldn't persist as + run-time dependencies. This isn't currently enforced, but could be in the + future. </para> </listitem> </varlistentry> @@ -421,33 +422,36 @@ let f(h, h + 1, i) = i + h A list of dependencies whose host platform is the new derivation's build platform, and target platform is the new derivation's target platform. This means a <literal>-1</literal> host offset and <literal>1</literal> - target offset from the new derivation's platforms. These are programs used - at build time that produce code to run with code produced by the depending - package. Most commonly, these are tools used to build the runtime or - standard library that the currently-being-built compiler will inject into - any code it compiles. In many cases, the currently-being-built-compiler is - itself employed for that task, but when that compiler won't run (i.e. its - build and host platform differ) this is not possible. Other times, the - compiler relies on some other tool, like binutils, that is always built - separately so that the dependency is unconditional. + target offset from the new derivation's platforms. These are programs + used at build time that produce code to run with code produced by the + depending package. Most commonly, these are tools used to build the + runtime or standard library that the currently-being-built compiler will + inject into any code it compiles. In many cases, the + currently-being-built-compiler is itself employed for that task, but when + that compiler won't run (i.e. its build and host platform differ) this is + not possible. Other times, the compiler relies on some other tool, like + binutils, that is always built separately so that the dependency is + unconditional. </para> <para> This is a somewhat confusing concept to wrap one’s head around, and for good reason. As the only dependency type where the platform offsets are not adjacent integers, it requires thinking of a bootstrapping stage - <emphasis>two</emphasis> away from the current one. It and its use-case go - hand in hand and are both considered poor form: try to not need this sort - of dependency, and try to avoid building standard libraries and runtimes - in the same derivation as the compiler produces code using them. Instead - strive to build those like a normal library, using the newly-built - compiler just as a normal library would. In short, do not use this - attribute unless you are packaging a compiler and are sure it is needed. + <emphasis>two</emphasis> away from the current one. It and its use-case + go hand in hand and are both considered poor form: try to not need this + sort of dependency, and try to avoid building standard libraries and + runtimes in the same derivation as the compiler produces code using them. + Instead strive to build those like a normal library, using the + newly-built compiler just as a normal library would. In short, do not use + this attribute unless you are packaging a compiler and are sure it is + needed. </para> <para> Since these packages are able to run at build time, they are added to the - <envar>PATH</envar>, as described above. But since these packages are only - guaranteed to be able to run then, they shouldn't persist as run-time - dependencies. This isn't currently enforced, but could be in the future. + <envar>PATH</envar>, as described above. But since these packages are + only guaranteed to be able to run then, they shouldn't persist as + run-time dependencies. This isn't currently enforced, but could be in the + future. </para> </listitem> </varlistentry> @@ -462,11 +466,11 @@ let f(h, h + 1, i) = i + h and <literal>0</literal> target offset from the new derivation's host platform. These are packages used at run-time to generate code also used at run-time. In practice, this would usually be tools used by compilers - for macros or a metaprogramming system, or libraries used by the macros or - metaprogramming code itself. It's always preferable to use a - <varname>depsBuildBuild</varname> dependency in the derivation being built - over a <varname>depsHostHost</varname> on the tool doing the building for - this purpose. + for macros or a metaprogramming system, or libraries used by the macros + or metaprogramming code itself. It's always preferable to use a + <varname>depsBuildBuild</varname> dependency in the derivation being + built over a <varname>depsHostHost</varname> on the tool doing the + building for this purpose. </para> </listitem> </varlistentry> @@ -481,8 +485,8 @@ let f(h, h + 1, i) = i + h <literal>1</literal> target offset from the new derivation's host platform. This would be called <varname>depsHostTarget</varname> but for historical continuity. If the dependency doesn't care about the target - platform (i.e. isn't a compiler or similar tool), put it here, rather than - in <varname>depsBuildBuild</varname>. + platform (i.e. isn't a compiler or similar tool), put it here, rather + than in <varname>depsBuildBuild</varname>. </para> <para> These are often programs and libraries used by the new derivation at @@ -664,10 +668,11 @@ passthru = { <literal>hello.baz.value1</literal>. We don't specify any usage or schema of <literal>passthru</literal> - it is meant for values that would be useful outside the derivation in other parts of a Nix expression (e.g. in - other derivations). An example would be to convey some specific dependency - of your derivation which contains a program with plugins support. Later, - others who make derivations with plugins can use passed-through dependency - to ensure that their plugin would be binary-compatible with built program. + other derivations). An example would be to convey some specific + dependency of your derivation which contains a program with plugins + support. Later, others who make derivations with plugins can use + passed-through dependency to ensure that their plugin would be + binary-compatible with built program. </para> </listitem> </varlistentry> @@ -677,9 +682,9 @@ passthru = { </term> <listitem> <para> - A script to be run by <filename>maintainers/scripts/update.nix</filename> when - the package is matched. It needs to be an executable file, either on the file - system: + A script to be run by <filename>maintainers/scripts/update.nix</filename> + when the package is matched. It needs to be an executable file, either on + the file system: <programlisting> passthru.updateScript = ./update.sh; </programlisting> @@ -695,16 +700,24 @@ passthru.updateScript = writeScript "update-zoom-us" '' update-source-version zoom-us "$version" ''; </programlisting> - The attribute can also contain a list, a script followed by arguments to be passed to it: + The attribute can also contain a list, a script followed by arguments to + be passed to it: <programlisting> passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]; </programlisting> - Note that the update scripts will be run in parallel by default; you should avoid running <command>git commit</command> or any other commands that cannot handle that. + Note that the update scripts will be run in parallel by default; you + should avoid running <command>git commit</command> or any other commands + that cannot handle that. </para> - <para> For information about how to run the updates, execute - <cmdsynopsis><command>nix-shell</command> <arg>maintainers/scripts/update.nix</arg></cmdsynopsis>. + <cmdsynopsis> + <command>nix-shell</command> + <arg> + maintainers/scripts/update.nix + </arg> + </cmdsynopsis> + . </para> </listitem> </varlistentry> @@ -1178,8 +1191,8 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ] By default, when cross compiling, the configure script has <option>--build=...</option> and <option>--host=...</option> passed. Packages can instead pass <literal>[ "build" "host" "target" ]</literal> - or a subset to control exactly which platform flags are passed. Compilers - and other tools can use this to also pass the target platform. + or a subset to control exactly which platform flags are passed. + Compilers and other tools can use this to also pass the target platform. <footnote xml:id="footnote-stdenv-build-time-guessing-impurity"> <para> Eventually these will be passed building natively as well, to improve @@ -1694,10 +1707,11 @@ installTargets = "install-bin install-doc";</programlisting> </term> <listitem> <para> - A package can export a <link linkend="ssec-setup-hooks">setup hook</link> - by setting this variable. The setup hook, if defined, is copied to - <filename>$out/nix-support/setup-hook</filename>. Environment variables - are then substituted in it using <function + A package can export a <link linkend="ssec-setup-hooks">setup + hook</link> by setting this variable. The setup hook, if defined, is + copied to <filename>$out/nix-support/setup-hook</filename>. Environment + variables are then substituted in it using + <function linkend="fun-substituteAll">substituteAll</function>. </para> </listitem> @@ -1812,8 +1826,8 @@ set debug-file-directory ~/.nix-profile/lib/debug <listitem> <para> A list of dependencies used by the phase. This gets included in - <varname>nativeBuildInputs</varname> when <varname>doInstallCheck</varname> is - set. + <varname>nativeBuildInputs</varname> when + <varname>doInstallCheck</varname> is set. </para> </listitem> </varlistentry> @@ -2160,10 +2174,11 @@ someVar=$(stripHash $name) dependency derivation is already built just the same—depending is just needing something to exist, and needing is idempotent. However, a dependency specified twice will have its setup hook run twice, and that could easily - change the build environment (though a well-written setup hook will therefore - strive to be idempotent so this is in fact not observable). More broadly, - setup hooks are anti-modular in that multiple dependencies, whether the same - or different, should not interfere and yet their setup hooks may well do so. + change the build environment (though a well-written setup hook will + therefore strive to be idempotent so this is in fact not observable). More + broadly, setup hooks are anti-modular in that multiple dependencies, whether + the same or different, should not interfere and yet their setup hooks may + well do so. </para> <para> @@ -2185,11 +2200,12 @@ someVar=$(stripHash $name) Returning to the C compiler wrapper example, if the wrapper itself is an <literal>n</literal> dependency, then it only wants to accumulate flags from <literal>n + 1</literal> dependencies, as only those ones match the - compiler's target platform. The <envar>hostOffset</envar> variable is defined - with the current dependency's host offset <envar>targetOffset</envar> with - its target offset, before its setup hook is sourced. Additionally, since most - environment hooks don't care about the target platform, that means the setup - hook can append to the right bash array by doing something like + compiler's target platform. The <envar>hostOffset</envar> variable is + defined with the current dependency's host offset + <envar>targetOffset</envar> with its target offset, before its setup hook is + sourced. Additionally, since most environment hooks don't care about the + target platform, that means the setup hook can append to the right bash + array by doing something like <programlisting language="bash"> addEnvHooks "$hostOffset" myBashFunction </programlisting> @@ -2204,24 +2220,22 @@ addEnvHooks "$hostOffset" myBashFunction </para> <para> - First, let’s cover some setup hooks that are part of Nixpkgs - default stdenv. This means that they are run for every package - built using <function>stdenv.mkDerivation</function>. Some of - these are platform specific, so they may run on Linux but not - Darwin or vice-versa. - <variablelist> + First, let’s cover some setup hooks that are part of Nixpkgs default + stdenv. This means that they are run for every package built using + <function>stdenv.mkDerivation</function>. Some of these are platform + specific, so they may run on Linux but not Darwin or vice-versa. + <variablelist> <varlistentry> <term> <literal>move-docs.sh</literal> </term> <listitem> - <para> + <para> This setup hook moves any installed documentation to the - <literal>/share</literal> subdirectory directory. This includes - the man, doc and info directories. This is needed for legacy - programs that do not know how to use the - <literal>share</literal> subdirectory. - </para> + <literal>/share</literal> subdirectory directory. This includes the man, + doc and info directories. This is needed for legacy programs that do not + know how to use the <literal>share</literal> subdirectory. + </para> </listitem> </varlistentry> <varlistentry> @@ -2229,11 +2243,11 @@ addEnvHooks "$hostOffset" myBashFunction <literal>compress-man-pages.sh</literal> </term> <listitem> - <para> - This setup hook compresses any man pages that have been - installed. The compression is done using the gzip program. This - helps to reduce the installed size of packages. - </para> + <para> + This setup hook compresses any man pages that have been installed. The + compression is done using the gzip program. This helps to reduce the + installed size of packages. + </para> </listitem> </varlistentry> <varlistentry> @@ -2241,12 +2255,11 @@ addEnvHooks "$hostOffset" myBashFunction <literal>strip.sh</literal> </term> <listitem> - <para> - This runs the strip command on installed binaries and - libraries. This removes unnecessary information like debug - symbols when they are not needed. This also helps to reduce the - installed size of packages. - </para> + <para> + This runs the strip command on installed binaries and libraries. This + removes unnecessary information like debug symbols when they are not + needed. This also helps to reduce the installed size of packages. + </para> </listitem> </varlistentry> <varlistentry> @@ -2254,15 +2267,14 @@ addEnvHooks "$hostOffset" myBashFunction <literal>patch-shebangs.sh</literal> </term> <listitem> - <para> - This setup hook patches installed scripts to use the full path - to the shebang interpreter. A shebang interpreter is the first - commented line of a script telling the operating system which - program will run the script (e.g <literal>#!/bin/bash</literal>). In - Nix, we want an exact path to that interpreter to be used. This - often replaces <literal>/bin/sh</literal> with a path in the - Nix store. - </para> + <para> + This setup hook patches installed scripts to use the full path to the + shebang interpreter. A shebang interpreter is the first commented line + of a script telling the operating system which program will run the + script (e.g <literal>#!/bin/bash</literal>). In Nix, we want an exact + path to that interpreter to be used. This often replaces + <literal>/bin/sh</literal> with a path in the Nix store. + </para> </listitem> </varlistentry> <varlistentry> @@ -2270,12 +2282,12 @@ addEnvHooks "$hostOffset" myBashFunction <literal>audit-tmpdir.sh</literal> </term> <listitem> - <para> - This verifies that no references are left from the install - binaries to the directory used to build those binaries. This - ensures that the binaries do not need things outside the Nix - store. This is currently supported in Linux only. - </para> + <para> + This verifies that no references are left from the install binaries to + the directory used to build those binaries. This ensures that the + binaries do not need things outside the Nix store. This is currently + supported in Linux only. + </para> </listitem> </varlistentry> <varlistentry> @@ -2283,14 +2295,14 @@ addEnvHooks "$hostOffset" myBashFunction <literal>multiple-outputs.sh</literal> </term> <listitem> - <para> - This setup hook adds configure flags that tell packages to - install files into any one of the proper outputs listed in - <literal>outputs</literal>. This behavior can be turned off by setting + <para> + This setup hook adds configure flags that tell packages to install files + into any one of the proper outputs listed in <literal>outputs</literal>. + This behavior can be turned off by setting <literal>setOutputFlags</literal> to false in the derivation - environment. See <xref linkend="chap-multiple-output"/> for - more information. - </para> + environment. See <xref linkend="chap-multiple-output"/> for more + information. + </para> </listitem> </varlistentry> <varlistentry> @@ -2298,11 +2310,11 @@ addEnvHooks "$hostOffset" myBashFunction <literal>move-sbin.sh</literal> </term> <listitem> - <para> - This setup hook moves any binaries installed in the sbin - subdirectory into bin. In addition, a link is provided from - sbin to bin for compatibility. - </para> + <para> + This setup hook moves any binaries installed in the sbin subdirectory + into bin. In addition, a link is provided from sbin to bin for + compatibility. + </para> </listitem> </varlistentry> <varlistentry> @@ -2310,11 +2322,11 @@ addEnvHooks "$hostOffset" myBashFunction <literal>move-lib64.sh</literal> </term> <listitem> - <para> - This setup hook moves any libraries installed in the lib64 - subdirectory into lib. In addition, a link is provided from - lib64 to lib for compatibility. - </para> + <para> + This setup hook moves any libraries installed in the lib64 subdirectory + into lib. In addition, a link is provided from lib64 to lib for + compatibility. + </para> </listitem> </varlistentry> <varlistentry> @@ -2322,10 +2334,10 @@ addEnvHooks "$hostOffset" myBashFunction <literal>set-source-date-epoch-to-latest.sh</literal> </term> <listitem> - <para> - This sets <literal>SOURCE_DATE_EPOCH</literal> to the - modification time of the most recent file. - </para> + <para> + This sets <literal>SOURCE_DATE_EPOCH</literal> to the modification time + of the most recent file. + </para> </listitem> </varlistentry> <varlistentry> @@ -2335,19 +2347,19 @@ addEnvHooks "$hostOffset" myBashFunction <listitem> <para> The Bintools Wrapper wraps the binary utilities for a bunch of - miscellaneous purposes. These are GNU Binutils when targetting Linux, and - a mix of cctools and GNU binutils for Darwin. [The "Bintools" name is - supposed to be a compromise between "Binutils" and "cctools" not denoting - any specific implementation.] Specifically, the underlying bintools - package, and a C standard library (glibc or Darwin's libSystem, just for - the dynamic loader) are all fed in, and dependency finding, hardening - (see below), and purity checks for each are handled by the Bintools - Wrapper. Packages typically depend on CC Wrapper, which in turn (at run - time) depends on the Bintools Wrapper. - </para> - <para> - The Bintools Wrapper was only just recently split off from CC Wrapper, so - the division of labor is still being worked out. For example, it + miscellaneous purposes. These are GNU Binutils when targetting Linux, + and a mix of cctools and GNU binutils for Darwin. [The "Bintools" name + is supposed to be a compromise between "Binutils" and "cctools" not + denoting any specific implementation.] Specifically, the underlying + bintools package, and a C standard library (glibc or Darwin's libSystem, + just for the dynamic loader) are all fed in, and dependency finding, + hardening (see below), and purity checks for each are handled by the + Bintools Wrapper. Packages typically depend on CC Wrapper, which in turn + (at run time) depends on the Bintools Wrapper. + </para> + <para> + The Bintools Wrapper was only just recently split off from CC Wrapper, + so the division of labor is still being worked out. For example, it shouldn't care about about the C standard library, but just take a derivation with the dynamic loader (which happens to be the glibc on linux). Dependency finding however is a task both wrappers will continue @@ -2357,11 +2369,12 @@ addEnvHooks "$hostOffset" myBashFunction <varname>nativeBuildInputs</varname>) in environment variables. The Bintools Wrapper's setup hook causes any <filename>lib</filename> and <filename>lib64</filename> subdirectories to be added to - <envar>NIX_LDFLAGS</envar>. Since the CC Wrapper and the Bintools Wrapper - use the same strategy, most of the Bintools Wrapper code is sparsely - commented and refers to the CC Wrapper. But the CC Wrapper's code, by - contrast, has quite lengthy comments. The Bintools Wrapper merely cites - those, rather than repeating them, to avoid falling out of sync. + <envar>NIX_LDFLAGS</envar>. Since the CC Wrapper and the Bintools + Wrapper use the same strategy, most of the Bintools Wrapper code is + sparsely commented and refers to the CC Wrapper. But the CC Wrapper's + code, by contrast, has quite lengthy comments. The Bintools Wrapper + merely cites those, rather than repeating them, to avoid falling out of + sync. </para> <para> A final task of the setup hook is defining a number of standard @@ -2370,8 +2383,8 @@ addEnvHooks "$hostOffset" myBashFunction under the assumption that the Bintools Wrapper's binaries will be on the path. Firstly, this helps poorly-written packages, e.g. ones that look for just <command>gcc</command> when <envar>CC</envar> isn't defined yet - <command>clang</command> is to be used. Secondly, this helps packages not - get confused when cross-compiling, in which case multiple Bintools + <command>clang</command> is to be used. Secondly, this helps packages + not get confused when cross-compiling, in which case multiple Bintools Wrappers may simultaneously be in use. <footnote xml:id="footnote-stdenv-per-platform-wrapper"> <para> @@ -2387,16 +2400,16 @@ addEnvHooks "$hostOffset" myBashFunction Wrappers, properly disambiguating them. </para> <para> - A problem with this final task is that the Bintools Wrapper is honest and - defines <envar>LD</envar> as <command>ld</command>. Most packages, + A problem with this final task is that the Bintools Wrapper is honest + and defines <envar>LD</envar> as <command>ld</command>. Most packages, however, firstly use the C compiler for linking, secondly use <envar>LD</envar> anyways, defining it as the C compiler, and thirdly, - only so define <envar>LD</envar> when it is undefined as a fallback. This - triple-threat means Bintools Wrapper will break those packages, as LD is - already defined as the actual linker which the package won't override yet - doesn't want to use. The workaround is to define, just for the - problematic package, <envar>LD</envar> as the C compiler. A good way to - do this would be <command>preConfigure = "LD=$CC"</command>. + only so define <envar>LD</envar> when it is undefined as a fallback. + This triple-threat means Bintools Wrapper will break those packages, as + LD is already defined as the actual linker which the package won't + override yet doesn't want to use. The workaround is to define, just for + the problematic package, <envar>LD</envar> as the C compiler. A good way + to do this would be <command>preConfigure = "LD=$CC"</command>. </para> </listitem> </varlistentry> @@ -2406,13 +2419,13 @@ addEnvHooks "$hostOffset" myBashFunction </term> <listitem> <para> - The CC Wrapper wraps a C toolchain for a bunch of miscellaneous purposes. - Specifically, a C compiler (GCC or Clang), wrapped binary tools, and a C - standard library (glibc or Darwin's libSystem, just for the dynamic - loader) are all fed in, and dependency finding, hardening (see below), - and purity checks for each are handled by the CC Wrapper. Packages - typically depend on the CC Wrapper, which in turn (at run-time) depends - on the Bintools Wrapper. + The CC Wrapper wraps a C toolchain for a bunch of miscellaneous + purposes. Specifically, a C compiler (GCC or Clang), wrapped binary + tools, and a C standard library (glibc or Darwin's libSystem, just for + the dynamic loader) are all fed in, and dependency finding, hardening + (see below), and purity checks for each are handled by the CC Wrapper. + Packages typically depend on the CC Wrapper, which in turn (at run-time) + depends on the Bintools Wrapper. </para> <para> Dependency finding is undoubtedly the main task of the CC Wrapper. This @@ -2434,14 +2447,13 @@ addEnvHooks "$hostOffset" myBashFunction </para> </listitem> </varlistentry> - </variablelist> + </variablelist> </para> <para> - Here are some more packages that provide a setup hook. Since the - list of hooks is extensible, this is not an exhaustive list the - mechanism is only to be used as a last resort, it might cover most - uses. + Here are some more packages that provide a setup hook. Since the list of + hooks is extensible, this is not an exhaustive list the mechanism is only to + be used as a last resort, it might cover most uses. <variablelist> <varlistentry> <term> @@ -2499,11 +2511,11 @@ addEnvHooks "$hostOffset" myBashFunction <listitem> <para> The <varname>autoreconfHook</varname> derivation adds - <varname>autoreconfPhase</varname>, which runs autoreconf, libtoolize and - automake, essentially preparing the configure script in autotools-based - builds. Most autotools-based packages come with the configure script - pre-generated, but this hook is necessary for a few packages and when you - need to patch the package’s configure scripts. + <varname>autoreconfPhase</varname>, which runs autoreconf, libtoolize + and automake, essentially preparing the configure script in + autotools-based builds. Most autotools-based packages come with the + configure script pre-generated, but this hook is necessary for a few + packages and when you need to patch the package’s configure scripts. </para> </listitem> </varlistentry> @@ -2547,9 +2559,9 @@ addEnvHooks "$hostOffset" myBashFunction </term> <listitem> <para> - Exports <envar>GDK_PIXBUF_MODULE_FILE</envar> environment variable to the - builder. Add librsvg package to <varname>buildInputs</varname> to get svg - support. + Exports <envar>GDK_PIXBUF_MODULE_FILE</envar> environment variable to + the builder. Add librsvg package to <varname>buildInputs</varname> to + get svg support. </para> </listitem> </varlistentry> @@ -2594,21 +2606,20 @@ addEnvHooks "$hostOffset" myBashFunction </para> <para> This is useful for programs that use <citerefentry> - <refentrytitle>dlopen</refentrytitle> - <manvolnum>3</manvolnum> - </citerefentry> to load libraries at runtime. + <refentrytitle>dlopen</refentrytitle> + <manvolnum>3</manvolnum> </citerefentry> to load libraries at runtime. </para> <para> - In certain situations you may want to run the main command - (<command>autoPatchelf</command>) of the setup hook on a file or a set - of directories instead of unconditionally patching all outputs. This - can be done by setting the <envar>dontAutoPatchelf</envar> environment - variable to a non-empty value. + In certain situations you may want to run the main command + (<command>autoPatchelf</command>) of the setup hook on a file or a set + of directories instead of unconditionally patching all outputs. This can + be done by setting the <envar>dontAutoPatchelf</envar> environment + variable to a non-empty value. </para> <para> - The <command>autoPatchelf</command> command also recognizes a - <parameter class="command">--no-recurse</parameter> command line flag, - which prevents it from recursing into subdirectories. + The <command>autoPatchelf</command> command also recognizes a + <parameter class="command">--no-recurse</parameter> command line flag, + which prevents it from recursing into subdirectories. </para> </listitem> </varlistentry> @@ -2619,22 +2630,22 @@ addEnvHooks "$hostOffset" myBashFunction <listitem> <para> This hook will make a build pause instead of stopping when a failure - happens. It prevents nix from cleaning up the build environment immediately and - allows the user to attach to a build environment using the - <command>cntr</command> command. Upon build error it will print - instructions on how to use <command>cntr</command>. Installing - cntr and running the command will provide shell access to the build - sandbox of failed build. At <filename>/var/lib/cntr</filename> the - sandboxed filesystem is mounted. All commands and files of the system are - still accessible within the shell. To execute commands from the sandbox - use the cntr exec subcommand. Note that <command>cntr</command> also - needs to be executed on the machine that is doing the build, which might - not be the case when remote builders are enabled. - <command>cntr</command> is only supported on Linux-based platforms. To - use it first add <literal>cntr</literal> to your - <literal>environment.systemPackages</literal> on NixOS or alternatively to - the root user on non-NixOS systems. Then in the package that is supposed - to be inspected, add <literal>breakpointHook</literal> to + happens. It prevents nix from cleaning up the build environment + immediately and allows the user to attach to a build environment using + the <command>cntr</command> command. Upon build error it will print + instructions on how to use <command>cntr</command>. Installing cntr and + running the command will provide shell access to the build sandbox of + failed build. At <filename>/var/lib/cntr</filename> the sandboxed + filesystem is mounted. All commands and files of the system are still + accessible within the shell. To execute commands from the sandbox use + the cntr exec subcommand. Note that <command>cntr</command> also needs + to be executed on the machine that is doing the build, which might not + be the case when remote builders are enabled. <command>cntr</command> is + only supported on Linux-based platforms. To use it first add + <literal>cntr</literal> to your + <literal>environment.systemPackages</literal> on NixOS or alternatively + to the root user on non-NixOS systems. Then in the package that is + supposed to be inspected, add <literal>breakpointHook</literal> to <literal>nativeBuildInputs</literal>. <programlisting> nativeBuildInputs = [ breakpointHook ]; @@ -2649,16 +2660,15 @@ addEnvHooks "$hostOffset" myBashFunction libiconv, libintl </term> <listitem> - <para> - A few libraries automatically add to - <literal>NIX_LDFLAGS</literal> their library, making their - symbols automatically available to the linker. This includes - libiconv and libintl (gettext). This is done to provide - compatibility between GNU Linux, where libiconv and libintl - are bundled in, and other systems where that might not be the - case. Sometimes, this behavior is not desired. To disable - this behavior, set <literal>dontAddExtraLibs</literal>. - </para> + <para> + A few libraries automatically add to <literal>NIX_LDFLAGS</literal> + their library, making their symbols automatically available to the + linker. This includes libiconv and libintl (gettext). This is done to + provide compatibility between GNU Linux, where libiconv and libintl are + bundled in, and other systems where that might not be the case. + Sometimes, this behavior is not desired. To disable this behavior, set + <literal>dontAddExtraLibs</literal>. + </para> </listitem> </varlistentry> <varlistentry> @@ -2666,17 +2676,17 @@ addEnvHooks "$hostOffset" myBashFunction cmake </term> <listitem> - <para> - Overrides the default configure phase to run the CMake command. By - default, we use the Make generator of CMake. In - addition, dependencies are added automatically to CMAKE_PREFIX_PATH so - that packages are correctly detected by CMake. Some additional flags - are passed in to give similar behavior to configure-based packages. You - can disable this hook’s behavior by setting configurePhase to a custom - value, or by setting dontUseCmakeConfigure. cmakeFlags controls flags - passed only to CMake. By default, parallel building is enabled as CMake - supports parallel building almost everywhere. When Ninja is also in - use, CMake will detect that and use the ninja generator. + <para> + Overrides the default configure phase to run the CMake command. By + default, we use the Make generator of CMake. In addition, dependencies + are added automatically to CMAKE_PREFIX_PATH so that packages are + correctly detected by CMake. Some additional flags are passed in to give + similar behavior to configure-based packages. You can disable this + hook’s behavior by setting configurePhase to a custom value, or by + setting dontUseCmakeConfigure. cmakeFlags controls flags passed only to + CMake. By default, parallel building is enabled as CMake supports + parallel building almost everywhere. When Ninja is also in use, CMake + will detect that and use the ninja generator. </para> </listitem> </varlistentry> @@ -2685,12 +2695,12 @@ addEnvHooks "$hostOffset" myBashFunction xcbuildHook </term> <listitem> - <para> - Overrides the build and install phases to run the “xcbuild” command. - This hook is needed when a project only comes with build files for the - XCode build system. You can disable this behavior by setting buildPhase - and configurePhase to a custom value. xcbuildFlags controls flags - passed only to xcbuild. + <para> + Overrides the build and install phases to run the “xcbuild” command. + This hook is needed when a project only comes with build files for the + XCode build system. You can disable this behavior by setting buildPhase + and configurePhase to a custom value. xcbuildFlags controls flags passed + only to xcbuild. </para> </listitem> </varlistentry> @@ -2699,13 +2709,13 @@ addEnvHooks "$hostOffset" myBashFunction meson </term> <listitem> - <para> - Overrides the configure phase to run meson to generate Ninja files. You - can disable this behavior by setting configurePhase to a custom value, - or by setting dontUseMesonConfigure. To run these files, you should - accompany meson with ninja. mesonFlags controls only the flags passed - to meson. By default, parallel building is enabled as Meson supports - parallel building almost everywhere. + <para> + Overrides the configure phase to run meson to generate Ninja files. You + can disable this behavior by setting configurePhase to a custom value, + or by setting dontUseMesonConfigure. To run these files, you should + accompany meson with ninja. mesonFlags controls only the flags passed to + meson. By default, parallel building is enabled as Meson supports + parallel building almost everywhere. </para> </listitem> </varlistentry> @@ -2714,11 +2724,11 @@ addEnvHooks "$hostOffset" myBashFunction ninja </term> <listitem> - <para> - Overrides the build, install, and check phase to run ninja instead of - make. You can disable this behavior with the dontUseNinjaBuild, - dontUseNinjaInstall, and dontUseNinjaCheck, respectively. Parallel - building is enabled by default in Ninja. + <para> + Overrides the build, install, and check phase to run ninja instead of + make. You can disable this behavior with the dontUseNinjaBuild, + dontUseNinjaInstall, and dontUseNinjaCheck, respectively. Parallel + building is enabled by default in Ninja. </para> </listitem> </varlistentry> @@ -2727,9 +2737,9 @@ addEnvHooks "$hostOffset" myBashFunction unzip </term> <listitem> - <para> - This setup hook will allow you to unzip .zip files specified in $src. - There are many similar packages like unrar, undmg, etc. + <para> + This setup hook will allow you to unzip .zip files specified in $src. + There are many similar packages like unrar, undmg, etc. </para> </listitem> </varlistentry> @@ -2738,11 +2748,11 @@ addEnvHooks "$hostOffset" myBashFunction wafHook </term> <listitem> - <para> - Overrides the configure, build, and install phases. This will run the - "waf" script used by many projects. If waf doesn’t exist, it will copy - the version of waf available in Nixpkgs wafFlags can be used to pass - flags to the waf script. + <para> + Overrides the configure, build, and install phases. This will run the + "waf" script used by many projects. If waf doesn’t exist, it will copy + the version of waf available in Nixpkgs wafFlags can be used to pass + flags to the waf script. </para> </listitem> </varlistentry> @@ -2751,14 +2761,14 @@ addEnvHooks "$hostOffset" myBashFunction scons </term> <listitem> - <para> - Overrides the build, install, and check phases. This uses the scons - build system as a replacement for make. scons does not provide a - configure phase, so everything is managed at build and install time. + <para> + Overrides the build, install, and check phases. This uses the scons + build system as a replacement for make. scons does not provide a + configure phase, so everything is managed at build and install time. </para> </listitem> </varlistentry> - </variablelist> + </variablelist> </para> </section> <section xml:id="sec-purity-in-nixpkgs"> |