nixpkgs-suyu/doc/manual/development.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>