Merge staging-next into staging

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/generators.xml" />
+ <xi:include href="functions/generators.section.xml" />
  <xi:include href="functions/debug.section.xml" />
  <xi:include href="functions/prefer-remote-fetch.section.xml" />
  <xi:include href="functions/nix-gitignore.section.xml" />

doc/functions/generators.section.md

@@ -0,0 +1,56 @@
+# Generators {#sec-generators}
+Generators are functions that create file formats from nix data structures, e. g. for configuration files. There are generators available for: `INI`, `JSON` and `YAML`
+
+All generators follow a similar call interface: `generatorName configFunctions data`, where `configFunctions` is an attrset of user-defined functions that format nested parts of the content. They each have common defaults, so often they do not need to be set manually. An example is `mkSectionName ? (name: libStr.escape [ "[" "]" ] name)` from the `INI` generator. It receives the name of a section and sanitizes it. The default `mkSectionName` escapes `[` and `]` with a backslash.
+
+Generators can be fine-tuned to produce exactly the file format required by your application/service. One example is an INI-file format which uses `: ` as separator, the strings `"yes"`/`"no"` as boolean values and requires all string values to be quoted:
+
+```nix
+with lib;
+let
+  customToINI = generators.toINI {
+    # specifies how to format a key/value pair
+    mkKeyValue = generators.mkKeyValueDefault {
+      # specifies the generated string for a subset of nix values
+      mkValueString = v:
+             if v == true then ''"yes"''
+        else if v == false then ''"no"''
+        else if isString v then ''"${v}"''
+        # and delegats all other values to the default generator
+        else generators.mkValueStringDefault {} v;
+    } ":";
+  };
+
+# the INI file can now be given as plain old nix values
+in customToINI {
+  main = {
+    pushinfo = true;
+    autopush = false;
+    host = "localhost";
+    port = 42;
+  };
+  mergetool = {
+    merge = "diff3";
+  };
+}
+```
+
+This will produce the following INI file as nix string:
+
+```INI
+[main]
+autopush:"no"
+host:"localhost"
+port:42
+pushinfo:"yes"
+str\:ange:"very::strange"
+
+[mergetool]
+merge:"diff3"
+```
+
+::: note
+Nix store paths can be converted to strings by enclosing a derivation attribute like so: `"${drv}"`.
+:::
+
+Detailed documentation for each generator can be found in `lib/generators.nix`.

nixos/doc/manual/administration/boot-problems.section.md

@@ -0,0 +1,35 @@
+# Boot Problems {#sec-boot-problems}
+
+If NixOS fails to boot, there are a number of kernel command line parameters that may help you to identify or fix the issue. You can add these parameters in the GRUB boot menu by pressing “e” to modify the selected boot entry and editing the line starting with `linux`. The following are some useful kernel command line parameters that are recognised by the NixOS boot scripts or by systemd:
+
+`boot.shell_on_fail`
+
+: Allows the user to start a root shell if something goes wrong in stage 1 of the boot process (the initial ramdisk). This is disabled by default because there is no authentication for the root shell.
+
+`boot.debug1`
+
+: Start an interactive shell in stage 1 before anything useful has been done. That is, no modules have been loaded and no file systems have been mounted, except for `/proc` and `/sys`.
+
+`boot.debug1devices`
+
+: Like `boot.debug1`, but runs stage1 until kernel modules are loaded and device nodes are created. This may help with e.g. making the keyboard work.
+
+`boot.debug1mounts`
+
+: Like `boot.debug1` or `boot.debug1devices`, but runs stage1 until all filesystems that are mounted during initrd are mounted (see [neededForBoot](#opt-fileSystems._name_.neededForBoot)). As a motivating example, this could be useful if you've forgotten to set [neededForBoot](options.html#opt-fileSystems._name_.neededForBoot) on a file system.
+
+`boot.trace`
+
+: Print every shell command executed by the stage 1 and 2 boot scripts.
+
+`single`
+
+: Boot into rescue mode (a.k.a. single user mode). This will cause systemd to start nothing but the unit `rescue.target`, which runs `sulogin` to prompt for the root password and start a root login shell. Exiting the shell causes the system to continue with the normal boot process.
+
+`systemd.log_level=debug` `systemd.log_target=console`
+
+: Make systemd very verbose and send log messages to the console instead of the journal. For more parameters recognised by systemd, see systemd(1).
+
+Notice that for `boot.shell_on_fail`, `boot.debug1`, `boot.debug1devices`, and `boot.debug1mounts`, if you did **not** select "start the new shell as pid 1", and you `exit` from the new shell, boot will proceed normally from the point where it failed, as if you'd chosen "ignore the error and continue".
+
+If no login prompts or X11 login screens appear (e.g. due to hanging dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start rescue mode (described above). (Also note that since most units have a 90-second timeout before systemd gives up on them, the `agetty` login prompts should appear eventually unless something is very wrong.)

nixos/doc/manual/administration/troubleshooting.xml

@@ -8,7 +8,7 @@
   This chapter describes solutions to common problems you might encounter when
   you manage your NixOS system.
  </para>
- <xi:include href="boot-problems.xml" />
+ <xi:include href="../from_md/administration/boot-problems.section.xml" />
  <xi:include href="maintenance-mode.xml" />
  <xi:include href="rollback.xml" />
  <xi:include href="store-corruption.xml" />

nixos/doc/manual/configuration/x-windows.xml

@@ -191,9 +191,12 @@
   <para>
    GTK themes can be installed either to user profile or system-wide (via
    <literal>environment.systemPackages</literal>). To make Qt 5 applications
-   look similar to GTK2 ones, you can install <literal>qt5.qtbase.gtk</literal>
-   package into your system environment. It should work for all Qt 5 library
-   versions.
+   look similar to GTK ones, you can use the following configuration:
+<programlisting>
+<xref linkend="opt-qt5.enable"/> = true;
+<xref linkend="opt-qt5.platformTheme"/> = "gtk2";
+<xref linkend="opt-qt5.style"/> = "gtk2";
+</programlisting>
   </para>
  </simplesect>
  <simplesect xml:id="custom-xkb-layouts">

nixos/doc/manual/development/assertions.section.md

@@ -0,0 +1,40 @@
+# Warnings and Assertions {#sec-assertions}
+
+When configuration problems are detectable in a module, it is a good idea to write an assertion or warning. Doing so provides clear feedback to the user and prevents errors after the build.
+
+Although Nix has the `abort` and `builtins.trace` [functions](https://nixos.org/nix/manual/#ssec-builtins) to perform such tasks, they are not ideally suited for NixOS modules. Instead of these functions, you can declare your warnings and assertions using the NixOS module system.
+
+## Warnings {#sec-assertions-warnings}
+
+This is an example of using `warnings`.
+
+```nix
+{ config, lib, ... }:
+{
+  config = lib.mkIf config.services.foo.enable {
+    warnings =
+      if config.services.foo.bar
+      then [ ''You have enabled the bar feature of the foo service.
+               This is known to cause some specific problems in certain situations.
+               '' ]
+      else [];
+  }
+}
+```
+
+## Assertions {#sec-assertions-assetions}
+
+This example, extracted from the [`syslogd` module](https://github.com/NixOS/nixpkgs/blob/release-17.09/nixos/modules/services/logging/syslogd.nix) shows how to use `assertions`. Since there can only be one active syslog daemon at a time, an assertion is useful to prevent such a broken system from being built.
+
+```nix
+{ config, lib, ... }:
+{
+  config = lib.mkIf config.services.syslogd.enable {
+    assertions =
+      [ { assertion = !config.services.rsyslogd.enable;
+          message = "rsyslogd conflicts with syslogd";
+        }
+      ];
+  }
+}
+```