a1d3882307
What it does: line and column level *declaration* position information:
$ nix repl .
nix-repl> :p nixosConfigurations.micro.options.environment.systemPackages.declarationPositions
[ { column = 7; file = "/nix/store/24aj3k7fgqv3ly7qkbf98qvphasrw9nb-source/nixos/modules/config/system-path.nix"; line = 63; } ]
Use cases:
- ctags over NixOS options, as will be presented at NixCon 2023 ;)
- improving the documentation pages to go to the exact line of the
declarations.
Related work:
- https://github.com/NixOS/nixpkgs/pull/65024
This one does it for all *definitions* rather than declarations, and
it was not followed through with due to performance worries.
- https://github.com/NixOS/nixpkgs/pull/208173
The basis for this change. This change is just a rebase of that one.
I split it out to add the capability before adding users of it, in
order to simplify review. However, the ctags script in there is a
sample user of this feature.
Benchmarks: conducted by evaluating my own reasonably complex NixOS
configuration with the command:
`hyperfine -S none -w 1 -- "nix eval .#nixosConfigurations.snowflake.config.system.build.toplevel.outPath"`
```
Benchmark 1: nix eval .#nixosConfigurations.snowflake.config.system.build.toplevel.outPath
Time (mean ± σ): 8.971 s ± 0.254 s [User: 5.872 s, System: 1.388 s]
Range (min … max): 8.574 s … 9.327 s 10 runs
Benchmark 1: nix eval .#nixosConfigurations.snowflake.config.system.build.toplevel.outPath
Time (mean ± σ): 8.766 s ± 0.160 s [User: 5.873 s, System: 1.346 s]
Range (min … max): 8.496 s … 9.033 s 10 runs
```
Summary of results: it seems to be in the noise, this does not cause any
visible regression in times.
|
||
|---|---|---|
| .. | ||
| path | ||
| systems | ||
| tests | ||
| ascii-table.nix | ||
| asserts.nix | ||
| attrsets.nix | ||
| cli.nix | ||
| customisation.nix | ||
| debug.nix | ||
| default.nix | ||
| deprecated.nix | ||
| derivations.nix | ||
| fetchers.nix | ||
| filesystem.nix | ||
| fixed-points.nix | ||
| flake.nix | ||
| generators.nix | ||
| kernel.nix | ||
| licenses.nix | ||
| lists.nix | ||
| meta.nix | ||
| minver.nix | ||
| modules.nix | ||
| options.nix | ||
| README.md | ||
| source-types.nix | ||
| sources.nix | ||
| strings-with-deps.nix | ||
| strings.nix | ||
| trivial.nix | ||
| types.nix | ||
| versions.nix | ||
| zip-int-bits.nix | ||
Nixpkgs lib
This directory contains the implementation, documentation and tests for the Nixpkgs lib library.
Overview
The evaluation entry point for lib is default.nix.
This file evaluates to an attribute set containing two separate kinds of attributes:
-
Sub-libraries: Attribute sets grouping together similar functionality. Each sub-library is defined in a separate file usually matching its attribute name.
Example:
lib.listsis a sub-library containing list-related functionality such aslib.lists.takeandlib.lists.imap0. These are defined in the filelists.nix. -
Aliases: Attributes that point to an attribute of the same name in some sub-library.
Example:
lib.takeis an alias forlib.lists.take.
Most files in this directory are definitions of sub-libraries, but there are a few others:
minver.nix: A string of the minimum version of Nix that is required to evaluate Nixpkgs.tests: Tests, see Running testsrelease.nix: A derivation aggregating all testsmisc.nix: Evaluation unit tests for most sub-libraries*.sh: Bash scripts that run tests for specific sub-libraries- All other files in this directory exist to support the tests
systems: Thelib.systemssub-library, structured into a directory instead of a file due to its complexitypath: Thelib.pathsub-library, which includes tests as well as a document describing the design goals oflib.path- All other files in this directory are sub-libraries
Module system
The module system spans multiple sub-libraries:
modules.nix:lib.modulesfor the core functions and anything not relating to option definitionsoptions.nix:lib.optionsfor anything relating to option definitionstypes.nix:lib.typesfor module system types
Reference documentation
Reference documentation for library functions is written above each function as a multi-line comment. These comments are processed using nixdoc and rendered in the Nixpkgs manual. The nixdoc README describes the comment format.
See the chapter on contributing to the Nixpkgs manual for how to build the manual.
Running tests
All library tests can be run by building the derivation in tests/release.nix:
nix-build tests/release.nix
Some commands for quicker iteration over parts of the test suite are also available:
# Run all evaluation unit tests in tests/misc.nix
# if the resulting list is empty, all tests passed
nix-instantiate --eval --strict tests/misc.nix
# Run the module system tests
tests/modules.sh
# Run the lib.sources tests
tests/sources.sh
# Run the lib.filesystem tests
tests/filesystem.sh
# Run the lib.path property tests
path/tests/prop.sh