# Contributing to the Nixpkgs reference manual

> Nixpkgs documentation from NixOS/nixpkgs on master (doc/).

## [Contributing to the Nixpkgs reference manual](https://docharvest.github.io/docs/nixpkgs/)

Contents

nixpkgs

Contributing to the Nixpkgs reference manual

Nixpkgs

Contributing to the Nixpkgs reference manual

This directory houses the source files for the Nixpkgs reference manual.

> \[!IMPORTANT\] We are actively restructuring our documentation to follow the [Diátaxis framework](https://diataxis.fr/)
> 
> Going forward, this directory should **only** contain [reference documentation](https://nix.dev/contributing/documentation/diataxis#reference). For tutorials, guides and explanations, contribute to [https://nix.dev/](https://nix.dev/) instead.
> 
> We are actively working to generate **all** reference documentation from the [doc-comments](https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md) present in code. This also provides the benefit of using `:doc` in the `nix repl` to view reference documentation locally on the fly.

For documentation only relevant for contributors, use Markdown files next to the source and regular code comments.

> \[!TIP\] Feedback for improving support for parsing and rendering doc-comments is highly appreciated. [Open an issue](https://github.com/NixOS/nixpkgs/issues/new?labels=6.topic%3A+documentation&title=Doc%3A+) to request bugfixes or new features.

Rendered documentation:

-   [Unstable (from master)](https://nixos.org/manual/nixpkgs/unstable/)
-   [Stable (from latest release)](https://nixos.org/manual/nixpkgs/stable/)

The rendering tool is [nixos-render-docs](../pkgs/by-name/ni/nixos-render-docs), sometimes abbreviated `nrd`.

## Contributing to this documentation

You can quickly check your edits with `nix-build`:

```
$ cd /path/to/nixpkgs
$ nix-build doc
```

If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.

### Development environment

In order to reduce repetition, consider using tools from the provided development environment:

Load it from the Nixpkgs documentation directory with

```
$ cd /path/to/nixpkgs/doc
$ nix-shell
```

To load the development utilities automatically when entering that directory, [set up `nix-direnv`](https://nix.dev/guides/recipes/direnv).

Make sure that your local files aren't added to Git history by adding the following lines to `.git/info/exclude` at the root of the Nixpkgs repository:

```
/**/.envrc
/**/.direnv
```

#### `devmode`

Use [`devmode`](../pkgs/by-name/de/devmode/README.md) for a live preview when editing the manual.

### Testing redirects

Once you have a successful build, you can open the relevant HTML (path mentioned above) in a browser along with the anchor, and observe the redirection.

Note that if you already loaded the page and _then_ input the anchor, you will need to perform a reload. This is because browsers do not re-run client JS code when only the anchor has changed.

## Syntax

As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.

Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:

#### Tables

Tables, using the [GitHub-flavored Markdown syntax](https://github.github.com/gfm/#tables-extension-).

#### Anchors

Explicitly defined **anchors** on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md).

It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:

```
## Syntax {#sec-contributing-markup}
```

> \[!Note\] NixOS option documentation does not support headings in general.

#### Inline Anchors

Allow linking to an arbitrary place in the text (e.g. individual list items, sentences…).

They are defined using a hybrid of the link syntax with the attributes syntax known from headings, called [bracketed spans](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/bracketed_spans.md):

```
- []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGApps*` hook will prepend it to `XDG_DATA_DIRS`.
```

#### Automatic links

If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example `[](#chap-contributing)`.

This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).

#### HTML

Inlining HTML is not allowed. Parts of the documentation get rendered to various non-HTML formats, such as man pages in the case of NixOS manual.

#### Roles

If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``. The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json). Please keep the `manpage-urls.json` file alphabetically sorted.

A few markups for other kinds of literals are also available:

-   `` {command}`rm -rfi` ``
-   `` {env}`XDG_DATA_DIRS` ``
-   `` {file}`/etc/passwd` ``
-   `` {option}`networking.useDHCP` ``
-   `` {var}`/etc/passwd` ``

These literal kinds are used mostly in NixOS option documentation.

This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax. They are handled by `myst_role` defined per renderer.

#### Admonitions

Set off from the text to bring attention to something.

It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md):

```
::: {.warning}
This is a warning
:::
```

The following are supported:

-   `caution`
-   `important`
-   `note`
-   `tip`
-   `warning`
-   `example`

Example admonitions require a title to work. If you don't provide one, the manual won't be built.

```
::: {.example #ex-showing-an-example}

# Title for this example

Text for the example.
:::
```

#### [Definition lists](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md)

For defining a group of terms:

```
pear
:   green or yellow bulbous fruit

watermelon
:   green fruit with red flesh
```

## Commit conventions

-   Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole.
    
-   If creating a commit purely for documentation changes, format the commit message in the following way:
    
    ```
    doc: (documentation summary)
    
    (Motivation for change, relevant links, additional information.)
    ```
    
    Examples:
    
    -   doc: update the kernel config documentation to use `nix-shell`
        
    -   doc: add information about `nix-update-script`
        
        Closes #216321.
        
-   If the commit contains more than just documentation changes, follow the commit message format relevant for the rest of the changes.
    

## Documentation conventions

In an effort to keep the Nixpkgs manual in a consistent style, please follow the conventions below, unless they prevent you from properly documenting something. In that case, please open an issue about the particular documentation convention and tag it with a "needs: documentation" label. When needed, each convention explains why it exists, so you can make a decision whether to follow it or not based on your particular case. Note that these conventions are about the **structure** of the manual (and its source files), not about the content that goes in it. You, as the writer of documentation, are still in charge of its content.

**For prose style, see the [documentation styleguide](./styleguide.md).**

### One sentence per line

Put each sentence in its own line. This makes reviews and suggestions much easier, since GitHub's review system is based on lines. It also helps identifying long sentences at a glance.

Not everything has been migrated to this format yet. Please always use it for new content. When changing existing content, update formatting if possible, but avoid excessive diffs.

### Examples first

Put examples before detailed explanations (see the [styleguide](./styleguide.md) for the rationale).

Use this structure for each documented item:

1.  Title
2.  Abstract (optional, one sentence max)
3.  Example
4.  Explanation (details, edge cases, types, defaults)

Rendered example:

````
## `lib.toUpper`

Converts all characters in a string to uppercase.

:::{.example #ex-lib-toUpper}
# Converting a string to uppercase
```nix
lib.toUpper "hello"
=> "HELLO"
```

:::

Only acts on ASCII characters.
Unicode characters are passed through unchanged.
````

### Writing Function Documentation

Function documentation is _reference documentation_, for which [diataxis Reference documentation](https://diataxis.fr/reference/) (8 minutes) is **mandatory reading**.

On top of the diataxis framework, which provides a balanced perspective on what reference documentation should contain, we apply a specific style rule to function documentation: the first sentence is in present tense, active voice, and the subject is omitted, referring implicitly to the name of the function. For example:

```
/**
  Subtracts value `b` from value `a`.

  Returns the difference as a number.
*/
subtractValues # ...elided code
```

Renders as:

```
## `subtractValues`

Subtracts value `b` from value `a`.

Returns the difference as a number.
```

### Callouts and examples

Use the [admonition syntax](#admonitions) for callouts and examples.

### `callPackage`\-compatible examples

Provide at least one example per function.

Example code should be such that it can be passed to `pkgs.callPackage`. Instead of something like:

```
pkgs.dockerTools.buildLayeredImage {
  name = "hello";
  contents = [ pkgs.hello ];
}
```

Write something like:

```
{ dockerTools, hello }:
dockerTools.buildLayeredImage {
  name = "hello";
  contents = [ hello ];
}
```

### REPLs

When showing inputs/outputs of any [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop), such as a shell or the Nix REPL, use a format as you'd see in the REPL, while trying to visually separate inputs from outputs. This means that for a shell, you should use a format like the following:

```
$ nix-build -A hello '<nixpkgs>' \
  --option require-sigs false \
  --option trusted-substituters file:///tmp/hello-cache \
  --option substituters file:///tmp/hello-cache
/nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1
```

Note how the input is preceded by `$` on the first line and indented on subsequent lines, and how the output is provided as you'd see on the shell.

For the Nix REPL, you should use a format like the following:

```
nix-repl> builtins.attrNames { a = 1; b = 2; }
[ "a" "b" ]
```

Note how the input is preceded by `nix-repl>` and the output is provided as you'd see on the Nix REPL.

### Headings for inputs, outputs and examples

When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples. Keep examples as the last nested heading, and link to the examples wherever applicable in the documentation.

The purpose of this convention is to provide a familiar structure for navigating the manual, so any reader can expect to find content related to inputs in an "inputs" heading, examples in an "examples" heading, and so on. An example:

```
## buildImage

Some explanation about the function here.
Describe a particular scenario, and point to [](#ex-dockerTools-buildImage), which is an example demonstrating it.

### Inputs

Documentation for the inputs of `buildImage`.
Perhaps even point to [](#ex-dockerTools-buildImage) again when talking about something specifically linked to it.

### Passthru outputs

Documentation for any passthru outputs of `buildImage`.

### Examples

Note that this is the last nested heading in the `buildImage` section.

:::{.example #ex-dockerTools-buildImage}

# Using `buildImage`

Example of how to use `buildImage` goes here.

:::
```

### Function arguments

Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments as well as their [types](https://nixos.org/manual/nix/stable/language/values). For example:

```
# pkgs.coolFunction {#pkgs.coolFunction}

`pkgs.coolFunction` *`name`* *`config`*

Description of what `callPackage` does.

## Inputs {#pkgs-coolFunction-inputs}

If something's special about `coolFunction`'s general argument handling, you can say so here.
Otherwise, just describe the single argument or start the arguments' definition list without introduction.

*`name`* (String)

: The name of the resulting image.

*`config`* (Attribute set)

: Introduce the parameter. Maybe you have a test to make sure `{ }` is a sensible default; then you can say: these attributes are optional; `{ }` is a valid argument.

  `outputHash` (String; _optional_)

  : A brief explanation including when and when not to pass this attribute.

  : _Default:_ the output path's hash.
```

Checklist:

-   Start with a synopsis, to show the order of positional arguments.
-   Metavariables are in emphasized code spans: ``*`arg1`*``. Metavariables are placeholders where users may write arbitrary expressions. This includes positional arguments.
-   Attribute names are regular code spans: `` `attr1` ``. These identifiers can _not_ be picked freely by users, so they are _not_ metavariables.
-   _optional_ attributes have a _`Default:`_ if it's easily described as a value.
-   _optional_ attributes have a _`Default behavior:`_ if it's not easily described using a value.
-   Nix types aren't in code spans, because they are not code
-   Nix types are capitalized, to distinguish them from the camelCase Module System types, which _are_ code and behave like functions.

#### Examples

To define a referenceable figure use the following fencing:

```
:::{.example #an-attribute-set-example}
# An attribute set example

You can add text before

    ```nix
    { a = 1; b = 2;}
    ```

and after code fencing
:::
```

Defining examples through the `example` fencing class adds them to a "List of Examples" section after the Table of Contents. Though this is not shown in the rendered documentation on nixos.org.

#### Figures

To define a referenceable figure use the following fencing:

```
::: {.figure #nixos-logo}
# NixOS Logo
![NixOS logo](./nixos_logo.png)
:::
```

Defining figures through the `figure` fencing class adds them to a `List of Figures` after the `Table of Contents`. Though this is not shown in the rendered documentation on nixos.org.

#### Footnotes

To add a footnote explanation, use the following syntax:

```
Sometimes it's better to add context [^context] in a footnote.

[^context]: This explanation will be rendered at the end of the chapter.
```

#### Inline comments

Inline comments are supported with following syntax:

```
<!-- This is an inline comment -->
```

The comments will not be rendered in the rendered HTML.

#### Link reference definitions

Links can reference a label, for example, to make the link target reusable:

```
::: {.note}
Reference links can also be used to [shorten URLs][url-id] and keep the markdown readable.
:::

[url-id]: https://github.com/NixOS/nixpkgs/blob/19d4f7dc485f74109bd66ef74231285ff797a823/doc/README.md
```

This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-reference-definitions).

#### Typographic replacements

Typographic replacements are enabled. Check the [list of possible replacement patterns](https://github.com/executablebooks/markdown-it-py/blob/3613e8016ecafe21709471ee0032a90a4157c2d1/markdown_it/rules_core/replacements.py#L1-L15).

## Getting help

If you need documentation-specific help or reviews, ping [@NixOS/documentation-team](https://github.com/orgs/nixos/teams/documentation-team) on your pull request.

## [Build helpers {#part-builders}](https://docharvest.github.io/docs/nixpkgs/build-helpers/)

Contents

nixpkgs

Build helpers {#part-builders}

Nixpkgs

Build helpers {#part-builders}

A build helper is a function that produces derivations.

:::{.warning} This is not to be confused with the [`builder` argument of the Nix `derivation` primitive](https://nixos.org/manual/nix/unstable/language/derivations.html), which refers to the executable that produces the build result, or [remote builder](https://nixos.org/manual/nix/stable/advanced-topics/distributed-builds.html), which refers to a remote machine that could run such an executable. :::

Such a function is usually designed to abstract over a typical workflow for a given programming language or framework. This allows declaring a build recipe by setting a limited number of options relevant to the particular use case instead of using the `derivation` function directly.

[`stdenv.mkDerivation`](#part-stdenv) is the most widely used build helper and serves as a basis for many others. In addition, it offers various options to customize parts of the builds.

There is no uniform interface for build helpers. [Trivial build helpers](#chap-trivial-builders) and [fetchers](#chap-pkgs-fetchers) have various input types for convenience. [Language- or framework-specific build helpers](#chap-language-support) usually follow the style of `stdenv.mkDerivation`, which accepts an attribute set or a fixed-point function taking an attribute set.

```
build-helpers/fixed-point-arguments.chapter.md
build-helpers/fetchers.chapter.md
build-helpers/trivial-build-helpers.chapter.md
build-helpers/testers.chapter.md
build-helpers/dev-shell-tools.chapter.md
build-helpers/special.md
build-helpers/images.md
hooks/index.md
languages-frameworks/index.md
packages/index.md
```

## [Images {#chap-images}](https://docharvest.github.io/docs/nixpkgs/build-helpers/images/)

Contents

nixpkgs

Images {#chap-images}

Nixpkgs

Images {#chap-images}

This chapter describes tools for creating various types of images.

```
images/appimagetools.section.md
images/dockertools.section.md
images/ocitools.section.md
images/portableservice.section.md
images/makediskimage.section.md
images/binarycache.section.md
```

## [Special build helpers {#chap-special}](https://docharvest.github.io/docs/nixpkgs/build-helpers/special/)

Contents

nixpkgs

Special build helpers {#chap-special}

Nixpkgs

Special build helpers {#chap-special}

This chapter describes several special build helpers.

```
special/buildenv.section.md
special/fakenss.section.md
special/fhs-environments.section.md
special/makesetuphook.section.md
special/mkshell.section.md
special/vm-tools.section.md
special/checkpoint-build.section.md
```

## [Contributing to Nixpkgs {#part-contributing}](https://docharvest.github.io/docs/nixpkgs/contributing/)

Contents

nixpkgs

Contributing to Nixpkgs {#part-contributing}

Nixpkgs

Contributing to Nixpkgs {#part-contributing}

```
contributing/quick-start.chapter.md
contributing/coding-conventions.chapter.md
contributing/submitting-changes.chapter.md
contributing/vulnerability-roundup.chapter.md
contributing/reviewing-contributions.chapter.md
contributing/contributing-to-documentation.chapter.md
```

## [Development of Nixpkgs {#part-development}](https://docharvest.github.io/docs/nixpkgs/development/)

Contents

nixpkgs

Development of Nixpkgs {#part-development}

Nixpkgs

Development of Nixpkgs {#part-development}

This section shows you how Nixpkgs is developed and how you can interact with the contributors and the latest updates. If you are interested in contributing yourself, see [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

```
development/opening-issues.chapter.md
```

## [Functions reference {#chap-functions}](https://docharvest.github.io/docs/nixpkgs/functions/)

Contents

nixpkgs

Functions reference {#chap-functions}

Nixpkgs

Functions reference {#chap-functions}

The Nixpkgs repository has several utility functions to manipulate Nix expressions.

```
functions/library.md
functions/generators.section.md
functions/debug.section.md
functions/prefer-remote-fetch.section.md
functions/nix-gitignore.section.md
```

## [Hooks reference {#chap-hooks}](https://docharvest.github.io/docs/nixpkgs/hooks/)

Contents

nixpkgs

Hooks reference {#chap-hooks}

Nixpkgs

Hooks reference {#chap-hooks}

Nixpkgs has several hook packages that augment the stdenv phases.

The stdenv built-in hooks are documented in [](#ssec-setup-hooks).

```
autoconf.section.md
automake.section.md
autopatchcil.section.md
autopatchelf.section.md
aws-c-common.section.md
bmake.section.md
breakpoint.section.md
cernlib.section.md
cmake.section.md
desktop-file-utils.section.md
gdk-pixbuf.section.md
ghc.section.md
gnome.section.md
haredo.section.md
installShellFiles.section.md
installFonts.section.md
julec.section.md
just.section.md
libglycin.section.md
libiconv.section.md
libxml2.section.md
meson.section.md
mpi-check-hook.section.md
ninja.section.md
nodejs-install-executables.section.md
nodejs-install-manuals.section.md
npm-build-hook.section.md
npm-config-hook.section.md
npm-install-hook.section.md
patch-rc-path-hooks.section.md
perl.section.md
pkg-config.section.md
pnpm.section.md
postgresql-test-hook.section.md
premake.section.md
python.section.md
scons.section.md
tauri.section.md
tetex-tex-live.section.md
udevCheckHook.section.md
unzip.section.md
validatePkgConfig.section.md
versionCheckHook.section.md
waf.section.md
writable-tmpdir-as-home-hook.section.md
zig.section.md
xcbuild.section.md
xfce4-dev-tools.section.md
```

## [Interoperability Standards {#part-interoperability}](https://docharvest.github.io/docs/nixpkgs/interoperability/)

Contents

nixpkgs

Interoperability Standards {#part-interoperability}

Nixpkgs

Interoperability Standards {#part-interoperability}

```
interoperability/cyclonedx.md
```

## [CycloneDX {#chap-interop-cyclonedx}](https://docharvest.github.io/docs/nixpkgs/interoperability/cyclonedx/)

Contents

nixpkgs

CycloneDX {#chap-interop-cyclonedx}

Nixpkgs

CycloneDX {#chap-interop-cyclonedx}

[OWASP](https://owasp.org/) [CycloneDX](https://cyclonedx.org/) is a Software [Bill of Materials](https://en.wikipedia.org/wiki/Bill_of_materials) (SBOM) standard. The standards described here are for including Nix specific information within SBOMs in a way that is interoperable with external SBOM tooling.

## `nix` Namespace Property Taxonomy {#sec-interop.cylonedx-nix}

The following tables describe namespaces for [properties](https://cyclonedx.org/docs/1.6/json/#components_items_properties) that can be attached to components within SBOMs. Component properties are lists of name-value-pairs where the values must be strings. Properties with the same name may appear more than once. Names and values are case-sensitive.

Property

Description

`nix:store_path`

A Nix store path for the given component. This property should be contextualized by additional properties that describe the production of the store path, such as those from the `nix:narinfo:` and `nix:fod` namespaces.

Namespace

Description

[`nix:narinfo`](#sec-interop.cylonedx-narinfo)

Namespace for properties that are specific to how a component is stored as a [Nix archive](https://nixos.org/manual/nix/stable/glossary#gloss-nar) (NAR) in a [binary cache](https://nixos.org/manual/nix/stable/glossary#gloss-binary-cache).

[`nix:fod`](#sec-interop.cylonedx-fod)

Namespace for properties that describe a [fixed-output derivation](https://nixos.org/manual/nix/stable/glossary#gloss-fixed-output-derivation).

### `nix:narinfo` {#sec-interop.cylonedx-narinfo}

Narinfo properties describe component archives that may be available from binary caches. The `nix:narinfo` properties should be accompanied by a `nix:store_path` property within the same property list.

Property

Description

`nix:narinfo:store_path`

Store path for the given store component.

`nix:narinfo:url`

URL path component.

`nix:narinfo:nar_hash`

Hash of the file system object part of the component when serialized as a Nix Archive.

`nix:narinfo:nar_size`

Size of the component when serialized as a Nix Archive.

`nix:narinfo:compression`

The compression format that component archive is in.

`nix:narinfo:file_hash`

A digest for the compressed component archive itself, as opposed to the data contained within.

`nix:narinfo:file_size`

The size of the compressed component archive itself.

`nix:narinfo:deriver`

The path to the derivation from which this component is produced.

`nix:narinfo:system`

The hardware and software platform on which this component is produced.

`nix:narinfo:sig`

Signatures claiming that this component is what it claims to be.

`nix:narinfo:ca`

Content address of this store object's file system object, used to compute its store path.

`nix:narinfo:references`

A whitespace separated array of store paths that this component references.

### `nix:fod` {#sec-interop.cylonedx-fod}

FOD properties describe a [fixed-output derivation](https://nixos.org/manual/nix/stable/glossary#gloss-fixed-output-derivation). The `nix:fod:method` property is required and must be accompanied by a `nix:store_path` property within the same property list. All other properties in this namespace are method-specific. To reproduce the build of a component the `nix:fod:method` value is resolved to an [appropriate function](#chap-pkgs-fetchers) within Nixpkgs whose arguments intersect with the given properties. When generating `nix:fod` properties the method selected should be a stable function with a minimal number of arguments. For example, the `fetchFromGitHub` is commonly used within Nixpkgs but should be reduced to a call to the function by which it is implemented, `fetchzip`.

Property

Description

`nix:fod:method`

Nixpkgs function that produces this FOD. Required. Examples: `"fetchzip"`, `"fetchgit"`

`nix:fod:name`

Derivation name, present when method is `"fetchzip"`

`nix:fod:ref`

[Git ref](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefrefaref), present when method is `"fetchgit"`

`nix:fod:rev`

[Git rev](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefrevisionarevision), present when method is `"fetchgit"`

`nix:fod:sha256`

FOD hash

`nix:fod:url`

URL to fetch

`nix:fod` properties may be extracted and evaluated to a derivation using code similar to the following, assuming a fictitious function `filterPropertiesToAttrs`:

```
{
  pkgs,
  filterPropertiesToAttrs,
  properties,
}:
let
  fodProps = filterPropertiesToAttrs "nix:fod:" properties;

  methods = {
    fetchzip =
      {
        name,
        url,
        sha256,
        ...
      }:
      pkgs.fetchzip { inherit name url sha256; };
  };

in
methods.${fodProps.method} fodProps
```

## [OpenXR in NixOS](https://docharvest.github.io/docs/nixpkgs/interoperability/openxr/)

Contents

nixpkgs

OpenXR in NixOS

Nixpkgs

OpenXR in NixOS

OpenXR is a standard for eXtended Reality (XR) applications and drivers (providers).

OpenXR runtime providers must ensure that the library path of the runtime's shared library can be loaded by Nix applications. If your OpenXR runtime provider runs in an FHSEnv, this means you may have to use `auto-patchelf` to link dependencies to the Nix store.

## [Languages and frameworks {#chap-language-support}](https://docharvest.github.io/docs/nixpkgs/languages-frameworks/)

Contents

nixpkgs

Languages and frameworks {#chap-language-support}

Nixpkgs

Languages and frameworks {#chap-language-support}

The [standard build environment](#chap-stdenv) makes it easy to build typical Autotools-based packages with very little code. Any other kind of package can be accommodated by overriding the appropriate phases of `stdenv`. However, there are specialised functions in Nixpkgs to easily build packages for other programming languages, such as Perl or Haskell. These are described in this chapter.

Each supported language or software ecosystem has its own package set named `<language or ecosystem>Packages`, which can be explored in various ways:

-   Search on [search.nixos.org](https://search.nixos.org/packages)
    
    For example, search for [`haskellPackages`](https://search.nixos.org/packages?query=haskellPackages) or [`rubyPackages`](https://search.nixos.org/packages?query=rubyPackages).
    
-   Navigate attribute sets with [`nix repl`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-repl).
    
    This technique is generally useful to inspect Nix language data structures.
    
    :::{.example #example-navigte-nix-repl}
    
    # Navigate Java compiler variants in `javaPackages` with `nix repl`
    
    ```
    $ nix repl -f '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable
    nix-repl> javaPackages.<tab>
    javaPackages.compiler               javaPackages.openjfx15              javaPackages.openjfx21              javaPackages.recurseForDerivations
    javaPackages.jogl_2_4_0             javaPackages.openjfx17              javaPackages.openjfx25
    javaPackages.mavenfod               javaPackages.openjfx19              javaPackages.override
    javaPackages.openjfx11              javaPackages.openjfx20              javaPackages.overrideDerivation
    ```
    
    :::
    
-   List all derivations on the command line with [`nix-env --query`](https://nixos.org/manual/nix/stable/command-ref/nix-env/query).
    
    `nix-env` is the only convenient way to do that, as it will skip attributes that fail [assertions](https://nixos.org/manual/nix/stable/language/constructs#assertions), such as when a package is [marked as broken](#var-meta-broken), rather than failing the entire evaluation.
    
    :::{.example #example-list-haskellPackages}
    
    # List all Python packages in Nixpkgs
    
    The following command lists all [derivations names](https://nixos.org/manual/nix/stable/language/derivations#attr-name) with their attribute path from the latest Nixpkgs rolling release (`nixpkgs-unstable`).
    
    ```
    $ nix-env -qaP -f '<nixpkgs>' -A pythonPackages -I nixpkgs=channel:nixpkgs-unstable
    ```
    
    ```
    pythonPackages.avahi                                                  avahi-0.8
    pythonPackages.boost                                                  boost-1.81.0
    pythonPackages.caffe                                                  caffe-1.0
    pythonPackages.caffeWithCuda                                          caffe-1.0
    pythonPackages.cbeams                                                 cbeams-1.0.3
    …
    ```
    
    :::
    

```
agda.section.md
android.section.md
astal.section.md
beam.section.md
chicken.section.md
rocq.section.md
cosmic.section.md
crystal.section.md
cuda.section.md
cuelang.section.md
dart.section.md
dhall.section.md
dlang.section.md
dotnet.section.md
emscripten.section.md
factor.section.md
gnome.section.md
go.section.md
gradle.section.md
hare.section.md
haskell.section.md
hy.section.md
idris.section.md
idris2.section.md
ios.section.md
java.section.md
javascript.section.md
julia.section.md
lean4.section.md
lisp.section.md
lua.section.md
maven.section.md
nim.section.md
ocaml.section.md
octave.section.md
perl.section.md
php.section.md
pkg-config.section.md
python.section.md
qt.section.md
r.section.md
ruby.section.md
rust.section.md
scheme.section.md
swift.section.md
tcl.section.md
texlive.section.md
typst.section.md
vim.section.md
neovim.section.md
```

## [Nixpkgs lib {#id-1.4}](https://docharvest.github.io/docs/nixpkgs/lib/)

Contents

nixpkgs

Nixpkgs \`lib\` {#id-1.4}

Nixpkgs

Nixpkgs \`lib\` {#id-1.4}

```
functions.md
module-system/module-system.chapter.md
```

## [Modules {#modules}](https://docharvest.github.io/docs/nixpkgs/modules/)

Contents

nixpkgs

Modules {#modules}

Nixpkgs

Modules {#modules}

The Nixpkgs repository provides [Module System](https://nixos.org/manual/nixpkgs/unstable/#module-system) modules for various purposes.

The following sections are organized by [module class](https://nixos.org/manual/nixpkgs/unstable/#module-system-lib-evalModules-param-class).

```
generic.chapter.md
```

## [Packages {#chap-packages}](https://docharvest.github.io/docs/nixpkgs/packages/)

Contents

nixpkgs

Packages {#chap-packages}

Nixpkgs

Packages {#chap-packages}

This chapter contains information about how to use and maintain the Nix expressions for a number of specific packages, such as the Linux kernel or X.org.

```
citrix.section.md
darwin-builder.section.md
dlib.section.md
eclipse.section.md
elm.section.md
emacs.section.md
firefox.section.md
friction-graphics.section.md
fish.section.md
fuse.section.md
geant4.section.md
ibus.section.md
inkscape.section.md
kakoune.section.md
krita.section.md
linux.section.md
lhapdf.section.md
locales.section.md
etc-files.section.md
nginx.section.md
nrfutil.section.md
opengl.section.md
packer.section.md
shell-helpers.section.md
python-tree-sitter.section.md
treefmt.section.md
steam.section.md
cataclysm-dda.section.md
urxvt.section.md
vcpkg.section.md
weechat.section.md
uv.section.md
build-support.md
```

## [Build Support {#sec-build-support}](https://docharvest.github.io/docs/nixpkgs/packages/build-support/)

Contents

nixpkgs

Build Support {#sec-build-support}

Nixpkgs

Build Support {#sec-build-support}

## `pkgs.substitute` {#pkgs-substitute}

`pkgs.substitute` is a wrapper around [the `substitute` Bash function](#fun-substitute) in the standard environment. It replaces strings in `src` as specified by the `substitutions` argument.

:::{.example #ex-pkgs-substitute}

# Usage of `pkgs.substitute`

In a build script, the line:

```
substitute $infile $outfile --replace-fail @foo@ ${foopkg}/bin/foo
```

is equivalent to:

```
{ substitute, foopkg }:
substitute {
  src = ./sourcefile.txt;
  substitutions = [
    "--replace"
    "@foo@"
    "${foopkg}/bin/foo"
  ];
}
```

:::

## `pkgs.replaceVars` {#pkgs-replacevars}

`pkgs.replaceVars <src> <replacements>` replaces all instances of `@varName@` (`@`s included) in file `src` with the respective value in the attribute set `replacements`.

:::{.example #ex-pkgs-replace-vars}

# Usage of `pkgs.replaceVars`

If `say-goodbye.sh` contains the following:

```
#! @bash@/bin/bash

echo @unchanged@
@hello@/bin/hello --greeting @greeting@
```

the following derivation will make substitutions to `@bash@`, `@hello@`, and `@greeting@`:

```
{
  replaceVars,
  bash,
  hello,
}:
replaceVars ./say-goodbye.sh {
  inherit bash hello;
  greeting = "goodbye";
  unchanged = null;
}
```

such that `$out` will result in something like the following:

```
#! /nix/store/s30jrpgav677fpc9yvkqsib70xfmx7xi-bash-5.2p26/bin/bash

echo @unchanged@
/nix/store/566f5isbvw014h7knmzmxa5l6hshx43k-hello-2.12.1/bin/hello --greeting goodbye
```

Note that, in contrast to the old `substituteAll`, `unchanged = null` must explicitly be set. Any unreferenced `@...@` pattern in the source file will throw an error. :::

## `pkgs.replaceVarsWith` {#pkgs-replacevarswith}

`pkgs.replaceVarsWith` works the same way as [pkgs.replaceVars](#pkgs-replacevars), but additionally allows more options.

:::{.example #ex-pkgs-replace-vars-with}

# Usage of `pkgs.replaceVarsWith`

With the example file `say-goodbye.sh`, consider:

```
{ replaceVarsWith }:
replaceVarsWith {
  src = ./say-goodbye.sh;

  replacements = {
    inherit bash hello;
    greeting = "goodbye";
    unchanged = null;
  };

  name = "say-goodbye";
  dir = "bin";
  isExecutable = true;
  meta.mainProgram = "say-goodbye";
}
```

This will make the resulting file executable, put it in `bin/say-goodbye` and set `meta` attributes respectively. :::

## [Release Notes {#chap-release-notes}](https://docharvest.github.io/docs/nixpkgs/release-notes/release-notes/)

Contents

nixpkgs

Release Notes {#chap-release-notes}

Nixpkgs

Release Notes {#chap-release-notes}

This section lists the release notes for each stable version of Nixpkgs and the current unstable revision.

```
rl-2611.section.md
rl-2605.section.md
rl-2511.section.md
rl-2505.section.md
```

## [Standard environment {#part-stdenv}](https://docharvest.github.io/docs/nixpkgs/stdenv/)

Contents

nixpkgs

Standard environment {#part-stdenv}

Nixpkgs

Standard environment {#part-stdenv}

```
stdenv/stdenv.chapter.md
stdenv/meta.chapter.md
stdenv/passthru.chapter.md
stdenv/multiple-output.chapter.md
stdenv/cross-compilation.chapter.md
stdenv/platform-notes.chapter.md
```

## [Styleguide](https://docharvest.github.io/docs/nixpkgs/styleguide/)

Contents

nixpkgs

Styleguide

Nixpkgs

Styleguide

## Writing Principles

A consistent style greatly increases the usability of all documentation and communication.

Use this page as a reference and style guide for our internal and external documentation.

### Knowledge Expectations

**Assume competence, not familiarity.**

Write for someone who knows a great deal — up to but not including this project.

**What readers know:**

-   Basic computer operation
-   Command line familiarity
-   General interest in systems configuration

**What readers don't know:**

-   NixOS-specific concepts
-   NixOS ecosystem details or grammar
-   NixOS workflows

If specific knowledge is required, mention it at the start of the page.

#### Show, Don't Tell

The fastest path to understanding is a working example. People learn by doing, not by reading about doing.

**Recommended structure:**

-   Start with the minimal working code or command
-   Briefly explain what it does
-   Cover edge cases or variations
-   Link to further information instead of including it

#### Grammar and Style

**Sentence structure:**

-   Use simple, direct sentences
-   Break complex ideas into multiple short sentences
-   Avoid nested clauses

**Bad:**

> The following command, which utilizes nixos-generate-config to produce a comprehensive hardware configuration, will write the results back into the respective configuration directory located on your local machine.

What the user does is hidden in the middle. `nixos-generate-config` is a leaked implementation detail. Users care about _detecting hardware_, not _the tool that does it_.

**Good:**

> This command detects your hardware and saves the configuration.

#### Content Organization

Lead with value. State what the reader will accomplish before explaining how.

**Bad:**

> To create a new NixOS configuration that you can later use as a webserver, first navigate to your project directory, then add a new host configuration file with the desired machine name.

**Good:**

Add a webserver configuration to your NixOS setup:

```
# hosts/webserver/configuration.nix
{ ... }:
{
  services.nginx.enable = true;
}
```

Use **progressive disclosure**. Introduce concepts only when needed.

**Recommended structure:**

1.  State the goal (one sentence)
2.  Show the simplest working example
3.  Explain concepts if needed
4.  Provide advanced options separately or link to the reference

#### No Meta-commentary

Don't describe what the documentation does. Just do it.

**Don't:**

> This section explains how to configure networking. The following guide walks you through setting up a web server.

**Do:**

> Configure networking by setting: Set up a web server:

#### Code Examples

**Keep examples focused:**

-   Show one concept at a time
-   Use realistic but simple scenarios
-   Avoid dependencies on other examples

**Minimal comments**

Let the code speak for itself. Paste code examples directly and without further alteration.

**Bad:**

```
# This sets the hostname for the machine
{
  networking.hostName = "webserver"; # Change this to your machine's hostname
  # This enables SSH access
  services.openssh.enable = true; # Required for remote deployment
}
```

**Good:**

```
{
  networking.hostName = "webserver";
  services.openssh.enable = true;
}
```

#### Lead with Practical Examples

Don't front-load theory. Readers want to accomplish something first, then understand why it works.

-   Show configuration as _what you want_, not _how the module system works_
-   Introduce Nix-specific concepts only when they are needed to complete the task
-   Defer language mechanics to reference pages or `nix.dev`

**Bad:**

> Before adding a service, you need to understand the NixOS module system and attribute set merging.

**Good:**

Enable nginx:

```
{ services.nginx.enable = true; }
```

This adds nginx to your system configuration. Rebuild to apply:

```
sudo nixos-rebuild switch
```

#### Teach Nix through examples, not theory

Users learn the NixOS module system by seeing patterns first.

-   Start with a working example
-   Explanation follows the code
-   Link deeper concepts instead of inlining them
-   Link to `nix.dev` for optional learning

#### General Rules

-   Abbreviate keys like `ssh-ed25519 AAAAC3NzaC…`
-   Abbreviate IP addresses like `192.168.XXX.XXX`
-   Variables are capitalized and start with `$`, e.g. `$YOUR_HOSTNAME`
-   Variables should be directly usable during copy-paste
-   Do **not** describe missing code parts (`#elided`, `#omitted`)
-   **Machine vs Host**: use "machine" for the NixOS system identity, "host" for the physical or virtual hardware

#### Capitalization

-   GB / RAM / HDD
-   bootable USB drive
-   Wi-Fi / DHCP / DNS
-   macOS / NixOS / Nix / Linux
-   Flakes
-   git

#### Headings

Use sentence case. A reader scanning only headings should understand the page.

**Don't:**

> Getting Started Overview Configure The Database

**Do:**

> Set up a PostgreSQL database Configure networking Add a user to the system

#### Imperative Mood, Voice, and Person

Use imperative mood for instructions. Address the reader as "you", not "the user". Use active voice; in other words, make the subject do the action.

**Don't:**

> The user should run the following command. The configuration will need to be updated. The key is generated by the system.

**Do:**

> Run the command. Update the configuration. The system generates the key.

#### Tense

Use present tense for descriptions. Future tense makes documentation feel tentative.

**Don't:**

> This will create a new folder. Running this command will install the package.

**Do:**

> This creates a new folder. Running this command installs the package.

#### Be Confident

State facts. Don't hedge with "should," "might," "typically," or "usually" unless the behavior genuinely varies.

**Don't:**

> This should create the configuration file. The service will usually start automatically.

**Do:**

> This creates the configuration file. The service starts automatically.

#### Avoid Nominalizations

A nominalization is a verb turned into a noun, often by adding _\-tion_, _\-meant_, or _\-ance_ (e.g. "explanation", "selection"). The fix: find the hidden verb and use it directly.

**Don't:**

> Make a selection from the list. Provide an explanation of the error.

**Do:**

> Select from the list. Explain the error.

#### Plain Words

Technical precision for technical terms; plain language for everything else.

-   "use" not "utilize"
-   "start" not "initiate"
-   "end" not "terminate"
-   "help" not "facilitate"
-   "send" not "transmit"
-   "set up" not "establish"
-   "find out" not "ascertain"

#### Filler Words and Weak Phrases

Cut words and phrases that add length without meaning.

Delete on sight:

-   "simply", "just", "easily", "basically", "obviously"
-   "in order to" → use "to"
-   "allows you to" → use the verb directly
-   "it's worth noting that" → just say the thing
-   no exclamation marks in technical prose

**Don't:**

> Simply run `nixos-rebuild switch`. In order to deploy, you first need to run the command, which allows you to push the config. It's worth noting that this requires root access.

**Do:**

> Run `nixos-rebuild switch`. To deploy, run: This requires root access.

Every word must earn its place.

#### Writing Procedures

One instruction per sentence. Don't pack multiple actions into one sentence.

**Don't:**

> Navigate to your project directory and run the command, then check the output.

**Do:**

1.  Navigate to your project directory.
2.  Run the command.
3.  Check the output.

Don't bury the negative. Key limitations should be prominent, not a footnote after a positive description.

**Don't:**

> This service supports multiple roles, integrates with existing modules, and works great for most setups (note that multiple instances are not supported).

**Do:**

> This service does not support multiple instances.

#### Consistent Terminology

Pick a term and stick to it. Don't swap synonyms to avoid repetition. In technical documentation, repetition is clarity.

**Don't:**

> Create a machine... configure the host... deploy the node.

**Do:**

> Create a machine... configure the machine... deploy the machine.

#### Links

Use descriptive link text. Never use "click here" or "this link."

**Don't:**

> For more information, see `[this page](url)`. Click `[here](url)` to read the reference.

**Do:**

> See the `[NixOS options reference](url)` for details. Read the `[NixOS module system guide](url)`.

Only link when the destination is directly relevant, not for generic background context (sometimes known as "Wikipedia-style links"). Readers feel obligated to click links, fearing they'll miss something important. Don't send them to a generic article about a technology when they're looking for how _your_ system uses it.

**Don't:**

> Our software uses [SQLite](https://sqlite.org/) for storage. _(Reader clicks expecting schema details — finds a generic product page instead.)_

(Note that in the above example, the SQLite link is the SQLite home page, which is likely not pertinent.)

**Do:**

> See `[database schema](url)` for the full table structure.

#### UI Language

Match UI element names exactly: wording, casing, and spacing (even if a label seems oddly worded).

**Don't:**

> Click the generator button. Select the save option.

**Do:**

> Click **Generate a Key**. Click **Save Changes**.

Someone will go looking for a button labeled "generator." They will not find it. They will be frustrated.

Consistency between documentation and interface builds confidence. Words are part of the interface.

:::{.tip} This can be tricky as UI changes; we don't yet have a policy in place for how to handle this. We welcome comments and suggestions. :::

#### Clean system discipline

Your machine has things new users don't: cached credentials, installed tools, environment variables, existing configuration. When writing or updating documentation:

**Don't:**

> Write steps from memory on your development machine, assuming what works there will work everywhere.

**Do:**

> -   Start on a clean system — a fresh VM or new user account
> -   Take notes in real time as you work through the steps
> -   Document every warning, prompt, or unexpected output the system shows

Also think in combinations: WSL vs native Linux, with and without existing keys. You don't need to test every matrix square — but you need to know which ones diverge.

#### Never type code — always copy-paste

Always copy commands and code from a terminal where you just ran them successfully. Never retype from memory.

**Don't:**

> Retype a command from memory into the documentation. Retype code into a code-block from memory

**Do:**

> Paste commands directly from the shell or IDE. Paste code that has been successfully validated with nix-instantiate or nix-build

Replace sensitive values with placeholders: `<YOUR-KEY>`, `<YOUR-HOST>`, `<YOUR-TOKEN>`.

Typed-from-memory commands introduce subtle errors. Even the most experienced software developers have occasional typos.

## [Toolchains {#part-toolchains}](https://docharvest.github.io/docs/nixpkgs/toolchains/)

Contents

nixpkgs

Toolchains {#part-toolchains}

Nixpkgs

Toolchains {#part-toolchains}

```
toolchains/llvm.chapter.md
```

## [Using Nixpkgs {#part-using}](https://docharvest.github.io/docs/nixpkgs/using-nixpkgs/)

Contents

nixpkgs

Using Nixpkgs {#part-using}

Nixpkgs

Using Nixpkgs {#part-using}

```
using/platform-support.chapter.md
using/configuration.chapter.md
using/overlays.chapter.md
using/overrides.chapter.md
```