Merge master into haskell-updates

  parse = pkgs.lib.recurseIntoAttrs {

    latest = pkgs.callPackage ./parse.nix { nix = pkgs.nixVersions.latest; };

    lix = pkgs.callPackage ./parse.nix { nix = pkgs.lix; };

    nix_2_24 = pkgs.callPackage ./parse.nix { nix = pkgs.nixVersions.nix_2_24; };

    nix_2_28 = pkgs.callPackage ./parse.nix { nix = pkgs.nixVersions.nix_2_28; };

  };

  shell = import ../shell.nix { inherit nixpkgs system; };

  tarball = import ../pkgs/top-level/make-tarball.nix {

# Contributing to the Nixpkgs reference manual

This directory houses the sources files for 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/)

#### Inline Anchors

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

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):

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 explain why it exists, so you can make a decision whether to follow it or not based on your particular case.

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.

  This can be seen as an equivalent of `FROM fromImage` in a `Dockerfile`.

  A value of `null` can be seen as an equivalent of `FROM scratch`.

  If specified, the layer created by `buildImage` will be appended to the layers defined in the base image, resulting in an image with at least two layers (one or more layers from the base image, and the layer created by `buildImage`).

  Otherwise, the resulting image with contain the single layer created by `buildImage`.

  If specified, the layer created by `buildImage` will be appended to the layers defined in the base image, resulting in an image with at least two layers (one or more layers from the base image and the layer created by `buildImage`).

  Otherwise, the resulting image will contain the single layer created by `buildImage`.

  :::{.note}

  Only **Env** configuration is inherited from the base image.

  This can be seen as an equivalent of `ADD contents/ /` in a `Dockerfile`.

  All the contents specified by `contents` will be added as a final layer in the generated image.

  They will be added as links to the actual files (e.g. links to the store paths).

  They will be added as links to the actual files (e.g., links to the store paths).

  The actual files will be added in previous layers.

  _Default value:_ `[]`

`gname` (String; _optional_) []{#dockerTools-buildLayeredImage-arg-gname}

: Credentials for Nix store ownership.

  Can be overridden to e.g. `1000` / `1000` / `"user"` / `"user"` to enable building a container where Nix can be used as an unprivileged user in single-user mode.

  Can be overridden to, e.g., `1000` / `1000` / `"user"` / `"user"` to enable building a container where Nix can be used as an unprivileged user in single-user mode.

  _Default value:_ `0` / `0` / `"root"` / `"root"`

- automatic or bound disk size: `diskSize` parameter, `additionalSpace` can be set when `diskSize` is `auto` to add a constant of disk space

- multiple partition table layouts: EFI, legacy, legacy + GPT, hybrid, none through `partitionTableType` parameter

- OVMF or EFI firmwares and variables templates can be customized

- root filesystem `fsType` can be customized to whatever `mkfs.${fsType}` exist during operations

- root filesystem `fsType` can be customized to whatever `mkfs.${fsType}` exists during operations

- root filesystem label can be customized, defaults to `nix-store` if it's a Nix store image, otherwise `nixpkgs/nixos`

- arbitrary code can be executed after disk image was produced with `postVM`

- the current nixpkgs can be realized as a channel in the disk image, which will change the hash of the image when the sources are updated

Images are **NOT** deterministic, please do not hesitate to try to fix this, source of determinisms are (not exhaustive) :

- bootloader installation have timestamps

- SQLite Nix store database contain registration times

- bootloader installation has timestamps

- SQLite Nix store database contains registration times

- `/etc/shadow` is in a non-deterministic order

A `deterministic` flag is available for best efforts determinism.

This is a wrapper around `pkgs.runCommandWith`, which

- produces a fixed-output derivation, enabling the command(s) to access the network ;

- salts the derivation's name based on its inputs, ensuring the command is re-run whenever the inputs changes.

- salts the derivation's name based on its inputs, ensuring the command is re-run whenever the inputs change.

It accepts the following attributes:

- the derivation's `name` ;