diff options
| -rw-r--r-- | doc/.gitignore | 7 | ||||
| -rw-r--r-- | doc/coding-conventions.xml | 98 | ||||
| -rw-r--r-- | doc/configuration.xml | 19 | ||||
| -rw-r--r-- | doc/cross-compilation.xml | 158 | ||||
| -rw-r--r-- | doc/functions/appimagetools.xml | 69 | ||||
| -rw-r--r-- | doc/functions/dockertools.xml | 24 | ||||
| -rw-r--r-- | doc/functions/fetchers.xml | 318 | ||||
| -rw-r--r-- | doc/functions/library.xml | 7 | ||||
| -rw-r--r-- | doc/functions/nix-gitignore.xml | 40 | ||||
| -rw-r--r-- | doc/functions/prefer-remote-fetch.xml | 14 | ||||
| -rw-r--r-- | doc/functions/trivial-builders.xml | 111 | ||||
| -rw-r--r-- | doc/languages-frameworks/ocaml.xml | 62 | ||||
| -rw-r--r-- | doc/package-notes.xml | 9 | ||||
| -rw-r--r-- | doc/platform-notes.xml | 4 | ||||
| -rw-r--r-- | doc/quick-start.xml | 4 | ||||
| -rw-r--r-- | doc/reviewing-contributions.xml | 14 | ||||
| -rw-r--r-- | doc/stdenv.xml | 570 |
17 files changed, 764 insertions, 764 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index cb07135e685..b5c58be03d1 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,7 +1,8 @@ *.chapter.xml *.section.xml .version -out -manual-full.xml -highlightjs +functions/library/generated functions/library/locations.xml +highlightjs +manual-full.xml +out diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml index d2c7a1baae9..58ce9c7e627 100644 --- a/doc/coding-conventions.xml +++ b/doc/coding-conventions.xml @@ -197,20 +197,14 @@ args.stdenv.mkDerivation (args // { <title>Package naming</title> <para> - The key words - <emphasis>must</emphasis>, - <emphasis>must not</emphasis>, - <emphasis>required</emphasis>, - <emphasis>shall</emphasis>, - <emphasis>shall not</emphasis>, - <emphasis>should</emphasis>, - <emphasis>should not</emphasis>, - <emphasis>recommended</emphasis>, - <emphasis>may</emphasis>, - and <emphasis>optional</emphasis> in this section - are to be interpreted as described in - <link xlink:href="https://tools.ietf.org/html/rfc2119">RFC 2119</link>. - Only <emphasis>emphasized</emphasis> words are to be interpreted in this way. + The key words <emphasis>must</emphasis>, <emphasis>must not</emphasis>, + <emphasis>required</emphasis>, <emphasis>shall</emphasis>, <emphasis>shall + not</emphasis>, <emphasis>should</emphasis>, <emphasis>should + not</emphasis>, <emphasis>recommended</emphasis>, <emphasis>may</emphasis>, + and <emphasis>optional</emphasis> in this section are to be interpreted as + described in <link xlink:href="https://tools.ietf.org/html/rfc2119">RFC + 2119</link>. Only <emphasis>emphasized</emphasis> words are to be + interpreted in this way. </para> <para> @@ -253,15 +247,15 @@ args.stdenv.mkDerivation (args // { <itemizedlist> <listitem> <para> - The <literal>name</literal> attribute <emphasis>should</emphasis> - be identical to the upstream package name. + The <literal>name</literal> attribute <emphasis>should</emphasis> be + identical to the upstream package name. </para> </listitem> <listitem> <para> - The <literal>name</literal> attribute <emphasis>must not</emphasis> - contain uppercase letters — e.g., <literal>"mplayer-1.0rc2"</literal> - instead of <literal>"MPlayer-1.0rc2"</literal>. + The <literal>name</literal> attribute <emphasis>must not</emphasis> + contain uppercase letters — e.g., <literal>"mplayer-1.0rc2"</literal> + instead of <literal>"MPlayer-1.0rc2"</literal>. </para> </listitem> <listitem> @@ -275,28 +269,29 @@ args.stdenv.mkDerivation (args // { <para> If a package is not a release but a commit from a repository, then the version part of the name <emphasis>must</emphasis> be the date of that - (fetched) commit. The date <emphasis>must</emphasis> be in <literal>"YYYY-MM-DD"</literal> - format. Also append <literal>"unstable"</literal> to the name - e.g., + (fetched) commit. The date <emphasis>must</emphasis> be in + <literal>"YYYY-MM-DD"</literal> format. Also append + <literal>"unstable"</literal> to the name - e.g., <literal>"pkgname-unstable-2014-09-23"</literal>. </para> </listitem> <listitem> <para> - Dashes in the package name <emphasis>should</emphasis> be preserved in new variable names, - rather than converted to underscores or camel cased — e.g., - <varname>http-parser</varname> instead of <varname>http_parser</varname> - or <varname>httpParser</varname>. The hyphenated style is preferred in - all three package names. + Dashes in the package name <emphasis>should</emphasis> be preserved in + new variable names, rather than converted to underscores or camel cased + — e.g., <varname>http-parser</varname> instead of + <varname>http_parser</varname> or <varname>httpParser</varname>. The + hyphenated style is preferred in all three package names. </para> </listitem> <listitem> <para> - If there are multiple versions of a package, this <emphasis>should</emphasis> be reflected in - the variable names in <filename>all-packages.nix</filename>, e.g. - <varname>json-c-0-9</varname> and <varname>json-c-0-11</varname>. If - there is an obvious “default” version, make an attribute like - <literal>json-c = json-c-0-9;</literal>. See also - <xref linkend="sec-versioning" /> + If there are multiple versions of a package, this + <emphasis>should</emphasis> be reflected in the variable names in + <filename>all-packages.nix</filename>, e.g. <varname>json-c-0-9</varname> + and <varname>json-c-0-11</varname>. If there is an obvious “default” + version, make an attribute like <literal>json-c = json-c-0-9;</literal>. + See also <xref linkend="sec-versioning" /> </para> </listitem> </itemizedlist> @@ -814,8 +809,8 @@ args.stdenv.mkDerivation (args // { <para> There are multiple ways to fetch a package source in nixpkgs. The general - guideline is that you should package reproducible sources with a high degree of - availability. Right now there is only one fetcher which has mirroring + guideline is that you should package reproducible sources with a high degree + of availability. Right now there is only one fetcher which has mirroring support and that is <literal>fetchurl</literal>. Note that you should also prefer protocols which have a corresponding proxy environment variable. </para> @@ -869,8 +864,10 @@ src = fetchFromGitHub { } </programlisting> Find the value to put as <literal>sha256</literal> by running - <literal>nix run -f '<nixpkgs>' nix-prefetch-github -c nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix</literal> - or <literal>nix-prefetch-url --unpack https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz</literal>. + <literal>nix run -f '<nixpkgs>' nix-prefetch-github -c + nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS + nix</literal> or <literal>nix-prefetch-url --unpack + https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz</literal>. </para> </listitem> </itemizedlist> @@ -953,17 +950,23 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable> would be replace hash with a fake one and rebuild. Nix build will fail and error message will contain desired hash. </para> - <warning><para>This method has security problems. Check below for details.</para></warning> + <warning> + <para> + This method has security problems. Check below for details. + </para> + </warning> </listitem> </orderedlist> <section xml:id="sec-source-hashes-security"> <title>Obtaining hashes securely</title> + <para> - Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead of fetching - source you can fetch malware, and instead of source hash you get hash of malware. Here are - security considerations for this scenario: + Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead + of fetching source you can fetch malware, and instead of source hash you + get hash of malware. Here are security considerations for this scenario: </para> + <itemizedlist> <listitem> <para> @@ -972,7 +975,8 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable> </listitem> <listitem> <para> - hashes from upstream (in method 3) should be obtained via secure protocol; + hashes from upstream (in method 3) should be obtained via secure + protocol; </para> </listitem> <listitem> @@ -982,12 +986,12 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable> </listitem> <listitem> <para> - <literal>https://</literal> URLs are not secure in method 5. When obtaining hashes - with fake hash method, TLS checks are disabled. So - refetch source hash from several different networks to exclude MITM scenario. - Alternatively, use fake hash method to make Nix error, but instead of extracting - hash from error, extract <literal>https://</literal> URL and prefetch it - with method 1. + <literal>https://</literal> URLs are not secure in method 5. When + obtaining hashes with fake hash method, TLS checks are disabled. So + refetch source hash from several different networks to exclude MITM + scenario. Alternatively, use fake hash method to make Nix error, but + instead of extracting hash from error, extract + <literal>https://</literal> URL and prefetch it with method 1. </para> </listitem> </itemizedlist> diff --git a/doc/configuration.xml b/doc/configuration.xml index 8a5ff8dcb8e..b497fa4e272 100644 --- a/doc/configuration.xml +++ b/doc/configuration.xml @@ -132,13 +132,13 @@ </itemizedlist> <para> - The difference between a package being unsupported on some system and - being broken is admittedly a bit fuzzy. If a program - <emphasis>ought</emphasis> to work on a certain platform, but doesn't, the - platform should be included in <literal>meta.platforms</literal>, but marked - as broken with e.g. <literal>meta.broken = - !hostPlatform.isWindows</literal>. Of course, this begs the question of what - "ought" means exactly. That is left to the package maintainer. + The difference between a package being unsupported on some system and being + broken is admittedly a bit fuzzy. If a program <emphasis>ought</emphasis> to + work on a certain platform, but doesn't, the platform should be included in + <literal>meta.platforms</literal>, but marked as broken with e.g. + <literal>meta.broken = !hostPlatform.isWindows</literal>. Of course, this + begs the question of what "ought" means exactly. That is left to the package + maintainer. </para> </section> <section xml:id="sec-allow-unfree"> @@ -175,9 +175,8 @@ </programlisting> </para> <para> - For a more useful example, try the following. This configuration - only allows unfree packages named flash player and visual studio - code: + For a more useful example, try the following. This configuration only + allows unfree packages named flash player and visual studio code: <programlisting> { allowUnfreePredicate = (pkg: builtins.elem diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml index 324fe5bdd02..dbaf6f104ec 100644 --- a/doc/cross-compilation.xml +++ b/doc/cross-compilation.xml @@ -6,17 +6,17 @@ <title>Introduction</title> <para> - "Cross-compilation" means compiling a program on one machine for another type - of machine. For example, a typical use of cross-compilation is to compile - programs for embedded devices. These devices often don't have the computing - power and memory to compile their own programs. One might think that - cross-compilation is a fairly niche concern. However, there are significant - advantages to rigorously distinguishing between build-time and run-time - environments! This applies even when one is developing and deploying on the - same machine. Nixpkgs is increasingly adopting the opinion that packages - should be written with cross-compilation in mind, and nixpkgs should evaluate - in a similar way (by minimizing cross-compilation-specific special cases) - whether or not one is cross-compiling. + "Cross-compilation" means compiling a program on one machine for another + type of machine. For example, a typical use of cross-compilation is to + compile programs for embedded devices. These devices often don't have the + computing power and memory to compile their own programs. One might think + that cross-compilation is a fairly niche concern. However, there are + significant advantages to rigorously distinguishing between build-time and + run-time environments! This applies even when one is developing and + deploying on the same machine. Nixpkgs is increasingly adopting the opinion + that packages should be written with cross-compilation in mind, and nixpkgs + should evaluate in a similar way (by minimizing cross-compilation-specific + special cases) whether or not one is cross-compiling. </para> <para> @@ -34,15 +34,16 @@ <title>Platform parameters</title> <para> - Nixpkgs follows the <link + Nixpkgs follows the + <link xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html">conventions - of GNU autoconf</link>. We distinguish between 3 types of platforms when - building a derivation: <wordasword>build</wordasword>, - <wordasword>host</wordasword>, and <wordasword>target</wordasword>. In - summary, <wordasword>build</wordasword> is the platform on which a package - is being built, <wordasword>host</wordasword> is the platform on which it - will run. The third attribute, <wordasword>target</wordasword>, is relevant - only for certain specific compilers and build tools. + of GNU autoconf</link>. We distinguish between 3 types of platforms when + building a derivation: <wordasword>build</wordasword>, + <wordasword>host</wordasword>, and <wordasword>target</wordasword>. In + summary, <wordasword>build</wordasword> is the platform on which a package + is being built, <wordasword>host</wordasword> is the platform on which it + will run. The third attribute, <wordasword>target</wordasword>, is relevant + only for certain specific compilers and build tools. </para> <para> @@ -95,10 +96,10 @@ The build process of certain compilers is written in such a way that the compiler resulting from a single build can itself only produce binaries for a single platform. The task of specifying this single "target - platform" is thus pushed to build time of the compiler. The root cause of - this is that the compiler (which will be run on the host) and the standard - library/runtime (which will be run on the target) are built by a single - build process. + platform" is thus pushed to build time of the compiler. The root cause + of this is that the compiler (which will be run on the host) and the + standard library/runtime (which will be run on the target) are built by + a single build process. </para> <para> There is no fundamental need to think about a single target ahead of @@ -136,9 +137,9 @@ This is a two-component shorthand for the platform. Examples of this would be "x86_64-darwin" and "i686-linux"; see <literal>lib.systems.doubles</literal> for more. The first component - corresponds to the CPU architecture of the platform and the second to the - operating system of the platform (<literal>[cpu]-[os]</literal>). This - format has built-in support in Nix, such as the + corresponds to the CPU architecture of the platform and the second to + the operating system of the platform (<literal>[cpu]-[os]</literal>). + This format has built-in support in Nix, such as the <varname>builtins.currentSystem</varname> impure string. </para> </listitem> @@ -149,14 +150,14 @@ </term> <listitem> <para> - This is a 3- or 4- component shorthand for the platform. Examples of this - would be <literal>x86_64-unknown-linux-gnu</literal> and + This is a 3- or 4- component shorthand for the platform. Examples of + this would be <literal>x86_64-unknown-linux-gnu</literal> and <literal>aarch64-apple-darwin14</literal>. This is a standard format called the "LLVM target triple", as they are pioneered by LLVM. In the 4-part form, this corresponds to <literal>[cpu]-[vendor]-[os]-[abi]</literal>. This format is strictly - more informative than the "Nix host double", as the previous format could - analogously be termed. This needs a better name than + more informative than the "Nix host double", as the previous format + could analogously be termed. This needs a better name than <varname>config</varname>! </para> </listitem> @@ -167,11 +168,10 @@ </term> <listitem> <para> - This is a Nix representation of a parsed LLVM target triple - with white-listed components. This can be specified directly, - or actually parsed from the <varname>config</varname>. See - <literal>lib.systems.parse</literal> for the exact - representation. + This is a Nix representation of a parsed LLVM target triple with + white-listed components. This can be specified directly, or actually + parsed from the <varname>config</varname>. See + <literal>lib.systems.parse</literal> for the exact representation. </para> </listitem> </varlistentry> @@ -253,15 +253,15 @@ <para> Some examples will make this clearer. If a package is being built with a <literal>(build, host, target)</literal> platform triple of <literal>(foo, - bar, bar)</literal>, then its build-time dependencies would have a triple of - <literal>(foo, foo, bar)</literal>, and <emphasis>those packages'</emphasis> - build-time dependencies would have a triple of <literal>(foo, foo, - foo)</literal>. In other words, it should take two "rounds" of following - build-time dependency edges before one reaches a fixed point where, by the - sliding window principle, the platform triple no longer changes. Indeed, - this happens with cross-compilation, where only rounds of native - dependencies starting with the second necessarily coincide with native - packages. + bar, bar)</literal>, then its build-time dependencies would have a triple + of <literal>(foo, foo, bar)</literal>, and <emphasis>those + packages'</emphasis> build-time dependencies would have a triple of + <literal>(foo, foo, foo)</literal>. In other words, it should take two + "rounds" of following build-time dependency edges before one reaches a + fixed point where, by the sliding window principle, the platform triple no + longer changes. Indeed, this happens with cross-compilation, where only + rounds of native dependencies starting with the second necessarily coincide + with native packages. </para> <note> @@ -273,23 +273,24 @@ </note> <para> - How does this work in practice? Nixpkgs is now structured so that build-time - dependencies are taken from <varname>buildPackages</varname>, whereas - run-time dependencies are taken from the top level attribute set. For - example, <varname>buildPackages.gcc</varname> should be used at build-time, - while <varname>gcc</varname> should be used at run-time. Now, for most of - Nixpkgs's history, there was no <varname>buildPackages</varname>, and most - packages have not been refactored to use it explicitly. Instead, one can use - the six (<emphasis>gasp</emphasis>) attributes used for specifying - dependencies as documented in <xref linkend="ssec-stdenv-dependencies"/>. We - "splice" together the run-time and build-time package sets with - <varname>callPackage</varname>, and then <varname>mkDerivation</varname> for - each of four attributes pulls the right derivation out. This splicing can be - skipped when not cross-compiling as the package sets are the same, but is a - bit slow for cross-compiling. Because of this, a best-of-both-worlds - solution is in the works with no splicing or explicit access of - <varname>buildPackages</varname> needed. For now, feel free to use either - method. + How does this work in practice? Nixpkgs is now structured so that + build-time dependencies are taken from <varname>buildPackages</varname>, + whereas run-time dependencies are taken from the top level attribute set. + For example, <varname>buildPackages.gcc</varname> should be used at + build-time, while <varname>gcc</varname> should be used at run-time. Now, + for most of Nixpkgs's history, there was no + <varname>buildPackages</varname>, and most packages have not been + refactored to use it explicitly. Instead, one can use the six + (<emphasis>gasp</emphasis>) attributes used for specifying dependencies as + documented in <xref linkend="ssec-stdenv-dependencies"/>. We "splice" + together the run-time and build-time package sets with + <varname>callPackage</varname>, and then <varname>mkDerivation</varname> + for each of four attributes pulls the right derivation out. This splicing + can be skipped when not cross-compiling as the package sets are the same, + but is a bit slow for cross-compiling. Because of this, a + best-of-both-worlds solution is in the works with no splicing or explicit + access of <varname>buildPackages</varname> needed. For now, feel free to + use either method. </para> <note> @@ -311,8 +312,8 @@ should be answered here. Ideally, the information above is exhaustive, so this section cannot provide any new information, but it is ludicrous and cruel to expect everyone to spend effort working through the interaction of - many features just to figure out the same answer to the same common problem. - Feel free to add to this list! + many features just to figure out the same answer to the same common + problem. Feel free to add to this list! </para> <qandaset> @@ -434,14 +435,15 @@ nix-build <nixpkgs> --arg crossSystem '{ config = "<arch>-<os> build plan or package set. A simple "build vs deploy" dichotomy is adequate: the sliding window principle described in the previous section shows how to interpolate between the these two "end points" to get the 3 platform triple - for each bootstrapping stage. That means for any package a given package set, - even those not bound on the top level but only reachable via dependencies or - <varname>buildPackages</varname>, the three platforms will be defined as one - of <varname>localSystem</varname> or <varname>crossSystem</varname>, with the - former replacing the latter as one traverses build-time dependencies. A last - simple difference is that <varname>crossSystem</varname> should be null when - one doesn't want to cross-compile, while the <varname>*Platform</varname>s - are always non-null. <varname>localSystem</varname> is always non-null. + for each bootstrapping stage. That means for any package a given package + set, even those not bound on the top level but only reachable via + dependencies or <varname>buildPackages</varname>, the three platforms will + be defined as one of <varname>localSystem</varname> or + <varname>crossSystem</varname>, with the former replacing the latter as one + traverses build-time dependencies. A last simple difference is that + <varname>crossSystem</varname> should be null when one doesn't want to + cross-compile, while the <varname>*Platform</varname>s are always non-null. + <varname>localSystem</varname> is always non-null. </para> </section> <!--============================================================--> @@ -455,13 +457,13 @@ nix-build <nixpkgs> --arg crossSystem '{ config = "<arch>-<os> <note> <para> If one explores Nixpkgs, they will see derivations with names like - <literal>gccCross</literal>. Such <literal>*Cross</literal> derivations is a - holdover from before we properly distinguished between the host and target - platforms—the derivation with "Cross" in the name covered the <literal>build - = host != target</literal> case, while the other covered the <literal>host = - target</literal>, with build platform the same or not based on whether one - was using its <literal>.nativeDrv</literal> or <literal>.crossDrv</literal>. - This ugliness will disappear soon. + <literal>gccCross</literal>. Such <literal>*Cross</literal> derivations is + a holdover from before we properly distinguished between the host and + target platforms—the derivation with "Cross" in the name covered the + <literal>build = host != target</literal> case, while the other covered the + <literal>host = target</literal>, with build platform the same or not based + on whether one was using its <literal>.nativeDrv</literal> or + <literal>.crossDrv</literal>. This ugliness will disappear soon. </para> </note> </section> diff --git a/doc/functions/appimagetools.xml b/doc/functions/appimagetools.xml index 270ab067bc3..4205c6da385 100644 --- a/doc/functions/appimagetools.xml +++ b/doc/functions/appimagetools.xml @@ -5,11 +5,11 @@ <title>pkgs.appimageTools</title> <para> - <varname>pkgs.appimageTools</varname> is a set of functions for extracting and wrapping - <link xlink:href="https://appimage.org/">AppImage</link> files. - - They are meant to be used if traditional packaging from source is infeasible, or it would take too long. - To quickly run an AppImage file, <literal>pkgs.appimage-run</literal> can be used as well. + <varname>pkgs.appimageTools</varname> is a set of functions for extracting + and wrapping <link xlink:href="https://appimage.org/">AppImage</link> files. + They are meant to be used if traditional packaging from source is infeasible, + or it would take too long. To quickly run an AppImage file, + <literal>pkgs.appimage-run</literal> can be used as well. </para> <warning> @@ -19,13 +19,13 @@ </para> </warning> - <section xml:id="ssec-pkgs-appimageTools-formats"> <title>AppImage formats</title> <para> There are different formats for AppImages, see - <link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the specification</link> for details. + <link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the + specification</link> for details. </para> <itemizedlist> @@ -34,7 +34,6 @@ Type 1 images are ISO 9660 files that are also ELF executables. </para> </listitem> - <listitem> <para> Type 2 images are ELF executables with an appended filesystem. @@ -46,7 +45,7 @@ They can be told apart with <command>file -k</command>: </para> - <screen> +<screen> <prompt>$ </prompt>file -k type1.AppImage type1.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) ISO 9660 CD-ROM filesystem data 'AppImage' (Lepton 3.x), scale 0-0, spot sensor temperature 0.000000, unit celsius, color scheme 0, calibration: offset 0.000000, slope 0.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=d629f6099d2344ad82818172add1d38c5e11bc6d, stripped\012- data @@ -56,7 +55,8 @@ type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x) </screen> <para> - Note how the type 1 AppImage is described as an <literal>ISO 9660 CD-ROM filesystem</literal>, and the type 2 AppImage is not. + Note how the type 1 AppImage is described as an <literal>ISO 9660 CD-ROM + filesystem</literal>, and the type 2 AppImage is not. </para> </section> @@ -64,12 +64,11 @@ type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x) <title>Wrapping</title> <para> - Depending on the type of AppImage you're wrapping, you'll have to use - <varname>wrapType1</varname> or <varname>wrapType2</varname>. + Depending on the type of AppImage you're wrapping, you'll have to use + <varname>wrapType1</varname> or <varname>wrapType2</varname>. </para> - - <programlisting> +<programlisting> appimageTools.wrapType2 { # or wrapType1 name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' /> src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' /> @@ -79,7 +78,6 @@ appimageTools.wrapType2 { # or wrapType1 extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' /> }</programlisting> - <calloutlist> <callout arearefs='ex-appimageTools-wrapping-1'> <para> @@ -93,29 +91,28 @@ appimageTools.wrapType2 { # or wrapType1 </callout> <callout arearefs='ex-appimageTools-wrapping-2'> <para> - <varname>extraPkgs</varname> allows you to pass a function to include additional packages - inside the FHS environment your AppImage is going to run in. - - There are a few ways to learn which dependencies an application needs: - - <itemizedlist> - <listitem> - <para> - Looking through the extracted AppImage files, reading its scripts and running <command>patchelf</command> and <command>ldd</command> on its executables. - This can also be done in <command>appimage-run</command>, by setting <command>APPIMAGE_DEBUG_EXEC=bash</command>. - </para> - </listitem> - - <listitem> - <para> - Running <command>strace -vfefile</command> on the wrapped executable, looking for libraries that can't be found. - </para> - </listitem> - </itemizedlist> - + <varname>extraPkgs</varname> allows you to pass a function to include + additional packages inside the FHS environment your AppImage is going to + run in. There are a few ways to learn which dependencies an application + needs: + <itemizedlist> + <listitem> + <para> + Looking through the extracted AppImage files, reading its scripts and + running <command>patchelf</command> and <command>ldd</command> on its + executables. This can also be done in <command>appimage-run</command>, + by setting <command>APPIMAGE_DEBUG_EXEC=bash</command>. + </para> + </listitem> + <listitem> + <para> + Running <command>strace -vfefile</command> on the wrapped executable, + looking for libraries that can't be found. + </para> + </listitem> + </itemizedlist> </para> </callout> </calloutlist> - </section> </section> diff --git a/doc/functions/dockertools.xml b/doc/functions/dockertools.xml index 2c8eb2cb774..75db0bd3918 100644 --- a/doc/functions/dockertools.xml +++ b/doc/functions/dockertools.xml @@ -24,9 +24,9 @@ <para> This function is analogous to the <command>docker build</command> command, - in that it can be used to build a Docker-compatible repository tarball containing - a single image with one or multiple layers. As such, the result is suitable - for being loaded in Docker with <command>docker load</command>. + in that it can be used to build a Docker-compatible repository tarball + containing a single image with one or multiple layers. As such, the result + is suitable for being loaded in Docker with <command>docker load</command>. </para> <para> @@ -190,8 +190,8 @@ buildImage { By default <function>buildImage</function> will use a static date of one second past the UNIX Epoch. This allows <function>buildImage</function> to produce binary reproducible images. When listing images with - <command>docker images</command>, the newly created images will be - listed like this: + <command>docker images</command>, the newly created images will be listed + like this: </para> <screen><![CDATA[ $ docker images @@ -402,9 +402,9 @@ pkgs.dockerTools.buildLayeredImage { <para> This function is analogous to the <command>docker pull</command> command, in - that it can be used to pull a Docker image from a Docker registry. By default - <link xlink:href="https://hub.docker.com/">Docker Hub</link> is used to pull - images. + that it can be used to pull a Docker image from a Docker registry. By + default <link xlink:href="https://hub.docker.com/">Docker Hub</link> is used + to pull images. </para> <para> @@ -484,10 +484,10 @@ sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b <para> This function is analogous to the <command>docker export</command> command, - in that it can be used to flatten a Docker image that contains multiple layers. It - is in fact the result of the merge of all the layers of the image. As such, - the result is suitable for being imported in Docker with <command>docker - import</command>. + in that it can be used to flatten a Docker image that contains multiple + layers. It is in fact the result of the merge of all the layers of the + image. As such, the result is suitable for being imported in Docker with + <command>docker import</command>. </para> <note> diff --git a/doc/functions/fetchers.xml b/doc/functions/fetchers.xml index b3bd2fe0f45..a736008c9d4 100644 --- a/doc/functions/fetchers.xml +++ b/doc/functions/fetchers.xml @@ -5,24 +5,21 @@ <title>Fetcher functions</title> <para> - When using Nix, you will frequently need to download source code - and other files from the internet. Nixpkgs comes with a few helper - functions that allow you to fetch fixed-output derivations in a - structured way. + When using Nix, you will frequently need to download source code and other + files from the internet. Nixpkgs comes with a few helper functions that allow + you to fetch fixed-output derivations in a structured way. </para> <para> - The two fetcher primitives are <function>fetchurl</function> and - <function>fetchzip</function>. Both of these have two required - arguments, a URL and a hash. The hash is typically - <literal>sha256</literal>, although many more hash algorithms are - supported. Nixpkgs contributors are currently recommended to use - <literal>sha256</literal>. This hash will be used by Nix to - identify your source. A typical usage of fetchurl is provided - below. + The two fetcher primitives are <function>fetchurl</function> and + <function>fetchzip</function>. Both of these have two required arguments, a + URL and a hash. The hash is typically <literal>sha256</literal>, although + many more hash algorithms are supported. Nixpkgs contributors are currently + recommended to use <literal>sha256</literal>. This hash will be used by Nix + to identify your source. A typical usage of fetchurl is provided below. </para> - <programlisting><![CDATA[ +<programlisting><![CDATA[ { stdenv, fetchurl }: stdenv.mkDerivation { @@ -35,172 +32,163 @@ stdenv.mkDerivation { ]]></programlisting> <para> - The main difference between <function>fetchurl</function> and - <function>fetchzip</function> is in how they store the contents. - <function>fetchurl</function> will store the unaltered contents of - the URL within the Nix store. <function>fetchzip</function> on the - other hand will decompress the archive for you, making files and - directories directly accessible in the future. - <function>fetchzip</function> can only be used with archives. - Despite the name, <function>fetchzip</function> is not limited to - .zip files and can also be used with any tarball. + The main difference between <function>fetchurl</function> and + <function>fetchzip</function> is in how they store the contents. + <function>fetchurl</function> will store the unaltered contents of the URL + within the Nix store. <function>fetchzip</function> on the other hand will + decompress the archive for you, making files and directories directly + accessible in the future. <function>fetchzip</function> can only be used with + archives. Despite the name, <function>fetchzip</function> is not limited to + .zip files and can also be used with any tarball. </para> <para> - <function>fetchpatch</function> works very similarly to - <function>fetchurl</function> with the same arguments expected. It - expects patch files as a source and and performs normalization on - them before computing the checksum. For example it will remove - comments or other unstable parts that are sometimes added by - version control systems and can change over time. + <function>fetchpatch</function> works very similarly to + <function>fetchurl</function> with the same arguments expected. It expects + patch files as a source and and performs normalization on them before + computing the checksum. For example it will remove comments or other unstable + parts that are sometimes added by version control systems and can change over + time. </para> <para> - Other fetcher functions allow you to add source code directly from - a VCS such as subversion or git. These are mostly straightforward - names based on the name of the command used with the VCS system. - Because they give you a working repository, they act most like - <function>fetchzip</function>. + Other fetcher functions allow you to add source code directly from a VCS such + as subversion or git. These are mostly straightforward names based on the + name of the command used with the VCS system. Because they give you a working + repository, they act most like <function>fetchzip</function>. </para> <variablelist> - <varlistentry> - <term> - <literal>fetchsvn</literal> - </term> - <listitem> - <para> - Used with Subversion. Expects <literal>url</literal> to a - Subversion directory, <literal>rev</literal>, and - <literal>sha256</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>fetchgit</literal> - </term> - <listitem> - <para> - Used with Git. Expects <literal>url</literal> to a Git repo, - <literal>rev</literal>, and <literal>sha256</literal>. - <literal>rev</literal> in this case can be full the git commit - id (SHA1 hash) or a tag name like - <literal>refs/tags/v1.0</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>fetchfossil</literal> - </term> - <listitem> - <para> - Used with Fossil. Expects <literal>url</literal> to a Fossil - archive, <literal>rev</literal>, and <literal>sha256</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>fetchcvs</literal> - </term> - <listitem> - <para> - Used with CVS. Expects <literal>cvsRoot</literal>, - <literal>tag</literal>, and <literal>sha256</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>fetchhg</literal> - </term> - <listitem> - <para> - Used with Mercurial. Expects <literal>url</literal>, - <literal>rev</literal>, and <literal>sha256</literal>. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term> + <literal>fetchsvn</literal> + </term> + <listitem> + <para> + Used with Subversion. Expects <literal>url</literal> to a Subversion + directory, <literal>rev</literal>, and <literal>sha256</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchgit</literal> + </term> + <listitem> + <para> + Used with Git. Expects <literal>url</literal> to a Git repo, + <literal>rev</literal>, and <literal>sha256</literal>. + <literal>rev</literal> in this case can be full the git commit id (SHA1 + hash) or a tag name like <literal>refs/tags/v1.0</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchfossil</literal> + </term> + <listitem> + <para> + Used with Fossil. Expects <literal>url</literal> to a Fossil archive, + <literal>rev</literal>, and <literal>sha256</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchcvs</literal> + </term> + <listitem> + <para> + Used with CVS. Expects <literal>cvsRoot</literal>, <literal>tag</literal>, + and <literal>sha256</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchhg</literal> + </term> + <listitem> + <para> + Used with Mercurial. Expects <literal>url</literal>, + <literal>rev</literal>, and <literal>sha256</literal>. + </para> + </listitem> + </varlistentry> </variablelist> <para> - A number of fetcher functions wrap part of - <function>fetchurl</function> and <function>fetchzip</function>. - They are mainly convenience functions intended for commonly used - destinations of source code in Nixpkgs. These wrapper fetchers are - listed below. + A number of fetcher functions wrap part of <function>fetchurl</function> and + <function>fetchzip</function>. They are mainly convenience functions intended + for commonly used destinations of source code in Nixpkgs. These wrapper + fetchers are listed below. </para> <variablelist> - <varlistentry> - <term> - <literal>fetchFromGitHub</literal> - </term> - <listitem> - <para> - <function>fetchFromGitHub</function> expects four arguments. - <literal>owner</literal> is a string corresponding to the - GitHub user or organization that controls this repository. - <literal>repo</literal> corresponds to the name of the - software repository. These are located at the top of every - GitHub HTML page as - <literal>owner</literal>/<literal>repo</literal>. - <literal>rev</literal> corresponds to the Git commit hash or - tag (e.g <literal>v1.0</literal>) that will be downloaded from - Git. Finally, <literal>sha256</literal> corresponds to the - hash of the extracted directory. Again, other hash algorithms - are also available but <literal>sha256</literal> is currently - preferred. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>fetchFromGitLab</literal> - </term> - <listitem> - <para> - This is used with GitLab repositories. The arguments expected - are very similar to fetchFromGitHub above. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>fetchFromBitbucket</literal> - </term> - <listitem> - <para> - This is used with BitBucket repositories. The arguments expected - are very similar to fetchFromGitHub above. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>fetchFromSavannah</literal> - </term> - <listitem> - <para> - This is used with Savannah repositories. The arguments expected - are very similar to fetchFromGitHub above. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>fetchFromRepoOrCz</literal> - </term> - <listitem> - <para> - This is used with repo.or.cz repositories. The arguments - expected are very similar to fetchFromGitHub above. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term> + <literal>fetchFromGitHub</literal> + </term> + <listitem> + <para> + <function>fetchFromGitHub</function> expects four arguments. + <literal>owner</literal> is a string corresponding to the GitHub user or + organization that controls this repository. <literal>repo</literal> + corresponds to the name of the software repository. These are located at + the top of every GitHub HTML page as + <literal>owner</literal>/<literal>repo</literal>. <literal>rev</literal> + corresponds to the Git commit hash or tag (e.g <literal>v1.0</literal>) + that will be downloaded from Git. Finally, <literal>sha256</literal> + corresponds to the hash of the extracted directory. Again, other hash + algorithms are also available but <literal>sha256</literal> is currently + preferred. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchFromGitLab</literal> + </term> + <listitem> + <para> + This is used with GitLab repositories. The arguments expected are very + similar to fetchFromGitHub above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchFromBitbucket</literal> + </term> + <listitem> + <para> + This is used with BitBucket repositories. The arguments expected are very + similar to fetchFromGitHub above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchFromSavannah</literal> + </term> + <listitem> + <para> + This is used with Savannah repositories. The arguments expected are very + similar to fetchFromGitHub above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchFromRepoOrCz</literal> + </term> + <listitem> + <para> + This is used with repo.or.cz repositories. The arguments expected are very + similar to fetchFromGitHub above. + </para> + </listitem> + </varlistentry> </variablelist> - - </section> diff --git a/doc/functions/library.xml b/doc/functions/library.xml index b01de3c6e41..e6aedaa6efd 100644 --- a/doc/functions/library.xml +++ b/doc/functions/library.xml @@ -13,12 +13,17 @@ <xi:include href="./library/attrsets.xml" /> - <!-- These docs are generated via nixdoc. To add another generated +<!-- These docs are generated via nixdoc. To add another generated library function file to this list, the file `lib-function-docs.nix` must also be updated. --> + <xi:include href="./library/generated/strings.xml" /> + <xi:include href="./library/generated/trivial.xml" /> + <xi:include href="./library/generated/lists.xml" /> + <xi:include href="./library/generated/debug.xml" /> + <xi:include href="./library/generated/options.xml" /> </section> diff --git a/doc/functions/nix-gitignore.xml b/doc/functions/nix-gitignore.xml index 465b38e0bf1..9011570d1ea 100644 --- a/doc/functions/nix-gitignore.xml +++ b/doc/functions/nix-gitignore.xml @@ -14,15 +14,15 @@ <title>Usage</title> <para> - <literal>pkgs.nix-gitignore</literal> exports a number of functions, but - you'll most likely need either <literal>gitignoreSource</literal> or - <literal>gitignoreSourcePure</literal>. As their first argument, they both - accept either 1. a file with gitignore lines or 2. a string - with gitignore lines, or 3. a list of either of the two. They will be - concatenated into a single big string. + <literal>pkgs.nix-gitignore</literal> exports a number of functions, but + you'll most likely need either <literal>gitignoreSource</literal> or + <literal>gitignoreSourcePure</literal>. As their first argument, they both + accept either 1. a file with gitignore lines or 2. a string with gitignore + lines, or 3. a list of either of the two. They will be concatenated into a + single big string. </para> - <programlisting><![CDATA[ +<programlisting><![CDATA[ { pkgs ? import <nixpkgs> {} }: nix-gitignore.gitignoreSource [] ./source @@ -40,24 +40,29 @@ ]]></programlisting> <para> - These functions are derived from the <literal>Filter</literal> functions - by setting the first filter argument to <literal>(_: _: true)</literal>: + These functions are derived from the <literal>Filter</literal> functions by + setting the first filter argument to <literal>(_: _: true)</literal>: </para> - <programlisting><![CDATA[ +<programlisting><![CDATA[ gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true); gitignoreSource = gitignoreFilterSource (_: _: true); ]]></programlisting> <para> - Those filter functions accept the same arguments the <literal>builtins.filterSource</literal> function would pass to its filters, thus <literal>fn: gitignoreFilterSourcePure fn ""</literal> should be extensionally equivalent to <literal>filterSource</literal>. The file is blacklisted iff it's blacklisted by either your filter or the gitignoreFilter. + Those filter functions accept the same arguments the + <literal>builtins.filterSource</literal> function would pass to its filters, + thus <literal>fn: gitignoreFilterSourcePure fn ""</literal> should be + extensionally equivalent to <literal>filterSource</literal>. The file is + blacklisted iff it's blacklisted by either your filter or the + gitignoreFilter. </para> <para> - If you want to make your own filter from scratch, you may use - </para> + If you want to make your own filter from scratch, you may use + </para> - <programlisting><![CDATA[ +<programlisting><![CDATA[ gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root; ]]></programlisting> </section> @@ -66,10 +71,11 @@ gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root; <title>gitignore files in subdirectories</title> <para> - If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function: - </para> + If you wish to use a filter that would search for .gitignore files in + subdirectories, just like git does by default, use this function: + </para> - <programlisting><![CDATA[ +<programlisting><![CDATA[ gitignoreFilterRecursiveSource = filter: patterns: root: # OR gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true); diff --git a/doc/functions/prefer-remote-fetch.xml b/doc/functions/prefer-remote-fetch.xml index 85f08f4eae1..2ccad921806 100644 --- a/doc/functions/prefer-remote-fetch.xml +++ b/doc/functions/prefer-remote-fetch.xml @@ -7,17 +7,15 @@ <para> <function>prefer-remote-fetch</function> is an overlay that download sources on remote builder. This is useful when the evaluating machine has a slow - upload while the builder can fetch faster directly from the source. - To use it, put the following snippet as a new overlay: - <programlisting> + upload while the builder can fetch faster directly from the source. To use + it, put the following snippet as a new overlay: +<programlisting> self: super: (super.prefer-remote-fetch self super) </programlisting> - - A full configuration example for that sets the overlay up for your own account, - could look like this - - <programlisting> + A full configuration example for that sets the overlay up for your own + account, could look like this +<programlisting> $ mkdir ~/.config/nixpkgs/overlays/ $ cat > ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix <<EOF self: super: super.prefer-remote-fetch self super diff --git a/doc/functions/trivial-builders.xml b/doc/functions/trivial-builders.xml index 92a07aedb5b..1fd92ecfe26 100644 --- a/doc/functions/trivial-builders.xml +++ b/doc/functions/trivial-builders.xml @@ -5,12 +5,11 @@ <title>Trivial builders</title> <para> - Nixpkgs provides a couple of functions that help with building - derivations. The most important one, - <function>stdenv.mkDerivation</function>, has already been - documented above. The following functions wrap - <function>stdenv.mkDerivation</function>, making it easier to use - in certain cases. + Nixpkgs provides a couple of functions that help with building derivations. + The most important one, <function>stdenv.mkDerivation</function>, has already + been documented above. The following functions wrap + <function>stdenv.mkDerivation</function>, making it easier to use in certain + cases. </para> <variablelist> @@ -19,26 +18,23 @@ <literal>runCommand</literal> </term> <listitem> - <para> - This takes three arguments, <literal>name</literal>, - <literal>env</literal>, and <literal>buildCommand</literal>. - <literal>name</literal> is just the name that Nix will append - to the store path in the same way that - <literal>stdenv.mkDerivation</literal> uses its - <literal>name</literal> attribute. <literal>env</literal> is an - attribute set specifying environment variables that will be set - for this derivation. These attributes are then passed to the - wrapped <literal>stdenv.mkDerivation</literal>. - <literal>buildCommand</literal> specifies the commands that - will be run to create this derivation. Note that you will need - to create <literal>$out</literal> for Nix to register the - command as successful. - </para> - <para> - An example of using <literal>runCommand</literal> is provided - below. - </para> - <programlisting> + <para> + This takes three arguments, <literal>name</literal>, + <literal>env</literal>, and <literal>buildCommand</literal>. + <literal>name</literal> is just the name that Nix will append to the store + path in the same way that <literal>stdenv.mkDerivation</literal> uses its + <literal>name</literal> attribute. <literal>env</literal> is an attribute + set specifying environment variables that will be set for this derivation. + These attributes are then passed to the wrapped + <literal>stdenv.mkDerivation</literal>. <literal>buildCommand</literal> + specifies the commands that will be run to create this derivation. Note + that you will need to create <literal>$out</literal> for Nix to register + the command as successful. + </para> + <para> + An example of using <literal>runCommand</literal> is provided below. + </para> +<programlisting> (import <nixpkgs> {}).runCommand "my-example" {} '' echo My example command is running @@ -65,41 +61,35 @@ <literal>runCommandCC</literal> </term> <listitem> - <para> - This works just like <literal>runCommand</literal>. The only - difference is that it also provides a C compiler in - <literal>buildCommand</literal>’s environment. To minimize your - dependencies, you should only use this if you are sure you will - need a C compiler as part of running your command. + <para> + This works just like <literal>runCommand</literal>. The only difference is + that it also provides a C compiler in <literal>buildCommand</literal>’s + environment. To minimize your dependencies, you should only use this if + you are sure you will need a C compiler as part of running your command. </para> </listitem> </varlistentry> <varlistentry> <term> - <literal>writeTextFile</literal>, <literal>writeText</literal>, - <literal>writeTextDir</literal>, <literal>writeScript</literal>, - <literal>writeScriptBin</literal> + <literal>writeTextFile</literal>, <literal>writeText</literal>, <literal>writeTextDir</literal>, <literal>writeScript</literal>, <literal>writeScriptBin</literal> </term> <listitem> - <para> - These functions write <literal>text</literal> to the Nix store. - This is useful for creating scripts from Nix expressions. - <literal>writeTextFile</literal> takes an attribute set and - expects two arguments, <literal>name</literal> and - <literal>text</literal>. <literal>name</literal> corresponds to - the name used in the Nix store path. <literal>text</literal> - will be the contents of the file. You can also set - <literal>executable</literal> to true to make this file have - the executable bit set. - </para> - <para> - Many more commands wrap <literal>writeTextFile</literal> - including <literal>writeText</literal>, - <literal>writeTextDir</literal>, - <literal>writeScript</literal>, and - <literal>writeScriptBin</literal>. These are convenience - functions over <literal>writeTextFile</literal>. - </para> + <para> + These functions write <literal>text</literal> to the Nix store. This is + useful for creating scripts from Nix expressions. + <literal>writeTextFile</literal> takes an attribute set and expects two + arguments, <literal>name</literal> and <literal>text</literal>. + <literal>name</literal> corresponds to the name used in the Nix store + path. <literal>text</literal> will be the contents of the file. You can + also set <literal>executable</literal> to true to make this file have the + executable bit set. + </para> + <para> + Many more commands wrap <literal>writeTextFile</literal> including + <literal>writeText</literal>, <literal>writeTextDir</literal>, + <literal>writeScript</literal>, and <literal>writeScriptBin</literal>. + These are convenience functions over <literal>writeTextFile</literal>. + </para> </listitem> </varlistentry> <varlistentry> @@ -109,16 +99,15 @@ <listitem> <para> This can be used to put many derivations into the same directory - structure. It works by creating a new derivation and adding - symlinks to each of the paths listed. It expects two arguments, + structure. It works by creating a new derivation and adding symlinks to + each of the paths listed. It expects two arguments, <literal>name</literal>, and <literal>paths</literal>. - <literal>name</literal> is the name used in the Nix store path - for the created derivation. <literal>paths</literal> is a list of - paths that will be symlinked. These paths can be to Nix store - derivations or any other subdirectory contained within. + <literal>name</literal> is the name used in the Nix store path for the + created derivation. <literal>paths</literal> is a list of paths that will + be symlinked. These paths can be to Nix store derivations or any other + subdirectory contained within. </para> </listitem> </varlistentry> </variablelist> - </section> diff --git a/doc/languages-frameworks/ocaml.xml b/doc/languages-frameworks/ocaml.xml index ea077061680..0deadf2edd0 100644 --- a/doc/languages-frameworks/ocaml.xml +++ b/doc/languages-frameworks/ocaml.xml @@ -4,39 +4,38 @@ <title>OCaml</title> <para> - OCaml libraries should be installed in - <literal>$(out)/lib/ocaml/${ocaml.version}/site-lib/</literal>. Such - directories are automatically added to the <literal>$OCAMLPATH</literal> - environment variable when building another package that depends on them - or when opening a <literal>nix-shell</literal>. + OCaml libraries should be installed in + <literal>$(out)/lib/ocaml/${ocaml.version}/site-lib/</literal>. Such + directories are automatically added to the <literal>$OCAMLPATH</literal> + environment variable when building another package that depends on them or + when opening a <literal>nix-shell</literal>. </para> <para> - Given that most of the OCaml ecosystem is now built with dune, - nixpkgs includes a convenience build support function called - <literal>buildDunePackage</literal> that will build an OCaml package - using dune, OCaml and findlib and any additional dependencies provided - as <literal>buildInputs</literal> or <literal>propagatedBuildInputs</literal>. + Given that most of the OCaml ecosystem is now built with dune, nixpkgs + includes a convenience build support function called + <literal>buildDunePackage</literal> that will build an OCaml package using + dune, OCaml and findlib and any additional dependencies provided as + <literal>buildInputs</literal> or <literal>propagatedBuildInputs</literal>. </para> <para> - Here is a simple package example. It defines an (optional) attribute - <literal>minimumOCamlVersion</literal> that will be used to throw a - descriptive evaluation error if building with an older OCaml is attempted. - It uses the <literal>fetchFromGitHub</literal> fetcher to get its source. - It sets the <literal>doCheck</literal> (optional) attribute to - <literal>true</literal> which means that tests will be run with - <literal>dune runtest -p angstrom</literal> after the build - (<literal>dune build -p angstrom</literal>) is complete. - It uses <literal>alcotest</literal> as a build input (because it is needed - to run the tests) and <literal>bigstringaf</literal> and - <literal>result</literal> as propagated build inputs (thus they will also - be available to libraries depending on this library). - The library will be installed using the <literal>angstrom.install</literal> - file that dune generates. + Here is a simple package example. It defines an (optional) attribute + <literal>minimumOCamlVersion</literal> that will be used to throw a + descriptive evaluation error if building with an older OCaml is attempted. It + uses the <literal>fetchFromGitHub</literal> fetcher to get its source. It + sets the <literal>doCheck</literal> (optional) attribute to + <literal>true</literal> which means that tests will be run with <literal>dune + runtest -p angstrom</literal> after the build (<literal>dune build -p + angstrom</literal>) is complete. It uses <literal>alcotest</literal> as a + build input (because it is needed to run the tests) and + <literal>bigstringaf</literal> and <literal>result</literal> as propagated + build inputs (thus they will also be available to libraries depending on this + library). The library will be installed using the + <literal>angstrom.install</literal> file that dune generates. </para> - <programlisting> +<programlisting> { stdenv, fetchFromGitHub, buildDunePackage, alcotest, result, bigstringaf }: buildDunePackage rec { @@ -66,14 +65,14 @@ buildDunePackage rec { </programlisting> <para> - Here is a second example, this time using a source archive generated with - <literal>dune-release</literal>. It is a good idea to use this archive when - it is available as it will usually contain substituted variables such as a - <literal>%%VERSION%%</literal> field. This library does not depend - on any other OCaml library and no tests are run after building it. + Here is a second example, this time using a source archive generated with + <literal>dune-release</literal>. It is a good idea to use this archive when + it is available as it will usually contain substituted variables such as a + <literal>%%VERSION%%</literal> field. This library does not depend on any + other OCaml library and no tests are run after building it. </para> - <programlisting> +<programlisting> { stdenv, fetchurl, buildDunePackage }: buildDunePackage rec { @@ -95,5 +94,4 @@ buildDunePackage rec { }; } </programlisting> - </section> diff --git a/doc/package-notes.xml b/doc/package-notes.xml index e23593107d8..dfdada3d28c 100644 --- a/doc/package-notes.xml +++ b/doc/package-notes.xml @@ -307,19 +307,20 @@ packageOverrides = pkgs: { </screen> </para> </section> - <section xml:id="sec-elm"> <title>Elm</title> <para> - To update Elm compiler, see <filename>nixpkgs/pkgs/development/compilers/elm/README.md</filename>. + To update Elm compiler, see + <filename>nixpkgs/pkgs/development/compilers/elm/README.md</filename>. </para> <para> - To package Elm applications, <link xlink:href="https://github.com/hercules-ci/elm2nix#elm2nix">read about elm2nix</link>. + To package Elm applications, + <link xlink:href="https://github.com/hercules-ci/elm2nix#elm2nix">read about + elm2nix</link>. </para> </section> - <section xml:id="sec-shell-helpers"> <title>Interactive shell helpers</title> diff --git a/doc/platform-notes.xml b/doc/platform-notes.xml index 6050271dbf6..b75b50dbb96 100644 --- a/doc/platform-notes.xml +++ b/doc/platform-notes.xml @@ -96,8 +96,8 @@ </programlisting> <para> The package <literal>xcbuild</literal> can be used to build projects that - really depend on Xcode. However, this replacement is not 100% - compatible with Xcode and can occasionally cause issues. + really depend on Xcode. However, this replacement is not 100% compatible + with Xcode and can occasionally cause issues. </para> </listitem> </itemizedlist> diff --git a/doc/quick-start.xml b/doc/quick-start.xml index 8dd673ed273..86c17ca4e9f 100644 --- a/doc/quick-start.xml +++ b/doc/quick-start.xml @@ -148,8 +148,8 @@ $ git add pkgs/development/libraries/libfoo/default.nix</screen> <listitem> <para> You can use <command>nix-prefetch-url</command> - <replaceable>url</replaceable> to get the - SHA-256 hash of source distributions. There are similar commands as + <replaceable>url</replaceable> to get the SHA-256 hash of source + distributions. There are similar commands as <command>nix-prefetch-git</command> and <command>nix-prefetch-hg</command> available in <literal>nix-prefetch-scripts</literal> package. diff --git a/doc/reviewing-contributions.xml b/doc/reviewing-contributions.xml index f541b7f22da..d31c6deb490 100644 --- a/doc/reviewing-contributions.xml +++ b/doc/reviewing-contributions.xml @@ -24,11 +24,13 @@ <para> The high change rate of Nixpkgs makes any pull request that remains open for too long subject to conflicts that will require extra work from the submitter - or the merger. Reviewing pull requests in a timely manner and being responsive - to the comments is the key to avoid this issue. GitHub provides sort filters - that can be used to see the <link + or the merger. Reviewing pull requests in a timely manner and being + responsive to the comments is the key to avoid this issue. GitHub provides + sort filters that can be used to see the + <link xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc">most - recently</link> and the <link + recently</link> and the + <link xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc">least recently</link> updated pull requests. We highly encourage looking at <link xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+review%3Anone+status%3Asuccess+-label%3A%222.status%3A+work-in-progress%22+no%3Aproject+no%3Aassignee+no%3Amilestone"> @@ -609,8 +611,8 @@ policy. create an issue or post on <link xlink:href="https://discourse.nixos.org">Discourse</link> with - references of packages and modules they maintain so the maintainership can be - taken over by other contributors. + references of packages and modules they maintain so the maintainership can + be taken over by other contributors. </para> </section> </chapter> 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"> |