Nixpkgs Reference Manual

https://nixos.org/manual/nixpkgs
Admin
The Nixpkgs Reference Manual describes the entire public interface of Nixpkgs, a collection of...
Tokens:258,464
Snippets:3,082
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configure Meson installation tags

Source: https://nixos.org/manual/nixpkgs/stable

Example of passing multiple installation tags to the Meson build system.

```nix
mesonInstallTags = [ "emulator" "assembler" ];
```

--------------------------------

### Cross-Build with Platform Example

Source: https://nixos.org/manual/nixpkgs/stable

Instantiate a build using a predefined platform example.

```bash
$ nix-build '<nixpkgs>' --arg crossSystem '(import <nixpkgs/lib>).systems.examples.fooBarBaz' -A whatever
```

--------------------------------

### Configure makeFlags

Source: https://nixos.org/manual/nixpkgs/stable

Example of setting makeFlags to define the installation prefix.

```nix
{ makeFlags = [ "PREFIX=$(out)" ]; }
```

--------------------------------

### Build npm projects with npmHooks

Source: https://nixos.org/manual/nixpkgs/stable

Complete example of using npmHooks and Node.js installation hooks to build a project.

```nix
{
  stdenv,
  fetchFromGitHub,
  fetchNpmDeps,
  npmHooks,
  nodejsInstallExecutables,
  nodejsInstallManuals,
  nodejs,
}:
stdenv.mkDerivation (finalAttrs: {
  pname = "some-npm-project";
  version = "1.0";

  src = fetchFromGitHub {
    owner = "JohnNpm";
    repo = "SomeProject";
    tag = finalAttrs.version;
    hash = "...";
  };

  strictDeps = true;

  nativeBuildInputs = [
    nodejs
    nodejsInstallExecutables
    nodejsInstallManuals
    npmHooks.npmConfigHook
    npmHooks.npmBuildHook
    npmHooks.npmInstallHook
  ];

  npmBuildScript = "build";

  npmBuildFlags = [
    "--prod"
  ];

  npmFlags = [
    "--ignore-scripts"
  ];

  npmDeps = fetchNpmDeps {
    inherit (finalAttrs) src;
    hash = "...";
  };

  makeWrapperArgs = [
    "--set"
    "NODE_ENV"
    "production"
  ];

  meta = {
    description = "npm project";
  };
})
```

--------------------------------

### Define a basic setup hook with makeSetupHook

Source: https://nixos.org/manual/nixpkgs/stable

Creates a simple setup hook that propagates dependencies.

```nix
pkgs.makeSetupHook {
  name = "something-hook";
  propagatedBuildInputs = [ pkgs.commandsomething ];
  depsTargetTargetPropagated = [ pkgs.libsomething ];
} ./script.sh
```

--------------------------------

### Usage examples for lib.fileset.toSource

Source: https://nixos.org/manual/nixpkgs/stable

Examples demonstrating how to import directories and files into the store, including union operations and error handling for out-of-root paths.

```nix
# Import the current directory into the store
# but only include files under ./src
toSource {
  root = ./.;
  fileset = ./src;
}
=> "/nix/store/...-source"

# Import the current directory into the store
# but only include ./Makefile and all files under ./src
toSource {
  root = ./.;
  fileset = union
    ./Makefile
    ./src;
}
=> "/nix/store/...-source"

# Trying to include a file outside the root will fail
toSource {
  root = ./.;
  fileset = unions [
    ./Makefile
    ./src
    ../LICENSE
  ];
}
=> <error>
```

--------------------------------

### Install executables with installBin

Source: https://nixos.org/manual/nixpkgs/stable

Use installBin to move files into outputBin. Rename files before installation if the source name is undesirable.

```nix
{
  nativeBuildInputs = [ installShellFiles ];

  # Sometimes the file has an undesirable name. It should be renamed before
  # being installed via installBin
  postInstall = ''
    mv a.out delmar
    installBin foobar delmar
  '';
}
```

--------------------------------

### Configure custom Eclipse environment

Source: https://nixos.org/manual/nixpkgs/stable

Example configuration for ~/.config/nixpkgs/config.nix to install Eclipse with specific plugins and JVM arguments.

```nix
{
  packageOverrides = pkgs: {
    myEclipse =
      with pkgs.eclipses;
      eclipseWithPlugins {
        eclipse = eclipse-platform;
        jvmArgs = [ "-Xmx2048m" ];
        plugins = [ plugins.color-theme ];
      };
  };
}
```

--------------------------------

### Sudo Password Prompt

Source: https://nixos.org/manual/nixpkgs/stable

Example of the sudo password prompt during the initial credential installation.

```text
+ sudo --reset-timestamp /nix/store/…-install-credentials.sh ./keys
Password:
```

--------------------------------

### Install shell completions

Source: https://nixos.org/manual/nixpkgs/stable

Demonstrates explicit and implicit shell completion installation using installShellCompletion.

```nix
{
  nativeBuildInputs = [ installShellFiles ];
  postInstall = ''
    # explicit behavior
    installShellCompletion --bash --name foobar.bash share/completions.bash
    installShellCompletion --fish --name foobar.fish share/completions.fish
    installShellCompletion --nushell --name foobar share/completions.nu
    installShellCompletion --zsh --name _foobar share/completions.zsh
    # implicit behavior
    installShellCompletion share/completions/foobar.{bash,fish,zsh,nu}
  '';
}
```

--------------------------------

### Configure Nixpkgs to allow unfree software

Source: https://nixos.org/manual/nixpkgs/stable

Example of a basic Nixpkgs configuration file enabling the installation of unfree packages.

```nix
{ allowUnfree = true; }
```

--------------------------------

### Configure Rebar3 with plugins

Source: https://nixos.org/manual/nixpkgs/stable

Example of initializing Rebar3 with global plugins.

```nix
beamPackages.rebar3WithPlugins { globalPlugins = [beamPackages.pc]; }
```

--------------------------------

### installBin

Source: https://nixos.org/manual/nixpkgs/stable

Installs one or more files as executable binaries into the outputBin directory.

```APIDOC
## installBin

### Description
Installs one or more paths to files as executable files into the `outputBin` directory.

### Usage
`installBin [paths...]`

### Example
```bash
postInstall = ''
  mv a.out delmar
  installBin foobar delmar
'';
```
```

--------------------------------

### Build a package with nix-build

Source: https://nixos.org/manual/nixpkgs/stable

Example of building a derivation and listing the resulting store path.

```bash
$ nix-build
(output removed for clarity)
/nix/store/2hy5bxw7xgbgxkn0i4x6hjr8w3dbx16c-source

$ ls /nix/store/2hy5bxw7xgbgxkn0i4x6hjr8w3dbx16c-source
patchelf-0.18.0
```

--------------------------------

### Install a manpage

Source: https://nixos.org/manual/nixpkgs/stable

Installs a manpage from a file using the installManPage utility.

```nix
  # Installs a manpage from a file called "--name"
  postInstall = ''
    installManPage -- --name
  '';
}
```

--------------------------------

### Setup MPI check phase hook

Source: https://nixos.org/manual/nixpkgs/stable

Example of including the MPI check phase hook in a derivation.

```nix
{ mpiCheckPhaseHook, mpi, ... }:
{

```

--------------------------------

### Define a complex setup hook with substitutions

Source: https://nixos.org/manual/nixpkgs/stable

Creates a setup hook that uses variable substitution and registers a function to preConfigureHooks.

```nix
pkgs.makeSetupHook
  {
    name = "run-hello-hook";
    # Put dependencies here if they have hooks or necessary dependencies propagated
    # otherwise prefer direct paths to executables.
    propagatedBuildInputs = [
      pkgs.hello
      pkgs.cowsay
    ];
    substitutions = {
      shell = "${pkgs.bash}/bin/bash";
      cowsay = "${pkgs.cowsay}/bin/cowsay";
    };
  }
  (
    writeScript "run-hello-hook.sh" ''
      #!@shell@
      # the direct path to the executable has to be here because
      # this will be run when the file is sourced
      # at which point '$PATH' has not yet been populated with inputs
      @cowsay@ cow

      _printHelloHook() {
        hello
      }
      preConfigureHooks+=(_printHelloHook)
    ''
  )
```

--------------------------------

### Install with mods

Source: https://nixos.org/manual/nixpkgs/stable

Use the withMods attribute to include specific mods in the installation.

```nix
cataclysm-dda.withMods (mods: with mods; [ tileset.UndeadPeople ])
```

--------------------------------

### Example usage of patchShebangs

Source: https://nixos.org/manual/nixpkgs/stable

Examples showing how to use patchShebangs with host or build flags.

```bash
patchShebangs --host /nix/store/<hash>-hello-1.0/bin
```

```bash
patchShebangs --build configure
```

--------------------------------

### Example Flake Usage

Source: https://nixos.org/manual/nixpkgs/stable

Complete flake configuration for setting up the darwin-builder.

```nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-22.11-darwin";
    darwin.url = "github:lnl7/nix-darwin/master";
    darwin.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs =
    {
      self,
      darwin,
      nixpkgs,
      ...
    }@inputs:
    let

      inherit (darwin.lib) darwinSystem;
      system = "aarch64-darwin";
      pkgs = nixpkgs.legacyPackages."${system}";
      linuxSystem = builtins.replaceStrings [ "darwin" ] [ "linux" ] system;

      darwin-builder = nixpkgs.lib.nixosSystem {
        system = linuxSystem;
        modules = [
          "${nixpkgs}/nixos/modules/profiles/nix-builder-vm.nix"
          {
            virtualisation = {
              host.pkgs = pkgs;
              darwin-builder.workingDirectory = "/var/lib/darwin-builder";
              darwin-builder.hostPort = 22;
            };
          }
        ];
      };
    in
    {

      darwinConfigurations = {
        machine1 = darwinSystem {
          inherit system;
          modules = [
            {
              nix.distributedBuilds = true;
              nix.buildMachines = [
                {
                  hostName = "localhost";
                  sshUser = "builder";
                  sshKey = "/etc/nix/builder_ed25519";
                  system = linuxSystem;
                  maxJobs = 4;
                  supportedFeatures = [
                    "kvm"
                    "benchmark"
                    "big-parallel"
                  ];
                }
              ];

              launchd.daemons.darwin-builder = {
                command = "${darwin-builder.config.system.build.macos-builder-installer}/bin/create-builder";
                serviceConfig = {
                  KeepAlive = true;
                  RunAtLoad = true;
                  StandardOutPath = "/var/log/darwin-builder.log";
                  StandardErrorPath = "/var/log/darwin-builder.log";
                };
              };
            }
          ];
        };
      };

    };
}
```

--------------------------------

### Install custom environment to profile

Source: https://nixos.org/manual/nixpkgs/stable

Use the nix-env command to build and install the defined environment into the user profile.

```bash
nix-env -iA myEnv
```

--------------------------------

### Install nix-generate-from-cpan

Source: https://nixos.org/manual/nixpkgs/stable

Install the helper utility to automatically generate Nix expressions from CPAN modules.

```bash
$ nix-env -f "<nixpkgs>" -iA nix-generate-from-cpan
```

--------------------------------

### Install manpages with installManPage

Source: https://nixos.org/manual/nixpkgs/stable

Use installManPage to place manpages into the correct share/man/man<section> directory. Use the --name flag to rename files during installation.

```nix
{
  nativeBuildInputs = [ installShellFiles ];

  # Sometimes the manpage file has an undesirable name; e.g., it conflicts with
  # another software with an equal name. To install it with a different name,
  # the installed name must be provided before the path to the file.
  #
  # Below install a manpage "foobar.1" from the source file "./foobar.1", and
  # also installs the manpage "fromsea.3" from the source file "./delmar.3".
  postInstall = ''
    installManPage \
        foobar.1 \
        --name fromsea.3 delmar.3
  '';
}
```

```nix
{
  nativeBuildInputs = [ installShellFiles ];

  postInstall = ''
    installManPage --name foobar.1 <($out/bin/foobar --manpage)
  '';
}
```

--------------------------------

### Define meta.teams default and example

Source: https://nixos.org/manual/nixpkgs/stable

Default value and example usage for the meta.teams attribute set.

```nix
[ ]
```

```nix
[ lib.teams.acme lib.teams.haskell ]
```

--------------------------------

### Use lib.fileset.difference

Source: https://nixos.org/manual/nixpkgs/stable

Examples showing how to exclude specific directories or files from a file set.

```nix
# Create a file set containing all files from the current directory,
# except ones under ./tests
difference ./. ./tests

let
  # A set of Nix-related files
  nixFiles = unions [ ./default.nix ./nix ./tests/default.nix ];
in
# Create a file set containing all files under ./tests, except ones in `nixFiles`,
# meaning only without ./tests/default.nix
difference ./tests nixFiles
```

--------------------------------

### lib.trivial.toBaseDigits Usage

Source: https://nixos.org/manual/nixpkgs/stable

Example demonstrating integer to base digits conversion.

```nix
toBaseDigits 10 123 => [ 1 2 3 ]

toBaseDigits 2 6 => [ 1 1 0 ]

toBaseDigits 16 250 => [ 15 10 ]
```

--------------------------------

### Verify .NET environment information

Source: https://nixos.org/manual/nixpkgs/stable

Command to display installed SDKs and runtimes in the current environment.

```bash
$ dotnet --info
.NET SDK:
 Version:           9.0.100
 Commit:            59db016f11
 Workload version:  9.0.100-manifests.3068a692
 MSBuild version:   17.12.7+5b8665660

Runtime Environment:
 OS Name:     nixos
 OS Version:  25.05
 OS Platform: Linux
 RID:         linux-x64
 Base Path:   /nix/store/a03c70i7x6rjdr6vikczsp5ck3v6rixh-dotnet-sdk-9.0.100/share/dotnet/sdk/9.0.100/

.NET workloads installed:
There are no installed workloads to display.
Configured to use loose manifests when installing new manifests.

Host:
  Version:      9.0.0
  Architecture: x64
  Commit:       9d5a6a9aa4

.NET SDKs installed:
  8.0.404 [/nix/store/6wlrjiy10wg766490dcmp6x64zb1vc8j-dotnet-core-combined/share/dotnet/sdk]
  9.0.100 [/nix/store/6wlrjiy10wg766490dcmp6x64zb1vc8j-dotnet-core-combined/share/dotnet/sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 8.0.11 [/nix/store/6wlrjiy10wg766490dcmp6x64zb1vc8j-dotnet-core-combined/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 9.0.0 [/nix/store/6wlrjiy10wg766490dcmp6x64zb1vc8j-dotnet-core-combined/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 8.0.11 [/nix/store/6wlrjiy10wg766490dcmp6x64zb1vc8j-dotnet-core-combined/share/dotnet/shared/Microsoft.NETCore.App]
  Microsoft.NETCore.App 9.0.0 [/nix/store/6wlrjiy10wg766490dcmp6x64zb1vc8j-dotnet-core-combined/share/dotnet/shared/Microsoft.NETCore.App]

Other architectures found:
  None

Environment variables:
  Not set

global.json file:
  Not found

Learn more:
  https://aka.ms/dotnet/info

Download .NET:
  https://aka.ms/dotnet/download
```

--------------------------------

### Full checkpoint build example

Source: https://nixos.org/manual/nixpkgs/stable

Demonstrates a complete workflow for an incremental build using checkpointBuildTools.

```nix
{
  pkgs ? import <nixpkgs> { },
}:
let
  inherit (pkgs.checkpointBuildTools) prepareCheckpointBuild mkCheckpointBuild;
  helloCheckpoint = prepareCheckpointBuild pkgs.hello;
  changedHello = pkgs.hello.overrideAttrs (_: {
    doCheck = false;
    postPatch = ''
      sed -i 's/Hello, world!/Hello, Nix!/g' src/hello.c
    '';
  });
in
mkCheckpointBuild changedHello helloCheckpoint
```

--------------------------------

### Yarn Berry metadata format

Source: https://nixos.org/manual/nixpkgs/stable

Example of the metadata blocks found at the start of Yarn Berry lock files.

```text
__metadata:
  version: 6
  cacheKey: 8[cX]
```

```text
__metadata:
  version: 8
  cacheKey: 10[cX]
```

--------------------------------

### Create package options

Source: https://nixos.org/manual/nixpkgs/stable

Demonstrates various ways to configure package options, including custom defaults, examples, and nullable settings.

```nix
mkPackageOption pkgs "hello" { }
=> { ...; default = pkgs.hello; defaultText = literalExpression "pkgs.hello"; description = "The hello package to use."; type = package; }

mkPackageOption pkgs "GHC" {
  default = [ "ghc" ];
  example = "pkgs.haskellPackages.ghc.withPackages (hkgs: [ hkgs.primes ])";
}
=> { ...; default = pkgs.ghc; defaultText = literalExpression "pkgs.ghc"; description = "The GHC package to use."; example = literalExpression "pkgs.haskellPackages.ghc.withPackages (hkgs: [ hkgs.primes ])"; type = package; }

mkPackageOption pkgs [ "python3Packages" "pytorch" ] {
  extraDescription = "This is an example and doesn't actually do anything.";
}
=> { ...; default = pkgs.python3Packages.pytorch; defaultText = literalExpression "pkgs.python3Packages.pytorch"; description = "The pytorch package to use. This is an example and doesn't actually do anything."; type = package; }

mkPackageOption pkgs "nushell" {
  nullable = true;
}
=> { ...; default = pkgs.nushell; defaultText = literalExpression "pkgs.nushell"; description = "The nushell package to use."; type = nullOr package; }

mkPackageOption pkgs "coreutils" {
  default = null;
}
=> { ...; description = "The coreutils package to use."; type = package; }
```

--------------------------------

### Configure buildDubPackage derivation

Source: https://nixos.org/manual/nixpkgs/stable

Example configuration for a DUB package derivation, including lockfile reference and custom install phase.

```nix
  # generated by dub-to-nix, see below
  dubLock = ./dub-lock.json;

  buildInputs = [
    ncurses
    zlib
  ];

  installPhase = ''
    runHook preInstall
    install -Dm755 btdu -t $out/bin
    runHook postInstall
  '';
}
```

--------------------------------

### Configure GApps and Qt wrapping in stdenv.mkDerivation

Source: https://nixos.org/manual/nixpkgs/stable

Examples of configuring nativeBuildInputs and preFixup for applications requiring GApps or Qt wrappers.

```nix
  nativeBuildInputs = [
    wrapGAppsHook3
    gobject-introspection
    # ...
  ];

  dontWrapGApps = true;

  # Arguments to be passed to `makeWrapper`, only used by buildPython*
  preFixup = ''
    makeWrapperArgs+=("''${gappsWrapperArgs[@]}")
  '';
}
```

```nix
stdenv.mkDerivation {
  pname = "calibre";
  version = "3.47.0";

  nativeBuildInputs = [
    wrapGAppsHook3
    qt6.wrapQtAppsHook
    qmake
    # ...
  ];

  dontWrapGApps = true;

  preFixup = ''
    qtWrapperArgs+=("''${gappsWrapperArgs[@]}")
  '';
}
```

--------------------------------

### Configure install targets

Source: https://nixos.org/manual/nixpkgs/stable

Specifies the make targets used for installation when the default 'install' target is insufficient.

```nix
{ installTargets = "install-bin install-doc"; }
```

--------------------------------

### Initialize nix-shell for package building

Source: https://nixos.org/manual/nixpkgs/stable

Prepare the environment by setting the output directory before running build phases.

```bash
cd "$(mktemp -d)"
nix-shell '<nixpkgs>' -A some_package
export out=$(pwd)/out
```

--------------------------------

### Basic Factor Application Packaging

Source: https://nixos.org/manual/nixpkgs/stable

A minimal example of using buildFactorApplication to package a Factor application.

```nix
{
  lib,
  fetchurl,
  factorPackages,
}:

factorPackages.buildFactorApplication (finalAttrs: {
  pname = "foo";
  version = "1.0";

  src = fetchurl {
    url = "https://some-forge.org/foo-${finalAttrs.version}.tar.gz";
  };
})
```

--------------------------------

### Update Nixpkgs configuration to use lib

Source: https://nixos.org/manual/nixpkgs/stable/release-notes

Examples showing the transition from using pkgs to lib in Nixpkgs configuration for improved performance and recursion safety.

```nix
  { pkgs, ... }:
  {
    allowlistedLicenses = [ pkgs.lib.licenses.nasa13 ];
    blocklistedLicenses = with pkgs.lib.licenses; [ gpl3Only gpl3Plus ];
  }
```

```nix
  { lib, ... }:
  {
    allowlistedLicenses = [ lib.licenses.nasa13 ];
    blocklistedLicenses = with lib.licenses; [ gpl3Only gpl3Plus ];
  }
```

```nix
  { pkgs, lib ? pkgs.lib, ... }:
  {
    allowlistedLicenses = [ lib.licenses.nasa13 ];
    blocklistedLicenses = with lib.licenses; [ gpl3Only gpl3Plus ];
  }
```

--------------------------------

### lib.fixedPoints.fix Recursion Examples

Source: https://nixos.org/manual/nixpkgs/stable

Examples comparing rec syntax with let-binding recursion.

```nix
nix-repl> rec {
  foo = "foo";
  bar = "bar";
  foobar = foo + bar;
}
{ bar = "bar"; foo = "foo"; foobar = "foobar"; }
```

```nix
nix-repl> let self = {
  foo = "foo";
  bar = "bar";
  foobar = self.foo + self.bar;
}; in self
{ bar = "bar"; foo = "foo"; foobar = "foobar"; }
```

--------------------------------

### Usage of writeTextFile

Source: https://nixos.org/manual/nixpkgs/stable

Examples demonstrating how to write text files to the Nix store with options for executability, destination paths, and build checks.

```nix
writeTextFile {
  name = "my-cool-script";
  text = ''
    #!/bin/sh
    echo "This is my cool script!"
  '';
  executable = true;
  destination = "/some/subpath/my-cool-script";
  checkPhase = ''
    ${pkgs.shellcheck}/bin/shellcheck $out/some/subpath/my-cool-script
  '';
  meta = {
    license = pkgs.lib.licenses.cc0;
  };
  allowSubstitutes = true;
  preferLocalBuild = false;
}
```

```nix
writeTextFile {
  name = "my-file";
  text = ''
    Contents of File
  '';
}
```

```nix
writeTextFile {
  name = "my-script";
  text = ''
    echo "hi"
  '';
  executable = true;
  destination = "/bin/my-script";
}
```

--------------------------------

### Setting up Tauri Application Build

Source: https://nixos.org/manual/nixpkgs/stable

Example derivation structure for building a Tauri application using cargo-tauri.hook.

```nix
{
  lib,
  stdenv,
  rustPlatform,
  fetchNpmDeps,
  cargo-tauri,
  glib-networking,
  nodejs,
  npmHooks,
  openssl,
  pkg-config,
  webkitgtk_4_1,
  wrapGAppsHook4,
}:

rustPlatform.buildRustPackage (finalAttrs: {
```

--------------------------------

### Usage examples for lib.fixedPoints.fix

Source: https://nixos.org/manual/nixpkgs/stable

Examples showing fix applied to attribute sets and lists.

```nix
fix (self: { foo = "foo"; bar = "bar"; foobar = self.foo + self.bar; })
=> { bar = "bar"; foo = "foo"; foobar = "foobar"; }

fix (self: [ 1 2 (elemAt self 0 + elemAt self 1) ])
=> [ 1 2 3 ]
```

--------------------------------

### Building the exportImage package

Source: https://nixos.org/manual/nixpkgs/stable

Example output showing the unpacking of image layers during the nix-build process.

```bash
$ nix-build
(some output removed for clarity)
Unpacking base image...
From-image name or tag wasn't set. Reading the first ID.
Unpacking layer 5731199219418f175d1580dbca05677e69144425b2d9ecb60f416cd57ca3ca42/layer.tar
tar: Removing leading `/' from member names
Unpacking layer e2897bf34bb78c4a65736510204282d9f7ca258ba048c183d665bd0f3d24c5ec/layer.tar
tar: Removing leading `/' from member names
Unpacking layer 420aa5876dca4128cd5256da7dea0948e30ef5971712f82601718cdb0a6b4cda/layer.tar
tar: Removing leading `/' from member names
Unpacking layer ea5f4e620e7906c8ecbc506b5e6f46420e68d4b842c3303260d5eb621b5942e5/layer.tar
tar: Removing leading `/' from member names
Unpacking layer 65807b9abe8ab753fa97da8fb74a21fcd4725cc51e1b679c7973c97acd47ebcf/layer.tar
tar: Removing leading `/' from member names
Unpacking layer b7da2076b60ebc0ea6824ef641978332b8ac908d47b2d07ff31b9cc362245605/layer.tar
Executing post-mount steps...
Packing raw image...
[    1.660036] reboot: Power down
/nix/store/x6a5m7c6zdpqz1d8j7cnzpx9glzzvd2h-hello
```

--------------------------------

### Install Idris via nix-env

Source: https://nixos.org/manual/nixpkgs/stable

Install the base Idris package using the nix-env command.

```bash
$ nix-env -f "<nixpkgs>" -iA idris
```

--------------------------------

### Build a Docker image with runAsRoot

Source: https://nixos.org/manual/nixpkgs/stable

Uses runAsRoot to perform setup tasks like creating directories and files inside the image.

```nix
{
  dockerTools,
  buildEnv,
  hello,
}:
dockerTools.buildImage {
  name = "hello";
  tag = "latest";

  copyToRoot = buildEnv {
    name = "image-root";
    paths = [ hello ];
    pathsToLink = [ "/bin" ];
  };

  runAsRoot = ''
    mkdir -p /data
    echo "some content" > my-file
  '';

  config = {
    Cmd = [ "/bin/hello" ];
    WorkingDir = "/data";
  };
}
```

--------------------------------

### Building and Running a Docker Image

Source: https://nixos.org/manual/nixpkgs/stable

Commands to build a Nix derivation, load it into Docker, and start an interactive shell.

```bash
$ nix-build
(some output removed for clarity)
/nix/store/rpf47f4z5b9qr4db4ach9yr4b85hjhxq-env-helpers.tar.gz
$ docker image load -i /nix/store/rpf47f4z5b9qr4db4ach9yr4b85hjhxq-env-helpers.tar.gz
(output removed for clarity)
$ docker container run --rm -it env-helpers:latest /bin/sh
sh-5.2# help
GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)
(rest of output removed for clarity)
```

--------------------------------

### Configure Ninja build phases

Source: https://nixos.org/manual/nixpkgs/stable

Example showing how to define native check inputs for a derivation using Ninja.

```nix
  nativeCheckInputs = [
    openssh
    mpiCheckPhaseHook
  ];
}
```

--------------------------------

### Define meta.maintainers default and example

Source: https://nixos.org/manual/nixpkgs/stable

Default value and example usage for the meta.maintainers attribute set.

```nix
[ ]
```

```nix
[ lib.maintainers.alice lib.maintainers.bob ]
```

--------------------------------

### lib.fixedPoints.extends usage examples

Source: https://nixos.org/manual/nixpkgs/stable

Provides various examples of using lib.fixedPoints.extends to modify attribute sets.

```nix
f = final: { a = 1; b = final.a + 2; }

fix f
=> { a = 1; b = 3; }

fix (extends (final: prev: { a = prev.a + 10; }) f)
=> { a = 11; b = 13; }

fix (extends (final: prev: { b = final.a + 5; }) f)
=> { a = 1; b = 6; }

fix (extends (final: prev: { c = final.a + final.b; }) f)
=> { a = 1; b = 3; c = 4; }
```

--------------------------------

### Configure Go Build Inputs

Source: https://nixos.org/manual/nixpkgs/stable

Example of specifying C library dependencies for Go programs that require CGO.

```nix
{
  buildInputs = [
    libvirt
    libxml2
  ];
}
```

--------------------------------

### Create a desktop file with makeDesktopItem

Source: https://nixos.org/manual/nixpkgs/stable

Demonstrates the configuration of various XDG specification fields for a desktop item.

```nix
{ makeDesktopItem }:
makeDesktopItem {
  name = "my-program";
  desktopName = "My Program";
  genericName = "Video Player";
  noDisplay = false;
  comment = "Cool video player";
  icon = "/path/to/icon";
  onlyShowIn = [ "KDE" ];
  dbusActivatable = true;
  tryExec = "my-program";
  exec = "my-program --someflag";
  path = "/some/working/path";
  terminal = false;
  actions.example = {
    name = "New Window";
    exec = "my-program --new-window";
    icon = "/some/icon";
  };
  mimeTypes = [ "video/mp4" ];
  categories = [ "Utility" ];
  implements = [ "org.my-program" ];
  keywords = [
    "Video"
    "Player"
  ];
  startupNotify = false;
  startupWMClass = "MyProgram";
  prefersNonDefaultGPU = false;
  extraConfig.X-SomeExtension = "somevalue";
}
```

--------------------------------

### Enter nix-shell with Idris libraries

Source: https://nixos.org/manual/nixpkgs/stable

Start a shell environment with specific Idris libraries available.

```bash
$ nix-shell -p 'idrisPackages.with-packages (with idrisPackages; [ contrib pruviloj ])'
```

--------------------------------

### Install an Octave package with nix-env

Source: https://nixos.org/manual/nixpkgs/stable

Install a specific Octave package into the user profile from the repository root.

```bash
$ nix-env -f. -iA octavePackages.symbolic
```

--------------------------------

### Configure pnpm install flags

Source: https://nixos.org/manual/nixpkgs/stable

Pass additional flags to the pnpm install command using pnpmInstallFlags.

```nix
{
  # ...
  pnpmDeps = fetchPnpmDeps {
    # ...
    inherit (finalAttrs) pnpmInstallFlags;
  };

  pnpmInstallFlags = [ "--shamefully-hoist" ];
}
```

--------------------------------

### Usage examples for lib.lists.foldl

Source: https://nixos.org/manual/nixpkgs/stable

Examples showing string concatenation and type conversion using left fold.

```nix
lconcat = foldl (a: b: a + b) "z"
lconcat [ "a" "b" "c" ]
=> "zabc"
# different types
lstrange = foldl (str: int: str + toString (int + 1)) "a"
lstrange [ 1 2 3 4 ]
=> "a2345"
```

--------------------------------

### Build a Docker image with extraCommands

Source: https://nixos.org/manual/nixpkgs/stable

Uses extraCommands to perform setup tasks, noting that paths are relative to the root.

```nix
{
  dockerTools,
  buildEnv,
  hello,
}:
dockerTools.buildImage {
  name = "hello";
  tag = "latest";

  copyToRoot = buildEnv {
    name = "image-root";
    paths = [ hello ];
    pathsToLink = [ "/bin" ];
  };

  extraCommands = ''
    mkdir -p data
    echo "some content" > my-file
  '';

  config = {
    Cmd = [ "/bin/hello" ];
    WorkingDir = "/data";
  };
}
```

--------------------------------

### Include documentation outputs

Source: https://nixos.org/manual/nixpkgs/stable

Configure extraOutputsToInstall to ensure man pages and documentation are included in the environment.

```nix
{
  packageOverrides =
    pkgs: with pkgs; {
      myPackages = pkgs.buildEnv {
        name = "my-packages";
        paths = [
          aspell
          bc
          coreutils
          ffmpeg
          nix
          emscripten
          jq
          nox
          silver-searcher
        ];
        pathsToLink = [
          "/share/man"
          "/share/doc"
          "/bin"
        ];
        extraOutputsToInstall = [
          "man"
          "doc"
        ];
      };
    };
}
```

--------------------------------

### Install custom Idris package

Source: https://nixos.org/manual/nixpkgs/stable

Install the custom Idris package defined in an overlay on NixOS or non-NixOS systems.

```bash
$ # On NixOS
$ nix-env -iA nixos.myIdris
$ # On non-NixOS
$ nix-env -iA nixpkgs.myIdris
```

--------------------------------

### Define Go build tags

Source: https://nixos.org/manual/nixpkgs/stable

Examples of setting static and conditional build tags for Go projects.

```nix
{
  tags = [
    "production"
    "sqlite"
  ];
}
```

```nix
{ tags = [ "production" ] ++ lib.optionals withSqlite [ "sqlite" ]; }
```

--------------------------------

### Install additional font formats

Source: https://nixos.org/manual/nixpkgs/stable

Uses the installFont function to install specific font formats to a custom location.

```nix
{
  nativeBuildInputs = [ installFonts ];

  postInstall = ''
    installFont svg $out/share/fonts/svg
  '';
}
```

--------------------------------

### Run the Quicklisp import script

Source: https://nixos.org/manual/nixpkgs/stable

Execute the import script to update Nixpkgs from Quicklisp data.

```bash
cd pkgs/development/lisp-modules
nix-shell --run 'sbcl --script ql-import.lisp'
```

--------------------------------

### Configure Idris2 prefix for installation

Source: https://nixos.org/manual/nixpkgs/stable

Sets the Idris2 prefix to a writable directory to enable the use of the --install command.

```nix
{
  pkgs ? import <nixpkgs> { },
}:
pkgs.mkShell {
  packages = [ (idris2.withPackages (p: [ p.idris2Api ])) ];
  shellHook = ''
    IDRIS2_PREFIX="$HOME/.idris2"
  '';
}
```

--------------------------------

### Loading and Running a NixShellImage

Source: https://nixos.org/manual/nixpkgs/stable

Commands to build, load, and execute a build environment image.

```bash
$ nix-build
(some output removed for clarity)
/nix/store/pkj1sgzaz31wl0pbvbg3yp5b3kxndqms-hello-2.12.1-env.tar.gz

$ docker image load -i /nix/store/pkj1sgzaz31wl0pbvbg3yp5b3kxndqms-hello-2.12.1-env.tar.gz
(some output removed for clarity)
Loaded image: hello-2.12.1-env:latest
```

```bash
$ docker container run -it hello-2.12.1-env:latest
[nix-shell:~]$ buildDerivation
Running phase: unpackPhase
unpacking source archive /nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz
source root is hello-2.12.1
(some output removed for clarity)
Running phase: fixupPhase
shrinking RPATHs of ELF executables and libraries in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1
shrinking /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin/hello
checking for references to /build/ in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1...
gzipping man pages under /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/share/man/
patching script interpreter paths in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1
stripping (with command strip and flags -S -p) in  /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin

[nix-shell:~]$ $out/bin/hello
Hello, world!
```

--------------------------------

### Set LDFLAGS for Darwin install name

Source: https://nixos.org/manual/nixpkgs/stable

Use makeFlags to pass the install name to the linker during the build process on Darwin.

```nix
  makeFlags = lib.optional stdenv.hostPlatform.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";
}
```

--------------------------------

### Example runtime error for bindnow

Source: https://nixos.org/manual/nixpkgs/stable

Example of a runtime error message encountered when a program is incompatible with the bindnow hardening flag.

```text
intel_drv.so: undefined symbol: vgaHWFreeHWRec
```

--------------------------------

### Override build and install phases

Source: https://nixos.org/manual/nixpkgs/stable

Demonstrates manual compilation by overriding buildPhase and installPhase within stdenv.mkDerivation.

```nix
stdenv.mkDerivation {
  pname = "fnord";
  version = "4.5";

  # ...

  buildPhase = ''
    runHook preBuild

    gcc foo.c -o foo

    runHook postBuild
  '';

  installPhase = ''
    runHook preInstall

    mkdir -p $out/bin
    cp foo $out/bin

    runHook postInstall
  '';
}
```

--------------------------------

### Define a source using toSource

Source: https://nixos.org/manual/nixpkgs/stable

Demonstrates creating a source from a root directory and a union of specific files and directories.

```nix
toSource {
  root = ../.;
  fileset = unions [
    ./Makefile
    ./src
    ../LICENSE
  ];
}
```

```nix
toSource {
  root = "/nix/store/...-source";
  fileset = ./.;
}
```

--------------------------------

### Fix dylib install names with install_name_tool

Source: https://nixos.org/manual/nixpkgs/stable

Use install_name_tool in postFixup to update the install name of a library to its final output path.

```nix
  postFixup = ''
    # `-id <install_name>` takes the install name. The last parameter is the path to the library.
    ${stdenv.cc.targetPrefix}install_name_tool -id "$out/lib/libfoo.dylib" "$out/lib/libfoo.dylib"
  '';
}
```

--------------------------------

### PIC hardening error example

Source: https://nixos.org/manual/nixpkgs/stable

Assembler error example occurring when position independent code (PIC) is enabled for environments that do not support it.

```text
ccbLfRgg.s: Assembler messages:
ccbLfRgg.s:33: Error: missing or invalid displacement expression `private_key_len@GOTOFF'
```

--------------------------------

### Run an OCI container with runc

Source: https://nixos.org/manual/nixpkgs/stable

Demonstrates the process of building the container and executing it using the runc runtime.

```bash
$ nix-build
(some output removed for clarity)
/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join

$ cd /nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join
$ nix-shell -p runc
[nix-shell:/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join]$ sudo runc run ocitools-example
help
GNU bash, version 5.2.26(1)-release (x86_64-pc-linux-gnu)
(some output removed for clarity)
```

--------------------------------

### Stackprotector hardening error example

Source: https://nixos.org/manual/nixpkgs/stable

Example of a build error indicating a missing reference to __stack_chk_fail, often requiring stackprotector to be disabled.

```text
bin/blib.a(bios_console.o): In function `bios_handle_cup':
/tmp/nix-build-ipxe-20141124-5cbdc41.drv-0/ipxe-5cbdc41/src/arch/i386/firmware/pcbios/bios_console.c:86: undefined reference to `__stack_chk_fail'
```

--------------------------------

### Configure a development environment with shellFor

Source: https://nixos.org/manual/nixpkgs/stable

Example of using shellFor to create a development environment that includes multiple packages and their dependencies.

```nix
{
  pkgs ? import <nixpkgs> { },
}:

pkgs.haskellPackages.shellFor {
  packages = hpkgs: [
    # reuse the nixpkgs for this package
    hpkgs.distribution-nixpkgs
    # call our generated Nix expression manually
    (hpkgs.callPackage ./my-project/my-project.nix { })
  ];
```

--------------------------------

### Configure Ubuntu 24.04 disk image

Source: https://nixos.org/manual/nixpkgs/stable

Creates an 8GiB Ubuntu 24.04 image with Firefox installed.

```nix
{ pkgs }:
pkgs.vmTools.diskImageFuns.ubuntu2404x86_64 {
  extraPackages = [ "firefox" ];
  size = 8192;
}
```

--------------------------------

### Format hardening error example

Source: https://nixos.org/manual/nixpkgs/stable

Example of a build error caused by the format hardening flag when a format string is not a string literal.

```text
/tmp/nix-build-zynaddsubfx-2.5.2.drv-0/zynaddsubfx-2.5.2/src/UI/guimain.cpp:571:28: error: format not a string literal and no format arguments [-Werror=format-security]
         printf(help_message);
                            ^
cc1plus: some warnings being treated as errors
```

--------------------------------

### Create a Python environment with custom packages

Source: https://nixos.org/manual/nixpkgs/stable

Demonstrates building a custom package and including it in a Python environment alongside existing packages using withPackages.

```nix
with import <nixpkgs> { };

(
  let
    my_toolz = python313.pkgs.buildPythonPackage (finalAttrs: {
      pname = "toolz";
      version = "0.10.0";
      pyproject = true;

      src = fetchPypi {
        inherit (finalAttrs) pname version;
        hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
      };

      build-system = [ python313.pkgs.setuptools ];

      # has no tests
      doCheck = false;

      meta = {
        homepage = "https://github.com/pytoolz/toolz/";
        description = "List processing tools and functional utilities";
        # [...]
      };
    });

  in
  python313.withPackages (
    ps: with ps; [
      numpy
      my_toolz
    ]
  )
).env
```

--------------------------------

### Install shell completions with process substitution

Source: https://nixos.org/manual/nixpkgs/stable

Uses process substitution to generate and install shell completions, guarded by platform execution checks.

```nix
{
  nativeBuildInputs = [ installShellFiles ];
  postInstall = lib.optionalString (stdenv.buildPlatform.canExecute stdenv.hostPlatform) ''
    # using process substitution
    installShellCompletion --cmd foobar \
      --bash <($out/bin/foobar --bash-completion) \
      --fish <($out/bin/foobar --fish-completion) \
      --nushell <($out/bin/foobar --nushell-completion) \
      --zsh <($out/bin/foobar --zsh-completion)
  '';
}
```

--------------------------------

### Extracting an AppImage to install extra files

Source: https://nixos.org/manual/nixpkgs/stable

Combine appimageTools.extract with wrapType2 to install additional files like desktop entries or icons extracted from the AppImage.

```nix
{ appimageTools, fetchurl }:
let
  pname = "irccloud";
  version = "0.16.0";

  src = fetchurl {
    url = "https://github.com/irccloud/irccloud-desktop/releases/download/v${version}/IRCCloud-${version}-linux-x86_64.AppImage";
    hash = "sha256-/hMPvYdnVB1XjKgU2v47HnVvW4+uC3rhRjbucqin4iI=";
  };

  appimageContents = appimageTools.extract { inherit pname version src; };
in
appimageTools.wrapType2 {
  inherit pname version src;

  extraPkgs = pkgs: [ pkgs.at-spi2-core ];

  extraInstallCommands = ''
    mv $out/bin/irccloud-${version} $out/bin/irccloud
    install -m 444 -D ${appimageContents}/irccloud.desktop $out/share/applications/irccloud.desktop
    install -m 444 -D ${appimageContents}/usr/share/icons/hicolor/512x512/apps/irccloud.png \
      $out/share/icons/hicolor/512x512/apps/irccloud.png
    substituteInPlace $out/share/applications/irccloud.desktop \
      --replace-fail 'Exec=AppRun' 'Exec=irccloud'
  '';
}
```

--------------------------------

### Usage of lib.fileset.fromSource

Source: https://nixos.org/manual/nixpkgs/stable

Demonstrates converting existing source-based filters into file sets for migration or composition.

```nix
# There's no cleanSource-like function for file sets yet,
# but we can just convert cleanSource to a file set and use it that way
toSource {
  root = ./.;
  fileset = fromSource (lib.sources.cleanSource ./.);
}

# Keeping a previous sourceByRegex (which could be migrated to `lib.fileset.unions`),
# but removing a subdirectory using file set functions
difference
  (fromSource (lib.sources.sourceByRegex ./. [
    "^README\\.md$"
    # This regex includes everything in ./doc
    "^doc(/.*)?$"
  ])
  ./doc/generated
```

--------------------------------

### lib.strings.hasPrefix

Source: https://nixos.org/manual/nixpkgs/stable

Check if a string starts with a specific prefix.

```APIDOC
## lib.strings.hasPrefix

### Description
Determine whether a string has given prefix.

### Type
`hasPrefix :: String -> String -> Bool`

### Example
```
hasPrefix "foo" "foobar"
=> true
```
```
Tokens:
Raw