diff options
author | Janne Heß <janne@hess.ooo> | 2024-03-27 19:10:27 +0100 |
---|---|---|
committer | Valentin Gagarin <valentin.gagarin@tweag.io> | 2024-03-28 09:28:12 +0100 |
commit | fcc95ff8172cc68a0d2d52aa1e8ef2120d2904ec (patch) | |
tree | 8de1a02f7d1624c97562c7736896a6c95c74ec04 /nixos/doc/manual/development | |
parent | bc77c7a9730833c7668c92288c6af950e7270cb5 (diff) |
treewide: Fix all Nix ASTs in all markdown files
This allows for correct highlighting and maybe future automatic formatting. The AST was verified to work with nixfmt only.
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… }; } ``` |