NixOS modules: Difference between revisions

(One intermediate revision by one other user not shown)

Line 276:

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">{ lib, pkgs, config, ... }:

{ lib, pkgs, config, ... }:

with lib;

let

Line 285:

Line 284:

cfg = config.services.hello;

in {

meta.doc = "Says hello every time you login.";

# Declare what settings a user of this "hello.nix" module CAN SET.

options.services.hello = {

Line 303:

Line 304:

};

}

}</syntaxhighlight>

</syntaxhighlight>

The other <code>configuration.nix</code> module can then import this <code>hello.nix</code> module

Line 374:

* [https://gitlab.com/simple-nixos-mailserver/nixos-mailserver nixos-mailserver] - full-featured mail server module

* [https://github.com/xtruder/nix-profiles X-Truder Nix-profiles] - modules for Nix to quickly configure your system based on application profiles.

=== Disabling modules ===

In some cases, you may wish to override or disable modules previously imported, for example by NixOS. This can be achieved using the top-level attribute <code>disabledModules</code><ref>[https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/manual/development/replace-modules.section.md "Replace Modules" section, NixOS manual]</ref>. It prevents that module, as well as any module it imports itself, from being imported into the current config scope. This means that neither the options it declares nor the configuration it might set are actually imported. This can be particularly useful to override or debug the implementation of a certain module, for example to use a module from an unstable NixOS channel while using the stable version of every other module in the system.

To disable a given module, you must refer to it based on either:

* the full, absolute path of the module: <code>/mnt/dev/foo/my-modules/services/thingy.nix</code><syntaxhighlight lang="nix">

{ ... }: {

imports = [ <jade-nur/modules> ];

disabledModules = [

# make sure that the GL module is never imported

"/home/xia/custom-modules/gl.nix"

# prevent the tilix module from 'jade-nur' being imported

# note that this doesn't disable the rest of 'jade-nur/modules'

<jade-nur/modules/programs/tilix.nix>

];

}

</syntaxhighlight>

* the path relative to the value of <code>modulesPath</code>: <code>"programs/hello.nix"</code><syntaxhighlight lang="nix">

{ ... }: {

disabledModules = [

# prevent NixOS's immich module from being imported

"services/web-apps/immich.nix"

];

imports = [

# ...and then import a replacement of it from somewhere else

];

}

</syntaxhighlight>

* an attribute set containing a <code>key</code> attribute, which should be a unique identity declared by the module you're trying to disable: <code>{ key = "my-super-unique-module"; }</code>. This is most useful for modules you have control over, as modules from NixOS and home-manager do not generally have specific keys.<syntaxhighlight lang="nix">

# in file foo.nix

{ ... }: {

disabledModules = [

# disable the module with the exact

# key "staple-battery-horse", as well

# as any module it imports itself

{ key = "staple-battery-horse"; }

];

...

}

# in file horse.nix, which could be imported

# from somewhere else in the config

{ ... }: {

# this key should be globally unique, it is

# the unique ID by which this module is tracked

# by the module system, and thus how it can

# be precisely disabled

key = "stable-battery-horse";

imports = [ ./impl.nix ];

options = { ... };

}

</syntaxhighlight>

Note that keys and paths (whether absolute or relative) must be exact. For example, <code>disabledModules = [ "services/web-apps" ]</code> won't have any effect, because the files inside that folder are imported individually; however, <code>disabledModules = [ "services/web-apps/akkoma.nix" "services/web-apps/immich.nix" ... ];</code> will disable every module specified.

More examples are available in the [https://nixos.org/manual/nixos/unstable/#sec-replace-modules "Replace modules" section of the NixOS manual] .

== Under the hood ==

@@ Line 276: / Line 276: @@
 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;
 let
@@ Line 285: / Line 284: @@
    cfg = config.services.hello;
 in {
+  meta.doc = "Says hello every time you login.";
    # Declare what settings a user of this "hello.nix" module CAN SET.
    options.services.hello = {
@@ Line 303: / Line 304: @@
      };
    };
-}
+}</syntaxhighlight>
-</syntaxhighlight>
 The other <code>configuration.nix</code> module can then import this <code>hello.nix</code> module
@@ Line 374: / Line 374: @@
 * [https://gitlab.com/simple-nixos-mailserver/nixos-mailserver nixos-mailserver] - full-featured mail server module
 * [https://github.com/xtruder/nix-profiles X-Truder Nix-profiles] - modules for Nix to quickly configure your system based on application profiles.
+=== Disabling modules ===
+In some cases, you may wish to override or disable modules previously imported, for example by NixOS. This can be achieved using the top-level attribute <code>disabledModules</code><ref>[https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/manual/development/replace-modules.section.md "Replace Modules" section, NixOS manual]</ref>. It prevents that module, as well as any module it imports itself, from being imported into the current config scope. This means that neither the options it declares nor the configuration it might set are actually imported. This can be particularly useful to override or debug the implementation of a certain module, for example to use a module from an unstable NixOS channel while using the stable version of every other module in the system.
+To disable a given module, you must refer to it based on either:
+* the full, absolute path of the module: <code>/mnt/dev/foo/my-modules/services/thingy.nix</code><syntaxhighlight lang="nix">
+{ ... }: {
+  imports = [ <jade-nur/modules> ];
+  disabledModules = [
+    # make sure that the GL module is never imported
+    "/home/xia/custom-modules/gl.nix"
+    # prevent the tilix module from 'jade-nur' being imported
+    # note that this doesn't disable the rest of 'jade-nur/modules'
+    <jade-nur/modules/programs/tilix.nix>
+  ];
+}
+</syntaxhighlight>
+* the path relative to the value of <code>modulesPath</code>: <code>"programs/hello.nix"</code><syntaxhighlight lang="nix">
+{ ... }: {
+  disabledModules = [
+    # prevent NixOS's immich module from being imported
+    "services/web-apps/immich.nix"
+  ];
+  imports = [
+    # ...and then import a replacement of it from somewhere else
+    <hotnix/services/immich>
+  ];
+}
+</syntaxhighlight>
+* an attribute set containing a <code>key</code> attribute, which should be a unique identity declared by the module you're trying to disable: <code>{ key = "my-super-unique-module"; }</code>. This is most useful for modules you have control over, as modules from NixOS and home-manager do not generally have specific keys.<syntaxhighlight lang="nix">
+# in file foo.nix
+{ ... }: {
+  disabledModules = [
+    # disable the module with the exact
+    # key "staple-battery-horse", as well
+    # as any module it imports itself
+    { key = "staple-battery-horse"; }
+  ];
+  ...
+}
+# in file horse.nix, which could be imported
+# from somewhere else in the config
+{ ... }: {
+  # this key should be globally unique, it is
+  # the unique ID by which this module is tracked
+  # by the module system, and thus how it can
+  # be precisely disabled
+  key = "stable-battery-horse";
+  imports = [ ./impl.nix ];
+  options = { ... };
+}
+</syntaxhighlight>
+Note that keys and paths (whether absolute or relative) must be exact. For example, <code>disabledModules = [ "services/web-apps" ]</code> won't have any effect, because the files inside that folder are imported individually; however, <code>disabledModules = [ "services/web-apps/akkoma.nix" "services/web-apps/immich.nix" ... ];</code> will disable every module specified.
+More examples are available in the [https://nixos.org/manual/nixos/unstable/#sec-replace-modules "Replace modules" section of the NixOS manual] .
 == Under the hood  ==