···1+# Nixpkgs lib
2+3+This directory contains the implementation, documentation and tests for the Nixpkgs `lib` library.
4+5+## Overview
6+7+The evaluation entry point for `lib` is [`default.nix`](default.nix).
8+This 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+21+Most 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+34+The [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+41+Reference documentation for library functions is written above each function as a multi-line comment.
42+These 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).
43+The nixdoc README describes the [comment format](https://github.com/nix-community/nixdoc#comment-format).
44+45+See 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+49+All library tests can be run by building the derivation in [`tests/release.nix`](tests/release.nix):
50+51+```bash
52+nix-build tests/release.nix
53+```
54+55+Some 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
60+nix-instantiate --eval --strict tests/misc.nix
61+62+# Run the module system tests
63+tests/modules.sh
64+65+# Run the lib.sources tests
66+tests/sources.sh
67+68+# Run the lib.filesystem tests
69+tests/filesystem.sh
70+71+# Run the lib.path property tests
72+path/tests/prop.sh
73+```
+53
lib/path/default.nix
···20 concatMap
21 foldl'
22 take
023 ;
2425 inherit (lib.strings)
···217 second argument: "${toString path2}" with root "${toString path2Deconstructed.root}"'';
218 take (length path1Deconstructed.components) path2Deconstructed.components == path1Deconstructed.components;
2190000000000000000000000000000000000000000000000000000220221 /* Whether a value is a valid subpath string.
222
···20 concatMap
21 foldl'
22 take
23+ drop
24 ;
2526 inherit (lib.strings)
···218 second argument: "${toString path2}" with root "${toString path2Deconstructed.root}"'';
219 take (length path1Deconstructed.components) path2Deconstructed.components == path1Deconstructed.components;
220221+ /*
222+ Remove the first path as a component-wise prefix from the second path.
223+ The result is a normalised subpath string, see `lib.path.subpath.normalise`.
224+225+ Laws:
226+227+ - Inverts `append` for normalised subpaths:
228+229+ removePrefix p (append p s) == subpath.normalise s
230+231+ Type:
232+ removePrefix :: Path -> Path -> String
233+234+ Example:
235+ removePrefix /foo /foo/bar/baz
236+ => "./bar/baz"
237+ removePrefix /foo /foo
238+ => "./."
239+ removePrefix /foo/bar /foo
240+ => <error>
241+ removePrefix /. /foo
242+ => "./foo"
243+ */
244+ removePrefix =
245+ path1:
246+ assert assertMsg
247+ (isPath path1)
248+ "lib.path.removePrefix: First argument is of type ${typeOf path1}, but a path was expected.";
249+ let
250+ path1Deconstructed = deconstructPath path1;
251+ path1Length = length path1Deconstructed.components;
252+ in
253+ path2:
254+ assert assertMsg
255+ (isPath path2)
256+ "lib.path.removePrefix: Second argument is of type ${typeOf path2}, but a path was expected.";
257+ let
258+ path2Deconstructed = deconstructPath path2;
259+ success = take path1Length path2Deconstructed.components == path1Deconstructed.components;
260+ components =
261+ if success then
262+ drop path1Length path2Deconstructed.components
263+ else
264+ throw ''
265+ lib.path.removePrefix: The first path argument "${toString path1}" is not a component-wise prefix of the second path argument "${toString path2}".'';
266+ in
267+ assert assertMsg
268+ (path1Deconstructed.root == path2Deconstructed.root) ''
269+ lib.path.removePrefix: Filesystem roots must be the same for both paths, but paths with different roots were given:
270+ first argument: "${toString path1}" with root "${toString path1Deconstructed.root}"
271+ second argument: "${toString path2}" with root "${toString path2Deconstructed.root}"'';
272+ joinRelPath components;
273274 /* Whether a value is a valid subpath string.
275
+5-2
lib/path/tests/prop.sh
···1#!/usr/bin/env bash
23-# Property tests for the `lib.path` library
4-#
5# It generates random path-like strings and runs the functions on
6# them, checking that the expected laws of the functions hold
000078set -euo pipefail
9shopt -s inherit_errexit
···1#!/usr/bin/env bash
23+# Property tests for lib/path/default.nix
04# It generates random path-like strings and runs the functions on
5# them, checking that the expected laws of the functions hold
6+# Run:
7+# [nixpkgs]$ lib/path/tests/prop.sh
8+# or:
9+# [nixpkgs]$ nix-build lib/tests/release.nix
1011set -euo pipefail
12shopt -s inherit_errexit
+18-1
lib/path/tests/unit.nix
···3{ libpath }:
4let
5 lib = import libpath;
6- inherit (lib.path) hasPrefix append subpath;
78 cases = lib.runTests {
9 # Test examples from the lib.path.append documentation
···55 testHasPrefixExample4 = {
56 expr = hasPrefix /. /foo;
57 expected = true;
0000000000000000058 };
5960 # Test examples from the lib.path.subpath.isValid documentation
···1-# to run these tests:
2-# nix-instantiate --eval --strict nixpkgs/lib/tests/misc.nix
3-# if the resulting list is empty, all tests passed
0000000000004with import ../default.nix;
56let
···1+/*
2+Nix evaluation tests for various lib functions.
3+4+Since these tests are implemented with Nix evaluation, error checking is limited to what `builtins.tryEval` can detect, which is `throw`'s and `abort`'s, without error messages.
5+If you need to test error messages or more complex evaluations, see ./modules.sh, ./sources.sh or ./filesystem.sh as examples.
6+7+To run these tests:
8+9+ [nixpkgs]$ nix-instantiate --eval --strict lib/tests/misc.nix
10+11+If the resulting list is empty, all tests passed.
12+Alternatively, to run all `lib` tests:
13+14+ [nixpkgs]$ nix-build lib/tests/release.nix
15+*/
16with import ../default.nix;
1718let
+7-1
lib/tests/modules.sh
···1#!/usr/bin/env bash
2-#
3# This script is used to test that the module system is working as expected.
04# By default it test the version of nixpkgs which is defined in the NIX_PATH.
0000056set -o errexit -o noclobber -o nounset -o pipefail
7shopt -s failglob inherit_errexit
···1#!/usr/bin/env bash
2+3# This script is used to test that the module system is working as expected.
4+# Executing it runs tests for `lib.modules`, `lib.options` and `lib.types`.
5# By default it test the version of nixpkgs which is defined in the NIX_PATH.
6+#
7+# Run:
8+# [nixpkgs]$ lib/tests/modules.sh
9+# or:
10+# [nixpkgs]$ nix-build lib/tests/release.nix
1112set -o errexit -o noclobber -o nounset -o pipefail
13shopt -s failglob inherit_errexit
···1#! /usr/bin/env nix-shell
2-#! nix-shell -i bash -p nix curl jq nix-prefetch-github git gnused -I nixpkgs=.
34# See regenerate-hackage-packages.sh for details on the purpose of this script.
5
···1#! /usr/bin/env nix-shell
2+#! nix-shell -i bash -p nix curl jq git gnused -I nixpkgs=.
34# See regenerate-hackage-packages.sh for details on the purpose of this script.
5
···32 meta = with lib; {
33 description = "Python API wrapper to retrieve warnings from the german NINA app";
34 homepage = "https://gitlab.com/DeerMaximum/pynina";
035 license = licenses.mit;
36 maintainers = with maintainers; [ fab ];
37 };
···32 meta = with lib; {
33 description = "Python API wrapper to retrieve warnings from the german NINA app";
34 homepage = "https://gitlab.com/DeerMaximum/pynina";
35+ changelog = "https://gitlab.com/DeerMaximum/pynina/-/releases/${version}";
36 license = licenses.mit;
37 maintainers = with maintainers; [ fab ];
38 };
···32 ];
3334 meta = with lib; {
35- description = "TPM 2.0 plugin for age";
36 homepage = "https://github.com/Foxboron/age-plugin-tpm";
37 license = licenses.mit;
38 platforms = platforms.linux;
···32 ];
3334 meta = with lib; {
35+ description = "TPM 2.0 plugin for age (This software is experimental, use it at your own risk)";
36 homepage = "https://github.com/Foxboron/age-plugin-tpm";
37 license = licenses.mit;
38 platforms = platforms.linux;