From a7f4fd00149d30651d1b16f708a95e5b76950d63 Mon Sep 17 00:00:00 2001 From: Wael Nasreddine Date: Fri, 8 Mar 2019 21:07:11 -0800 Subject: doc: format the documentation (#57102) --- doc/stdenv.xml | 570 +++++++++++++++++++++++++++++---------------------------- 1 file changed, 290 insertions(+), 280 deletions(-) (limited to 'doc/stdenv.xml') diff --git a/doc/stdenv.xml b/doc/stdenv.xml index 81bd4556193f..68a3282d7d68 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -228,18 +228,17 @@ genericBuild - The extension of PATH 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 PATH 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. - Currently, this means for native builds all dependencies are put - on the PATH. 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 - depsBuild* and + Currently, this means for native builds all dependencies are put on the + PATH. 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 depsBuild* and nativeBuildInputs would be added to the PATH. @@ -252,9 +251,10 @@ genericBuild 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. @@ -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. @@ -287,8 +287,8 @@ genericBuild propagation logic. - 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! 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 - 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. - Because of the bounds checks, the uncommon cases are h = t - and h + 2 = t. In the former case, the motivation for - mapOffset 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 h = + t and h + 2 = t. In the former case, the + motivation for mapOffset 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. mapOffset effectively "squashes" all its transitive dependencies' offsets so that none will ever be greater than the target offset of the original h = t package. In the other case, - h + 1 is skipped over between the host and target offsets. - Instead of squashing the offsets, we need to "rip" them apart so no + h + 1 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. - 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 mapOffset 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 PATH, 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. @@ -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 -1 host offset and 0 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 depsBuildBuild or depsBuildTarget. This could be called depsBuildHost but nativeBuildInputs is used for historical continuity. @@ -407,8 +407,9 @@ let f(h, h + 1, i) = i + h Since these packages are able to be run at build-time, they are added to the PATH, 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. @@ -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 -1 host offset and 1 - 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. 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 - two 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. + two 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. Since these packages are able to run at build time, they are added to the - PATH, 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. + PATH, 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. @@ -462,11 +466,11 @@ let f(h, h + 1, i) = i + h and 0 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 - depsBuildBuild dependency in the derivation being built - over a depsHostHost 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 + depsBuildBuild dependency in the derivation being + built over a depsHostHost on the tool doing the + building for this purpose. @@ -481,8 +485,8 @@ let f(h, h + 1, i) = i + h 1 target offset from the new derivation's host platform. This would be called depsHostTarget 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 depsBuildBuild. + platform (i.e. isn't a compiler or similar tool), put it here, rather + than in depsBuildBuild. These are often programs and libraries used by the new derivation at @@ -664,10 +668,11 @@ passthru = { hello.baz.value1. We don't specify any usage or schema of passthru - 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. @@ -677,9 +682,9 @@ passthru = { - A script to be run by maintainers/scripts/update.nix when - the package is matched. It needs to be an executable file, either on the file - system: + A script to be run by maintainers/scripts/update.nix + when the package is matched. It needs to be an executable file, either on + the file system: passthru.updateScript = ./update.sh; @@ -695,16 +700,24 @@ passthru.updateScript = writeScript "update-zoom-us" '' update-source-version zoom-us "$version" ''; - 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: passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]; - Note that the update scripts will be run in parallel by default; you should avoid running git commit or any other commands that cannot handle that. + Note that the update scripts will be run in parallel by default; you + should avoid running git commit or any other commands + that cannot handle that. - For information about how to run the updates, execute - nix-shell maintainers/scripts/update.nix. + + nix-shell + + maintainers/scripts/update.nix + + + . @@ -1178,8 +1191,8 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ] By default, when cross compiling, the configure script has and passed. Packages can instead pass [ "build" "host" "target" ] - 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. Eventually these will be passed building natively as well, to improve @@ -1694,10 +1707,11 @@ installTargets = "install-bin install-doc"; - A package can export a setup hook - by setting this variable. The setup hook, if defined, is copied to - $out/nix-support/setup-hook. Environment variables - are then substituted in it using setup + hook by setting this variable. The setup hook, if defined, is + copied to $out/nix-support/setup-hook. Environment + variables are then substituted in it using + substituteAll. @@ -1812,8 +1826,8 @@ set debug-file-directory ~/.nix-profile/lib/debug A list of dependencies used by the phase. This gets included in - nativeBuildInputs when doInstallCheck is - set. + nativeBuildInputs when + doInstallCheck is set. @@ -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. @@ -2185,11 +2200,12 @@ someVar=$(stripHash $name) Returning to the C compiler wrapper example, if the wrapper itself is an n dependency, then it only wants to accumulate flags from n + 1 dependencies, as only those ones match the - compiler's target platform. The hostOffset variable is defined - with the current dependency's host offset targetOffset 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 hostOffset variable is + defined with the current dependency's host offset + targetOffset 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 addEnvHooks "$hostOffset" myBashFunction @@ -2204,24 +2220,22 @@ addEnvHooks "$hostOffset" myBashFunction - 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 stdenv.mkDerivation. Some of - these are platform specific, so they may run on Linux but not - Darwin or vice-versa. - + 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 + stdenv.mkDerivation. Some of these are platform + specific, so they may run on Linux but not Darwin or vice-versa. + move-docs.sh - + This setup hook moves any installed documentation to the - /share subdirectory directory. This includes - the man, doc and info directories. This is needed for legacy - programs that do not know how to use the - share subdirectory. - + /share subdirectory directory. This includes the man, + doc and info directories. This is needed for legacy programs that do not + know how to use the share subdirectory. + @@ -2229,11 +2243,11 @@ addEnvHooks "$hostOffset" myBashFunction compress-man-pages.sh - - 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. - + + 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. + @@ -2241,12 +2255,11 @@ addEnvHooks "$hostOffset" myBashFunction strip.sh - - 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. - + + 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. + @@ -2254,15 +2267,14 @@ addEnvHooks "$hostOffset" myBashFunction patch-shebangs.sh - - 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 #!/bin/bash). In - Nix, we want an exact path to that interpreter to be used. This - often replaces /bin/sh with a path in the - Nix store. - + + 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 #!/bin/bash). In Nix, we want an exact + path to that interpreter to be used. This often replaces + /bin/sh with a path in the Nix store. + @@ -2270,12 +2282,12 @@ addEnvHooks "$hostOffset" myBashFunction audit-tmpdir.sh - - 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. - + + 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. + @@ -2283,14 +2295,14 @@ addEnvHooks "$hostOffset" myBashFunction multiple-outputs.sh - - This setup hook adds configure flags that tell packages to - install files into any one of the proper outputs listed in - outputs. This behavior can be turned off by setting + + This setup hook adds configure flags that tell packages to install files + into any one of the proper outputs listed in outputs. + This behavior can be turned off by setting setOutputFlags to false in the derivation - environment. See for - more information. - + environment. See for more + information. + @@ -2298,11 +2310,11 @@ addEnvHooks "$hostOffset" myBashFunction move-sbin.sh - - 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. - + + 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. + @@ -2310,11 +2322,11 @@ addEnvHooks "$hostOffset" myBashFunction move-lib64.sh - - 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. - + + 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. + @@ -2322,10 +2334,10 @@ addEnvHooks "$hostOffset" myBashFunction set-source-date-epoch-to-latest.sh - - This sets SOURCE_DATE_EPOCH to the - modification time of the most recent file. - + + This sets SOURCE_DATE_EPOCH to the modification time + of the most recent file. + @@ -2335,19 +2347,19 @@ addEnvHooks "$hostOffset" myBashFunction 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. - - - 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. + + + 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 nativeBuildInputs) in environment variables. The Bintools Wrapper's setup hook causes any lib and lib64 subdirectories to be added to - NIX_LDFLAGS. 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. + NIX_LDFLAGS. 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. 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 gcc when CC isn't defined yet - clang is to be used. Secondly, this helps packages not - get confused when cross-compiling, in which case multiple Bintools + clang 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. @@ -2387,16 +2400,16 @@ addEnvHooks "$hostOffset" myBashFunction Wrappers, properly disambiguating them. - A problem with this final task is that the Bintools Wrapper is honest and - defines LD as ld. Most packages, + A problem with this final task is that the Bintools Wrapper is honest + and defines LD as ld. Most packages, however, firstly use the C compiler for linking, secondly use LD anyways, defining it as the C compiler, and thirdly, - only so define LD 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, LD as the C compiler. A good way to - do this would be preConfigure = "LD=$CC". + only so define LD 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, LD as the C compiler. A good way + to do this would be preConfigure = "LD=$CC". @@ -2406,13 +2419,13 @@ addEnvHooks "$hostOffset" myBashFunction - 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. Dependency finding is undoubtedly the main task of the CC Wrapper. This @@ -2434,14 +2447,13 @@ addEnvHooks "$hostOffset" myBashFunction - + - 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. @@ -2499,11 +2511,11 @@ addEnvHooks "$hostOffset" myBashFunction The autoreconfHook derivation adds - autoreconfPhase, 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. + autoreconfPhase, 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. @@ -2547,9 +2559,9 @@ addEnvHooks "$hostOffset" myBashFunction - Exports GDK_PIXBUF_MODULE_FILE environment variable to the - builder. Add librsvg package to buildInputs to get svg - support. + Exports GDK_PIXBUF_MODULE_FILE environment variable to + the builder. Add librsvg package to buildInputs to + get svg support. @@ -2594,21 +2606,20 @@ addEnvHooks "$hostOffset" myBashFunction This is useful for programs that use - dlopen - 3 - to load libraries at runtime. + dlopen + 3 to load libraries at runtime. - In certain situations you may want to run the main command - (autoPatchelf) 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 dontAutoPatchelf environment - variable to a non-empty value. + In certain situations you may want to run the main command + (autoPatchelf) 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 dontAutoPatchelf environment + variable to a non-empty value. - The autoPatchelf command also recognizes a - --no-recurse command line flag, - which prevents it from recursing into subdirectories. + The autoPatchelf command also recognizes a + --no-recurse command line flag, + which prevents it from recursing into subdirectories. @@ -2619,22 +2630,22 @@ addEnvHooks "$hostOffset" myBashFunction 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 - cntr command. Upon build error it will print - instructions on how to use cntr. Installing - cntr and running the command will provide shell access to the build - sandbox of failed build. At /var/lib/cntr 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 cntr also - needs to be executed on the machine that is doing the build, which might - not be the case when remote builders are enabled. - cntr is only supported on Linux-based platforms. To - use it first add cntr to your - environment.systemPackages on NixOS or alternatively to - the root user on non-NixOS systems. Then in the package that is supposed - to be inspected, add breakpointHook to + happens. It prevents nix from cleaning up the build environment + immediately and allows the user to attach to a build environment using + the cntr command. Upon build error it will print + instructions on how to use cntr. Installing cntr and + running the command will provide shell access to the build sandbox of + failed build. At /var/lib/cntr 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 cntr also needs + to be executed on the machine that is doing the build, which might not + be the case when remote builders are enabled. cntr is + only supported on Linux-based platforms. To use it first add + cntr to your + environment.systemPackages on NixOS or alternatively + to the root user on non-NixOS systems. Then in the package that is + supposed to be inspected, add breakpointHook to nativeBuildInputs. nativeBuildInputs = [ breakpointHook ]; @@ -2649,16 +2660,15 @@ addEnvHooks "$hostOffset" myBashFunction libiconv, libintl - - A few libraries automatically add to - NIX_LDFLAGS 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 dontAddExtraLibs. - + + A few libraries automatically add to NIX_LDFLAGS + 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 + dontAddExtraLibs. + @@ -2666,17 +2676,17 @@ addEnvHooks "$hostOffset" myBashFunction cmake - - 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. + + 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. @@ -2685,12 +2695,12 @@ addEnvHooks "$hostOffset" myBashFunction xcbuildHook - - 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. + + 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. @@ -2699,13 +2709,13 @@ addEnvHooks "$hostOffset" myBashFunction meson - - 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. + + 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. @@ -2714,11 +2724,11 @@ addEnvHooks "$hostOffset" myBashFunction ninja - - 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. + + 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. @@ -2727,9 +2737,9 @@ addEnvHooks "$hostOffset" myBashFunction unzip - - This setup hook will allow you to unzip .zip files specified in $src. - There are many similar packages like unrar, undmg, etc. + + This setup hook will allow you to unzip .zip files specified in $src. + There are many similar packages like unrar, undmg, etc. @@ -2738,11 +2748,11 @@ addEnvHooks "$hostOffset" myBashFunction wafHook - - 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. + + 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. @@ -2751,14 +2761,14 @@ addEnvHooks "$hostOffset" myBashFunction scons - - 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. + + 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. - +
-- cgit 1.4.1