forked from mirrors/nixpkgs
328 lines
11 KiB
XML
328 lines
11 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink">
|
||
|
||
<title>Development</title>
|
||
|
||
<para>This chapter has some random notes on hacking on
|
||
NixOS.</para>
|
||
|
||
|
||
<section>
|
||
|
||
<title>Extending NixOS</title>
|
||
|
||
<para>A unique syntax is used to express all system, hardware, computer and
|
||
service configurations. This syntax helps for reading and writing new
|
||
configuration files. It is coming with some extra strategies defined in
|
||
NixPkgs which are used to merge and evaluate all configuration files.</para>
|
||
|
||
<para>A configuration file is the same as your own computer
|
||
configuration.</para>
|
||
|
||
<example xml:id='conf-syntax'><title>Usual configuration file</title>
|
||
<programlisting>
|
||
{pkgs, config, ...}: <co xml:id='conf-syntax-1' />
|
||
|
||
###### interface
|
||
let
|
||
inherit (pkgs.lib) mkOption; <co xml:id='conf-syntax-2' />
|
||
|
||
options = { <co xml:id='conf-syntax-3' />
|
||
services = {
|
||
locate = {
|
||
|
||
enable = mkOption {
|
||
default = false;
|
||
example = true;
|
||
description = ''
|
||
If enabled, NixOS will periodically update the database of
|
||
files used by the <command>locate</command> command.
|
||
'';
|
||
};
|
||
|
||
period = mkOption {
|
||
default = "15 02 * * *";
|
||
description = ''
|
||
This option defines (in the format used by cron) when the
|
||
locate database is updated.
|
||
The default is to update at 02:15 (at night) every day.
|
||
'';
|
||
};
|
||
|
||
};
|
||
|
||
};
|
||
};
|
||
in
|
||
|
||
###### implementation
|
||
let
|
||
cfg = config.services.locate; <co xml:id='conf-syntax-4' />
|
||
inherit (pkgs.lib) mkIf mkThenElse;
|
||
|
||
locatedb = "/var/cache/locatedb";
|
||
logfile = "/var/log/updatedb";
|
||
cmd = "root updatedb --localuser=nobody --output=${locatedb} > ${logfile}";
|
||
in
|
||
|
||
mkIf cfg.enable {<co xml:id='conf-syntax-5' />
|
||
require = [ <co xml:id='conf-syntax-6' />
|
||
options
|
||
|
||
# config.services.cron
|
||
(import ../../upstart-jobs/cron.nix)
|
||
];
|
||
|
||
services = {
|
||
cron = {
|
||
systemCronJobs = mkThenElse { <co xml:id='conf-syntax-7' />
|
||
thenPart = "${cfg.period} root ${cmd}";
|
||
elsePart = "";
|
||
};
|
||
};
|
||
};
|
||
}</programlisting>
|
||
</example>
|
||
|
||
<para><xref linkend='conf-syntax' /> shows the <emphasis>configuration
|
||
file</emphasis> for the locate service which uses cron to update the
|
||
database at some dates which can be defined by the user. This nix
|
||
expression is coming
|
||
from <filename>upstart-jobs/cron/locate.nix</filename>. It shows a simple
|
||
example of a service that can be either distributed on many computer that
|
||
are using the same configuration or to shared with the community. This
|
||
file is divided in two with the interface and the implementation. Both
|
||
the interface and the implementation declare a <emphasis>configuration
|
||
set</emphasis>.
|
||
|
||
<calloutlist>
|
||
|
||
<callout arearefs='conf-syntax-1'>
|
||
|
||
<para>This line declares the arguments of the configuration file. You
|
||
can omit this line if there is no reference to <varname>pkgs</varname>
|
||
and <varname>config</varname> inside the configuration file.</para>
|
||
|
||
<para>The argument <varname>pkgs</varname> refers to NixPkgs and allow
|
||
you to access all attributes contained inside it. In this
|
||
example <varname>pkgs</varname> is used to retrieve common functions to
|
||
ease the writing of configuration files
|
||
like <varname>mkOption</varname>, <varname>mkIf</varname>
|
||
and <varname>mkThenElse</varname>.</para>
|
||
|
||
<para>The argument <varname>config</varname> corresponds to the whole
|
||
NixOS configuration. This is a set which is build by merging all
|
||
configuration files imported to set up the system. Thus all options
|
||
declared are contained inside this variable. In this
|
||
example <varname>config</varname> is used to retrieve the status of
|
||
the <varname>enable</varname> flag. The important point of this
|
||
argument is that it contains either the result of the merge of different
|
||
settings or the default value, therefore you cannot assume
|
||
that <option>config.services.locate.enable</option> is always false
|
||
because it may have been defined in another configuration file.</para>
|
||
|
||
</callout>
|
||
|
||
<callout arearefs='conf-syntax-2'>
|
||
|
||
<para>This line is used to import a function that is useful for
|
||
writing this configuration file.</para>
|
||
|
||
</callout>
|
||
|
||
<callout arearefs='conf-syntax-3'>
|
||
|
||
<para>The variable <varname>options</varname> is
|
||
a <emphasis>configuration set</emphasis> which is only used to declare
|
||
options with the function <varname>mkOption</varname> imported
|
||
from <filename>pkgs/lib/default.nix</filename>. Options may contained
|
||
any attribute but only the following have a special
|
||
meaning: <varname>default</varname>, <varname>example</varname>,
|
||
<varname>description</varname>, <varname>merge</varname>
|
||
and <varname>apply</varname>.</para>
|
||
|
||
<para>The <varname>merge</varname> attribute is used to merge all values
|
||
defined in all configuration files and this function return a value
|
||
which has the same type as the default value. If the merge function is
|
||
not defined, then a default function
|
||
(<varname>pkgs.lib.mergeDefaultOption</varname>) is used to merge
|
||
values. The <varname>merge</varname> attribute is a function which
|
||
expect two arguments: the location of the option and the list of values
|
||
which have to be merged.</para>
|
||
|
||
<para>The <varname>apply</varname> attribute is a function used to
|
||
process the option. Thus the value return
|
||
by <option>config.<replaceable>option</replaceable></option> would be
|
||
the result of the <varname>apply</varname> function called with either
|
||
the <varname>default</varname> value or the result of
|
||
the <varname>merge</varname> function.</para>
|
||
|
||
</callout>
|
||
|
||
<callout arearefs='conf-syntax-4'>
|
||
|
||
<para>This line is a common trick used to reduce the amount of
|
||
writing. In this case <varname>cfg</varname> is just a sugar over
|
||
<option>config.services.locate</option></para>
|
||
|
||
</callout>
|
||
|
||
<callout arearefs='conf-syntax-5'>
|
||
|
||
<para>This line is used to declare a special <emphasis>IF</emphasis>
|
||
statement. If you had put a usual <emphasis>IF</emphasis> statement
|
||
here, with the same condition, then you will get an infinite loop. The
|
||
reason is that your condition ask for the value of the
|
||
option <option>config.services.locate.enable</option> but in order to
|
||
get this value you have to evaluate all configuration sets including the
|
||
configuration set contained inside your file.</para>
|
||
|
||
<para>To remove this extra complexity, <varname>mkIf</varname> has been
|
||
introduced to get rid of possible infinite loop and to factor your
|
||
writing.</para>
|
||
|
||
</callout>
|
||
|
||
<callout arearefs='conf-syntax-6'>
|
||
|
||
<para>The attribute <varname>require</varname> is the only special
|
||
option that exists. It is used to embed all option declarations that
|
||
are required by your configuration file and it is also used to provide
|
||
the options that you are declaring.</para>
|
||
|
||
<para>This attribute is processed
|
||
with <varname>pkgs.lib.uniqFlatten</varname> to collect all
|
||
configuration files that are used by your system and it avoid the
|
||
insertion of duplicated elements by comparing the configuration set codes.</para>
|
||
|
||
<para>Currently, the file <filename>configuration.nix</filename>
|
||
implicitly embeds <filename>system/options.nix</filename>. If you need
|
||
a special configuration file, then you will have to add similar lines
|
||
to your computer configuration.</para>
|
||
|
||
</callout>
|
||
|
||
<callout arearefs='conf-syntax-7'>
|
||
|
||
<para>As <varname>mkIf</varname> does not need
|
||
any <emphasis>then</emphasis> part or <emphasis>else</emphasis> part,
|
||
then you can specify one on each option definition with the
|
||
function <varname>mkThenElse</varname>.</para>
|
||
|
||
<para>To avoid a lot of <varname>mkThenElse</varname> with empty
|
||
<emphasis>else</emphasis> part, a sugar has been added to infer the
|
||
corresponding <emphasis>empty</emphasis>-value of your option when the
|
||
function <varname>mkThenElse</varname> is not used.</para>
|
||
|
||
<para>If your <emphasis>then</emphasis> part
|
||
and <emphasis>else</emphasis> part are identical, then you should use
|
||
the function <varname>mkAlways</varname> to ignore the condition.</para>
|
||
|
||
<para>If you need to add another condition, then you can add <varname>mkIf</varname> to on
|
||
the appropriate location. Thus the <emphasis>then</emphasis> part will
|
||
only be used if all conditions declared with <varname>mkIf</varname>
|
||
are satisfied.</para>
|
||
|
||
</callout>
|
||
|
||
</calloutlist>
|
||
|
||
</para>
|
||
|
||
</section>
|
||
|
||
<section>
|
||
|
||
<title>Building specific parts of NixOS</title>
|
||
|
||
<para>
|
||
|
||
<screen>
|
||
$ nix-build /etc/nixos/nixos <replaceable>attr</replaceable></screen>
|
||
|
||
where <replaceable>attr</replaceable> is an attribute in
|
||
<filename>/etc/nixos/nixos/default.nix</filename>. Attributes of interest include:
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry>
|
||
<term><varname>kernel</varname></term>
|
||
<listitem><para>The kernel.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>initialRamdisk</varname></term>
|
||
<listitem><para>The initial ramdisk (initrd) for this configuration.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>bootStage1</varname></term>
|
||
<listitem><para>The stage 1 (initrd) init script.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>bootStage2</varname></term>
|
||
<listitem><para>The stage 2 init script.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>etc</varname></term>
|
||
<listitem><para>The statically computed parts of <filename>/etc</filename>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>upstartJobs</varname></term>
|
||
<listitem><para>An attribute set containing the Upstart jobs. For
|
||
instance, the <varname>sshd</varname> Upstart job can be built by
|
||
doing <literal>nix-build /etc/nixos/nixos -A
|
||
tests.upstartJobs.sshd</literal>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
</para>
|
||
|
||
</section>
|
||
|
||
|
||
<section>
|
||
|
||
<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>
|
||
$ nix-build .../nixos/configuration/rescue-cd.nix -A system.nixosInstall
|
||
$ dd if=/dev/zero of=diskimage seek=2G count=0 bs=1
|
||
$ yes | mke2fs -j diskimage
|
||
$ mount -o loop diskimage /mnt
|
||
$ ./result/bin/nixos-install</screen>
|
||
|
||
</para>
|
||
|
||
</section>
|
||
|
||
|
||
<section>
|
||
|
||
<title>Testing the <literal>initrd</literal></title>
|
||
|
||
<para>A quick way to test whether the kernel and the initial ramdisk
|
||
boot correctly is to use QEMU’s <option>-kernel</option> and
|
||
<option>-initrd</option> options:
|
||
|
||
<screen>
|
||
$ nix-build /etc/nixos/nixos -A initialRamdisk -o initrd
|
||
$ nix-build /etc/nixos/nixos -A kernel -o kernel
|
||
$ qemu-system-x86_64 -kernel ./kernel/vmlinuz -initrd ./initrd/initrd -hda /dev/null
|
||
</screen>
|
||
|
||
</para>
|
||
|
||
</section>
|
||
|
||
|
||
</chapter>
|