Merge pull request #129074 from bobby285271/pr11
nixos/doc: convert Chapter 57, 59, 60, 63 to CommonMark
This commit is contained in:
Jörg Thalheim
GitHub
commit
00f361a846
74
nixos/doc/manual/development/building-parts.chapter.md
Normal file
74
nixos/doc/manual/development/building-parts.chapter.md
Normal file
|
|
@ -0,0 +1,74 @@
|
|||
# Building Specific Parts of NixOS {#sec-building-parts}
|
||||
|
||||
With the command `nix-build`, you can build specific parts of your NixOS
|
||||
configuration. This is done as follows:
|
||||
|
||||
```ShellSession
|
||||
$ cd /path/to/nixpkgs/nixos
|
||||
$ nix-build -A config.option
|
||||
```
|
||||
|
||||
where `option` is a NixOS option with type "derivation" (i.e. something
|
||||
that can be built). Attributes of interest include:
|
||||
|
||||
`system.build.toplevel`
|
||||
|
||||
: The top-level option that builds the entire NixOS system. Everything
|
||||
else in your configuration is indirectly pulled in by this option.
|
||||
This is what `nixos-rebuild` builds and what `/run/current-system`
|
||||
points to afterwards.
|
||||
|
||||
A shortcut to build this is:
|
||||
|
||||
```ShellSession
|
||||
$ nix-build -A system
|
||||
```
|
||||
|
||||
`system.build.manual.manualHTML`
|
||||
|
||||
: The NixOS manual.
|
||||
|
||||
`system.build.etc`
|
||||
|
||||
: A tree of symlinks that form the static parts of `/etc`.
|
||||
|
||||
`system.build.initialRamdisk` , `system.build.kernel`
|
||||
|
||||
: The initial ramdisk and kernel of the system. This allows a quick
|
||||
way to test whether the kernel and the initial ramdisk boot
|
||||
correctly, by using QEMU's `-kernel` and `-initrd` options:
|
||||
|
||||
```ShellSession
|
||||
$ nix-build -A config.system.build.initialRamdisk -o initrd
|
||||
$ nix-build -A config.system.build.kernel -o kernel
|
||||
$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
|
||||
```
|
||||
|
||||
`system.build.nixos-rebuild` , `system.build.nixos-install` , `system.build.nixos-generate-config`
|
||||
|
||||
: These build the corresponding NixOS commands.
|
||||
|
||||
`systemd.units.unit-name.unit`
|
||||
|
||||
: This builds the unit with the specified name. Note that since unit
|
||||
names contain dots (e.g. `httpd.service`), you need to put them
|
||||
between quotes, like this:
|
||||
|
||||
```ShellSession
|
||||
$ nix-build -A 'config.systemd.units."httpd.service".unit'
|
||||
```
|
||||
|
||||
You can also test individual units, without rebuilding the whole
|
||||
system, by putting them in `/run/systemd/system`:
|
||||
|
||||
```ShellSession
|
||||
$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
|
||||
/run/systemd/system/tmp-httpd.service
|
||||
# systemctl daemon-reload
|
||||
# systemctl start tmp-httpd.service
|
||||
```
|
||||
|
||||
Note that the unit must not have the same name as any unit in
|
||||
`/etc/systemd/system` since those take precedence over
|
||||
`/run/systemd/system`. That's why the unit is installed as
|
||||
`tmp-httpd.service` here.
|
||||
|
|
@ -1,121 +0,0 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="sec-building-parts">
|
||||
<title>Building Specific Parts of NixOS</title>
|
||||
<para>
|
||||
With the command <command>nix-build</command>, you can build specific parts
|
||||
of your NixOS configuration. This is done as follows:
|
||||
<screen>
|
||||
<prompt>$ </prompt>cd <replaceable>/path/to/nixpkgs/nixos</replaceable>
|
||||
<prompt>$ </prompt>nix-build -A config.<replaceable>option</replaceable></screen>
|
||||
where <replaceable>option</replaceable> is a NixOS option with type
|
||||
“derivation” (i.e. something that can be built). Attributes of interest
|
||||
include:
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>system.build.toplevel</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The top-level option that builds the entire NixOS system. Everything else
|
||||
in your configuration is indirectly pulled in by this option. This is
|
||||
what <command>nixos-rebuild</command> builds and what
|
||||
<filename>/run/current-system</filename> points to afterwards.
|
||||
</para>
|
||||
<para>
|
||||
A shortcut to build this is:
|
||||
<screen>
|
||||
<prompt>$ </prompt>nix-build -A system</screen>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>system.build.manual.manualHTML</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The NixOS manual.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>system.build.etc</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A tree of symlinks that form the static parts of
|
||||
<filename>/etc</filename>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>system.build.initialRamdisk</varname>
|
||||
</term>
|
||||
<term>
|
||||
<varname>system.build.kernel</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The initial ramdisk and kernel of the system. This allows a quick way to
|
||||
test whether the kernel and the initial ramdisk boot correctly, by using
|
||||
QEMU’s <option>-kernel</option> and <option>-initrd</option> options:
|
||||
<screen>
|
||||
<prompt>$ </prompt>nix-build -A config.system.build.initialRamdisk -o initrd
|
||||
<prompt>$ </prompt>nix-build -A config.system.build.kernel -o kernel
|
||||
<prompt>$ </prompt>qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
|
||||
</screen>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>system.build.nixos-rebuild</varname>
|
||||
</term>
|
||||
<term>
|
||||
<varname>system.build.nixos-install</varname>
|
||||
</term>
|
||||
<term>
|
||||
<varname>system.build.nixos-generate-config</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
These build the corresponding NixOS commands.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>systemd.units.<replaceable>unit-name</replaceable>.unit</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This builds the unit with the specified name. Note that since unit names
|
||||
contain dots (e.g. <literal>httpd.service</literal>), you need to put
|
||||
them between quotes, like this:
|
||||
<screen>
|
||||
<prompt>$ </prompt>nix-build -A 'config.systemd.units."httpd.service".unit'
|
||||
</screen>
|
||||
You can also test individual units, without rebuilding the whole system,
|
||||
by putting them in <filename>/run/systemd/system</filename>:
|
||||
<screen>
|
||||
<prompt>$ </prompt>cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
|
||||
/run/systemd/system/tmp-httpd.service
|
||||
<prompt># </prompt>systemctl daemon-reload
|
||||
<prompt># </prompt>systemctl start tmp-httpd.service
|
||||
</screen>
|
||||
Note that the unit must not have the same name as any unit in
|
||||
<filename>/etc/systemd/system</filename> since those take precedence over
|
||||
<filename>/run/systemd/system</filename>. That’s why the unit is
|
||||
installed as <filename>tmp-httpd.service</filename> here.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</chapter>
|
||||
|
|
@ -9,11 +9,11 @@
|
|||
This chapter describes how you can modify and extend NixOS.
|
||||
</para>
|
||||
</partintro>
|
||||
<xi:include href="sources.xml" />
|
||||
<xi:include href="../from_md/development/sources.chapter.xml" />
|
||||
<xi:include href="writing-modules.xml" />
|
||||
<xi:include href="building-parts.xml" />
|
||||
<xi:include href="writing-documentation.xml" />
|
||||
<xi:include href="../from_md/development/building-parts.chapter.xml" />
|
||||
<xi:include href="../from_md/development/writing-documentation.chapter.xml" />
|
||||
<xi:include href="../from_md/development/building-nixos.chapter.xml" />
|
||||
<xi:include href="nixos-tests.xml" />
|
||||
<xi:include href="testing-installer.xml" />
|
||||
<xi:include href="../from_md/development/testing-installer.chapter.xml" />
|
||||
</part>
|
||||
|
|
|
|||
77
nixos/doc/manual/development/sources.chapter.md
Normal file
77
nixos/doc/manual/development/sources.chapter.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
# Getting the Sources {#sec-getting-sources}
|
||||
|
||||
By default, NixOS's `nixos-rebuild` command uses the NixOS and Nixpkgs
|
||||
sources provided by the `nixos` channel (kept in
|
||||
`/nix/var/nix/profiles/per-user/root/channels/nixos`). To modify NixOS,
|
||||
however, you should check out the latest sources from Git. This is as
|
||||
follows:
|
||||
|
||||
```ShellSession
|
||||
$ git clone https://github.com/NixOS/nixpkgs
|
||||
$ cd nixpkgs
|
||||
$ git remote update origin
|
||||
```
|
||||
|
||||
This will check out the latest Nixpkgs sources to `./nixpkgs` the NixOS
|
||||
sources to `./nixpkgs/nixos`. (The NixOS source tree lives in a
|
||||
subdirectory of the Nixpkgs repository.) The `nixpkgs` repository has
|
||||
branches that correspond to each Nixpkgs/NixOS channel (see
|
||||
[](#sec-upgrading) for more information about channels). Thus, the
|
||||
Git branch `origin/nixos-17.03` will contain the latest built and tested
|
||||
version available in the `nixos-17.03` channel.
|
||||
|
||||
It's often inconvenient to develop directly on the master branch, since
|
||||
if somebody has just committed (say) a change to GCC, then the binary
|
||||
cache may not have caught up yet and you'll have to rebuild everything
|
||||
from source. So you may want to create a local branch based on your
|
||||
current NixOS version:
|
||||
|
||||
```ShellSession
|
||||
$ nixos-version
|
||||
17.09pre104379.6e0b727 (Hummingbird)
|
||||
|
||||
$ git checkout -b local 6e0b727
|
||||
```
|
||||
|
||||
Or, to base your local branch on the latest version available in a NixOS
|
||||
channel:
|
||||
|
||||
```ShellSession
|
||||
$ git remote update origin
|
||||
$ git checkout -b local origin/nixos-17.03
|
||||
```
|
||||
|
||||
(Replace `nixos-17.03` with the name of the channel you want to use.)
|
||||
You can use `git merge` or `git
|
||||
rebase` to keep your local branch in sync with the channel, e.g.
|
||||
|
||||
```ShellSession
|
||||
$ git remote update origin
|
||||
$ git merge origin/nixos-17.03
|
||||
```
|
||||
|
||||
You can use `git cherry-pick` to copy commits from your local branch to
|
||||
the upstream branch.
|
||||
|
||||
If you want to rebuild your system using your (modified) sources, you
|
||||
need to tell `nixos-rebuild` about them using the `-I` flag:
|
||||
|
||||
```ShellSession
|
||||
# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs
|
||||
```
|
||||
|
||||
If you want `nix-env` to use the expressions in `/my/sources`, use
|
||||
`nix-env -f
|
||||
/my/sources/nixpkgs`, or change the default by adding a symlink in
|
||||
`~/.nix-defexpr`:
|
||||
|
||||
```ShellSession
|
||||
$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs
|
||||
```
|
||||
|
||||
You may want to delete the symlink `~/.nix-defexpr/channels_root` to
|
||||
prevent root's NixOS channel from clashing with your own tree (this may
|
||||
break the command-not-found utility though). If you want to go back to
|
||||
the default state, you may just remove the `~/.nix-defexpr` directory
|
||||
completely, log out and log in again and it should have been recreated
|
||||
with a link to the root channels.
|
||||
|
|
@ -1,85 +0,0 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="sec-getting-sources">
|
||||
<title>Getting the Sources</title>
|
||||
<para>
|
||||
By default, NixOS’s <command>nixos-rebuild</command> command uses the NixOS
|
||||
and Nixpkgs sources provided by the <literal>nixos</literal> channel (kept in
|
||||
<filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>). To
|
||||
modify NixOS, however, you should check out the latest sources from Git. This
|
||||
is as follows:
|
||||
<screen>
|
||||
<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs
|
||||
<prompt>$ </prompt>cd nixpkgs
|
||||
<prompt>$ </prompt>git remote update origin
|
||||
</screen>
|
||||
This will check out the latest Nixpkgs sources to
|
||||
<filename>./nixpkgs</filename> the NixOS sources to
|
||||
<filename>./nixpkgs/nixos</filename>. (The NixOS source tree lives in a
|
||||
subdirectory of the Nixpkgs repository.) The
|
||||
<literal>nixpkgs</literal> repository has branches that correspond
|
||||
to each Nixpkgs/NixOS channel (see <xref linkend="sec-upgrading"/> for more
|
||||
information about channels). Thus, the Git branch
|
||||
<literal>origin/nixos-17.03</literal> will contain the latest built and
|
||||
tested version available in the <literal>nixos-17.03</literal> channel.
|
||||
</para>
|
||||
<para>
|
||||
It’s often inconvenient to develop directly on the master branch, since if
|
||||
somebody has just committed (say) a change to GCC, then the binary cache may
|
||||
not have caught up yet and you’ll have to rebuild everything from source.
|
||||
So you may want to create a local branch based on your current NixOS version:
|
||||
<screen>
|
||||
<prompt>$ </prompt>nixos-version
|
||||
17.09pre104379.6e0b727 (Hummingbird)
|
||||
|
||||
<prompt>$ </prompt>git checkout -b local 6e0b727
|
||||
</screen>
|
||||
Or, to base your local branch on the latest version available in a NixOS
|
||||
channel:
|
||||
<screen>
|
||||
<prompt>$ </prompt>git remote update origin
|
||||
<prompt>$ </prompt>git checkout -b local origin/nixos-17.03
|
||||
</screen>
|
||||
(Replace <literal>nixos-17.03</literal> with the name of the channel you want
|
||||
to use.) You can use <command>git merge</command> or <command>git
|
||||
rebase</command> to keep your local branch in sync with the channel, e.g.
|
||||
<screen>
|
||||
<prompt>$ </prompt>git remote update origin
|
||||
<prompt>$ </prompt>git merge origin/nixos-17.03
|
||||
</screen>
|
||||
You can use <command>git cherry-pick</command> to copy commits from your
|
||||
local branch to the upstream branch.
|
||||
</para>
|
||||
<para>
|
||||
If you want to rebuild your system using your (modified) sources, you need to
|
||||
tell <command>nixos-rebuild</command> about them using the
|
||||
<option>-I</option> flag:
|
||||
<screen>
|
||||
<prompt># </prompt>nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs
|
||||
</screen>
|
||||
</para>
|
||||
<para>
|
||||
If you want <command>nix-env</command> to use the expressions in
|
||||
<replaceable>/my/sources</replaceable>, use <command>nix-env -f
|
||||
<replaceable>/my/sources</replaceable>/nixpkgs</command>, or change the
|
||||
default by adding a symlink in <filename>~/.nix-defexpr</filename>:
|
||||
<screen>
|
||||
<prompt>$ </prompt>ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs
|
||||
</screen>
|
||||
You may want to delete the symlink
|
||||
<filename>~/.nix-defexpr/channels_root</filename> to prevent root’s NixOS
|
||||
channel from clashing with your own tree (this may break the
|
||||
command-not-found utility though). If you want to go back to the default
|
||||
state, you may just remove the <filename>~/.nix-defexpr</filename> directory
|
||||
completely, log out and log in again and it should have been recreated with a
|
||||
link to the root channels.
|
||||
</para>
|
||||
<!-- FIXME: not sure what this means.
|
||||
<para>You should not pass the base directory
|
||||
<filename><replaceable>/my/sources</replaceable></filename>
|
||||
to <command>nix-env</command>, as it will break after interpreting expressions
|
||||
in <filename>nixos/</filename> as packages.</para>
|
||||
-->
|
||||
</chapter>
|
||||
18
nixos/doc/manual/development/testing-installer.chapter.md
Normal file
18
nixos/doc/manual/development/testing-installer.chapter.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
# Testing the Installer {#ch-testing-installer}
|
||||
|
||||
Building, burning, and booting from an installation CD is rather
|
||||
tedious, so here is a quick way to see if the installer works properly:
|
||||
|
||||
```ShellSession
|
||||
# mount -t tmpfs none /mnt
|
||||
# nixos-generate-config --root /mnt
|
||||
$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install
|
||||
# ./result/bin/nixos-install
|
||||
```
|
||||
|
||||
To start a login shell in the new NixOS installation in `/mnt`:
|
||||
|
||||
```ShellSession
|
||||
$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter
|
||||
# ./result/bin/nixos-enter
|
||||
```
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="ch-testing-installer">
|
||||
<title>Testing the Installer</title>
|
||||
<para>
|
||||
Building, burning, and booting from an installation CD is rather tedious, so
|
||||
here is a quick way to see if the installer works properly:
|
||||
<screen>
|
||||
<prompt># </prompt>mount -t tmpfs none /mnt
|
||||
<prompt># </prompt>nixos-generate-config --root /mnt
|
||||
<prompt>$ </prompt>nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install
|
||||
<prompt># </prompt>./result/bin/nixos-install</screen>
|
||||
To start a login shell in the new NixOS installation in
|
||||
<filename>/mnt</filename>:
|
||||
<screen>
|
||||
<prompt>$ </prompt>nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter
|
||||
<prompt># </prompt>./result/bin/nixos-enter
|
||||
</screen>
|
||||
</para>
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,93 @@
|
|||
# Writing NixOS Documentation {#sec-writing-documentation}
|
||||
|
||||
As NixOS grows, so too does the need for a catalogue and explanation of
|
||||
its extensive functionality. Collecting pertinent information from
|
||||
disparate sources and presenting it in an accessible style would be a
|
||||
worthy contribution to the project.
|
||||
|
||||
## Building the Manual {#sec-writing-docs-building-the-manual}
|
||||
|
||||
The DocBook sources of the [](#book-nixos-manual) are in the
|
||||
[`nixos/doc/manual`](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)
|
||||
subdirectory of the Nixpkgs repository.
|
||||
|
||||
You can quickly validate your edits with `make`:
|
||||
|
||||
```ShellSession
|
||||
$ cd /path/to/nixpkgs/nixos/doc/manual
|
||||
$ nix-shell
|
||||
nix-shell$ make
|
||||
```
|
||||
|
||||
Once you are done making modifications to the manual, it\'s important to
|
||||
build it before committing. You can do that as follows:
|
||||
|
||||
```ShellSession
|
||||
nix-build nixos/release.nix -A manual.x86_64-linux
|
||||
```
|
||||
|
||||
When this command successfully finishes, it will tell you where the
|
||||
manual got generated. The HTML will be accessible through the `result`
|
||||
symlink at `./result/share/doc/nixos/index.html`.
|
||||
|
||||
## Editing DocBook XML {#sec-writing-docs-editing-docbook-xml}
|
||||
|
||||
For general information on how to write in DocBook, see [DocBook 5: The
|
||||
Definitive Guide](http://www.docbook.org/tdg5/en/html/docbook.html).
|
||||
|
||||
Emacs nXML Mode is very helpful for editing DocBook XML because it
|
||||
validates the document as you write, and precisely locates errors. To
|
||||
use it, see [](#sec-emacs-docbook-xml).
|
||||
|
||||
[Pandoc](http://pandoc.org) can generate DocBook XML from a multitude of
|
||||
formats, which makes a good starting point. Here is an example of Pandoc
|
||||
invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML:
|
||||
|
||||
```ShellSession
|
||||
pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
|
||||
```
|
||||
|
||||
Pandoc can also quickly convert a single `section.xml` to HTML, which is
|
||||
helpful when drafting.
|
||||
|
||||
Sometimes writing valid DocBook is simply too difficult. In this case,
|
||||
submit your documentation updates in a [GitHub
|
||||
Issue](https://github.com/NixOS/nixpkgs/issues/new) and someone will
|
||||
handle the conversion to XML for you.
|
||||
|
||||
## Creating a Topic {#sec-writing-docs-creating-a-topic}
|
||||
|
||||
You can use an existing topic as a basis for the new topic or create a
|
||||
topic from scratch.
|
||||
|
||||
Keep the following guidelines in mind when you create and add a topic:
|
||||
|
||||
- The NixOS [`book`](http://www.docbook.org/tdg5/en/html/book.html)
|
||||
element is in `nixos/doc/manual/manual.xml`. It includes several
|
||||
[`parts`](http://www.docbook.org/tdg5/en/html/book.html) which are in
|
||||
subdirectories.
|
||||
|
||||
- Store the topic file in the same directory as the `part` to which it
|
||||
belongs. If your topic is about configuring a NixOS module, then the
|
||||
XML file can be stored alongside the module definition `nix` file.
|
||||
|
||||
- If you include multiple words in the file name, separate the words
|
||||
with a dash. For example: `ipv6-config.xml`.
|
||||
|
||||
- Make sure that the `xml:id` value is unique. You can use abbreviations
|
||||
if the ID is too long. For example: `nixos-config`.
|
||||
|
||||
- Determine whether your topic is a chapter or a section. If you are
|
||||
unsure, open an existing topic file and check whether the main
|
||||
element is chapter or section.
|
||||
|
||||
## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic}
|
||||
|
||||
Open the parent XML file and add an `xi:include` element to the list of
|
||||
chapters with the file name of the topic that you created. If you
|
||||
created a `section`, you add the file to the `chapter` file. If you created
|
||||
a `chapter`, you add the file to the `part` file.
|
||||
|
||||
If the topic is about configuring a NixOS module, it can be
|
||||
automatically included in the manual by using the `meta.doc` attribute.
|
||||
See [](#sec-meta-attributes) for an explanation.
|
||||
|
|
@ -1,150 +0,0 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="sec-writing-documentation">
|
||||
<title>Writing NixOS Documentation</title>
|
||||
<para>
|
||||
As NixOS grows, so too does the need for a catalogue and explanation of its
|
||||
extensive functionality. Collecting pertinent information from disparate
|
||||
sources and presenting it in an accessible style would be a worthy
|
||||
contribution to the project.
|
||||
</para>
|
||||
<section xml:id="sec-writing-docs-building-the-manual">
|
||||
<title>Building the Manual</title>
|
||||
|
||||
<para>
|
||||
The DocBook sources of the <xref linkend="book-nixos-manual"/> are in the
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><filename>nixos/doc/manual</filename></link>
|
||||
subdirectory of the Nixpkgs repository.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can quickly validate your edits with <command>make</command>:
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
<prompt>$ </prompt>cd /path/to/nixpkgs/nixos/doc/manual
|
||||
<prompt>$ </prompt>nix-shell
|
||||
<prompt>nix-shell$ </prompt>make
|
||||
</screen>
|
||||
|
||||
<para>
|
||||
Once you are done making modifications to the manual, it's important to
|
||||
build it before committing. You can do that as follows:
|
||||
</para>
|
||||
|
||||
<screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
|
||||
|
||||
<para>
|
||||
When this command successfully finishes, it will tell you where the manual
|
||||
got generated. The HTML will be accessible through the
|
||||
<filename>result</filename> symlink at
|
||||
<filename>./result/share/doc/nixos/index.html</filename>.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-writing-docs-editing-docbook-xml">
|
||||
<title>Editing DocBook XML</title>
|
||||
|
||||
<para>
|
||||
For general information on how to write in DocBook, see
|
||||
<link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html"> DocBook
|
||||
5: The Definitive Guide</link>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Emacs nXML Mode is very helpful for editing DocBook XML because it validates
|
||||
the document as you write, and precisely locates errors. To use it, see
|
||||
<xref linkend="sec-emacs-docbook-xml"/>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<link xlink:href="http://pandoc.org">Pandoc</link> can generate DocBook XML
|
||||
from a multitude of formats, which makes a good starting point.
|
||||
<example xml:id="ex-pandoc-xml-conv">
|
||||
<title>Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML</title>
|
||||
<screen>pandoc -f markdown_github -t docbook5 docs.md -o my-section.md</screen>
|
||||
</example>
|
||||
Pandoc can also quickly convert a single <filename>section.xml</filename> to
|
||||
HTML, which is helpful when drafting.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Sometimes writing valid DocBook is simply too difficult. In this case,
|
||||
submit your documentation updates in a
|
||||
<link
|
||||
xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
|
||||
Issue</link> and someone will handle the conversion to XML for you.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-writing-docs-creating-a-topic">
|
||||
<title>Creating a Topic</title>
|
||||
|
||||
<para>
|
||||
You can use an existing topic as a basis for the new topic or create a topic
|
||||
from scratch.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Keep the following guidelines in mind when you create and add a topic:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
The NixOS
|
||||
<link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>book</tag></link>
|
||||
element is in <filename>nixos/doc/manual/manual.xml</filename>. It
|
||||
includes several
|
||||
<link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>part</tag>s</link>
|
||||
which are in subdirectories.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Store the topic file in the same directory as the <tag>part</tag> to
|
||||
which it belongs. If your topic is about configuring a NixOS module, then
|
||||
the XML file can be stored alongside the module definition
|
||||
<filename>nix</filename> file.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
If you include multiple words in the file name, separate the words with a
|
||||
dash. For example: <filename>ipv6-config.xml</filename>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Make sure that the <tag>xml:id</tag> value is unique. You can use
|
||||
abbreviations if the ID is too long. For example:
|
||||
<varname>nixos-config</varname>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Determine whether your topic is a chapter or a section. If you are
|
||||
unsure, open an existing topic file and check whether the main element is
|
||||
chapter or section.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-writing-docs-adding-a-topic">
|
||||
<title>Adding a Topic to the Book</title>
|
||||
|
||||
<para>
|
||||
Open the parent XML file and add an <varname>xi:include</varname> element to
|
||||
the list of chapters with the file name of the topic that you created. If
|
||||
you created a <tag>section</tag>, you add the file to the <tag>chapter</tag>
|
||||
file. If you created a <tag>chapter</tag>, you add the file to the
|
||||
<tag>part</tag> file.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If the topic is about configuring a NixOS module, it can be automatically
|
||||
included in the manual by using the <varname>meta.doc</varname> attribute.
|
||||
See <xref
|
||||
linkend="sec-meta-attributes"/> for an explanation.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
124
nixos/doc/manual/from_md/development/building-parts.chapter.xml
Normal file
124
nixos/doc/manual/from_md/development/building-parts.chapter.xml
Normal file
|
|
@ -0,0 +1,124 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-building-parts">
|
||||
<title>Building Specific Parts of NixOS</title>
|
||||
<para>
|
||||
With the command <literal>nix-build</literal>, you can build
|
||||
specific parts of your NixOS configuration. This is done as follows:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ cd /path/to/nixpkgs/nixos
|
||||
$ nix-build -A config.option
|
||||
</programlisting>
|
||||
<para>
|
||||
where <literal>option</literal> is a NixOS option with type
|
||||
<quote>derivation</quote> (i.e. something that can be built).
|
||||
Attributes of interest include:
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>system.build.toplevel</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The top-level option that builds the entire NixOS system.
|
||||
Everything else in your configuration is indirectly pulled in
|
||||
by this option. This is what <literal>nixos-rebuild</literal>
|
||||
builds and what <literal>/run/current-system</literal> points
|
||||
to afterwards.
|
||||
</para>
|
||||
<para>
|
||||
A shortcut to build this is:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ nix-build -A system
|
||||
</programlisting>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>system.build.manual.manualHTML</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The NixOS manual.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>system.build.etc</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A tree of symlinks that form the static parts of
|
||||
<literal>/etc</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>system.build.initialRamdisk</literal> ,
|
||||
<literal>system.build.kernel</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The initial ramdisk and kernel of the system. This allows a
|
||||
quick way to test whether the kernel and the initial ramdisk
|
||||
boot correctly, by using QEMU’s <literal>-kernel</literal> and
|
||||
<literal>-initrd</literal> options:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ nix-build -A config.system.build.initialRamdisk -o initrd
|
||||
$ nix-build -A config.system.build.kernel -o kernel
|
||||
$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
|
||||
</programlisting>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>system.build.nixos-rebuild</literal> ,
|
||||
<literal>system.build.nixos-install</literal> ,
|
||||
<literal>system.build.nixos-generate-config</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
These build the corresponding NixOS commands.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>systemd.units.unit-name.unit</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This builds the unit with the specified name. Note that since
|
||||
unit names contain dots (e.g.
|
||||
<literal>httpd.service</literal>), you need to put them
|
||||
between quotes, like this:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ nix-build -A 'config.systemd.units."httpd.service".unit'
|
||||
</programlisting>
|
||||
<para>
|
||||
You can also test individual units, without rebuilding the
|
||||
whole system, by putting them in
|
||||
<literal>/run/systemd/system</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
|
||||
/run/systemd/system/tmp-httpd.service
|
||||
# systemctl daemon-reload
|
||||
# systemctl start tmp-httpd.service
|
||||
</programlisting>
|
||||
<para>
|
||||
Note that the unit must not have the same name as any unit in
|
||||
<literal>/etc/systemd/system</literal> since those take
|
||||
precedence over <literal>/run/systemd/system</literal>. That’s
|
||||
why the unit is installed as
|
||||
<literal>tmp-httpd.service</literal> here.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</chapter>
|
||||
90
nixos/doc/manual/from_md/development/sources.chapter.xml
Normal file
90
nixos/doc/manual/from_md/development/sources.chapter.xml
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-getting-sources">
|
||||
<title>Getting the Sources</title>
|
||||
<para>
|
||||
By default, NixOS’s <literal>nixos-rebuild</literal> command uses
|
||||
the NixOS and Nixpkgs sources provided by the
|
||||
<literal>nixos</literal> channel (kept in
|
||||
<literal>/nix/var/nix/profiles/per-user/root/channels/nixos</literal>).
|
||||
To modify NixOS, however, you should check out the latest sources
|
||||
from Git. This is as follows:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ git clone https://github.com/NixOS/nixpkgs
|
||||
$ cd nixpkgs
|
||||
$ git remote update origin
|
||||
</programlisting>
|
||||
<para>
|
||||
This will check out the latest Nixpkgs sources to
|
||||
<literal>./nixpkgs</literal> the NixOS sources to
|
||||
<literal>./nixpkgs/nixos</literal>. (The NixOS source tree lives in
|
||||
a subdirectory of the Nixpkgs repository.) The
|
||||
<literal>nixpkgs</literal> repository has branches that correspond
|
||||
to each Nixpkgs/NixOS channel (see <xref linkend="sec-upgrading" />
|
||||
for more information about channels). Thus, the Git branch
|
||||
<literal>origin/nixos-17.03</literal> will contain the latest built
|
||||
and tested version available in the <literal>nixos-17.03</literal>
|
||||
channel.
|
||||
</para>
|
||||
<para>
|
||||
It’s often inconvenient to develop directly on the master branch,
|
||||
since if somebody has just committed (say) a change to GCC, then the
|
||||
binary cache may not have caught up yet and you’ll have to rebuild
|
||||
everything from source. So you may want to create a local branch
|
||||
based on your current NixOS version:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ nixos-version
|
||||
17.09pre104379.6e0b727 (Hummingbird)
|
||||
|
||||
$ git checkout -b local 6e0b727
|
||||
</programlisting>
|
||||
<para>
|
||||
Or, to base your local branch on the latest version available in a
|
||||
NixOS channel:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ git remote update origin
|
||||
$ git checkout -b local origin/nixos-17.03
|
||||
</programlisting>
|
||||
<para>
|
||||
(Replace <literal>nixos-17.03</literal> with the name of the channel
|
||||
you want to use.) You can use <literal>git merge</literal> or
|
||||
<literal>git rebase</literal> to keep your local branch in sync with
|
||||
the channel, e.g.
|
||||
</para>
|
||||
<programlisting>
|
||||
$ git remote update origin
|
||||
$ git merge origin/nixos-17.03
|
||||
</programlisting>
|
||||
<para>
|
||||
You can use <literal>git cherry-pick</literal> to copy commits from
|
||||
your local branch to the upstream branch.
|
||||
</para>
|
||||
<para>
|
||||
If you want to rebuild your system using your (modified) sources,
|
||||
you need to tell <literal>nixos-rebuild</literal> about them using
|
||||
the <literal>-I</literal> flag:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs
|
||||
</programlisting>
|
||||
<para>
|
||||
If you want <literal>nix-env</literal> to use the expressions in
|
||||
<literal>/my/sources</literal>, use
|
||||
<literal>nix-env -f /my/sources/nixpkgs</literal>, or change the
|
||||
default by adding a symlink in <literal>~/.nix-defexpr</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs
|
||||
</programlisting>
|
||||
<para>
|
||||
You may want to delete the symlink
|
||||
<literal>~/.nix-defexpr/channels_root</literal> to prevent root’s
|
||||
NixOS channel from clashing with your own tree (this may break the
|
||||
command-not-found utility though). If you want to go back to the
|
||||
default state, you may just remove the
|
||||
<literal>~/.nix-defexpr</literal> directory completely, log out and
|
||||
log in again and it should have been recreated with a link to the
|
||||
root channels.
|
||||
</para>
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="ch-testing-installer">
|
||||
<title>Testing the Installer</title>
|
||||
<para>
|
||||
Building, burning, and booting from an installation CD is rather
|
||||
tedious, so here is a quick way to see if the installer works
|
||||
properly:
|
||||
</para>
|
||||
<programlisting>
|
||||
# mount -t tmpfs none /mnt
|
||||
# nixos-generate-config --root /mnt
|
||||
$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install
|
||||
# ./result/bin/nixos-install
|
||||
</programlisting>
|
||||
<para>
|
||||
To start a login shell in the new NixOS installation in
|
||||
<literal>/mnt</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter
|
||||
# ./result/bin/nixos-enter
|
||||
</programlisting>
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,144 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-writing-documentation">
|
||||
<title>Writing NixOS Documentation</title>
|
||||
<para>
|
||||
As NixOS grows, so too does the need for a catalogue and explanation
|
||||
of its extensive functionality. Collecting pertinent information
|
||||
from disparate sources and presenting it in an accessible style
|
||||
would be a worthy contribution to the project.
|
||||
</para>
|
||||
<section xml:id="sec-writing-docs-building-the-manual">
|
||||
<title>Building the Manual</title>
|
||||
<para>
|
||||
The DocBook sources of the <xref linkend="book-nixos-manual" />
|
||||
are in the
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><literal>nixos/doc/manual</literal></link>
|
||||
subdirectory of the Nixpkgs repository.
|
||||
</para>
|
||||
<para>
|
||||
You can quickly validate your edits with <literal>make</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ cd /path/to/nixpkgs/nixos/doc/manual
|
||||
$ nix-shell
|
||||
nix-shell$ make
|
||||
</programlisting>
|
||||
<para>
|
||||
Once you are done making modifications to the manual, it's
|
||||
important to build it before committing. You can do that as
|
||||
follows:
|
||||
</para>
|
||||
<programlisting>
|
||||
nix-build nixos/release.nix -A manual.x86_64-linux
|
||||
</programlisting>
|
||||
<para>
|
||||
When this command successfully finishes, it will tell you where
|
||||
the manual got generated. The HTML will be accessible through the
|
||||
<literal>result</literal> symlink at
|
||||
<literal>./result/share/doc/nixos/index.html</literal>.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-writing-docs-editing-docbook-xml">
|
||||
<title>Editing DocBook XML</title>
|
||||
<para>
|
||||
For general information on how to write in DocBook, see
|
||||
<link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html">DocBook
|
||||
5: The Definitive Guide</link>.
|
||||
</para>
|
||||
<para>
|
||||
Emacs nXML Mode is very helpful for editing DocBook XML because it
|
||||
validates the document as you write, and precisely locates errors.
|
||||
To use it, see <xref linkend="sec-emacs-docbook-xml" />.
|
||||
</para>
|
||||
<para>
|
||||
<link xlink:href="http://pandoc.org">Pandoc</link> can generate
|
||||
DocBook XML from a multitude of formats, which makes a good
|
||||
starting point. Here is an example of Pandoc invocation to convert
|
||||
GitHub-Flavoured MarkDown to DocBook 5 XML:
|
||||
</para>
|
||||
<programlisting>
|
||||
pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
|
||||
</programlisting>
|
||||
<para>
|
||||
Pandoc can also quickly convert a single
|
||||
<literal>section.xml</literal> to HTML, which is helpful when
|
||||
drafting.
|
||||
</para>
|
||||
<para>
|
||||
Sometimes writing valid DocBook is simply too difficult. In this
|
||||
case, submit your documentation updates in a
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
|
||||
Issue</link> and someone will handle the conversion to XML for
|
||||
you.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-writing-docs-creating-a-topic">
|
||||
<title>Creating a Topic</title>
|
||||
<para>
|
||||
You can use an existing topic as a basis for the new topic or
|
||||
create a topic from scratch.
|
||||
</para>
|
||||
<para>
|
||||
Keep the following guidelines in mind when you create and add a
|
||||
topic:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
The NixOS
|
||||
<link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>book</literal></link>
|
||||
element is in <literal>nixos/doc/manual/manual.xml</literal>.
|
||||
It includes several
|
||||
<link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>parts</literal></link>
|
||||
which are in subdirectories.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Store the topic file in the same directory as the
|
||||
<literal>part</literal> to which it belongs. If your topic is
|
||||
about configuring a NixOS module, then the XML file can be
|
||||
stored alongside the module definition <literal>nix</literal>
|
||||
file.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
If you include multiple words in the file name, separate the
|
||||
words with a dash. For example:
|
||||
<literal>ipv6-config.xml</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Make sure that the <literal>xml:id</literal> value is unique.
|
||||
You can use abbreviations if the ID is too long. For example:
|
||||
<literal>nixos-config</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Determine whether your topic is a chapter or a section. If you
|
||||
are unsure, open an existing topic file and check whether the
|
||||
main element is chapter or section.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="sec-writing-docs-adding-a-topic">
|
||||
<title>Adding a Topic to the Book</title>
|
||||
<para>
|
||||
Open the parent XML file and add an <literal>xi:include</literal>
|
||||
element to the list of chapters with the file name of the topic
|
||||
that you created. If you created a <literal>section</literal>, you
|
||||
add the file to the <literal>chapter</literal> file. If you
|
||||
created a <literal>chapter</literal>, you add the file to the
|
||||
<literal>part</literal> file.
|
||||
</para>
|
||||
<para>
|
||||
If the topic is about configuring a NixOS module, it can be
|
||||
automatically included in the manual by using the
|
||||
<literal>meta.doc</literal> attribute. See
|
||||
<xref linkend="sec-meta-attributes" /> for an explanation.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
Loading…
Reference in a new issue