···

       
10
       
10
       
 
       
When a build failure happens there will be an instruction printed that shows how to attach with `cntr` to the build sandbox.

     

       
11
       
11
       
 
       


     

       
12
       
12
       
 
       
::: {.note}

     

       
13
       
13
       
-
       
::: {.title}

     

       
14
       
13
       
 
       
Caution with remote builds

     

       
15
       
15
       
-
       
:::

     

       
16
       
14
       
 
       


     

       
17
       
15
       
 
       
This won’t work with remote builds as the build environment is on a different machine and can’t be accessed by `cntr`. Remote builds can be turned off by setting `--option builders ''` for `nix-build` or `--builders ''` for `nix build`.

     

       
18
       
16
       
 
       
:::

     

···

       
13
       
13
       
 
       
submodules.

     

       
14
       
14
       
 
       


     

       
15
       
15
       
 
       
::: {#ex-freeform-module .example}

     

       
16
       
16
       
-
       
::: {.title}

     

       
17
       
16
       
 
       
**Example: Freeform submodule**

     

       
18
       
18
       
-
       
:::

     

       
17
       
17
       
+
       


     

       
19
       
18
       
 
       
The following shows a submodule assigning a freeform type that allows

     

       
20
       
19
       
 
       
arbitrary attributes with `str` values below `settings`, but also

     

       
21
       
20
       
 
       
declares an option for the `settings.port` attribute to have it

     

···

       
189
       
189
       
 
       
enforces that there can only be a single display manager enabled.

     

       
190
       
190
       
 
       


     

       
191
       
191
       
 
       
::: {#ex-option-declaration-eot-service .example}

     

       
192
       
192
       
-
       
::: {.title}

     

       
193
       
192
       
 
       
**Example: Extensible type placeholder in the service module**

     

       
194
       
194
       
-
       
:::

     

       
195
       
193
       
 
       
```nix

     

       
196
       
194
       
 
       
services.xserver.displayManager.enable = mkOption {

     

       
197
       
195
       
 
       
  description = "Display manager to use";

     
···

       
201
       
199
       
 
       
:::

     

       
202
       
200
       
 
       


     

       
203
       
201
       
 
       
::: {#ex-option-declaration-eot-backend-gdm .example}

     

       
204
       
204
       
-
       
::: {.title}

     

       
205
       
202
       
 
       
**Example: Extending `services.xserver.displayManager.enable` in the `gdm` module**

     

       
206
       
206
       
-
       
:::

     

       
207
       
203
       
 
       
```nix

     

       
208
       
204
       
 
       
services.xserver.displayManager.enable = mkOption {

     

       
209
       
205
       
 
       
  type = with types; nullOr (enum [ "gdm" ]);

     
···

       
212
       
208
       
 
       
:::

     

       
213
       
209
       
 
       


     

       
214
       
210
       
 
       
::: {#ex-option-declaration-eot-backend-sddm .example}

     

       
215
       
215
       
-
       
::: {.title}

     

       
216
       
211
       
 
       
**Example: Extending `services.xserver.displayManager.enable` in the `sddm` module**

     

       
217
       
217
       
-
       
:::

     

       
218
       
212
       
 
       
```nix

     

       
219
       
213
       
 
       
services.xserver.displayManager.enable = mkOption {

     

       
220
       
214
       
 
       
  type = with types; nullOr (enum [ "sddm" ]);

     

···

       
36
       
36
       
 
       
    together. This type is recommended when the option type is unknown.

     

       
37
       
37
       
 
       


     

       
38
       
38
       
 
       
    ::: {#ex-types-anything .example}

     

       
39
       
39
       
-
       
    ::: {.title}

     

       
40
       
39
       
 
       
    **Example: `types.anything` Example**

     

       
41
       
41
       
-
       
    :::

     

       
40
       
40
       
+
       


     

       
42
       
41
       
 
       
    Two definitions of this type like

     

       
43
       
42
       
 
       


     

       
44
       
43
       
 
       
    ```nix

     
···

       
357
       
356
       
 
       
if you want to allow users to leave it undefined.

     

       
358
       
357
       
 
       


     

       
359
       
358
       
 
       
::: {#ex-submodule-direct .example}

     

       
360
       
360
       
-
       
::: {.title}

     

       
361
       
359
       
 
       
**Example: Directly defined submodule**

     

       
362
       
362
       
-
       
:::

     

       
363
       
360
       
 
       
```nix

     

       
364
       
361
       
 
       
options.mod = mkOption {

     

       
365
       
362
       
 
       
  description = "submodule example";

     
···

       
378
       
375
       
 
       
:::

     

       
379
       
376
       
 
       


     

       
380
       
377
       
 
       
::: {#ex-submodule-reference .example}

     

       
381
       
381
       
-
       
::: {.title}

     

       
382
       
378
       
 
       
**Example: Submodule defined as a reference**

     

       
383
       
383
       
-
       
:::

     

       
384
       
379
       
 
       
```nix

     

       
385
       
380
       
 
       
let

     

       
386
       
381
       
 
       
  modOptions = {

     
···

       
408
       
403
       
 
       
([Example: Definition of a list of submodules](#ex-submodule-listof-definition)).

     

       
409
       
404
       
 
       


     

       
410
       
405
       
 
       
::: {#ex-submodule-listof-declaration .example}

     

       
411
       
411
       
-
       
::: {.title}

     

       
412
       
406
       
 
       
**Example: Declaration of a list of submodules**

     

       
413
       
413
       
-
       
:::

     

       
414
       
407
       
 
       
```nix

     

       
415
       
408
       
 
       
options.mod = mkOption {

     

       
416
       
409
       
 
       
  description = "submodule example";

     
···

       
429
       
422
       
 
       
:::

     

       
430
       
423
       
 
       


     

       
431
       
424
       
 
       
::: {#ex-submodule-listof-definition .example}

     

       
432
       
432
       
-
       
::: {.title}

     

       
433
       
425
       
 
       
**Example: Definition of a list of submodules**

     

       
434
       
434
       
-
       
:::

     

       
435
       
426
       
 
       
```nix

     

       
436
       
427
       
 
       
config.mod = [

     

       
437
       
428
       
 
       
  { foo = 1; bar = "one"; }

     
···

       
446
       
437
       
 
       
([Example: Definition of attribute sets of submodules](#ex-submodule-attrsof-definition)).

     

       
447
       
438
       
 
       


     

       
448
       
439
       
 
       
::: {#ex-submodule-attrsof-declaration .example}

     

       
449
       
449
       
-
       
::: {.title}

     

       
450
       
440
       
 
       
**Example: Declaration of attribute sets of submodules**

     

       
451
       
451
       
-
       
:::

     

       
452
       
441
       
 
       
```nix

     

       
453
       
442
       
 
       
options.mod = mkOption {

     

       
454
       
443
       
 
       
  description = "submodule example";

     
···

       
467
       
456
       
 
       
:::

     

       
468
       
457
       
 
       


     

       
469
       
458
       
 
       
::: {#ex-submodule-attrsof-definition .example}

     

       
470
       
470
       
-
       
::: {.title}

     

       
471
       
459
       
 
       
**Example: Definition of attribute sets of submodules**

     

       
472
       
472
       
-
       
:::

     

       
473
       
460
       
 
       
```nix

     

       
474
       
461
       
 
       
config.mod.one = { foo = 1; bar = "one"; };

     

       
475
       
462
       
 
       
config.mod.two = { foo = 2; bar = "two"; };

     
···

       
489
       
476
       
 
       
    ([Example: Overriding a type check](#ex-extending-type-check-2)).

     

       
490
       
477
       
 
       


     

       
491
       
478
       
 
       
    ::: {#ex-extending-type-check-1 .example}

     

       
492
       
492
       
-
       
    ::: {.title}

     

       
493
       
479
       
 
       
    **Example: Adding a type check**

     

       
494
       
494
       
-
       
    :::

     

       
480
       
480
       
+
       


     

       
495
       
481
       
 
       
    ```nix

     

       
496
       
482
       
 
       
    byte = mkOption {

     

       
497
       
483
       
 
       
      description = "An integer between 0 and 255.";

     
···

       
501
       
487
       
 
       
    :::

     

       
502
       
488
       
 
       


     

       
503
       
489
       
 
       
    ::: {#ex-extending-type-check-2 .example}

     

       
504
       
504
       
-
       
    ::: {.title}

     

       
505
       
490
       
 
       
    **Example: Overriding a type check**

     

       
506
       
506
       
-
       
    :::

     

       
491
       
491
       
+
       


     

       
507
       
492
       
 
       
    ```nix

     

       
508
       
493
       
 
       
    nixThings = mkOption {

     

       
509
       
494
       
 
       
      description = "words that start with 'nix'";

     

···

       
144
       
144
       
 
       
    :::

     

       
145
       
145
       
 
       


     

       
146
       
146
       
 
       
::: {#ex-settings-nix-representable .example}

     

       
147
       
147
       
-
       
::: {.title}

     

       
148
       
147
       
 
       
**Example: Module with conventional `settings` option**

     

       
149
       
149
       
-
       
:::

     

       
148
       
148
       
+
       


     

       
150
       
149
       
 
       
The following shows a module for an example program that uses a JSON

     

       
151
       
150
       
 
       
configuration file. It demonstrates how above values can be used, along

     

       
152
       
151
       
 
       
with some other related best practices. See the comments for

     
···

       
220
       
219
       
 
       
up in the manual.

     

       
221
       
220
       
 
       


     

       
222
       
221
       
 
       
::: {#ex-settings-typed-attrs .example}

     

       
223
       
223
       
-
       
::: {.title}

     

       
224
       
222
       
 
       
**Example: Declaring a type-checked `settings` attribute**

     

       
225
       
225
       
-
       
:::

     

       
226
       
223
       
 
       
```nix

     

       
227
       
224
       
 
       
settings = lib.mkOption {

     

       
228
       
225
       
 
       
  type = lib.types.submodule {

     

···

       
37
       
37
       
 
       
is shown in [Example: Structure of NixOS Modules](#ex-module-syntax).

     

       
38
       
38
       
 
       


     

       
39
       
39
       
 
       
::: {#ex-module-syntax .example}

     

       
40
       
40
       
-
       
::: {.title}

     

       
41
       
40
       
 
       
**Example: Structure of NixOS Modules**

     

       
42
       
42
       
-
       
:::

     

       
43
       
41
       
 
       
```nix

     

       
44
       
42
       
 
       
{ config, pkgs, ... }:

     

       
45
       
43
       
 
       


     
···

       
102
       
100
       
 
       
functions system environment substitution should *not* be disabled explicitly.

     

       
103
       
101
       
 
       


     

       
104
       
102
       
 
       
::: {#locate-example .example}

     

       
105
       
105
       
-
       
::: {.title}

     

       
106
       
103
       
 
       
**Example: NixOS Module for the "locate" Service**

     

       
107
       
107
       
-
       
:::

     

       
108
       
104
       
 
       
```nix

     

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

     

       
110
       
106
       
 
       


     
···

       
165
       
161
       
 
       
:::

     

       
166
       
162
       
 
       


     

       
167
       
163
       
 
       
::: {#exec-escaping-example .example}

     

       
168
       
168
       
-
       
::: {.title}

     

       
169
       
164
       
 
       
**Example: Escaping in Exec directives**

     

       
170
       
170
       
-
       
:::

     

       
171
       
165
       
 
       
```nix

     

       
172
       
166
       
 
       
{ config, lib, pkgs, utils, ... }:

     

       
173
       
167
       
 
       


     

···

       
538
       
538
       
 
       
corresponding configuration Nix expression.

     

       
539
       
539
       
 
       


     

       
540
       
540
       
 
       
::: {#ex-partition-scheme-MBR .example}

     

       
541
       
541
       
-
       
::: {.title}

     

       
542
       
541
       
 
       
**Example: Example partition schemes for NixOS on `/dev/sda` (MBR)**

     

       
543
       
543
       
-
       
:::

     

       
544
       
542
       
 
       
```ShellSession

     

       
545
       
543
       
 
       
# parted /dev/sda -- mklabel msdos

     

       
546
       
544
       
 
       
# parted /dev/sda -- mkpart primary 1MB -8GB

     
···

       
549
       
547
       
 
       
:::

     

       
550
       
548
       
 
       


     

       
551
       
549
       
 
       
::: {#ex-partition-scheme-UEFI .example}

     

       
552
       
552
       
-
       
::: {.title}

     

       
553
       
550
       
 
       
**Example: Example partition schemes for NixOS on `/dev/sda` (UEFI)**

     

       
554
       
554
       
-
       
:::

     

       
555
       
551
       
 
       
```ShellSession

     

       
556
       
552
       
 
       
# parted /dev/sda -- mklabel gpt

     

       
557
       
553
       
 
       
# parted /dev/sda -- mkpart primary 512MB -8GB

     
···

       
562
       
558
       
 
       
:::

     

       
563
       
559
       
 
       


     

       
564
       
560
       
 
       
::: {#ex-install-sequence .example}

     

       
565
       
565
       
-
       
::: {.title}

     

       
566
       
561
       
 
       
**Example: Commands for Installing NixOS on `/dev/sda`**

     

       
567
       
567
       
-
       
:::

     

       
562
       
562
       
+
       


     

       
568
       
563
       
 
       
With a partitioned disk.

     

       
569
       
564
       
 
       


     

       
570
       
565
       
 
       
```ShellSession

     
···

       
583
       
578
       
 
       
:::

     

       
584
       
579
       
 
       


     

       
585
       
580
       
 
       
::: {#ex-config .example}

     

       
586
       
586
       
-
       
::: {.title}

     

       
587
       
581
       
 
       
**Example: NixOS Configuration**

     

       
588
       
588
       
-
       
:::

     

       
589
       
582
       
 
       
```ShellSession

     

       
590
       
583
       
 
       
{ config, pkgs, ... }: {

     

       
591
       
584
       
 
       
  imports = [