NixOS · Oct 10, 2018 · Oct 10, 2018 · Oct 10, 2018 · Oct 12, 2018 · Oct 12, 2018
diff --git a/doc/functions/dockertools.xml b/doc/functions/dockertools.xml
@@ -37,29 +37,29 @@
   <example xml:id='ex-dockerTools-buildImage'>
    <title>Docker build</title>
 <programlisting>
-  buildImage {
-    name = "redis"; <co xml:id='ex-dockerTools-buildImage-1' />
-    tag = "latest"; <co xml:id='ex-dockerTools-buildImage-2' />
-
-    fromImage = someBaseImage; <co xml:id='ex-dockerTools-buildImage-3' />
-    fromImageName = null; <co xml:id='ex-dockerTools-buildImage-4' />
-    fromImageTag = "latest"; <co xml:id='ex-dockerTools-buildImage-5' />
-
-    contents = pkgs.redis; <co xml:id='ex-dockerTools-buildImage-6' />
-    runAsRoot = '' <co xml:id='ex-dockerTools-buildImage-runAsRoot' />
-      #!${stdenv.shell}
-      mkdir -p /data
-    '';
-
-    config = { <co xml:id='ex-dockerTools-buildImage-8' />
-      Cmd = [ "/bin/redis-server" ];
-      WorkingDir = "/data";
-      Volumes = {
-        "/data" = {};
-      };
+buildImage {
+  name = "redis"; <co xml:id='ex-dockerTools-buildImage-1' />
+  tag = "latest"; <co xml:id='ex-dockerTools-buildImage-2' />
+
+  fromImage = someBaseImage; <co xml:id='ex-dockerTools-buildImage-3' />
+  fromImageName = null; <co xml:id='ex-dockerTools-buildImage-4' />
+  fromImageTag = "latest"; <co xml:id='ex-dockerTools-buildImage-5' />
+
+  contents = pkgs.redis; <co xml:id='ex-dockerTools-buildImage-6' />
+  runAsRoot = '' <co xml:id='ex-dockerTools-buildImage-runAsRoot' />
+    #!${stdenv.shell}
+    mkdir -p /data
+  '';
+
+  config = { <co xml:id='ex-dockerTools-buildImage-8' />
+    Cmd = [ "/bin/redis-server" ];
+    WorkingDir = "/data";
+    Volumes = {
+      "/data" = {};
     };
-  }
-  </programlisting>
+  };
+}
+</programlisting>
   </example>
 
   <para>
@@ -226,6 +226,177 @@ hello        latest   de2bf4786de6   About a minute ago   25.2MB
   </example>
  </section>
 
+ <section xml:id="ssec-pkgs-dockerTools-buildLayeredImage">
+  <title>buildLayeredImage</title>
+
+  <para>
+   Create a Docker image with many of the store paths being on their own layer
+   to improve sharing between images.
+  </para>
+
+  <variablelist>
+   <varlistentry>
+    <term>
+     <varname>name</varname>
+    </term>
+    <listitem>
+     <para>
+      The name of the resulting image.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>tag</varname> <emphasis>optional</emphasis>
+    </term>
+    <listitem>
+     <para>
+      Tag of the generated image.
+     </para>
+     <para>
+      <emphasis>Default:</emphasis> the output path's hash
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>contents</varname> <emphasis>optional</emphasis>
+    </term>
+    <listitem>
+     <para>
+      Top level paths in the container. Either a single derivation, or a list
+      of derivations.
+     </para>
+     <para>
+      <emphasis>Default:</emphasis> <literal>[]</literal>
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>config</varname> <emphasis>optional</emphasis>
+    </term>
+    <listitem>
+     <para>
+      Run-time configuration of the container. A full list of the options are
+      available at in the
+      <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions">
+      Docker Image Specification v1.2.0 </link>.
+     </para>
+     <para>
+      <emphasis>Default:</emphasis> <literal>{}</literal>
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>created</varname> <emphasis>optional</emphasis>
+    </term>
+    <listitem>
+     <para>
+      Date and time the layers were created. Follows the same
+      <literal>now</literal> exception supported by
+      <literal>buildImage</literal>.
+     </para>
+     <para>
+      <emphasis>Default:</emphasis> <literal>1970-01-01T00:00:01Z</literal>
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>maxLayers</varname> <emphasis>optional</emphasis>
+    </term>
+    <listitem>
+     <para>
+      Maximum number of layers to create.
+     </para>
+     <para>
+      <emphasis>Default:</emphasis> <literal>24</literal>
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <section xml:id="dockerTools-buildLayeredImage-arg-contents">
+   <title>Behavior of <varname>contents</varname> in the final image</title>
+
+   <para>
+    Each path directly listed in <varname>contents</varname> will have a
+    symlink in the root of the image.
+   </para>
+
+   <para>
+    For example:
+<programlisting><![CDATA[
+pkgs.dockerTools.buildLayeredImage {
+  name = "hello";
+  contents = [ pkgs.hello ];
+}
+]]></programlisting>
+    will create symlinks for all the paths in the <literal>hello</literal>
+    package:
+<screen><![CDATA[
+/bin/hello -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/bin/hello
+/share/info/hello.info -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/info/hello.info
+/share/locale/bg/LC_MESSAGES/hello.mo -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/locale/bg/LC_MESSAGES/hello.mo
+]]></screen>
+   </para>
+  </section>
+
+  <section xml:id="dockerTools-buildLayeredImage-arg-config">
+   <title>Automatic inclusion of <varname>config</varname> references</title>
+
+   <para>
+    The closure of <varname>config</varname> is automatically included in the
+    closure of the final image.
+   </para>
+
+   <para>
+    This allows you to make very simple Docker images with very little code.
+    This container will start up and run <command>hello</command>:
+<programlisting><![CDATA[
+pkgs.dockerTools.buildLayeredImage {
+  name = "hello";
+  config.Cmd = [ "${pkgs.hello}/bin/hello" ];
+}
+]]></programlisting>
+   </para>
+  </section>
+
+  <section xml:id="dockerTools-buildLayeredImage-arg-maxLayers">
+   <title>Adjusting <varname>maxLayers</varname></title>
+
+   <para>
+    Increasing the <varname>maxLayers</varname> increases the number of layers
+    which have a chance to be shared between different images.
+   </para>
+
+   <para>
+    Modern Docker installations support up to 128 layers, however older
+    versions support as few as 42.
+   </para>
+
+   <para>
+    If the produced image will not be extended by other Docker builds, it is
+    safe to set <varname>maxLayers</varname> to <literal>128</literal>. However
+    it will be impossible to extend the image further.
+   </para>
+
+   <para>
+    The first (<literal>maxLayers-2</literal>) most "popular" paths will have
+    their own individual layers, then layer #<literal>maxLayers-1</literal>
+    will contain all the remaining "unpopular" paths, and finally layer
+    #<literal>maxLayers</literal> will contain the Image configuration.
+   </para>
+
+   <para>
+    Docker's Layers are not inherently ordered, they are content-addressable
+    and are not explicitly layered until they are composed in to an Image.
+   </para>
+  </section>
+ </section>
+
  <section xml:id="ssec-pkgs-dockerTools-fetchFromRegistry">
   <title>pullImage</title>
 
@@ -243,15 +414,15 @@ hello        latest   de2bf4786de6   About a minute ago   25.2MB
   <example xml:id='ex-dockerTools-pullImage'>
    <title>Docker pull</title>
 <programlisting>
-  pullImage {
-    imageName = "nixos/nix"; <co xml:id='ex-dockerTools-pullImage-1' />
-    imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; <co xml:id='ex-dockerTools-pullImage-2' />
-    finalImageTag = "1.11";  <co xml:id='ex-dockerTools-pullImage-3' />
-    sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; <co xml:id='ex-dockerTools-pullImage-4' />
-    os = "linux"; <co xml:id='ex-dockerTools-pullImage-5' />
-    arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-6' />
-  }
-  </programlisting>
+pullImage {
+  imageName = "nixos/nix"; <co xml:id='ex-dockerTools-pullImage-1' />
+  imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; <co xml:id='ex-dockerTools-pullImage-2' />
+  finalImageTag = "1.11";  <co xml:id='ex-dockerTools-pullImage-3' />
+  sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; <co xml:id='ex-dockerTools-pullImage-4' />
+  os = "linux"; <co xml:id='ex-dockerTools-pullImage-5' />
+  arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-6' />
+}
+</programlisting>
   </example>
 
   <calloutlist>
@@ -273,9 +444,9 @@ hello        latest   de2bf4786de6   About a minute ago   25.2MB
      exactly which image you want. By default it will match the OS and
      architecture of the host the command is run on.
 <programlisting>
-  $ nix-shell --packages skopeo jq --command "skopeo --override-os linux --override-arch x86_64 inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'"
-  sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
-  </programlisting>
+$ nix-shell --packages skopeo jq --command "skopeo --override-os linux --override-arch x86_64 inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'"
+sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
+</programlisting>
      This argument is required.
     </para>
    </callout>
@@ -333,13 +504,13 @@ hello        latest   de2bf4786de6   About a minute ago   25.2MB
   <example xml:id='ex-dockerTools-exportImage'>
    <title>Docker export</title>
 <programlisting>
-  exportImage {
-    fromImage = someLayeredImage;
-    fromImageName = null;
-    fromImageTag = null;
+exportImage {
+  fromImage = someLayeredImage;
+  fromImageName = null;
+  fromImageTag = null;
 
-    name = someLayeredImage.name;
-  }
+  name = someLayeredImage.name;
+}
   </programlisting>
   </example>
 
@@ -369,19 +540,19 @@ hello        latest   de2bf4786de6   About a minute ago   25.2MB
   <example xml:id='ex-dockerTools-shadowSetup'>
    <title>Shadow base files</title>
 <programlisting>
-  buildImage {
-    name = "shadow-basic";
-
-    runAsRoot = ''
-      #!${stdenv.shell}
-      ${shadowSetup}
-      groupadd -r redis
-      useradd -r -g redis redis
-      mkdir /data
-      chown redis:redis /data
-    '';
-  }
-  </programlisting>
+buildImage {
+  name = "shadow-basic";
+
+  runAsRoot = ''
+    #!${stdenv.shell}
+    ${shadowSetup}
+    groupadd -r redis
+    useradd -r -g redis redis
+    mkdir /data
+    chown redis:redis /data
+  '';
+}
+</programlisting>
   </example>
 
   <para>

diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md
@@ -22,6 +22,7 @@ Adding custom .vimrc lines can be done using the following code:
 
 ```
 vim_configurable.customize {
+  # `name` specifies the name of the executable and package
   name = "vim-with-plugins";
 
   vimrcConfig.customRC = ''
@@ -30,6 +31,8 @@ vim_configurable.customize {
 }
 ```
 
+This configuration is used when vim is invoked with the command specified as name, in this case `vim-with-plugins`.
+
 For Neovim the `configure` argument can be overridden to achieve the same:
 
 ```
@@ -82,6 +85,7 @@ The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.n
 {
   packageOverrides = pkgs: with pkgs; {
     myVim = vim_configurable.customize {
+      # `name` specifies the name of the executable and package
       name = "vim-with-plugins";
       # add here code from the example section
     };

diff --git a/doc/stdenv.xml b/doc/stdenv.xml
@@ -372,7 +372,7 @@ let f(h, h + 1, i) = i + h
       They are programs/libraries used at build time that furthermore produce
       programs/libraries also used at build time. If the dependency doesn't
       care about the target platform (i.e. isn't a compiler or similar tool),
-      put it in <varname>nativeBuildInputs</varname>instead. The most common
+      put it in <varname>nativeBuildInputs</varname> instead. The most common
       use for this <literal>buildPackages.stdenv.cc</literal>, the default C
       compiler for this role. That example crops up more than one might think
       in old commonly used C libraries.
@@ -2100,7 +2100,7 @@ someVar=$(stripHash $name)
 
   <para>
    In order to alleviate this burden, the <firstterm>setup
-   hook></firstterm>mechanism was written, where any package can include a
+   hook</firstterm> mechanism was written, where any package can include a
    shell script that [by convention rather than enforcement by Nix], any
    downstream reverse-dependency will source as part of its build process. That
    allows the downstream dependency to merely specify its dependencies, and
@@ -2445,6 +2445,28 @@ addEnvHooks "$hostOffset" myBashFunction
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term>
+      breakpointHook
+     </term>
+     <listitem>
+      <para>
+       This hook will make a build pause instead of stopping when a failure
+       happen. It prevents nix to cleanup the build environment immediatly and
+       allows the user to attach to a build environment using the
+       <command>cntr</command> command. On build error it will print the
+       instruction that are neccessary for <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
+       sandbox 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
+       be not the case when remote builders are enabled.
+       <command>cntr</command> is only supported on linux based platforms.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </section>