+4
-2
lib/generators.nix
+4
-2
lib/generators.nix
···
···
+16
lib/strings.nix
+16
lib/strings.nix
···
+179
nixos/doc/manual/development/settings-options.xml
+179
nixos/doc/manual/development/settings-options.xml
···
···+Many programs have configuration files where program-specific settings can be declared. File formats can be separated into two categories:+Nix-representable ones: These can trivially be mapped to a subset of Nix syntax. E.g. JSON is an example, since its values like <literal>{"foo":{"bar":10}}</literal> can be mapped directly to Nix: <literal>{ foo = { bar = 10; }; }</literal>. Other examples are INI, YAML and TOML. The following section explains the convention for these settings.+Non-nix-representable ones: These can't be trivially mapped to a subset of Nix syntax. Most generic programming languages are in this group, e.g. bash, since the statement <literal>if true; then echo hi; fi</literal> doesn't have a trivial representation in Nix.+Currently there are no fixed conventions for these, but it is common to have a <literal>configFile</literal> option for setting the configuration file path directly. The default value of <literal>configFile</literal> can be an auto-generated file, with convenient options for controlling the contents. For example an option of type <literal>attrsOf str</literal> can be used for representing environment variables which generates a section like <literal>export FOO="foo"</literal>. Often it can also be useful to also include an <literal>extraConfig</literal> option of type <literal>lines</literal> to allow arbitrary text after the autogenerated part of the file.+By convention, formats like this are handled with a generic <literal>settings</literal> option, representing the full program configuration as a Nix value. The type of this option should represent the format. The most common formats have a predefined type and string generator already declared under <literal>pkgs.formats</literal>:+A function taking an empty attribute set (for future extensibility) and returning a set with JSON-specific attributes <varname>type</varname> and <varname>generate</varname> as specified <link linkend='pkgs-formats-result'>below</link>.+A function taking an empty attribute set (for future extensibility) and returning a set with YAML-specific attributes <varname>type</varname> and <varname>generate</varname> as specified <link linkend='pkgs-formats-result'>below</link>.+<varname>pkgs.formats.ini</varname> { <replaceable>listsAsDuplicateKeys</replaceable> ? false, ... }+It returns a set with INI-specific attributes <varname>type</varname> and <varname>generate</varname> as specified <link linkend='pkgs-formats-result'>below</link>.+A function taking an empty attribute set (for future extensibility) and returning a set with TOML-specific attributes <varname>type</varname> and <varname>generate</varname> as specified <link linkend='pkgs-formats-result'>below</link>.+<varname>generate</varname> <replaceable>filename</replaceable> <replaceable>jsonValue</replaceable>+This function puts the value contents in the Nix store. So this should be avoided for secrets.+The following shows a module for an example program that uses a JSON configuration file. It demonstrates how above values can be used, along with some other related best practices. See the comments for explanations.
+1
nixos/doc/manual/development/writing-modules.xml
+1
nixos/doc/manual/development/writing-modules.xml
+11
pkgs/pkgs-lib/default.nix
+11
pkgs/pkgs-lib/default.nix
···
···
+109
pkgs/pkgs-lib/formats.nix
+109
pkgs/pkgs-lib/formats.nix
···
···
+7
pkgs/pkgs-lib/tests/default.nix
+7
pkgs/pkgs-lib/tests/default.nix
···
+157
pkgs/pkgs-lib/tests/formats.nix
+157
pkgs/pkgs-lib/tests/formats.nix
···
···+runBuildTests = tests: pkgs.linkFarm "nixpkgs-pkgs-lib-format-tests" (mapAttrsToList (name: value: { inherit name; path = runBuildTest name value; }) (filterAttrs (name: value: value != null) tests));
+3
pkgs/top-level/all-packages.nix
+3
pkgs/top-level/all-packages.nix
+2
pkgs/top-level/release.nix
+2
pkgs/top-level/release.nix
······
······