NixOS modules: Difference between revisions

← Older editNewer edit →
VisualWikitext
imported>Toraritte
Move "NixOS Module Enhancements" section from Alternative Package Sets article to here
Klinger (talk | contribs)
trusted
717 edits
m changed link from redirect to article
(14 intermediate revisions by 10 users not shown)
Line 1: Line 1:
'''Modules''' are files combined by NixOS to produce the full system configuration. A module contains a Nix expression. It ''declares'' options for other modules to ''define'' (give a value). It processes them and defines options declared in other modules.<ref>{{manual:nixos|sec=#sec-writing-modules|chapter=Chapter 42. Writing NixOS Modules}}</ref>
NixOS produces a full system configuration by combining smaller, more isolated and reusable components: '''Modules'''. A module is a file containing a Nix expression with a specific structure. It ''declares'' options for other modules to ''define'' (give a value). It processes them and defines options declared in other modules.<ref>{{manual:nixos|sec=#sec-writing-modules|chapter=Chapter 42. Writing NixOS Modules}}</ref>


For example, {{ic|/etc/nixos/configuration.nix}} is a module. Most other modules are in {{Nixpkgs Link|nixos/modules}}.
For example, {{ic|/etc/nixos/configuration.nix}} is a module. Most other modules are in {{Nixpkgs Link|nixos/modules}}.
Line 10: Line 10:
{
{
   imports = [
   imports = [
     # paths to other modules
     # Paths to other modules.
    # Compose this module out of smaller ones.
   ];
   ];


   options = {
   options = {
     # option declarations
     # Option declarations.
    # Declare what settings a user of this module module can set.
    # Usually this includes a global "enable" option which defaults to false.
   };
   };


   config = {
   config = {
     # option definitions
     # Option definitions.
    # Define what other settings, services and resources should be active.
    # Usually these depend on whether a user of this module chose to "enable" it
    # using the "option" above.
    # Options for modules imported in "imports" can be set here.
   };
   };
}
}
Line 28: Line 35:
{
{
   imports = [
   imports = [
     # paths to other modules
     # Paths to other modules.
     ./module.nix
     ./module.nix
     /path/to/absolute/module.nix
     /path/to/absolute/module.nix
   ];
   ];


   # option definitions
   # Config definitions.
  services.othermodule.enable = true;
  # ...
  # Notice that you can leave out the "config { }" wrapper.
}
}
</syntaxhighlight>
</syntaxhighlight>


Note: <code>imports</code> provides the same behavior as the obsolete <code>require</code>. There is no reason to use <code>require</code> anymore, however it may still linger in some legacy code. .  
Beginners often confuse the modules attribute <code>imports = [./module.nix]</code> here with the Nix [https://nixos.org/manual/nix/stable/language/builtins.html#builtins-import builtins] function <code>import module.nix</code>. The first expects a path to a file containing a NixOS module (having the same specific structure we're describing here), while the second loads whatever Nix expression is in that file (no expected structure). See [https://discourse.nixos.org/t/import-list-in-configuration-nix-vs-import-function/11372/8 this post].
 
Note: <code>imports</code> provides the same behavior as the obsolete <code>require</code>. There is no reason to use <code>require</code> anymore, however it may still linger in some legacy code.


=== Function ===
=== Function ===
Line 46: Line 58:
{ config, pkgs, ... }:
{ config, pkgs, ... }:
{
{
  imports = [];
   # ...
   # ...
}
}
Line 59: Line 72:
<dt><code>options</code></dt>
<dt><code>options</code></dt>
<dd>All option declarations refined with all definition and declaration references.</dd>
<dd>All option declarations refined with all definition and declaration references.</dd>
<dt><code>lib</code></dt>
<dd>An instance of the nixpkgs "standard library", providing what usually is in <code>pkgs.lib</code>.</dd>


<dt><code>pkgs</code></dt>
<dt><code>pkgs</code></dt>
Line 67: Line 83:


</dl>
</dl>
==== Passing custom values to modules ====
The [[NixOS:config_argument|<code>config</code>]], <code>options</code>, <code>lib</code>, <code>pkgs</code>, and <code>modulesPath</code> arguments are passed automatically to modules, when the module is imported.
For example, in the following Nix flake, the `./configuration.nix` file will be provided with the default set of arguments listed above, plus `extraArg`, which was set in the `specialArgs` argument to the `nixosGenerate` function.<syntaxhighlight lang="nix">
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
    nixos-generators = {
      url = "github:nix-community/nixos-generators";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    xc = {
      url = "github:joerdav/xc";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
  outputs = { nixpkgs, nixos-generators, xc, ... }:
    let
      pkgsForSystem = system: import nixpkgs {
        inherit system;
        overlays = [
          (final: prev: { xc = xc.packages.${system}.xc; })
        ];
      };
      allVMs = [ "x86_64-linux" "aarch64-linux" ];
      forAllVMs = f: nixpkgs.lib.genAttrs allVMs (system: f {
        inherit system;
        pkgs = pkgsForSystem system;
      });
    in
    {
      packages = forAllVMs ({ system, pkgs }: {
        vm = nixos-generators.nixosGenerate {
          system = system;
          specialArgs = {
            extraArg = "foobar";
          };
          modules = [
            ./configuration.nix
          ];
          format = "raw";
        };
      });
    };
}
</syntaxhighlight>


==== modulesPath ====
==== modulesPath ====
Line 114: Line 178:
</syntaxhighlight>
</syntaxhighlight>


They are created with {{ic|mkOption}}, a function accepting a set with following attributes:<ref>{{Nixpkgs Link|lib/options.nix#L51-L84}}</ref><ref>{{manual:nixos|sec=#sec-option-declarations|chapter=42.1. Option Declarations}}</ref>
They are created with {{ic|mkOption}}, a function accepting a set with following attributes:<ref>{{Nixpkgs Link|lib/options.nix#L66-L88}}</ref><ref>{{manual:nixos|sec=#sec-option-declarations|chapter=42.1. Option Declarations}}</ref>


<dl>
<dl>
Line 147: Line 211:
== Example ==
== Example ==


put into <code>hello.nix</code> in the same folder as your <code>configuration.nix</code>.
To see how modules are setup and reuse other modules in practice put <code>hello.nix</code> in the same folder as your <code>configuration.nix</code>:
 
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
{ lib, pkgs, config, ... }:
{ lib, pkgs, config, ... }:
with lib;                       
with lib;                       
let
let
  # Shorter name to access final settings a
  # user of hello.nix module HAS ACTUALLY SET.
  # cfg is a typical convention.
   cfg = config.services.hello;
   cfg = config.services.hello;
in {
in {
  # Declare what settings a user of this "hello.nix" module CAN SET.
   options.services.hello = {
   options.services.hello = {
     enable = mkEnableOption "hello service";
     enable = mkEnableOption "hello service";
Line 162: Line 231:
   };
   };


  # Define what other settings, services and resources should be active IF
  # a user of this "hello.nix" module ENABLED this module
  # by setting "services.hello.enable = true;".
   config = mkIf cfg.enable {
   config = mkIf cfg.enable {
     systemd.services.hello = {
     systemd.services.hello = {
Line 171: Line 243:
</syntaxhighlight>
</syntaxhighlight>


Add the following to your <code>configuration.nix</code>
The other <code>configuration.nix</code> module can then import this <code>hello.nix</code> module
and decide to enable it (and optionally set other allowed settings) as follows:
<syntaxhighlight lang=nix>
<syntaxhighlight lang=nix>
{
{
Line 231: Line 305:
=== Using external NixOS modules ===
=== Using external NixOS modules ===


Some external modules provide extra functionality to the nixpkgs module system. You can include these modules after extracting them onto the system by using <code>imports = [ `path to module`]</code> or add them to your <code>NIX_PATH</code> via <code>NIX_PATH=$NIX_PATH:musnix=/path/to/musnix</code> and import them by including <code>imports = [ <musnix> ]</code> in your <code>configuration.nix</code>.
Some external modules provide extra functionality to the NixOS module system. You can include these modules, after making them available as a file system path (e.g. through <code>builtins.fetchTarball</code>), by using <code>imports = [ `path to module`]</code> in your <code>configuration.nix</code>.


* [https://github.com/ip1981/nixsap Nixsap] - allows to run multiple instances of a service without containers.
* [https://github.com/ip1981/nixsap Nixsap] - allows to run multiple instances of a service without containers.
Line 322: Line 396:
</syntaxhighlight>
</syntaxhighlight>


If you're developing on top of master, this will potentially cause the compilation of lots of packages, since changes on master might not cached on cache.nixos.org yet. To avoid that, you can develop your module on top of the <code>nixos-unstable</code> [[Channels|channel]], tracked by the eponymous branch in https://github.com/NixOS/nixpkgs:
If you're developing on top of master, this will potentially cause the compilation of lots of packages, since changes on master might not cached on cache.nixos.org yet. To avoid that, you can develop your module on top of the <code>nixos-unstable</code> [[Channel branches|channel branch]], tracked by the eponymous branch in https://github.com/NixOS/nixpkgs:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
git checkout -b mymodule upstream/nixos-unstable
git checkout -b mymodule upstream/nixos-unstable
</syntaxhighlight>
</syntaxhighlight>
=== With Flakes ===
If you're developing a module from nixpkgs, you can try and follow the directions here: https://github.com/Misterio77/nix-starter-configs/issues/28.
If you want to develop a module from a git repo, you can use `--override-input`. For example, if you have an input in your flake called {{ic|jovian}},, you can use
<syntaxhighlight lang="bash">
nixos-rebuild switch --override-input jovian <path-to-url>` --flake <uri>
</syntaxhighlight>
Of course, it doesn't have to be {{|c|nixos-rebuild}} in particular.


== References ==
== References ==
Retrieved from "https://wiki.nixos.org/wiki/NixOS_modules"