From f2b54e3b71891c29f951e46b00c6edc4807b3b63 Mon Sep 17 00:00:00 2001 From: fricklerhandwerk Date: Sat, 17 Jun 2023 03:25:57 +0200 Subject: [PATCH 1/4] add links to environment variables documentation --- .../src/command-ref/conf-file-prefix.md | 25 ++++++++----------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/doc/manual/src/command-ref/conf-file-prefix.md b/doc/manual/src/command-ref/conf-file-prefix.md index 44b7ba86d..d2989ff20 100644 --- a/doc/manual/src/command-ref/conf-file-prefix.md +++ b/doc/manual/src/command-ref/conf-file-prefix.md @@ -6,28 +6,25 @@ By default Nix reads settings from the following places: - - The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e. - `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if - `NIX_CONF_DIR` is set. Values loaded in this file are not forwarded - to the Nix daemon. The client assumes that the daemon has already - loaded them. + - The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e. `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if [`NIX_CONF_DIR`](./env-common.md#env-NIX_CONF_DIR) is set. - - If `NIX_USER_CONF_FILES` is set, then each path separated by `:` - will be loaded in reverse order. + Values loaded in this file are not forwarded to the Nix daemon. + The client assumes that the daemon has already loaded them. - Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` - and `XDG_CONFIG_HOME`. If unset, `XDG_CONFIG_DIRS` defaults to - `/etc/xdg`, and `XDG_CONFIG_HOME` defaults to `$HOME/.config` - as per [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). + - If [`NIX_USER_CONF_FILES`](./env-common.md#env-NIX_USER_CONF_FILES) is set, then each path separated by `:` will be loaded in reverse order. - - If `NIX_CONFIG` is set, its contents is treated as the contents of - a configuration file. + Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` and [`XDG_CONFIG_HOME`](./env-common.md#env-XDG_CONFIG_HOME). + If unset, `XDG_CONFIG_DIRS` defaults to `/etc/xdg`, and `XDG_CONFIG_HOME` defaults to `$HOME/.config` as per [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). + + - If [`NIX_CONFIG`](./env-common.md#env-NIX_CONFIG) is set, its contents are treated as the contents of a configuration file. The configuration files consist of `name = value` pairs, one per line. Other files can be included with a line like `include path`, where *path* is interpreted relative to the current conf file and a missing file is an error unless `!include` is used instead. Comments -start with a `#` character. Here is an example configuration file: +start with a `#` character. + +Here is an example configuration file: keep-outputs = true # Nice for developers keep-derivations = true # Idem From 38bd1cc9bc80e6dec59e56a7d1ce19379915a910 Mon Sep 17 00:00:00 2001 From: fricklerhandwerk Date: Sat, 17 Jun 2023 03:53:37 +0200 Subject: [PATCH 2/4] split configuration file page into sections this makes it easier to scan for specific information, such as the format of command line flags --- .../src/command-ref/conf-file-prefix.md | 53 +++++++++++-------- 1 file changed, 32 insertions(+), 21 deletions(-) diff --git a/doc/manual/src/command-ref/conf-file-prefix.md b/doc/manual/src/command-ref/conf-file-prefix.md index d2989ff20..29325ee45 100644 --- a/doc/manual/src/command-ref/conf-file-prefix.md +++ b/doc/manual/src/command-ref/conf-file-prefix.md @@ -4,6 +4,10 @@ # Description +Nix supports a variety of configuration settings, which are read from configuration files or taken as command line flags. + +## Configuration file + By default Nix reads settings from the following places: - The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e. `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if [`NIX_CONF_DIR`](./env-common.md#env-NIX_CONF_DIR) is set. @@ -18,32 +22,39 @@ By default Nix reads settings from the following places: - If [`NIX_CONFIG`](./env-common.md#env-NIX_CONFIG) is set, its contents are treated as the contents of a configuration file. -The configuration files consist of `name = value` pairs, one per -line. Other files can be included with a line like `include path`, -where *path* is interpreted relative to the current conf file and a -missing file is an error unless `!include` is used instead. Comments -start with a `#` character. +### File format -Here is an example configuration file: +Configuration files consist of `name = value` pairs, one per line. +Comments start with a `#` character. - keep-outputs = true # Nice for developers - keep-derivations = true # Idem +Example: -You can override settings on the command line using the `--option` -flag, e.g. `--option keep-outputs false`. Every configuration setting -also has a corresponding command line flag, e.g. `--max-jobs 16`; for -Boolean settings, there are two flags to enable or disable the setting -(e.g. `--keep-failed` and `--no-keep-failed`). +``` +keep-outputs = true # Nice for developers +keep-derivations = true # Idem +``` -A configuration setting usually overrides any previous value. However, -you can prefix the name of the setting by `extra-` to *append* to the -previous value. For instance, +Other files can be included with a line like `include `, where `` is interpreted relative to the current configuration file. +A missing file is an error unless `!include` is used instead. - substituters = a b - extra-substituters = c d +A configuration setting usually overrides any previous value. +However, you can prefix the name of the setting by `extra-` to *append* to the previous value. -defines the `substituters` setting to be `a b c d`. This is also -available as a command line flag (e.g. `--extra-substituters`). +For instance, -The following settings are currently available: +``` +substituters = a b +extra-substituters = c d +``` + +defines the `substituters` setting to be `a b c d`. + +## Command line flags + +Every configuration setting has a corresponding command line flag (e.g. `--max-jobs 16`). +Boolean settings do not need an argument, and can be explicitly disabled with the `no-` prefix (e.g. `--keep-failed` and `--no-keep-failed`). + +Existing settings can be appended to using the `extra-` prefix (e.g. `--extra-substituters`). + +# Available settings From bc7324e912578cdbeb1f10bf1c8d9b447a416dbd Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 20 Jun 2023 12:12:03 +0200 Subject: [PATCH 3/4] clarify read order for configuration settings --- doc/manual/src/command-ref/conf-file-prefix.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/manual/src/command-ref/conf-file-prefix.md b/doc/manual/src/command-ref/conf-file-prefix.md index 29325ee45..3cd622247 100644 --- a/doc/manual/src/command-ref/conf-file-prefix.md +++ b/doc/manual/src/command-ref/conf-file-prefix.md @@ -8,19 +8,19 @@ Nix supports a variety of configuration settings, which are read from configurat ## Configuration file -By default Nix reads settings from the following places: +By default Nix reads settings from the following places, in that order: - - The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e. `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if [`NIX_CONF_DIR`](./env-common.md#env-NIX_CONF_DIR) is set. +1. The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e. `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if [`NIX_CONF_DIR`](./env-common.md#env-NIX_CONF_DIR) is set. - Values loaded in this file are not forwarded to the Nix daemon. - The client assumes that the daemon has already loaded them. + Values loaded in this file are not forwarded to the Nix daemon. + The client assumes that the daemon has already loaded them. - - If [`NIX_USER_CONF_FILES`](./env-common.md#env-NIX_USER_CONF_FILES) is set, then each path separated by `:` will be loaded in reverse order. +1. If [`NIX_USER_CONF_FILES`](./env-common.md#env-NIX_USER_CONF_FILES) is set, then each path separated by `:` will be loaded in reverse order. - Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` and [`XDG_CONFIG_HOME`](./env-common.md#env-XDG_CONFIG_HOME). - If unset, `XDG_CONFIG_DIRS` defaults to `/etc/xdg`, and `XDG_CONFIG_HOME` defaults to `$HOME/.config` as per [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). + Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` and [`XDG_CONFIG_HOME`](./env-common.md#env-XDG_CONFIG_HOME). + If unset, `XDG_CONFIG_DIRS` defaults to `/etc/xdg`, and `XDG_CONFIG_HOME` defaults to `$HOME/.config` as per [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). - - If [`NIX_CONFIG`](./env-common.md#env-NIX_CONFIG) is set, its contents are treated as the contents of a configuration file. +1. If [`NIX_CONFIG`](./env-common.md#env-NIX_CONFIG) is set, its contents are treated as the contents of a configuration file. ### File format @@ -38,7 +38,7 @@ Other files can be included with a line like `include `, where `` is A missing file is an error unless `!include` is used instead. A configuration setting usually overrides any previous value. -However, you can prefix the name of the setting by `extra-` to *append* to the previous value. +However, for settings that take a list of items, you can prefix the name of the setting by `extra-` to *append* to the previous value. For instance, From 68c62193439ec90d34a7988c6a1a73b3e553a435 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 20 Jun 2023 12:12:23 +0200 Subject: [PATCH 4/4] clarify setting options on the command line --- doc/manual/src/command-ref/conf-file-prefix.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/doc/manual/src/command-ref/conf-file-prefix.md b/doc/manual/src/command-ref/conf-file-prefix.md index 3cd622247..1e4085977 100644 --- a/doc/manual/src/command-ref/conf-file-prefix.md +++ b/doc/manual/src/command-ref/conf-file-prefix.md @@ -49,12 +49,22 @@ extra-substituters = c d defines the `substituters` setting to be `a b c d`. +Unknown option names are not an error, and are simply ignored with a warning. + ## Command line flags -Every configuration setting has a corresponding command line flag (e.g. `--max-jobs 16`). -Boolean settings do not need an argument, and can be explicitly disabled with the `no-` prefix (e.g. `--keep-failed` and `--no-keep-failed`). +Configuration options can be set on the command line, overriding the values set in the [configuration file](#configuration-file): -Existing settings can be appended to using the `extra-` prefix (e.g. `--extra-substituters`). +- Every configuration setting has corresponding command line flag (e.g. `--max-jobs 16`). + Boolean settings do not need an argument, and can be explicitly disabled with the `no-` prefix (e.g. `--keep-failed` and `--no-keep-failed`). + + Unknown option names are invalid flags (unless there is already a flag with that name), and are rejected with an error. + +- The flag `--option ` is interpreted exactly like a ` = ` in a setting file. + + Unknown option names are ignored with a warning. + +The `extra-` prefix is supported for settings that take a list of items (e.g. `--extra-trusted users alice` or `--option extra-trusted-users alice`). # Available settings