uboot: (firmwareOdroidC2/C4) don't invoke patch tool, use patches = [] instead
https://github.com/NixOS/nixpkgs/blob/master/pkgs/stdenv/generic/setup.sh#L948 this can do it nicely. Signed-off-by: Anton Arapov <anton@deadbeef.mx>
This commit is contained in:
commit
56de2bcd43
30691 changed files with 3076956 additions and 0 deletions
208
nixos/doc/manual/development/writing-modules.chapter.md
Normal file
208
nixos/doc/manual/development/writing-modules.chapter.md
Normal file
|
|
@ -0,0 +1,208 @@
|
|||
# Writing NixOS Modules {#sec-writing-modules}
|
||||
|
||||
NixOS has a modular system for declarative configuration. This system
|
||||
combines multiple *modules* to produce the full system configuration.
|
||||
One of the modules that constitute the configuration is
|
||||
`/etc/nixos/configuration.nix`. Most of the others live in the
|
||||
[`nixos/modules`](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules)
|
||||
subdirectory of the Nixpkgs tree.
|
||||
|
||||
Each NixOS module is a file that handles one logical aspect of the
|
||||
configuration, such as a specific kind of hardware, a service, or
|
||||
network settings. A module configuration does not have to handle
|
||||
everything from scratch; it can use the functionality provided by other
|
||||
modules for its implementation. Thus a module can *declare* options that
|
||||
can be used by other modules, and conversely can *define* options
|
||||
provided by other modules in its own implementation. For example, the
|
||||
module
|
||||
[`pam.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix)
|
||||
declares the option `security.pam.services` that allows other modules (e.g.
|
||||
[`sshd.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix))
|
||||
to define PAM services; and it defines the option `environment.etc` (declared by
|
||||
[`etc.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix))
|
||||
to cause files to be created in `/etc/pam.d`.
|
||||
|
||||
In [](#sec-configuration-syntax), we saw the following structure of
|
||||
NixOS modules:
|
||||
|
||||
```nix
|
||||
{ config, pkgs, ... }:
|
||||
|
||||
{ option definitions
|
||||
}
|
||||
```
|
||||
|
||||
This is actually an *abbreviated* form of module that only defines
|
||||
options, but does not declare any. The structure of full NixOS modules
|
||||
is shown in [Example: Structure of NixOS Modules](#ex-module-syntax).
|
||||
|
||||
::: {#ex-module-syntax .example}
|
||||
::: {.title}
|
||||
**Example: Structure of NixOS Modules**
|
||||
:::
|
||||
```nix
|
||||
{ config, pkgs, ... }:
|
||||
|
||||
{
|
||||
imports =
|
||||
[ paths of other modules
|
||||
];
|
||||
|
||||
options = {
|
||||
option declarations
|
||||
};
|
||||
|
||||
config = {
|
||||
option definitions
|
||||
};
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
The meaning of each part is as follows.
|
||||
|
||||
- The first line makes the current Nix expression a function. The variable
|
||||
`pkgs` contains Nixpkgs (by default, it takes the `nixpkgs` entry of
|
||||
`NIX_PATH`, see the [Nix manual](https://nixos.org/manual/nix/stable/#sec-common-env)
|
||||
for further details), while `config` contains the full system
|
||||
configuration. This line can be omitted if there is no reference to
|
||||
`pkgs` and `config` inside the module.
|
||||
|
||||
- This `imports` list enumerates the paths to other NixOS modules that
|
||||
should be included in the evaluation of the system configuration. A
|
||||
default set of modules is defined in the file `modules/module-list.nix`.
|
||||
These don\'t need to be added in the import list.
|
||||
|
||||
- The attribute `options` is a nested set of *option declarations*
|
||||
(described below).
|
||||
|
||||
- The attribute `config` is a nested set of *option definitions* (also
|
||||
described below).
|
||||
|
||||
[Example: NixOS Module for the "locate" Service](#locate-example)
|
||||
shows a module that handles the regular update of the "locate" database,
|
||||
an index of all files in the file system. This module declares two
|
||||
options that can be defined by other modules (typically the user's
|
||||
`configuration.nix`): `services.locate.enable` (whether the database should
|
||||
be updated) and `services.locate.interval` (when the update should be done).
|
||||
It implements its functionality by defining two options declared by other
|
||||
modules: `systemd.services` (the set of all systemd services) and
|
||||
`systemd.timers` (the list of commands to be executed periodically by
|
||||
`systemd`).
|
||||
|
||||
Care must be taken when writing systemd services using `Exec*` directives. By
|
||||
default systemd performs substitution on `%<char>` specifiers in these
|
||||
directives, expands environment variables from `$FOO` and `${FOO}`, splits
|
||||
arguments on whitespace, and splits commands on `;`. All of these must be escaped
|
||||
to avoid unexpected substitution or splitting when interpolating into an `Exec*`
|
||||
directive, e.g. when using an `extraArgs` option to pass additional arguments to
|
||||
the service. The functions `utils.escapeSystemdExecArg` and
|
||||
`utils.escapeSystemdExecArgs` are provided for this, see [Example: Escaping in
|
||||
Exec directives](#exec-escaping-example) for an example. When using these
|
||||
functions system environment substitution should *not* be disabled explicitly.
|
||||
|
||||
::: {#locate-example .example}
|
||||
::: {.title}
|
||||
**Example: NixOS Module for the "locate" Service**
|
||||
:::
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
with lib;
|
||||
|
||||
let
|
||||
cfg = config.services.locate;
|
||||
in {
|
||||
options.services.locate = {
|
||||
enable = mkOption {
|
||||
type = types.bool;
|
||||
default = false;
|
||||
description = ''
|
||||
If enabled, NixOS will periodically update the database of
|
||||
files used by the locate command.
|
||||
'';
|
||||
};
|
||||
|
||||
interval = mkOption {
|
||||
type = types.str;
|
||||
default = "02:15";
|
||||
example = "hourly";
|
||||
description = ''
|
||||
Update the locate database at this interval. Updates by
|
||||
default at 2:15 AM every day.
|
||||
|
||||
The format is described in
|
||||
systemd.time(7).
|
||||
'';
|
||||
};
|
||||
|
||||
# Other options omitted for documentation
|
||||
};
|
||||
|
||||
config = {
|
||||
systemd.services.update-locatedb =
|
||||
{ description = "Update Locate Database";
|
||||
path = [ pkgs.su ];
|
||||
script =
|
||||
''
|
||||
mkdir -m 0755 -p $(dirname ${toString cfg.output})
|
||||
exec updatedb \
|
||||
--localuser=${cfg.localuser} \
|
||||
${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \
|
||||
--output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags}
|
||||
'';
|
||||
};
|
||||
|
||||
systemd.timers.update-locatedb = mkIf cfg.enable
|
||||
{ description = "Update timer for locate database";
|
||||
partOf = [ "update-locatedb.service" ];
|
||||
wantedBy = [ "timers.target" ];
|
||||
timerConfig.OnCalendar = cfg.interval;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
::: {#exec-escaping-example .example}
|
||||
::: {.title}
|
||||
**Example: Escaping in Exec directives**
|
||||
:::
|
||||
```nix
|
||||
{ config, lib, pkgs, utils, ... }:
|
||||
|
||||
with lib;
|
||||
|
||||
let
|
||||
cfg = config.services.echo;
|
||||
echoAll = pkgs.writeScript "echo-all" ''
|
||||
#! ${pkgs.runtimeShell}
|
||||
for s in "$@"; do
|
||||
printf '%s\n' "$s"
|
||||
done
|
||||
'';
|
||||
args = [ "a%Nything" "lang=\${LANG}" ";" "/bin/sh -c date" ];
|
||||
in {
|
||||
systemd.services.echo =
|
||||
{ description = "Echo to the journal";
|
||||
wantedBy = [ "multi-user.target" ];
|
||||
serviceConfig.Type = "oneshot";
|
||||
serviceConfig.ExecStart = ''
|
||||
${echoAll} ${utils.escapeSystemdExecArgs args}
|
||||
'';
|
||||
};
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
```{=docbook}
|
||||
<xi:include href="option-declarations.section.xml" />
|
||||
<xi:include href="option-types.section.xml" />
|
||||
<xi:include href="option-def.section.xml" />
|
||||
<xi:include href="assertions.section.xml" />
|
||||
<xi:include href="meta-attributes.section.xml" />
|
||||
<xi:include href="importing-modules.section.xml" />
|
||||
<xi:include href="replace-modules.section.xml" />
|
||||
<xi:include href="freeform-modules.section.xml" />
|
||||
<xi:include href="settings-options.section.xml" />
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue