push sheeet

doc/packages/build-support.md

@@ -0,0 +1,105 @@
+# 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:
+
+```bash
+substitute $infile $outfile --replace-fail @foo@ ${foopkg}/bin/foo
+```
+
+is equivalent to:
+
+```nix
+{ 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
+#! @bash@/bin/bash
+
+echo @unchanged@
+@hello@/bin/hello --greeting @greeting@
+```
+
+the following derivation will make substitutions to `@bash@`, `@hello@`, and `@greeting@`:
+
+```nix
+{
+  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:
+
+```nix
+{ 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.
+:::

doc/packages/cataclysm-dda.section.md

@@ -0,0 +1,129 @@
+# Cataclysm: Dark Days Ahead {#cataclysm-dark-days-ahead}
+
+## How to install Cataclysm DDA {#how-to-install-cataclysm-dda}
+
+To install the latest stable release of Cataclysm DDA to your profile, execute
+`nix-env -f "<nixpkgs>" -iA cataclysm-dda`. For the curses build (build
+without tiles), install `cataclysmDDA.stable.curses`. Note: `cataclysm-dda` is
+an alias to `cataclysmDDA.stable.tiles`.
+
+If you like access to a development build of your favorite git revision,
+override `cataclysm-dda-git` (or `cataclysmDDA.git.curses` if you like the curses
+build):
+
+```nix
+cataclysm-dda-git.override {
+  version = "YYYY-MM-DD";
+  rev = "YOUR_FAVORITE_REVISION";
+  sha256 = "CHECKSUM_OF_THE_REVISION";
+}
+```
+
+The sha256 checksum can be obtained by
+
+```sh
+nix-prefetch-url --unpack "https://github.com/CleverRaven/Cataclysm-DDA/archive/${YOUR_FAVORITE_REVISION}.tar.gz"
+```
+
+The default configuration directory is `~/.cataclysm-dda`. If you prefer
+`$XDG_CONFIG_HOME/cataclysm-dda`, override the derivation:
+
+```nix
+cataclysm-dda.override { useXdgDir = true; }
+```
+
+## Important note for overriding packages {#important-note-for-overriding-packages}
+
+After applying `overrideAttrs`, you need to fix `passthru.pkgs` and
+`passthru.withMods` attributes either manually or by using `attachPkgs`:
+
+```nix
+let
+  # You enabled parallel building.
+  myCDDA = cataclysm-dda-git.overrideAttrs (_: {
+    enableParallelBuilding = true;
+  });
+
+  # Unfortunately, this refers to the package before overriding and
+  # parallel building is still disabled.
+  badExample = myCDDA.withMods (_: [ ]);
+
+  inherit (cataclysmDDA) attachPkgs pkgs wrapCDDA;
+
+  # You can fix it by hand
+  goodExample1 = myCDDA.overrideAttrs (old: {
+    passthru = old.passthru // {
+      pkgs = pkgs.override { build = goodExample1; };
+      withMods = wrapCDDA goodExample1;
+    };
+  });
+
+  # or by using a helper function `attachPkgs`.
+  goodExample2 = attachPkgs pkgs myCDDA;
+
+  # badExample                     # parallel building disabled
+  # goodExample1.withMods (_: [])  # parallel building enabled
+in
+goodExample2.withMods (_: [ ]) # parallel building enabled
+```
+
+## Customizing with mods {#customizing-with-mods}
+
+To install Cataclysm DDA with mods of your choice, you can use `withMods`
+attribute:
+
+```nix
+cataclysm-dda.withMods (mods: with mods; [ tileset.UndeadPeople ])
+```
+
+All mods, soundpacks, and tilesets available in nixpkgs are found in
+`cataclysmDDA.pkgs`.
+
+Here is an example to modify existing mods and/or add more mods not available
+in nixpkgs:
+
+```nix
+let
+  customMods =
+    self: super:
+    lib.recursiveUpdate super {
+      # Modify existing mod
+      tileset.UndeadPeople = super.tileset.UndeadPeople.overrideAttrs (old: {
+        # If you like to apply a patch to the tileset for example
+        patches = [ ./path/to/your.patch ];
+      });
+
+      # Add another mod
+      mod.Awesome = cataclysmDDA.buildMod {
+        modName = "Awesome";
+        version = "0.x";
+        src = fetchFromGitHub {
+          owner = "Someone";
+          repo = "AwesomeMod";
+          rev = "...";
+          hash = "...";
+        };
+        # Path to be installed in the unpacked source (default: ".")
+        modRoot = "contents/under/this/path/will/be/installed";
+      };
+
+      # Add another soundpack
+      soundpack.Fantastic = cataclysmDDA.buildSoundPack {
+        # ditto
+      };
+
+      # Add another tileset
+      tileset.SuperDuper = cataclysmDDA.buildTileSet {
+        # ditto
+      };
+    };
+in
+cataclysm-dda.withMods (
+  mods: with mods.extend customMods; [
+    tileset.UndeadPeople
+    mod.Awesome
+    soundpack.Fantastic
+    tileset.SuperDuper
+  ]
+)
+```

doc/packages/citrix.section.md

@@ -0,0 +1,33 @@
+# Citrix Workspace {#sec-citrix}
+
+The [Citrix Workspace App](https://www.citrix.com/products/workspace-app/) is a remote desktop viewer which provides access to [XenDesktop](https://www.citrix.com/products/xenapp-xendesktop/) installations.
+
+## Basic usage {#sec-citrix-base}
+
+The tarball archive needs to be downloaded manually, as the license agreements of the vendor for [Citrix Workspace](https://www.citrix.com/downloads/workspace-app/linux/workspace-app-for-linux-latest.html) needs to be accepted first. Then run `nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz`. With the archive available in the store, the package can be built and installed with Nix.
+
+## Citrix Self-service {#sec-citrix-selfservice}
+
+The [self-service](https://support.citrix.com/article/CTX200337) is an application for managing Citrix desktops and applications. Please note that this feature only works with at least `citrix_workspace_20_06_0` and later versions.
+
+In order to set this up, you first have to [download the `.cr` file from the Netscaler Gateway](https://its.uiowa.edu/support/article/102186). After that, you can configure the `selfservice` like this:
+
+```ShellSession
+$ storebrowse -C ~/Downloads/receiverconfig.cr
+$ selfservice
+```
+
+## Custom certificates {#sec-citrix-custom-certs}
+
+The `Citrix Workspace App` in `nixpkgs` trusts several certificates [from the Mozilla database](https://curl.haxx.se/docs/caextract.html) by default. However, several companies using Citrix might require their own corporate certificate. On distros with imperative packaging, these certs can be stored easily in [`$ICAROOT`](https://citrix.github.io/receiver-for-linux-command-reference/), however, this directory is a store path in `nixpkgs`. In order to work around this issue, the package provides a simple mechanism to add custom certificates without rebuilding the entire package using `symlinkJoin`:
+
+```nix
+with import <nixpkgs> { config.allowUnfree = true; };
+let
+  extraCerts = [
+    ./custom-cert-1.pem
+    ./custom-cert-2.pem # ...
+  ];
+in
+citrix_workspace.override { inherit extraCerts; }
+```

doc/packages/darwin-builder.section.md

@@ -0,0 +1,204 @@
+# darwin.linux-builder {#sec-darwin-builder}
+
+:::{.warning}
+By default, `darwin.linux-builder` uses a publicly-known private SSH **host key** (this is different from the SSH key used by the user that connects to the builder).
+
+Given the intended use case for it (a Linux builder that runs **on the same machine**), this shouldn't be an issue.
+However, if you plan to deviate from this use case in any way (e.g. by exposing this builder to remote machines), you should understand the security implications of doing so and take any appropriate measures.
+:::
+
+`darwin.linux-builder` provides a way to bootstrap a Linux remote builder on a macOS machine.
+
+This requires macOS version 12.4 or later.
+
+The remote builder runs on host port 31022 by default.
+You can change it by overriding `virtualisation.darwin-builder.hostPort`.
+See the [example](#sec-darwin-builder-example-flake).
+
+You will also need to be a trusted user for your Nix installation.  In other
+words, your `/etc/nix/nix.conf` should have something like:
+
+```
+extra-trusted-users = <your username goes here>
+```
+
+To launch the remote builder, run the following flake:
+
+```ShellSession
+$ nix run nixpkgs#darwin.linux-builder
+```
+
+That will prompt you to enter your `sudo` password:
+
+```
++ sudo --reset-timestamp /nix/store/…-install-credentials.sh ./keys
+Password:
+```
+
+… so that it can install a private key used to `ssh` into the build server.
+After that the script will launch the virtual machine and automatically log you
+in as the `builder` user:
+
+```
+<<< Welcome to NixOS 22.11.20220901.1bd8d11 (aarch64) - ttyAMA0 >>>
+
+Run 'nixos-help' for the NixOS manual.
+
+nixos login: builder (automatic login)
+
+
+[builder@nixos:~]$
+```
+
+> Note: When you need to stop the VM, run `shutdown now` as the `builder` user.
+
+To delegate builds to the remote builder, add the following options to your
+`nix.conf` file:
+
+```
+# - Replace ${ARCH} with either aarch64 or x86_64 to match your host machine
+# - Replace ${MAX_JOBS} with the maximum number of builds (pick 4 if you're not sure)
+builders = ssh-ng://builder@linux-builder ${ARCH}-linux /etc/nix/builder_ed25519 ${MAX_JOBS} - - - c3NoLWVkMjU1MTkgQUFBQUMzTnphQzFsWkRJMU5URTVBQUFBSUpCV2N4Yi9CbGFxdDFhdU90RStGOFFVV3JVb3RpQzVxQkorVXVFV2RWQ2Igcm9vdEBuaXhvcwo=
+
+# Not strictly necessary, but this will reduce your disk utilization
+builders-use-substitutes = true
+```
+
+To allow Nix to connect to a remote builder not running on port 22, you will also need to create a new file at `/etc/ssh/ssh_config.d/100-linux-builder.conf`:
+
+```
+Host linux-builder
+  Hostname localhost
+  HostKeyAlias linux-builder
+  Port 31022
+```
+
+… and then restart your Nix daemon to apply the change:
+
+```ShellSession
+$ sudo launchctl kickstart -k system/org.nixos.nix-daemon
+```
+
+## Example flake usage {#sec-darwin-builder-example-flake}
+
+```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";
+                };
+              };
+            }
+          ];
+        };
+      };
+
+    };
+}
+```
+
+## Reconfiguring the remote builder {#sec-darwin-builder-reconfiguring}
+
+Initially you should not change the remote builder configuration else you will not be
+able to use the binary cache. However, after you have the remote builder running locally
+you may use it to build a modified remote builder with additional storage or memory.
+
+To do this, you just need to set the `virtualisation.darwin-builder.*` parameters as
+in the example below and rebuild.
+
+```nix
+{
+  darwin-builder = nixpkgs.lib.nixosSystem {
+    system = linuxSystem;
+    modules = [
+      "${nixpkgs}/nixos/modules/profiles/nix-builder-vm.nix"
+      {
+        virtualisation.host.pkgs = pkgs;
+        virtualisation.darwin-builder.diskSize = 5120;
+        virtualisation.darwin-builder.memorySize = 1024;
+        virtualisation.darwin-builder.hostPort = 33022;
+        virtualisation.darwin-builder.workingDirectory = "/var/lib/darwin-builder";
+      }
+    ];
+  };
+}
+```
+
+You may make any other changes to your VM in this attribute set. For example,
+you could enable Docker or X11 forwarding to your Darwin host.
+
+## Troubleshooting the generated configuration {#sec-darwin-builder-troubleshoot}
+
+The `linux-builder` package exposes the attributes `nixosConfig` and `nixosOptions` that allow you to inspect the generated NixOS configuration in the `nix repl`. For example:
+
+```
+$ nix repl --file ~/src/nixpkgs --argstr system aarch64-darwin
+
+nix-repl> darwin.linux-builder.nixosConfig.nix.package
+«derivation /nix/store/...-nix-2.17.0.drv»
+
+nix-repl> :p darwin.linux-builder.nixosOptions.virtualisation.memorySize.definitionsWithLocations
+[ { file = "/home/user/src/nixpkgs/nixos/modules/profiles/nix-builder-vm.nix"; value = 3072; } ]
+
+```

doc/packages/dlib.section.md

@@ -0,0 +1,13 @@
+# DLib {#dlib}
+
+[DLib](http://dlib.net/) is a modern, C++\-based toolkit which provides several machine learning algorithms.
+
+## Compiling without AVX support {#compiling-without-avx-support}
+
+Especially older CPUs don't support [AVX](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) (Advanced Vector Extensions) instructions that are used by DLib to optimize their algorithms.
+
+On the affected hardware, errors like `Illegal instruction` will occur. In those cases, AVX support needs to be disabled:
+
+```nix
+self: super: { dlib = super.dlib.override { avxSupport = false; }; }
+```

doc/packages/eclipse.section.md

@@ -0,0 +1,72 @@
+# Eclipse {#sec-eclipse}
+
+The Nix expressions related to the Eclipse platform and IDE are in [`pkgs/applications/editors/eclipse`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/eclipse).
+
+Nixpkgs provides several packages that will install Eclipse in its various forms. These range from the bare-bones Eclipse Platform to the more fully featured Eclipse SDK or Scala-IDE packages, and multiple versions are often available. It is possible to list available Eclipse packages by issuing the command:
+
+```ShellSession
+$ nix-env -f '<nixpkgs>' -qaP -A eclipses --description
+```
+
+Once an Eclipse variant is installed, it can be run using the `eclipse` command, as expected. From within Eclipse, it is then possible to install plugins in the usual manner by either manually specifying an Eclipse update site or by installing the Marketplace Client plugin and using it to discover and install other plugins. This installation method provides an Eclipse installation that closely resembles a manually installed Eclipse.
+
+If you prefer to install plugins in a more declarative manner, then Nixpkgs also offers several Eclipse plugins that can be installed in an _Eclipse environment_. This type of environment is created using the function `eclipseWithPlugins` found inside the `nixpkgs.eclipses` attribute set. This function takes as an argument `{ eclipse, plugins ? [], jvmArgs ? [] }` where `eclipse` is one of the Eclipse packages described above, `plugins` is a list of plugin derivations, and `jvmArgs` is a list of arguments given to the JVM running Eclipse. For example, say you wish to install the latest Eclipse Platform with the popular Eclipse Color Theme plugin and also allow Eclipse to use more RAM. You could then add:
+
+```nix
+{
+  packageOverrides = pkgs: {
+    myEclipse =
+      with pkgs.eclipses;
+      eclipseWithPlugins {
+        eclipse = eclipse-platform;
+        jvmArgs = [ "-Xmx2048m" ];
+        plugins = [ plugins.color-theme ];
+      };
+  };
+}
+```
+
+to your Nixpkgs configuration (`~/.config/nixpkgs/config.nix`) and install it by running `nix-env -f '<nixpkgs>' -iA myEclipse` and afterward running Eclipse as usual. It is possible to find out which plugins are available for installation using `eclipseWithPlugins` by running:
+
+```ShellSession
+$ nix-env -f '<nixpkgs>' -qaP -A eclipses.plugins --description
+```
+
+If there is a need to install plugins that are not available in Nixpkgs then it may be possible to define these plugins outside Nixpkgs using the `buildEclipseUpdateSite` and `buildEclipsePlugin` functions found in the `nixpkgs.eclipses.plugins` attribute set. Use the `buildEclipseUpdateSite` function to install a plugin distributed as an Eclipse update site. This function takes `{ name, src }` as argument, where `src` indicates the Eclipse update site archive. All Eclipse features and plugins within the downloaded update site will be installed. When an update site archive is not available, then the `buildEclipsePlugin` function can be used to install a plugin that consists of a pair of feature and plugin JARs. This function takes an argument `{ name, srcFeature, srcPlugin }` where `srcFeature` and `srcPlugin` are the feature and plugin JARs, respectively.
+
+Expanding the previous example with two plugins using the above functions, we have:
+
+```nix
+{
+  packageOverrides = pkgs: {
+    myEclipse =
+      with pkgs.eclipses;
+      eclipseWithPlugins {
+        eclipse = eclipse-platform;
+        jvmArgs = [ "-Xmx2048m" ];
+        plugins = [
+          plugins.color-theme
+          (plugins.buildEclipsePlugin {
+            name = "myplugin1-1.0";
+            srcFeature = fetchurl {
+              url = "http://…/features/myplugin1.jar";
+              hash = "sha256-123…";
+            };
+            srcPlugin = fetchurl {
+              url = "http://…/plugins/myplugin1.jar";
+              hash = "sha256-123…";
+            };
+          })
+          (plugins.buildEclipseUpdateSite {
+            name = "myplugin2-1.0";
+            src = fetchurl {
+              stripRoot = false;
+              url = "http://…/myplugin2.zip";
+              hash = "sha256-123…";
+            };
+          })
+        ];
+      };
+  };
+}
+```

doc/packages/elm.section.md

@@ -0,0 +1,11 @@
+# Elm {#sec-elm}
+
+To start a development environment, run:
+
+```ShellSession
+nix-shell -p elmPackages.elm elmPackages.elm-format
+```
+
+To update the Elm compiler, see `nixpkgs/pkgs/development/compilers/elm/README.md`.
+
+To package Elm applications, [read about elm2nix](https://github.com/hercules-ci/elm2nix#elm2nix).

doc/packages/emacs.section.md

@@ -0,0 +1,126 @@
+# Emacs {#sec-emacs}
+
+## Configuring Emacs {#sec-emacs-config}
+
+The Emacs package comes with some extra helpers to make it easier to configure. `emacs.pkgs.withPackages` allows you to manage packages from ELPA. This means that you will not have to install those packages from within Emacs. For instance, if you wanted to use `company`, `counsel`, `flycheck`, `ivy`, `magit`, `projectile`, and `use-package`, you could use this as a `~/.config/nixpkgs/config.nix` override:
+
+```nix
+{
+  packageOverrides =
+    pkgs: with pkgs; {
+      myEmacs = emacs.pkgs.withPackages (
+        epkgs:
+        (with epkgs.melpaStablePackages; [
+          company
+          counsel
+          flycheck
+          ivy
+          magit
+          projectile
+          use-package
+        ])
+      );
+    };
+}
+```
+
+You can install it like any other package via `nix-env -iA myEmacs`. However, this will only install those packages. It will not `configure` them for us. To do this, we need to provide a configuration file. Luckily, it is possible to do this from within Nix! By modifying the above example, we can make Emacs load a custom config file. The key is to create a package that provides a `default.el` file in `/share/emacs/site-start/`. Emacs knows to load this file automatically when it starts.
+
+```nix
+{
+  packageOverrides = pkgs: {
+    myEmacsConfig = pkgs.writeText "default.el" ''
+      (eval-when-compile
+        (require 'use-package))
+
+      ;; load some packages
+
+      (use-package company
+        :bind ("<C-tab>" . company-complete)
+        :diminish company-mode
+        :commands (company-mode global-company-mode)
+        :defer 1
+        :config
+        (global-company-mode))
+
+      (use-package counsel
+        :commands (counsel-descbinds)
+        :bind (([remap execute-extended-command] . counsel-M-x)
+               ("C-x C-f" . counsel-find-file)
+               ("C-c g" . counsel-git)
+               ("C-c j" . counsel-git-grep)
+               ("C-c k" . counsel-ag)
+               ("C-x l" . counsel-locate)
+               ("M-y" . counsel-yank-pop)))
+
+      (use-package flycheck
+        :defer 2
+        :config (global-flycheck-mode))
+
+      (use-package ivy
+        :defer 1
+        :bind (("C-c C-r" . ivy-resume)
+               ("C-x C-b" . ivy-switch-buffer)
+               :map ivy-minibuffer-map
+               ("C-j" . ivy-call))
+        :diminish ivy-mode
+        :commands ivy-mode
+        :config
+        (ivy-mode 1))
+
+      (use-package magit
+        :defer
+        :if (executable-find "git")
+        :bind (("C-x g" . magit-status)
+               ("C-x G" . magit-dispatch-popup))
+        :init
+        (setq magit-completing-read-function 'ivy-completing-read))
+
+      (use-package projectile
+        :commands projectile-mode
+        :bind-keymap ("C-c p" . projectile-command-map)
+        :defer 5
+        :config
+        (projectile-global-mode))
+    '';
+
+    myEmacs = emacs.pkgs.withPackages (
+      epkgs:
+      (with epkgs.melpaStablePackages; [
+        (runCommand "default.el" { } ''
+          mkdir -p $out/share/emacs/site-lisp
+          cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
+        '')
+        company
+        counsel
+        flycheck
+        ivy
+        magit
+        projectile
+        use-package
+      ])
+    );
+  };
+}
+```
+
+This provides a fairly full Emacs start file. It will load in addition to the user's personal config. You can always disable it by passing `-q` to the Emacs command.
+
+Sometimes `emacs.pkgs.withPackages` is not enough, as this package set has some priorities imposed on packages (with the lowest priority assigned to GNU-devel ELPA, and the highest for packages manually defined in `pkgs/applications/editors/emacs/elisp-packages/manual-packages`). But you can't control these priorities when some package is installed as a dependency. You can override it on a per-package-basis, providing all the required dependencies manually, but it's tedious and there is always a possibility that an unwanted dependency will sneak in through some other package. To completely override such a package, you can use `overrideScope`.
+
+```nix
+let
+  overrides = self: super: rec {
+    haskell-mode = self.melpaPackages.haskell-mode;
+    # ...
+  };
+in
+((emacsPackagesFor emacs).overrideScope overrides).withPackages (
+  p: with p; [
+    # here both these package will use haskell-mode of our own choice
+    ghc-mod
+    dante
+  ]
+)
+```
+}

doc/packages/etc-files.section.md

@@ -0,0 +1,18 @@
+# /etc files {#etc}
+
+Certain calls in glibc require access to runtime files found in `/etc` such as `/etc/protocols` or `/etc/services` -- [getprotobyname](https://linux.die.net/man/3/getprotobyname) is one such function.
+
+On non-NixOS distributions, these files are typically provided by packages (i.e., [netbase](https://packages.debian.org/sid/netbase)) if not already pre-installed in your distribution. This can cause non-reproducibility for code if they rely on these files being present.
+
+If [iana-etc](https://hydra.nixos.org/job/nixos/trunk-combined/nixpkgs.iana-etc.x86_64-linux) is part of your `buildInputs`, then it will set the environment variables `NIX_ETC_PROTOCOLS` and `NIX_ETC_SERVICES` to the corresponding files in the package through a setup hook.
+
+
+```bash
+> nix-shell -p iana-etc
+
+[nix-shell:~]$ env | grep NIX_ETC
+NIX_ETC_SERVICES=/nix/store/aj866hr8fad8flnggwdhrldm0g799ccz-iana-etc-20210225/etc/services
+NIX_ETC_PROTOCOLS=/nix/store/aj866hr8fad8flnggwdhrldm0g799ccz-iana-etc-20210225/etc/protocols
+```
+
+Nixpkgs's version of [glibc](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/glibc/default.nix) has been patched to check for the existence of these environment variables. If the environment variables are *not* set, then it will attempt to find the files at the default location within `/etc`.

doc/packages/firefox.section.md

@@ -0,0 +1,55 @@
+# Firefox {#sec-firefox}
+
+## Build wrapped Firefox with extensions and policies {#build-wrapped-firefox-with-extensions-and-policies}
+
+The `wrapFirefox` function allows to pass policies, preferences and extensions that are available to Firefox. With the help of `fetchFirefoxAddon` this allows to build a Firefox version that already comes with add-ons pre-installed:
+
+```nix
+{
+  # Nix firefox addons only work with the firefox-esr package.
+  myFirefox = wrapFirefox firefox-esr-unwrapped {
+    nixExtensions = [
+      (fetchFirefoxAddon {
+        name = "ublock"; # Has to be unique!
+        url = "https://addons.mozilla.org/firefox/downloads/file/3679754/ublock_origin-1.31.0-an+fx.xpi";
+        hash = "sha256-2e73AbmYZlZXCP5ptYVcFjQYdjDp4iPoEPEOSCVF5sA=";
+      })
+    ];
+
+    extraPolicies = {
+      CaptivePortal = false;
+      DisableFirefoxStudies = true;
+      DisablePocket = true;
+      DisableTelemetry = true;
+      DisableFirefoxAccounts = true;
+      FirefoxHome = {
+        Pocket = false;
+        Snippets = false;
+      };
+      UserMessaging = {
+        ExtensionRecommendations = false;
+        SkipOnboarding = true;
+      };
+      SecurityDevices = {
+        # Use a proxy module rather than `nixpkgs.config.firefox.smartcardSupport = true`
+        "PKCS#11 Proxy Module" = "${pkgs.p11-kit}/lib/p11-kit-proxy.so";
+      };
+    };
+
+    extraPrefs = ''
+      // Show more ssl cert infos
+      lockPref("security.identityblock.show_extended_validation", true);
+    '';
+  };
+}
+```
+
+If `nixExtensions != null`, then all manually installed add-ons will be uninstalled from your browser profile.
+To view available enterprise policies, visit [enterprise policies](https://github.com/mozilla/policy-templates#enterprisepoliciesenabled)
+or type into the Firefox URL bar: `about:policies#documentation`.
+Nix installed add-ons do not have a valid signature, which is why signature verification is disabled. This does not compromise security because downloaded add-ons are checksummed and manual add-ons can't be installed. Also, make sure that the `name` field of `fetchFirefoxAddon` is unique. If you remove an add-on from the `nixExtensions` array, rebuild and start Firefox: the removed add-on will be completely removed with all of its settings.
+
+## Troubleshooting {#sec-firefox-troubleshooting}
+If add-ons are marked as broken or the signature is invalid, make sure you have Firefox ESR installed. Normal Firefox does not provide the ability anymore to disable signature verification for add-ons; thus, Nix add-ons get disabled by the normal Firefox binary.
+
+If add-ons do not appear installed despite being defined in your nix configuration file, reset the local add-on state of your Firefox profile by clicking `Help -> More Troubleshooting Information -> Refresh Firefox`. This can happen if you switch from manual add-on mode to nix add-on mode and then back to manual mode and then again to nix add-on mode.

doc/packages/fish.section.md

@@ -0,0 +1,53 @@
+# Fish {#sec-fish}
+
+Fish is a "smart and user-friendly command line shell" with support for plugins.
+
+
+## Vendor Fish scripts {#sec-fish-vendor}
+
+Any package may ship its own Fish completions, configuration snippets, and
+functions. Those should be installed to
+`$out/share/fish/vendor_{completions,conf,functions}.d` respectively.
+
+When the `programs.fish.enable` and
+`programs.fish.vendor.{completions,config,functions}.enable` options from the
+NixOS Fish module are set to true, those paths are symlinked in the current
+system environment and are automatically loaded by Fish.
+
+
+## Packaging Fish plugins {#sec-fish-plugins-pkg}
+
+While packages providing standalone executables belong to the top level,
+packages which have the sole purpose of extending Fish belong to the
+`fishPlugins` scope and should be registered in
+`pkgs/shells/fish/plugins/default.nix`.
+
+The `buildFishPlugin` utility function can be used to automatically copy Fish
+scripts from `$src/{completions,conf,conf.d,functions}` to the standard vendor
+installation paths. It also sets up the test environment so that the optional
+`checkPhase` is executed in a Fish shell with other already packaged plugins
+and package-local Fish functions specified in `checkPlugins` and
+`checkFunctionDirs` respectively.
+
+See `pkgs/shells/fish/plugins/pure.nix` for an example of Fish plugin package
+using `buildFishPlugin` and running unit tests with the `fishtape` test runner.
+
+
+## Fish wrapper {#sec-fish-wrapper}
+
+The `wrapFish` package is a wrapper around Fish which can be used to create
+Fish shells initialized with some plugins as well as completions, configuration
+snippets and functions sourced from the given paths. This provides a convenient
+way to test Fish plugins and scripts without having to alter the environment.
+
+```nix
+wrapFish {
+  pluginPkgs = with fishPlugins; [
+    pure
+    foreign-env
+  ];
+  completionDirs = [ ];
+  functionDirs = [ ];
+  confDirs = [ "/path/to/some/fish/init/dir/" ];
+}
+```

doc/packages/fuse.section.md

@@ -0,0 +1,45 @@
+# FUSE {#sec-fuse}
+
+Some packages rely on
+[FUSE](https://www.kernel.org/doc/html/latest/filesystems/fuse.html) to provide
+support for additional filesystems not supported by the kernel.
+
+In general, FUSE software is primarily developed for Linux but many of them can
+also run on macOS. Nixpkgs supports FUSE packages on macOS, but it requires
+[macFUSE](https://osxfuse.github.io) to be installed outside of Nix. macFUSE
+currently isn't packaged in Nixpkgs, mainly because it includes a kernel
+extension, which isn't supported by Nix outside of NixOS.
+
+If a package fails to run on macOS with an error message similar to the
+following, it's a likely sign that you need to have macFUSE installed.
+
+    dyld: Library not loaded: /usr/local/lib/libfuse.2.dylib
+    Referenced from: /nix/store/w8bi72bssv0bnxhwfw3xr1mvn7myf37x-sshfs-fuse-2.10/bin/sshfs
+    Reason: image not found
+    [1]    92299 abort      /nix/store/w8bi72bssv0bnxhwfw3xr1mvn7myf37x-sshfs-fuse-2.10/bin/sshfs
+
+Package maintainers may often encounter the following error when building FUSE
+packages on macOS:
+
+    checking for fuse.h... no
+    configure: error: No fuse.h found.
+
+This happens on autoconf-based projects that use `AC_CHECK_HEADERS` or
+`AC_CHECK_LIBS` to detect libfuse, and will occur even when the `fuse` package
+is included in `buildInputs`. It happens because libfuse headers throw an error
+on macOS if the `FUSE_USE_VERSION` macro is undefined. Many projects do define
+`FUSE_USE_VERSION`, but only inside C source files. This results in the above
+error at configure time because the configure script would attempt to compile
+sample FUSE programs without defining `FUSE_USE_VERSION`.
+
+There are two possible solutions for this problem in Nixpkgs:
+
+1. Pass `FUSE_USE_VERSION` to the configure script by adding
+   `CFLAGS=-DFUSE_USE_VERSION=25` in `configureFlags`. The actual value would
+   have to match the definition used in the upstream source code.
+2. Remove `AC_CHECK_HEADERS` / `AC_CHECK_LIBS` for libfuse.
+
+However, a better solution might be to fix the build script upstream to use
+`PKG_CHECK_MODULES` instead. This approach wouldn't suffer from the problem that
+`AC_CHECK_HEADERS`/`AC_CHECK_LIBS` has at the price of introducing a dependency
+on pkg-config.

doc/packages/geant4.section.md

@@ -0,0 +1,15 @@
+# Geant4 {#geant4}
+
+[Geant4](https://www.geant4.org/) is a toolkit for simulating how particles pass through matter. It is available through the `geant4` package.
+
+## Setup hook {#geant4-hook}
+
+The setup hook included in the package applies the environment variables set by the [`geant4.sh` script](https://github.com/Geant4/geant4/blob/master/cmake/Modules/G4ConfigureGNUMakeHelpers.cmake#L4-L55), which is typically necessary for compiling `make`-based programs that depend on Geant4.
+
+## Datasets {#geant4-datasets}
+
+All of [the Geant4 datasets provided by CERN](https://geant4.web.cern.ch/support/download) are available through the `geant4.data` attrset.
+
+### Setup hook {#geant4-datasets-hook}
+
+The hook provided by the packages in `geant4.data` will set an appropriate environment variable in the form of `G4[...]DATA`. For example, for the `G4RadioactiveDecay` dataset, the `G4RADIOACTIVEDATA` environment variable is set to the value expected by Geant4.

doc/packages/ibus.section.md

@@ -0,0 +1,48 @@
+# ibus-engines.typing-booster {#sec-ibus-typing-booster}
+
+This package is an ibus-based completion method to speed up typing.
+
+## Activating the engine {#sec-ibus-typing-booster-activate}
+
+IBus needs to be configured accordingly to activate `typing-booster`. The configuration depends on the desktop manager in use. For detailed instructions, please refer to the [upstream docs](https://mike-fabian.github.io/ibus-typing-booster/).
+
+On NixOS, you need to explicitly enable `ibus` with given engines before customizing your desktop to use `typing-booster`. This can be achieved using the `ibus` module:
+
+```nix
+{ pkgs, ... }:
+{
+  i18n.inputMethod = {
+    enable = true;
+    type = "ibus";
+    ibus.engines = with pkgs.ibus-engines; [ typing-booster ];
+  };
+}
+```
+
+## Using custom hunspell dictionaries {#sec-ibus-typing-booster-customize-hunspell}
+
+The IBus engine is based on `hunspell` to support completion in many languages. By default, the dictionaries `de-de`, `en-us`, `fr-moderne` `es-es`, `it-it`, `sv-se` and `sv-fi` are in use. To add another dictionary, the package can be overridden like this:
+
+```nix
+ibus-engines.typing-booster.override {
+  langs = [
+    "de-at"
+    "en-gb"
+  ];
+}
+```
+
+_Note: each language passed to `langs` must be an attribute name in `pkgs.hunspellDicts`._
+
+## Built-in emoji picker {#sec-ibus-typing-booster-emoji-picker}
+
+The `ibus-engines.typing-booster` package contains a program named `emoji-picker`. To display all emojis correctly, a special font such as `noto-fonts-color-emoji` is needed:
+
+On NixOS, it can be installed using the following expression:
+
+```nix
+{ pkgs, ... }:
+{
+  fonts.packages = with pkgs; [ noto-fonts-color-emoji ];
+}
+```

doc/packages/index.md

@@ -0,0 +1,37 @@
+# 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.
+
+```{=include=} sections
+citrix.section.md
+darwin-builder.section.md
+dlib.section.md
+eclipse.section.md
+elm.section.md
+emacs.section.md
+firefox.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
+opengl.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
+xorg.section.md
+uv.section.md
+build-support.md
+```

doc/packages/inkscape.section.md

@@ -0,0 +1,27 @@
+# Inkscape {#sec-inkscape}
+
+[Inkscape](https://inkscape.org) is a powerful vector graphics editor.
+
+## Plugins {#inkscape-plugins}
+Inkscape plugins are collected in the [`inkscape-extensions`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages) package set.
+To enable them, use an override on `inkscape-with-extensions`:
+
+```nix
+inkscape-with-extensions.override {
+  inkscapeExtensions = with inkscape-extensions; [ inkstitch ];
+}
+```
+
+Similarly, this works in the shell:
+
+```bash
+$ nix-shell -p 'inkscape-with-extensions.override { inkscapeExtensions = with inkscape-extensions; [inkstitch]; }'
+[nix-shell:~]$ # Ink/Stitch is now available via the extension menu
+[nix-shell:~]$ inkscape
+```
+
+All available extensions can be enabled by passing `inkscapeExtensions = null;`.
+
+::: {.note}
+Loading the Inkscape extensions stand-alone (without using `override`) does not affect Inkscape at all.
+:::

doc/packages/kakoune.section.md

@@ -0,0 +1,7 @@
+# Kakoune {#sec-kakoune}
+
+Kakoune can be built to autoload plugins:
+
+```nix
+(kakoune.override { plugins = with pkgs.kakounePlugins; [ parinfer-rust ]; })
+```

doc/packages/krita.section.md

@@ -0,0 +1,37 @@
+# Krita {#sec-krita}
+
+## Python plugins {#krita-python-plugins}
+
+"pykrita" plugins should be installed following
+[Krita's manual](https://docs.krita.org/en/user_manual/python_scripting/install_custom_python_plugin.html).
+This generally involves extracting the extension to `~/.local/share/krita/pykrita/`.
+
+## Binary plugins {#krita-binary-plugins}
+
+Binary plugins are Dynamically Linked Libraries to be loaded by Krita.
+
+_Note: You most likely won't need to deal with binary plugins,
+all known plugins are bundled and enabled by default._
+
+### Installing binary plugins {#krita-install-binary-plugins}
+
+You can choose what plugins are added to Krita by overriding the
+`binaryPlugins` attribute.
+
+If you want to add plugins instead of replacing, you can read the
+list of previous plugins via `pkgs.krita.binaryPlugins`:
+
+```nix
+(pkgs.krita.override (old: {
+  binaryPlugins = old.binaryPlugins ++ [ your-plugin ];
+}))
+```
+
+### Example structure of a binary plugin {#krita-binary-plugin-structure}
+
+```
+/nix/store/00000000000000000000000000000000-krita-plugin-example-1.2.3
+└── lib
+   └── kritaplugins
+      └── krita_example.so
+```

doc/packages/lhapdf.section.md

@@ -0,0 +1,11 @@
+# LHAPDF {#lhapdf}
+
+[LHAPDF](https://lhapdf.hepforge.org/) is a tool for evaluating parton distribution functions (PDFs) in high-energy physics. LHAPDF is available in the `lhapdf` package.
+
+## PDF sets {#lhapdf-sets}
+
+All of [the PDF sets made available by the LHAPDF project](https://lhapdf.hepforge.org/pdfsets.html) are available through the `lhapdf.pdf_sets` attrset.
+
+### Setup hook {#lhapdf-sets-hook}
+
+Each package provided in the `lhapdf.pdf_sets` attrset contains a setup hook which adds itself to [the `LHAPDF_DATA_PATH` environment variable](https://lhapdf.hepforge.org/#sets).

doc/packages/linux.section.md

@@ -0,0 +1,160 @@
+# Linux kernel {#sec-linux-kernel}
+
+The Nix expressions to build the Linux kernel are in [`pkgs/os-specific/linux/kernel`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/os-specific/linux/kernel).
+
+The function [`pkgs.buildLinux`](https://github.com/NixOS/nixpkgs/blob/d77bda728d5041c1294a68fb25c79e2d161f62b9/pkgs/os-specific/linux/kernel/generic.nix) builds a kernel with [common configuration values](https://github.com/NixOS/nixpkgs/blob/d77bda728d5041c1294a68fb25c79e2d161f62b9/pkgs/os-specific/linux/kernel/common-config.nix).
+This is the preferred option unless you have a very specific use case.
+Most kernels packaged in Nixpkgs are built that way, and it will also generate kernels suitable for NixOS.
+[`pkgs.linuxManualConfig`](https://github.com/NixOS/nixpkgs/blob/d77bda728d5041c1294a68fb25c79e2d161f62b9/pkgs/os-specific/linux/kernel/manual-config.nix) requires a complete configuration to be passed.
+It has fewer additional features than `pkgs.buildLinux`, which provides common configuration values and exposes the `features` attribute, as explained below.
+
+Both functions have an argument `kernelPatches` which should be a list of `{name, patch, extraConfig}` attribute sets, where `name` is the name of the patch (which is included in the kernel’s `meta.description` attribute), `patch` is the patch itself (possibly compressed), and `extraConfig` (optional) is a string specifying extra options to be concatenated to the kernel configuration file (`.config`).
+
+The kernel derivation created with `pkgs.buildLinux` exports an attribute `features` specifying whether optional functionality is or isn’t enabled. This is used in NixOS to implement kernel-specific behaviour.
+
+If you are using a kernel packaged in Nixpkgs, you can customize it by overriding its arguments. For details on how each argument affects the generated kernel, refer to [the `pkgs.buildLinux` source code](https://github.com/NixOS/nixpkgs/blob/d77bda728d5041c1294a68fb25c79e2d161f62b9/pkgs/os-specific/linux/kernel/generic.nix).
+
+:::{.example #ex-overriding-kernel-derivation}
+
+# Overriding the kernel derivation
+
+Assuming you are using the kernel from `pkgs.linux_latest`:
+
+```nix
+pkgs.linux_latest.override {
+  ignoreConfigErrors = true;
+  autoModules = false;
+  kernelPreferBuiltin = true;
+  structuredExtraConfig = with lib.kernel; {
+    DEBUG_KERNEL = yes;
+    FRAME_POINTER = yes;
+    KGDB = yes;
+    KGDB_SERIAL_CONSOLE = yes;
+    DEBUG_INFO = yes;
+  };
+}
+```
+
+:::
+
+## Manual kernel configuration {#sec-manual-kernel-configuration}
+
+Sometimes it may not be desirable to use kernels built with `pkgs.buildLinux`, especially if most of the common configuration has to be altered or disabled to achieve a kernel as expected by the target use case.
+An example of this is building a kernel for use in a VM or micro VM. You can use `pkgs.linuxPackages_custom` in these cases. It requires the `src`, `version`, and `configfile` attributes to be specified.
+
+:::{.example #ex-using-linux-manual-config}
+
+# Using `pkgs.linuxPackages_custom` with a specific source, version, and config file
+
+```nix
+{ pkgs, ... }:
+pkgs.linuxPackages_custom {
+  version = "6.1.55";
+  src = pkgs.fetchurl {
+    url = "https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-${version}.tar.xz";
+    hash = "sha256-qH4kHsFdU0UsTv4hlxOjdp2IzENrW5jPbvsmLEr/FcA=";
+  };
+  configfile = ./path_to_config_file;
+}
+```
+
+If necessary, the version string can be slightly modified to explicitly mark it as a custom version. If you do so, ensure the `modDirVersion` attribute matches the source's version, otherwise the build will fail.
+
+```nix
+{ pkgs, ... }:
+pkgs.linuxPackages_custom {
+  version = "6.1.55-custom";
+  modDirVersion = "6.1.55";
+  src = pkgs.fetchurl {
+    url = "https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-${modDirVersion}.tar.xz";
+    hash = "sha256-qH4kHsFdU0UsTv4hlxOjdp2IzENrW5jPbvsmLEr/FcA=";
+  };
+  configfile = ./path_to_config_file;
+}
+```
+
+:::
+
+Additional attributes can be used with `linuxManualConfig` for further customisation instead of `linuxPackages_custom`. You're encouraged to read [the `pkgs.linuxManualConfig` source code](https://github.com/NixOS/nixpkgs/blob/d77bda728d5041c1294a68fb25c79e2d161f62b9/pkgs/os-specific/linux/kernel/manual-config.nix) to understand how to use them.
+
+To edit the `.config` file for Linux X.Y from within Nix, proceed as follows:
+
+```ShellSession
+$ nix-shell '<nixpkgs>' -A linuxKernel.kernels.linux_X_Y.configEnv
+$ unpackPhase
+$ cd linux-*
+$ make nconfig
+```
+
+## Developing kernel modules {#sec-linux-kernel-developing-modules}
+
+When developing kernel modules it's often convenient to run the edit-compile-run loop as quickly as possible.
+See the snippet below as an example.
+
+:::{.example #ex-edit-compile-run-kernel-modules}
+
+# Edit-compile-run loop when developing `mellanox` drivers
+
+```ShellSession
+$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev
+$ nix-shell '<nixpkgs>' -A linuxPackages.kernel
+$ unpackPhase
+$ cd linux-*
+$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
+# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
+```
+
+:::
+
+## Maintainer information {#sec-linux-kernel-maintainer-information}
+
+### Updating kernels {#sec-linux-updates}
+
+Updating all kernels can be done with the following script:
+
+```ShellSession
+$ pkgs/os-specific/linux/kernel/update.sh
+```
+
+The change gets submitted like this:
+
+* File a PR against `staging-nixos`.
+  * Add a `backport release-XX.XX` label for an automated backport.
+    We don't expect many other changes on that branch to require a backport, hence there's no such branch for stable.
+    By using an additional PR, we get the automatic backport against stable without manual cherry-picks.
+* Merge into `staging-nixos`.
+* File as PR from `staging-nixos` against `master`.
+* When all status checks are green, merge.
+
+### Add a new (major) version of the Linux kernel {#sec-linux-add-new-kernel-version}
+
+* When running `./pkgs/os-specific/linux/kernel/update.sh`, new kernel majors get discovered automatically.
+* Prepare all Nix expressions for the new kernel
+  * Instantiate the new kernel in `pkgs/top-level/linux-kernels.nix` in the `kernels`-section.
+    ```nix
+    {
+      linux_X_Y = callPackage ../os-specific/linux/kernel/mainline.nix {
+        branch = "X.Y";
+        kernelPatches = [
+          # any new patches required (it makes to look which patches are used by its predecessor)
+        ];
+      };
+    }
+    ```
+  * Instantiate the package-set in `vanillaPackages`:
+    ```nix
+    {
+      linux_X_Y = recurseIntoAttrs (packagesFor kernels.linux_X_Y);
+    }
+    ```
+  * Update `linux_latest` to the new attribute.
+* __SQUASH__ the changes into the `linux: init at …` commit.
+* If a new hardened is available:
+  * Instantiate a `linux_X_Y_hardened = hardenedKernelsFor kernels.linux_X_Y { };` in `kernels` and
+    `linux_X_Y_hardened = hardenedKernelFor kernels.linux_X_Y { };` in the `packages`-section.
+  * Make sure to remove the hardened variant of the previous kernel version unless it's LTS.
+    We only support the latest and latest LTS version of hardened.
+* If no new hardened kernel is available:
+  * Keep the previously latest kernel until its mainline counterpart gets removed.
+    After that `linux_hardened` points to the latest LTS supported by hardened.
+* __SQUASH__ the changes into the `linux_X_Y_hardened: init at …` commit.

doc/packages/locales.section.md

@@ -0,0 +1,5 @@
+# Locales {#locales}
+
+To allow simultaneous use of packages linked against different versions of `glibc` with different locale archive formats, Nixpkgs patches `glibc` to rely on the `LOCALE_ARCHIVE` environment variable.
+
+On non-NixOS distributions, this variable is obviously not set. This can cause regressions in language support or even crashes in some Nixpkgs-provided programs. The simplest way to mitigate this problem is exporting the `LOCALE_ARCHIVE` variable pointing to `${glibcLocales}/lib/locale/locale-archive`. The drawback (and the reason this is not the default) is the relatively large (a hundred MiB) size of the full set of locales. It is possible to build a custom set of locales by overriding parameters `allLocales` and `locales` of the package.

doc/packages/nginx.section.md

@@ -0,0 +1,11 @@
+# Nginx {#sec-nginx}
+
+[Nginx](https://nginx.org) is a reverse proxy and lightweight webserver.
+
+## ETags on static files served from the Nix store {#sec-nginx-etag}
+
+HTTP has a couple of different mechanisms for caching to prevent clients from having to download the same content repeatedly if a resource has not changed since the last time it was requested. When nginx is used as a server for static files, it implements the caching mechanism based on the [`Last-Modified`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) response header automatically; unfortunately, it works by using filesystem timestamps to determine the value of the `Last-Modified` header. This doesn't give the desired behavior when the file is in the Nix store because all file timestamps are set to 0 (for reasons related to build reproducibility).
+
+Fortunately, HTTP supports an alternative (and more effective) caching mechanism: the [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) response header. The value of the `ETag` header specifies some identifier for the particular content that the server is sending (e.g., a hash). When a client makes a second request for the same resource, it sends that value back in an `If-None-Match` header. If the ETag value is unchanged, then the server does not need to resend the content.
+
+The nginx package in Nixpkgs is patched such that when nginx serves a file out of `/nix/store`, the hash in the store path is used as the `ETag` header in the HTTP response, thus providing proper caching functionality. With NixOS 24.05 and later, the `ETag` additionally includes the response content length, to ensure files served with static compression do not share `ETag`s with their uncompressed version. This `ETag` functionality is enabled automatically; you do not need to modify any configuration to get this behavior.

doc/packages/opengl.section.md

@@ -0,0 +1,15 @@
+# OpenGL {#sec-opengl}
+
+OpenGL support varies depending on which hardware is used and which drivers are available and loaded.
+
+Broadly, we support both GL vendors: Mesa and NVIDIA.
+
+## NixOS Desktop {#nixos-desktop}
+
+The NixOS desktop or other non-headless configurations are the primary target for OpenGL libraries and applications. The current solution for discovering which drivers are available is based on [libglvnd](https://gitlab.freedesktop.org/glvnd/libglvnd). `libglvnd` performs "vendor-neutral dispatch", trying a variety of techniques to find the system's GL implementation. In practice, this will be either via standard GLX for X11 users or EGL for Wayland users, and supporting either NVIDIA or Mesa extensions.
+
+## Nix on GNU/Linux {#nix-on-gnulinux}
+
+If you are using a non-NixOS GNU/Linux/X11 desktop with free software video drivers, consider launching OpenGL-dependent programs from Nixpkgs with Nixpkgs versions of `libglvnd` and `mesa` in `LD_LIBRARY_PATH`. For Mesa drivers, the Linux kernel version doesn't have to match nixpkgs.
+
+For proprietary video drivers, you might have luck with also adding the corresponding video driver package.

doc/packages/python-tree-sitter.section.md

@@ -0,0 +1,56 @@
+# Python Tree Sitter {#python-tree-sitter}
+
+[Tree Sitter](https://tree-sitter.github.io/tree-sitter/) is a framework for building grammars for programming languages. It generates and uses syntax trees from source files, which are useful for code analysis, tooling, and syntax highlighting.
+
+Python bindings for Tree Sitter grammars are provided through the [py-tree-sitter](https://github.com/tree-sitter/py-tree-sitter) module. The Nix package `python3Packages.tree-sitter-grammars` provides pre-built grammars for various languages.
+
+For example, to experiment with the Rust grammar, you can create a shell environment with the following configuration:
+
+```nix
+{
+  pkgs ? import <nixpkgs> { },
+}:
+
+pkgs.mkShell {
+  name = "py-tree-sitter-dev-shell";
+
+  buildInputs = with pkgs; [
+    (python3.withPackages (
+      ps: with ps; [
+        tree-sitter
+        tree-sitter-grammars.tree-sitter-rust
+      ]
+    ))
+  ];
+}
+```
+
+Once inside the shell, the following Python code demonstrates how to parse a Rust code snippet:
+
+```python
+# Import the Tree Sitter library and Rust grammar
+import tree_sitter
+import tree_sitter_rust
+
+# Load the Rust grammar and initialize the parser
+rust = tree_sitter.Language(tree_sitter_rust.language())
+parser = tree_sitter.Parser(rust)
+
+# Parse a Rust snippet
+tree = parser.parse(
+    bytes(
+        """
+        fn main() {
+          println!("Hello, world!");
+        }
+        """,
+        "utf8"
+    )
+)
+
+# Display the resulting syntax tree
+print(tree.root_node)
+```
+
+The `tree_sitter_rust.language()` function references the Rust grammar loaded in the Nix shell. The resulting tree allows you to programmatically inspect the structure of the code.
+

doc/packages/shell-helpers.section.md

@@ -0,0 +1,12 @@
+# Interactive shell helpers {#sec-shell-helpers}
+
+Some packages provide shell integration to be more useful. But unlike other systems, nix doesn't have a standard `share` directory location. This is why a bunch of `PACKAGE-share` scripts are shipped that print the location of the corresponding shared folder. The current list of such packages is as follows:
+
+- `fzf` : `fzf-share`
+
+E.g. `fzf` can then be used in the `.bashrc` like this:
+
+```bash
+source "$(fzf-share)/completion.bash"
+source "$(fzf-share)/key-bindings.bash"
+```

doc/packages/steam.section.md

@@ -0,0 +1,48 @@
+# Steam {#sec-steam}
+
+## Steam in Nix {#sec-steam-nix}
+
+Steam is distributed as a `.deb` file, for now only as an i686 package (the amd64 package only has documentation). When unpacked, it has a script called `steam` that in Ubuntu (their target distro) would go to `/usr/bin`. When run for the first time, this script copies some files to the user's home, which include another script that is ultimately responsible for launching the steam binary, which is also in `$HOME`.
+
+Nix problems and constraints:
+
+- We don't have `/bin/bash` and many scripts point there. Same thing for `/usr/bin/python`.
+- We don't have the dynamic loader in `/lib`.
+- The `steam.sh` script in `$HOME` cannot be patched, as it is checked and rewritten by steam.
+- The steam binary cannot be patched, it's also checked.
+
+The current approach to deploy Steam in NixOS is composing a FHS-compatible chroot environment, as documented [here](https://sandervanderburg.blogspot.com/2013/09/composing-fhs-compatible-chroot.html). This allows us to have binaries in the expected paths without disrupting the system and to avoid patching them to work in a non-FHS environment.
+
+## How to play {#sec-steam-play}
+
+Use `programs.steam.enable = true;` if you want to add steam to `systemPackages` and also enable a few workarounds as well as Steam controller support or other Steam supported controllers such as the DualShock 4 or Nintendo Switch Pro Controller.
+
+## Troubleshooting {#sec-steam-troub}
+
+- **Steam fails to start. What do I do?**
+
+  Try to run
+
+  ```ShellSession
+  strace steam
+  ```
+
+  to see what is causing steam to fail.
+
+- **Using the FOSS Radeon or nouveau (nvidia) drivers**
+
+  - Steam ships statically linked with a version of `libcrypto` that conflicts with the one dynamically loaded by radeonsi_dri.so. If you get the error:
+
+    ```
+    steam.sh: line 713: 7842 Segmentation fault (core dumped)
+    ```
+
+    have a look at [this pull request](https://github.com/NixOS/nixpkgs/pull/20269).
+
+## steam-run {#sec-steam-run}
+
+The FHS-compatible chroot used for Steam can also be used to run other Linux games that expect a FHS environment. To use it, install the `steam-run` package and run the game with:
+
+```
+steam-run ./foo
+```

doc/packages/treefmt.section.md

@@ -0,0 +1,23 @@
+# treefmt {#treefmt}
+
+[treefmt](https://github.com/numtide/treefmt) streamlines the process of applying formatters to your project, making it a breeze with just one command line.
+
+The [`treefmt` package](https://search.nixos.org/packages?channel=unstable&show=treefmt)
+provides functions for configuring treefmt using the module system, which are [documented below](#sec-functions-library-treefmt), along with [their options](#sec-treefmt-options-reference).
+
+Alternatively, treefmt can be configured using [treefmt-nix](https://github.com/numtide/treefmt-nix).
+
+```{=include=} sections auto-id-prefix=auto-generated-treefmt-functions
+treefmt-functions.section.md
+```
+
+## Options Reference {#sec-treefmt-options-reference}
+
+The following attributes can be passed to [`withConfig`](#pkgs.treefmt.withConfig) or [`evalConfig`](#pkgs.treefmt.evalConfig):
+
+```{=include=} options
+id-prefix: opt-treefmt-
+list-id: configuration-variable-list
+source: ../treefmt-options.json
+```
+

doc/packages/urxvt.section.md

@@ -0,0 +1,83 @@
+# Urxvt {#sec-urxvt}
+
+Urxvt, also known as rxvt-unicode, is a highly customizable terminal emulator.
+
+## Configuring urxvt {#sec-urxvt-conf}
+
+In `nixpkgs`, urxvt is provided by the package `rxvt-unicode`. It can be configured to include your choice of plugins, reducing its closure size from the default configuration which includes all available plugins. To make use of this functionality, use an overlay or directly install an expression that overrides its configuration, such as:
+
+```nix
+rxvt-unicode.override {
+  configure =
+    { availablePlugins, ... }:
+    {
+      plugins = with availablePlugins; [
+        perls
+        resize-font
+        vtwheel
+      ];
+    };
+}
+```
+
+If the `configure` function returns an attrset without the `plugins` attribute, `availablePlugins` will be used automatically.
+
+In order to add plugins but also keep all default plugins installed, it is possible to use the following method:
+
+```nix
+rxvt-unicode.override {
+  configure =
+    { availablePlugins, ... }:
+    {
+      plugins = (builtins.attrValues availablePlugins) ++ [ custom-plugin ];
+    };
+}
+```
+
+To get a list of all the plugins available, open the Nix REPL and run
+
+```ShellSession
+$ nix repl
+:l <nixpkgs>
+map (p: p.name) pkgs.rxvt-unicode.plugins
+```
+
+Alternatively, if your shell is bash or zsh and have completion enabled, type `nixpkgs.rxvt-unicode.plugins.<tab>`.
+
+In addition to `plugins` the options `extraDeps` and `perlDeps` can be used to install extra packages. `extraDeps` can be used, for example, to provide `xsel` (a clipboard manager) to the clipboard plugin, without installing it globally:
+
+```nix
+rxvt-unicode.override {
+  configure =
+    { availablePlugins, ... }:
+    {
+      pluginsDeps = [ xsel ];
+    };
+}
+```
+
+`perlDeps` is a handy way to provide Perl packages to your custom plugins (in `$HOME/.urxvt/ext`). For example, if you need `AnyEvent` you can do:
+
+```nix
+rxvt-unicode.override {
+  configure =
+    { availablePlugins, ... }:
+    {
+      perlDeps = with perlPackages; [ AnyEvent ];
+    };
+}
+```
+
+## Packaging urxvt plugins {#sec-urxvt-pkg}
+
+Urxvt plugins reside in `pkgs/applications/misc/rxvt-unicode-plugins`. To add a new plugin, create an expression in a subdirectory and add the package to the set in `pkgs/applications/misc/rxvt-unicode-plugins/default.nix`.
+
+A plugin can be any kind of derivation; the only requirement is that it should always install perl scripts in `$out/lib/urxvt/perl`. Look for existing plugins for examples.
+
+If the plugin is itself a Perl package that needs to be imported from other plugins or scripts, add the following passthrough:
+
+```nix
+{ passthru.perlPackages = [ "self" ]; }
+```
+
+This will make the urxvt wrapper pick up the dependency and set up the Perl path accordingly.

doc/packages/uv.section.md

@@ -0,0 +1,22 @@
+# uv {#sec-uv}
+
+`uv` is an extremely fast Python package installer and resolver, written in Rust.
+It manages project dependencies and environments, with support for lockfiles, workspaces, and more.
+
+Due to `uv` being unaware that it is running on a NixOS system, by default, it will fetch dynamically-linked Python executables that will fail to run, as NixOS cannot run executables intended for generic Linux environments out of the box.
+To learn more on this, please visit
+https://nix.dev/guides/faq.html#how-to-run-non-nix-executables
+
+There are two ways to mitigate this:
+
+1. Provide `uv` with a statically-linked Python executable (ideally from `nixpkgs`) via the [`UV_PYTHON` environment variable](https://docs.astral.sh/uv/reference/environment/#uv_python). Alternatively, the `--python` flag can also be used, but this is easy to forget. It is also helpful to forbid `uv` from downloading any Python binaries via the [`UV_PYTHON_DOWNLOADS` environment variable](https://docs.astral.sh/uv/reference/environment/#uv_python_downloads) by setting it to `never`.
+These variables can be set in `shell.nix` and `.env` files, which can be redistributed with the project to ensure other NixOS machines can execute the project.
+
+2. Add `programs.nix-ld.enable = true` to your NixOS config. While functional, the previous option is to be preferred, as this is the "works on my machine" option, because redistributing Python projects that use `uv` to another NixOS machine that does not have `nix-ld` enabled will cause the same errors to occur.
+
+Additionally, there is the issue of modules from PyPI vendoring dynamically-linked libraries, such as `numpy`, which will also fail to work.
+This topic is not local to `uv`, but is deserving of documentation nonetheless.
+Setting `LD_LIBRARY_PATH` should be the solution of choice here. Either:
+
+1. Use `lib.makeLibraryPath` to set `LD_LIBRARY_PATH` from a `shell.nix`, e.g. `LD_LIBRARY_PATH = lib.makeLibraryPath [ pkgs.openssl pkgs.zlib pkgs.curl ]`
+2. (If you have already enabled `nix-ld`) set `LD_LIBRARY_PATH` to `NIX_LD_LIBRARY_PATH`. Be aware this is not a silver bullet solution, as this simply provides a list of commonly used libraries, as is shown in `nixos/modules/programs/nix-ld.nix`.

doc/packages/vcpkg.section.md

@@ -0,0 +1,24 @@
+# VCPKG {#sec-vcpkg}
+
+The `vcpkg-tool` package has a wrapper around the `vcpkg` executable to avoid writing to the nix store.
+The wrapper will also be present in `vcpkg`, unless you specify `vcpkg.override { vcpkg-tool = vcpkg-tool-unwrapped; }`
+
+The wrapper has been made in a way so that it will provide default cli arguments but tries not to interfere if the user provides the same arguments.
+The arguments also have corresponding environment variables that can be used as an alternative way of overriding these paths.
+
+Run the wrapper with the environment variable `NIX_VCPKG_DEBUG_PRINT_ENVVARS=true` to get a full list of corresponding environment variables.
+
+## Nix specific environment variables {#sec-vcpkg-nix-envvars}
+
+The wrapper also provides some new nix-specific environment variables that let you control some of the wrapper functionality.
+
+- `NIX_VCPKG_WRITABLE_PATH = <path>`
+
+   Set this environment variable to specify the path where `vcpkg` will store buildtime artifacts.
+   This will become the base path for all of the other paths.
+
+- `NIX_VCPKG_DEBUG_PRINT_ENVVARS = true | false`
+
+   Set this to `true` for the wrapper to print the corresponding environment variables for the arguments that will be provided to the unwrapped executable.
+   The list of variables will be printed right before invoking `vcpkg`.
+   This can be useful if you suspect that the wrapper for some reason was unable to prioritize user-provided cli args over its default ones, or for fixing other issues like typos or unexpanded environment variables.

doc/packages/weechat.section.md

@@ -0,0 +1,125 @@
+# WeeChat {#sec-weechat}
+
+WeeChat can be configured to include your choice of plugins, reducing its closure size from the default configuration which includes all available plugins. To make use of this functionality, install an expression that overrides its configuration, such as:
+
+```nix
+weechat.override {
+  configure = (
+    { availablePlugins, ... }:
+    {
+      plugins = with availablePlugins; [
+        python
+        perl
+      ];
+    }
+  );
+}
+```
+
+If the `configure` function returns an attrset without the `plugins` attribute, `availablePlugins` will be used automatically.
+
+The plugins currently available are `python`, `perl`, `ruby`, `guile`, `tcl` and `lua`.
+
+The Python and Perl plugins allow the addition of extra libraries. For instance, the `inotify.py` script in `weechat-scripts` requires D-Bus or libnotify, and the `fish.py` script requires `pycrypto`. To use these scripts, use the plugin's `withPackages` attribute:
+
+```nix
+weechat.override {
+  configure =
+    { availablePlugins, ... }:
+    {
+      plugins = with availablePlugins; [
+        (python.withPackages (
+          ps: with ps; [
+            pycrypto
+            python-dbus
+          ]
+        ))
+      ];
+    };
+}
+```
+
+In order to also keep all default plugins installed, it is possible to use the following method:
+
+```nix
+weechat.override {
+  configure =
+    { availablePlugins, ... }:
+    {
+      plugins = builtins.attrValues (
+        availablePlugins
+        // {
+          python = availablePlugins.python.withPackages (
+            ps: with ps; [
+              pycrypto
+              python-dbus
+            ]
+          );
+        }
+      );
+    };
+}
+```
+
+WeeChat allows to set defaults on startup using the `--run-command`. The `configure` method can be used to pass commands to the program:
+
+```nix
+weechat.override {
+  configure =
+    { availablePlugins, ... }:
+    {
+      init = ''
+        /set foo bar
+        /server add libera irc.libera.chat
+      '';
+    };
+}
+```
+
+Further values can be added to the list of commands when running `weechat --run-command "your-commands"`.
+
+Additionally, it's possible to specify scripts to be loaded when starting `weechat`. These will be loaded before the commands from `init`:
+
+```nix
+weechat.override {
+  configure =
+    { availablePlugins, ... }:
+    {
+      scripts = with pkgs.weechatScripts; [
+        weechat-xmpp
+        weechat-matrix-bridge
+        wee-slack
+      ];
+      init = ''
+        /set plugins.var.python.jabber.key "val"
+      '';
+    };
+}
+```
+
+In `nixpkgs` there's a subpackage which contains derivations for WeeChat scripts. Such derivations expect a `passthru.scripts` attribute, which contains a list of all scripts inside the store path. Furthermore, all scripts have to live in `$out/share`. An exemplary derivation looks like this:
+
+```nix
+{ stdenv, fetchurl }:
+
+stdenv.mkDerivation {
+  name = "exemplary-weechat-script";
+  src = fetchurl {
+    url = "https://scripts.tld/your-scripts.tar.gz";
+    hash = "...";
+  };
+  passthru.scripts = [
+    "foo.py"
+    "bar.lua"
+  ];
+  installPhase = ''
+    runHook preInstall
+
+    mkdir $out/share
+    cp foo.py $out/share
+    cp bar.lua $out/share
+
+    runHook postInstall
+  '';
+}
+```

doc/packages/xorg.section.md

@@ -0,0 +1,34 @@
+# X.org {#sec-xorg}
+
+The Nix expressions for the X.org packages reside in `pkgs/servers/x11/xorg/default.nix`. This file is automatically generated from lists of tarballs in an X.org release. As such, it should not be modified directly; rather, you should modify the lists, the generator script, or the file `pkgs/servers/x11/xorg/overrides.nix`, in which you can override or add to the derivations produced by the generator.
+
+## Katamari Tarballs {#katamari-tarballs}
+
+X.org upstream releases used to include [katamari](https://en.wiktionary.org/wiki/%E3%81%8B%E3%81%9F%E3%81%BE%E3%82%8A) releases, which included a holistic recommended version for each tarball, up until 7.7. To create a list of tarballs in a katamari release:
+
+```ShellSession
+export release="X11R7.7"
+export url="mirror://xorg/$release/src/everything/"
+cat $(PRINT_PATH=1 nix-prefetch-url $url | tail -n 1) \
+  | perl -e 'while (<>) { if (/(href|HREF)="([^"]*.bz2)"/) { print "$ENV{'url'}$2\n"; }; }' \
+  | sort > "tarballs-$release.list"
+```
+
+## Individual Tarballs {#individual-tarballs}
+
+The upstream release process for [X11R7.8](https://x.org/wiki/Releases/7.8/) does not include a planned katamari. Instead, each component of X.org is released as its own tarball. We maintain `pkgs/servers/x11/xorg/tarballs.list` as a list of tarballs for each individual package. This list includes X.org core libraries and protocol descriptions, extra newer X11 interface libraries, like `xorg.libxcb`, and classic utilities which are largely unused but still available if needed, like `xorg.imake`.
+
+## Generating Nix Expressions {#generating-nix-expressions}
+
+The generator is invoked as follows:
+
+```ShellSession
+cd pkgs/servers/x11/xorg
+<tarballs.list perl ./generate-expr-from-tarballs.pl
+```
+
+For each of the tarballs in the `.list` files, the script downloads it, unpacks it, and searches its `configure.ac` and `*.pc.in` files for dependencies. This information is used to generate `default.nix`. The generator caches downloaded tarballs between runs. Pay close attention to the `NOT FOUND: $NAME` messages at the end of the run, since they may indicate missing dependencies. (Some might be optional dependencies, however.)
+
+## Overriding the Generator {#overriding-the-generator}
+
+If the expression for a package requires derivation attributes that the generator cannot figure out automatically (say, `patches` or a `postInstall` hook), you should modify `pkgs/servers/x11/xorg/overrides.nix`.