093b51a562
That should match with a related change in nixpkgs. svn path=/nixos/trunk/; revision=20095
345 lines
12 KiB
XML
345 lines
12 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>
|
||
{config, modulesPath, pkgs, ...}: <co xml:id='conf-syntax-1' />
|
||
|
||
let
|
||
inherit (pkgs.lib) mkOption mkIf mkThenElse types; <co xml:id='conf-syntax-2' />
|
||
|
||
cfg = config.services.locate; <co xml:id='conf-syntax-4' />
|
||
locatedb = "/var/cache/locatedb";
|
||
logfile = "/var/log/updatedb";
|
||
cmd = "root updatedb --localuser=nobody --output=${locatedb} > ${logfile}";
|
||
in
|
||
|
||
{
|
||
imports = [ <co xml:id='conf-syntax-6' />
|
||
(modulesPath + /services/scheduling/cron.nix)
|
||
];
|
||
|
||
options = { <co xml:id='conf-syntax-3' />
|
||
services.locate = {
|
||
enable = mkOption {
|
||
default = false;
|
||
example = true;
|
||
type = types.bool;
|
||
description = ''
|
||
If enabled, NixOS will periodically update the database of
|
||
files used by the <command>locate</command> command.
|
||
'';
|
||
};
|
||
|
||
period = mkOption {
|
||
default = "15 02 * * *";
|
||
type = types.uniq type.string;
|
||
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.
|
||
'';
|
||
};
|
||
};
|
||
};
|
||
|
||
config = mkIf cfg.enable { <co xml:id='conf-syntax-5' />
|
||
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 functions that are 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>imports</varname> contains a list of other
|
||
module location. These modules should provide option declarations for
|
||
the current module in order to be evaluated safely.</para>
|
||
|
||
<para>When a dependence on a NixOS module has to be made, then you
|
||
should use the argument <varname>modulesPath</varname> to prefix the
|
||
location of your NixOS repository.</para>
|
||
|
||
</callout>
|
||
|
||
<callout arearefs='conf-syntax-7'>
|
||
|
||
<para>The attribute <varname>config</varname>, which should not be
|
||
confused with the argument of the same name, contains a set of option
|
||
definitions defined by this module. When there is
|
||
neither <varname>imports</varname> nor <varname>options</varname>, then
|
||
this attribute set can be return without any enclosing. This feature
|
||
allow you to write your <filename>configuration.nix</filename> as a
|
||
module which does not contains any option declarations.</para>
|
||
|
||
<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 -A <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>config</varname></term>
|
||
<listitem><para>The computer configuration generated from
|
||
the <envar>NIXOS_CONFIG</envar> environment variable (default
|
||
is <filename>/etc/nixos/configuration.nix</filename>) with the NixOS
|
||
default set of modules.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>system</varname></term>
|
||
<listitem><para>The derivation which build your computer system. It is
|
||
built by the command <command>nixos-rebuild
|
||
build</command></para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>vm</varname></term>
|
||
<listitem><para>The derivation which build your computer system inside a
|
||
virtual machine. It is built by the command <command>nixos-rebuild
|
||
build-vm</command></para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
</para>
|
||
|
||
<para>
|
||
Most parts of NixOS can be build through the <varname>config</varname>
|
||
attribute set. This attribute set allows you to have a view of the merged
|
||
option definitions and all its derivations. Important derivations are store
|
||
inside the option <option>system.build</option> and can be listed with the
|
||
command <command>nix-instantiate --xml --eval-only /etc/nixos/nixos -A
|
||
config.system.build</command>
|
||
</para>
|
||
|
||
</section>
|
||
|
||
|
||
<section>
|
||
|
||
<title>Building your own NixOS CD</title>
|
||
|
||
<para>Building a NixOS CD is as easy as configuring your own computer. The
|
||
idea is to use another module which will replace
|
||
your <filename>configuration.nix</filename> to configure the system that
|
||
would be install on the CD.</para>
|
||
|
||
<para>Default CD/DVD configurations are available
|
||
inside <filename>nixos/modules/installer/cd-dvd</filename>. To build them
|
||
you have to set <envar>NIXOS_CONFIG</envar> before
|
||
running <command>nix-build</command> to build the ISO.
|
||
|
||
<screen>
|
||
$ export NIXOS_CONFIG=/etc/nixos/nixos/modules/installer/cd-dvd/installation-cd-minimal.nix
|
||
$ nix-build /etc/nixos/nixos -A config.system.build.isoImage</screen>
|
||
|
||
</para>
|
||
|
||
<para>Before burning your CD/DVD, you can check the content of the image by mounting anywhere like
|
||
suggested by the following command:
|
||
|
||
<screen>
|
||
$ mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>
|
||
|
||
</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>
|
||
$ export NIXOS_CONFIG=/etc/nixos/nixos/modules/installer/cd-dvd/installation-cd-minimal.nix
|
||
$ nix-build /etc/nixos/nixos -A config.system.build.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 config.system.build.initialRamdisk -o initrd
|
||
$ nix-build /etc/nixos/nixos -A config.system.build.kernel -o kernel
|
||
$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
|
||
</screen>
|
||
|
||
</para>
|
||
|
||
</section>
|
||
|
||
|
||
</chapter>
|