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
  74 # Run the lib.fileset tests
  75 fileset/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