mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-10-31 06:31:20 +00:00
Merge pull request #244044 from tweag/lib-readme
Create a Readme in `lib`
This commit is contained in:
commit
0665253b86
73
lib/README.md
Normal file
73
lib/README.md
Normal file
@ -0,0 +1,73 @@
|
||||
# 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`](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`](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`](minver.nix): A string of the minimum version of Nix that is required to evaluate Nixpkgs.
|
||||
- [`tests`](tests): Tests, see [Running tests](#running-tests)
|
||||
- [`release.nix`](tests/release.nix): A derivation aggregating all tests
|
||||
- [`misc.nix`](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`](systems): The `lib.systems` sub-library, structured into a directory instead of a file due to its complexity
|
||||
- [`path`](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](https://nixos.org/manual/nixpkgs/#module-system) spans multiple sub-libraries:
|
||||
- [`modules.nix`](modules.nix): `lib.modules` for the core functions and anything not relating to option definitions
|
||||
- [`options.nix`](options.nix): `lib.options` for anything relating to option definitions
|
||||
- [`types.nix`](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](https://github.com/nix-community/nixdoc) and [rendered in the Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/#chap-functions).
|
||||
The nixdoc README describes the [comment format](https://github.com/nix-community/nixdoc#comment-format).
|
||||
|
||||
See the [chapter on contributing to the Nixpkgs manual](https://nixos.org/manual/nixpkgs/#chap-contributing) for how to build the manual.
|
||||
|
||||
## Running tests
|
||||
|
||||
All library tests can be run by building the derivation in [`tests/release.nix`](tests/release.nix):
|
||||
|
||||
```bash
|
||||
nix-build tests/release.nix
|
||||
```
|
||||
|
||||
Some commands for quicker iteration over parts of the test suite are also available:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
@ -1,9 +1,12 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
# Property tests for the `lib.path` library
|
||||
#
|
||||
# Property tests for lib/path/default.nix
|
||||
# It generates random path-like strings and runs the functions on
|
||||
# them, checking that the expected laws of the functions hold
|
||||
# Run:
|
||||
# [nixpkgs]$ lib/path/tests/prop.sh
|
||||
# or:
|
||||
# [nixpkgs]$ nix-build lib/tests/release.nix
|
||||
|
||||
set -euo pipefail
|
||||
shopt -s inherit_errexit
|
||||
|
@ -1,6 +1,18 @@
|
||||
# to run these tests:
|
||||
# nix-instantiate --eval --strict nixpkgs/lib/tests/misc.nix
|
||||
# if the resulting list is empty, all tests passed
|
||||
/*
|
||||
Nix evaluation tests for various lib functions.
|
||||
|
||||
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.
|
||||
If you need to test error messages or more complex evaluations, see ./modules.sh, ./sources.sh or ./filesystem.sh as examples.
|
||||
|
||||
To run these tests:
|
||||
|
||||
[nixpkgs]$ nix-instantiate --eval --strict lib/tests/misc.nix
|
||||
|
||||
If the resulting list is empty, all tests passed.
|
||||
Alternatively, to run all `lib` tests:
|
||||
|
||||
[nixpkgs]$ nix-build lib/tests/release.nix
|
||||
*/
|
||||
with import ../default.nix;
|
||||
|
||||
let
|
||||
|
@ -1,7 +1,13 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
|
||||
# This script is used to test that the module system is working as expected.
|
||||
# Executing it runs tests for `lib.modules`, `lib.options` and `lib.types`.
|
||||
# By default it test the version of nixpkgs which is defined in the NIX_PATH.
|
||||
#
|
||||
# Run:
|
||||
# [nixpkgs]$ lib/tests/modules.sh
|
||||
# or:
|
||||
# [nixpkgs]$ nix-build lib/tests/release.nix
|
||||
|
||||
set -o errexit -o noclobber -o nounset -o pipefail
|
||||
shopt -s failglob inherit_errexit
|
||||
|
@ -1,4 +1,11 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
# Tests lib/sources.nix
|
||||
# Run:
|
||||
# [nixpkgs]$ lib/tests/sources.sh
|
||||
# or:
|
||||
# [nixpkgs]$ nix-build lib/tests/release.nix
|
||||
|
||||
set -euo pipefail
|
||||
shopt -s inherit_errexit
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user