commit 03431f1244a92659cf26a1b6e40de5db00c5e310 · pyrox.dev/nixpkgs

+73

lib/README.md

···

       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
       +
       ```