NixOS · Oct 2, 2018 · Oct 2, 2018 · Oct 3, 2018 · Oct 3, 2018 · Oct 8, 2018
Showing 767 changed files with 11,877 additions and 6,328 deletions.
diff --git a/doc/functions.xml b/doc/functions.xml
@@ -11,7 +11,10 @@
  <xi:include href="functions/overrides.xml" />
  <xi:include href="functions/generators.xml" />
  <xi:include href="functions/debug.xml" />
+ <xi:include href="functions/fetchers.xml" />
+ <xi:include href="functions/trivial-builders.xml" />
  <xi:include href="functions/fhs-environments.xml" />
  <xi:include href="functions/shell.xml" />
  <xi:include href="functions/dockertools.xml" />
+ <xi:include href="functions/prefer-remote-fetch.xml" />
 </chapter>
diff --git a/doc/functions/fetchers.xml b/doc/functions/fetchers.xml
@@ -0,0 +1,206 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xml:id="sec-pkgs-fetchers">
+ <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.
+ </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.
+ </para>
+
+ <programlisting><![CDATA[
+{ stdenv, fetchurl }:
+
+stdenv.mkDerivation {
+  name = "hello";
+  src = fetchurl {
+    url = "http://www.example.org/hello.tar.gz";
+    sha256 = "1111111111111111111111111111111111111111111111111111";
+  };
+}
+]]></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.
+ </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.
+ </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>.
+ </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>
+ </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.
+ </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>
+ </variablelist>
+
+
+</section>
diff --git a/doc/functions/prefer-remote-fetch.xml b/doc/functions/prefer-remote-fetch.xml
@@ -0,0 +1,27 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/xinclude"
+         xml:id="sec-prefer-remote-fetch">
+ <title>prefer-remote-fetch overlay</title>
+
+ <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>
+    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>
+    $ mkdir ~/.config/nixpkgs/overlays/
+    $ cat &gt; ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix &lt;&lt;EOF
+      self: super: super.prefer-remote-fetch self super
+    EOF
+  </programlisting>
+ </para>
+</section>
diff --git a/doc/functions/trivial-builders.xml b/doc/functions/trivial-builders.xml
@@ -0,0 +1,124 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xml:id="sec-trivial-builders">
+ <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.
+ </para>
+
+ <variablelist>
+  <varlistentry>
+   <term>
+    <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>
+       (import &lt;nixpkgs&gt; {}).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>
+   <term>
+    <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>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <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>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <literal>symlinkJoin</literal>
+   </term>
+   <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,
+     <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.
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+
+</section>