Commit Graph

64 Commits

Author SHA1 Message Date
Robert Hensing
8919495cac
Merge pull request #156503 from hercules-ci/nixos-add-system.build-options
nixos: Add `system.build.`{`toplevel`,`installBootLoader`}, improve error message
2022-01-25 14:13:24 +01:00
Robert Hensing
8691ab3d47 lib.modules: Define mergeOneOption in terms of mergeUniqueOption 2022-01-24 16:23:18 +01:00
Robert Hensing
ba3e91ed43 lib.types: Add unique like uniq, but custom errors
Couldn't extend types.uniq and it had a silly name anyway.
Now we can have better error messages.
2022-01-24 16:14:55 +01:00
Anselm Schüler
c008b3d100 nixos/docs/option-declarations: Document mkEnableOption and mkPackageOption
This is a squashed commit. These are the original commit messages:

lib/option: Improve comment

better comment

Update documentation

Updated nixos/doc/manual/development/options-declarations.md with info on mkEnableOption and mkPackageOption.
Updated the comment on mkEnableOption in lib/options.nix

remove trailing whitespace

nixos/doc/option-declarations: Update IDs & formatting

nixos/docs/option-declarations: Escape angle brackets

Build DB from MD

(Amended) Fix typo
Co-authored-by: pennae <82953136+pennae@users.noreply.github.com>

(Amended) Build DB from MD (again)
2022-01-23 19:44:21 +01:00
Anselm Schüler
fdf7ede344 lib/options: Add mkPackageOption
This is a squashed commit. These are the original commit messages:

lib/options: Add mkPackageOption

lib/options: Add missing semicolon

lib/options.nix: Make mkPackageOption more complicated

lib/options: Fix indent. & spacing

lib/options.nix: Remove example and align comment

lib/options: ravenous overuse of arguments

lib/options: Format better

lib/options: Add default examplePath decl

lib/options: Make better mkPackageOption function

lib/options: Remove trailing whitespace

lib/options: Improve mkPackageOptions

lib/options: Remove pkgs prefixing
Co-authored-by: pennae <82953136+pennae@users.noreply.github.com>

lib/options: Slim down mkPackageOption further

lib/options: mkPackageOption: Add "pkgs." to example

lib/options: mkPackageOption: Make name & pkgs single arguments

lib/options: mkPackageOption: Swap name & pkgs

lib/options: Remove unnecessary import
Co-authored-by: pennae <82953136+pennae@users.noreply.github.com>
2022-01-23 14:23:03 +01:00
pennae
fc614c37c6 nixos/documentation: split options doc build
most modules can be evaluated for their documentation in a very
restricted environment that doesn't include all of nixpkgs. this
evaluation can then be cached and reused for subsequent builds, merging
only documentation that has changed into the cached set. since nixos
ships with a large number of modules of which only a few are used in any
given config this can save evaluation a huge percentage of nixos
options available in any given config.

in tests of this caching, despite having to copy most of nixos/, saves
about 80% of the time needed to build the system manual, or about two
second on the machine used for testing. build time for a full system
config shrank from 9.4s to 7.4s, while turning documentation off
entirely shortened the build to 7.1s.
2022-01-02 19:46:13 +01:00
Robert Hensing
64dfd983df modules: Add visible = "shallow" to hide only sub-options 2021-11-01 09:34:07 +01:00
Naïm Favier
52a2e4136e
lib/options: add literalExpression and literalDocBook, deprecate literalExample 2021-10-03 17:19:19 +02:00
Maximilian Bosch
5773ae93f7
lib/generators: move limit detection into withRecursion
As suggested in #131205.

Now it's possible to pretty-print a value with `lib.generators` like
this:

    with lib.generators;
    toPretty { }
      (withRecursion { depthLimit = 10; } /* arbitrarily complex value */)

Also, this can be used for any other pretty-printer now if needed.
2021-08-26 00:28:49 +02:00
Maximilian Bosch
fbc9084c39
lib/options: use depthLimit for toPretty when showing a definition
When having a bogus declaration such as

    { lib, ... }:
    {
      foo.bar = mkOption {
        type = types.str;
      };
    }

the evaluation will terminate with a not-so helpful

    error: stack overflow (possible infinite recursion)

To make sure a useful error is still provided, I added a `depthLimit` of
`10` which should be perfectly sufficient to `toPretty` when it's used
in an error-case for `showDefs`.
2021-08-25 23:18:27 +02:00
Silvan Mosberger
998a9c1707 lib/options: Better mergeEqualOption error for uncomparable types
For an option definition that uses `lib.options.mergeEqualOption`
underneath, like `types.anything`, an error is thrown when multiple
functions are assigned, indicating that functions can't be compared for
equivalence:

  error: The option `test' has conflicting definition values:
  - In `xxx': <function>
  - In `xxx': <function>
  (use '--show-trace' to show detailed location information)

However, the error message didn't use the correct files. While above
error indicates that both definitions are in the xxx file, that's in
fact not true. Above error was generated with

  options.test = lib.mkOption {
    type = lib.types.anything;
  };

  imports = [
    {
      _file = "yyy";
      test = y: y;
    }
    {
      _file = "xxx";
      test = x: x;
    }
  ];

With this change, the error uses the correct file locations:

  error: The option `test' has conflicting definition values:
  - In `xxx': <function>
  - In `yyy': <function>
  (use '--show-trace' to show detailed location information)
2021-08-10 19:54:32 +02:00
Silvan Mosberger
9e6737710c Revert "Module-builtin assertions, disabling assertions and submodule assertions" 2020-12-18 16:44:37 +01:00
Silvan Mosberger
0b61ed7af9
lib/options: Don't show internal suboption in the manual
Initially https://github.com/NixOS/nixpkgs/pull/82897 prevented
non-visible options from being rendered in the manual, but
visible-but-internal options were still being recursed into. This fixes
this, aligning the recurse condition here with the one in
make-options-doc/default.nix
2020-11-30 22:51:34 +01:00
Robert Hensing
c9f8f66248 lib/options.nix: Use merge-friendly inherit syntax 2020-10-22 13:46:48 +02:00
Robert Hensing
afa6c51f27 lib: Use Nix's static scope checking, fix error message, optimize
Nix can perform static scope checking, but whenever code is inside
a `with` expression, the analysis breaks down, because it can't
know statically what's in the attribute set whose attributes were
brought into scope. In those cases, Nix has to assume that
everything works out.

Except it doesnt. Removing `with` from lib/ revealed an undefined
variable in an error message.

If that doesn't convince you that we're better off without `with`,
I can tell you that this PR results in a 3% evaluation performance
improvement because Nix can look up local variables by index.
This adds up with applications like the module system.

Furthermore, removing `with` makes the binding site of each
variable obvious, which helps with comprehension.
2020-10-22 13:46:47 +02:00
Robert Hensing
4d4682c2b6 lib/options.nix: Use head instead of elemAt _ 0 2020-10-22 13:46:47 +02:00
Silvan Mosberger
bdfcee2590
lib/modules: Improve error messages using showDefs 2020-09-21 18:24:52 +02:00
Silvan Mosberger
7c20e68f6b
lib/options: Introduce showDefs
For pretty-printing definitions, including file and values
2020-09-21 18:24:50 +02:00
Silvan Mosberger
6e7bc2c6c9
lib/options: Fix mergeEqualOption for singular functions
Previously it would error out for a single function definition
2020-09-15 21:01:07 +02:00
Daiderd Jordan
964700da44
lib/options: fix showOption example 2020-04-14 20:38:31 +02:00
Daiderd Jordan
31a03daa72
Revert "lib/options: Use escapeNixIdentifier for showOption"
This is used in in the manual generation for option identifiers that can
be linked. This, unike what the example describes, doesn't preserve
quotes which is needed for these identifiers to be valid.

This reverts commit 124cccbe3b.
2020-04-14 20:34:07 +02:00
Jan Tojnar
c652b64a26
lib/options: Relax showOption quoting
124cccbe3b
broke the build of NixOS manual.

It does not make sense to be as strict as with attributes since we
are not limited by the CLI's inability to handle numbers.
Placeholders should not be quoted either as they are not part of Nix
syntax but a meta-level construct.
2020-04-14 04:49:17 +02:00
Silvan Mosberger
124cccbe3b
lib/options: Use escapeNixIdentifier for showOption 2020-04-13 17:27:04 +02:00
Silvan Mosberger
f195625227
lib/options: Only recurse into visible sub options 2020-03-19 01:13:27 +01:00
Jan Tojnar
907529ff06
lib/options: fix path in comment 2019-08-26 02:01:49 +02:00
danbst
bfb6ef1d59 module system: prettify a bit error when unique option defined twice
The error can be reproduced like:
```
$ nix-instantiate ./nixos -A system --arg configuration '
  { fileSystems."/".device = "nodev";
    boot.loader.grub.devices = [ "nodev" ];
    containers.t.config.imports = [ <nixpkgs/nixos/modules/virtualisation/amazon-image.nix> ];
  }'
```

Previously error was:
```
error: The unique option `containers.t.networking.hostName' is defined multiple times, in `/nix/var/nix/profiles/per-user/root/channels/nixpkgs/nixos/modules/virtualisation/amazon-image.nix' and `module at /home/danbst/dev/nixpkgs/nixos/modules/virtualisation/containers.nix:470'.
(use '--show-trace' to show detailed location information)
```

Now it is:
```
error: The unique option `containers.t.networking.hostName' is defined multiple times, in:
 - /nix/var/nix/profiles/per-user/root/channels/nixpkgs/nixos/modules/virtualisation/amazon-image.nix
 - module at /home/danbst/dev/nixpkgs/nixos/modules/virtualisation/containers.nix:470.
(use '--show-trace' to show detailed location information)
```

Related: https://github.com/NixOS/nixpkgs/issues/15747
2019-06-05 03:10:57 +03:00
Danylo Hlynskyi
60e8fcf0e5
module system: revert "remove types.optionSet", just deprecate (#56857)
The explicit remove helped to uncover some hidden uses of `optionSet`
in NixOps. However it makes life harder for end-users of NixOps - it will
be impossible to deploy 19.03 systems with old NixOps, but there is no
new release of NixOps with `optionSet` fixes.

Also, "deprecation" process isn't well defined. Even that `optionSet` was
declared "deprecated" for many years, it was never announced. Hence, I
leave "deprecation" announce. Then, 3 releases after announce,
we can announce removal of this feature.

This type has to be removed, not `throw`-ed in runtime, because it makes
some perfectly fine code to fail. For example:
```
$ nix-instantiate --eval -E '(import <nixpkgs/lib>).types' --strict
trace: `types.list` is deprecated; use `types.listOf` instead
error: types.optionSet is deprecated; use types.submodule instead
(use '--show-trace' to show detailed location information)
```
2019-03-07 21:28:09 +02:00
Jan Malakhovski
a53b3ba091 lib: optionAttrSetToDocList: warn instead of throwing on options without descriptions
For convenience, it's not like not having a description is deadly or something.
2019-03-05 09:41:41 +00:00
danbst
27982b408e types.optionSet: deprecate and remove last usages 2019-01-31 00:41:10 +02:00
Vincent Ambo
2384966880 lib/options: Update documentation comments for docs generation
Documents functions in `lib.options` for docs generation with nixdoc.

The formatting change in the `mkOption` arguments is due to the way
`nixdoc` parses documentation comments on pattern arguments. It's not
ideal, but it works.
2018-10-29 10:45:28 +01:00
Tobias Pflug
d5166027e2 docs: lib/options.nix function documentation 2018-10-02 22:05:57 +02:00
Graham Christensen
059a71a611
lib/options: teach showOptions about funny option names
Handle the case where options have funny symbols inside of them.

Example:

If I reference the following attribute without it being defined:

  security.acme.certs."example.com".webroot

I now get the error:

    The option `security.acme.certs."example.com".webroot' is used but
    not defined.

where before I got:

    The option `security.acme.certs.example.com.webroot' is used but
    not defined.

which is not true.
2018-03-05 09:58:06 -05:00
Jan Malakhovski
a3a8c1f54d lib: export option location in optionAttrSetToDocList 2018-02-11 22:04:09 +00:00
Jan Malakhovski
660806066a nixos, lib: implement relatedPackages option
This allows one to specify "related packages" in NixOS that get rendered into
the configuration.nix(5) man page. The interface philosophy is pretty much
stolen from TeX bibliography.

See the next several commits for examples.
2018-02-09 19:51:06 +00:00
Graham Christensen
b5a61f2c59
Revert "nixos: doc: implement related packages in the manual" 2017-12-23 07:19:45 -05:00
Jan Malakhovski
67ec6371d5 nixos, lib: implement relatedPackages option
This allows one to specify "related packages" in NixOS that get rendered into
the configuration.nix(5) man page. The interface philosophy is pretty much
stolen from TeX bibliography.
2017-12-07 21:26:35 +00:00
Graham Christensen
152c63c9ff
Convert libs to a fixed-point
This does break the API of being able to import any lib file and get
its libs, however I'm not sure people did this.

I made this while exploring being able to swap out docFn with a stub
in #2305, to avoid functor performance problems. I don't know if that
is going to move forward (or if it is a problem or not,) but after
doing all this work figured I'd put it up anyway :)

Two notable advantages to this approach:

1. when a lib inherits another lib's functions, it doesn't
   automatically get put in to the scope of lib
2. when a lib implements a new obscure functions, it doesn't
   automatically get put in to the scope of lib

Using the test script (later in this commit) I got the following diff
on the API:

  + diff master fixed-lib
  11764a11765,11766
  > .types.defaultFunctor
  > .types.defaultTypeMerge
  11774a11777,11778
  > .types.isOptionType
  > .types.isType
  11781a11786
  > .types.mkOptionType
  11788a11794
  > .types.setType
  11795a11802
  > .types.types

This means that this commit _adds_ to the API, however I can't find a
way to fix these last remaining discrepancies. At least none are
_removed_.

Test script (run with nix-repl in the PATH):

  #!/bin/sh

  set -eux

  repl() {
      suff=${1:-}
      echo "(import ./lib)$suff" \
          | nix-repl 2>&1
  }

  attrs_to_check() {
      repl "${1:-}" \
          | tr ';'  $'\n' \
          | grep "\.\.\." \
          | cut -d' ' -f2 \
          | sed -e "s/^/${1:-}./" \
          | sort
  }

  summ() {
      repl "${1:-}" \
          | tr ' ' $'\n' \
          | sort \
          | uniq
  }

  deep_summ() {
      suff="${1:-}"
      depth="${2:-4}"
      depth=$((depth - 1))
      summ "$suff"

      for attr in $(attrs_to_check "$suff" | grep -v "types.types"); do
          if [ $depth -eq 0 ]; then
              summ "$attr" | sed -e "s/^/$attr./"
          else
              deep_summ "$attr" "$depth" | sed -e "s/^/$attr./"
          fi
      done
  }

  (
      cd nixpkgs

      #git add .
      #git commit -m "Auto-commit, sorry" || true
      git checkout fixed-lib
      deep_summ > ../fixed-lib
      git checkout master
      deep_summ > ../master
  )

  if diff master fixed-lib; then
      echo "SHALLOW MATCH!"
  fi

  (
      cd nixpkgs
      git checkout fixed-lib
      repl .types
  )
2017-09-16 21:36:43 -04:00
Eric Sagnes
e14de56613 module system: extensible option types 2016-11-06 00:05:58 +01:00
Eelco Dolstra
f463d24903 Add read-only options
These are options that can have only one definition, regardless of
priority.
2015-07-30 13:44:50 +02:00
Eelco Dolstra
0ae8b365b3 Rename misc.nix -> deprecated.nix 2015-07-23 18:31:54 +02:00
Eelco Dolstra
637e35deb9 Use foldl' instead of fold in some places 2015-07-23 18:31:54 +02:00
Eelco Dolstra
f14dab05d6 optionAttrSetToDocList: O(n^2) -> O(n)
This shaves about 10% off memory consumption of NixOS evaluation.
2015-07-23 16:49:13 +02:00
Eelco Dolstra
e212e07cf6 Make types.bool complain on conflicting definitions
Previously, conflicting definitions would merge to "true". Now they
give an error, e.g.

  error: The option `hardware.enableAllFirmware' has conflicting definitions, in `/etc/nixos/configurations/misc/eelco/stuff.nix' and `/etc/nixos/configurations/misc/eelco/mandark.nix'.
2015-06-15 18:07:48 +02:00
Eelco Dolstra
a4925bcfa8 Remove obsolete stuff 2015-06-15 18:07:44 +02:00
Domen Kožar
79a51b0cf3 Add Type information into manual and manpages, fixes #4600 2015-01-04 15:41:32 +01:00
Nicolas B. Pierron
2f365923d6 modules: Add mkSinkUndeclaredOptions. 2014-12-21 14:50:46 +01:00
Eelco Dolstra
ce61353a9f Eliminate some optionals/optionalAttrs calls on the hot path 2014-10-05 01:59:24 +02:00
Eelco Dolstra
785eaf2cea Add some primops to lib 2013-11-12 13:48:30 +01:00
Eelco Dolstra
be5d3a59dd Clean up some option examples 2013-10-30 18:47:43 +01:00
Eelco Dolstra
70a2c54527 Strictly check the arguments to mkOption
And fix various instances of bad arguments.
2013-10-30 15:35:09 +01:00