diff options
author | Alyssa Ross <hi@alyssa.is> | 2019-03-16 17:16:21 +0000 |
---|---|---|
committer | Alyssa Ross <hi@alyssa.is> | 2019-03-16 22:36:36 +0000 |
commit | cb6d0ec12187e0c2c11b203f3d8fa62790628141 (patch) | |
tree | 0ca0fedc67d5676e89438cffa3e0865eee0962e4 /nixpkgs/doc/functions | |
parent | 4d83b8e578d3a0b78d2694921c944172b009036a (diff) | |
parent | da1a2b1eeafa66b4419b4f275396d8a731eccb61 (diff) | |
download | nixlib-cb6d0ec12187e0c2c11b203f3d8fa62790628141.tar nixlib-cb6d0ec12187e0c2c11b203f3d8fa62790628141.tar.gz nixlib-cb6d0ec12187e0c2c11b203f3d8fa62790628141.tar.bz2 nixlib-cb6d0ec12187e0c2c11b203f3d8fa62790628141.tar.lz nixlib-cb6d0ec12187e0c2c11b203f3d8fa62790628141.tar.xz nixlib-cb6d0ec12187e0c2c11b203f3d8fa62790628141.tar.zst nixlib-cb6d0ec12187e0c2c11b203f3d8fa62790628141.zip |
Merge commit 'da1a2b1eeafa66b4419b4f275396d8a731eccb61'
Diffstat (limited to 'nixpkgs/doc/functions')
-rw-r--r-- | nixpkgs/doc/functions/appimagetools.xml | 69 | ||||
-rw-r--r-- | nixpkgs/doc/functions/dockertools.xml | 24 | ||||
-rw-r--r-- | nixpkgs/doc/functions/fetchers.xml | 318 | ||||
-rw-r--r-- | nixpkgs/doc/functions/library.xml | 7 | ||||
-rw-r--r-- | nixpkgs/doc/functions/nix-gitignore.xml | 40 | ||||
-rw-r--r-- | nixpkgs/doc/functions/prefer-remote-fetch.xml | 14 | ||||
-rw-r--r-- | nixpkgs/doc/functions/trivial-builders.xml | 111 |
7 files changed, 283 insertions, 300 deletions
diff --git a/nixpkgs/doc/functions/appimagetools.xml b/nixpkgs/doc/functions/appimagetools.xml index 270ab067bc39..4205c6da3851 100644 --- a/nixpkgs/doc/functions/appimagetools.xml +++ b/nixpkgs/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/nixpkgs/doc/functions/dockertools.xml b/nixpkgs/doc/functions/dockertools.xml index 2c8eb2cb7743..75db0bd3918c 100644 --- a/nixpkgs/doc/functions/dockertools.xml +++ b/nixpkgs/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/nixpkgs/doc/functions/fetchers.xml b/nixpkgs/doc/functions/fetchers.xml index b3bd2fe0f45e..a736008c9d41 100644 --- a/nixpkgs/doc/functions/fetchers.xml +++ b/nixpkgs/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/nixpkgs/doc/functions/library.xml b/nixpkgs/doc/functions/library.xml index b01de3c6e413..e6aedaa6efdd 100644 --- a/nixpkgs/doc/functions/library.xml +++ b/nixpkgs/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/nixpkgs/doc/functions/nix-gitignore.xml b/nixpkgs/doc/functions/nix-gitignore.xml index 465b38e0bf1d..9011570d1eae 100644 --- a/nixpkgs/doc/functions/nix-gitignore.xml +++ b/nixpkgs/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/nixpkgs/doc/functions/prefer-remote-fetch.xml b/nixpkgs/doc/functions/prefer-remote-fetch.xml index 85f08f4eae14..2ccad9218062 100644 --- a/nixpkgs/doc/functions/prefer-remote-fetch.xml +++ b/nixpkgs/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/nixpkgs/doc/functions/trivial-builders.xml b/nixpkgs/doc/functions/trivial-builders.xml index 92a07aedb5b9..1fd92ecfe262 100644 --- a/nixpkgs/doc/functions/trivial-builders.xml +++ b/nixpkgs/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> |