···11+# Nixpkgs lib
22+33+This directory contains the implementation, documentation and tests for the Nixpkgs `lib` library.
44+55+## Overview
66+77+The evaluation entry point for `lib` is [`default.nix`](default.nix).
88+This file evaluates to an attribute set containing two separate kinds of attributes:
99+- Sub-libraries:
1010+ Attribute sets grouping together similar functionality.
1111+ Each sub-library is defined in a separate file usually matching its attribute name.
1212+1313+ Example: `lib.lists` is a sub-library containing list-related functionality such as `lib.lists.take` and `lib.lists.imap0`.
1414+ These are defined in the file [`lists.nix`](lists.nix).
1515+1616+- Aliases:
1717+ Attributes that point to an attribute of the same name in some sub-library.
1818+1919+ Example: `lib.take` is an alias for `lib.lists.take`.
2020+2121+Most files in this directory are definitions of sub-libraries, but there are a few others:
2222+- [`minver.nix`](minver.nix): A string of the minimum version of Nix that is required to evaluate Nixpkgs.
2323+- [`tests`](tests): Tests, see [Running tests](#running-tests)
2424+ - [`release.nix`](tests/release.nix): A derivation aggregating all tests
2525+ - [`misc.nix`](tests/misc.nix): Evaluation unit tests for most sub-libraries
2626+ - `*.sh`: Bash scripts that run tests for specific sub-libraries
2727+ - All other files in this directory exist to support the tests
2828+- [`systems`](systems): The `lib.systems` sub-library, structured into a directory instead of a file due to its complexity
2929+- [`path`](path): The `lib.path` sub-library, which includes tests as well as a document describing the design goals of `lib.path`
3030+- All other files in this directory are sub-libraries
3131+3232+### Module system
3333+3434+The [module system](https://nixos.org/manual/nixpkgs/#module-system) spans multiple sub-libraries:
3535+- [`modules.nix`](modules.nix): `lib.modules` for the core functions and anything not relating to option definitions
3636+- [`options.nix`](options.nix): `lib.options` for anything relating to option definitions
3737+- [`types.nix`](types.nix): `lib.types` for module system types
3838+3939+## Reference documentation
4040+4141+Reference documentation for library functions is written above each function as a multi-line comment.
4242+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).
4343+The nixdoc README describes the [comment format](https://github.com/nix-community/nixdoc#comment-format).
4444+4545+See the [chapter on contributing to the Nixpkgs manual](https://nixos.org/manual/nixpkgs/#chap-contributing) for how to build the manual.
4646+4747+## Running tests
4848+4949+All library tests can be run by building the derivation in [`tests/release.nix`](tests/release.nix):
5050+5151+```bash
5252+nix-build tests/release.nix
5353+```
5454+5555+Some commands for quicker iteration over parts of the test suite are also available:
5656+5757+```bash
5858+# Run all evaluation unit tests in tests/misc.nix
5959+# if the resulting list is empty, all tests passed
6060+nix-instantiate --eval --strict tests/misc.nix
6161+6262+# Run the module system tests
6363+tests/modules.sh
6464+6565+# Run the lib.sources tests
6666+tests/sources.sh
6767+6868+# Run the lib.filesystem tests
6969+tests/filesystem.sh
7070+7171+# Run the lib.path property tests
7272+path/tests/prop.sh
7373+```
+53
lib/path/default.nix
···2020 concatMap
2121 foldl'
2222 take
2323+ drop
2324 ;
24252526 inherit (lib.strings)
···217218 second argument: "${toString path2}" with root "${toString path2Deconstructed.root}"'';
218219 take (length path1Deconstructed.components) path2Deconstructed.components == path1Deconstructed.components;
219220221221+ /*
222222+ Remove the first path as a component-wise prefix from the second path.
223223+ The result is a normalised subpath string, see `lib.path.subpath.normalise`.
224224+225225+ Laws:
226226+227227+ - Inverts `append` for normalised subpaths:
228228+229229+ removePrefix p (append p s) == subpath.normalise s
230230+231231+ Type:
232232+ removePrefix :: Path -> Path -> String
233233+234234+ Example:
235235+ removePrefix /foo /foo/bar/baz
236236+ => "./bar/baz"
237237+ removePrefix /foo /foo
238238+ => "./."
239239+ removePrefix /foo/bar /foo
240240+ => <error>
241241+ removePrefix /. /foo
242242+ => "./foo"
243243+ */
244244+ removePrefix =
245245+ path1:
246246+ assert assertMsg
247247+ (isPath path1)
248248+ "lib.path.removePrefix: First argument is of type ${typeOf path1}, but a path was expected.";
249249+ let
250250+ path1Deconstructed = deconstructPath path1;
251251+ path1Length = length path1Deconstructed.components;
252252+ in
253253+ path2:
254254+ assert assertMsg
255255+ (isPath path2)
256256+ "lib.path.removePrefix: Second argument is of type ${typeOf path2}, but a path was expected.";
257257+ let
258258+ path2Deconstructed = deconstructPath path2;
259259+ success = take path1Length path2Deconstructed.components == path1Deconstructed.components;
260260+ components =
261261+ if success then
262262+ drop path1Length path2Deconstructed.components
263263+ else
264264+ throw ''
265265+ lib.path.removePrefix: The first path argument "${toString path1}" is not a component-wise prefix of the second path argument "${toString path2}".'';
266266+ in
267267+ assert assertMsg
268268+ (path1Deconstructed.root == path2Deconstructed.root) ''
269269+ lib.path.removePrefix: Filesystem roots must be the same for both paths, but paths with different roots were given:
270270+ first argument: "${toString path1}" with root "${toString path1Deconstructed.root}"
271271+ second argument: "${toString path2}" with root "${toString path2Deconstructed.root}"'';
272272+ joinRelPath components;
220273221274 /* Whether a value is a valid subpath string.
222275
+5-2
lib/path/tests/prop.sh
···11#!/usr/bin/env bash
2233-# Property tests for the `lib.path` library
44-#
33+# Property tests for lib/path/default.nix
54# It generates random path-like strings and runs the functions on
65# them, checking that the expected laws of the functions hold
66+# Run:
77+# [nixpkgs]$ lib/path/tests/prop.sh
88+# or:
99+# [nixpkgs]$ nix-build lib/tests/release.nix
710811set -euo pipefail
912shopt -s inherit_errexit
···11-# to run these tests:
22-# nix-instantiate --eval --strict nixpkgs/lib/tests/misc.nix
33-# if the resulting list is empty, all tests passed
11+/*
22+Nix evaluation tests for various lib functions.
33+44+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.
55+If you need to test error messages or more complex evaluations, see ./modules.sh, ./sources.sh or ./filesystem.sh as examples.
66+77+To run these tests:
88+99+ [nixpkgs]$ nix-instantiate --eval --strict lib/tests/misc.nix
1010+1111+If the resulting list is empty, all tests passed.
1212+Alternatively, to run all `lib` tests:
1313+1414+ [nixpkgs]$ nix-build lib/tests/release.nix
1515+*/
416with import ../default.nix;
517618let
+7-1
lib/tests/modules.sh
···11#!/usr/bin/env bash
22-#
22+33# This script is used to test that the module system is working as expected.
44+# Executing it runs tests for `lib.modules`, `lib.options` and `lib.types`.
45# By default it test the version of nixpkgs which is defined in the NIX_PATH.
66+#
77+# Run:
88+# [nixpkgs]$ lib/tests/modules.sh
99+# or:
1010+# [nixpkgs]$ nix-build lib/tests/release.nix
511612set -o errexit -o noclobber -o nounset -o pipefail
713shopt -s failglob inherit_errexit
···3232 meta = with lib; {
3333 description = "Python API wrapper to retrieve warnings from the german NINA app";
3434 homepage = "https://gitlab.com/DeerMaximum/pynina";
3535+ changelog = "https://gitlab.com/DeerMaximum/pynina/-/releases/${version}";
3536 license = licenses.mit;
3637 maintainers = with maintainers; [ fab ];
3738 };
···3232 ];
33333434 meta = with lib; {
3535- description = "TPM 2.0 plugin for age";
3535+ description = "TPM 2.0 plugin for age (This software is experimental, use it at your own risk)";
3636 homepage = "https://github.com/Foxboron/age-plugin-tpm";
3737 license = licenses.mit;
3838 platforms = platforms.linux;