From b50a039304e97bd6bb056ab8ec91dea57c1cee1c Mon Sep 17 00:00:00 2001 From: Danila Danko Date: Mon, 8 Jan 2024 03:02:47 +0300 Subject: [PATCH 1/4] fix: increase toc width --- docs/theme/pagetoc.css | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/theme/pagetoc.css b/docs/theme/pagetoc.css index 651572ce..3ca69e64 100644 --- a/docs/theme/pagetoc.css +++ b/docs/theme/pagetoc.css @@ -1,5 +1,5 @@ :root { - --toc-width: 270px; + --toc-width: 310px; --center-content-toc-shift: calc(-1 * var(--toc-width) / 2); } @@ -21,26 +21,26 @@ display: flex; } - @media (max-width: 1179px) { + @media (max-width: 1219px) { .sidebar-hidden .sidetoc { display: none; } } - @media (max-width: 1439px) { + @media (max-width: 1499px) { .sidebar-visible .sidetoc { display: none; } } - @media (1180px <= width <= 1439px) { + @media (1220px <= width <= 1519px) { .sidebar-hidden main { position: relative; left: var(--center-content-toc-shift); } } - @media (1440px <= width <= 1700px) { + @media (1500px <= width <= 1820px) { .sidebar-visible main { position: relative; left: var(--center-content-toc-shift); From d0ae5c5a2d83bc8b1cfb5bd57bf9c6f8ffb618a0 Mon Sep 17 00:00:00 2001 From: Danila Danko Date: Sat, 13 Jan 2024 15:44:37 +0300 Subject: [PATCH 2/4] fix: html in description --- extra/services/postgres.nix | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extra/services/postgres.nix b/extra/services/postgres.nix index e54ea8a2..1fb7800a 100644 --- a/extra/services/postgres.nix +++ b/extra/services/postgres.nix @@ -63,7 +63,7 @@ in default = [ "--no-locale" ]; example = [ "--data-checksums" "--allow-group-access" ]; description = '' - Additional arguments passed to initdb during data dir + Additional arguments passed to `initdb` during data dir initialisation. ''; }; From 709136bf00c9ad0bab3e11a741fa1a8aef220c89 Mon Sep 17 00:00:00 2001 From: Danila Danko Date: Sat, 13 Jan 2024 15:51:06 +0300 Subject: [PATCH 3/4] fix: modules docs schema - show values as code instead of JSON - show type before the default value - show type as a block of code, not inline code --- modules/modules-docs.nix | 52 +++++++++++++++++++++------------------- 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/modules/modules-docs.nix b/modules/modules-docs.nix index c44636a1..547b9f77 100644 --- a/modules/modules-docs.nix +++ b/modules/modules-docs.nix @@ -117,60 +117,64 @@ let # TODO: display values like TOML instead. toMarkdown = optionsDocs: let + optionsDocsPartitioned = partition (opt: head opt.loc != "_module") optionsDocs; + # TODO: handle opt.relatedPackages. What is it for? optToMd = opt: + let heading = lib.showOption opt.loc; in '' - ## `${opt.name}` + ### `${heading}` '' + (lib.optionalString opt.internal "\n**internal**\n") - + opt.description + "\n" - + (lib.optionalString (opt ? default && opt.default != null) '' + + opt.description + + '' + **Type**: + + ```console + ${opt.type} + ``` + '' + + (lib.optionalString (opt ? default && opt.default != null) '' + **Default value**: + ```nix - ${ - # When defaultText is set on the module, we only get back a - # string here and defaultText has disappeared. Re-hydrate that - # knowledge by looking at the type. - if builtins.isString opt.default && !(lib.hasPrefix "string" opt.type) then - # If it's a defaultText, assume it's already formatted as nix - # code. - opt.default - else - builtins.toJSON opt.default - } + ${removeSuffix "\n" opt.default.text} ``` - '') - + '' - - **Type**: ${opt.type} - '' + (lib.optionalString (opt ? example) '' **Example value**: + ```nix - ${builtins.toJSON opt.example} + ${removeSuffix "\n" opt.example.text} ``` - '') + '' - Declared in: + **Declared in**: + '' + ( lib.concatStringsSep "\n" (map - (decl: "* [${decl.path}](${decl.url})") + (decl: "- [${decl.path}](${decl.url})") opt.declarations ) ) + "\n" ; + doc = [ + "## Options\n" + (concatStringsSep "\n" (map optToMd optionsDocsPartitioned.right)) + "## Extra options\n" + (concatStringsSep "\n" (map optToMd optionsDocsPartitioned.wrong)) + ]; in - concatStringsSep "\n" (map optToMd optionsDocs); + concatStringsSep "\n" doc; in { options.modules-docs = { From 09549c01a38e8a95233b1671507f848570ad03ca Mon Sep 17 00:00:00 2001 From: Danila Danko Date: Sat, 13 Jan 2024 15:51:15 +0300 Subject: [PATCH 4/4] chore: update docs --- docs/src/modules_schema.md | 1241 ++++++++++++++++++++++-------------- 1 file changed, 777 insertions(+), 464 deletions(-) diff --git a/docs/src/modules_schema.md b/docs/src/modules_schema.md index 245d7d6b..8b9054d3 100644 --- a/docs/src/modules_schema.md +++ b/docs/src/modules_schema.md @@ -1,112 +1,85 @@ -## `_module.args` +## Options -Additional arguments passed to each module in addition to ones -like `lib`, `config`, -and `pkgs`, `modulesPath`. - -This option is also available to all submodules. Submodules do not -inherit args from their parent module, nor do they provide args to -their parent module or sibling submodules. The sole exception to -this is the argument `name` which is provided by -parent modules to a submodule and contains the attribute name -the submodule is bound to, or a unique generated name if it is -not bound to an attribute. - -Some arguments are already passed by default, of which the -following *cannot* be changed with this option: -- {var}`lib`: The nixpkgs library. -- {var}`config`: The results of all options after merging the values from all modules together. -- {var}`options`: The options declared in all modules. -- {var}`specialArgs`: The `specialArgs` argument passed to `evalModules`. -- All attributes of {var}`specialArgs` - - Whereas option values can generally depend on other option values - thanks to laziness, this does not apply to `imports`, which - must be computed statically before anything else. - - For this reason, callers of the module system can provide `specialArgs` - which are available during import resolution. - - For NixOS, `specialArgs` includes - {var}`modulesPath`, which allows you to import - extra modules from the nixpkgs package tree without having to - somehow make the module aware of the location of the - `nixpkgs` or NixOS directories. - ``` - { modulesPath, ... }: { - imports = [ - (modulesPath + "/profiles/minimal.nix") - ]; - } - ``` - -For NixOS, the default value for this option includes at least this argument: -- {var}`pkgs`: The nixpkgs package set according to - the {option}`nixpkgs.pkgs` option. - - -**Type**: lazy attribute set of raw value - -Declared in: -* [lib/modules.nix]() - -## `commands` +### `commands` Add commands to the environment. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"[ ]"} +```console +list of (submodule) ``` +**Default value**: -**Type**: list of (submodule) +```nix +[ ] +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"[\n {\n help = \"print hello\";\n name = \"hello\";\n command = \"echo hello\";\n }\n\n {\n package = \"nixpkgs-fmt\";\n category = \"formatter\";\n }\n]\n"} +[ + { + help = "print hello"; + name = "hello"; + command = "echo hello"; + } + + { + package = "nixpkgs-fmt"; + category = "formatter"; + } +] ``` +**Declared in**: -Declared in: -* [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) +- [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) -## `commands.*.package` +### `commands.*.package` Used to bring in a specific package. This package will be added to the environment. +**Type**: + +```console +null or (package or string convertible to it) +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"null"} +null ``` +**Declared in**: -**Type**: null or (package or string convertible to it) +- [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) -Declared in: -* [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) - -## `commands.*.category` +### `commands.*.category` Set a free text category under which this command is grouped and shown in the help menu. +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"[general commands]\""} +"[general commands]" ``` +**Declared in**: -**Type**: string - -Declared in: -* [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) +- [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) -## `commands.*.command` +### `commands.*.command` If defined, it will add a script with the name of the command, and the content of this value. @@ -114,156 +87,195 @@ content of this value. By default it generates a bash script, unless a different shebang is provided. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"null"} +```console +null or string ``` +**Default value**: -**Type**: null or string +```nix +null +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"''\n #!/usr/bin/env python\n print(\"Hello\")\n''"} +'' + #!/usr/bin/env python + print("Hello") +'' ``` +**Declared in**: -Declared in: -* [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) +- [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) -## `commands.*.help` +### `commands.*.help` Describes what the command does in one line of text. +**Type**: + +```console +null or string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"null"} +null ``` +**Declared in**: -**Type**: null or string - -Declared in: -* [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) +- [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) -## `commands.*.name` +### `commands.*.name` Name of this command. Defaults to attribute name in commands. +**Type**: + +```console +null or string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"null"} +null ``` +**Declared in**: -**Type**: null or string +- [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) -Declared in: -* [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix) - -## `devshell.packages` +### `devshell.packages` The set of packages to appear in the project environment. Those packages come from and can be searched by going to +**Type**: + +```console +list of (package or string convertible to it) +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"[ ]"} +[ ] ``` +**Declared in**: -**Type**: list of (package or string convertible to it) - -Declared in: -* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) +- [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) -## `devshell.packagesFrom` +### `devshell.packagesFrom` Add all the build dependencies from the listed packages to the environment. +**Type**: + +```console +list of (package or string convertible to it) +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"[ ]"} +[ ] ``` +**Declared in**: -**Type**: list of (package or string convertible to it) - -Declared in: -* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) +- [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) -## `devshell.interactive..deps` +### `devshell.interactive..deps` A list of other steps that this one depends on. +**Type**: + +```console +list of string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"[ ]"} +[ ] ``` +**Declared in**: -**Type**: list of string +- [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) -Declared in: -* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) - -## `devshell.interactive..text` +### `devshell.interactive..text` Script to run. +**Type**: + +```console +string +``` -**Type**: string +**Declared in**: -Declared in: -* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) +- [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) -## `devshell.load_profiles` +### `devshell.load_profiles` Whether to enable load etc/profiles.d/*.sh in the shell. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"false"} +```console +boolean ``` +**Default value**: -**Type**: boolean +```nix +false +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"true"} +true ``` +**Declared in**: -Declared in: -* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) +- [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) -## `devshell.meta` +### `devshell.meta` Metadata, such as 'meta.description'. Can be useful as metadata for downstream tooling. +**Type**: + +```console +attribute set of anything +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"{ }"} +{ } ``` +**Declared in**: -**Type**: attribute set of anything - -Declared in: -* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) +- [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) -## `devshell.motd` +### `devshell.motd` Message Of The Day. @@ -272,35 +284,46 @@ the shell. You may use any valid ansi color from the 8-bit ansi color table. For example, to use a green color you would use something like {106}. You may also use {bold}, {italic}, {underline}. Use {reset} to turn off all attributes. +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"''\n {202}🔨 Welcome to devshell{reset}\n $(type -p menu &>/dev/null && menu)\n''"} +'' + {202}🔨 Welcome to devshell{reset} + $(type -p menu &>/dev/null && menu) +'' ``` +**Declared in**: -**Type**: string +- [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) -Declared in: -* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) - -## `devshell.name` +### `devshell.name` Name of the shell environment. It usually maps to the project name. +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"devshell\""} +"devshell" ``` +**Declared in**: -**Type**: string - -Declared in: -* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) +- [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) -## `devshell.prj_root_fallback` +### `devshell.prj_root_fallback` If IN_NIX_SHELL is nonempty, or DIRENV_IN_ENVRC is set to '1', then PRJ_ROOT is set to the value of PWD. @@ -316,846 +339,1136 @@ Otherwise, you can set this to a string representing the desired default path, or to a submodule of the same type valid in the 'env' options list (except that the 'name' field is ignored). +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"{\n eval = \"$PWD\";\n}"} +```console +null or ((submodule) or non-empty string convertible to it) ``` +**Default value**: -**Type**: null or ((submodule) or non-empty string convertible to it) +```nix +{ + eval = "$PWD"; +} +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"{\n # Use the top-level directory of the working tree\n eval = \"$(git rev-parse --show-toplevel)\";\n};\n"} +{ + # Use the top-level directory of the working tree + eval = "$(git rev-parse --show-toplevel)"; +}; ``` +**Declared in**: -Declared in: -* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) +- [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) -## `devshell.prj_root_fallback.eval` +### `devshell.prj_root_fallback.eval` Like value but not evaluated by Bash. This allows to inject other variable names or even commands using the `$()` notation. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"null"} +```console +null or string ``` +**Default value**: -**Type**: null or string +```nix +null +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"\"$OTHER_VAR\""} +"$OTHER_VAR" ``` +**Declared in**: -Declared in: -* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) +- [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) -## `devshell.prj_root_fallback.name` +### `devshell.prj_root_fallback.name` Name of the environment variable +**Type**: -**Type**: string +```console +string +``` -Declared in: -* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) +**Declared in**: -## `devshell.prj_root_fallback.prefix` +- [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) + +### `devshell.prj_root_fallback.prefix` Prepend to PATH-like environment variables. For example name = "PATH"; prefix = "bin"; will expand the path of ./bin and prepend it to the PATH, separated by ':'. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"null"} +```console +null or string ``` +**Default value**: -**Type**: null or string +```nix +null +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"\"bin\""} +"bin" ``` +**Declared in**: -Declared in: -* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) +- [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) -## `devshell.prj_root_fallback.unset` +### `devshell.prj_root_fallback.unset` Whether to enable unsets the variable. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"false"} +```console +boolean ``` +**Default value**: -**Type**: boolean +```nix +false +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"true"} +true ``` +**Declared in**: -Declared in: -* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) +- [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) -## `devshell.prj_root_fallback.value` +### `devshell.prj_root_fallback.value` Shell-escaped value to set +**Type**: + +```console +null or string or signed integer or boolean or package +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"null"} +null ``` +**Declared in**: -**Type**: null or string or signed integer or boolean or package - -Declared in: -* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) +- [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) -## `devshell.startup..deps` +### `devshell.startup..deps` A list of other steps that this one depends on. +**Type**: + +```console +list of string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"[ ]"} +[ ] ``` +**Declared in**: -**Type**: list of string - -Declared in: -* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) +- [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) -## `devshell.startup..text` +### `devshell.startup..text` Script to run. +**Type**: -**Type**: string +```console +string +``` + +**Declared in**: -Declared in: -* [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) +- [modules/devshell.nix](https://github.com/numtide/devshell/tree/main/modules/devshell.nix) -## `env` +### `env` Add environment variables to the shell. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"[ ]"} +```console +list of (submodule) ``` +**Default value**: -**Type**: list of (submodule) +```nix +[ ] +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"[\n {\n name = \"HTTP_PORT\";\n value = 8080;\n }\n {\n name = \"PATH\";\n prefix = \"bin\";\n }\n {\n name = \"XDG_CACHE_DIR\";\n eval = \"$PRJ_ROOT/.cache\";\n }\n {\n name = \"CARGO_HOME\";\n unset = true;\n }\n]\n"} +[ + { + name = "HTTP_PORT"; + value = 8080; + } + { + name = "PATH"; + prefix = "bin"; + } + { + name = "XDG_CACHE_DIR"; + eval = "$PRJ_ROOT/.cache"; + } + { + name = "CARGO_HOME"; + unset = true; + } +] ``` +**Declared in**: -Declared in: -* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) +- [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) -## `env.*.eval` +### `env.*.eval` Like value but not evaluated by Bash. This allows to inject other variable names or even commands using the `$()` notation. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"null"} +```console +null or string ``` +**Default value**: -**Type**: null or string +```nix +null +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"\"$OTHER_VAR\""} +"$OTHER_VAR" ``` +**Declared in**: -Declared in: -* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) +- [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) -## `env.*.name` +### `env.*.name` Name of the environment variable +**Type**: -**Type**: string +```console +string +``` + +**Declared in**: -Declared in: -* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) +- [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) -## `env.*.prefix` +### `env.*.prefix` Prepend to PATH-like environment variables. For example name = "PATH"; prefix = "bin"; will expand the path of ./bin and prepend it to the PATH, separated by ':'. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"null"} +```console +null or string ``` +**Default value**: -**Type**: null or string +```nix +null +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"\"bin\""} +"bin" ``` +**Declared in**: -Declared in: -* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) +- [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) -## `env.*.unset` +### `env.*.unset` Whether to enable unsets the variable. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"false"} +```console +boolean ``` +**Default value**: -**Type**: boolean +```nix +false +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"true"} +true ``` +**Declared in**: -Declared in: -* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) +- [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) -## `env.*.value` +### `env.*.value` Shell-escaped value to set +**Type**: + +```console +null or string or signed integer or boolean or package +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"null"} +null ``` +**Declared in**: -**Type**: null or string or signed integer or boolean or package - -Declared in: -* [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) +- [modules/env.nix](https://github.com/numtide/devshell/tree/main/modules/env.nix) -## `extra.locale.package` +### `extra.locale.package` Set the glibc locale package that will be used on Linux +**Type**: + +```console +package +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"pkgs.glibcLocales\""} +"pkgs.glibcLocales" ``` +**Declared in**: -**Type**: package +- [extra/locale.nix](https://github.com/numtide/devshell/tree/main/extra/locale.nix) -Declared in: -* [extra/locale.nix](https://github.com/numtide/devshell/tree/main/extra/locale.nix) - -## `extra.locale.lang` +### `extra.locale.lang` Set the language of the project +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"null"} +```console +null or string ``` +**Default value**: -**Type**: null or string +```nix +null +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"\"en_GB.UTF-8\""} +"en_GB.UTF-8" ``` +**Declared in**: -Declared in: -* [extra/locale.nix](https://github.com/numtide/devshell/tree/main/extra/locale.nix) +- [extra/locale.nix](https://github.com/numtide/devshell/tree/main/extra/locale.nix) -## `git.hooks.enable` +### `git.hooks.enable` Whether to enable install .git/hooks on shell entry. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"false"} +```console +boolean ``` +**Default value**: -**Type**: boolean +```nix +false +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"true"} +true ``` +**Declared in**: -Declared in: -* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) +- [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) -## `git.hooks.applypatch-msg.text` +### `git.hooks.applypatch-msg.text` Text of the script to install +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"\""} +"" ``` +**Declared in**: -**Type**: string +- [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) -Declared in: -* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) - -## `git.hooks.commit-msg.text` +### `git.hooks.commit-msg.text` Text of the script to install +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"\""} +"" ``` +**Declared in**: -**Type**: string - -Declared in: -* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) +- [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) -## `git.hooks.fsmonitor-watchman.text` +### `git.hooks.fsmonitor-watchman.text` Text of the script to install +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"\""} +"" ``` +**Declared in**: -**Type**: string - -Declared in: -* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) +- [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) -## `git.hooks.post-update.text` +### `git.hooks.post-update.text` Text of the script to install +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"\""} +"" ``` +**Declared in**: -**Type**: string +- [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) -Declared in: -* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) - -## `git.hooks.pre-applypatch.text` +### `git.hooks.pre-applypatch.text` Text of the script to install +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"\""} +"" ``` +**Declared in**: -**Type**: string - -Declared in: -* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) +- [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) -## `git.hooks.pre-commit.text` +### `git.hooks.pre-commit.text` Text of the script to install +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"\""} +"" ``` +**Declared in**: -**Type**: string - -Declared in: -* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) +- [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) -## `git.hooks.pre-merge-commit.text` +### `git.hooks.pre-merge-commit.text` Text of the script to install +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"\""} +"" ``` +**Declared in**: -**Type**: string +- [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) -Declared in: -* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) - -## `git.hooks.pre-push.text` +### `git.hooks.pre-push.text` Text of the script to install +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"\""} +"" ``` +**Declared in**: -**Type**: string - -Declared in: -* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) +- [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) -## `git.hooks.pre-rebase.text` +### `git.hooks.pre-rebase.text` Text of the script to install +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"\""} +"" ``` +**Declared in**: -**Type**: string - -Declared in: -* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) +- [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) -## `git.hooks.prepare-commit-msg.text` +### `git.hooks.prepare-commit-msg.text` Text of the script to install +**Type**: + +```console +string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"\""} +"" ``` +**Declared in**: -**Type**: string +- [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) -Declared in: -* [extra/git/hooks.nix](https://github.com/numtide/devshell/tree/main/extra/git/hooks.nix) - -## `language.c.compiler` +### `language.c.compiler` Which C compiler to use +**Type**: + +```console +package or string convertible to it +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"pkgs.clang\""} +"pkgs.clang" ``` +**Declared in**: -**Type**: package or string convertible to it - -Declared in: -* [extra/language/c.nix](https://github.com/numtide/devshell/tree/main/extra/language/c.nix) +- [extra/language/c.nix](https://github.com/numtide/devshell/tree/main/extra/language/c.nix) -## `language.c.includes` +### `language.c.includes` C dependencies from nixpkgs +**Type**: + +```console +list of (package or string convertible to it) +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"[ ]"} +[ ] ``` +**Declared in**: -**Type**: list of (package or string convertible to it) - -Declared in: -* [extra/language/c.nix](https://github.com/numtide/devshell/tree/main/extra/language/c.nix) +- [extra/language/c.nix](https://github.com/numtide/devshell/tree/main/extra/language/c.nix) -## `language.c.libraries` +### `language.c.libraries` Use this when another language dependens on a dynamic library +**Type**: + +```console +list of (package or string convertible to it) +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"[ ]"} +[ ] ``` +**Declared in**: -**Type**: list of (package or string convertible to it) +- [extra/language/c.nix](https://github.com/numtide/devshell/tree/main/extra/language/c.nix) -Declared in: -* [extra/language/c.nix](https://github.com/numtide/devshell/tree/main/extra/language/c.nix) - -## `language.go.package` +### `language.go.package` Which go package to use +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":""} +```console +package or string convertible to it ``` +**Default value**: -**Type**: package or string convertible to it +```nix + +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"pkgs.go"} +pkgs.go ``` +**Declared in**: -Declared in: -* [extra/language/go.nix](https://github.com/numtide/devshell/tree/main/extra/language/go.nix) +- [extra/language/go.nix](https://github.com/numtide/devshell/tree/main/extra/language/go.nix) -## `language.go.GO111MODULE` +### `language.go.GO111MODULE` Enable Go modules +**Type**: + +```console +one of "on", "off", "auto" +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"on\""} +"on" ``` +**Declared in**: -**Type**: one of "on", "off", "auto" - -Declared in: -* [extra/language/go.nix](https://github.com/numtide/devshell/tree/main/extra/language/go.nix) +- [extra/language/go.nix](https://github.com/numtide/devshell/tree/main/extra/language/go.nix) -## `language.perl.package` +### `language.perl.package` Which Perl package to use +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":""} +```console +package or string convertible to it ``` +**Default value**: -**Type**: package or string convertible to it +```nix + +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"pkgs.perl538"} +pkgs.perl538 ``` +**Declared in**: -Declared in: -* [extra/language/perl.nix](https://github.com/numtide/devshell/tree/main/extra/language/perl.nix) +- [extra/language/perl.nix](https://github.com/numtide/devshell/tree/main/extra/language/perl.nix) -## `language.perl.extraPackages` +### `language.perl.extraPackages` List of extra packages (coming from perl5XXPackages) to add +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"[ ]"} +```console +list of (package or string convertible to it) ``` +**Default value**: -**Type**: list of (package or string convertible to it) +```nix +[ ] +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"[ perl538Packages.FileNext ]"} +[ perl538Packages.FileNext ] ``` +**Declared in**: -Declared in: -* [extra/language/perl.nix](https://github.com/numtide/devshell/tree/main/extra/language/perl.nix) +- [extra/language/perl.nix](https://github.com/numtide/devshell/tree/main/extra/language/perl.nix) -## `language.perl.libraryPaths` +### `language.perl.libraryPaths` List of paths to add to PERL5LIB +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"[ ]"} +```console +list of string ``` +**Default value**: -**Type**: list of string +```nix +[ ] +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"[ ./lib ]"} +[ ./lib ] ``` +**Declared in**: -Declared in: -* [extra/language/perl.nix](https://github.com/numtide/devshell/tree/main/extra/language/perl.nix) +- [extra/language/perl.nix](https://github.com/numtide/devshell/tree/main/extra/language/perl.nix) -## `language.ruby.package` +### `language.ruby.package` Ruby version used by your project +**Type**: + +```console +package or string convertible to it +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"pkgs.ruby_3_2\""} +"pkgs.ruby_3_2" ``` +**Declared in**: -**Type**: package or string convertible to it - -Declared in: -* [extra/language/ruby.nix](https://github.com/numtide/devshell/tree/main/extra/language/ruby.nix) +- [extra/language/ruby.nix](https://github.com/numtide/devshell/tree/main/extra/language/ruby.nix) -## `language.ruby.nativeDeps` +### `language.ruby.nativeDeps` Use this when your gems depend on a dynamic library +**Type**: + +```console +list of (package or string convertible to it) +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"[ ]"} +[ ] ``` +**Declared in**: -**Type**: list of (package or string convertible to it) +- [extra/language/ruby.nix](https://github.com/numtide/devshell/tree/main/extra/language/ruby.nix) -Declared in: -* [extra/language/ruby.nix](https://github.com/numtide/devshell/tree/main/extra/language/ruby.nix) - -## `language.rust.enableDefaultToolchain` +### `language.rust.enableDefaultToolchain` Enable the default rust toolchain coming from nixpkgs +**Type**: + +```console +boolean +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"true\""} +"true" ``` +**Declared in**: -**Type**: boolean - -Declared in: -* [extra/language/rust.nix](https://github.com/numtide/devshell/tree/main/extra/language/rust.nix) +- [extra/language/rust.nix](https://github.com/numtide/devshell/tree/main/extra/language/rust.nix) -## `language.rust.packageSet` +### `language.rust.packageSet` Which rust package set to use +**Type**: + +```console +attribute set +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"pkgs.rustPlatform\""} +"pkgs.rustPlatform" ``` +**Declared in**: -**Type**: attribute set - -Declared in: -* [extra/language/rust.nix](https://github.com/numtide/devshell/tree/main/extra/language/rust.nix) +- [extra/language/rust.nix](https://github.com/numtide/devshell/tree/main/extra/language/rust.nix) -## `language.rust.tools` +### `language.rust.tools` Which rust tools to pull from the platform package set +**Type**: + +```console +list of string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"[\n \"rustc\"\n \"cargo\"\n \"clippy\"\n \"rustfmt\"\n]"} +[ + "rustc" + "cargo" + "clippy" + "rustfmt" +] ``` +**Declared in**: -**Type**: list of string - -Declared in: -* [extra/language/rust.nix](https://github.com/numtide/devshell/tree/main/extra/language/rust.nix) +- [extra/language/rust.nix](https://github.com/numtide/devshell/tree/main/extra/language/rust.nix) -## `serviceGroups` +### `serviceGroups` Add services to the environment. Services can be used to group long-running processes. +**Type**: + +```console +attribute set of (submodule) +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"{ }"} +{ } ``` +**Declared in**: -**Type**: attribute set of (submodule) +- [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) -Declared in: -* [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) - -## `serviceGroups..description` +### `serviceGroups..description` Short description of the service group, shown in generated commands +**Type**: + +```console +null or string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"null"} +null ``` +**Declared in**: -**Type**: null or string - -Declared in: -* [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) +- [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) -## `serviceGroups..name` +### `serviceGroups..name` Name of the service group. Defaults to attribute name in groups. +**Type**: + +```console +null or string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"null"} +null ``` +**Declared in**: -**Type**: null or string - -Declared in: -* [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) +- [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) -## `serviceGroups..services` +### `serviceGroups..services` Attrset of services that should be run in this group. +**Type**: + +```console +attribute set of (submodule) +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"{ }"} +{ } ``` +**Declared in**: -**Type**: attribute set of (submodule) +- [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) -Declared in: -* [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) - -## `serviceGroups..services..command` +### `serviceGroups..services..command` Command to execute. +**Type**: + +```console +string +``` -**Type**: string +**Declared in**: -Declared in: -* [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) +- [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) -## `serviceGroups..services..name` +### `serviceGroups..services..name` Name of this service. Defaults to attribute name in group services. +**Type**: + +```console +null or string +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"null"} +null ``` +**Declared in**: -**Type**: null or string +- [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) -Declared in: -* [modules/services.nix](https://github.com/numtide/devshell/tree/main/modules/services.nix) - -## `services.postgres.package` +### `services.postgres.package` Which version of postgres to use +**Type**: + +```console +package or string convertible to it +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"\"pkgs.postgresql\""} +"pkgs.postgresql" ``` +**Declared in**: -**Type**: package or string convertible to it - -Declared in: -* [extra/services/postgres.nix](https://github.com/numtide/devshell/tree/main/extra/services/postgres.nix) +- [extra/services/postgres.nix](https://github.com/numtide/devshell/tree/main/extra/services/postgres.nix) -## `services.postgres.createUserDB` +### `services.postgres.createUserDB` Create a database named like current user on startup. This option only makes sense when `setupPostgresOnStartup` is true. +**Type**: + +```console +boolean +``` **Default value**: + ```nix -{"_type":"literalExpression","text":"true"} +true ``` +**Declared in**: -**Type**: boolean - -Declared in: -* [extra/services/postgres.nix](https://github.com/numtide/devshell/tree/main/extra/services/postgres.nix) +- [extra/services/postgres.nix](https://github.com/numtide/devshell/tree/main/extra/services/postgres.nix) -## `services.postgres.initdbArgs` +### `services.postgres.initdbArgs` -Additional arguments passed to initdb during data dir +Additional arguments passed to `initdb` during data dir initialisation. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"[\n \"--no-locale\"\n]"} +```console +list of string ``` +**Default value**: -**Type**: list of string +```nix +[ + "--no-locale" +] +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"[\n \"--data-checksums\"\n \"--allow-group-access\"\n]"} +[ + "--data-checksums" + "--allow-group-access" +] ``` +**Declared in**: -Declared in: -* [extra/services/postgres.nix](https://github.com/numtide/devshell/tree/main/extra/services/postgres.nix) +- [extra/services/postgres.nix](https://github.com/numtide/devshell/tree/main/extra/services/postgres.nix) -## `services.postgres.setupPostgresOnStartup` +### `services.postgres.setupPostgresOnStartup` Whether to enable call setup-postgres on startup. +**Type**: -**Default value**: -```nix -{"_type":"literalExpression","text":"false"} +```console +boolean ``` +**Default value**: -**Type**: boolean +```nix +false +``` **Example value**: + ```nix -{"_type":"literalExpression","text":"true"} +true +``` + +**Declared in**: + +- [extra/services/postgres.nix](https://github.com/numtide/devshell/tree/main/extra/services/postgres.nix) + +## Extra options + +### `_module.args` + +Additional arguments passed to each module in addition to ones +like `lib`, `config`, +and `pkgs`, `modulesPath`. + +This option is also available to all submodules. Submodules do not +inherit args from their parent module, nor do they provide args to +their parent module or sibling submodules. The sole exception to +this is the argument `name` which is provided by +parent modules to a submodule and contains the attribute name +the submodule is bound to, or a unique generated name if it is +not bound to an attribute. + +Some arguments are already passed by default, of which the +following *cannot* be changed with this option: +- {var}`lib`: The nixpkgs library. +- {var}`config`: The results of all options after merging the values from all modules together. +- {var}`options`: The options declared in all modules. +- {var}`specialArgs`: The `specialArgs` argument passed to `evalModules`. +- All attributes of {var}`specialArgs` + + Whereas option values can generally depend on other option values + thanks to laziness, this does not apply to `imports`, which + must be computed statically before anything else. + + For this reason, callers of the module system can provide `specialArgs` + which are available during import resolution. + + For NixOS, `specialArgs` includes + {var}`modulesPath`, which allows you to import + extra modules from the nixpkgs package tree without having to + somehow make the module aware of the location of the + `nixpkgs` or NixOS directories. + ``` + { modulesPath, ... }: { + imports = [ + (modulesPath + "/profiles/minimal.nix") + ]; + } + ``` + +For NixOS, the default value for this option includes at least this argument: +- {var}`pkgs`: The nixpkgs package set according to + the {option}`nixpkgs.pkgs` option. + +**Type**: + +```console +lazy attribute set of raw value ``` +**Declared in**: -Declared in: -* [extra/services/postgres.nix](https://github.com/numtide/devshell/tree/main/extra/services/postgres.nix) +- [lib/modules.nix]()