nixpkgs/lib
Daniel Sidhion f452bb946c
Merge pull request #312215 from hsjobeki/doc/lib-debug
doc: migrate lib.debug to doc-comment format
2024-05-20 23:20:36 -07:00
..
deprecated lib: Document status of deprecated.nix and move it 2024-04-21 16:04:35 +02:00
fileset doc: migrate filesets to doc-comment format (#303811) 2024-05-20 23:12:31 -07:00
path lib.path.hasStorePathPrefix: init 2023-12-13 17:12:52 +01:00
systems freebsd: Cleanup, get ready to support version 14 2024-05-11 21:52:07 -04:00
tests Merge pull request #308032 from obsidiansystems/freebsd-no-suffix-version 2024-05-01 10:03:12 -04:00
.version lib flake: Fix version 2024-02-26 22:32:58 +01:00
ascii-table.nix strings: add escapeQuery for url encoding 2023-03-03 20:48:55 +01:00
asserts.nix doc: lib.asserts migrate to doc-comments (#292310) 2024-03-07 14:04:50 +01:00
attrsets.nix lib/attrsets: introduce mapCartesianProduct 2024-04-15 19:16:15 +02:00
cli.nix doc: migrate lib.cli to use doc-comments 2024-03-22 09:54:17 +01:00
customisation.nix doc: migrate lib.customisation to use doc-comments 2024-03-22 10:02:09 +01:00
debug.nix doc: migrate lib.debug to doc-comment format 2024-05-16 15:52:50 +02:00
default.nix Merge pull request #214021 from tweag/ifilter0 2024-04-22 22:18:34 +02:00
derivations.nix lib.lazyDerivation: Support multi-output derivations 2024-02-29 12:37:52 +01:00
fetchers.nix lib.fetchers: Add uppercase proxy environment variables 2024-04-26 14:30:55 -04:00
filesystem.nix lib.packagesFromDirectoryRecursive: init 2023-12-19 09:48:17 -08:00
fixed-points.nix lib.fixedPoints: fix rendering of docs for extends 2024-02-29 06:22:00 -08:00
flake-version-info.nix flake/version overlay: review fixes 2023-12-10 13:25:24 +01:00
flake.nix flake/version overlay: review fixes 2023-12-10 13:25:24 +01:00
generators.nix lib: use names from lib in lib/generators.nix, rather than builtins or submodules of lib 2024-03-16 11:19:38 -07:00
gvariant.nix lib/gvariant: Use more specific instructions for int and attrset 2024-05-02 23:19:08 +02:00
kernel.nix doc: migrate trivial files to doc-comment format (#299986) 2024-04-04 16:36:07 +02:00
licenses.nix licenses: add ICU license 2024-05-02 15:34:02 +00:00
lists.nix lib.lists.ifilter0: init 2024-04-22 18:33:14 +02:00
meta.nix Merge pull request #291909 from cdmistman/lib-meta-available-on-doc-example 2024-02-27 12:44:37 -08:00
minver.nix boostrap fetchurl: Add SRI support 2022-08-24 09:55:45 +02:00
modules.nix lib: remove all uses of lib.mdDoc 2024-04-13 10:07:35 -07:00
options.nix lib: clarify warning about mdDoc 2024-04-15 14:16:33 -04:00
README.md Merge pull request #272083 from tweag/lib-contrib 2023-12-19 22:29:51 +01:00
source-types.nix lib.sourceTypes: simplify implementation 2022-05-30 16:27:34 +08:00
sources.nix lib: Take advantage of section descriptions 2023-11-20 03:02:11 +01:00
strings-with-deps.nix lib: Use Nix's static scope checking, fix error message, optimize 2020-10-22 13:46:47 +02:00
strings.nix lib/strings: Add makeIncludePath (#296237) 2024-04-02 19:01:05 +02:00
trivial.nix lib: add xor 2024-04-04 19:46:58 +00:00
types.nix Merge pull request #284551 from hercules-ci/types-attrTag 2024-04-09 20:48:44 +02:00
versions.nix lib.versions: Remove unneeded polyfill 2024-02-09 05:46:05 +01:00

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. 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.

  • 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: A string of the minimum version of Nix that is required to evaluate Nixpkgs.
  • tests: Tests, see Running tests
    • release.nix: A derivation aggregating all 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: The lib.systems sub-library, structured into a directory instead of a file due to its complexity
  • 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 spans multiple sub-libraries:

  • modules.nix: lib.modules for the core functions and anything not relating to option definitions
  • options.nix: lib.options for anything relating to option definitions
  • types.nix: lib.types for module system types

PR Guidelines

Follow these guidelines for proposing a change to the interface of lib.

Provide a Motivation

Clearly describe why the change is necessary and its use cases.

Make sure that the change benefits the user more than the added mental effort of looking it up and keeping track of its definition. If the same can reasonably be done with the existing interface, consider just updating the documentation with more examples and links. This is also known as the Fairbairn Threshold.

Through this principle we avoid the human cost of duplicated functionality in an overly large library.

Make one PR for each change

Don't have multiple changes in one PR, instead split it up into multiple ones.

This keeps the conversation focused and has a higher chance of getting merged.

Name the interface appropriately

When introducing new names to the interface, such as new function, or new function attributes, make sure to name it appropriately.

Names should be self-explanatory and consistent with the rest of lib. If there's no obvious best name, include the alternatives you considered.

Write documentation

Update the reference documentation to reflect the change.

Be generous with links to related functionality.

Write tests

Add good test coverage for the change, including:

  • Tests for edge cases, such as empty values or lists.

  • Tests for tricky inputs, such as a string with string context or a path that doesn't exist.

  • Test all code paths, such as if-then-else branches and returned attributes.

  • If the tests for the sub-library are written in bash, test messages of custom errors, such as throw or abortMsg,

    At the time this is only not necessary for sub-libraries tested with tests/misc.nix.

See running tests for more details on the test suites.

Write tidy code

Name variables well, even if they're internal. The code should be as self-explanatory as possible. Be generous with code comments when appropriate.

As a baseline, follow the Nixpkgs code conventions.

Write efficient code

Nix generally does not have free abstractions. Be aware that seemingly straightforward changes can cause more allocations and a decrease in performance. That said, don't optimise prematurely, especially in new code.

Reference documentation

Reference documentation for library functions is written above each function as a multi-line comment. These comments are processed using nixdoc and rendered in the Nixpkgs manual. The nixdoc README describes the comment format.

See doc/README.md for how to build the manual.

Running tests

All library tests can be run by building the derivation in tests/release.nix:

nix-build tests/release.nix

Some commands for quicker iteration over parts of the test suite are also available:

# 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

# Run the lib.fileset tests
fileset/tests.sh

Commit conventions

  • Make sure you read about the commit conventions common to Nixpkgs as a whole.

  • Format the commit messages in the following way:

    lib.(section): (init | add additional argument | refactor | etc)
    
    (Motivation for change. Additional information.)
    

    Examples:

    • lib.getExe': check arguments

    • lib.fileset: Add an additional argument in the design docs

      Closes #264537