Merge pull request #128885 from bobby285271/pr3

 nixos/doc: convert "Chapter 5. Configuration Syntax" to CommonMark

3 files changed, 715 insertions, 0 deletions

diff --git a/nixos/doc/manual/from_md/configuration/config-file.section.xml b/nixos/doc/manual/from_md/configuration/config-file.section.xml
new file mode 100644
index 00000000000..952c6e60030
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/config-file.section.xml
@@ -0,0 +1,231 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-configuration-file">
+  <title>NixOS Configuration File</title>
+  <para>
+    The NixOS configuration file generally looks like this:
+  </para>
+  <programlisting language="bash">
+{ config, pkgs, ... }:
+
+{ option definitions
+}
+</programlisting>
+  <para>
+    The first line (<literal>{ config, pkgs, ... }:</literal>) denotes
+    that this is actually a function that takes at least the two
+    arguments <literal>config</literal> and <literal>pkgs</literal>.
+    (These are explained later, in chapter
+    <xref linkend="sec-writing-modules" />) The function returns a
+    <emphasis>set</emphasis> of option definitions
+    (<literal>{ ... }</literal>). These definitions have the form
+    <literal>name = value</literal>, where <literal>name</literal> is
+    the name of an option and <literal>value</literal> is its value. For
+    example,
+  </para>
+  <programlisting language="bash">
+{ config, pkgs, ... }:
+
+{ services.httpd.enable = true;
+  services.httpd.adminAddr = &quot;alice@example.org&quot;;
+  services.httpd.virtualHosts.localhost.documentRoot = &quot;/webroot&quot;;
+}
+</programlisting>
+  <para>
+    defines a configuration with three option definitions that together
+    enable the Apache HTTP Server with <literal>/webroot</literal> as
+    the document root.
+  </para>
+  <para>
+    Sets can be nested, and in fact dots in option names are shorthand
+    for defining a set containing another set. For instance,
+    <xref linkend="opt-services.httpd.enable" /> defines a set named
+    <literal>services</literal> that contains a set named
+    <literal>httpd</literal>, which in turn contains an option
+    definition named <literal>enable</literal> with value
+    <literal>true</literal>. This means that the example above can also
+    be written as:
+  </para>
+  <programlisting language="bash">
+{ config, pkgs, ... }:
+
+{ services = {
+    httpd = {
+      enable = true;
+      adminAddr = &quot;alice@example.org&quot;;
+      virtualHosts = {
+        localhost = {
+          documentRoot = &quot;/webroot&quot;;
+        };
+      };
+    };
+  };
+}
+</programlisting>
+  <para>
+    which may be more convenient if you have lots of option definitions
+    that share the same prefix (such as
+    <literal>services.httpd</literal>).
+  </para>
+  <para>
+    NixOS checks your option definitions for correctness. For instance,
+    if you try to define an option that doesn’t exist (that is, doesn’t
+    have a corresponding <emphasis>option declaration</emphasis>),
+    <literal>nixos-rebuild</literal> will give an error like:
+  </para>
+  <programlisting>
+The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
+</programlisting>
+  <para>
+    Likewise, values in option definitions must have a correct type. For
+    instance, <literal>services.httpd.enable</literal> must be a Boolean
+    (<literal>true</literal> or <literal>false</literal>). Trying to
+    give it a value of another type, such as a string, will cause an
+    error:
+  </para>
+  <programlisting>
+The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
+</programlisting>
+  <para>
+    Options have various types of values. The most important are:
+  </para>
+  <variablelist>
+    <varlistentry>
+      <term>
+        Strings
+      </term>
+      <listitem>
+        <para>
+          Strings are enclosed in double quotes, e.g.
+        </para>
+        <programlisting language="bash">
+networking.hostName = &quot;dexter&quot;;
+</programlisting>
+        <para>
+          Special characters can be escaped by prefixing them with a
+          backslash (e.g. <literal>\&quot;</literal>).
+        </para>
+        <para>
+          Multi-line strings can be enclosed in <emphasis>double single
+          quotes</emphasis>, e.g.
+        </para>
+        <programlisting language="bash">
+networking.extraHosts =
+  ''
+    127.0.0.2 other-localhost
+    10.0.0.1 server
+  '';
+</programlisting>
+        <para>
+          The main difference is that it strips from each line a number
+          of spaces equal to the minimal indentation of the string as a
+          whole (disregarding the indentation of empty lines), and that
+          characters like <literal>&quot;</literal> and
+          <literal>\</literal> are not special (making it more
+          convenient for including things like shell code). See more
+          info about this in the Nix manual
+          <link xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        Booleans
+      </term>
+      <listitem>
+        <para>
+          These can be <literal>true</literal> or
+          <literal>false</literal>, e.g.
+        </para>
+        <programlisting language="bash">
+networking.firewall.enable = true;
+networking.firewall.allowPing = false;
+</programlisting>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        Integers
+      </term>
+      <listitem>
+        <para>
+          For example,
+        </para>
+        <programlisting language="bash">
+boot.kernel.sysctl.&quot;net.ipv4.tcp_keepalive_time&quot; = 60;
+</programlisting>
+        <para>
+          (Note that here the attribute name
+          <literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in
+          quotes to prevent it from being interpreted as a set named
+          <literal>net</literal> containing a set named
+          <literal>ipv4</literal>, and so on. This is because it’s not a
+          NixOS option but the literal name of a Linux kernel setting.)
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        Sets
+      </term>
+      <listitem>
+        <para>
+          Sets were introduced above. They are name/value pairs enclosed
+          in braces, as in the option definition
+        </para>
+        <programlisting language="bash">
+fileSystems.&quot;/boot&quot; =
+  { device = &quot;/dev/sda1&quot;;
+    fsType = &quot;ext4&quot;;
+    options = [ &quot;rw&quot; &quot;data=ordered&quot; &quot;relatime&quot; ];
+  };
+</programlisting>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        Lists
+      </term>
+      <listitem>
+        <para>
+          The important thing to note about lists is that list elements
+          are separated by whitespace, like this:
+        </para>
+        <programlisting language="bash">
+boot.kernelModules = [ &quot;fuse&quot; &quot;kvm-intel&quot; &quot;coretemp&quot; ];
+</programlisting>
+        <para>
+          List elements can be any other type, e.g. sets:
+        </para>
+        <programlisting language="bash">
+swapDevices = [ { device = &quot;/dev/disk/by-label/swap&quot;; } ];
+</programlisting>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        Packages
+      </term>
+      <listitem>
+        <para>
+          Usually, the packages you need are already part of the Nix
+          Packages collection, which is a set that can be accessed
+          through the function argument <literal>pkgs</literal>. Typical
+          uses:
+        </para>
+        <programlisting language="bash">
+environment.systemPackages =
+  [ pkgs.thunderbird
+    pkgs.emacs
+  ];
+
+services.postgresql.package = pkgs.postgresql_10;
+</programlisting>
+        <para>
+          The latter option definition changes the default PostgreSQL
+          package used by NixOS’s PostgreSQL service to 10.x. For more
+          information on packages, including how to add new ones, see
+          <xref linkend="sec-custom-packages" />.
+        </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+</section>
diff --git a/nixos/doc/manual/from_md/configuration/modularity.section.xml b/nixos/doc/manual/from_md/configuration/modularity.section.xml
new file mode 100644
index 00000000000..a7688090fcc
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/modularity.section.xml
@@ -0,0 +1,152 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-modularity">
+  <title>Modularity</title>
+  <para>
+    The NixOS configuration mechanism is modular. If your
+    <literal>configuration.nix</literal> becomes too big, you can split
+    it into multiple files. Likewise, if you have multiple NixOS
+    configurations (e.g. for different computers) with some commonality,
+    you can move the common configuration into a shared file.
+  </para>
+  <para>
+    Modules have exactly the same syntax as
+    <literal>configuration.nix</literal>. In fact,
+    <literal>configuration.nix</literal> is itself a module. You can use
+    other modules by including them from
+    <literal>configuration.nix</literal>, e.g.:
+  </para>
+  <programlisting language="bash">
+{ config, pkgs, ... }:
+
+{ imports = [ ./vpn.nix ./kde.nix ];
+  services.httpd.enable = true;
+  environment.systemPackages = [ pkgs.emacs ];
+  ...
+}
+</programlisting>
+  <para>
+    Here, we include two modules from the same directory,
+    <literal>vpn.nix</literal> and <literal>kde.nix</literal>. The
+    latter might look like this:
+  </para>
+  <programlisting language="bash">
+{ config, pkgs, ... }:
+
+{ services.xserver.enable = true;
+  services.xserver.displayManager.sddm.enable = true;
+  services.xserver.desktopManager.plasma5.enable = true;
+  environment.systemPackages = [ pkgs.vim ];
+}
+</programlisting>
+  <para>
+    Note that both <literal>configuration.nix</literal> and
+    <literal>kde.nix</literal> define the option
+    <xref linkend="opt-environment.systemPackages" />. When multiple
+    modules define an option, NixOS will try to
+    <emphasis>merge</emphasis> the definitions. In the case of
+    <xref linkend="opt-environment.systemPackages" />, that’s easy: the
+    lists of packages can simply be concatenated. The value in
+    <literal>configuration.nix</literal> is merged last, so for
+    list-type options, it will appear at the end of the merged list. If
+    you want it to appear first, you can use
+    <literal>mkBefore</literal>:
+  </para>
+  <programlisting language="bash">
+boot.kernelModules = mkBefore [ &quot;kvm-intel&quot; ];
+</programlisting>
+  <para>
+    This causes the <literal>kvm-intel</literal> kernel module to be
+    loaded before any other kernel modules.
+  </para>
+  <para>
+    For other types of options, a merge may not be possible. For
+    instance, if two modules define
+    <xref linkend="opt-services.httpd.adminAddr" />,
+    <literal>nixos-rebuild</literal> will give an error:
+  </para>
+  <programlisting>
+The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.
+</programlisting>
+  <para>
+    When that happens, it’s possible to force one definition take
+    precedence over the others:
+  </para>
+  <programlisting language="bash">
+services.httpd.adminAddr = pkgs.lib.mkForce &quot;bob@example.org&quot;;
+</programlisting>
+  <para>
+    When using multiple modules, you may need to access configuration
+    values defined in other modules. This is what the
+    <literal>config</literal> function argument is for: it contains the
+    complete, merged system configuration. That is,
+    <literal>config</literal> is the result of combining the
+    configurations returned by every module <footnote>
+      <para>
+        If you’re wondering how it’s possible that the (indirect)
+        <emphasis>result</emphasis> of a function is passed as an
+        <emphasis>input</emphasis> to that same function: that’s because
+        Nix is a <quote>lazy</quote> language — it only computes values
+        when they are needed. This works as long as no individual
+        configuration value depends on itself.
+      </para>
+    </footnote> . For example, here is a module that adds some packages
+    to <xref linkend="opt-environment.systemPackages" /> only if
+    <xref linkend="opt-services.xserver.enable" /> is set to
+    <literal>true</literal> somewhere else:
+  </para>
+  <programlisting language="bash">
+{ config, pkgs, ... }:
+
+{ environment.systemPackages =
+    if config.services.xserver.enable then
+      [ pkgs.firefox
+        pkgs.thunderbird
+      ]
+    else
+      [ ];
+}
+</programlisting>
+  <para>
+    With multiple modules, it may not be obvious what the final value of
+    a configuration option is. The command
+    <literal>nixos-option</literal> allows you to find out:
+  </para>
+  <programlisting>
+$ nixos-option services.xserver.enable
+true
+
+$ nixos-option boot.kernelModules
+[ &quot;tun&quot; &quot;ipv6&quot; &quot;loop&quot; ... ]
+</programlisting>
+  <para>
+    Interactive exploration of the configuration is possible using
+    <literal>nix repl</literal>, a read-eval-print loop for Nix
+    expressions. A typical use:
+  </para>
+  <programlisting>
+$ nix repl '&lt;nixpkgs/nixos&gt;'
+
+nix-repl&gt; config.networking.hostName
+&quot;mandark&quot;
+
+nix-repl&gt; map (x: x.hostName) config.services.httpd.virtualHosts
+[ &quot;example.org&quot; &quot;example.gov&quot; ]
+</programlisting>
+  <para>
+    While abstracting your configuration, you may find it useful to
+    generate modules using code, instead of writing files. The example
+    below would have the same effect as importing a file which sets
+    those options.
+  </para>
+  <programlisting language="bash">
+{ config, pkgs, ... }:
+
+let netConfig = hostName: {
+  networking.hostName = hostName;
+  networking.useDHCP = false;
+};
+
+in
+
+{ imports = [ (netConfig &quot;nixos.localdomain&quot;) ]; }
+</programlisting>
+</section>
diff --git a/nixos/doc/manual/from_md/configuration/summary.section.xml b/nixos/doc/manual/from_md/configuration/summary.section.xml
new file mode 100644
index 00000000000..96a178c4930
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/summary.section.xml
@@ -0,0 +1,332 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-nix-syntax-summary">
+  <title>Syntax Summary</title>
+  <para>
+    Below is a summary of the most important syntactic constructs in the
+    Nix expression language. It’s not complete. In particular, there are
+    many other built-in functions. See the
+    <link xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
+    manual</link> for the rest.
+  </para>
+  <informaltable>
+    <tgroup cols="2">
+      <colspec align="left" />
+      <colspec align="left" />
+      <thead>
+        <row>
+          <entry>
+            Example
+          </entry>
+          <entry>
+            Description
+          </entry>
+        </row>
+      </thead>
+      <tbody>
+        <row>
+          <entry>
+            <emphasis>Basic values</emphasis>
+          </entry>
+          <entry>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>&quot;Hello world&quot;</literal>
+          </entry>
+          <entry>
+            A string
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>&quot;${pkgs.bash}/bin/sh&quot;</literal>
+          </entry>
+          <entry>
+            A string containing an expression (expands to
+            <literal>&quot;/nix/store/hash-bash-version/bin/sh&quot;</literal>)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>true</literal>, <literal>false</literal>
+          </entry>
+          <entry>
+            Booleans
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>123</literal>
+          </entry>
+          <entry>
+            An integer
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>./foo.png</literal>
+          </entry>
+          <entry>
+            A path (relative to the containing Nix expression)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <emphasis>Compound values</emphasis>
+          </entry>
+          <entry>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x = 1; y = 2; }</literal>
+          </entry>
+          <entry>
+            A set with attributes named <literal>x</literal> and
+            <literal>y</literal>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ foo.bar = 1; }</literal>
+          </entry>
+          <entry>
+            A nested set, equivalent to
+            <literal>{ foo = { bar = 1; }; }</literal>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>rec { x = &quot;foo&quot;; y = x + &quot;bar&quot;; }</literal>
+          </entry>
+          <entry>
+            A recursive set, equivalent to
+            <literal>{ x = &quot;foo&quot;; y = &quot;foobar&quot;; }</literal>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>[ &quot;foo&quot; &quot;bar&quot; ]</literal>
+          </entry>
+          <entry>
+            A list with two elements
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <emphasis>Operators</emphasis>
+          </entry>
+          <entry>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>&quot;foo&quot; + &quot;bar&quot;</literal>
+          </entry>
+          <entry>
+            String concatenation
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>1 + 2</literal>
+          </entry>
+          <entry>
+            Integer addition
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>&quot;foo&quot; == &quot;f&quot; + &quot;oo&quot;</literal>
+          </entry>
+          <entry>
+            Equality test (evaluates to <literal>true</literal>)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>&quot;foo&quot; != &quot;bar&quot;</literal>
+          </entry>
+          <entry>
+            Inequality test (evaluates to <literal>true</literal>)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>!true</literal>
+          </entry>
+          <entry>
+            Boolean negation
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x = 1; y = 2; }.x</literal>
+          </entry>
+          <entry>
+            Attribute selection (evaluates to <literal>1</literal>)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x = 1; y = 2; }.z or 3</literal>
+          </entry>
+          <entry>
+            Attribute selection with default (evaluates to
+            <literal>3</literal>)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x = 1; y = 2; } // { z = 3; }</literal>
+          </entry>
+          <entry>
+            Merge two sets (attributes in the right-hand set taking
+            precedence)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <emphasis>Control structures</emphasis>
+          </entry>
+          <entry>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>if 1 + 1 == 2 then &quot;yes!&quot; else &quot;no!&quot;</literal>
+          </entry>
+          <entry>
+            Conditional expression
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>assert 1 + 1 == 2; &quot;yes!&quot;</literal>
+          </entry>
+          <entry>
+            Assertion check (evaluates to
+            <literal>&quot;yes!&quot;</literal>). See
+            <xref linkend="sec-assertions" /> for using assertions in
+            modules
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>let x = &quot;foo&quot;; y = &quot;bar&quot;; in x + y</literal>
+          </entry>
+          <entry>
+            Variable definition
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>with pkgs.lib; head [ 1 2 3 ]</literal>
+          </entry>
+          <entry>
+            Add all attributes from the given set to the scope
+            (evaluates to <literal>1</literal>)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <emphasis>Functions (lambdas)</emphasis>
+          </entry>
+          <entry>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>x: x + 1</literal>
+          </entry>
+          <entry>
+            A function that expects an integer and returns it increased
+            by 1
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>(x: x + 1) 100</literal>
+          </entry>
+          <entry>
+            A function call (evaluates to 101)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>let inc = x: x + 1; in inc (inc (inc 100))</literal>
+          </entry>
+          <entry>
+            A function bound to a variable and subsequently called by
+            name (evaluates to 103)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x, y }: x + y</literal>
+          </entry>
+          <entry>
+            A function that expects a set with required attributes
+            <literal>x</literal> and <literal>y</literal> and
+            concatenates them
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x, y ? &quot;bar&quot; }: x + y</literal>
+          </entry>
+          <entry>
+            A function that expects a set with required attribute
+            <literal>x</literal> and optional <literal>y</literal>,
+            using <literal>&quot;bar&quot;</literal> as default value
+            for <literal>y</literal>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x, y, ... }: x + y</literal>
+          </entry>
+          <entry>
+            A function that expects a set with required attributes
+            <literal>x</literal> and <literal>y</literal> and ignores
+            any other attributes
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x, y } @ args: x + y</literal>
+          </entry>
+          <entry>
+            A function that expects a set with required attributes
+            <literal>x</literal> and <literal>y</literal>, and binds the
+            whole set to <literal>args</literal>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <emphasis>Built-in functions</emphasis>
+          </entry>
+          <entry>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>import ./foo.nix</literal>
+          </entry>
+          <entry>
+            Load and return Nix expression in given file
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>map (x: x + x) [ 1 2 3 ]</literal>
+          </entry>
+          <entry>
+            Apply a function to every element of a list (evaluates to
+            <literal>[ 2 4 6 ]</literal>)
+          </entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </informaltable>
+</section>