···11+# Building Specific Parts of NixOS {#sec-building-parts}
22+33+With the command `nix-build`, you can build specific parts of your NixOS
44+configuration. This is done as follows:
55+66+```ShellSession
77+$ cd /path/to/nixpkgs/nixos
88+$ nix-build -A config.option
99+```
1010+1111+where `option` is a NixOS option with type "derivation" (i.e. something
1212+that can be built). Attributes of interest include:
1313+1414+`system.build.toplevel`
1515+1616+: The top-level option that builds the entire NixOS system. Everything
1717+ else in your configuration is indirectly pulled in by this option.
1818+ This is what `nixos-rebuild` builds and what `/run/current-system`
1919+ points to afterwards.
2020+2121+ A shortcut to build this is:
2222+2323+ ```ShellSession
2424+ $ nix-build -A system
2525+ ```
2626+2727+`system.build.manual.manualHTML`
2828+2929+: The NixOS manual.
3030+3131+`system.build.etc`
3232+3333+: A tree of symlinks that form the static parts of `/etc`.
3434+3535+`system.build.initialRamdisk` , `system.build.kernel`
3636+3737+: The initial ramdisk and kernel of the system. This allows a quick
3838+ way to test whether the kernel and the initial ramdisk boot
3939+ correctly, by using QEMU's `-kernel` and `-initrd` options:
4040+4141+ ```ShellSession
4242+ $ nix-build -A config.system.build.initialRamdisk -o initrd
4343+ $ nix-build -A config.system.build.kernel -o kernel
4444+ $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
4545+ ```
4646+4747+`system.build.nixos-rebuild` , `system.build.nixos-install` , `system.build.nixos-generate-config`
4848+4949+: These build the corresponding NixOS commands.
5050+5151+`systemd.units.unit-name.unit`
5252+5353+: This builds the unit with the specified name. Note that since unit
5454+ names contain dots (e.g. `httpd.service`), you need to put them
5555+ between quotes, like this:
5656+5757+ ```ShellSession
5858+ $ nix-build -A 'config.systemd.units."httpd.service".unit'
5959+ ```
6060+6161+ You can also test individual units, without rebuilding the whole
6262+ system, by putting them in `/run/systemd/system`:
6363+6464+ ```ShellSession
6565+ $ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
6666+ /run/systemd/system/tmp-httpd.service
6767+ # systemctl daemon-reload
6868+ # systemctl start tmp-httpd.service
6969+ ```
7070+7171+ Note that the unit must not have the same name as any unit in
7272+ `/etc/systemd/system` since those take precedence over
7373+ `/run/systemd/system`. That's why the unit is installed as
7474+ `tmp-httpd.service` here.
-121
nixos/doc/manual/development/building-parts.xml
···11-<chapter xmlns="http://docbook.org/ns/docbook"
22- xmlns:xlink="http://www.w3.org/1999/xlink"
33- xmlns:xi="http://www.w3.org/2001/XInclude"
44- version="5.0"
55- xml:id="sec-building-parts">
66- <title>Building Specific Parts of NixOS</title>
77- <para>
88- With the command <command>nix-build</command>, you can build specific parts
99- of your NixOS configuration. This is done as follows:
1010-<screen>
1111-<prompt>$ </prompt>cd <replaceable>/path/to/nixpkgs/nixos</replaceable>
1212-<prompt>$ </prompt>nix-build -A config.<replaceable>option</replaceable></screen>
1313- where <replaceable>option</replaceable> is a NixOS option with type
1414- “derivation” (i.e. something that can be built). Attributes of interest
1515- include:
1616- <variablelist>
1717- <varlistentry>
1818- <term>
1919- <varname>system.build.toplevel</varname>
2020- </term>
2121- <listitem>
2222- <para>
2323- The top-level option that builds the entire NixOS system. Everything else
2424- in your configuration is indirectly pulled in by this option. This is
2525- what <command>nixos-rebuild</command> builds and what
2626- <filename>/run/current-system</filename> points to afterwards.
2727- </para>
2828- <para>
2929- A shortcut to build this is:
3030-<screen>
3131-<prompt>$ </prompt>nix-build -A system</screen>
3232- </para>
3333- </listitem>
3434- </varlistentry>
3535- <varlistentry>
3636- <term>
3737- <varname>system.build.manual.manualHTML</varname>
3838- </term>
3939- <listitem>
4040- <para>
4141- The NixOS manual.
4242- </para>
4343- </listitem>
4444- </varlistentry>
4545- <varlistentry>
4646- <term>
4747- <varname>system.build.etc</varname>
4848- </term>
4949- <listitem>
5050- <para>
5151- A tree of symlinks that form the static parts of
5252- <filename>/etc</filename>.
5353- </para>
5454- </listitem>
5555- </varlistentry>
5656- <varlistentry>
5757- <term>
5858- <varname>system.build.initialRamdisk</varname>
5959- </term>
6060- <term>
6161- <varname>system.build.kernel</varname>
6262- </term>
6363- <listitem>
6464- <para>
6565- The initial ramdisk and kernel of the system. This allows a quick way to
6666- test whether the kernel and the initial ramdisk boot correctly, by using
6767- QEMU’s <option>-kernel</option> and <option>-initrd</option> options:
6868-<screen>
6969-<prompt>$ </prompt>nix-build -A config.system.build.initialRamdisk -o initrd
7070-<prompt>$ </prompt>nix-build -A config.system.build.kernel -o kernel
7171-<prompt>$ </prompt>qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
7272-</screen>
7373- </para>
7474- </listitem>
7575- </varlistentry>
7676- <varlistentry>
7777- <term>
7878- <varname>system.build.nixos-rebuild</varname>
7979- </term>
8080- <term>
8181- <varname>system.build.nixos-install</varname>
8282- </term>
8383- <term>
8484- <varname>system.build.nixos-generate-config</varname>
8585- </term>
8686- <listitem>
8787- <para>
8888- These build the corresponding NixOS commands.
8989- </para>
9090- </listitem>
9191- </varlistentry>
9292- <varlistentry>
9393- <term>
9494- <varname>systemd.units.<replaceable>unit-name</replaceable>.unit</varname>
9595- </term>
9696- <listitem>
9797- <para>
9898- This builds the unit with the specified name. Note that since unit names
9999- contain dots (e.g. <literal>httpd.service</literal>), you need to put
100100- them between quotes, like this:
101101-<screen>
102102-<prompt>$ </prompt>nix-build -A 'config.systemd.units."httpd.service".unit'
103103-</screen>
104104- You can also test individual units, without rebuilding the whole system,
105105- by putting them in <filename>/run/systemd/system</filename>:
106106-<screen>
107107-<prompt>$ </prompt>cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
108108- /run/systemd/system/tmp-httpd.service
109109-<prompt># </prompt>systemctl daemon-reload
110110-<prompt># </prompt>systemctl start tmp-httpd.service
111111-</screen>
112112- Note that the unit must not have the same name as any unit in
113113- <filename>/etc/systemd/system</filename> since those take precedence over
114114- <filename>/run/systemd/system</filename>. That’s why the unit is
115115- installed as <filename>tmp-httpd.service</filename> here.
116116- </para>
117117- </listitem>
118118- </varlistentry>
119119- </variablelist>
120120- </para>
121121-</chapter>
···11+# Getting the Sources {#sec-getting-sources}
22+33+By default, NixOS's `nixos-rebuild` command uses the NixOS and Nixpkgs
44+sources provided by the `nixos` channel (kept in
55+`/nix/var/nix/profiles/per-user/root/channels/nixos`). To modify NixOS,
66+however, you should check out the latest sources from Git. This is as
77+follows:
88+99+```ShellSession
1010+$ git clone https://github.com/NixOS/nixpkgs
1111+$ cd nixpkgs
1212+$ git remote update origin
1313+```
1414+1515+This will check out the latest Nixpkgs sources to `./nixpkgs` the NixOS
1616+sources to `./nixpkgs/nixos`. (The NixOS source tree lives in a
1717+subdirectory of the Nixpkgs repository.) The `nixpkgs` repository has
1818+branches that correspond to each Nixpkgs/NixOS channel (see
1919+[](#sec-upgrading) for more information about channels). Thus, the
2020+Git branch `origin/nixos-17.03` will contain the latest built and tested
2121+version available in the `nixos-17.03` channel.
2222+2323+It's often inconvenient to develop directly on the master branch, since
2424+if somebody has just committed (say) a change to GCC, then the binary
2525+cache may not have caught up yet and you'll have to rebuild everything
2626+from source. So you may want to create a local branch based on your
2727+current NixOS version:
2828+2929+```ShellSession
3030+$ nixos-version
3131+17.09pre104379.6e0b727 (Hummingbird)
3232+3333+$ git checkout -b local 6e0b727
3434+```
3535+3636+Or, to base your local branch on the latest version available in a NixOS
3737+channel:
3838+3939+```ShellSession
4040+$ git remote update origin
4141+$ git checkout -b local origin/nixos-17.03
4242+```
4343+4444+(Replace `nixos-17.03` with the name of the channel you want to use.)
4545+You can use `git merge` or `git
4646+ rebase` to keep your local branch in sync with the channel, e.g.
4747+4848+```ShellSession
4949+$ git remote update origin
5050+$ git merge origin/nixos-17.03
5151+```
5252+5353+You can use `git cherry-pick` to copy commits from your local branch to
5454+the upstream branch.
5555+5656+If you want to rebuild your system using your (modified) sources, you
5757+need to tell `nixos-rebuild` about them using the `-I` flag:
5858+5959+```ShellSession
6060+# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs
6161+```
6262+6363+If you want `nix-env` to use the expressions in `/my/sources`, use
6464+`nix-env -f
6565+ /my/sources/nixpkgs`, or change the default by adding a symlink in
6666+`~/.nix-defexpr`:
6767+6868+```ShellSession
6969+$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs
7070+```
7171+7272+You may want to delete the symlink `~/.nix-defexpr/channels_root` to
7373+prevent root's NixOS channel from clashing with your own tree (this may
7474+break the command-not-found utility though). If you want to go back to
7575+the default state, you may just remove the `~/.nix-defexpr` directory
7676+completely, log out and log in again and it should have been recreated
7777+with a link to the root channels.
-85
nixos/doc/manual/development/sources.xml
···11-<chapter xmlns="http://docbook.org/ns/docbook"
22- xmlns:xlink="http://www.w3.org/1999/xlink"
33- xmlns:xi="http://www.w3.org/2001/XInclude"
44- version="5.0"
55- xml:id="sec-getting-sources">
66- <title>Getting the Sources</title>
77- <para>
88- By default, NixOS’s <command>nixos-rebuild</command> command uses the NixOS
99- and Nixpkgs sources provided by the <literal>nixos</literal> channel (kept in
1010- <filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>). To
1111- modify NixOS, however, you should check out the latest sources from Git. This
1212- is as follows:
1313-<screen>
1414-<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs
1515-<prompt>$ </prompt>cd nixpkgs
1616-<prompt>$ </prompt>git remote update origin
1717-</screen>
1818- This will check out the latest Nixpkgs sources to
1919- <filename>./nixpkgs</filename> the NixOS sources to
2020- <filename>./nixpkgs/nixos</filename>. (The NixOS source tree lives in a
2121- subdirectory of the Nixpkgs repository.) The
2222- <literal>nixpkgs</literal> repository has branches that correspond
2323- to each Nixpkgs/NixOS channel (see <xref linkend="sec-upgrading"/> for more
2424- information about channels). Thus, the Git branch
2525- <literal>origin/nixos-17.03</literal> will contain the latest built and
2626- tested version available in the <literal>nixos-17.03</literal> channel.
2727- </para>
2828- <para>
2929- It’s often inconvenient to develop directly on the master branch, since if
3030- somebody has just committed (say) a change to GCC, then the binary cache may
3131- not have caught up yet and you’ll have to rebuild everything from source.
3232- So you may want to create a local branch based on your current NixOS version:
3333-<screen>
3434-<prompt>$ </prompt>nixos-version
3535-17.09pre104379.6e0b727 (Hummingbird)
3636-3737-<prompt>$ </prompt>git checkout -b local 6e0b727
3838-</screen>
3939- Or, to base your local branch on the latest version available in a NixOS
4040- channel:
4141-<screen>
4242-<prompt>$ </prompt>git remote update origin
4343-<prompt>$ </prompt>git checkout -b local origin/nixos-17.03
4444-</screen>
4545- (Replace <literal>nixos-17.03</literal> with the name of the channel you want
4646- to use.) You can use <command>git merge</command> or <command>git
4747- rebase</command> to keep your local branch in sync with the channel, e.g.
4848-<screen>
4949-<prompt>$ </prompt>git remote update origin
5050-<prompt>$ </prompt>git merge origin/nixos-17.03
5151-</screen>
5252- You can use <command>git cherry-pick</command> to copy commits from your
5353- local branch to the upstream branch.
5454- </para>
5555- <para>
5656- If you want to rebuild your system using your (modified) sources, you need to
5757- tell <command>nixos-rebuild</command> about them using the
5858- <option>-I</option> flag:
5959-<screen>
6060-<prompt># </prompt>nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs
6161-</screen>
6262- </para>
6363- <para>
6464- If you want <command>nix-env</command> to use the expressions in
6565- <replaceable>/my/sources</replaceable>, use <command>nix-env -f
6666- <replaceable>/my/sources</replaceable>/nixpkgs</command>, or change the
6767- default by adding a symlink in <filename>~/.nix-defexpr</filename>:
6868-<screen>
6969-<prompt>$ </prompt>ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs
7070-</screen>
7171- You may want to delete the symlink
7272- <filename>~/.nix-defexpr/channels_root</filename> to prevent root’s NixOS
7373- channel from clashing with your own tree (this may break the
7474- command-not-found utility though). If you want to go back to the default
7575- state, you may just remove the <filename>~/.nix-defexpr</filename> directory
7676- completely, log out and log in again and it should have been recreated with a
7777- link to the root channels.
7878- </para>
7979-<!-- FIXME: not sure what this means.
8080-<para>You should not pass the base directory
8181-<filename><replaceable>/my/sources</replaceable></filename>
8282-to <command>nix-env</command>, as it will break after interpreting expressions
8383-in <filename>nixos/</filename> as packages.</para>
8484--->
8585-</chapter>
···11+# Testing the Installer {#ch-testing-installer}
22+33+Building, burning, and booting from an installation CD is rather
44+tedious, so here is a quick way to see if the installer works properly:
55+66+```ShellSession
77+# mount -t tmpfs none /mnt
88+# nixos-generate-config --root /mnt
99+$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install
1010+# ./result/bin/nixos-install
1111+```
1212+1313+To start a login shell in the new NixOS installation in `/mnt`:
1414+1515+```ShellSession
1616+$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter
1717+# ./result/bin/nixos-enter
1818+```
···11-<chapter xmlns="http://docbook.org/ns/docbook"
22- xmlns:xlink="http://www.w3.org/1999/xlink"
33- xmlns:xi="http://www.w3.org/2001/XInclude"
44- version="5.0"
55- xml:id="ch-testing-installer">
66- <title>Testing the Installer</title>
77- <para>
88- Building, burning, and booting from an installation CD is rather tedious, so
99- here is a quick way to see if the installer works properly:
1010-<screen>
1111-<prompt># </prompt>mount -t tmpfs none /mnt
1212-<prompt># </prompt>nixos-generate-config --root /mnt
1313-<prompt>$ </prompt>nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install
1414-<prompt># </prompt>./result/bin/nixos-install</screen>
1515- To start a login shell in the new NixOS installation in
1616- <filename>/mnt</filename>:
1717-<screen>
1818-<prompt>$ </prompt>nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter
1919-<prompt># </prompt>./result/bin/nixos-enter
2020-</screen>
2121- </para>
2222-</chapter>
···11+# Writing NixOS Documentation {#sec-writing-documentation}
22+33+As NixOS grows, so too does the need for a catalogue and explanation of
44+its extensive functionality. Collecting pertinent information from
55+disparate sources and presenting it in an accessible style would be a
66+worthy contribution to the project.
77+88+## Building the Manual {#sec-writing-docs-building-the-manual}
99+1010+The DocBook sources of the [](#book-nixos-manual) are in the
1111+[`nixos/doc/manual`](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)
1212+subdirectory of the Nixpkgs repository.
1313+1414+You can quickly validate your edits with `make`:
1515+1616+```ShellSession
1717+$ cd /path/to/nixpkgs/nixos/doc/manual
1818+$ nix-shell
1919+nix-shell$ make
2020+```
2121+2222+Once you are done making modifications to the manual, it\'s important to
2323+build it before committing. You can do that as follows:
2424+2525+```ShellSession
2626+nix-build nixos/release.nix -A manual.x86_64-linux
2727+```
2828+2929+When this command successfully finishes, it will tell you where the
3030+manual got generated. The HTML will be accessible through the `result`
3131+symlink at `./result/share/doc/nixos/index.html`.
3232+3333+## Editing DocBook XML {#sec-writing-docs-editing-docbook-xml}
3434+3535+For general information on how to write in DocBook, see [DocBook 5: The
3636+Definitive Guide](http://www.docbook.org/tdg5/en/html/docbook.html).
3737+3838+Emacs nXML Mode is very helpful for editing DocBook XML because it
3939+validates the document as you write, and precisely locates errors. To
4040+use it, see [](#sec-emacs-docbook-xml).
4141+4242+[Pandoc](http://pandoc.org) can generate DocBook XML from a multitude of
4343+formats, which makes a good starting point. Here is an example of Pandoc
4444+invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML:
4545+4646+```ShellSession
4747+pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
4848+```
4949+5050+Pandoc can also quickly convert a single `section.xml` to HTML, which is
5151+helpful when drafting.
5252+5353+Sometimes writing valid DocBook is simply too difficult. In this case,
5454+submit your documentation updates in a [GitHub
5555+Issue](https://github.com/NixOS/nixpkgs/issues/new) and someone will
5656+handle the conversion to XML for you.
5757+5858+## Creating a Topic {#sec-writing-docs-creating-a-topic}
5959+6060+You can use an existing topic as a basis for the new topic or create a
6161+topic from scratch.
6262+6363+Keep the following guidelines in mind when you create and add a topic:
6464+6565+- The NixOS [`book`](http://www.docbook.org/tdg5/en/html/book.html)
6666+ element is in `nixos/doc/manual/manual.xml`. It includes several
6767+ [`parts`](http://www.docbook.org/tdg5/en/html/book.html) which are in
6868+ subdirectories.
6969+7070+- Store the topic file in the same directory as the `part` to which it
7171+ belongs. If your topic is about configuring a NixOS module, then the
7272+ XML file can be stored alongside the module definition `nix` file.
7373+7474+- If you include multiple words in the file name, separate the words
7575+ with a dash. For example: `ipv6-config.xml`.
7676+7777+- Make sure that the `xml:id` value is unique. You can use abbreviations
7878+ if the ID is too long. For example: `nixos-config`.
7979+8080+- Determine whether your topic is a chapter or a section. If you are
8181+ unsure, open an existing topic file and check whether the main
8282+ element is chapter or section.
8383+8484+## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic}
8585+8686+Open the parent XML file and add an `xi:include` element to the list of
8787+chapters with the file name of the topic that you created. If you
8888+created a `section`, you add the file to the `chapter` file. If you created
8989+a `chapter`, you add the file to the `part` file.
9090+9191+If the topic is about configuring a NixOS module, it can be
9292+automatically included in the manual by using the `meta.doc` attribute.
9393+See [](#sec-meta-attributes) for an explanation.
···11-<chapter xmlns="http://docbook.org/ns/docbook"
22- xmlns:xlink="http://www.w3.org/1999/xlink"
33- xmlns:xi="http://www.w3.org/2001/XInclude"
44- version="5.0"
55- xml:id="sec-writing-documentation">
66- <title>Writing NixOS Documentation</title>
77- <para>
88- As NixOS grows, so too does the need for a catalogue and explanation of its
99- extensive functionality. Collecting pertinent information from disparate
1010- sources and presenting it in an accessible style would be a worthy
1111- contribution to the project.
1212- </para>
1313- <section xml:id="sec-writing-docs-building-the-manual">
1414- <title>Building the Manual</title>
1515-1616- <para>
1717- The DocBook sources of the <xref linkend="book-nixos-manual"/> are in the
1818- <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><filename>nixos/doc/manual</filename></link>
1919- subdirectory of the Nixpkgs repository.
2020- </para>
2121-2222- <para>
2323- You can quickly validate your edits with <command>make</command>:
2424- </para>
2525-2626-<screen>
2727-<prompt>$ </prompt>cd /path/to/nixpkgs/nixos/doc/manual
2828-<prompt>$ </prompt>nix-shell
2929-<prompt>nix-shell$ </prompt>make
3030-</screen>
3131-3232- <para>
3333- Once you are done making modifications to the manual, it's important to
3434- build it before committing. You can do that as follows:
3535- </para>
3636-3737-<screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
3838-3939- <para>
4040- When this command successfully finishes, it will tell you where the manual
4141- got generated. The HTML will be accessible through the
4242- <filename>result</filename> symlink at
4343- <filename>./result/share/doc/nixos/index.html</filename>.
4444- </para>
4545- </section>
4646- <section xml:id="sec-writing-docs-editing-docbook-xml">
4747- <title>Editing DocBook XML</title>
4848-4949- <para>
5050- For general information on how to write in DocBook, see
5151- <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html"> DocBook
5252- 5: The Definitive Guide</link>.
5353- </para>
5454-5555- <para>
5656- Emacs nXML Mode is very helpful for editing DocBook XML because it validates
5757- the document as you write, and precisely locates errors. To use it, see
5858- <xref linkend="sec-emacs-docbook-xml"/>.
5959- </para>
6060-6161- <para>
6262- <link xlink:href="http://pandoc.org">Pandoc</link> can generate DocBook XML
6363- from a multitude of formats, which makes a good starting point.
6464- <example xml:id="ex-pandoc-xml-conv">
6565- <title>Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML</title>
6666-<screen>pandoc -f markdown_github -t docbook5 docs.md -o my-section.md</screen>
6767- </example>
6868- Pandoc can also quickly convert a single <filename>section.xml</filename> to
6969- HTML, which is helpful when drafting.
7070- </para>
7171-7272- <para>
7373- Sometimes writing valid DocBook is simply too difficult. In this case,
7474- submit your documentation updates in a
7575- <link
7676- xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
7777- Issue</link> and someone will handle the conversion to XML for you.
7878- </para>
7979- </section>
8080- <section xml:id="sec-writing-docs-creating-a-topic">
8181- <title>Creating a Topic</title>
8282-8383- <para>
8484- You can use an existing topic as a basis for the new topic or create a topic
8585- from scratch.
8686- </para>
8787-8888- <para>
8989- Keep the following guidelines in mind when you create and add a topic:
9090- <itemizedlist>
9191- <listitem>
9292- <para>
9393- The NixOS
9494- <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>book</tag></link>
9595- element is in <filename>nixos/doc/manual/manual.xml</filename>. It
9696- includes several
9797- <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>part</tag>s</link>
9898- which are in subdirectories.
9999- </para>
100100- </listitem>
101101- <listitem>
102102- <para>
103103- Store the topic file in the same directory as the <tag>part</tag> to
104104- which it belongs. If your topic is about configuring a NixOS module, then
105105- the XML file can be stored alongside the module definition
106106- <filename>nix</filename> file.
107107- </para>
108108- </listitem>
109109- <listitem>
110110- <para>
111111- If you include multiple words in the file name, separate the words with a
112112- dash. For example: <filename>ipv6-config.xml</filename>.
113113- </para>
114114- </listitem>
115115- <listitem>
116116- <para>
117117- Make sure that the <tag>xml:id</tag> value is unique. You can use
118118- abbreviations if the ID is too long. For example:
119119- <varname>nixos-config</varname>.
120120- </para>
121121- </listitem>
122122- <listitem>
123123- <para>
124124- Determine whether your topic is a chapter or a section. If you are
125125- unsure, open an existing topic file and check whether the main element is
126126- chapter or section.
127127- </para>
128128- </listitem>
129129- </itemizedlist>
130130- </para>
131131- </section>
132132- <section xml:id="sec-writing-docs-adding-a-topic">
133133- <title>Adding a Topic to the Book</title>
134134-135135- <para>
136136- Open the parent XML file and add an <varname>xi:include</varname> element to
137137- the list of chapters with the file name of the topic that you created. If
138138- you created a <tag>section</tag>, you add the file to the <tag>chapter</tag>
139139- file. If you created a <tag>chapter</tag>, you add the file to the
140140- <tag>part</tag> file.
141141- </para>
142142-143143- <para>
144144- If the topic is about configuring a NixOS module, it can be automatically
145145- included in the manual by using the <varname>meta.doc</varname> attribute.
146146- See <xref
147147- linkend="sec-meta-attributes"/> for an explanation.
148148- </para>
149149- </section>
150150-</chapter>
···11+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-building-parts">
22+ <title>Building Specific Parts of NixOS</title>
33+ <para>
44+ With the command <literal>nix-build</literal>, you can build
55+ specific parts of your NixOS configuration. This is done as follows:
66+ </para>
77+ <programlisting>
88+$ cd /path/to/nixpkgs/nixos
99+$ nix-build -A config.option
1010+</programlisting>
1111+ <para>
1212+ where <literal>option</literal> is a NixOS option with type
1313+ <quote>derivation</quote> (i.e. something that can be built).
1414+ Attributes of interest include:
1515+ </para>
1616+ <variablelist>
1717+ <varlistentry>
1818+ <term>
1919+ <literal>system.build.toplevel</literal>
2020+ </term>
2121+ <listitem>
2222+ <para>
2323+ The top-level option that builds the entire NixOS system.
2424+ Everything else in your configuration is indirectly pulled in
2525+ by this option. This is what <literal>nixos-rebuild</literal>
2626+ builds and what <literal>/run/current-system</literal> points
2727+ to afterwards.
2828+ </para>
2929+ <para>
3030+ A shortcut to build this is:
3131+ </para>
3232+ <programlisting>
3333+$ nix-build -A system
3434+</programlisting>
3535+ </listitem>
3636+ </varlistentry>
3737+ <varlistentry>
3838+ <term>
3939+ <literal>system.build.manual.manualHTML</literal>
4040+ </term>
4141+ <listitem>
4242+ <para>
4343+ The NixOS manual.
4444+ </para>
4545+ </listitem>
4646+ </varlistentry>
4747+ <varlistentry>
4848+ <term>
4949+ <literal>system.build.etc</literal>
5050+ </term>
5151+ <listitem>
5252+ <para>
5353+ A tree of symlinks that form the static parts of
5454+ <literal>/etc</literal>.
5555+ </para>
5656+ </listitem>
5757+ </varlistentry>
5858+ <varlistentry>
5959+ <term>
6060+ <literal>system.build.initialRamdisk</literal> ,
6161+ <literal>system.build.kernel</literal>
6262+ </term>
6363+ <listitem>
6464+ <para>
6565+ The initial ramdisk and kernel of the system. This allows a
6666+ quick way to test whether the kernel and the initial ramdisk
6767+ boot correctly, by using QEMU’s <literal>-kernel</literal> and
6868+ <literal>-initrd</literal> options:
6969+ </para>
7070+ <programlisting>
7171+$ nix-build -A config.system.build.initialRamdisk -o initrd
7272+$ nix-build -A config.system.build.kernel -o kernel
7373+$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
7474+</programlisting>
7575+ </listitem>
7676+ </varlistentry>
7777+ <varlistentry>
7878+ <term>
7979+ <literal>system.build.nixos-rebuild</literal> ,
8080+ <literal>system.build.nixos-install</literal> ,
8181+ <literal>system.build.nixos-generate-config</literal>
8282+ </term>
8383+ <listitem>
8484+ <para>
8585+ These build the corresponding NixOS commands.
8686+ </para>
8787+ </listitem>
8888+ </varlistentry>
8989+ <varlistentry>
9090+ <term>
9191+ <literal>systemd.units.unit-name.unit</literal>
9292+ </term>
9393+ <listitem>
9494+ <para>
9595+ This builds the unit with the specified name. Note that since
9696+ unit names contain dots (e.g.
9797+ <literal>httpd.service</literal>), you need to put them
9898+ between quotes, like this:
9999+ </para>
100100+ <programlisting>
101101+$ nix-build -A 'config.systemd.units."httpd.service".unit'
102102+</programlisting>
103103+ <para>
104104+ You can also test individual units, without rebuilding the
105105+ whole system, by putting them in
106106+ <literal>/run/systemd/system</literal>:
107107+ </para>
108108+ <programlisting>
109109+$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
110110+ /run/systemd/system/tmp-httpd.service
111111+# systemctl daemon-reload
112112+# systemctl start tmp-httpd.service
113113+</programlisting>
114114+ <para>
115115+ Note that the unit must not have the same name as any unit in
116116+ <literal>/etc/systemd/system</literal> since those take
117117+ precedence over <literal>/run/systemd/system</literal>. That’s
118118+ why the unit is installed as
119119+ <literal>tmp-httpd.service</literal> here.
120120+ </para>
121121+ </listitem>
122122+ </varlistentry>
123123+ </variablelist>
124124+</chapter>
···11+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-getting-sources">
22+ <title>Getting the Sources</title>
33+ <para>
44+ By default, NixOS’s <literal>nixos-rebuild</literal> command uses
55+ the NixOS and Nixpkgs sources provided by the
66+ <literal>nixos</literal> channel (kept in
77+ <literal>/nix/var/nix/profiles/per-user/root/channels/nixos</literal>).
88+ To modify NixOS, however, you should check out the latest sources
99+ from Git. This is as follows:
1010+ </para>
1111+ <programlisting>
1212+$ git clone https://github.com/NixOS/nixpkgs
1313+$ cd nixpkgs
1414+$ git remote update origin
1515+</programlisting>
1616+ <para>
1717+ This will check out the latest Nixpkgs sources to
1818+ <literal>./nixpkgs</literal> the NixOS sources to
1919+ <literal>./nixpkgs/nixos</literal>. (The NixOS source tree lives in
2020+ a subdirectory of the Nixpkgs repository.) The
2121+ <literal>nixpkgs</literal> repository has branches that correspond
2222+ to each Nixpkgs/NixOS channel (see <xref linkend="sec-upgrading" />
2323+ for more information about channels). Thus, the Git branch
2424+ <literal>origin/nixos-17.03</literal> will contain the latest built
2525+ and tested version available in the <literal>nixos-17.03</literal>
2626+ channel.
2727+ </para>
2828+ <para>
2929+ It’s often inconvenient to develop directly on the master branch,
3030+ since if somebody has just committed (say) a change to GCC, then the
3131+ binary cache may not have caught up yet and you’ll have to rebuild
3232+ everything from source. So you may want to create a local branch
3333+ based on your current NixOS version:
3434+ </para>
3535+ <programlisting>
3636+$ nixos-version
3737+17.09pre104379.6e0b727 (Hummingbird)
3838+3939+$ git checkout -b local 6e0b727
4040+</programlisting>
4141+ <para>
4242+ Or, to base your local branch on the latest version available in a
4343+ NixOS channel:
4444+ </para>
4545+ <programlisting>
4646+$ git remote update origin
4747+$ git checkout -b local origin/nixos-17.03
4848+</programlisting>
4949+ <para>
5050+ (Replace <literal>nixos-17.03</literal> with the name of the channel
5151+ you want to use.) You can use <literal>git merge</literal> or
5252+ <literal>git rebase</literal> to keep your local branch in sync with
5353+ the channel, e.g.
5454+ </para>
5555+ <programlisting>
5656+$ git remote update origin
5757+$ git merge origin/nixos-17.03
5858+</programlisting>
5959+ <para>
6060+ You can use <literal>git cherry-pick</literal> to copy commits from
6161+ your local branch to the upstream branch.
6262+ </para>
6363+ <para>
6464+ If you want to rebuild your system using your (modified) sources,
6565+ you need to tell <literal>nixos-rebuild</literal> about them using
6666+ the <literal>-I</literal> flag:
6767+ </para>
6868+ <programlisting>
6969+# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs
7070+</programlisting>
7171+ <para>
7272+ If you want <literal>nix-env</literal> to use the expressions in
7373+ <literal>/my/sources</literal>, use
7474+ <literal>nix-env -f /my/sources/nixpkgs</literal>, or change the
7575+ default by adding a symlink in <literal>~/.nix-defexpr</literal>:
7676+ </para>
7777+ <programlisting>
7878+$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs
7979+</programlisting>
8080+ <para>
8181+ You may want to delete the symlink
8282+ <literal>~/.nix-defexpr/channels_root</literal> to prevent root’s
8383+ NixOS channel from clashing with your own tree (this may break the
8484+ command-not-found utility though). If you want to go back to the
8585+ default state, you may just remove the
8686+ <literal>~/.nix-defexpr</literal> directory completely, log out and
8787+ log in again and it should have been recreated with a link to the
8888+ root channels.
8989+ </para>
9090+</chapter>
···11+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="ch-testing-installer">
22+ <title>Testing the Installer</title>
33+ <para>
44+ Building, burning, and booting from an installation CD is rather
55+ tedious, so here is a quick way to see if the installer works
66+ properly:
77+ </para>
88+ <programlisting>
99+# mount -t tmpfs none /mnt
1010+# nixos-generate-config --root /mnt
1111+$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install
1212+# ./result/bin/nixos-install
1313+</programlisting>
1414+ <para>
1515+ To start a login shell in the new NixOS installation in
1616+ <literal>/mnt</literal>:
1717+ </para>
1818+ <programlisting>
1919+$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter
2020+# ./result/bin/nixos-enter
2121+</programlisting>
2222+</chapter>
···11+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-writing-documentation">
22+ <title>Writing NixOS Documentation</title>
33+ <para>
44+ As NixOS grows, so too does the need for a catalogue and explanation
55+ of its extensive functionality. Collecting pertinent information
66+ from disparate sources and presenting it in an accessible style
77+ would be a worthy contribution to the project.
88+ </para>
99+ <section xml:id="sec-writing-docs-building-the-manual">
1010+ <title>Building the Manual</title>
1111+ <para>
1212+ The DocBook sources of the <xref linkend="book-nixos-manual" />
1313+ are in the
1414+ <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><literal>nixos/doc/manual</literal></link>
1515+ subdirectory of the Nixpkgs repository.
1616+ </para>
1717+ <para>
1818+ You can quickly validate your edits with <literal>make</literal>:
1919+ </para>
2020+ <programlisting>
2121+$ cd /path/to/nixpkgs/nixos/doc/manual
2222+$ nix-shell
2323+nix-shell$ make
2424+</programlisting>
2525+ <para>
2626+ Once you are done making modifications to the manual, it's
2727+ important to build it before committing. You can do that as
2828+ follows:
2929+ </para>
3030+ <programlisting>
3131+nix-build nixos/release.nix -A manual.x86_64-linux
3232+</programlisting>
3333+ <para>
3434+ When this command successfully finishes, it will tell you where
3535+ the manual got generated. The HTML will be accessible through the
3636+ <literal>result</literal> symlink at
3737+ <literal>./result/share/doc/nixos/index.html</literal>.
3838+ </para>
3939+ </section>
4040+ <section xml:id="sec-writing-docs-editing-docbook-xml">
4141+ <title>Editing DocBook XML</title>
4242+ <para>
4343+ For general information on how to write in DocBook, see
4444+ <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html">DocBook
4545+ 5: The Definitive Guide</link>.
4646+ </para>
4747+ <para>
4848+ Emacs nXML Mode is very helpful for editing DocBook XML because it
4949+ validates the document as you write, and precisely locates errors.
5050+ To use it, see <xref linkend="sec-emacs-docbook-xml" />.
5151+ </para>
5252+ <para>
5353+ <link xlink:href="http://pandoc.org">Pandoc</link> can generate
5454+ DocBook XML from a multitude of formats, which makes a good
5555+ starting point. Here is an example of Pandoc invocation to convert
5656+ GitHub-Flavoured MarkDown to DocBook 5 XML:
5757+ </para>
5858+ <programlisting>
5959+pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
6060+</programlisting>
6161+ <para>
6262+ Pandoc can also quickly convert a single
6363+ <literal>section.xml</literal> to HTML, which is helpful when
6464+ drafting.
6565+ </para>
6666+ <para>
6767+ Sometimes writing valid DocBook is simply too difficult. In this
6868+ case, submit your documentation updates in a
6969+ <link xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
7070+ Issue</link> and someone will handle the conversion to XML for
7171+ you.
7272+ </para>
7373+ </section>
7474+ <section xml:id="sec-writing-docs-creating-a-topic">
7575+ <title>Creating a Topic</title>
7676+ <para>
7777+ You can use an existing topic as a basis for the new topic or
7878+ create a topic from scratch.
7979+ </para>
8080+ <para>
8181+ Keep the following guidelines in mind when you create and add a
8282+ topic:
8383+ </para>
8484+ <itemizedlist>
8585+ <listitem>
8686+ <para>
8787+ The NixOS
8888+ <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>book</literal></link>
8989+ element is in <literal>nixos/doc/manual/manual.xml</literal>.
9090+ It includes several
9191+ <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>parts</literal></link>
9292+ which are in subdirectories.
9393+ </para>
9494+ </listitem>
9595+ <listitem>
9696+ <para>
9797+ Store the topic file in the same directory as the
9898+ <literal>part</literal> to which it belongs. If your topic is
9999+ about configuring a NixOS module, then the XML file can be
100100+ stored alongside the module definition <literal>nix</literal>
101101+ file.
102102+ </para>
103103+ </listitem>
104104+ <listitem>
105105+ <para>
106106+ If you include multiple words in the file name, separate the
107107+ words with a dash. For example:
108108+ <literal>ipv6-config.xml</literal>.
109109+ </para>
110110+ </listitem>
111111+ <listitem>
112112+ <para>
113113+ Make sure that the <literal>xml:id</literal> value is unique.
114114+ You can use abbreviations if the ID is too long. For example:
115115+ <literal>nixos-config</literal>.
116116+ </para>
117117+ </listitem>
118118+ <listitem>
119119+ <para>
120120+ Determine whether your topic is a chapter or a section. If you
121121+ are unsure, open an existing topic file and check whether the
122122+ main element is chapter or section.
123123+ </para>
124124+ </listitem>
125125+ </itemizedlist>
126126+ </section>
127127+ <section xml:id="sec-writing-docs-adding-a-topic">
128128+ <title>Adding a Topic to the Book</title>
129129+ <para>
130130+ Open the parent XML file and add an <literal>xi:include</literal>
131131+ element to the list of chapters with the file name of the topic
132132+ that you created. If you created a <literal>section</literal>, you
133133+ add the file to the <literal>chapter</literal> file. If you
134134+ created a <literal>chapter</literal>, you add the file to the
135135+ <literal>part</literal> file.
136136+ </para>
137137+ <para>
138138+ If the topic is about configuring a NixOS module, it can be
139139+ automatically included in the manual by using the
140140+ <literal>meta.doc</literal> attribute. See
141141+ <xref linkend="sec-meta-attributes" /> for an explanation.
142142+ </para>
143143+ </section>
144144+</chapter>
+20-10
nixos/modules/misc/documentation.nix
···120120 '';
121121 };
122122123123+ man.manualPages = mkOption {
124124+ type = types.path;
125125+ default = pkgs.buildEnv {
126126+ name = "man-paths";
127127+ paths = config.environment.systemPackages;
128128+ pathsToLink = [ "/share/man" ];
129129+ extraOutputsToInstall = ["man"];
130130+ ignoreCollisions = true;
131131+ };
132132+ defaultText = "all man pages in config.environment.systemPackages";
133133+ description = ''
134134+ The manual pages to generate caches for if <option>generateCaches</option>
135135+ is enabled. Must be a path to a directory with man pages under
136136+ <literal>/share/man</literal>; see the source for an example.
137137+ Advanced users can make this a content-addressed derivation to save a few rebuilds.
138138+ '';
139139+ };
140140+123141 info.enable = mkOption {
124142 type = types.bool;
125143 default = true;
···207225 environment.extraOutputsToInstall = [ "man" ] ++ optional cfg.dev.enable "devman";
208226 environment.etc."man_db.conf".text =
209227 let
210210- manualPages = pkgs.buildEnv {
211211- name = "man-paths";
212212- paths = config.environment.systemPackages;
213213- pathsToLink = [ "/share/man" ];
214214- extraOutputsToInstall = ["man"];
215215- ignoreCollisions = true;
216216- };
217217- manualCache = pkgs.runCommandLocal "man-cache" { }
218218- ''
219219- echo "MANDB_MAP ${manualPages}/share/man $out" > man.conf
228228+ manualCache = pkgs.runCommandLocal "man-cache" { } ''
229229+ echo "MANDB_MAP ${cfg.man.manualPages}/share/man $out" > man.conf
220230 ${pkgs.man-db}/bin/mandb -C man.conf -psc >/dev/null 2>&1
221231 '';
222232 in
+2-1
nixos/modules/programs/environment.nix
···18181919 environment.variables =
2020 { NIXPKGS_CONFIG = "/etc/nix/nixpkgs-config.nix";
2121- PAGER = mkDefault "less -R";
2121+ PAGER = mkDefault "less";
2222+ LESS = mkDefault "-R";
2223 EDITOR = mkDefault "nano";
2324 XDG_CONFIG_DIRS = [ "/etc/xdg" ]; # needs to be before profile-relative paths to allow changes through environment.etc
2425 };
+7-1
nixos/modules/services/misc/nix-ssh-serve.nix
···44let cfg = config.nix.sshServe;
55 command =
66 if cfg.protocol == "ssh"
77- then "nix-store --serve"
77+ then "nix-store --serve ${lib.optionalString cfg.write "--write"}"
88 else "nix-daemon --stdio";
99in {
1010 options = {
···1515 type = types.bool;
1616 default = false;
1717 description = "Whether to enable serving the Nix store as a remote store via SSH.";
1818+ };
1919+2020+ write = mkOption {
2121+ type = types.bool;
2222+ default = false;
2323+ 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.";
1824 };
19252026 keys = mkOption {
···55To update the list of packages from nongnu (ELPA),
66771. Run `./update-nongnu`.
88-2. Check for evaluation errors: `nix-instantiate ../../../../.. -A emacs.pkgs.nongnuPackages`.
99-3. Run `git commit -m "org-packages $(date -Idate)" -- nongnu-generated.nix`
88+2. Check for evaluation errors:
99+ env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate ../../../../.. -A emacs.pkgs.nongnuPackages
1010+3. Run `git commit -m "nongnu-packages $(date -Idate)" -- nongnu-generated.nix`
10111112*/
1213
···55To update the list of packages from Org (ELPA),
66771. Run `./update-org`.
88-2. Check for evaluation errors: `nix-instantiate ../../../../.. -A emacs.pkgs.orgPackages`.
88+2. Check for evaluation errors:
99+ env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate ../../../../.. -A emacs.pkgs.orgPackages
9103. Run `git commit -m "org-packages $(date -Idate)" -- org-generated.nix`
10111112*/
···4242 install -Dm444 -t $out/lib/systemd/system systemd/step-ca.service
4343 '';
44444545- # Tests fail on darwin with
4646- # panic: httptest: failed to listen on a port: listen tcp6 [::1]:0: bind: operation not permitted [recovered]
4747- # probably some sandboxing issue
4848- doCheck = stdenv.isLinux;
4545+ # Tests start http servers which need to bind to local addresses:
4646+ # panic: httptest: failed to listen on a port: listen tcp6 [::1]:0: bind: operation not permitted
4747+ __darwinAllowLocalNetworking = true;
49485049 meta = with lib; {
5150 description = "A private certificate authority (X.509 & SSH) & ACME server for secure automated certificate management, so you can use TLS everywhere & SSO for SSH";