The previous code was optimized for the old uniq behavior, which did not
call merge. That's changed, so the legacy path is not a hot path anymore,
and is not worth any tech debt.
The deprecation warnings in lib were wildly inconsistent. Different
formulations were used in different places for the same meaning. Some warnings
used builtins.trace instead of lib.warn, which prevents silencing; one even
only had a comment instead. Make everything more uniform.
This doesn't change uniq. Why not?
- In NixOS it seems that uniq is only used with
simple types that are fully checked by t.check.
- It exists for much longer and is used more widely.
- I believe we should deprecate it, because unique was
already better.
- unique can be a proving ground.
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.
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.
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.
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.
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.
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`.
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.
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.
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 :)
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>
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)
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>
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.
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.
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`.
