wiki/docs/nix/lib-reference.md

title	description	published	date	tags	editor	dateCreated
Nix built-in and lib functions	An overview of the various functions available in Nix and Nixpkgs lib.	true	2024-08-02T23:15:00.000Z	nix, nixpkgs	markdown	2024-06-09T16:32:18.232Z

Introduction to Nix builtins and Nixpkgs lib

This page is an overview of the Nix built-in functions, and functions available in Nixpkgs' lib.

Built-in functions (builtins)

Built-ins are core language functions built directly into the Nix language evaluator. These functions are available through the global builtins constant.

Resources:

• Nix manual
• Nixpkgs lib reference by teu5us

Assertion functions (lib.asserts)

Assertions are generally used to check and/or enforce certain requirements in your configuration files. They're often used to handle conflicts between features or dependencies.

Resources:

• Nix manual
• Nixpkgs source

Attribute-set functions (lib.attrset)

Attribute sets are collections of name-value pairs (called attributes) enclosed in curly braces ( { } )

Resources:

• Nix manual
• Nixpkgs lib reference by teu5us
• Nixpkgs source

Customization functions (lib.customization)

Customization functions let you override derivations and packages.

Sources:

• Nixpkgs lib reference by teu5us
• Nixpkgs source

Debugging functions (lib.debug)

Debug functions are useful for debugging Nix expressions.

• trace-like functions take two values, print the first to stderr and return the second.
• traceVal-like functions take one argument which both printed and returned.
• traceSeq-like functions fully evaluate their traced value before printing (not just to “weak head normal form” like trace does by default).
• Functions that end in -Fn take an additional function as their first argument, which is applied to the traced value before it is printed.

Resources:

• Nixpkgs source

Local Files (lib.fileset)

A safer and more convenient interface for working with local files (compared to nix's built-in functionality).

Resources:

• Nixpkgs source
• Nixpkgs manual
• nix.dev Tutorial

Generator functions (lib.generators)

Generators can create various file formats from Nix data structures. They all use a similar interface: generator { config-attrs } data. config-attrs are used to overwrite the generator's default attributes.

Resources:

• Nixpkgs source

List manipulation functions (lib.lists)

List manipulation functions let you create and manipulate lists.

Resources:

• Nixpkgs source

Meta functions (lib.meta)

Meta functions override metadata attributes about derivations, packages, attribute sets, and other Nix constructs.

Resources:

• Nixpkgs source

Modules functions (lib.modules)

Modules functions let you define, evaluate, and merge Nix modules. They also include functions to import module definitions from other formats, like JSON and TOML.

Two of the most commonly used functions in this set are:

• mkIf, which lets you adds conditional statements to your modules, and
• mkMerge, which lets you combine multiple module definitions into one.

Resources:

• Nixpkgs source

NixOS / Nixpkgs option handling functions (lib.options)

Options are attributes commonly used to enable and configure Nix modules. Options are declared using the mkOption function.

Sources:

• NixOS Wiki
• My NixOS
• Nixpkgs source

Source filtering functions (lib.sources)

Source filtering functions change how sources are copied to the Nix store. For example, if you want to add a Git repository to your Nix store, but don't want to include the .git folder, you can use lib.sources.cleanSource ./folder.

Sources:

• Nixpkgs lib reference by teu5us
• Nixpks source

String manipulation functions (lib.strings)

String manipulation functions are used to create, manipulate, and parse strings (i.e. text). Common uses include:

• Exporting strings to different formats (lib.toJSON)
• Retrieving specific characters from a string (lib.elem, lib.elemAt, lib.substring, etc.)
• Checking if a string is a certain type (lib.isInt, lib.isPath, etc.)

Sources:

• Nixpkgs lib reference by teu5us
• Nixpkgs source

Miscellaneous functions (lib.trivial)

Miscellaneous functions are functions that don't fit under any other category. This is a grab bag of different functions, including:

• Math functions (lib.trivial.min, lib.trivial.max, etc.)
• Comparison operators (lib.trivial.or, lib.trivial.and, etc.)
• Bitwise comparison operators (lib.trivial.bitAnd, lib.trivial.bitOr, etc.)
• Getting the current version/release of Nix (lib.trivial.version, lib.trivial.release)
  • This also includes functions to compare the current version/release against a specific version/release, in order to conditionally enable features (lib.trivial.oldestSupportedRelease, lib.trivial.isInOldestRelease)
• Error and exception-handling functions (lib.trivial.warn, lib.trivial.throwIf, etc.)

Resources:

• Nixpkgs lib reference by teu5us
• Nixpkgs source

Versions functions (lib.versions)

Versions functions are for parsing version numbers from a string. This works well in tandem with lib.trivial.version, which retrieves the current Nixpkgs version.

Resources:

• Nixpkgs lib reference by teu5us
• Nixpkgs source