NixOS modules: Difference between revisions
imported>Malteneuss m Improve structure and reuse formulations |
m changed link from redirect to article |
||
| (9 intermediate revisions by 7 users not shown) | |||
| Line 10: | Line 10: | ||
{ | { | ||
imports = [ | imports = [ | ||
# | # Paths to other modules. | ||
# Compose this module out of smaller ones. | |||
]; | ]; | ||
options = { | options = { | ||
# option | # 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 | # 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. | ||
./module.nix | ./module.nix | ||
/path/to/absolute/module.nix | /path/to/absolute/module.nix | ||
]; | ]; | ||
# | # Config definitions. | ||
services.othermodule.enable = true; | |||
# ... | |||
# Notice that you can leave out the "config { }" wrapper. | |||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 48: | Line 58: | ||
{ config, pkgs, ... }: | { config, pkgs, ... }: | ||
{ | { | ||
imports = []; | |||
# ... | # ... | ||
} | } | ||
| Line 61: | 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 69: | 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 116: | Line 178: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
They are created with {{ic|mkOption}}, a function accepting a set with following attributes:<ref>{{Nixpkgs Link|lib/options.nix# | 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 334: | 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> [[ | 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 == | ||