diff options
Diffstat (limited to 'nixos/doc/manual/development/writing-modules.xml')
| -rw-r--r-- | nixos/doc/manual/development/writing-modules.xml | 69 |
1 files changed, 13 insertions, 56 deletions
diff --git a/nixos/doc/manual/development/writing-modules.xml b/nixos/doc/manual/development/writing-modules.xml index bbf793bb0be9..18088040bd60 100644 --- a/nixos/doc/manual/development/writing-modules.xml +++ b/nixos/doc/manual/development/writing-modules.xml @@ -5,49 +5,25 @@ xml:id="sec-writing-modules"> <title>Writing NixOS Modules</title> <para> - NixOS has a modular system for declarative configuration. This system - combines multiple <emphasis>modules</emphasis> to produce the full system - configuration. One of the modules that constitute the configuration is - <filename>/etc/nixos/configuration.nix</filename>. Most of the others live in - the - <link -xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><filename>nixos/modules</filename></link> - subdirectory of the Nixpkgs tree. + NixOS has a modular system for declarative configuration. This system combines multiple <emphasis>modules</emphasis> to produce the full system configuration. One of the modules that constitute the configuration is <filename>/etc/nixos/configuration.nix</filename>. Most of the others live in the <link +xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><filename>nixos/modules</filename></link> subdirectory of the Nixpkgs tree. </para> <para> - 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 <emphasis>declare</emphasis> options that - can be used by other modules, and conversely can <emphasis>define</emphasis> - options provided by other modules in its own implementation. For example, the - module - <link -xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link> - declares the option <option>security.pam.services</option> that allows other - modules (e.g. - <link -xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>) - to define PAM services; and it defines the option - <option>environment.etc</option> (declared by - <link -xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>) - to cause files to be created in <filename>/etc/pam.d</filename>. + 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 <emphasis>declare</emphasis> options that can be used by other modules, and conversely can <emphasis>define</emphasis> options provided by other modules in its own implementation. For example, the module <link +xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link> declares the option <option>security.pam.services</option> that allows other modules (e.g. <link +xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>) to define PAM services; and it defines the option <option>environment.etc</option> (declared by <link +xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>) to cause files to be created in <filename>/etc/pam.d</filename>. </para> <para xml:id="para-module-syn"> In <xref -linkend="sec-configuration-syntax"/>, we saw the following structure - of NixOS modules: +linkend="sec-configuration-syntax"/>, we saw the following structure of NixOS modules: <programlisting> { config, pkgs, ... }: { <replaceable>option definitions</replaceable> } </programlisting> - This is actually an <emphasis>abbreviated</emphasis> form of module that only - defines options, but does not declare any. The structure of full NixOS - modules is shown in <xref linkend='ex-module-syntax' />. + This is actually an <emphasis>abbreviated</emphasis> form of module that only defines options, but does not declare any. The structure of full NixOS modules is shown in <xref linkend='ex-module-syntax' />. </para> <example xml:id='ex-module-syntax'> <title>Structure of NixOS Modules</title> @@ -73,47 +49,28 @@ linkend="sec-configuration-syntax"/>, we saw the following structure <calloutlist> <callout arearefs='module-syntax-1'> <para> - This line makes the current Nix expression a function. The variable - <varname>pkgs</varname> contains Nixpkgs, while <varname>config</varname> - contains the full system configuration. This line can be omitted if there - is no reference to <varname>pkgs</varname> and <varname>config</varname> - inside the module. + This line makes the current Nix expression a function. The variable <varname>pkgs</varname> contains Nixpkgs, while <varname>config</varname> contains the full system configuration. This line can be omitted if there is no reference to <varname>pkgs</varname> and <varname>config</varname> inside the module. </para> </callout> <callout arearefs='module-syntax-2'> <para> - This 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 - <filename>modules/module-list.nix</filename>. These don't need to be added - in the import list. + This 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 <filename>modules/module-list.nix</filename>. These don't need to be added in the import list. </para> </callout> <callout arearefs='module-syntax-3'> <para> - The attribute <varname>options</varname> is a nested set of - <emphasis>option declarations</emphasis> (described below). + The attribute <varname>options</varname> is a nested set of <emphasis>option declarations</emphasis> (described below). </para> </callout> <callout arearefs='module-syntax-4'> <para> - The attribute <varname>config</varname> is a nested set of - <emphasis>option definitions</emphasis> (also described below). + The attribute <varname>config</varname> is a nested set of <emphasis>option definitions</emphasis> (also described below). </para> </callout> </calloutlist> </para> <para> - <xref linkend='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 <filename>configuration.nix</filename>): - <option>services.locate.enable</option> (whether the database should be - updated) and <option>services.locate.interval</option> (when the update - should be done). It implements its functionality by defining two options - declared by other modules: <option>systemd.services</option> (the set of all - systemd services) and <option>systemd.timers</option> (the list of commands - to be executed periodically by <command>systemd</command>). + <xref linkend='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 <filename>configuration.nix</filename>): <option>services.locate.enable</option> (whether the database should be updated) and <option>services.locate.interval</option> (when the update should be done). It implements its functionality by defining two options declared by other modules: <option>systemd.services</option> (the set of all systemd services) and <option>systemd.timers</option> (the list of commands to be executed periodically by <command>systemd</command>). </para> <example xml:id='locate-example'> <title>NixOS Module for the “locate” Service</title> |