NixOS · Apr 27, 2018 · Aug 6, 2018 · Aug 14, 2018 · Aug 16, 2018 · Aug 16, 2018
Showing 660 changed files with 18,333 additions and 6,388 deletions.
diff --git a/.dir-locals.el b/.dir-locals.el
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -20,6 +20,8 @@ under the terms of [COPYING](../COPYING), which is an MIT-like license.
   (Motivation for change. Additional information.)
   ```
 
+  For consistency, there should not be a period at the end of the commit message's summary line (the first line of the commit message).
+
   Examples:
 
   * nginx: init at 2.0.1

diff --git a/README.md b/README.md
@@ -12,12 +12,12 @@ build daemon as so-called channels. To get channel information via git, add
 ```
 
 For stability and maximum binary package support, it is recommended to maintain
-custom changes on top of one of the channels, e.g. `nixos-18.03` for the latest
+custom changes on top of one of the channels, e.g. `nixos-18.09` for the latest
 release and `nixos-unstable` for the latest successful build of master:
 
 ```
 % git remote update channels
-% git rebase channels/nixos-18.03
+% git rebase channels/nixos-18.09
 ```
 
 For pull-requests, please rebase onto nixpkgs `master`.
@@ -31,9 +31,9 @@ For pull-requests, please rebase onto nixpkgs `master`.
 * [Manual (NixOS)](https://nixos.org/nixos/manual/)
 * [Community maintained wiki](https://nixos.wiki/)
 * [Continuous package builds for unstable/master](https://hydra.nixos.org/jobset/nixos/trunk-combined)
-* [Continuous package builds for 18.03 release](https://hydra.nixos.org/jobset/nixos/release-18.03)
+* [Continuous package builds for 18.09 release](https://hydra.nixos.org/jobset/nixos/release-18.09)
 * [Tests for unstable/master](https://hydra.nixos.org/job/nixos/trunk-combined/tested#tabs-constituents)
-* [Tests for 18.03 release](https://hydra.nixos.org/job/nixos/release-18.03/tested#tabs-constituents)
+* [Tests for 18.09 release](https://hydra.nixos.org/job/nixos/release-18.09/tested#tabs-constituents)
 
 Communication:
 

diff --git a/default.nix b/default.nix
@@ -18,7 +18,7 @@ if ! builtins ? nixVersion || builtins.compareVersions requiredVersion builtins.
 
     For more information, please see the NixOS release notes at
     https://nixos.org/nixos/manual or locally at
-    ${toString ./doc/manual/release-notes}.
+    ${toString ./nixos/doc/manual/release-notes}.
 
     If you need further help, see https://nixos.org/nixos/support.html
   ''

diff --git a/doc/.gitignore b/doc/.gitignore
@@ -4,3 +4,4 @@
 out
 manual-full.xml
 highlightjs
+functions/library/locations.xml
diff --git a/doc/Makefile b/doc/Makefile
@@ -19,7 +19,7 @@ fix-misc-xml:
 
 .PHONY: clean
 clean:
-	rm -f ${MD_TARGETS} .version manual-full.xml
+	rm -f ${MD_TARGETS} .version manual-full.xml functions/library/locations.xml
 	rm -rf ./out/ ./highlightjs
 
 .PHONY: validate
@@ -69,13 +69,17 @@ highlightjs:
 	cp -r "$$HIGHLIGHTJS/loader.js" highlightjs/
 
 
-manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml
+manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml *.xml **/*.xml **/**/*.xml
 	xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
 
 .version:
 	nix-instantiate --eval \
 		-E '(import ../lib).version' > .version
 
+functions/library/locations.xml:
+	nix-build ./lib-function-locations.nix \
+		--out-link ./functions/library/locations.xml
+
 %.section.xml: %.section.md
 	pandoc $^ -w docbook+smart \
 		-f markdown+smart \

diff --git a/doc/default.nix b/doc/default.nix
@@ -1,6 +1,7 @@
+{ pkgs ? (import ./.. { }), nixpkgs ? { }}:
 let
-  pkgs = import ./.. { };
   lib = pkgs.lib;
+  locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs; };
 in
 pkgs.stdenv.mkDerivation {
   name = "nixpkgs-manual";
@@ -29,6 +30,8 @@ pkgs.stdenv.mkDerivation {
   ];
 
   postPatch = ''
+    rm -rf ./functions/library/locations.xml
+    ln -s ${locationsXml} ./functions/library/locations.xml
     echo ${lib.version} > .version
   '';
 

diff --git a/doc/functions.xml b/doc/functions.xml
@@ -7,7 +7,7 @@
   The nixpkgs repository has several utility functions to manipulate Nix
   expressions.
  </para>
-
+ <xi:include href="functions/library.xml" />
  <xi:include href="functions/overrides.xml" />
  <xi:include href="functions/generators.xml" />
  <xi:include href="functions/debug.xml" />

diff --git a/doc/functions/library.xml b/doc/functions/library.xml
@@ -0,0 +1,15 @@
+<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-functions-library">
+ <title>Nixpkgs Library Functions</title>
+
+ <para>
+  Nixpkgs provides a standard library at <varname>pkgs.lib</varname>, or
+  through <code>import &lt;nixpkgs/lib&gt;</code>.
+ </para>
+
+ <xi:include href="./library/asserts.xml" />
+
+ <xi:include href="./library/attrsets.xml" />
+</section>
diff --git a/doc/functions/library/asserts.xml b/doc/functions/library/asserts.xml
@@ -0,0 +1,117 @@
+<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-functions-library-asserts">
+ <title>Assert functions</title>
+
+ <section xml:id="function-library-lib.asserts.assertMsg">
+  <title><function>lib.asserts.assertMsg</function></title>
+
+  <subtitle><literal>assertMsg :: Bool -> String -> Bool</literal>
+  </subtitle>
+
+  <xi:include href="./locations.xml" xpointer="lib.asserts.assertMsg" />
+
+  <para>
+   Print a trace message if <literal>pred</literal> is false.
+  </para>
+
+  <para>
+   Intended to be used to augment asserts with helpful error messages.
+  </para>
+
+  <variablelist>
+   <varlistentry>
+    <term>
+     <varname>pred</varname>
+    </term>
+    <listitem>
+     <para>
+      Condition under which the <varname>msg</varname> should
+      <emphasis>not</emphasis> be printed.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>msg</varname>
+    </term>
+    <listitem>
+     <para>
+      Message to print.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <example xml:id="function-library-lib.asserts.assertMsg-example-false">
+   <title>Printing when the predicate is false</title>
+<programlisting><![CDATA[
+assert lib.asserts.assertMsg ("foo" == "bar") "foo is not bar, silly"
+stderr> trace: foo is not bar, silly
+stderr> assert failed
+]]></programlisting>
+  </example>
+ </section>
+
+ <section xml:id="function-library-lib.asserts.assertOneOf">
+  <title><function>lib.asserts.assertOneOf</function></title>
+
+  <subtitle><literal>assertOneOf :: String -> String ->
+      StringList -> Bool</literal>
+  </subtitle>
+
+  <xi:include href="./locations.xml" xpointer="lib.asserts.assertOneOf" />
+
+  <para>
+   Specialized <function>asserts.assertMsg</function> for checking if
+   <varname>val</varname> is one of the elements of <varname>xs</varname>.
+   Useful for checking enums.
+  </para>
+
+  <variablelist>
+   <varlistentry>
+    <term>
+     <varname>name</varname>
+    </term>
+    <listitem>
+     <para>
+      The name of the variable the user entered <varname>val</varname> into,
+      for inclusion in the error message.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>val</varname>
+    </term>
+    <listitem>
+     <para>
+      The value of what the user provided, to be compared against the values in
+      <varname>xs</varname>.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>xs</varname>
+    </term>
+    <listitem>
+     <para>
+      The list of valid values.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <example xml:id="function-library-lib.asserts.assertOneOf-example">
+   <title>Ensuring a user provided a possible value</title>
+<programlisting><![CDATA[
+let sslLibrary = "bearssl";
+in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ];
+=> false
+stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl"
+        ]]></programlisting>
+  </example>
+ </section>
+</section>