nixpkgs/nixos/modules/misc/nixos.xml

<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="module-misc-nixos">

<title>NixOS Reentry</title>

<!-- FIXME: render nicely -->

<!-- FIXME: source can be added automatically -->
<para><emphasis>Source:</emphasis> <filename>modules/misc/nixos.nix</filename></para>

<!-- FIXME: more stuff, like maintainer? -->

<para>NixOS reentry can be used for both pinning the evaluation to a
specific version of NixOS, and to dynamically add additional modules into
the Module evaluation.</para>

<section><title>NixOS Version Pinning</title>

<para>To pin a specific version of NixOS, you need a version that you can
either clone localy, or that you can fetch remotely.</para>

<para>If you already have a cloned version of NixOS in the directory
<filename>/etc/nixos/nixpkgs-16-03</filename>, then you can specify the
<option>nixos.path</option> with either the path or the relative path of
your NixOS clone. For example, you can add the following to your
<filename>/etc/nixos/configuration.nix</filename> file:

<programlisting>
nixos.path = ./nixpkgs-16-03/nixos;
</programlisting>
</para>

<para>Another option is to fetch a specific version of NixOS, with either
the <literal>fetchTarball</literal> builtin, or the
<literal>pkgs.fetchFromGitHub</literal> function and use the result as an
input.

<programlisting>
nixos.path = "${builtins.fetchTarball https://github.com/NixOS/nixpkgs/archive/1f27976e03c15183191d1b4aa1a40d1f14666cd2.tar.gz}/nixos";
</programlisting>
</para>

</section>


<section><title>Adding Module Dynamically</title>

<para>To add additional module, the recommended way is to use statically
known modules in the list of imported arguments as described in <xref
linkend="sec-modularity" />.  Unfortunately, this recommended method has
limitation, such that the list of imported files cannot be selected based on
the content of the configuration.

Fortunately, NixOS reentry system can be used as an alternative to register
new imported modules based on the content of the configuration. To do so,
one should define both <option>nixos.path</option> and
<option>nixos.extraModules</option> options.

<programlisting>
nixos.path = &lt;nixos&gt;;
nixos.extraModules =
  if config.networking.hostName == "server" then
    [ ./server.nix ] else [ ./client.nix ];
</programlisting>

Also note, that the above can be reimplemented in a different way which is
not as expensive, by using <literal>mkIf</literal> at the top each
configuration if both modules are present on the file system (see <xref
linkend="sec-option-definitions" />) and by always inmporting both
modules.</para>

</section>

<section><title>Options</title>

<para>FIXME: auto-generated list of module options.</para>

</section>


</chapter>