$ cd /
$ tree bin usr sbin lib lib64
bin
└── sh -> /nix/store/...
usr
└── bin
    └── env -> /nix/store/...
sbin  [error opening dir]
lib  [error opening dir]
lib64  [error opening dir]    

# build the system described by the configuration
#
# <nixpkgs/nixos> evaluates the configuration at $NIXOS_CONFIG, or
# at <nixos-config>, which is by default `/etc/nixos/configuration.nix`
system=`nix build --impure --no-link --print-out-paths \
  --expr '(import <nixpkgs/nixos> {}).config.system.build.toplevel'`

# update the system's profile with a new generation that points to the new system object
nix build --profile /nix/var/nix/profiles/system $system

# pass off execution to a script inside the new system object, allowing it to
# 1. update the bootloader
# 2. stop/start/reload/restart systemd units
# 3. mount/unmount/remount filesystems
# 4. run $system/activate, which is a series of idempotent "activation scripts"
#    that make sure the running system conforms to the new configuration
$system/bin/switch-to-configuration switch

# nixos-rebuild...
# `
# | subcommand   | builds what?       | updates profile? | switch-to-configuration? |
# +--------------+--------------------+------------------+--------------------------+
# | switch       | toplevel           | yes              | yes                      |
# | boot         | toplevel           | yes              | yes                      |
# | test         | toplevel           | no               | yes                      |
# | dry-activate | toplevel           | no               | yes                      |
# | build        | toplevel           | no               | no                       |
# | dry-build    | toplevel --dry-run | no               | no                       |
# | build-vm     | vm                 | no               | no                       |
# | build-vm-wi..| vmWithBootloader   | no               | no                       |
#   th-bootloader
# `
# switch-to-configuration...
# `
# | subcommand   | installs bootloader? | activate?        |
# +--------------+----------------------+------------------+
# | switch       | yes                  | yes              |
# | boot         | yes                  | no               |
# | test         | no                   | yes              |
# | dry-activate | no                   | no, dry-activate |
# `

# for booting and activating the system
# nixos can boot if you delete *everything but these*, it just won't remember any state!
/boot/
/nix/

# for identifying a machine across reboots
/etc/machine-id
/etc/ssh/ssh_host_*

# for persisting ad hoc users/groups, unless all are declarative
/etc/{passwd,shadow,group,subuid,subgid}

# user state
/root/
/home/

# application state
/var/{db,log,lib,spool}/

{ 
  config, # the final configuration after merging all option definitions
  options, # the set of all declared options
  lib, # the nixpkgs standard library
  pkgs, # the nixpkgs package set
  modulesPath, # <nixpkgs/nixos/modules>
  ...
}: {
  imports = [
    # paths to other modules
  ];

  options = {
    # option declarations
  };

  config = {
    # option definitions
  };
}

{ ... }: {
  imports = [
    # paths to other modules
  ];

  # option definitions
}

{
  # option definitions
}

# assuming two declared options `someList` and `someSet`...

# imported.nix
{
  someList = [ 1 ];
  someSet.a = 1;
}

# main.nix
{
  imports = [ ./imported.nix ];

  someList = [ 2 ];
  someSet.b = 2;
}

# the resulting configuration
{
  someList = [ 1 2 ];
  someSet = {
    a = 1;
    b = 2;
  };
}

{ lib, config, ... }:
with lib;
{
  ## Overriding
  # if you want to be able to change a scalar option that's already been defined
  # in another module, you can change a definition's override priority to
  # signal which should be preferred.
  #
  # for set/list options, this will also totally replace lower-priority definitions
  # rather than merging like normal.
  
  # lower priority = more preferred
  # the default is 100
  myScalarOption = mkOverride 1 "important!!!";

  # presets are also available
  myScalarOption = mkDefault "not very important..."; # mkOverride 1000
  myScalarOption = mkForce   "kind of a big deal!!!"; # mkOverride 50

  ## Ordering
  # if you want to make sure definitions are merged in a *specific order*, you can
  # change a definition's order priority, too

  # default is 1000
  myListOption = mkOrder 1 [ "i go first!!!" ];

  # and, the presets
  myListOption = mkBefore [ "put me in early :D" ]; # mkOrder 500
  myListOption = mkAfter  [ "fashionably late ;)" ]; # mkOrder 1500

  ## Conditional and Assertion
  # you can also keep a portion of the configuration from being defined unless
  # a predicate is `true`
  myMaybeOption = mkIf config.foo.enabled "success!";

  # or, more forcefully, you can assert a precondition and throw otherwise
  myMaybeOption = mkAssert config.foo.enabled
    "you need to enable foo to use this!"
    "success!";
  
  ## Merge
  # finally, you can invoke the merge algorithm on a list of sets yourself, as if
  # each of the sets were inside a different module

  # this can be convenient in cases where you want to apply different properties to
  # different subsets of a config
  myMergedConfig = mkMerge [
    (mkDefault {
      a = 1;
      c = 3;
    })
    (mkIf config.foo.enabled {
      b = 2;
      c = 4;
    })
  ];
  # if config.foo.enabled == true:
  #   { a = 1; b = 2; c = 4; }
  # otherwise:
  #   { a = 1; c = 3; }
}

{ lib, pkgs, ... }:
with lib;
{
  options.foo = {
    myOption = mkOption {
      # all attributes are optional, `null` if unset

      # behavior:
      default = "world", # what does this option default to if left undefined?
      type = types.str, # what type of data is this option?
      apply = x: "Hello, ${x}!", # transforms the value given to a different result
      readOnly = false, # can this only be written once?

      # documentation:
      description = ..., # description of option
      defaultText = ..., # string representation of `default`
      example = ..., # example value
      internal = false, # is this for nixos developers only?
      visible = true # should this be visible in documentation?
    };

    # option to enable a module is so common it gets a shortcut
    enable = mkEnableOption "foo";
    # equivalent to:
    enable = mkOption {
      default = false;
      example = true;
      description = "Whether to enable foo.";
      type = types.bool;
    };

    # also, a shortcut for creating a package option
    myPackage = mkPackageOption
      pkgs # package set
      "foo" # package name
      {
        # all attributes are optional

        nullable = false; # whether the package can be null
        default = "foo"; # default package, by default the name specified above
        example = ...;
        extraDescription = ...;
      };
  };

  config = mkIf config.foo.enable {
    /* ... */
  };
}