Commit Graph

98 Commits

Author SHA1 Message Date
Silvan Mosberger
055ba65fed lib: Take advantage of section descriptions
See https://github.com/nix-community/nixdoc/releases/tag/v2.6.0
2023-11-20 03:02:11 +01:00
Anselm Schüler
7e24b3619f
lib/options: refactor mkPackageOption 2023-10-10 13:14:17 +02:00
Anselm Schüler
f07537da75
lib/options: add pkgsText parameter to mkPackageOption 2023-10-06 14:08:50 +02:00
Anselm Schüler
19241f5618
lib/options: correct and improve documentation of mkPackageOption 2023-10-06 14:07:06 +02:00
pennae
d36f950d40 lib: turn *MD functions into aliases
with docbook gone and MD the default these aren't needed any more. we
can't remove them yet because there's thousands of uses, but maybe some
day we can.
2023-06-13 16:56:32 +02:00
pennae
7542a1aa8f lib/options: remove literalDocBook
no longer supported. warning when used would not be appropriate, and
docbook has been on the way out for long enough that throwing an error
should not be necessary either.
2023-06-13 16:56:30 +02:00
Naïm Favier
4a56b2655e
lib/options: nullable mkPackageOption
It is sometimes useful to allow setting a package option to `null` to
skip installing the package. See
https://github.com/nix-community/home-manager/pull/3668#issuecomment-1554044171
for example.
2023-05-19 12:22:21 +02:00
Naïm Favier
7cd5b9a6e8
lib/options: fix rendering of options with only a defaultText
Some options have their default value set in the `config` instead of
`default`, for example to push `mkDefault`s down an attribute set.
In those cases, it's useful to provide a `defaultText` for informational
purposes.
2023-05-06 17:09:10 +02:00
pennae
f0e8db002b lib/options: fix mkPackageOption docs
nixdoc takes everything from Type: to Example: as the type, which
misrendered a large part of the docs. it also drops sorely needed spaces
where the type had line breaks, so all has to be on one line (or use
non-standard literal spaces, which is probably worse).

also clarify what the `?` for arguments mean while we're here.
2023-03-05 01:21:46 +01:00
Anselm Schüler
9769e90233 lib/options: Add more options to mkPackageOption 2023-02-26 03:00:22 +01:00
Naïm Favier
6c7d4d4f9d
lib/options: update showOption comment 2023-02-18 18:13:11 +01:00
Domen Kožar
fe734efc9c types: suggest how to resolve the conflict 2023-02-09 08:24:12 +00:00
Domen Kožar
b3cc29c288 types: explicitly state unique options are expected to be unique 2023-02-09 07:25:50 +00:00
Colin Arnott
6ff66fcbd7
lib: standardise attrset type syntax
There are a number of different syntaxes used for attrset type
signatures in our doc strings, this change standardises upon one that
uses :: for specifying attribute type, and ; terminators to be
consistent with nix syntax. There are no bugs in the functions
themselves, just that different syntaxes may confuse new users.
2023-01-30 23:53:44 +00:00
pennae
9da5f12ecf modules: add mkPackageOptionMD
another transitional option factory, like mkAliasOptionModuleMD.
2023-01-05 02:33:13 +01:00
hsjobeki
5ff21bfc73 attrsets: fix and add some doc types 2022-12-24 14:08:11 +01:00
Robert Hensing
5fb20d2f8c lib.modules: Add error context to rendered default and example attrs 2022-12-10 23:23:42 +01:00
Naïm Favier
6a117e2759 nixos/doc: render option values using lib.generators.toPretty
Render un`_type`d defaults and examples as `literalExpression`s using
`lib.generators.toPretty` so that consumers don't have to reinvent Nix
pretty-printing. `renderOptionValue` is kept internal for now intentionally.

Make `toPretty` print floats as valid Nix values (without a tilde).

Get rid of the now-obsolete `substSpecial` function.

Move towards disallowing evaluation of packages in the manual by
raising a warning on `pkgs.foo.{outPath,drvPath}`; later, this should
throw an error. Instead, module authors should use `literalExpression`
and `mkPackageOption`.
2022-12-08 17:52:52 +01:00
sternenseemann
c7a0d75bd1 haskell.compiler.ghc92: 9.2.4 -> 9.2.5 2022-11-07 17:29:47 +01:00
Maximilian Bosch
6396482dde
lib/options/showOption: fix quoting of attr-names that are not identifiers
Personally, I think that warnings such as

    warning: The option `services.redis.enable' defined in `/home/ma27/Projects/nixpkgs/test.nix@node-vm' has been renamed to `services.redis.servers..enable'.

are fairly confusing because of the `..` and it's more correct to
actually quote that. With this change the warning now looks like this:

    warning: The option `services.redis.enable' defined in `/home/ma27/Projects/nixpkgs/test.nix@node-vm' has been renamed to `services.redis.servers."".enable'.

While implementing that I realized that you'd have
a similar problem whenever you use attribute-names that aren't
identifiers, e.g.

    services.nginx.virtualHosts."example.org".locations."/".invalid = 23;

now results in the following error:

    error: The option `interactive.nodes.vm.services.nginx.virtualHosts."example.org".locations."/".invalid' does not exist. Definition values:
           - In `/home/ma27/Projects/nixpkgs/test.nix@node-vm': 23

Of course there are some corner-cases where this won't work: when
generating the manual, you display submodules like this:

    services.nginx.virtualHosts.<name>

Since `<name>` isn't a value, but an indicator for a submodule, it must
not be quoted. This also applies to the following identifiers:

* `*` for `listOf submodule`
* `<function body>` for `functionTo`

This might not be correct if you actually have a submodule with an
attribute name called `<name>`, but I think it's an improvement over the
current situation and for this you'd probably need to make even more
complex changes to the module system.
2022-10-07 10:09:03 +02:00
figsoda
d29b0096d3 lib/options.nix: remove unused binding 2022-09-26 22:18:55 -04:00
pennae
767485a0de lib/options: deprecate docbook text and literalDocBook
deprecate literalDocBook by adding a warning (that will not fire yet) to
its uses and other docbook literal strings by adding optional warning
message to mergeJSON.
2022-09-10 18:23:13 +02:00
pennae
e04a09082e lib/modules: convert option description to MD 2022-08-31 17:27:37 +02:00
pennae
9bb82c35b7 lib/options: add mdDoc support to mkEnableOption 2022-08-30 15:05:05 +02:00
sternenseemann
7f909b041b haskell.compiler: ghc923 -> ghc924
https://www.haskell.org/ghc/download_ghc_9_2_4.html
2022-07-28 18:09:33 +02:00
Robert Hensing
4a8bc4fd07 lib/options: Add hint for debugging infinite recursion in docs 2022-06-27 17:41:32 +02:00
Robert Hensing
89b4bd8b24 lib/options: Add showOptionWithDefLocs 2022-06-21 14:22:33 +02:00
pennae
320aa2a791 treewide: attempt at markdown option docs 2022-06-12 12:44:38 +02:00
sternenseemann
90099ac5fa haskell.compiler: ghc922 -> ghc923
https://www.haskell.org/ghc/download_ghc_9_2_3.html

Since the tarball is generated by Hadrian, neither autoreconf nor ./boot
is executed so ./configure and ghc.mk is missing.
2022-05-28 21:11:07 +02:00
sternenseemann
372d0a707e Merge remote-tracking branch 'origin/master' into haskell-updates 2022-03-26 09:59:28 +01:00
Silvan Mosberger
96698efe0c lib/modules: Finally remove deprecated types.optionSet
types.optionSet has been deprecated for almost 10 years now
(0e333688ce)! A removal
was already attempted in 2019
(27982b408e), but it was promptly
reinstantiated since some third-party uses were discovered
(f531ce75e4178c6867cc1d0f7fec96b2d5c3f1cb).

It's finally time to remove it for good :)
2022-03-18 04:51:27 +01:00
github-actions[bot]
6863d678bc
Merge master into haskell-updates 2022-03-17 00:10:36 +00:00
sternenseemann
47f837f5e8 haskell.compiler: ghc921 -> ghc922
https://www.haskell.org/ghc/download_ghc_9_2_2.html
2022-03-09 16:42:07 +01:00
Janne Heß
0c766a100e lib/options: Throw error for options without a type
Makes all options rendered in the manual throw an error if they don't
have a type specified.

This is a follow-up to #76184

Co-Authored-By: Silvan Mosberger <contact@infinisil.com>
2022-02-28 22:51:41 +01:00
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