···1+# Building Specific Parts of NixOS {#sec-building-parts}
2+3+With the command `nix-build`, you can build specific parts of your NixOS
4+configuration. This is done as follows:
5+6+```ShellSession
7+$ cd /path/to/nixpkgs/nixos
8+$ nix-build -A config.option
9+```
10+11+where `option` is a NixOS option with type "derivation" (i.e. something
12+that can be built). Attributes of interest include:
13+14+`system.build.toplevel`
15+16+: The top-level option that builds the entire NixOS system. Everything
17+ else in your configuration is indirectly pulled in by this option.
18+ This is what `nixos-rebuild` builds and what `/run/current-system`
19+ points to afterwards.
20+21+ A shortcut to build this is:
22+23+ ```ShellSession
24+ $ nix-build -A system
25+ ```
26+27+`system.build.manual.manualHTML`
28+29+: The NixOS manual.
30+31+`system.build.etc`
32+33+: A tree of symlinks that form the static parts of `/etc`.
34+35+`system.build.initialRamdisk` , `system.build.kernel`
36+37+: The initial ramdisk and kernel of the system. This allows a quick
38+ way to test whether the kernel and the initial ramdisk boot
39+ correctly, by using QEMU's `-kernel` and `-initrd` options:
40+41+ ```ShellSession
42+ $ nix-build -A config.system.build.initialRamdisk -o initrd
43+ $ nix-build -A config.system.build.kernel -o kernel
44+ $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
45+ ```
46+47+`system.build.nixos-rebuild` , `system.build.nixos-install` , `system.build.nixos-generate-config`
48+49+: These build the corresponding NixOS commands.
50+51+`systemd.units.unit-name.unit`
52+53+: This builds the unit with the specified name. Note that since unit
54+ names contain dots (e.g. `httpd.service`), you need to put them
55+ between quotes, like this:
56+57+ ```ShellSession
58+ $ nix-build -A 'config.systemd.units."httpd.service".unit'
59+ ```
60+61+ You can also test individual units, without rebuilding the whole
62+ system, by putting them in `/run/systemd/system`:
63+64+ ```ShellSession
65+ $ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
66+ /run/systemd/system/tmp-httpd.service
67+ # systemctl daemon-reload
68+ # systemctl start tmp-httpd.service
69+ ```
70+71+ Note that the unit must not have the same name as any unit in
72+ `/etc/systemd/system` since those take precedence over
73+ `/run/systemd/system`. That's why the unit is installed as
74+ `tmp-httpd.service` here.
-121
nixos/doc/manual/development/building-parts.xml
···1-<chapter xmlns="http://docbook.org/ns/docbook"
2- xmlns:xlink="http://www.w3.org/1999/xlink"
3- xmlns:xi="http://www.w3.org/2001/XInclude"
4- version="5.0"
5- xml:id="sec-building-parts">
6- <title>Building Specific Parts of NixOS</title>
7- <para>
8- With the command <command>nix-build</command>, you can build specific parts
9- of your NixOS configuration. This is done as follows:
10-<screen>
11-<prompt>$ </prompt>cd <replaceable>/path/to/nixpkgs/nixos</replaceable>
12-<prompt>$ </prompt>nix-build -A config.<replaceable>option</replaceable></screen>
13- where <replaceable>option</replaceable> is a NixOS option with type
14- “derivation” (i.e. something that can be built). Attributes of interest
15- include:
16- <variablelist>
17- <varlistentry>
18- <term>
19- <varname>system.build.toplevel</varname>
20- </term>
21- <listitem>
22- <para>
23- The top-level option that builds the entire NixOS system. Everything else
24- in your configuration is indirectly pulled in by this option. This is
25- what <command>nixos-rebuild</command> builds and what
26- <filename>/run/current-system</filename> points to afterwards.
27- </para>
28- <para>
29- A shortcut to build this is:
30-<screen>
31-<prompt>$ </prompt>nix-build -A system</screen>
32- </para>
33- </listitem>
34- </varlistentry>
35- <varlistentry>
36- <term>
37- <varname>system.build.manual.manualHTML</varname>
38- </term>
39- <listitem>
40- <para>
41- The NixOS manual.
42- </para>
43- </listitem>
44- </varlistentry>
45- <varlistentry>
46- <term>
47- <varname>system.build.etc</varname>
48- </term>
49- <listitem>
50- <para>
51- A tree of symlinks that form the static parts of
52- <filename>/etc</filename>.
53- </para>
54- </listitem>
55- </varlistentry>
56- <varlistentry>
57- <term>
58- <varname>system.build.initialRamdisk</varname>
59- </term>
60- <term>
61- <varname>system.build.kernel</varname>
62- </term>
63- <listitem>
64- <para>
65- The initial ramdisk and kernel of the system. This allows a quick way to
66- test whether the kernel and the initial ramdisk boot correctly, by using
67- QEMU’s <option>-kernel</option> and <option>-initrd</option> options:
68-<screen>
69-<prompt>$ </prompt>nix-build -A config.system.build.initialRamdisk -o initrd
70-<prompt>$ </prompt>nix-build -A config.system.build.kernel -o kernel
71-<prompt>$ </prompt>qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
72-</screen>
73- </para>
74- </listitem>
75- </varlistentry>
76- <varlistentry>
77- <term>
78- <varname>system.build.nixos-rebuild</varname>
79- </term>
80- <term>
81- <varname>system.build.nixos-install</varname>
82- </term>
83- <term>
84- <varname>system.build.nixos-generate-config</varname>
85- </term>
86- <listitem>
87- <para>
88- These build the corresponding NixOS commands.
89- </para>
90- </listitem>
91- </varlistentry>
92- <varlistentry>
93- <term>
94- <varname>systemd.units.<replaceable>unit-name</replaceable>.unit</varname>
95- </term>
96- <listitem>
97- <para>
98- This builds the unit with the specified name. Note that since unit names
99- contain dots (e.g. <literal>httpd.service</literal>), you need to put
100- them between quotes, like this:
101-<screen>
102-<prompt>$ </prompt>nix-build -A 'config.systemd.units."httpd.service".unit'
103-</screen>
104- You can also test individual units, without rebuilding the whole system,
105- by putting them in <filename>/run/systemd/system</filename>:
106-<screen>
107-<prompt>$ </prompt>cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
108- /run/systemd/system/tmp-httpd.service
109-<prompt># </prompt>systemctl daemon-reload
110-<prompt># </prompt>systemctl start tmp-httpd.service
111-</screen>
112- Note that the unit must not have the same name as any unit in
113- <filename>/etc/systemd/system</filename> since those take precedence over
114- <filename>/run/systemd/system</filename>. That’s why the unit is
115- installed as <filename>tmp-httpd.service</filename> here.
116- </para>
117- </listitem>
118- </varlistentry>
119- </variablelist>
120- </para>
121-</chapter>
···1+# Getting the Sources {#sec-getting-sources}
2+3+By default, NixOS's `nixos-rebuild` command uses the NixOS and Nixpkgs
4+sources provided by the `nixos` channel (kept in
5+`/nix/var/nix/profiles/per-user/root/channels/nixos`). To modify NixOS,
6+however, you should check out the latest sources from Git. This is as
7+follows:
8+9+```ShellSession
10+$ git clone https://github.com/NixOS/nixpkgs
11+$ cd nixpkgs
12+$ git remote update origin
13+```
14+15+This will check out the latest Nixpkgs sources to `./nixpkgs` the NixOS
16+sources to `./nixpkgs/nixos`. (The NixOS source tree lives in a
17+subdirectory of the Nixpkgs repository.) The `nixpkgs` repository has
18+branches that correspond to each Nixpkgs/NixOS channel (see
19+[](#sec-upgrading) for more information about channels). Thus, the
20+Git branch `origin/nixos-17.03` will contain the latest built and tested
21+version available in the `nixos-17.03` channel.
22+23+It's often inconvenient to develop directly on the master branch, since
24+if somebody has just committed (say) a change to GCC, then the binary
25+cache may not have caught up yet and you'll have to rebuild everything
26+from source. So you may want to create a local branch based on your
27+current NixOS version:
28+29+```ShellSession
30+$ nixos-version
31+17.09pre104379.6e0b727 (Hummingbird)
32+33+$ git checkout -b local 6e0b727
34+```
35+36+Or, to base your local branch on the latest version available in a NixOS
37+channel:
38+39+```ShellSession
40+$ git remote update origin
41+$ git checkout -b local origin/nixos-17.03
42+```
43+44+(Replace `nixos-17.03` with the name of the channel you want to use.)
45+You can use `git merge` or `git
46+ rebase` to keep your local branch in sync with the channel, e.g.
47+48+```ShellSession
49+$ git remote update origin
50+$ git merge origin/nixos-17.03
51+```
52+53+You can use `git cherry-pick` to copy commits from your local branch to
54+the upstream branch.
55+56+If you want to rebuild your system using your (modified) sources, you
57+need to tell `nixos-rebuild` about them using the `-I` flag:
58+59+```ShellSession
60+# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs
61+```
62+63+If you want `nix-env` to use the expressions in `/my/sources`, use
64+`nix-env -f
65+ /my/sources/nixpkgs`, or change the default by adding a symlink in
66+`~/.nix-defexpr`:
67+68+```ShellSession
69+$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs
70+```
71+72+You may want to delete the symlink `~/.nix-defexpr/channels_root` to
73+prevent root's NixOS channel from clashing with your own tree (this may
74+break the command-not-found utility though). If you want to go back to
75+the default state, you may just remove the `~/.nix-defexpr` directory
76+completely, log out and log in again and it should have been recreated
77+with a link to the root channels.
-85
nixos/doc/manual/development/sources.xml
···1-<chapter xmlns="http://docbook.org/ns/docbook"
2- xmlns:xlink="http://www.w3.org/1999/xlink"
3- xmlns:xi="http://www.w3.org/2001/XInclude"
4- version="5.0"
5- xml:id="sec-getting-sources">
6- <title>Getting the Sources</title>
7- <para>
8- By default, NixOS’s <command>nixos-rebuild</command> command uses the NixOS
9- and Nixpkgs sources provided by the <literal>nixos</literal> channel (kept in
10- <filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>). To
11- modify NixOS, however, you should check out the latest sources from Git. This
12- is as follows:
13-<screen>
14-<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs
15-<prompt>$ </prompt>cd nixpkgs
16-<prompt>$ </prompt>git remote update origin
17-</screen>
18- This will check out the latest Nixpkgs sources to
19- <filename>./nixpkgs</filename> the NixOS sources to
20- <filename>./nixpkgs/nixos</filename>. (The NixOS source tree lives in a
21- subdirectory of the Nixpkgs repository.) The
22- <literal>nixpkgs</literal> repository has branches that correspond
23- to each Nixpkgs/NixOS channel (see <xref linkend="sec-upgrading"/> for more
24- information about channels). Thus, the Git branch
25- <literal>origin/nixos-17.03</literal> will contain the latest built and
26- tested version available in the <literal>nixos-17.03</literal> channel.
27- </para>
28- <para>
29- It’s often inconvenient to develop directly on the master branch, since if
30- somebody has just committed (say) a change to GCC, then the binary cache may
31- not have caught up yet and you’ll have to rebuild everything from source.
32- So you may want to create a local branch based on your current NixOS version:
33-<screen>
34-<prompt>$ </prompt>nixos-version
35-17.09pre104379.6e0b727 (Hummingbird)
36-37-<prompt>$ </prompt>git checkout -b local 6e0b727
38-</screen>
39- Or, to base your local branch on the latest version available in a NixOS
40- channel:
41-<screen>
42-<prompt>$ </prompt>git remote update origin
43-<prompt>$ </prompt>git checkout -b local origin/nixos-17.03
44-</screen>
45- (Replace <literal>nixos-17.03</literal> with the name of the channel you want
46- to use.) You can use <command>git merge</command> or <command>git
47- rebase</command> to keep your local branch in sync with the channel, e.g.
48-<screen>
49-<prompt>$ </prompt>git remote update origin
50-<prompt>$ </prompt>git merge origin/nixos-17.03
51-</screen>
52- You can use <command>git cherry-pick</command> to copy commits from your
53- local branch to the upstream branch.
54- </para>
55- <para>
56- If you want to rebuild your system using your (modified) sources, you need to
57- tell <command>nixos-rebuild</command> about them using the
58- <option>-I</option> flag:
59-<screen>
60-<prompt># </prompt>nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs
61-</screen>
62- </para>
63- <para>
64- If you want <command>nix-env</command> to use the expressions in
65- <replaceable>/my/sources</replaceable>, use <command>nix-env -f
66- <replaceable>/my/sources</replaceable>/nixpkgs</command>, or change the
67- default by adding a symlink in <filename>~/.nix-defexpr</filename>:
68-<screen>
69-<prompt>$ </prompt>ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs
70-</screen>
71- You may want to delete the symlink
72- <filename>~/.nix-defexpr/channels_root</filename> to prevent root’s NixOS
73- channel from clashing with your own tree (this may break the
74- command-not-found utility though). If you want to go back to the default
75- state, you may just remove the <filename>~/.nix-defexpr</filename> directory
76- completely, log out and log in again and it should have been recreated with a
77- link to the root channels.
78- </para>
79-<!-- FIXME: not sure what this means.
80-<para>You should not pass the base directory
81-<filename><replaceable>/my/sources</replaceable></filename>
82-to <command>nix-env</command>, as it will break after interpreting expressions
83-in <filename>nixos/</filename> as packages.</para>
84--->
85-</chapter>
···1+# Testing the Installer {#ch-testing-installer}
2+3+Building, burning, and booting from an installation CD is rather
4+tedious, so here is a quick way to see if the installer works properly:
5+6+```ShellSession
7+# mount -t tmpfs none /mnt
8+# nixos-generate-config --root /mnt
9+$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install
10+# ./result/bin/nixos-install
11+```
12+13+To start a login shell in the new NixOS installation in `/mnt`:
14+15+```ShellSession
16+$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter
17+# ./result/bin/nixos-enter
18+```
···1-<chapter xmlns="http://docbook.org/ns/docbook"
2- xmlns:xlink="http://www.w3.org/1999/xlink"
3- xmlns:xi="http://www.w3.org/2001/XInclude"
4- version="5.0"
5- xml:id="ch-testing-installer">
6- <title>Testing the Installer</title>
7- <para>
8- Building, burning, and booting from an installation CD is rather tedious, so
9- here is a quick way to see if the installer works properly:
10-<screen>
11-<prompt># </prompt>mount -t tmpfs none /mnt
12-<prompt># </prompt>nixos-generate-config --root /mnt
13-<prompt>$ </prompt>nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install
14-<prompt># </prompt>./result/bin/nixos-install</screen>
15- To start a login shell in the new NixOS installation in
16- <filename>/mnt</filename>:
17-<screen>
18-<prompt>$ </prompt>nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter
19-<prompt># </prompt>./result/bin/nixos-enter
20-</screen>
21- </para>
22-</chapter>
···1+# Writing NixOS Documentation {#sec-writing-documentation}
2+3+As NixOS grows, so too does the need for a catalogue and explanation of
4+its extensive functionality. Collecting pertinent information from
5+disparate sources and presenting it in an accessible style would be a
6+worthy contribution to the project.
7+8+## Building the Manual {#sec-writing-docs-building-the-manual}
9+10+The DocBook sources of the [](#book-nixos-manual) are in the
11+[`nixos/doc/manual`](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)
12+subdirectory of the Nixpkgs repository.
13+14+You can quickly validate your edits with `make`:
15+16+```ShellSession
17+$ cd /path/to/nixpkgs/nixos/doc/manual
18+$ nix-shell
19+nix-shell$ make
20+```
21+22+Once you are done making modifications to the manual, it\'s important to
23+build it before committing. You can do that as follows:
24+25+```ShellSession
26+nix-build nixos/release.nix -A manual.x86_64-linux
27+```
28+29+When this command successfully finishes, it will tell you where the
30+manual got generated. The HTML will be accessible through the `result`
31+symlink at `./result/share/doc/nixos/index.html`.
32+33+## Editing DocBook XML {#sec-writing-docs-editing-docbook-xml}
34+35+For general information on how to write in DocBook, see [DocBook 5: The
36+Definitive Guide](http://www.docbook.org/tdg5/en/html/docbook.html).
37+38+Emacs nXML Mode is very helpful for editing DocBook XML because it
39+validates the document as you write, and precisely locates errors. To
40+use it, see [](#sec-emacs-docbook-xml).
41+42+[Pandoc](http://pandoc.org) can generate DocBook XML from a multitude of
43+formats, which makes a good starting point. Here is an example of Pandoc
44+invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML:
45+46+```ShellSession
47+pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
48+```
49+50+Pandoc can also quickly convert a single `section.xml` to HTML, which is
51+helpful when drafting.
52+53+Sometimes writing valid DocBook is simply too difficult. In this case,
54+submit your documentation updates in a [GitHub
55+Issue](https://github.com/NixOS/nixpkgs/issues/new) and someone will
56+handle the conversion to XML for you.
57+58+## Creating a Topic {#sec-writing-docs-creating-a-topic}
59+60+You can use an existing topic as a basis for the new topic or create a
61+topic from scratch.
62+63+Keep the following guidelines in mind when you create and add a topic:
64+65+- The NixOS [`book`](http://www.docbook.org/tdg5/en/html/book.html)
66+ element is in `nixos/doc/manual/manual.xml`. It includes several
67+ [`parts`](http://www.docbook.org/tdg5/en/html/book.html) which are in
68+ subdirectories.
69+70+- Store the topic file in the same directory as the `part` to which it
71+ belongs. If your topic is about configuring a NixOS module, then the
72+ XML file can be stored alongside the module definition `nix` file.
73+74+- If you include multiple words in the file name, separate the words
75+ with a dash. For example: `ipv6-config.xml`.
76+77+- Make sure that the `xml:id` value is unique. You can use abbreviations
78+ if the ID is too long. For example: `nixos-config`.
79+80+- Determine whether your topic is a chapter or a section. If you are
81+ unsure, open an existing topic file and check whether the main
82+ element is chapter or section.
83+84+## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic}
85+86+Open the parent XML file and add an `xi:include` element to the list of
87+chapters with the file name of the topic that you created. If you
88+created a `section`, you add the file to the `chapter` file. If you created
89+a `chapter`, you add the file to the `part` file.
90+91+If the topic is about configuring a NixOS module, it can be
92+automatically included in the manual by using the `meta.doc` attribute.
93+See [](#sec-meta-attributes) for an explanation.
···1-<chapter xmlns="http://docbook.org/ns/docbook"
2- xmlns:xlink="http://www.w3.org/1999/xlink"
3- xmlns:xi="http://www.w3.org/2001/XInclude"
4- version="5.0"
5- xml:id="sec-writing-documentation">
6- <title>Writing NixOS Documentation</title>
7- <para>
8- As NixOS grows, so too does the need for a catalogue and explanation of its
9- extensive functionality. Collecting pertinent information from disparate
10- sources and presenting it in an accessible style would be a worthy
11- contribution to the project.
12- </para>
13- <section xml:id="sec-writing-docs-building-the-manual">
14- <title>Building the Manual</title>
15-16- <para>
17- The DocBook sources of the <xref linkend="book-nixos-manual"/> are in the
18- <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><filename>nixos/doc/manual</filename></link>
19- subdirectory of the Nixpkgs repository.
20- </para>
21-22- <para>
23- You can quickly validate your edits with <command>make</command>:
24- </para>
25-26-<screen>
27-<prompt>$ </prompt>cd /path/to/nixpkgs/nixos/doc/manual
28-<prompt>$ </prompt>nix-shell
29-<prompt>nix-shell$ </prompt>make
30-</screen>
31-32- <para>
33- Once you are done making modifications to the manual, it's important to
34- build it before committing. You can do that as follows:
35- </para>
36-37-<screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
38-39- <para>
40- When this command successfully finishes, it will tell you where the manual
41- got generated. The HTML will be accessible through the
42- <filename>result</filename> symlink at
43- <filename>./result/share/doc/nixos/index.html</filename>.
44- </para>
45- </section>
46- <section xml:id="sec-writing-docs-editing-docbook-xml">
47- <title>Editing DocBook XML</title>
48-49- <para>
50- For general information on how to write in DocBook, see
51- <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html"> DocBook
52- 5: The Definitive Guide</link>.
53- </para>
54-55- <para>
56- Emacs nXML Mode is very helpful for editing DocBook XML because it validates
57- the document as you write, and precisely locates errors. To use it, see
58- <xref linkend="sec-emacs-docbook-xml"/>.
59- </para>
60-61- <para>
62- <link xlink:href="http://pandoc.org">Pandoc</link> can generate DocBook XML
63- from a multitude of formats, which makes a good starting point.
64- <example xml:id="ex-pandoc-xml-conv">
65- <title>Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML</title>
66-<screen>pandoc -f markdown_github -t docbook5 docs.md -o my-section.md</screen>
67- </example>
68- Pandoc can also quickly convert a single <filename>section.xml</filename> to
69- HTML, which is helpful when drafting.
70- </para>
71-72- <para>
73- Sometimes writing valid DocBook is simply too difficult. In this case,
74- submit your documentation updates in a
75- <link
76- xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
77- Issue</link> and someone will handle the conversion to XML for you.
78- </para>
79- </section>
80- <section xml:id="sec-writing-docs-creating-a-topic">
81- <title>Creating a Topic</title>
82-83- <para>
84- You can use an existing topic as a basis for the new topic or create a topic
85- from scratch.
86- </para>
87-88- <para>
89- Keep the following guidelines in mind when you create and add a topic:
90- <itemizedlist>
91- <listitem>
92- <para>
93- The NixOS
94- <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>book</tag></link>
95- element is in <filename>nixos/doc/manual/manual.xml</filename>. It
96- includes several
97- <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>part</tag>s</link>
98- which are in subdirectories.
99- </para>
100- </listitem>
101- <listitem>
102- <para>
103- Store the topic file in the same directory as the <tag>part</tag> to
104- which it belongs. If your topic is about configuring a NixOS module, then
105- the XML file can be stored alongside the module definition
106- <filename>nix</filename> file.
107- </para>
108- </listitem>
109- <listitem>
110- <para>
111- If you include multiple words in the file name, separate the words with a
112- dash. For example: <filename>ipv6-config.xml</filename>.
113- </para>
114- </listitem>
115- <listitem>
116- <para>
117- Make sure that the <tag>xml:id</tag> value is unique. You can use
118- abbreviations if the ID is too long. For example:
119- <varname>nixos-config</varname>.
120- </para>
121- </listitem>
122- <listitem>
123- <para>
124- Determine whether your topic is a chapter or a section. If you are
125- unsure, open an existing topic file and check whether the main element is
126- chapter or section.
127- </para>
128- </listitem>
129- </itemizedlist>
130- </para>
131- </section>
132- <section xml:id="sec-writing-docs-adding-a-topic">
133- <title>Adding a Topic to the Book</title>
134-135- <para>
136- Open the parent XML file and add an <varname>xi:include</varname> element to
137- the list of chapters with the file name of the topic that you created. If
138- you created a <tag>section</tag>, you add the file to the <tag>chapter</tag>
139- file. If you created a <tag>chapter</tag>, you add the file to the
140- <tag>part</tag> file.
141- </para>
142-143- <para>
144- If the topic is about configuring a NixOS module, it can be automatically
145- included in the manual by using the <varname>meta.doc</varname> attribute.
146- See <xref
147- linkend="sec-meta-attributes"/> for an explanation.
148- </para>
149- </section>
150-</chapter>
···1+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-building-parts">
2+ <title>Building Specific Parts of NixOS</title>
3+ <para>
4+ With the command <literal>nix-build</literal>, you can build
5+ specific parts of your NixOS configuration. This is done as follows:
6+ </para>
7+ <programlisting>
8+$ cd /path/to/nixpkgs/nixos
9+$ nix-build -A config.option
10+</programlisting>
11+ <para>
12+ where <literal>option</literal> is a NixOS option with type
13+ <quote>derivation</quote> (i.e. something that can be built).
14+ Attributes of interest include:
15+ </para>
16+ <variablelist>
17+ <varlistentry>
18+ <term>
19+ <literal>system.build.toplevel</literal>
20+ </term>
21+ <listitem>
22+ <para>
23+ The top-level option that builds the entire NixOS system.
24+ Everything else in your configuration is indirectly pulled in
25+ by this option. This is what <literal>nixos-rebuild</literal>
26+ builds and what <literal>/run/current-system</literal> points
27+ to afterwards.
28+ </para>
29+ <para>
30+ A shortcut to build this is:
31+ </para>
32+ <programlisting>
33+$ nix-build -A system
34+</programlisting>
35+ </listitem>
36+ </varlistentry>
37+ <varlistentry>
38+ <term>
39+ <literal>system.build.manual.manualHTML</literal>
40+ </term>
41+ <listitem>
42+ <para>
43+ The NixOS manual.
44+ </para>
45+ </listitem>
46+ </varlistentry>
47+ <varlistentry>
48+ <term>
49+ <literal>system.build.etc</literal>
50+ </term>
51+ <listitem>
52+ <para>
53+ A tree of symlinks that form the static parts of
54+ <literal>/etc</literal>.
55+ </para>
56+ </listitem>
57+ </varlistentry>
58+ <varlistentry>
59+ <term>
60+ <literal>system.build.initialRamdisk</literal> ,
61+ <literal>system.build.kernel</literal>
62+ </term>
63+ <listitem>
64+ <para>
65+ The initial ramdisk and kernel of the system. This allows a
66+ quick way to test whether the kernel and the initial ramdisk
67+ boot correctly, by using QEMU’s <literal>-kernel</literal> and
68+ <literal>-initrd</literal> options:
69+ </para>
70+ <programlisting>
71+$ nix-build -A config.system.build.initialRamdisk -o initrd
72+$ nix-build -A config.system.build.kernel -o kernel
73+$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
74+</programlisting>
75+ </listitem>
76+ </varlistentry>
77+ <varlistentry>
78+ <term>
79+ <literal>system.build.nixos-rebuild</literal> ,
80+ <literal>system.build.nixos-install</literal> ,
81+ <literal>system.build.nixos-generate-config</literal>
82+ </term>
83+ <listitem>
84+ <para>
85+ These build the corresponding NixOS commands.
86+ </para>
87+ </listitem>
88+ </varlistentry>
89+ <varlistentry>
90+ <term>
91+ <literal>systemd.units.unit-name.unit</literal>
92+ </term>
93+ <listitem>
94+ <para>
95+ This builds the unit with the specified name. Note that since
96+ unit names contain dots (e.g.
97+ <literal>httpd.service</literal>), you need to put them
98+ between quotes, like this:
99+ </para>
100+ <programlisting>
101+$ nix-build -A 'config.systemd.units."httpd.service".unit'
102+</programlisting>
103+ <para>
104+ You can also test individual units, without rebuilding the
105+ whole system, by putting them in
106+ <literal>/run/systemd/system</literal>:
107+ </para>
108+ <programlisting>
109+$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
110+ /run/systemd/system/tmp-httpd.service
111+# systemctl daemon-reload
112+# systemctl start tmp-httpd.service
113+</programlisting>
114+ <para>
115+ Note that the unit must not have the same name as any unit in
116+ <literal>/etc/systemd/system</literal> since those take
117+ precedence over <literal>/run/systemd/system</literal>. That’s
118+ why the unit is installed as
119+ <literal>tmp-httpd.service</literal> here.
120+ </para>
121+ </listitem>
122+ </varlistentry>
123+ </variablelist>
124+</chapter>
···1+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-getting-sources">
2+ <title>Getting the Sources</title>
3+ <para>
4+ By default, NixOS’s <literal>nixos-rebuild</literal> command uses
5+ the NixOS and Nixpkgs sources provided by the
6+ <literal>nixos</literal> channel (kept in
7+ <literal>/nix/var/nix/profiles/per-user/root/channels/nixos</literal>).
8+ To modify NixOS, however, you should check out the latest sources
9+ from Git. This is as follows:
10+ </para>
11+ <programlisting>
12+$ git clone https://github.com/NixOS/nixpkgs
13+$ cd nixpkgs
14+$ git remote update origin
15+</programlisting>
16+ <para>
17+ This will check out the latest Nixpkgs sources to
18+ <literal>./nixpkgs</literal> the NixOS sources to
19+ <literal>./nixpkgs/nixos</literal>. (The NixOS source tree lives in
20+ a subdirectory of the Nixpkgs repository.) The
21+ <literal>nixpkgs</literal> repository has branches that correspond
22+ to each Nixpkgs/NixOS channel (see <xref linkend="sec-upgrading" />
23+ for more information about channels). Thus, the Git branch
24+ <literal>origin/nixos-17.03</literal> will contain the latest built
25+ and tested version available in the <literal>nixos-17.03</literal>
26+ channel.
27+ </para>
28+ <para>
29+ It’s often inconvenient to develop directly on the master branch,
30+ since if somebody has just committed (say) a change to GCC, then the
31+ binary cache may not have caught up yet and you’ll have to rebuild
32+ everything from source. So you may want to create a local branch
33+ based on your current NixOS version:
34+ </para>
35+ <programlisting>
36+$ nixos-version
37+17.09pre104379.6e0b727 (Hummingbird)
38+39+$ git checkout -b local 6e0b727
40+</programlisting>
41+ <para>
42+ Or, to base your local branch on the latest version available in a
43+ NixOS channel:
44+ </para>
45+ <programlisting>
46+$ git remote update origin
47+$ git checkout -b local origin/nixos-17.03
48+</programlisting>
49+ <para>
50+ (Replace <literal>nixos-17.03</literal> with the name of the channel
51+ you want to use.) You can use <literal>git merge</literal> or
52+ <literal>git rebase</literal> to keep your local branch in sync with
53+ the channel, e.g.
54+ </para>
55+ <programlisting>
56+$ git remote update origin
57+$ git merge origin/nixos-17.03
58+</programlisting>
59+ <para>
60+ You can use <literal>git cherry-pick</literal> to copy commits from
61+ your local branch to the upstream branch.
62+ </para>
63+ <para>
64+ If you want to rebuild your system using your (modified) sources,
65+ you need to tell <literal>nixos-rebuild</literal> about them using
66+ the <literal>-I</literal> flag:
67+ </para>
68+ <programlisting>
69+# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs
70+</programlisting>
71+ <para>
72+ If you want <literal>nix-env</literal> to use the expressions in
73+ <literal>/my/sources</literal>, use
74+ <literal>nix-env -f /my/sources/nixpkgs</literal>, or change the
75+ default by adding a symlink in <literal>~/.nix-defexpr</literal>:
76+ </para>
77+ <programlisting>
78+$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs
79+</programlisting>
80+ <para>
81+ You may want to delete the symlink
82+ <literal>~/.nix-defexpr/channels_root</literal> to prevent root’s
83+ NixOS channel from clashing with your own tree (this may break the
84+ command-not-found utility though). If you want to go back to the
85+ default state, you may just remove the
86+ <literal>~/.nix-defexpr</literal> directory completely, log out and
87+ log in again and it should have been recreated with a link to the
88+ root channels.
89+ </para>
90+</chapter>
···1+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="ch-testing-installer">
2+ <title>Testing the Installer</title>
3+ <para>
4+ Building, burning, and booting from an installation CD is rather
5+ tedious, so here is a quick way to see if the installer works
6+ properly:
7+ </para>
8+ <programlisting>
9+# mount -t tmpfs none /mnt
10+# nixos-generate-config --root /mnt
11+$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install
12+# ./result/bin/nixos-install
13+</programlisting>
14+ <para>
15+ To start a login shell in the new NixOS installation in
16+ <literal>/mnt</literal>:
17+ </para>
18+ <programlisting>
19+$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter
20+# ./result/bin/nixos-enter
21+</programlisting>
22+</chapter>
···1+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-writing-documentation">
2+ <title>Writing NixOS Documentation</title>
3+ <para>
4+ As NixOS grows, so too does the need for a catalogue and explanation
5+ of its extensive functionality. Collecting pertinent information
6+ from disparate sources and presenting it in an accessible style
7+ would be a worthy contribution to the project.
8+ </para>
9+ <section xml:id="sec-writing-docs-building-the-manual">
10+ <title>Building the Manual</title>
11+ <para>
12+ The DocBook sources of the <xref linkend="book-nixos-manual" />
13+ are in the
14+ <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><literal>nixos/doc/manual</literal></link>
15+ subdirectory of the Nixpkgs repository.
16+ </para>
17+ <para>
18+ You can quickly validate your edits with <literal>make</literal>:
19+ </para>
20+ <programlisting>
21+$ cd /path/to/nixpkgs/nixos/doc/manual
22+$ nix-shell
23+nix-shell$ make
24+</programlisting>
25+ <para>
26+ Once you are done making modifications to the manual, it's
27+ important to build it before committing. You can do that as
28+ follows:
29+ </para>
30+ <programlisting>
31+nix-build nixos/release.nix -A manual.x86_64-linux
32+</programlisting>
33+ <para>
34+ When this command successfully finishes, it will tell you where
35+ the manual got generated. The HTML will be accessible through the
36+ <literal>result</literal> symlink at
37+ <literal>./result/share/doc/nixos/index.html</literal>.
38+ </para>
39+ </section>
40+ <section xml:id="sec-writing-docs-editing-docbook-xml">
41+ <title>Editing DocBook XML</title>
42+ <para>
43+ For general information on how to write in DocBook, see
44+ <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html">DocBook
45+ 5: The Definitive Guide</link>.
46+ </para>
47+ <para>
48+ Emacs nXML Mode is very helpful for editing DocBook XML because it
49+ validates the document as you write, and precisely locates errors.
50+ To use it, see <xref linkend="sec-emacs-docbook-xml" />.
51+ </para>
52+ <para>
53+ <link xlink:href="http://pandoc.org">Pandoc</link> can generate
54+ DocBook XML from a multitude of formats, which makes a good
55+ starting point. Here is an example of Pandoc invocation to convert
56+ GitHub-Flavoured MarkDown to DocBook 5 XML:
57+ </para>
58+ <programlisting>
59+pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
60+</programlisting>
61+ <para>
62+ Pandoc can also quickly convert a single
63+ <literal>section.xml</literal> to HTML, which is helpful when
64+ drafting.
65+ </para>
66+ <para>
67+ Sometimes writing valid DocBook is simply too difficult. In this
68+ case, submit your documentation updates in a
69+ <link xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
70+ Issue</link> and someone will handle the conversion to XML for
71+ you.
72+ </para>
73+ </section>
74+ <section xml:id="sec-writing-docs-creating-a-topic">
75+ <title>Creating a Topic</title>
76+ <para>
77+ You can use an existing topic as a basis for the new topic or
78+ create a topic from scratch.
79+ </para>
80+ <para>
81+ Keep the following guidelines in mind when you create and add a
82+ topic:
83+ </para>
84+ <itemizedlist>
85+ <listitem>
86+ <para>
87+ The NixOS
88+ <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>book</literal></link>
89+ element is in <literal>nixos/doc/manual/manual.xml</literal>.
90+ It includes several
91+ <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>parts</literal></link>
92+ which are in subdirectories.
93+ </para>
94+ </listitem>
95+ <listitem>
96+ <para>
97+ Store the topic file in the same directory as the
98+ <literal>part</literal> to which it belongs. If your topic is
99+ about configuring a NixOS module, then the XML file can be
100+ stored alongside the module definition <literal>nix</literal>
101+ file.
102+ </para>
103+ </listitem>
104+ <listitem>
105+ <para>
106+ If you include multiple words in the file name, separate the
107+ words with a dash. For example:
108+ <literal>ipv6-config.xml</literal>.
109+ </para>
110+ </listitem>
111+ <listitem>
112+ <para>
113+ Make sure that the <literal>xml:id</literal> value is unique.
114+ You can use abbreviations if the ID is too long. For example:
115+ <literal>nixos-config</literal>.
116+ </para>
117+ </listitem>
118+ <listitem>
119+ <para>
120+ Determine whether your topic is a chapter or a section. If you
121+ are unsure, open an existing topic file and check whether the
122+ main element is chapter or section.
123+ </para>
124+ </listitem>
125+ </itemizedlist>
126+ </section>
127+ <section xml:id="sec-writing-docs-adding-a-topic">
128+ <title>Adding a Topic to the Book</title>
129+ <para>
130+ Open the parent XML file and add an <literal>xi:include</literal>
131+ element to the list of chapters with the file name of the topic
132+ that you created. If you created a <literal>section</literal>, you
133+ add the file to the <literal>chapter</literal> file. If you
134+ created a <literal>chapter</literal>, you add the file to the
135+ <literal>part</literal> file.
136+ </para>
137+ <para>
138+ If the topic is about configuring a NixOS module, it can be
139+ automatically included in the manual by using the
140+ <literal>meta.doc</literal> attribute. See
141+ <xref linkend="sec-meta-attributes" /> for an explanation.
142+ </para>
143+ </section>
144+</chapter>
···120 '';
121 };
122123+ man.manualPages = mkOption {
124+ type = types.path;
125+ default = pkgs.buildEnv {
126+ name = "man-paths";
127+ paths = config.environment.systemPackages;
128+ pathsToLink = [ "/share/man" ];
129+ extraOutputsToInstall = ["man"];
130+ ignoreCollisions = true;
131+ };
132+ defaultText = "all man pages in config.environment.systemPackages";
133+ description = ''
134+ The manual pages to generate caches for if <option>generateCaches</option>
135+ is enabled. Must be a path to a directory with man pages under
136+ <literal>/share/man</literal>; see the source for an example.
137+ Advanced users can make this a content-addressed derivation to save a few rebuilds.
138+ '';
139+ };
140+141 info.enable = mkOption {
142 type = types.bool;
143 default = true;
···225 environment.extraOutputsToInstall = [ "man" ] ++ optional cfg.dev.enable "devman";
226 environment.etc."man_db.conf".text =
227 let
228+ manualCache = pkgs.runCommandLocal "man-cache" { } ''
229+ echo "MANDB_MAP ${cfg.man.manualPages}/share/man $out" > man.conf
00000000230 ${pkgs.man-db}/bin/mandb -C man.conf -psc >/dev/null 2>&1
231 '';
232 in
+2-1
nixos/modules/programs/environment.nix
···1819 environment.variables =
20 { NIXPKGS_CONFIG = "/etc/nix/nixpkgs-config.nix";
21- PAGER = mkDefault "less -R";
022 EDITOR = mkDefault "nano";
23 XDG_CONFIG_DIRS = [ "/etc/xdg" ]; # needs to be before profile-relative paths to allow changes through environment.etc
24 };
···1819 environment.variables =
20 { NIXPKGS_CONFIG = "/etc/nix/nixpkgs-config.nix";
21+ PAGER = mkDefault "less";
22+ LESS = mkDefault "-R";
23 EDITOR = mkDefault "nano";
24 XDG_CONFIG_DIRS = [ "/etc/xdg" ]; # needs to be before profile-relative paths to allow changes through environment.etc
25 };
+7-1
nixos/modules/services/misc/nix-ssh-serve.nix
···4let cfg = config.nix.sshServe;
5 command =
6 if cfg.protocol == "ssh"
7- then "nix-store --serve"
8 else "nix-daemon --stdio";
9in {
10 options = {
···15 type = types.bool;
16 default = false;
17 description = "Whether to enable serving the Nix store as a remote store via SSH.";
00000018 };
1920 keys = mkOption {
···4let cfg = config.nix.sshServe;
5 command =
6 if cfg.protocol == "ssh"
7+ then "nix-store --serve ${lib.optionalString cfg.write "--write"}"
8 else "nix-daemon --stdio";
9in {
10 options = {
···15 type = types.bool;
16 default = false;
17 description = "Whether to enable serving the Nix store as a remote store via SSH.";
18+ };
19+20+ write = mkOption {
21+ type = types.bool;
22+ default = false;
23+ description = "Whether to enable writing to the Nix store as a remote store via SSH. Note: the sshServe user is named nix-ssh and is not a trusted-user. nix-ssh should be added to the nix.trustedUsers option in most use cases, such as allowing remote building of derivations.";
24 };
2526 keys = mkOption {
···5To update the list of packages from nongnu (ELPA),
671. Run `./update-nongnu`.
8-2. Check for evaluation errors: `nix-instantiate ../../../../.. -A emacs.pkgs.nongnuPackages`.
9-3. Run `git commit -m "org-packages $(date -Idate)" -- nongnu-generated.nix`
01011*/
12
···5To update the list of packages from nongnu (ELPA),
671. Run `./update-nongnu`.
8+2. Check for evaluation errors:
9+ env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate ../../../../.. -A emacs.pkgs.nongnuPackages
10+3. Run `git commit -m "nongnu-packages $(date -Idate)" -- nongnu-generated.nix`
1112*/
13
···5To update the list of packages from Org (ELPA),
671. Run `./update-org`.
8-2. Check for evaluation errors: `nix-instantiate ../../../../.. -A emacs.pkgs.orgPackages`.
093. Run `git commit -m "org-packages $(date -Idate)" -- org-generated.nix`
1011*/
···5To update the list of packages from Org (ELPA),
671. Run `./update-org`.
8+2. Check for evaluation errors:
9+ env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate ../../../../.. -A emacs.pkgs.orgPackages
103. Run `git commit -m "org-packages $(date -Idate)" -- org-generated.nix`
1112*/
···42 install -Dm444 -t $out/lib/systemd/system systemd/step-ca.service
43 '';
4445- # Tests fail on darwin with
46- # panic: httptest: failed to listen on a port: listen tcp6 [::1]:0: bind: operation not permitted [recovered]
47- # probably some sandboxing issue
48- doCheck = stdenv.isLinux;
4950 meta = with lib; {
51 description = "A private certificate authority (X.509 & SSH) & ACME server for secure automated certificate management, so you can use TLS everywhere & SSO for SSH";
···42 install -Dm444 -t $out/lib/systemd/system systemd/step-ca.service
43 '';
4445+ # Tests start http servers which need to bind to local addresses:
46+ # panic: httptest: failed to listen on a port: listen tcp6 [::1]:0: bind: operation not permitted
47+ __darwinAllowLocalNetworking = true;
04849 meta = with lib; {
50 description = "A private certificate authority (X.509 & SSH) & ACME server for secure automated certificate management, so you can use TLS everywhere & SSO for SSH";