diff options
Diffstat (limited to 'doc/functions')
-rw-r--r-- | doc/functions/fetchers.xml | 20 | ||||
-rw-r--r-- | doc/functions/trivial-builders.xml | 83 |
2 files changed, 75 insertions, 28 deletions
diff --git a/doc/functions/fetchers.xml b/doc/functions/fetchers.xml index 96937ca7182e1..b3bd2fe0f45e2 100644 --- a/doc/functions/fetchers.xml +++ b/doc/functions/fetchers.xml @@ -6,8 +6,8 @@ <para> When using Nix, you will frequently need to download source code - and other file from the internet. Nixpkgs comes with a few helper - functions that allow you to fetch fixed-output derivations in + 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> @@ -48,7 +48,11 @@ stdenv.mkDerivation { <para> <function>fetchpatch</function> works very similarly to - <function>fetchurl</function> with the same arguments expected. + <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> @@ -80,6 +84,9 @@ stdenv.mkDerivation { <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> @@ -141,9 +148,10 @@ stdenv.mkDerivation { GitHub HTML page as <literal>owner</literal>/<literal>repo</literal>. <literal>rev</literal> corresponds to the Git commit hash or - tag that will be downloaded from Git. Finally, - <literal>sha256</literal>. Again, other hash algorithms are - also available but <literal>sha256</literal> is currently + 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> diff --git a/doc/functions/trivial-builders.xml b/doc/functions/trivial-builders.xml index 4fbe88836100b..c5972d3ea908c 100644 --- a/doc/functions/trivial-builders.xml +++ b/doc/functions/trivial-builders.xml @@ -5,10 +5,10 @@ <title>Trivial builders</title> <para> - There are a couple of functions provide in Nixpkgs that help with - building derivations. The most important one, + Nixpkgs provides a couple of functions that help with building + derivations. The most important one, <function>stdenv.mkDerivation</function>, has already been - documented above. These wrap + documented above. The following functions wrap <function>stdenv.mkDerivation</function>, making it easier to use in certain cases. </para> @@ -22,14 +22,42 @@ <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 use to - refer to the derivation. <literal>env</literal> is an attribute - set specifying environment variables that will be set for this - derivation. <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> + <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 + + mkdir $out + + echo I can write data to the Nix store > $out/message + + echo I can also run basic commands like: + + echo ls + ls + + echo whoami + whoami + + echo date + date + '' + </programlisting> </listitem> </varlistentry> <varlistentry> @@ -47,19 +75,30 @@ </varlistentry> <varlistentry> <term> - <literal>writeTextFile</literal> + <literal>writeTextFile</literal>, <literal>writeText</literal>, + <literal>writeTextDir</literal>, <literal>writeScript</literal>, + <literal>writeScriptBin</literal> </term> <listitem> <para> - This writes <literal>text</literal> to the Nix store. This is - useful for creating scripts from Nix expressions. This 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> + 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> @@ -75,7 +114,7 @@ <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 directory. + derivations or any other subdirectory contained within. </para> </listitem> </varlistentry> |