From 00f380dee5c395704b8b83c462d0d735ff0e810e Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <eelco.dolstra@logicblox.com>
Date: Sun, 13 Oct 2013 16:20:49 +0200
Subject: [PATCH] Document nixos-generate-config

---
 .../doc/manual/man-nixos-generate-config.xml  | 191 ++++++++++++++++++
 nixos/doc/manual/man-pages.xml                |  11 +-
 2 files changed, 196 insertions(+), 6 deletions(-)
 create mode 100644 nixos/doc/manual/man-nixos-generate-config.xml

diff --git a/nixos/doc/manual/man-nixos-generate-config.xml b/nixos/doc/manual/man-nixos-generate-config.xml
new file mode 100644
index 000000000000..ff69d8d91701
--- /dev/null
+++ b/nixos/doc/manual/man-nixos-generate-config.xml
@@ -0,0 +1,191 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<refmeta>
+  <refentrytitle><command>nixos-generate-config</command></refentrytitle>
+  <manvolnum>8</manvolnum>
+  <refmiscinfo class="source">NixOS</refmiscinfo>
+  <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
+</refmeta>
+
+<refnamediv>
+  <refname><command>nixos-generate-config</command></refname>
+  <refpurpose>generate NixOS configuration modules</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nixos-generate-config</command>
+    <arg><option>--force</option></arg>
+    <arg>
+      <arg choice='plain'><option>--root</option></arg>
+      <replaceable>root</replaceable>
+    </arg>
+    <arg>
+      <arg choice='plain'><option>--dir</option></arg>
+      <replaceable>dir</replaceable>
+    </arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>This command writes two NixOS configuration modules:
+
+<variablelist>
+
+  <varlistentry>
+    <term><option>/etc/nixos/hardware-configuration.nix</option></term>
+    <listitem>
+      <para>This module sets NixOS configuration options based on your
+      current hardware configuration.  In particular, it sets the
+      <option>fileSystem</option> option to reflect all currently
+      mounted file systems, the <option>swapDevices</option> option to
+      reflect active swap devices, and the
+      <option>boot.initrd.*</option> options to ensure that the
+      initial ramdisk contains any kernel modules necessary for
+      mounting the root file system.</para>
+
+      <para>If this file already exists, it is overwritten.  Thus, you
+      should not modify it manually.  Rather, you should include it
+      from your <filename>/etc/nixos/configuration.nix</filename>, and
+      re-run <command>nixos-generate-config</command> to update it
+      whenever your hardware configuration changes.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>/etc/nixos/configuration.nix</option></term>
+    <listitem>
+      <para>This is the main NixOS system configuration module.  If it
+      already exists, it’s left unchanged.  Otherwise,
+      <command>nixos-generate-config</command> will write a template
+      for you to customise.</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
+</para>
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<para>This command accepts the following options:</para>
+
+<variablelist>
+
+  <varlistentry>
+    <term><option>--root</option></term>
+    <listitem>
+      <para>If this option is given, treat the directory
+      <replaceable>root</replaceable> as the root of the file system.
+      This means that configuration files will be written to
+      <filename><replaceable>root</replaceable>/etc/nixos</filename>,
+      and that any file systems outside of
+      <replaceable>root</replaceable> are ignored for the purpose of
+      generating the <option>fileSystems</option> option.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--dir</option></term>
+    <listitem>
+      <para>If this option is given, write the configuration files to
+      the directory <replaceable>dir</replaceable> instead of
+      <filename>/etc/nixos</filename>.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--force</option></term>
+    <listitem>
+      <para>Overwrite
+      <filename>/etc/nixos/configuration.nix</filename> if it already
+      exists.</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<para>This command is typically used during NixOS installation to
+write initial configuration modules.  For example, if you created and
+mounted the target file systems on <filename>/mnt</filename> and
+<filename>/mnt/boot</filename>, you would run:
+
+<screen>
+$ nixos-generate-config --root /mnt
+</screen>
+
+The resulting file
+<filename>/mnt/etc/nixos/hardware-configuration.nix</filename> might
+look like this:
+
+<programlisting>
+# Do not modify this file!  It was generated by ‘nixos-generate-config’
+# and may be overwritten by future invocations.  Please make changes
+# to /etc/nixos/configuration.nix instead.
+{ config, pkgs, ... }:
+
+{
+  imports =
+    [ &lt;nixos/modules/installer/scan/not-detected.nix>
+    ];
+
+  boot.initrd.availableKernelModules = [ "ehci_hcd" "ahci" ];
+  boot.kernelModules = [ "kvm-intel" ];
+  boot.extraModulePackages = [ ];
+
+  fileSystems."/" =
+    { device = "/dev/disk/by-label/nixos";
+      fsType = "ext3";
+      options = "rw,data=ordered,relatime";
+    };
+
+  fileSystems."/boot" =
+    { device = "/dev/sda1";
+      fsType = "ext3";
+      options = "rw,errors=continue,user_xattr,acl,barrier=1,data=writeback,relatime";
+    };
+
+  swapDevices =
+    [ { device = "/dev/sda2"; }
+    ];
+
+  nix.maxJobs = 8;
+}
+</programlisting>
+
+It will also create a basic
+<filename>/mnt/etc/nixos/configuration.nix</filename>, which you
+should edit to customise the logical configuration of your system.
+This file includes the result of the hardware scan as follows:
+
+<programlisting>
+  imports = [ ./hardware-configuration.nix ];
+</programlisting>
+</para>
+
+<para>After installation, if your hardware configuration changes, you
+can run:
+
+<screen>
+$ nixos-generate-config
+</screen>
+
+to update <filename>/etc/nixos/hardware-configuration.nix</filename>.
+Your <filename>/etc/nixos/configuration.nix</filename> will
+<emphasis>not</emphasis> be overwritten.</para>
+
+</refsection>
+
+</refentry>
diff --git a/nixos/doc/manual/man-pages.xml b/nixos/doc/manual/man-pages.xml
index 7840e1b897b0..5178d595fda6 100644
--- a/nixos/doc/manual/man-pages.xml
+++ b/nixos/doc/manual/man-pages.xml
@@ -15,17 +15,16 @@
     </author>
 
     <copyright>
-      <year>2007</year>
-      <year>2008</year>
-      <year>2009</year>
+      <year>2007-2013</year>
       <holder>Eelco Dolstra</holder>
     </copyright>
-    
+
   </info>
-  
+
   <xi:include href="man-configuration.xml" />
   <xi:include href="man-nixos-rebuild.xml" />
+  <xi:include href="man-nixos-generate-config.xml" />
   <xi:include href="man-nixos-option.xml" />
   <xi:include href="man-nixos-build-vms.xml" />
-  
+
 </reference>