nixpkgs/lib
Rebecca Turner fa9727cf1e
lib: modules.sh should check JSON output for predictability
Currently, the `lib/tests/modules.sh` test checks the output of
`nix-instantiate --eval` without `--json`, which outputs an unspecified
human-readable format.

This patch modifies `modules.sh` to use the `--json` output instead, to
be robust against future changes to `nix-instantiate` output.
2023-12-19 09:23:09 -08:00
..
fileset lib.fileset.gitTracked: Improve error when passing files 2023-12-11 23:05:51 +01:00
path lib.path.hasStorePathPrefix: init 2023-12-13 17:12:52 +01:00
systems lib.systems.elaborate: add libDir attribute 2023-12-03 16:23:44 -05:00
tests lib: modules.sh should check JSON output for predictability 2023-12-19 09:23:09 -08:00
ascii-table.nix strings: add escapeQuery for url encoding 2023-03-03 20:48:55 +01:00
asserts.nix lib: add asserts.assertEachOneOf 2023-11-09 17:27:20 +01:00
attrsets.nix lib/attrsets: Document and link Nix language operators 2023-12-13 18:38:41 +01:00
cli.nix
customisation.nix lib.callPackageWith: Optimize levenshtein sort 2023-12-08 22:15:29 +01:00
debug.nix lib/debug: remove unused let bindings 2023-06-23 09:41:04 +00:00
default.nix lib.sortOn: init 2023-12-08 22:15:29 +01:00
deprecated.nix lib.closePropagation: Remove the quadratic behavior in lib.closePropagation 2022-10-07 18:03:42 +02:00
derivations.nix lib.derivations: fix comment typo 2023-06-02 23:57:30 +08:00
fetchers.nix
filesystem.nix lib: Take advantage of section descriptions 2023-11-20 03:02:11 +01:00
fixed-points.nix lib/fixed-points.nix: correct typo 2023-10-31 11:45:51 -07:00
flake-version-info.nix flake/version overlay: review fixes 2023-12-10 13:25:24 +01:00
flake.nix flake/version overlay: review fixes 2023-12-10 13:25:24 +01:00
generators.nix lib.generators: made toLua accept derivations too 2023-12-15 15:05:46 +01:00
gvariant.nix lib: Take advantage of section descriptions 2023-11-20 03:02:11 +01:00
kernel.nix lib.kernel.unset: init 2023-05-01 10:23:42 +00:00
licenses.nix sudo: fix meta license information (#269788) 2023-12-02 09:45:08 +01:00
lists.nix lib.sort: Make doc consistent with sortOn 2023-12-08 22:15:30 +01:00
meta.nix lib.getExe: Make more efficient 2023-12-12 16:44:07 +13:00
minver.nix boostrap fetchurl: Add SRI support 2022-08-24 09:55:45 +02:00
modules.nix lib/modules: Test optionless module errors from #131205 2023-12-09 14:15:49 +01:00
options.nix lib: Take advantage of section descriptions 2023-11-20 03:02:11 +01:00
README.md doc: Rename to Nixpkgs reference manual and state purpose 2023-12-08 01:26:31 +01:00
source-types.nix lib.sourceTypes: simplify implementation 2022-05-30 16:27:34 +08:00
sources.nix lib: Take advantage of section descriptions 2023-11-20 03:02:11 +01:00
strings-with-deps.nix
strings.nix Merge pull request #273473 from adisbladis/lib-isConvertibleToString-static-list 2023-12-11 17:46:48 +01:00
trivial.nix Merge pull request #273470 from adisbladis/lib-tohexstring-static-values 2023-12-11 17:46:23 +01:00
types.nix treewide: add __attrsFailEvaluation and __recurseIntoDerivationForReleaseJobs 2023-12-15 05:13:46 -08:00
versions.nix lib/versions: add pad 2022-12-21 12:58:21 +01:00
zip-int-bits.nix lib/zip-int-bits: fix typo: bitXOR -> bitXor 2022-06-09 20:04:37 +03:00

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.lists is a sub-library containing list-related functionality such as lib.lists.take and lib.lists.imap0. These are defined in the file lists.nix.

  • Aliases: Attributes that point to an attribute of the same name in some sub-library.

    Example: lib.take is an alias for lib.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 tests
    • release.nix: A derivation aggregating all tests
    • misc.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: The lib.systems sub-library, structured into a directory instead of a file due to its complexity
  • path: The lib.path sub-library, which includes tests as well as a document describing the design goals of lib.path
  • All other files in this directory are sub-libraries

Module system

The module system spans multiple sub-libraries:

  • modules.nix: lib.modules for the core functions and anything not relating to option definitions
  • options.nix: lib.options for anything relating to option definitions
  • types.nix: lib.types for 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 doc/README.md 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

# Run the lib.fileset tests
fileset/tests.sh

Commit conventions

  • Make sure you read about the commit conventions common to Nixpkgs as a whole.

  • Format the commit messages in the following way:

    lib.(section): (init | add additional argument | refactor | etc)
    
    (Motivation for change. Additional information.)
    

    Examples:

    • lib.getExe': check arguments

    • lib.fileset: Add an additional argument in the design docs

      Closes #264537