nixpkgs/nixos/doc/manual/development.xml

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="ch-development">

<title>Development</title>

<para>This chapter describes how you can modify and extend
NixOS.</para>


<!--===============================================================-->

<section 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-unstable</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 done using the following command:

<screen>
$ nixos-checkout <replaceable>/my/sources</replaceable>
</screen>

or

<screen>
$ mkdir -p <replaceable>/my/sources</replaceable>
$ cd <replaceable>/my/sources</replaceable>
$ nix-env -i git
$ git clone git://github.com/NixOS/nixpkgs.git
</screen>

This will check out the latest NixOS sources to
<filename><replaceable>/my/sources</replaceable>/nixpkgs/nixos</filename>
and the Nixpkgs sources to
<filename><replaceable>/my/sources</replaceable>/nixpkgs</filename>.
(The NixOS source tree lives in a subdirectory of the Nixpkgs
repository.)  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>
$ 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>
$ 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.</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>
-->

</section>


<!--===============================================================-->

<section xml:id="sec-writing-modules">

<title>Writing NixOS modules</title>

<para>NixOS has a modular system for declarative configuration.  This
system combines multiple <emphasis>modules</emphasis> to produce the
full system configuration.  One of the modules that constitute the
configuration is <filename>/etc/nixos/configuration.nix</filename>.
Most of the others live in the <link
xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><filename>nixos/modules</filename></link>
subdirectory of the Nixpkgs tree.</para>

<para>Each NixOS module is a file that handles one logical aspect of
the configuration, such as a specific kind of hardware, a service, or
network settings.  A module configuration does not have to handle
everything from scratch; it can use the functionality provided by
other modules for its implementation.  Thus a module can
<emphasis>declare</emphasis> options that can be used by other
modules, and conversely can <emphasis>define</emphasis> options
provided by other modules in its own implementation.  For example, the
module <link
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link>
declares the option <option>security.pam.services</option> that allows
other modules (e.g. <link
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>)
to define PAM services; and it defines the option
<option>environment.etc</option> (declared by <link
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>)
to cause files to be created in
<filename>/etc/pam.d</filename>.</para>

<para xml:id="para-module-syn">In <xref
linkend="sec-configuration-syntax"/>, we saw the following structure
of NixOS modules:

<programlisting>
{ config, pkgs, ... }:

{ <replaceable>option definitions</replaceable>
}
</programlisting>

This is actually an <emphasis>abbreviated</emphasis> form of module
that only defines options, but does not declare any.  The structure of
full NixOS modules is shown in <xref linkend='ex-module-syntax' />.</para>

<example xml:id='ex-module-syntax'><title>Structure of NixOS modules</title>
<programlisting>
{ config, pkgs, ... }: <co xml:id='module-syntax-1' />

{
  imports =
    [ <replaceable>paths of other modules</replaceable> <co xml:id='module-syntax-2' />
    ];

  options = {
    <replaceable>option declarations</replaceable> <co xml:id='module-syntax-3' />
  };

  config = {
    <replaceable>option definitions</replaceable> <co xml:id='module-syntax-4' />
  };
}</programlisting>
</example>

<para>The meaning of each part is as follows.

<calloutlist>
  <callout arearefs='module-syntax-1'>
    <para>This line makes the current Nix expression a function.  The
    variable <varname>pkgs</varname> contains Nixpkgs, while
    <varname>config</varname> contains the full system configuration.
    This line can be omitted if there is no reference to
    <varname>pkgs</varname> and <varname>config</varname> inside the
    module.</para>
  </callout>

  <callout arearefs='module-syntax-2'>
    <para>This list enumerates the paths to other NixOS modules that
    should be included in the evaluation of the system configuration.
    A default set of modules is defined in the file
    <filename>modules/module-list.nix</filename>.  These don't need to
    be added in the import list.</para>
  </callout>

  <callout arearefs='module-syntax-3'>
    <para>The attribute <varname>options</varname> is a nested set of
    <emphasis>option declarations</emphasis> (described below).</para>
  </callout>

  <callout arearefs='module-syntax-4'>
    <para>The attribute <varname>config</varname> is a nested set of
    <emphasis>option definitions</emphasis> (also described
    below).</para>
  </callout>
</calloutlist>

</para>

<para><xref linkend='locate-example' /> shows a module that handles
the regular update of the “locate” database, an index of all files in
the file system.  This module declares two options that can be defined
by other modules (typically the user’s
<filename>configuration.nix</filename>):
<option>services.locate.enable</option> (whether the database should
be updated) and <option>services.locate.period</option> (when the
update should be done).  It implements its functionality by defining
two options declared by other modules:
<option>systemd.services</option> (the set of all systemd services)
and <option>services.cron.systemCronJobs</option> (the list of
commands to be executed periodically by <command>cron</command>).</para>

<example xml:id='locate-example'><title>NixOS module for the “locate” service</title>
<programlisting>
{ config, lib, pkgs, ... }:

with lib;

let locatedb = "/var/cache/locatedb"; in

{
  options = {

    services.locate = {

      enable = mkOption {
        type = types.bool;
        default = false;
        description = ''
          If enabled, NixOS will periodically update the database of
          files used by the <command>locate</command> command.
        '';
      };

      period = mkOption {
        type = types.str;
        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.
        '';
      };

    };

  };

  config = {

    systemd.services.update-locatedb =
      { description = "Update Locate Database";
        path  = [ pkgs.su ];
        script =
          ''
            mkdir -m 0755 -p $(dirname ${locatedb})
            exec updatedb --localuser=nobody --output=${locatedb} --prunepaths='/tmp /var/tmp /media /run'
          '';
      };

    services.cron.systemCronJobs = optional config.services.locate.enable
      "${config.services.locate.period} root ${config.systemd.package}/bin/systemctl start update-locatedb.service";

  };
}</programlisting>
</example>

<section><title>Option declarations</title>

<para>An option declaration specifies the name, type and description
of a NixOS configuration option.  It is illegal to define an option
that hasn’t been declared in any module.  A option declaration
generally looks like this:

<programlisting>
options = {
  <replaceable>name</replaceable> = mkOption {
    type = <replaceable>type specification</replaceable>;
    default = <replaceable>default value</replaceable>;
    example = <replaceable>example value</replaceable>;
    description = "<replaceable>Description for use in the NixOS manual.</replaceable>";
  };
};
</programlisting>

</para>

<para>The function <varname>mkOption</varname> accepts the following arguments.

<variablelist>

  <varlistentry>
    <term><varname>type</varname></term>
    <listitem>
      <para>The type of the option (see below).  It may be omitted,
      but that’s not advisable since it may lead to errors that are
      hard to diagnose.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>default</varname></term>
    <listitem>
      <para>The default value used if no value is defined by any
      module.  A default is not required; in that case, if the option
      value is ever used, an error will be thrown.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>example</varname></term>
    <listitem>
      <para>An example value that will be shown in the NixOS manual.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>description</varname></term>
    <listitem>
      <para>A textual description of the option, in DocBook format,
      that will be included in the NixOS manual.</para>
    </listitem>
  </varlistentry>

</variablelist>

</para>

<para>Here is a non-exhaustive list of option types:

<variablelist>

  <varlistentry>
    <term><varname>types.bool</varname></term>
    <listitem>
      <para>A Boolean.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.int</varname></term>
    <listitem>
      <para>An integer.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.str</varname></term>
    <listitem>
      <para>A string.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.lines</varname></term>
    <listitem>
      <para>A string.  If there are multiple definitions, they are
      concatenated, with newline characters in between.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.path</varname></term>
    <listitem>
      <para>A path, defined as anything that, when coerced to a
      string, starts with a slash.  This includes derivations.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.listOf</varname> <replaceable>t</replaceable></term>
    <listitem>
      <para>A list of elements of type <replaceable>t</replaceable>
      (e.g., <literal>types.listOf types.str</literal> is a list of
      strings).  Multiple definitions are concatenated together.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.attrsOf</varname> <replaceable>t</replaceable></term>
    <listitem>
      <para>A set of elements of type <replaceable>t</replaceable>
      (e.g., <literal>types.attrsOf types.int</literal> is a set of
      name/value pairs, the values being integers).</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.nullOr</varname> <replaceable>t</replaceable></term>
    <listitem>
      <para>Either the value <literal>null</literal> or something of
      type <replaceable>t</replaceable>.</para>
    </listitem>
  </varlistentry>

</variablelist>

You can also create new types using the function
<varname>mkOptionType</varname>.  See
<filename>lib/types.nix</filename> in Nixpkgs for details.</para>

</section>


<section><title>Option definitions</title>

<para>Option definitions are generally straight-forward bindings of values to option names, like

<programlisting>
config = {
  services.httpd.enable = true;
};
</programlisting>

However, sometimes you need to wrap an option definition or set of
option definitions in a <emphasis>property</emphasis> to achieve
certain effects:</para>

<simplesect><title>Delaying conditionals</title>

<para>If a set of option definitions is conditional on the value of
another option, you may need to use <varname>mkIf</varname>.
Consider, for instance:

<programlisting>
config = if config.services.httpd.enable then {
  environment.systemPackages = [ <replaceable>...</replaceable> ];
  <replaceable>...</replaceable>
} else {};
</programlisting>

This definition will cause Nix to fail with an “infinite recursion”
error.  Why?  Because the value of
<option>config.services.httpd.enable</option> depends on the value
being constructed here.  After all, you could also write the clearly
circular and contradictory:
<programlisting>
config = if config.services.httpd.enable then {
  services.httpd.enable = false;
} else {
  services.httpd.enable = true;
};
</programlisting>

The solution is to write:

<programlisting>
config = mkIf config.services.httpd.enable {
  environment.systemPackages = [ <replaceable>...</replaceable> ];
  <replaceable>...</replaceable>
};
</programlisting>

The special function <varname>mkIf</varname> causes the evaluation of
the conditional to be “pushed down” into the individual definitions,
as if you had written:

<programlisting>
config = {
  environment.systemPackages = if config.services.httpd.enable then [ <replaceable>...</replaceable> ] else [];
  <replaceable>...</replaceable>
};
</programlisting>

</para>

</simplesect>

<simplesect><title>Setting priorities</title>

<para>A module can override the definitions of an option in other
modules by setting a <emphasis>priority</emphasis>.  All option
definitions that do not have the lowest priority value are discarded.
By default, option definitions have priority 1000.  You can specify an
explicit priority by using <varname>mkOverride</varname>, e.g.

<programlisting>
services.openssh.enable = mkOverride 10 false;
</programlisting>

This definition causes all other definitions with priorities above 10
to be discarded.  The function <varname>mkForce</varname> is
equal to <varname>mkOverride 50</varname>.</para>

</simplesect>

<simplesect><title>Merging configurations</title>

<para>In conjunction with <literal>mkIf</literal>, it is sometimes
useful for a module to return multiple sets of option definitions, to
be merged together as if they were declared in separate modules.  This
can be done using <varname>mkMerge</varname>:

<programlisting>
config = mkMerge
  [ # Unconditional stuff.
    { environment.systemPackages = [ <replaceable>...</replaceable> ];
    }
    # Conditional stuff.
    (mkIf config.services.bla.enable {
      environment.systemPackages = [ <replaceable>...</replaceable> ];
    })
  ];
</programlisting>

</para>

</simplesect>

</section>


<section><title>Important options</title>

<para>NixOS has many options, but some are of particular importance to
module writers.</para>

<variablelist>

  <varlistentry>
    <term><option>environment.etc</option></term>
    <listitem>
      <para>This set defines files in <filename>/etc</filename>.  A
      typical use is:
<programlisting>
environment.etc."os-release".text =
  ''
    NAME=NixOS
    <replaceable>...</replaceable>
  '';
</programlisting>
      which causes a file named <filename>/etc/os-release</filename>
      to be created with the given contents.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>system.activationScripts</option></term>
    <listitem>
      <para>A set of shell script fragments that must be executed
      whenever the configuration is activated (i.e., at boot time, or
      after running <command>nixos-rebuild switch</command>).  For instance,
<programlisting>
system.activationScripts.media =
  ''
    mkdir -m 0755 -p /media
  '';
</programlisting>
      causes the directory <filename>/media</filename> to be created.
      Activation scripts must be idempotent.  They should not start
      background processes such as daemons; use
      <option>systemd.services</option> for that.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>systemd.services</option></term>
    <listitem>
      <para>This is the set of systemd services.  Example:
<programlisting>
systemd.services.dhcpcd =
  { description = "DHCP Client";
    wantedBy = [ "multi-user.target" ];
    after = [ "systemd-udev-settle.service" ];
    path = [ dhcpcd pkgs.nettools pkgs.openresolv ];
    serviceConfig =
      { Type = "forking";
        PIDFile = "/run/dhcpcd.pid";
        ExecStart = "${dhcpcd}/sbin/dhcpcd --config ${dhcpcdConf}";
        Restart = "always";
      };
  };
</programlisting>
      which creates the systemd unit
      <literal>dhcpcd.service</literal>.  The option
      <option>wantedBy</option> determined which other units pull this
      one in; <literal>multi-user.target</literal> is the default
      target of the system, so <literal>dhcpcd.service</literal> will
      always be started.  The option
      <option>serviceConfig.ExecStart</option> provides the main
      command for the service; it’s also possible to provide pre-start
      actions, stop scripts, and so on.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>users.extraUsers</option></term>
    <term><option>users.extraGroups</option></term>
    <listitem>
      <para>If your service requires special UIDs or GIDs, you can
      define them with these options.  See <xref
      linkend="sec-user-management"/> for details.</para>
    </listitem>
  </varlistentry>

</variablelist>

</section>


</section>


<!--===============================================================-->

<section 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>
$ cd <replaceable>/path/to/nixpkgs/nixos</replaceable>
$ 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>
$ nix-build -A system</screen>
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>system.build.manual.manual</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>
$ 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
</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>
$ 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>
$ 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
</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>

</section>


<!--===============================================================-->

<section xml:id="sec-building-cd">

<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 installed 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>
$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix</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>
$ nix-build -A config.system.build.nixos-install
$ mount -t tmpfs none /mnt
$ ./result/bin/nixos-install</screen>

To start a login shell in the new NixOS installation in
<filename>/mnt</filename>:

<screen>
$ ./result/bin/nixos-install --chroot
</screen>

</para>

</section>



<!--===============================================================-->

<section xml:id="sec-nixos-tests">

<title>NixOS tests</title>

<para>When you add some feature to NixOS, you should write a test for
it. NixOS tests are kept in the directory <filename
xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixos/tests</filename>,
and are executed (using Nix) by a testing framework that automatically
starts one or more virtual machines containing the NixOS system(s)
required for the test.</para>

<simplesect><title>Writing tests</title>

<para>A NixOS test is a Nix expression that has the following structure:

<programlisting>
import ./make-test.nix {

  # Either the configuration of a single machine:
  machine =
    { config, pkgs, ... }:
    { <replaceable>configuration…</replaceable>
    };

  # Or a set of machines:
  nodes =
    { <replaceable>machine1</replaceable> =
        { config, pkgs, ... }: { <replaceable>…</replaceable> };
      <replaceable>machine2</replaceable> =
        { config, pkgs, ... }: { <replaceable>…</replaceable> };
      …
    };

  testScript =
    ''
      <replaceable>Perl code…</replaceable>
    '';
}
</programlisting>

The attribute <literal>testScript</literal> is a bit of Perl code that
executes the test (described below). During the test, it will start
one or more virtual machines, the configuration of which is described
by the attribute <literal>machine</literal> (if you need only one
machine in your test) or by the attribute <literal>nodes</literal> (if
you need multiple machines). For instance, <filename
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename>
only needs a single machine to test whether users can log in on the
virtual console, whether device ownership is correctly maintained when
switching between consoles, and so on. On the other hand, <filename
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs.nix">nfs.nix</filename>,
which tests NFS client and server functionality in the Linux kernel
(including whether locks are maintained across server crashes),
requires three machines: a server and two clients.</para>

<para>There are a few special NixOS configuration options for test
VMs:

<!-- FIXME: would be nice to generate this automatically. -->

<variablelist>

  <varlistentry>
    <term><option>virtualisation.memorySize</option></term>
    <listitem><para>The memory of the VM in
    megabytes.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><option>virtualisation.vlans</option></term>
    <listitem><para>The virtual networks to which the VM is
    connected. See <filename
    xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nat.nix">nat.nix</filename>
    for an example.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><option>virtualisation.writableStore</option></term>
    <listitem><para>By default, the Nix store in the VM is not
    writable. If you enable this option, a writable union file system
    is mounted on top of the Nix store to make it appear
    writable. This is necessary for tests that run Nix operations that
    modify the store.</para></listitem>
  </varlistentry>

</variablelist>

For more options, see the module <filename
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/qemu-vm.nix">qemu-vm.nix</filename>.</para>

<para>The test script is a sequence of Perl statements that perform
various actions, such as starting VMs, executing commands in the VMs,
and so on. Each virtual machine is represented as an object stored in
the variable <literal>$<replaceable>name</replaceable></literal>,
where <replaceable>name</replaceable> is the identifier of the machine
(which is just <literal>machine</literal> if you didn’t specify
multiple machines using the <literal>nodes</literal> attribute). For
instance, the following starts the machine, waits until it has
finished booting, then executes a command and checks that the output
is more-or-less correct:

<programlisting>
$machine->start;
$machine->waitForUnit("default.target");
$machine->succeed("uname") =~ /Linux/;
</programlisting>

The first line is actually unnecessary; machines are implicitly
started when you first execute an action on them (such as
<literal>waitForUnit</literal> or <literal>succeed</literal>). If you
have multiple machines, you can speed up the test by starting them in
parallel:

<programlisting>
startAll;
</programlisting>

</para>

<para>The following methods are available on machine objects:

<variablelist>

  <varlistentry>
    <term><methodname>start</methodname></term>
    <listitem><para>Start the virtual machine. This method is
    asynchronous — it does not wait for the machine to finish
    booting.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>shutdown</methodname></term>
    <listitem><para>Shut down the machine, waiting for the VM to
    exit.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>crash</methodname></term>
    <listitem><para>Simulate a sudden power failure, by telling the VM
    to exit immediately.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>block</methodname></term>
    <listitem><para>Simulate unplugging the Ethernet cable that
    connects the machine to the other machines.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>unblock</methodname></term>
    <listitem><para>Undo the effect of
    <methodname>block</methodname>.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>screenshot</methodname></term>
    <listitem><para>Take a picture of the display of the virtual
    machine, in PNG format. The screenshot is linked from the HTML
    log.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>sendMonitorCommand</methodname></term>
    <listitem><para>Send a command to the QEMU monitor. This is rarely
    used, but allows doing stuff such as attaching virtual USB disks
    to a running machine.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>sendKeys</methodname></term>
    <listitem><para>Simulate pressing keys on the virtual keyboard,
    e.g., <literal>sendKeys("ctrl-alt-delete")</literal>.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>sendChars</methodname></term>
    <listitem><para>Simulate typing a sequence of characters on the
    virtual keyboard, e.g., <literal>sendKeys("foobar\n")</literal>
    will type the string <literal>foobar</literal> followed by the
    Enter key.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>execute</methodname></term>
    <listitem><para>Execute a shell command, returning a list
    <literal>(<replaceable>status</replaceable>,
    <replaceable>stdout</replaceable>)</literal>.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>succeed</methodname></term>
    <listitem><para>Execute a shell command, raising an exception if
    the exit status is not zero, otherwise returning the standard
    output.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>fail</methodname></term>
    <listitem><para>Like <methodname>succeed</methodname>, but raising
    an exception if the command returns a zero status.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>waitUntilSucceeds</methodname></term>
    <listitem><para>Repeat a shell command with 1-second intervals
    until it succeeds.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>waitUntilFails</methodname></term>
    <listitem><para>Repeat a shell command with 1-second intervals
    until it fails.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>waitForUnit</methodname></term>
    <listitem><para>Wait until the specified systemd unit has reached
    the “active” state.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>waitForFile</methodname></term>
    <listitem><para>Wait until the specified file
    exists.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>waitForOpenPort</methodname></term>
    <listitem><para>Wait until a process is listening on the given TCP
    port (on <literal>localhost</literal>, at least).</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>waitForClosedPort</methodname></term>
    <listitem><para>Wait until nobody is listening on the given TCP
    port.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>waitForX</methodname></term>
    <listitem><para>Wait until the X11 server is accepting
    connections.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><methodname>waitForWindow</methodname></term>
    <listitem><para>Wait until an X11 window has appeared whose name
    matches the given regular expression, e.g.,
    <literal>waitForWindow(qr/Terminal/)</literal>.</para></listitem>
  </varlistentry>

</variablelist>

</para>

</simplesect>


<simplesect><title>Running tests</title>

<para>You can run tests using <command>nix-build</command>. For
example, to run the test <filename
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename>,
you just do:

<screen>
$ nix-build '&lt;nixpkgs/nixos/tests/login.nix>'
</screen>

or, if you don’t want to rely on <envar>NIX_PATH</envar>:

<screen>
$ cd /my/nixpkgs/nixos/tests
$ nix-build login.nix
…
running the VM test script
machine: QEMU running (pid 8841)
…
6 out of 6 tests succeeded
</screen>

After building/downloading all required dependencies, this will
perform a build that starts a QEMU/KVM virtual machine containing a
NixOS system. The virtual machine mounts the Nix store of the host;
this makes VM creation very fast, as no disk image needs to be
created. Afterwards, you can view a pretty-printed log of the test:

<screen>
$ firefox result/log.html
</screen>

</para>

<para>It is also possible to run the test environment interactively,
allowing you to experiment with the VMs.  For example:

<screen>
$ nix-build login.nix -A driver
$ ./result/bin/nixos-run-vms
</screen>

The script <command>nixos-run-vms</command> starts the virtual
machines defined by test.  The root file system of the VMs is created
on the fly and kept across VM restarts in
<filename>./</filename><varname>hostname</varname><filename>.qcow2</filename>.</para>

<para>Finally, the test itself can be run interactively.  This is
particularly useful when developing or debugging a test:

<screen>
$ nix-build tests/ -A nfs.driver
$ ./result/bin/nixos-test-driver
starting VDE switch for network 1
&gt;
</screen>

You can then take any Perl statement, e.g.

<screen>
&gt; startAll
&gt; $machine->succeed("touch /tmp/foo")
</screen>

The function <command>testScript</command> executes the entire test
script and drops you back into the test driver command line upon its
completion.  This allows you to inspect the state of the VMs after the
test (e.g. to debug the test script).</para>

</simplesect>

</section>


</chapter>