diff options
Diffstat (limited to 'nixos/doc/manual/development')
12 files changed, 205 insertions, 149 deletions
diff --git a/nixos/doc/manual/development/activation-script.section.md b/nixos/doc/manual/development/activation-script.section.md index cc317a6a01aa8..f771c3524b796 100644 --- a/nixos/doc/manual/development/activation-script.section.md +++ b/nixos/doc/manual/development/activation-script.section.md @@ -17,13 +17,15 @@ activation script will take these dependencies into account and order the snippets accordingly. As a simple example: ```nix -system.activationScripts.my-activation-script = { - deps = [ "etc" ]; - # supportsDryActivation = true; - text = '' - echo "Hallo i bims" - ''; -}; +{ + system.activationScripts.my-activation-script = { + deps = [ "etc" ]; + # supportsDryActivation = true; + text = '' + echo "Hallo i bims" + ''; + }; +} ``` This example creates an activation script snippet that is run after the `etc` diff --git a/nixos/doc/manual/development/assertions.section.md b/nixos/doc/manual/development/assertions.section.md index cc6d81e56990b..eb5158c90f98c 100644 --- a/nixos/doc/manual/development/assertions.section.md +++ b/nixos/doc/manual/development/assertions.section.md @@ -18,7 +18,7 @@ This is an example of using `warnings`. This is known to cause some specific problems in certain situations. '' ] else []; - } + }; } ``` @@ -35,6 +35,6 @@ This example, extracted from the [`syslogd` module](https://github.com/NixOS/nix message = "rsyslogd conflicts with syslogd"; } ]; - } + }; } ``` diff --git a/nixos/doc/manual/development/etc-overlay.section.md b/nixos/doc/manual/development/etc-overlay.section.md index e6f6d8d4ca1ef..d8588f508a26c 100644 --- a/nixos/doc/manual/development/etc-overlay.section.md +++ b/nixos/doc/manual/development/etc-overlay.section.md @@ -9,7 +9,9 @@ Instead of using a custom perl script to activate `/etc`, you activate it via an overlay filesystem: ```nix -system.etc.overlay.enable = true; +{ + system.etc.overlay.enable = true; +} ``` Using an overlay has two benefits: @@ -22,7 +24,9 @@ upper layer). However, you can also mount `/etc` immutably (i.e. read-only) by setting: ```nix -system.etc.overlay.mutable = false; +{ + system.etc.overlay.mutable = false; +} ``` The overlay is atomically replaced during system switch. However, files that diff --git a/nixos/doc/manual/development/meta-attributes.section.md b/nixos/doc/manual/development/meta-attributes.section.md index 33b41fe74d297..b2ad23e58b94b 100644 --- a/nixos/doc/manual/development/meta-attributes.section.md +++ b/nixos/doc/manual/development/meta-attributes.section.md @@ -14,11 +14,11 @@ file. { config, lib, pkgs, ... }: { options = { - ... + # ... }; config = { - ... + # ... }; meta = { diff --git a/nixos/doc/manual/development/non-switchable-systems.section.md b/nixos/doc/manual/development/non-switchable-systems.section.md index 87bb46c789091..a51e8233f30b3 100644 --- a/nixos/doc/manual/development/non-switchable-systems.section.md +++ b/nixos/doc/manual/development/non-switchable-systems.section.md @@ -9,7 +9,7 @@ profile: ```nix { modulesPath, ... }: { - imports = [ "${modulesPath}/profiles/image-based-appliance.nix" ] + imports = [ "${modulesPath}/profiles/image-based-appliance.nix" ]; } ``` diff --git a/nixos/doc/manual/development/option-declarations.section.md b/nixos/doc/manual/development/option-declarations.section.md index 762070416187d..ad5857b11a2e0 100644 --- a/nixos/doc/manual/development/option-declarations.section.md +++ b/nixos/doc/manual/development/option-declarations.section.md @@ -6,14 +6,16 @@ hasn't been declared in any module. An option declaration generally looks like this: ```nix -options = { - name = mkOption { - type = type specification; - default = default value; - example = example value; - description = lib.mdDoc "Description for use in the NixOS manual."; +{ + options = { + name = mkOption { + type = type specification; + default = default value; + example = example value; + description = lib.mdDoc "Description for use in the NixOS manual."; + }; }; -}; +} ``` The attribute names within the `name` attribute path must be camel @@ -221,28 +223,34 @@ enforces that there can only be a single display manager enabled. ::: {#ex-option-declaration-eot-service .example} ### Extensible type placeholder in the service module ```nix -services.xserver.displayManager.enable = mkOption { - description = "Display manager to use"; - type = with types; nullOr (enum [ ]); -}; +{ + services.xserver.displayManager.enable = mkOption { + description = "Display manager to use"; + type = with types; nullOr (enum [ ]); + }; +} ``` ::: ::: {#ex-option-declaration-eot-backend-gdm .example} ### Extending `services.xserver.displayManager.enable` in the `gdm` module ```nix -services.xserver.displayManager.enable = mkOption { - type = with types; nullOr (enum [ "gdm" ]); -}; +{ + services.xserver.displayManager.enable = mkOption { + type = with types; nullOr (enum [ "gdm" ]); + }; +} ``` ::: ::: {#ex-option-declaration-eot-backend-sddm .example} ### Extending `services.xserver.displayManager.enable` in the `sddm` module ```nix -services.xserver.displayManager.enable = mkOption { - type = with types; nullOr (enum [ "sddm" ]); -}; +{ + services.xserver.displayManager.enable = mkOption { + type = with types; nullOr (enum [ "sddm" ]); + }; +} ``` ::: diff --git a/nixos/doc/manual/development/option-def.section.md b/nixos/doc/manual/development/option-def.section.md index 6a3dc26b99be4..227f41d812ff1 100644 --- a/nixos/doc/manual/development/option-def.section.md +++ b/nixos/doc/manual/development/option-def.section.md @@ -4,9 +4,11 @@ Option definitions are generally straight-forward bindings of values to option names, like ```nix -config = { - services.httpd.enable = true; -}; +{ + config = { + services.httpd.enable = true; + }; +} ``` However, sometimes you need to wrap an option definition or set of @@ -18,10 +20,12 @@ If a set of option definitions is conditional on the value of another option, you may need to use `mkIf`. Consider, for instance: ```nix -config = if config.services.httpd.enable then { - environment.systemPackages = [ ... ]; - ... -} else {}; +{ + config = if config.services.httpd.enable then { + environment.systemPackages = [ /* ... */ ]; + # ... + } else {}; +} ``` This definition will cause Nix to fail with an "infinite recursion" @@ -30,30 +34,36 @@ on the value being constructed here. After all, you could also write the clearly circular and contradictory: ```nix -config = if config.services.httpd.enable then { - services.httpd.enable = false; -} else { - services.httpd.enable = true; -}; +{ + config = if config.services.httpd.enable then { + services.httpd.enable = false; + } else { + services.httpd.enable = true; + }; +} ``` The solution is to write: ```nix -config = mkIf config.services.httpd.enable { - environment.systemPackages = [ ... ]; - ... -}; +{ + config = mkIf config.services.httpd.enable { + environment.systemPackages = [ /* ... */ ]; + # ... + }; +} ``` The special function `mkIf` causes the evaluation of the conditional to be "pushed down" into the individual definitions, as if you had written: ```nix -config = { - environment.systemPackages = if config.services.httpd.enable then [ ... ] else []; - ... -}; +{ + config = { + environment.systemPackages = if config.services.httpd.enable then [ /* ... */ ] else []; + # ... + }; +} ``` ## Setting Priorities {#sec-option-definitions-setting-priorities} @@ -65,7 +75,9 @@ priority 100 and option defaults have priority 1500. You can specify an explicit priority by using `mkOverride`, e.g. ```nix -services.openssh.enable = mkOverride 10 false; +{ + services.openssh.enable = mkOverride 10 false; +} ``` This definition causes all other definitions with priorities above 10 to @@ -80,7 +92,9 @@ The functions `mkBefore` and `mkAfter` are equal to `mkOrder 500` and `mkOrder 1 As an example, ```nix -hardware.firmware = mkBefore [ myFirmware ]; +{ + hardware.firmware = mkBefore [ myFirmware ]; +} ``` This definition ensures that `myFirmware` comes before other unordered @@ -97,13 +111,15 @@ they were declared in separate modules. This can be done using `mkMerge`: ```nix -config = mkMerge - [ # Unconditional stuff. - { environment.systemPackages = [ ... ]; - } - # Conditional stuff. - (mkIf config.services.bla.enable { - environment.systemPackages = [ ... ]; - }) - ]; +{ + config = mkMerge + [ # Unconditional stuff. + { environment.systemPackages = [ /* ... */ ]; + } + # Conditional stuff. + (mkIf config.services.bla.enable { + environment.systemPackages = [ /* ... */ ]; + }) + ]; +} ``` diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md index 04edf99e70b00..243039b016737 100644 --- a/nixos/doc/manual/development/option-types.section.md +++ b/nixos/doc/manual/development/option-types.section.md @@ -374,19 +374,21 @@ if you want to allow users to leave it undefined. ::: {#ex-submodule-direct .example} ### Directly defined submodule ```nix -options.mod = mkOption { - description = "submodule example"; - type = with types; submodule { - options = { - foo = mkOption { - type = int; - }; - bar = mkOption { - type = str; +{ + options.mod = mkOption { + description = "submodule example"; + type = with types; submodule { + options = { + foo = mkOption { + type = int; + }; + bar = mkOption { + type = str; + }; }; }; }; -}; +} ``` ::: @@ -405,10 +407,12 @@ let }; }; in -options.mod = mkOption { - description = "submodule example"; - type = with types; submodule modOptions; -}; +{ + options.mod = mkOption { + description = "submodule example"; + type = with types; submodule modOptions; + }; +} ``` ::: @@ -421,29 +425,33 @@ multiple definitions of the submodule option set ::: {#ex-submodule-listof-declaration .example} ### Declaration of a list of submodules ```nix -options.mod = mkOption { - description = "submodule example"; - type = with types; listOf (submodule { - options = { - foo = mkOption { - type = int; - }; - bar = mkOption { - type = str; +{ + options.mod = mkOption { + description = "submodule example"; + type = with types; listOf (submodule { + options = { + foo = mkOption { + type = int; + }; + bar = mkOption { + type = str; + }; }; - }; - }); -}; + }); + }; +} ``` ::: ::: {#ex-submodule-listof-definition .example} ### Definition of a list of submodules ```nix -config.mod = [ - { foo = 1; bar = "one"; } - { foo = 2; bar = "two"; } -]; +{ + config.mod = [ + { foo = 1; bar = "one"; } + { foo = 2; bar = "two"; } + ]; +} ``` ::: @@ -455,27 +463,31 @@ multiple named definitions of the submodule option set ::: {#ex-submodule-attrsof-declaration .example} ### Declaration of attribute sets of submodules ```nix -options.mod = mkOption { - description = "submodule example"; - type = with types; attrsOf (submodule { - options = { - foo = mkOption { - type = int; - }; - bar = mkOption { - type = str; +{ + options.mod = mkOption { + description = "submodule example"; + type = with types; attrsOf (submodule { + options = { + foo = mkOption { + type = int; + }; + bar = mkOption { + type = str; + }; }; - }; - }); -}; + }); + }; +} ``` ::: ::: {#ex-submodule-attrsof-definition .example} ### Definition of attribute sets of submodules ```nix -config.mod.one = { foo = 1; bar = "one"; }; -config.mod.two = { foo = 2; bar = "two"; }; +{ + config.mod.one = { foo = 1; bar = "one"; }; + config.mod.two = { foo = 2; bar = "two"; }; +} ``` ::: @@ -495,10 +507,12 @@ Types are mainly characterized by their `check` and `merge` functions. ### Adding a type check ```nix - byte = mkOption { - description = "An integer between 0 and 255."; - type = types.addCheck types.int (x: x >= 0 && x <= 255); - }; + { + byte = mkOption { + description = "An integer between 0 and 255."; + type = types.addCheck types.int (x: x >= 0 && x <= 255); + }; + } ``` ::: @@ -506,12 +520,14 @@ Types are mainly characterized by their `check` and `merge` functions. ### Overriding a type check ```nix - nixThings = mkOption { - description = "words that start with 'nix'"; - type = types.str // { - check = (x: lib.hasPrefix "nix" x) + { + nixThings = mkOption { + description = "words that start with 'nix'"; + type = types.str // { + check = (x: lib.hasPrefix "nix" x); + }; }; - }; + } ``` ::: diff --git a/nixos/doc/manual/development/settings-options.section.md b/nixos/doc/manual/development/settings-options.section.md index 71ec9bbc88925..806eee5637907 100644 --- a/nixos/doc/manual/development/settings-options.section.md +++ b/nixos/doc/manual/development/settings-options.section.md @@ -248,28 +248,30 @@ up in the manual. ::: {#ex-settings-typed-attrs .example} ### Declaring a type-checked `settings` attribute ```nix -settings = lib.mkOption { - type = lib.types.submodule { +{ + settings = lib.mkOption { + type = lib.types.submodule { + + freeformType = settingsFormat.type; + + # Declare an option for the port such that the type is checked and this option + # is shown in the manual. + options.port = lib.mkOption { + type = lib.types.port; + default = 8080; + description = '' + Which port this service should listen on. + ''; + }; - freeformType = settingsFormat.type; - - # Declare an option for the port such that the type is checked and this option - # is shown in the manual. - options.port = lib.mkOption { - type = lib.types.port; - default = 8080; - description = '' - Which port this service should listen on. - ''; }; - + default = {}; + description = '' + Configuration for Foo, see + <link xlink:href="https://example.com/docs/foo"/> + for supported values. + ''; }; - default = {}; - description = '' - Configuration for Foo, see - <link xlink:href="https://example.com/docs/foo"/> - for supported values. - ''; -}; +} ``` ::: diff --git a/nixos/doc/manual/development/unit-handling.section.md b/nixos/doc/manual/development/unit-handling.section.md index d5ba6a9529d01..1f6a30d6ef343 100644 --- a/nixos/doc/manual/development/unit-handling.section.md +++ b/nixos/doc/manual/development/unit-handling.section.md @@ -94,11 +94,13 @@ To make an existing sysinit service restart correctly during system switch, you have to declare: ```nix -systemd.services.my-sysinit = { - requiredBy = [ "sysinit-reactivation.target" ]; - before = [ "sysinit-reactivation.target" ]; - restartTriggers = [ config.environment.etc."my-sysinit.d".source ]; -}; +{ + systemd.services.my-sysinit = { + requiredBy = [ "sysinit-reactivation.target" ]; + before = [ "sysinit-reactivation.target" ]; + restartTriggers = [ config.environment.etc."my-sysinit.d".source ]; + }; +} ``` You need to configure appropriate `restartTriggers` specific to your service. diff --git a/nixos/doc/manual/development/writing-modules.chapter.md b/nixos/doc/manual/development/writing-modules.chapter.md index 20157a21e890f..67a5cc23a6aa5 100644 --- a/nixos/doc/manual/development/writing-modules.chapter.md +++ b/nixos/doc/manual/development/writing-modules.chapter.md @@ -28,7 +28,7 @@ NixOS modules: ```nix { config, pkgs, ... }: -{ option definitions +{ # option definitions } ``` @@ -43,15 +43,15 @@ is shown in [Example: Structure of NixOS Modules](#ex-module-syntax). { imports = - [ paths of other modules + [ # paths of other modules ]; options = { - option declarations + # option declarations }; config = { - option definitions + # option definitions }; } ``` diff --git a/nixos/doc/manual/development/writing-nixos-tests.section.md b/nixos/doc/manual/development/writing-nixos-tests.section.md index 50886376c2409..3ce12f41c60fe 100644 --- a/nixos/doc/manual/development/writing-nixos-tests.section.md +++ b/nixos/doc/manual/development/writing-nixos-tests.section.md @@ -8,10 +8,10 @@ A NixOS test is a module that has the following structure: # One or more machines: nodes = { machine = - { config, pkgs, ... }: { … }; + { config, pkgs, ... }: { /* ... */ }; machine2 = - { config, pkgs, ... }: { … }; - … + { config, pkgs, ... }: { /* ... */ }; + # … }; testScript = @@ -46,16 +46,20 @@ Tests are invoked differently depending on whether the test is part of NixOS or Tests that are part of NixOS are added to [`nixos/tests/all-tests.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/all-tests.nix). ```nix +{ hostname = runTest ./hostname.nix; +} ``` Overrides can be added by defining an anonymous module in `all-tests.nix`. ```nix +{ hostname = runTest { imports = [ ./hostname.nix ]; defaults.networking.firewall.enable = false; }; +} ``` You can run a test with attribute name `hostname` in `nixos/tests/all-tests.nix` by invoking: @@ -161,7 +165,7 @@ For faster dev cycles it's also possible to disable the code-linters skipLint = true; nodes.machine = { config, pkgs, ... }: - { configuration… + { # configuration… }; testScript = @@ -177,12 +181,14 @@ linter directly (again, don't commit this within the Nixpkgs repository): ```nix +{ testScript = '' # fmt: off Python code… # fmt: on ''; +} ``` Similarly, the type checking of test scripts can be disabled in the following @@ -193,7 +199,7 @@ way: skipTypeCheck = true; nodes.machine = { config, pkgs, ... }: - { configuration… + { # configuration… }; } ``` |