pyrox.dev
1# Nixpkgs lib
2
3This directory contains the implementation, documentation and tests for the Nixpkgs `lib` library.
4
5## Overview
6
7The evaluation entry point for `lib` is [`default.nix`](default.nix).
8This file evaluates to an attribute set containing two separate kinds of attributes:
9- Sub-libraries:
10 Attribute sets grouping together similar functionality.
11 Each sub-library is defined in a separate file usually matching its attribute name.
12
13 Example: `lib.lists` is a sub-library containing list-related functionality such as `lib.lists.take` and `lib.lists.imap0`.
14 These are defined in the file [`lists.nix`](lists.nix).
15
16- Aliases:
17 Attributes that point to an attribute of the same name in some sub-library.
18
19 Example: `lib.take` is an alias for `lib.lists.take`.
20
21Most files in this directory are definitions of sub-libraries, but there are a few others:
22- [`minver.nix`](minver.nix): A string of the minimum version of Nix that is required to evaluate Nixpkgs.
23- [`tests`](tests): Tests, see [Running tests](#running-tests)
24 - [`release.nix`](tests/release.nix): A derivation aggregating all tests
25 - [`misc.nix`](tests/misc.nix): Evaluation unit tests for most sub-libraries
26 - `*.sh`: Bash scripts that run tests for specific sub-libraries
27 - All other files in this directory exist to support the tests
28- [`systems`](systems): The `lib.systems` sub-library, structured into a directory instead of a file due to its complexity
29- [`path`](path): The `lib.path` sub-library, which includes tests as well as a document describing the design goals of `lib.path`
30- All other files in this directory are sub-libraries
31
32### Module system
33
34The [module system](https://nixos.org/manual/nixpkgs/#module-system) spans multiple sub-libraries:
35- [`modules.nix`](modules.nix): `lib.modules` for the core functions and anything not relating to option definitions
36- [`options.nix`](options.nix): `lib.options` for anything relating to option definitions
37- [`types.nix`](types.nix): `lib.types` for module system types
38
39## Reference documentation
40
41Reference documentation for library functions is written above each function as a multi-line comment.
42These comments are processed using [nixdoc](https://github.com/nix-community/nixdoc) and [rendered in the Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/#chap-functions).
43The nixdoc README describes the [comment format](https://github.com/nix-community/nixdoc#comment-format).
44
45See the [chapter on contributing to the Nixpkgs manual](https://nixos.org/manual/nixpkgs/#chap-contributing) for how to build the manual.
46
47## Running tests
48
49All library tests can be run by building the derivation in [`tests/release.nix`](tests/release.nix):
50
51```bash
52nix-build tests/release.nix
53```
54
55Some commands for quicker iteration over parts of the test suite are also available:
56
57```bash
58# Run all evaluation unit tests in tests/misc.nix
59# if the resulting list is empty, all tests passed
60nix-instantiate --eval --strict tests/misc.nix
61
62# Run the module system tests
63tests/modules.sh
64
65# Run the lib.sources tests
66tests/sources.sh
67
68# Run the lib.filesystem tests
69tests/filesystem.sh
70
71# Run the lib.path property tests
72path/tests/prop.sh
73
74# Run the lib.fileset tests
75fileset/tests.sh
76```
77
78## Commit conventions
79
80- Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole.
81
82- Format the commit messages in the following way:
83
84 ```
85 lib.(section): (init | add additional argument | refactor | etc)
86
87 (Motivation for change. Additional information.)
88 ```
89
90 Examples:
91
92 * lib.getExe': check arguments
93 * lib.fileset: Add an additional argument in the design docs
94
95 Closes #264537
96