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 ## PR Guidelines
  40
  41 Follow these guidelines for proposing a change to the interface of `lib`.
  42
  43 ### Provide a Motivation
  44
  45 Clearly describe why the change is necessary and its use cases.
  46
  47 Make sure that the change benefits the user more than the added mental effort of looking it up and keeping track of its definition.
  48 If the same can reasonably be done with the existing interface,
  49 consider just updating the documentation with more examples and links.
  50 This is also known as the [Fairbairn Threshold](https://wiki.haskell.org/Fairbairn_threshold).
  51
  52 Through this principle we avoid the human cost of duplicated functionality in an overly large library.
  53
  54 ### Make one PR for each change
  55
  56 Don't have multiple changes in one PR, instead split it up into multiple ones.
  57
  58 This keeps the conversation focused and has a higher chance of getting merged.
  59
  60 ### Name the interface appropriately
  61
  62 When introducing new names to the interface, such as new function, or new function attributes,
  63 make sure to name it appropriately.
  64
  65 Names should be self-explanatory and consistent with the rest of `lib`.
  66 If there's no obvious best name, include the alternatives you considered.
  67
  68 ### Write documentation
  69
  70 Update the [reference documentation](#reference-documentation) to reflect the change.
  71
  72 Be generous with links to related functionality.
  73
  74 ### Write tests
  75
  76 Add good test coverage for the change, including:
  77
  78 - Tests for edge cases, such as empty values or lists.
  79 - Tests for tricky inputs, such as a string with string context or a path that doesn't exist.
  80 - Test all code paths, such as `if-then-else` branches and returned attributes.
  81 - If the tests for the sub-library are written in bash,
  82   test messages of custom errors, such as `throw` or `abortMsg`,
  83
  84   At the time this is only not necessary for sub-libraries tested with [`tests/misc.nix`](./tests/misc.nix).
  85
  86 See [running tests](#running-tests) for more details on the test suites.
  87
  88 ### Write tidy code
  89
  90 Name variables well, even if they're internal.
  91 The code should be as self-explanatory as possible.
  92 Be generous with code comments when appropriate.
  93
  94 As a baseline, follow the [Nixpkgs code conventions](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#code-conventions).
  95
  96 ### Write efficient code
  97
  98 Nix generally does not have free abstractions.
  99 Be aware that seemingly straightforward changes can cause more allocations and a decrease in performance.
 100 That said, don't optimise prematurely, especially in new code.
 101
 102 ## Reference documentation
 103
 104 Reference documentation for library functions is written above each function as a multi-line comment.
 105 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).
 106 The nixdoc README describes the [comment format](https://github.com/nix-community/nixdoc#comment-format).
 107
 108 See [doc/README.md](../doc/README.md) for how to build the manual.
 109
 110 ## Running tests
 111
 112 All library tests can be run by building the derivation in [`tests/release.nix`](tests/release.nix):
 113
 114 ```bash
 115 nix-build tests/release.nix
 116 ```
 117
 118 Some commands for quicker iteration over parts of the test suite are also available:
 119
 120 ```bash
 121 # Run all evaluation unit tests in tests/misc.nix
 122 # if the resulting list is empty, all tests passed
 123 nix-instantiate --eval --strict tests/misc.nix
 124
 125 # Run the module system tests
 126 tests/modules.sh
 127
 128 # Run the lib.sources tests
 129 tests/sources.sh
 130
 131 # Run the lib.filesystem tests
 132 tests/filesystem.sh
 133
 134 # Run the lib.path property tests
 135 path/tests/prop.sh
 136
 137 # Run the lib.fileset tests
 138 fileset/tests.sh
 139 ```
 140
 141 ## Commit conventions
 142
 143 - Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole.
 144
 145 - Format the commit messages in the following way:
 146
 147   ```
 148   lib.(section): (init | add additional argument | refactor | etc)
 149
 150   (Motivation for change. Additional information.)
 151   ```
 152
 153   Examples:
 154
 155   * lib.getExe': check arguments
 156   * lib.fileset: Add an additional argument in the design docs
 157
 158     Closes #264537
 159