Merge branch 'master' into stdenv.cc.libcxx

2023-08-12 14:19:01 -07:00
parent b51302ed47 fe53548a11
commit 1b8ca87a83
26754 changed files with 1840677 additions and 796056 deletions
@@ -55,10 +55,13 @@ trim_trailing_whitespace = unset
 [*.lock]
 indent_size = unset

-# trailing whitespace is an actual syntax element of classic Markdown/
-# CommonMark to enforce a line break
+# Although Markdown/CommonMark allows using two trailing spaces to denote
+# a hard line break, we do not use that feature in nixpkgs since
+# it forces the surrounding paragraph to become a <literallayout> which
+# does not wrap reasonably.
+# Instead of a hard line break, start a new paragraph by inserting a blank line.
 [*.md]
-trim_trailing_whitespace = unset
+trim_trailing_whitespace = true

 # binaries
 [*.nib]
@@ -92,3 +95,13 @@ trim_trailing_whitespace = unset

 [pkgs/tools/misc/timidity/timidity.cfg]
 trim_trailing_whitespace = unset
+
+[pkgs/tools/virtualization/ovftool/*.ova]
+end_of_line = unset
+insert_final_newline = unset
+trim_trailing_whitespace = unset
+charset = unset
+
+[lib/tests/*.plist]
+indent_style = tab
+insert_final_newline = unset
@@ -39,3 +39,60 @@ d1c1a0c656ccd8bd3b25d3c4287f2d075faf3cf3

 # fix indentation in meteor default.nix
 a37a6de881ec4c6708e6b88fd16256bbc7f26bbd
+
+# treewide: automatically md-convert option descriptions
+2e751c0772b9d48ff6923569adfa661b030ab6a2
+
+# nixos/*: automatically convert option docs
+087472b1e5230ffc8ba642b1e4f9218adf4634a2
+
+# nixos/*: automatically convert option descriptions
+ef176dcf7e76c3639571d7c6051246c8fbadf12a
+
+# nixos/*: automatically convert option docs to MD
+61e93df1891972bae3e0c97a477bd44e8a477aa0
+
+# nixos/*: convert options with admonitions to MD
+722b99bc0eb57711c0498a86a3f55e6c69cdb05f
+
+# nixos/*: automatically convert option docs
+6039648c50c7c0858b5e506c6298773a98e0f066
+
+# nixos/*: md-convert options with unordered lists
+c915b915b5e466a0b0b2af2906cd4d2380b8a1de
+
+# nixos/*: convert options with listings
+f2ea09ecbe1fa1da32eaa6e036d64ac324a2986f
+
+# nixos/*: convert straggler options to MD
+1d41cff3dc4c8f37bb5841f51fcbff705e169178
+
+# nixos/*: normalize manpage references to single-line form
+423545fe4865d126e86721ba30da116e29c65004
+
+# nixos/documentation: split options doc build
+fc614c37c653637e5475a0b0a987489b4d1f351d
+
+# nixos/*: convert options with admonitions to MD
+722b99bc0eb57711c0498a86a3f55e6c69cdb05f
+
+# nixos/*: convert internal option descriptions to MD
+9547123258f69efd92b54763051d6dc7f3bfcaca
+
+# nixos/*: replace </para><para> with double linebreaks
+694d5b19d30bf66687b42fb77f43ea7cd1002a62
+
+# treewide: add defaultText for options with simple interpolation defaults
+fb0e5be84331188a69b3edd31679ca6576edb75a
+
+# nixos/*: mark pre-existing markdown descriptions as mdDoc
+7e7d68a250f75678451cd44f8c3d585bf750461e
+
+# nixos/*: normalize link format
+3aebb4a2be8821a6d8a695f0908d8567dc00de31
+
+# nixos/*: replace <code> in option docs with <literal>
+16102dce2fbad670bd47dd75c860a8daa5fe47ad
+
+# nixos/*: add trivial defaultText for options with simple defaults
+25124556397ba17bfd70297000270de1e6523b0a
@@ -1,4 +1,6 @@
 **/deps.nix linguist-generated
+**/deps.json linguist-generated
+**/deps.toml linguist-generated
 **/node-packages.nix linguist-generated

 pkgs/applications/editors/emacs-modes/*-generated.nix linguist-generated
@@ -22,60 +22,62 @@
 /.editorconfig @Mic92 @zowoq

 # Libraries
-/lib                        @edolstra @nbp @infinisil
-/lib/systems                @alyssais @nbp @ericson2314 @matthewbauer
-/lib/generators.nix         @edolstra @nbp @Profpatsch
-/lib/cli.nix                @edolstra @nbp @Profpatsch
-/lib/debug.nix              @edolstra @nbp @Profpatsch
-/lib/asserts.nix            @edolstra @nbp @Profpatsch
+/lib                        @edolstra @infinisil
+/lib/systems                @alyssais @ericson2314 @matthewbauer @amjoseph-nixpkgs
+/lib/generators.nix         @edolstra @Profpatsch
+/lib/cli.nix                @edolstra @Profpatsch
+/lib/debug.nix              @edolstra @Profpatsch
+/lib/asserts.nix            @edolstra @Profpatsch
+/lib/path.*                 @infinisil @fricklerhandwerk

 # Nixpkgs Internals
-/default.nix                                     @nbp
-/pkgs/top-level/default.nix                      @nbp @Ericson2314
-/pkgs/top-level/impure.nix                       @nbp @Ericson2314
-/pkgs/top-level/stage.nix                        @nbp @Ericson2314 @matthewbauer
+/default.nix                                     @Ericson2314
+/pkgs/top-level/default.nix                      @Ericson2314
+/pkgs/top-level/impure.nix                       @Ericson2314
+/pkgs/top-level/stage.nix                        @Ericson2314 @matthewbauer
 /pkgs/top-level/splice.nix                       @Ericson2314 @matthewbauer
 /pkgs/top-level/release-cross.nix                @Ericson2314 @matthewbauer
-/pkgs/stdenv/generic                             @Ericson2314 @matthewbauer
-/pkgs/stdenv/cross                               @Ericson2314 @matthewbauer
-/pkgs/build-support/cc-wrapper                   @Ericson2314
+/pkgs/stdenv/generic                             @Ericson2314 @matthewbauer @amjoseph-nixpkgs
+/pkgs/stdenv/generic/check-meta.nix              @Ericson2314 @matthewbauer @piegamesde
+/pkgs/stdenv/cross                               @Ericson2314 @matthewbauer @amjoseph-nixpkgs
+/pkgs/build-support/cc-wrapper                   @Ericson2314 @amjoseph-nixpkgs
 /pkgs/build-support/bintools-wrapper             @Ericson2314
 /pkgs/build-support/setup-hooks                  @Ericson2314
 /pkgs/build-support/setup-hooks/auto-patchelf.sh @layus
 /pkgs/build-support/setup-hooks/auto-patchelf.py @layus
+/pkgs/pkgs-lib                                   @infinisil

 # Nixpkgs build-support
 /pkgs/build-support/writers @lassulus @Profpatsch

+# Nixpkgs make-disk-image
+/doc/builders/images/makediskimage.section.md  @raitobezarius
+/nixos/lib/make-disk-image.nix                 @raitobezarius
+
 # Nixpkgs documentation
-/doc @fricklerhandwerk
 /maintainers/scripts/db-to-md.sh @jtojnar @ryantm
 /maintainers/scripts/doc @jtojnar @ryantm
-/doc/build-aux/pandoc-filters @jtojnar
-/doc/contributing/contributing-to-documentation.chapter.md @jtojnar
+
+# Contributor documentation
+/CONTRIBUTING.md @infinisil
+/.github/PULL_REQUEST_TEMPLATE.md @infinisil
+/doc/contributing/ @fricklerhandwerk @infinisil
+/doc/contributing/contributing-to-documentation.chapter.md @jtojnar @fricklerhandwerk @infinisil

 # NixOS Internals
-/nixos/default.nix          @nbp @infinisil
-/nixos/lib/from-env.nix     @nbp @infinisil
-/nixos/lib/eval-config.nix  @nbp @infinisil
-/nixos/doc/manual/configuration/abstractions.xml      @nbp
-/nixos/doc/manual/configuration/config-file.xml       @nbp
-/nixos/doc/manual/configuration/config-syntax.xml     @nbp
-/nixos/doc/manual/configuration/modularity.xml        @nbp
-/nixos/doc/manual/development/assertions.xml          @nbp
-/nixos/doc/manual/development/meta-attributes.xml     @nbp
-/nixos/doc/manual/development/option-declarations.xml @nbp
-/nixos/doc/manual/development/option-def.xml          @nbp
-/nixos/doc/manual/development/option-types.xml        @nbp
-/nixos/doc/manual/development/replace-modules.xml     @nbp
-/nixos/doc/manual/development/writing-modules.xml     @nbp
-/nixos/doc/manual/man-nixos-option.xml                @nbp
-/nixos/modules/installer/tools/nixos-option.sh        @nbp
+/nixos/default.nix                                    @infinisil
+/nixos/lib/from-env.nix                               @infinisil
+/nixos/lib/eval-config.nix                            @infinisil
 /nixos/modules/system                                 @dasJ
+/nixos/modules/system/activation/bootspec.nix         @grahamc @cole-h @raitobezarius
+/nixos/modules/system/activation/bootspec.cue         @grahamc @cole-h @raitobezarius

 # NixOS integration test driver
 /nixos/lib/test-driver  @tfc

+# NixOS QEMU virtualisation
+/nixos/virtualisation/qemu-vm.nix           @raitobezarius
+
 # Systemd
 /nixos/modules/system/boot/systemd.nix      @NixOS/systemd
 /nixos/modules/system/boot/systemd          @NixOS/systemd
@@ -91,10 +93,8 @@

 # Python-related code and docs
 /maintainers/scripts/update-python-libraries	              @FRidh
-/pkgs/top-level/python-packages.nix                         @FRidh @jonringer
 /pkgs/development/interpreters/python                       @FRidh
-/pkgs/development/python-modules                            @FRidh @jonringer
-/doc/languages-frameworks/python.section.md                 @FRidh
+/doc/languages-frameworks/python.section.md                 @FRidh @mweinelt
 /pkgs/development/tools/poetry2nix                          @adisbladis
 /pkgs/development/interpreters/python/hooks                 @FRidh @jonringer

@@ -121,11 +121,13 @@
 /pkgs/development/ruby-modules      @marsam

 # Rust
-/pkgs/development/compilers/rust @Mic92 @LnL7 @zowoq
+/pkgs/development/compilers/rust @Mic92 @zowoq @winterqt @figsoda
+/pkgs/build-support/rust @zowoq @winterqt @figsoda
+/doc/languages-frameworks/rust.section.md @zowoq @winterqt @figsoda

 # C compilers
-/pkgs/development/compilers/gcc @matthewbauer
-/pkgs/development/compilers/llvm @matthewbauer
+/pkgs/development/compilers/gcc @matthewbauer @amjoseph-nixpkgs
+/pkgs/development/compilers/llvm @matthewbauer @RaitoBezarius

 # Compatibility stuff
 /pkgs/top-level/unix-tools.nix @matthewbauer
@@ -140,6 +142,11 @@
 # Browsers
 /pkgs/applications/networking/browsers/firefox @mweinelt

+# Certificate Authorities
+pkgs/data/misc/cacert/ @ajs124 @lukegb @mweinelt
+pkgs/development/libraries/nss/ @ajs124 @lukegb @mweinelt
+pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt
+
 # Jetbrains
 /pkgs/applications/editors/jetbrains @edwtjo

@@ -186,10 +193,16 @@
 /nixos/modules/services/networking/babeld.nix @mweinelt
 /nixos/modules/services/networking/kea.nix @mweinelt
 /nixos/modules/services/networking/knot.nix @mweinelt
+/nixos/modules/services/monitoring/prometheus/exporters/kea.nix @mweinelt
 /nixos/tests/babeld.nix @mweinelt
 /nixos/tests/kea.nix @mweinelt
 /nixos/tests/knot.nix @mweinelt

+# Web servers
+/doc/builders/packages/nginx.section.md @raitobezarius
+/pkgs/servers/http/nginx/ @raitobezarius
+/nixos/modules/services/web-servers/nginx/ @raitobezarius
+
 # Dhall
 /pkgs/development/dhall-modules      @Gabriella439 @Profpatsch @ehmry
 /pkgs/development/interpreters/dhall @Gabriella439 @Profpatsch @ehmry
@@ -212,33 +225,28 @@
 /pkgs/top-level/emacs-packages.nix              @adisbladis

 # Neovim
-/pkgs/applications/editors/neovim      @jonringer @teto
+/pkgs/applications/editors/neovim      @figsoda @jonringer @teto

 # VimPlugins
-/pkgs/applications/editors/vim/plugins         @jonringer
+/pkgs/applications/editors/vim/plugins         @figsoda @jonringer

 # VsCode Extensions
 /pkgs/applications/editors/vscode/extensions   @jonringer

-# Prometheus exporter modules and tests
-/nixos/modules/services/monitoring/prometheus/exporters.nix  @WilliButz
-/nixos/modules/services/monitoring/prometheus/exporters.xml  @WilliButz
-/nixos/tests/prometheus-exporters.nix                        @WilliButz
-
 # PHP interpreter, packages, extensions, tests and documentation
-/doc/languages-frameworks/php.section.md          @aanderse @etu @globin @ma27 @talyz
-/nixos/tests/php                                  @aanderse @etu @globin @ma27 @talyz
-/pkgs/build-support/build-pecl.nix                @aanderse @etu @globin @ma27 @talyz
-/pkgs/development/interpreters/php       @jtojnar @aanderse @etu @globin @ma27 @talyz
-/pkgs/development/php-packages                    @aanderse @etu @globin @ma27 @talyz
-/pkgs/top-level/php-packages.nix         @jtojnar @aanderse @etu @globin @ma27 @talyz
+/doc/languages-frameworks/php.section.md          @aanderse @drupol @etu @globin @ma27 @talyz
+/nixos/tests/php                                  @aanderse @drupol @etu @globin @ma27 @talyz
+/pkgs/build-support/build-pecl.nix                @aanderse @drupol @etu @globin @ma27 @talyz
+/pkgs/development/interpreters/php       @jtojnar @aanderse @drupol @etu @globin @ma27 @talyz
+/pkgs/development/php-packages                    @aanderse @drupol @etu @globin @ma27 @talyz
+/pkgs/top-level/php-packages.nix         @jtojnar @aanderse @drupol @etu @globin @ma27 @talyz

 # Podman, CRI-O modules and related
-/nixos/modules/virtualisation/containers.nix @zowoq @adisbladis
-/nixos/modules/virtualisation/cri-o.nix      @zowoq @adisbladis
-/nixos/modules/virtualisation/podman         @zowoq @adisbladis
-/nixos/tests/cri-o.nix                       @zowoq @adisbladis
-/nixos/tests/podman                          @zowoq @adisbladis
+/nixos/modules/virtualisation/containers.nix @adisbladis
+/nixos/modules/virtualisation/cri-o.nix      @adisbladis
+/nixos/modules/virtualisation/podman         @adisbladis
+/nixos/tests/cri-o.nix                       @adisbladis
+/nixos/tests/podman                          @adisbladis

 # Docker tools
 /pkgs/build-support/docker                   @roberth
@@ -256,6 +264,7 @@
 # GNOME
 /pkgs/desktops/gnome                              @jtojnar
 /pkgs/desktops/gnome/extensions       @piegamesde @jtojnar
+/pkgs/build-support/make-hardcode-gsettings-patch @jtojnar

 # Cinnamon
 /pkgs/desktops/cinnamon @mkg20001
@@ -268,22 +277,33 @@
 # terraform providers
 /pkgs/applications/networking/cluster/terraform-providers @zowoq

-# kubernetes
-/nixos/doc/manual/configuration/kubernetes.chapter.md @zowoq
-/nixos/modules/services/cluster/kubernetes            @zowoq
-/nixos/tests/kubernetes                               @zowoq
-/pkgs/applications/networking/cluster/kubernetes      @zowoq
-
 # Matrix
 /pkgs/servers/heisenbridge                                 @piegamesde
 /pkgs/servers/matrix-conduit                               @piegamesde
-/pkgs/servers/matrix-synapse/matrix-appservice-irc         @piegamesde
 /nixos/modules/services/misc/heisenbridge.nix              @piegamesde
-/nixos/modules/services/misc/matrix-appservice-irc.nix     @piegamesde
 /nixos/modules/services/misc/matrix-conduit.nix            @piegamesde
-/nixos/tests/matrix-appservice-irc.nix                     @piegamesde
 /nixos/tests/matrix-conduit.nix                            @piegamesde

 # Dotnet
 /pkgs/build-support/dotnet          @IvarWithoutBones
 /pkgs/development/compilers/dotnet  @IvarWithoutBones
+
+# Node.js
+/pkgs/build-support/node/build-npm-package      @lilyinstarlight @winterqt
+/pkgs/build-support/node/fetch-npm-deps         @lilyinstarlight @winterqt
+/doc/languages-frameworks/javascript.section.md @lilyinstarlight @winterqt
+
+# OCaml
+/pkgs/build-support/ocaml           @ulrikstrid
+/pkgs/development/compilers/ocaml   @ulrikstrid
+/pkgs/development/ocaml-modules     @ulrikstrid
+
+# ZFS
+pkgs/os-specific/linux/zfs                @raitobezarius
+nixos/lib/make-single-disk-zfs-image.nix  @raitobezarius
+nixos/lib/make-multi-disk-zfs-image.nix   @raitobezarius
+nixos/modules/tasks/filesystems/zfs.nix   @raitobezarius
+nixos/tests/zfs.nix                       @raitobezarius
+
+# Linux Kernel
+pkgs/os-specific/linux/kernel/manual-config.nix   @amjoseph-nixpkgs
@@ -26,6 +26,7 @@ If applicable, add screenshots to help explain your problem.
 Add any other context about the problem here.

 ### Notify maintainers
+
 <!--
 Please @ people who are in the `meta.maintainers` list of the offending package or module.
 If in doubt, check `git blame` for whoever last touched something.
@@ -1,31 +1,36 @@
 ---
 name: Build failure
 about: Create a report to help us improve
-title: ''
+title: 'Build failure: PACKAGENAME'
 labels: '0.kind: build failure'
 assignees: ''

 ---

 ### Steps To Reproduce
+
 Steps to reproduce the behavior:
 1. build *X*

 ### Build log
+
 ```
 log here if short otherwise a link to a gist
 ```

 ### Additional context
+
 Add any other context about the problem here.

 ### Notify maintainers
+
 <!--
 Please @ people who are in the `meta.maintainers` list of the offending package or module.
 If in doubt, check `git blame` for whoever last touched something.
 -->

 ### Metadata
+
 Please run `nix-shell -p nix-info --run "nix-info -m"` and paste the result.

 ```console
@@ -1,7 +1,7 @@
 ---
 name: Missing or incorrect documentation
-about:
-title: ''
+about: Help us improve the Nixpkgs and NixOS reference manuals
+title: 'Documentation: '
 labels: '9.needs: documentation'
 assignees: ''

@@ -11,11 +11,15 @@ assignees: ''

 <!-- describe your problem -->

+## Proposal
+
+<!-- propose a solution (optional) -->
+
 ## Checklist

 <!-- make sure this issue is not redundant or obsolete -->

- [ ] checked [latest Nixpkgs manual] \([source][nixpkgs-source]) and [latest NixOS manual]] \[source][nixos-source])
+- [ ] checked [latest Nixpkgs manual] \([source][nixpkgs-source]) and [latest NixOS manual] \([source][nixos-source])
 - [ ] checked [open documentation issues] for possible duplicates
 - [ ] checked [open documentation pull requests] for possible solutions

@@ -26,7 +30,3 @@ assignees: ''
 [open documentation issues]: https://github.com/NixOS/nixpkgs/issues?q=is%3Aissue+is%3Aopen+label%3A%229.needs%3A+documentation%22
 [open documentation pull requests]: https://github.com/NixOS/nixpkgs/pulls?q=is%3Aopen+is%3Apr+label%3A%228.has%3A+documentation%22%2C%226.topic%3A+documentation%22

-## Proposal
-
-<!-- propose a solution -->
-
@@ -1,24 +1,17 @@
 ---
 name: Out-of-date package reports
 about: For packages that are out-of-date
-title: ''
+title: 'Update request: PACKAGENAME OLDVERSION → NEWVERSION'
 labels: '9.needs: package (update)'
 assignees: ''

 ---

-
-###### Checklist
-
-<!-- Note that these are hard requirements -->
-
-<!--
-You can use the "Go to file" functionality on GitHub to find the package
-Then you can go to the history for this package
-Find the latest "package_name: old_version -> new_version" commit
-The "new_version" is the current version of the package
-->
- [ ] Checked the [nixpkgs master branch](https://github.com/NixOS/nixpkgs)
+- Package name:
+- Latest released version:
+<!-- Search your package here: https://search.nixos.org/packages?channel=unstable -->
+- Current version on the unstable channel:
+- Current version on the stable/release channel:
 <!--
 Type the name of your package and try to find an open pull request for the package
 If you find an open pull request, you can review it!
@@ -26,23 +19,10 @@ There's a high chance that you'll have the new version right away while helping
 -->
 - [ ] Checked the [nixpkgs pull requests](https://github.com/NixOS/nixpkgs/pulls)

-###### Project name
-`nix search` name:
-<!--
-The current version can be found easily with the same process as above for checking the master branch
-If an open PR is present for the package, take this version as the current one and link to the PR
-->
-current version:
-desired version:
+**Notify maintainers**

-###### Notify maintainers
-<!--
-Search your package here: https://search.nixos.org/packages?channel=unstable
-If no maintainer is listed for your package, tag the person that last updated the package
-->
+<!-- If the search.nixos.org result shows no maintainers, tag the person that last updated the package. -->

-maintainers:
+-----

-###### Note for maintainers
-
-Please tag this issue in your PR.
+Note for maintainers: Please tag this issue in your PR.
@@ -1,14 +1,15 @@
 ---
 name: Packaging requests
 about: For packages that are missing
-title: ''
+title: 'Package request: PACKAGENAME'
 labels: '0.kind: packaging request'
 assignees: ''

 ---

 **Project description**
-_describe the project a little_
+
+<!-- Describe the project a little: -->

 **Metadata**

@@ -0,0 +1,31 @@
+---
+name: Unreproducible package
+about: A package that does not produce a bit-by-bit reproducible result each time it is built
+title: ''
+labels: [ '0.kind: enhancement', '6.topic: reproducible builds' ]
+assignees: ''
+
+---
+
+Building this package twice does not produce the bit-by-bit identical result each time, making it harder to detect CI breaches. You can read more about this at https://reproducible-builds.org/ .
+
+Fixing bit-by-bit reproducibility also has additional advantages, such as avoiding hard-to-reproduce bugs, making content-addressed storage more effective and reducing rebuilds in such systems.
+
+### Steps To Reproduce
+
+```
+nix-build '<nixpkgs>' -A ... --check --keep-failed
+```
+
+You can use `diffoscope` to analyze the differences in the output of the two builds.
+
+To view the build log of the build that produced the artifact in the binary cache:
+
+```
+nix-store --read-log $(nix-instantiate '<nixpkgs>' -A ...)
+```
+
+### Additional context
+
+(please share the relevant fragment of the diffoscope output here,
+and any additional analysis you may have done)
@@ -1,11 +1,11 @@
-###### Description of changes
+## Description of changes

 <!--
 For package updates please link to a changelog or describe changes, this helps your fellow maintainers discover breaking updates.
 For new packages please briefly describe the package or provide a link to its homepage.
 -->

-###### Things done
+## Things done

 <!-- Please check what applies. Note that these are not hard requirements but merely serve as information for reviewers. -->

@@ -22,11 +22,10 @@ For new packages please briefly describe the package or provide a link to its ho
  - made sure NixOS tests are [linked](https://nixos.org/manual/nixpkgs/unstable/#ssec-nixos-tests-linking) to the relevant packages
 - [ ] Tested compilation of all packages that depend on this change using `nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD"`. Note: all changes have to be committed, also see [nixpkgs-review usage](https://github.com/Mic92/nixpkgs-review#usage)
 - [ ] Tested basic functionality of all binary files (usually in `./result/bin/`)
- [22.11 Release Notes (or backporting 22.05 Release notes)](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#generating-2211-release-notes)
+- [23.11 Release Notes](https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/manual/release-notes/rl-2311.section.md) (or backporting [23.05 Release notes](https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/manual/release-notes/rl-2305.section.md))
  - [ ] (Package updates) Added a release notes entry if the change is major or breaking
  - [ ] (Module updates) Added a release notes entry if the change is significant
  - [ ] (Module addition) Added a release notes entry if adding a new NixOS module
-  - [ ] (Release notes changes) Ran `nixos/doc/manual/md-to-db.sh` to update generated release notes
 - [ ] Fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

 <!--
@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
@@ -19,6 +19,11 @@
  - pkgs/build-support/emacs/**/*
  - pkgs/top-level/emacs-packages.nix

+"6.topic: Enlightenment DE":
+  - nixos/modules/services/x11/desktop-managers/enlightenment.nix
+  - pkgs/desktops/enlightenment/**/*
+  - pkgs/development/python-modules/python-efl/*
+
 "6.topic: erlang":
  - doc/languages-frameworks/beam.section.md
  - pkgs/development/beam-modules/**/*
@@ -59,12 +64,35 @@
  - pkgs/build-support/kernel/**/*
  - pkgs/os-specific/linux/kernel/**/*

+"6.topic: lib":
+  - lib/**
+
 "6.topic: lua":
  - pkgs/development/interpreters/lua-5/**/*
  - pkgs/development/interpreters/luajit/**/*
  - pkgs/development/lua-modules/**/*
  - pkgs/top-level/lua-packages.nix

+"6.topic: Lumina DE":
+  - nixos/modules/services/x11/desktop-managers/lumina.nix
+  - pkgs/desktops/lumina/**/*
+
+"6.topic: LXQt":
+  - nixos/modules/services/x11/desktop-managers/lxqt.nix
+  - pkgs/desktops/lxqt/**/*
+
+"6.topic: mate":
+  - nixos/modules/services/x11/desktop-managers/mate.nix
+  - nixos/tests/mate.nix
+  - pkgs/desktops/mate/**/*
+
+"6.topic: module system":
+  - lib/modules.nix
+  - lib/types.nix
+  - lib/options.nix
+  - lib/tests/modules.sh
+  - lib/tests/modules/**
+
 "6.topic: nixos":
  - nixos/**/*
  - pkgs/os-specific/linux/nixos-rebuild/**/*
@@ -75,6 +103,14 @@
  - pkgs/development/nim-packages/**/*
  - pkgs/top-level/nim-packages.nix

+"6.topic: nodejs":
+  - doc/languages-frameworks/javascript.section.md
+  - pkgs/build-support/node/**/*
+  - pkgs/development/node-packages/**/*
+  - pkgs/development/tools/yarn/*
+  - pkgs/development/tools/yarn2nix-moretea/**/*
+  - pkgs/development/web/nodejs/*
+
 "6.topic: ocaml":
  - doc/languages-frameworks/ocaml.section.md
  - pkgs/development/compilers/ocaml/**/*
@@ -143,6 +179,9 @@
  - nixos/modules/programs/neovim.nix
  - pkgs/applications/editors/neovim/**/*

+"6.topic: vscode":
+  - pkgs/applications/editors/vscode/**/*
+
 "6.topic: xfce":
  - nixos/doc/manual/configuration/xfce.xml
  - nixos/modules/services/x11/desktop-managers/xfce.nix
@@ -14,26 +14,20 @@ permissions:
 jobs:
  backport:
    permissions:
-      contents: write  # for zeebe-io/backport-action to create branch
-      pull-requests: write  # for zeebe-io/backport-action to create PR to backport
+      contents: write # for korthout/backport-action to create branch
+      pull-requests: write # for korthout/backport-action to create PR to backport
    name: Backport Pull Request
    if: github.repository_owner == 'NixOS' && github.event.pull_request.merged == true && (github.event_name != 'labeled' || startsWith('backport', github.event.label.name))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
-          # required to find all branches
-          fetch-depth: 0
          ref: ${{ github.event.pull_request.head.sha }}
      - name: Create backport PRs
-        # should be kept in sync with `version`
-        uses: zeebe-io/backport-action@v0.0.5
+        uses: korthout/backport-action@v1.3.1
        with:
-          # Config README: https://github.com/zeebe-io/backport-action#backport-action
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          github_workspace: ${{ github.workspace }}
-          # should be kept in sync with `uses`
-          version: v0.0.5
+          # Config README: https://github.com/korthout/backport-action#backport-action
+          copy_labels_pattern: 'severity:\ssecurity'
          pull_description: |-
            Bot-based backport to `${target_branch}`, triggered by a label in #${pull_number}.

@@ -19,8 +19,8 @@ jobs:
    # we don't limit this action to only NixOS repo since the checks are cheap and useful developer feedback
    steps:
    - uses: actions/checkout@v3
-    - uses: cachix/install-nix-action@v17
-    - uses: cachix/cachix-action@v10
+    - uses: cachix/install-nix-action@v22
+    - uses: cachix/cachix-action@v12
      with:
        # This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.
        name: nixpkgs-ci
@@ -0,0 +1,24 @@
+name: "Check that maintainer list is sorted"
+
+on:
+  pull_request_target:
+    paths:
+      - 'maintainers/maintainer-list.nix'
+permissions:
+  contents: read
+
+jobs:
+  nixos:
+    runs-on: ubuntu-latest
+    if: github.repository_owner == 'NixOS'
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          # pull_request_target checks out the base branch by default
+          ref: refs/pull/${{ github.event.pull_request.number }}/merge
+      - uses: cachix/install-nix-action@v22
+        with:
+          # explicitly enable sandbox
+          extra_nix_config: sandbox = true
+      - name: Check that maintainer-list.nix is sorted
+        run: nix-instantiate --eval maintainers/scripts/check-maintainers-sorted.nix
@@ -1,21 +0,0 @@
-#!/usr/bin/env nix-shell
-#! nix-shell -i bash -p html-tidy
-
-set -euo pipefail
-shopt -s inherit_errexit
-
-normalize() {
-  tidy \
-      --anchor-as-name no \
-      --coerce-endtags no \
-      --escape-scripts no \
-      --fix-backslash no \
-      --fix-style-tags no \
-      --fix-uri no \
-      --indent yes \
-      --wrap 0 \
-      < "$1" \
-      2> /dev/null
-}
-
-diff -U3 <(normalize "$1") <(normalize "$2")
@@ -21,7 +21,7 @@ jobs:
      id: ismerge
      run: |
        ISMERGE=$(curl -H 'Accept: application/vnd.github.groot-preview+json' -H "authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" https://api.github.com/repos/${{ env.GITHUB_REPOSITORY }}/commits/${{ env.GITHUB_SHA }}/pulls | jq -r '.[] | select(.merge_commit_sha == "${{ env.GITHUB_SHA }}") | any')
-        echo "::set-output name=ismerge::$ISMERGE"
+        echo "ismerge=$ISMERGE" >> $GITHUB_OUTPUT
    # github events are eventually consistent, so wait until changes propagate to thier DB
    - run: sleep 60
      if: steps.ismerge.outputs.ismerge != 'true'
@@ -11,7 +11,7 @@ on:
 jobs:
  tests:
    runs-on: ubuntu-latest
-    if: "github.repository_owner == 'NixOS' && !contains(github.event.pull_request.title, '[skip editorconfig]')"
+    if: "github.repository_owner == 'NixOS' && !contains(github.event.pull_request.title, '[skip treewide]')"
    steps:
    - name: Get list of changed files from PR
      env:
@@ -28,16 +28,14 @@ jobs:
      with:
        # pull_request_target checks out the base branch by default
        ref: refs/pull/${{ github.event.pull_request.number }}/merge
-    - uses: cachix/install-nix-action@v17
+    - uses: cachix/install-nix-action@v22
      with:
        # nixpkgs commit is pinned so that it doesn't break
        # editorconfig-checker 2.4.0
        nix_path: nixpkgs=https://github.com/NixOS/nixpkgs/archive/c473cc8714710179df205b153f4e9fa007107ff9.tar.gz
-    - name: install editorconfig-checker
-      run: nix-env -iA editorconfig-checker -f '<nixpkgs>'
    - name: Checking EditorConfig
      run: |
-        cat "$HOME/changed_files" | xargs -r editorconfig-checker -disable-indent-size
+        cat "$HOME/changed_files" | nix-shell -p editorconfig-checker --run 'xargs -r editorconfig-checker -disable-indent-size'
    - if: ${{ failure() }}
      run: |
        echo "::error :: Hey! It looks like your changes don't follow our editorconfig settings. Read https://editorconfig.org/#download to configure your editor so you never see this error again."
@@ -16,7 +16,7 @@ permissions:
 jobs:
  labels:
    runs-on: ubuntu-latest
-    if: github.repository_owner == 'NixOS'
+    if: "github.repository_owner == 'NixOS' && !contains(github.event.pull_request.title, '[skip treewide]')"
    steps:
    - uses: actions/labeler@v4
      with:
@@ -18,22 +18,14 @@ jobs:
        with:
          # pull_request_target checks out the base branch by default
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
-      - uses: cachix/install-nix-action@v17
+      - uses: cachix/install-nix-action@v22
        with:
          # explicitly enable sandbox
          extra_nix_config: sandbox = true
-      - uses: cachix/cachix-action@v10
+      - uses: cachix/cachix-action@v12
        with:
          # This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.
          name: nixpkgs-ci
          signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'
-      - name: Building NixOS manual with DocBook options
+      - name: Building NixOS manual
        run: NIX_PATH=nixpkgs=$(pwd) nix-build --option restrict-eval true nixos/release.nix -A manual.x86_64-linux
-      - name: Building NixOS manual with Markdown options
-        run: |
-          export NIX_PATH=nixpkgs=$(pwd)
-          nix-build \
-            --option restrict-eval true \
-            --arg configuration '{ documentation.nixos.options.allowDocBook = false; }' \
-            nixos/release.nix \
-            -A manual.x86_64-linux
@@ -8,6 +8,7 @@ on:
      - master
    paths:
      - 'doc/**'
+      - 'lib/**'

 jobs:
  nixpkgs:
@@ -18,11 +19,11 @@ jobs:
        with:
          # pull_request_target checks out the base branch by default
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
-      - uses: cachix/install-nix-action@v17
+      - uses: cachix/install-nix-action@v22
        with:
          # explicitly enable sandbox
          extra_nix_config: sandbox = true
-      - uses: cachix/cachix-action@v10
+      - uses: cachix/cachix-action@v12
        with:
          # This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.
          name: nixpkgs-ci
@@ -1,64 +0,0 @@
-name: "Check NixOS Manual DocBook rendering against MD rendering"
-
-
-on:
-  schedule:
-    # * is a special character in YAML so you have to quote this string
-    # Check every 24 hours
-    - cron:  '0 0 * * *'
-
-permissions:
-  contents: read
-
-jobs:
-  check-rendering-equivalence:
-    permissions:
-      pull-requests: write  # for peter-evans/create-or-update-comment to create or update comment
-    if: github.repository_owner == 'NixOS'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: cachix/install-nix-action@v17
-        with:
-          # explicitly enable sandbox
-          extra_nix_config: sandbox = true
-      - uses: cachix/cachix-action@v10
-        with:
-          # This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.
-          name: nixpkgs-ci
-          signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'
-
-      - name: Build DocBook and MD manuals
-        run: |
-          export NIX_PATH=nixpkgs=$(pwd)
-          nix-build \
-            --option restrict-eval true \
-            -o docbook nixos/release.nix \
-            -A manual.x86_64-linux
-          nix-build \
-            --option restrict-eval true \
-            --arg configuration '{ documentation.nixos.options.allowDocBook = false; }' \
-            -o md nixos/release.nix \
-            -A manual.x86_64-linux
-
-      - name: Compare DocBook and MD manuals
-        id: check
-        run: |
-          export NIX_PATH=nixpkgs=$(pwd)
-          .github/workflows/compare-manuals.sh \
-            docbook/share/doc/nixos/options.html \
-            md/share/doc/nixos/options.html
-
-      # if the manual can't be built we don't want to notify anyone.
-      # while this may temporarily hide rendering failures it will be a lot
-      # less noisy until all nixpkgs pull requests have stopped using
-      # docbook for option docs.
-      - name: Comment on failure
-        uses: peter-evans/create-or-update-comment@v2
-        if: ${{ failure() && steps.check.conclusion == 'failure' }}
-        with:
-          issue-number: 189318
-          body: |
-            Markdown and DocBook manuals do not agree.
-
-            Check https://github.com/NixOS/nixpkgs/actions/runs/${{ github.run_id }} for details.
@@ -1,34 +0,0 @@
-name: NixOS manual checks
-
-permissions: read-all
-
-on:
-  pull_request_target:
-    branches-ignore:
-      - 'release-**'
-    paths:
-      - 'nixos/**/*.xml'
-      - 'nixos/**/*.md'
-
-jobs:
-  tests:
-    runs-on: ubuntu-latest
-    if: github.repository_owner == 'NixOS'
-    steps:
-    - uses: actions/checkout@v3
-      with:
-        # pull_request_target checks out the base branch by default
-        ref: refs/pull/${{ github.event.pull_request.number }}/merge
-    - uses: cachix/install-nix-action@v17
-    - name: Check DocBook files generated from Markdown are consistent
-      run: |
-        nixos/doc/manual/md-to-db.sh
-        git diff --exit-code || {
-          echo
-          echo 'Generated manual files are out of date.'
-          echo 'Please run'
-          echo
-          echo '    nixos/doc/manual/md-to-db.sh'
-          echo
-          exit 1
-        }
@@ -0,0 +1,33 @@
+name: "Set pending OfBorg status"
+on:
+  pull_request_target:
+
+# Sets the ofborg-eval status to "pending" to signal that we are waiting for
+# OfBorg even if it is running late. The status will be overwritten by OfBorg
+# once it starts evaluation.
+
+# WARNING:
+# When extending this action, be aware that $GITHUB_TOKEN allows (restricted) write access to
+# the GitHub repository. This means that it should not evaluate user input in a
+# way that allows code injection.
+
+permissions:
+  contents: read
+
+jobs:
+  action:
+    if: github.repository_owner == 'NixOS'
+    permissions:
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+    - name: "Set pending OfBorg status"
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        curl \
+          -X POST \
+          -H "Accept: application/vnd.github.v3+json" \
+          -H "Authorization: Bearer $GITHUB_TOKEN" \
+          -d '{"context": "ofborg-eval", "state": "pending", "description": "Waiting for OfBorg..."}' \
+          "https://api.github.com/repos/NixOS/nixpkgs/commits/${{ github.event.pull_request.head.sha }}/statuses"
@@ -1,26 +0,0 @@
-name: "clear pending status"
-
-on:
-  check_suite:
-    types: [ completed ]
-
-permissions:
-  contents: read
-
-jobs:
-  action:
-    permissions:
-      statuses: write
-    runs-on: ubuntu-latest
-    steps:
-    - name: clear pending status
-      if: github.repository_owner == 'NixOS' && github.event.check_suite.app.name == 'OfBorg'
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      run: |
-        curl \
-          -X POST \
-          -H "Accept: application/vnd.github.v3+json" \
-          -H "Authorization: token $GITHUB_TOKEN" \
-          -d '{"state": "success", "target_url": " ", "description": " ", "context": "Wait for ofborg"}' \
-          "https://api.github.com/repos/NixOS/nixpkgs/statuses/${{ github.event.check_suite.head_sha }}"
@@ -1,30 +0,0 @@
-name: "set pending status"
-
-on:
-  pull_request_target:
-
-# WARNING:
-# When extending this action, be aware that $GITHUB_TOKEN allows write access to
-# the GitHub repository. This means that it should not evaluate user input in a
-# way that allows code injection.
-
-permissions:
-  contents: read
-
-jobs:
-  action:
-    permissions:
-      statuses: write
-    runs-on: ubuntu-latest
-    steps:
-    - name: set pending status
-      if: github.repository_owner == 'NixOS'
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      run: |
-        curl \
-          -X POST \
-          -H "Accept: application/vnd.github.v3+json" \
-          -H "Authorization: token $GITHUB_TOKEN" \
-          -d '{"state": "pending", "target_url": " ", "description": "This pending status will be cleared when ofborg starts eval.", "context": "Wait for ofborg"}' \
-          "https://api.github.com/repos/NixOS/nixpkgs/statuses/${{ github.event.pull_request.head.sha }}"
@@ -34,10 +34,10 @@ jobs:
        pairs:
          - from: master
            into: haskell-updates
-          - from: release-22.05
-            into: staging-next-22.05
-          - from: staging-next-22.05
-            into: staging-22.05
+          - from: release-23.05
+            into: staging-next-23.05
+          - from: staging-next-23.05
+            into: staging-23.05
    name: ${{ matrix.pairs.from }} → ${{ matrix.pairs.into }}
    steps:
      - uses: actions/checkout@v3
@@ -51,7 +51,7 @@ jobs:
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Comment on failure
-        uses: peter-evans/create-or-update-comment@v2
+        uses: peter-evans/create-or-update-comment@v3
        if: ${{ failure() }}
        with:
          issue-number: 105153
@@ -49,7 +49,7 @@ jobs:
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Comment on failure
-        uses: peter-evans/create-or-update-comment@v2
+        uses: peter-evans/create-or-update-comment@v3
        if: ${{ failure() }}
        with:
          issue-number: 105153
@@ -1,8 +1,8 @@
 name: "Update terraform-providers"

 on:
-  #schedule:
-  #  - cron: "14 3 * * 0"
+  schedule:
+    - cron: "0 3 * * *"
  workflow_dispatch:

 permissions:
@@ -11,44 +11,59 @@ permissions:
 jobs:
  tf-providers:
    permissions:
-      contents: write  # for peter-evans/create-pull-request to create branch
-      pull-requests: write  # for peter-evans/create-pull-request to create a PR, for peter-evans/create-or-update-comment to create or update comment
+      contents: write # for peter-evans/create-pull-request to create branch
+      pull-requests: write # for peter-evans/create-pull-request to create a PR
    if: github.repository_owner == 'NixOS' && github.ref == 'refs/heads/master' # ensure workflow_dispatch only runs on master
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
-      - uses: cachix/install-nix-action@v17
+      - uses: cachix/install-nix-action@v22
+        with:
+          nix_path: nixpkgs=channel:nixpkgs-unstable
      - name: setup
        id: setup
        run: |
-          echo ::set-output name=title::"terraform-providers: update $(date -u +"%Y-%m-%d")"
+          echo "title=terraform-providers: update $(date -u +"%Y-%m-%d")" >> $GITHUB_OUTPUT
      - name: update terraform-providers
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git config user.name "github-actions[bot]"
-          pushd pkgs/applications/networking/cluster/terraform-providers
-          ./update-all-providers --no-build
-          git commit -m "${{ steps.setup.outputs.title }}" providers.json
-          popd
+          echo | nix-shell \
+            maintainers/scripts/update.nix \
+            --argstr commit true \
+            --argstr keep-going true \
+            --argstr max-workers 2 \
+            --argstr path terraform-providers
+      - name: get failed updates
+        run: |
+          echo 'FAILED<<EOF' >> $GITHUB_ENV
+          git ls-files --others >> $GITHUB_ENV
+          echo 'EOF' >> $GITHUB_ENV
+      # cleanup logs of failed updates so they aren't included in the PR
+      - name: clean repo
+        run: |
+          git clean -f
      - name: create PR
-        uses: peter-evans/create-pull-request@v4
+        uses: peter-evans/create-pull-request@v5
        with:
          body: |
            Automatic update by [update-terraform-providers](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/update-terraform-providers.yml) action.

+            https://github.com/NixOS/nixpkgs/actions/runs/${{ github.run_id }}
+
+            These providers failed to update:
+            ```
+            ${{ env.FAILED }}
+            ```
+
            Check that all providers build with:
            ```
            @ofborg build terraform.full
            ```
+            If there is more than ten commits in the PR `ofborg` won't build it automatically and you will need to use the above command.
          branch: terraform-providers-update
          delete-branch: false
-          labels: "2.status: work-in-progress"
          title: ${{ steps.setup.outputs.title }}
          token: ${{ secrets.GITHUB_TOKEN }}
-      - name: comment on failure
-        uses: peter-evans/create-or-update-comment@v2
-        if: ${{ failure() }}
-        with:
-          issue-number: 153416
-          body: |
-            Automatic update of terraform providers [failed](https://github.com/NixOS/nixpkgs/actions/runs/${{ github.run_id }}).
@@ -2,10 +2,15 @@
 ,*
 .*.swp
 .*.swo
+.\#*
+\#*\#
 .idea/
 .vscode/
 outputs/
 result-*
+result
+repl-result-*
+!pkgs/development/python-modules/result
 /doc/NEWS.html
 /doc/NEWS.txt
 /doc/manual.html
@@ -0,0 +1,14 @@
+ajs124 <git@ajs124.de> <ajs124@users.noreply.github.com>
+Anderson Torres <torres.anderson.85@protonmail.com>
+Daniel Løvbrøtte Olsen <me@dandellion.xyz> <daniel.olsen99@gmail.com>
+Fabian Affolter <mail@fabian-affolter.ch> <fabian@affolter-engineering.ch>
+Janne Heß <janne@hess.ooo> <dasJ@users.noreply.github.com>
+Jörg Thalheim <joerg@thalheim.io> <Mic92@users.noreply.github.com>
+Martin Weinelt <hexa@darmstadt.ccc.de> <mweinelt@users.noreply.github.com>
+R. RyanTM <ryantm-bot@ryantm.com>
+Robert Hensing <robert@roberthensing.nl> <roberth@users.noreply.github.com>
+Sandro Jäckel <sandro.jaeckel@gmail.com>
+Sandro Jäckel <sandro.jaeckel@gmail.com> <sandro.jaeckel@sap.com>
+superherointj <5861043+superherointj@users.noreply.github.com>
+Vladimír Čunát <v@cunat.cz> <vcunat@gmail.com>
+Vladimír Čunát <v@cunat.cz> <vladimir.cunat@nic.cz>
@@ -1 +1 @@
-22.11
+23.11
@@ -38,11 +38,15 @@ Below is a short excerpt of some points in there:
    The old config generation system used impure shell scripts and could break in specific circumstances (see #1234).

 * `meta.description` should:
+  * Be short, just one sentence.
  * Be capitalized.
  * Not start with the package name.
-  * Not have a period at the end.
+    * More generally, it should not refer to the package name.
+  * Not end with a period (or any punctuation for that matter).
+  * Aim to inform while avoiding subjective language.
 * `meta.license` must be set and fit the upstream license.
  * If there is no upstream license, `meta.license` should default to `lib.licenses.unfree`.
+  * If in doubt, try to contact the upstream developers for clarification.
 * `meta.maintainers` must be set.

 See the nixpkgs manual for more details on [standard meta-attributes](https://nixos.org/nixpkgs/manual/#sec-standard-meta-attributes).
@@ -51,16 +55,32 @@ See the nixpkgs manual for more details on [standard meta-attributes](https://ni

 In addition to writing properly formatted commit messages, it's important to include relevant information so other developers can later understand *why* a change was made. While this information usually can be found by digging code, mailing list/Discourse archives, pull request discussions or upstream changes, it may require a lot of work.

-For package version upgrades and such a one-line commit message is usually sufficient.
+Package version upgrades usually allow for simpler commit messages, including attribute name, old and new version, as well as a reference to the relevant release notes/changelog. Every once in a while a package upgrade requires more extensive changes, and that subsequently warrants a more verbose message.
+
+Pull requests should not be squash merged in order to keep complete commit messages and GPG signatures intact and must not be when the change doesn't make sense as a single commit.
+This means that, when addressing review comments in order to keep the pull request in an always mergeable status, you will sometimes need to rewrite your branch's history and then force-push it with `git push --force-with-lease`.
+Useful git commands that can help a lot with this are `git commit --patch --amend` and `git rebase --interactive`. For more details consult the git man pages or online resources like [git-rebase.io](https://git-rebase.io/) or [The Pro Git Book](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History).
+
+## Testing changes
+
+To run the main types of tests locally:
+
+- Run package-internal tests with `nix-build --attr pkgs.PACKAGE.passthru.tests`
+- Run [NixOS tests](https://nixos.org/manual/nixos/unstable/#sec-nixos-tests) with `nix-build --attr nixosTest.NAME`, where `NAME` is the name of the test listed in `nixos/tests/all-tests.nix`
+- Run [global package tests](https://nixos.org/manual/nixpkgs/unstable/#sec-package-tests) with `nix-build --attr tests.PACKAGE`, where `PACKAGE` is the name of the test listed in `pkgs/test/default.nix`
+- See `lib/tests/NAME.nix` for instructions on running specific library tests

 ## Rebasing between branches (i.e. from master to staging)

 From time to time, changes between branches must be rebased, for example, if the
 number of new rebuilds they would cause is too large for the target branch. When
 rebasing, care must be taken to include only the intended changes, otherwise
-many CODEOWNERS will be inadvertently requested for review.  To achieve this,
+many CODEOWNERS will be inadvertently requested for review. To achieve this,
 rebasing should not be performed directly on the target branch, but on the merge
-base between the current and target branch.
+base between the current and target branch. As an additional precautionary measure,
+you should temporarily mark the PR as draft for the duration of the operation.
+This reduces the probability of mass-pinging people. (OfBorg might still
+request a couple of persons for reviews though.)

 In the following example, we assume that the current branch, called `feature`,
 is based on `master`, and we rebase it onto the merge base between
@@ -94,21 +114,51 @@ git status
 git push origin feature --force-with-lease
 ```

+### Something went wrong and a lot of people were pinged
+
+It happens. Remember to be kind, especially to new contributors.
+There is no way back, so the pull request should be closed and locked
+(if possible). The changes should be re-submitted in a new PR, in which the people
+originally involved in the conversation need to manually be pinged again.
+No further discussion should happen on the original PR, as a lot of people
+are now subscribed to it.
+
+The following message (or a version thereof) might be left when closing to
+describe the situation, since closing and locking without any explanation
+is kind of rude:
+
+```markdown
+It looks like you accidentally mass-pinged a bunch of people, which are now subscribed
+and getting notifications for everything in this pull request. Unfortunately, they
+cannot be automatically unsubscribed from the issue (removing review request does not
+unsubscribe), therefore development cannot continue in this pull request anymore.
+
+Please open a new pull request with your changes, link back to this one and ping the
+people actually involved in here over there.
+
+In order to avoid this in the future, there are instructions for how to properly
+rebase between branches in our [contribution guidelines](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#rebasing-between-branches-ie-from-master-to-staging).
+Setting your pull request to draft prior to rebasing is strongly recommended.
+In draft status, you can preview the list of people that are about to be requested
+for review, which allows you to sidestep this issue.
+This is not a bulletproof method though, as OfBorg still does review requests even on draft PRs.
+```
+
 ## Backporting changes

 Follow these steps to backport a change into a release branch in compliance with the [commit policy](https://nixos.org/nixpkgs/manual/#submitting-changes-stable-release-branches).

-You can add a label such as `backport release-22.05` to a PR, so that merging it will
+You can add a label such as `backport release-23.05` to a PR, so that merging it will
 automatically create a backport (via [a GitHub Action](.github/workflows/backport.yml)).
-This also works for PR's that have already been merged, and might take a couple of minutes to trigger.
+This also works for pull requests that have already been merged, and might take a couple of minutes to trigger.

 You can also create the backport manually:

 1. Take note of the commits in which the change was introduced into `master` branch.
-2. Check out the target _release branch_, e.g. `release-22.05`. Do not use a _channel branch_ like `nixos-22.05` or `nixpkgs-22.05-darwin`.
+2. Check out the target _release branch_, e.g. `release-23.05`. Do not use a _channel branch_ like `nixos-23.05` or `nixpkgs-23.05-darwin`.
 3. Create a branch for your change, e.g. `git checkout -b backport`.
 4. When the reason to backport is not obvious from the original commit message, use `git cherry-pick -xe <original commit>` and add a reason. Otherwise use `git cherry-pick -x <original commit>`. That's fine for minor version updates that only include security and bug fixes, commits that fixes an otherwise broken package or similar. Please also ensure the commits exists on the master branch; in the case of squashed or rebased merges, the commit hash will change and the new commits can be found in the merge message at the bottom of the master pull request.
-5. Push to GitHub and open a backport pull request. Make sure to select the release branch (e.g. `release-22.05`) as the target branch of the pull request, and link to the pull request in which the original change was comitted to `master`. The pull request title should be the commit title with the release version as prefix, e.g. `[22.05]`.
+5. Push to GitHub and open a backport pull request. Make sure to select the release branch (e.g. `release-23.05`) as the target branch of the pull request, and link to the pull request in which the original change was committed to `master`. The pull request title should be the commit title with the release version as prefix, e.g. `[23.05]`.
 6. When the backport pull request is merged and you have the necessary privileges you can also replace the label `9.needs: port to stable` with `8.has: port to stable` on the original pull request. This way maintainers can keep track of missing backports easier.

 ## Criteria for Backporting changes
@@ -120,16 +170,6 @@ Anything that does not cause user or downstream dependency regressions can be ba
 - Services which require a client to be up-to-date regardless. (E.g. `spotify`, `steam`, or `discord`)
 - Security critical applications (E.g. `firefox`)

-## Generating 22.11 Release Notes
-
-Documentation in nixpkgs is transitioning to a markdown-centric workflow. Release notes now require a translation step to convert from markdown to a compatible docbook document.
-
-Steps for updating 22.11 Release notes:
-
-1. Edit `nixos/doc/manual/release-notes/rl-2211.section.md` with the desired changes
-2. Run `./nixos/doc/manual/md-to-db.sh` to render `nixos/doc/manual/from_md/release-notes/rl-2211.section.xml`
-3. Include changes to `rl-2211.section.md` and `rl-2211.section.xml` in the same commit.
-
 ## Reviewing contributions

 See the nixpkgs manual for more details on how to [Review contributions](https://nixos.org/nixpkgs/manual/#chap-reviewing-contributions).
@@ -1,4 +1,4 @@
-Copyright (c) 2003-2022 Eelco Dolstra and the Nixpkgs/NixOS contributors
+Copyright (c) 2003-2023 Eelco Dolstra and the Nixpkgs/NixOS contributors

 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -51,9 +51,9 @@ Nixpkgs and NixOS are built and tested by our continuous integration
 system, [Hydra](https://hydra.nixos.org/).

 * [Continuous package builds for unstable/master](https://hydra.nixos.org/jobset/nixos/trunk-combined)
-* [Continuous package builds for the NixOS 22.05 release](https://hydra.nixos.org/jobset/nixos/release-22.05)
+* [Continuous package builds for the NixOS 23.05 release](https://hydra.nixos.org/jobset/nixos/release-23.05)
 * [Tests for unstable/master](https://hydra.nixos.org/job/nixos/trunk-combined/tested#tabs-constituents)
-* [Tests for the NixOS 22.05 release](https://hydra.nixos.org/job/nixos/release-22.05/tested#tabs-constituents)
+* [Tests for the NixOS 23.05 release](https://hydra.nixos.org/job/nixos/release-23.05/tested#tabs-constituents)

 Artifacts successfully built with Hydra are published to cache at
 https://cache.nixos.org/. When successful build and test criteria are
@@ -1,8 +0,0 @@
-*.chapter.xml
-*.section.xml
-.version
-functions/library/generated
-functions/library/locations.xml
-highlightjs
-manual-full.xml
-out
@@ -1,116 +0,0 @@
-MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$' -not -name README.md)))
-
-PANDOC ?= pandoc
-
-pandoc_media_dir = media
-# NOTE: Keep in sync with NixOS manual (/nixos/doc/manual/md-to-db.sh) and conversion script (/maintainers/scripts/db-to-md.sh).
-# TODO: Remove raw-attribute when we can get rid of DocBook altogether.
-pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
-# Not needed:
-# - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)
-pandoc_flags = --extract-media=$(pandoc_media_dir) \
-	--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
-	--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \
-	--lua-filter=build-aux/pandoc-filters/link-unix-man-references.lua \
-	--lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
-	--lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \
-	-f commonmark$(pandoc_commonmark_enabled_extensions)+smart
-
-.PHONY: all
-all: validate format out/html/index.html out/epub/manual.epub
-
-.PHONY: debug
-debug:
-	nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"
-
-.PHONY: format
-format: doc-support/result
-	find . -iname '*.xml' -type f | while read f; do \
-		echo $$f ;\
-		xmlformat --config-file "doc-support/result/xmlformat.conf" -i $$f ;\
-	done
-
-.PHONY: fix-misc-xml
-fix-misc-xml:
-	find . -iname '*.xml' -type f \
-		-exec ../nixos/doc/varlistentry-fixer.rb {} ';'
-
-.PHONY: clean
-clean:
-	rm -f ${MD_TARGETS} doc-support/result .version manual-full.xml functions/library/locations.xml functions/library/generated
-	rm -rf ./out/ ./highlightjs ./media
-
-.PHONY: validate
-validate: manual-full.xml doc-support/result
-	jing doc-support/result/docbook.rng manual-full.xml
-
-out/html/index.html: doc-support/result manual-full.xml style.css highlightjs
-	mkdir -p out/html
-	xsltproc \
-		--nonet --xinclude \
-		--output $@ \
-		doc-support/result/xhtml.xsl \
-		./manual-full.xml
-
-	mkdir -p out/html/highlightjs/
-	cp -r highlightjs out/html/
-
-	cp -r $(pandoc_media_dir) out/html/
-	cp ./overrides.css out/html/
-	cp ./style.css out/html/style.css
-
-	mkdir -p out/html/images/callouts
-	cp doc-support/result/xsl/docbook/images/callouts/*.svg out/html/images/callouts/
-	chmod u+w -R out/html/
-
-out/epub/manual.epub: manual-full.xml
-	mkdir -p out/epub/scratch
-	xsltproc --nonet \
-		--output out/epub/scratch/ \
-		doc-support/result/epub.xsl \
-		./manual-full.xml
-
-	cp -r $(pandoc_media_dir) out/epub/scratch/OEBPS
-	cp ./overrides.css out/epub/scratch/OEBPS
-	cp ./style.css out/epub/scratch/OEBPS
-	mkdir -p out/epub/scratch/OEBPS/images/callouts/
-	cp doc-support/result/xsl/docbook/images/callouts/*.svg out/epub/scratch/OEBPS/images/callouts/
-	echo "application/epub+zip" > mimetype
-	zip -0Xq "out/epub/manual.epub" mimetype
-	rm mimetype
-	cd "out/epub/scratch/" && zip -Xr9D "../manual.epub" *
-	rm -rf "out/epub/scratch/"
-
-highlightjs: doc-support/result
-	mkdir -p highlightjs
-	cp -r doc-support/result/highlightjs/highlight.pack.js highlightjs/
-	cp -r doc-support/result/highlightjs/LICENSE highlightjs/
-	cp -r doc-support/result/highlightjs/mono-blue.css highlightjs/
-	cp -r doc-support/result/highlightjs/loader.js highlightjs/
-
-
-manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml functions/library/generated *.xml **/*.xml **/**/*.xml
-	xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
-
-.version: doc-support/result
-	ln -rfs ./doc-support/result/version .version
-
-doc-support/result: doc-support/default.nix
-	(cd doc-support; nix-build)
-
-functions/library/locations.xml: doc-support/result
-	ln -rfs ./doc-support/result/function-locations.xml functions/library/locations.xml
-
-functions/library/generated: doc-support/result
-	ln -rfs ./doc-support/result/function-docs functions/library/generated
-
-%.section.xml: %.section.md
-	$(PANDOC) $^ -t docbook \
-		$(pandoc_flags) \
-		-o $@
-
-%.chapter.xml: %.chapter.md
-	$(PANDOC) $^ -t docbook \
-		--top-level-division=chapter \
-		$(pandoc_flags) \
-		-o $@
@@ -1,23 +0,0 @@
--[[
-Converts Code AST nodes produced by pandoc’s DocBook reader
-from citerefentry elements into AST for corresponding role
-for reStructuredText.
-
-We use subset of MyST syntax (CommonMark with features from rST)
-so let’s use the rST AST for rST features.
-
-Reference: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage
-]]
-
-function Code(elem)
-  elem.classes = elem.classes:map(function (x)
-    if x == 'citerefentry' then
-      elem.attributes['role'] = 'manpage'
-      return 'interpreted-text'
-    else
-      return x
-    end
-  end)
-
-  return elem
-end
@@ -1,34 +0,0 @@
--[[
-Converts Link AST nodes with empty label to DocBook xref elements.
-
-This is a temporary script to be able use cross-references conveniently
-using syntax taken from MyST, while we still use docbook-xsl
-for generating the documentation.
-
-Reference: https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing
-]]
-
-local function starts_with(start, str)
-  return str:sub(1, #start) == start
-end
-
-local function escape_xml_arg(arg)
-  amps = arg:gsub('&', '&amp;')
-  amps_quotes = amps:gsub('"', '&quot;')
-  amps_quotes_lt = amps_quotes:gsub('<', '&lt;')
-
-  return amps_quotes_lt
-end
-
-function Link(elem)
-  has_no_content = #elem.content == 0
-  targets_anchor = starts_with('#', elem.target)
-  has_no_attributes = elem.title == '' and elem.identifier == '' and #elem.classes == 0 and #elem.attributes == 0
-
-  if has_no_content and targets_anchor and has_no_attributes then
-    -- xref expects idref without the pound-sign
-    target_without_hash = elem.target:sub(2, #elem.target)
-
-    return pandoc.RawInline('docbook', '<xref linkend="' .. escape_xml_arg(target_without_hash) .. '" />')
-  end
-end
@@ -1,44 +0,0 @@
--[[
-Converts AST for reStructuredText roles into corresponding
-DocBook elements.
-
-Currently, only a subset of roles is supported.
-
-Reference:
-  List of roles:
-    https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
-  manpage:
-    https://tdg.docbook.org/tdg/5.1/citerefentry.html
-  file:
-    https://tdg.docbook.org/tdg/5.1/filename.html
-]]
-
-function Code(elem)
-  if elem.classes:includes('interpreted-text') then
-    local tag = nil
-    local content = elem.text
-    if elem.attributes['role'] == 'manpage' then
-      tag = 'citerefentry'
-      local title, volnum = content:match('^(.+)%((%w+)%)$')
-      if title == nil then
-        -- No volnum in parentheses.
-        title = content
-      end
-      content = '<refentrytitle>' .. title .. '</refentrytitle>' .. (volnum ~= nil and ('<manvolnum>' .. volnum .. '</manvolnum>') or '')
-    elseif elem.attributes['role'] == 'file' then
-      tag = 'filename'
-    elseif elem.attributes['role'] == 'command' then
-      tag = 'command'
-    elseif elem.attributes['role'] == 'option' then
-      tag = 'option'
-    elseif elem.attributes['role'] == 'var' then
-      tag = 'varname'
-    elseif elem.attributes['role'] == 'env' then
-      tag = 'envar'
-    end
-
-    if tag ~= nil then
-      return pandoc.RawInline('docbook', '<' .. tag .. '>' .. content .. '</' .. tag .. '>')
-    end
-  end
-end
@@ -1,17 +0,0 @@
--[[
-Turns a manpage reference into a link, when a mapping is defined below.
-]]
-
-local man_urls = {
-  ["tmpfiles.d(5)"] = "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html",
-  ["nix.conf(5)"] = "https://nixos.org/manual/nix/stable/#sec-conf-file",
-  ["systemd.time(7)"] = "https://www.freedesktop.org/software/systemd/man/systemd.time.html",
-  ["systemd.timer(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.timer.html",
-}
-
-function Code(elem)
-  local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'
-  if is_man_role and man_urls[elem.text] ~= nil then
-    return pandoc.Link(elem, man_urls[elem.text])
-  end
-end
@@ -1,29 +0,0 @@
--[[
-Replaces Str AST nodes containing {role}, followed by a Code node
-by a Code node with attrs that would be produced by rST reader
-from the role syntax.
-
-This is to emulate MyST syntax in Pandoc.
-(MyST is a CommonMark flavour with rST features mixed in.)
-
-Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point
-]]
-
-function Inlines(inlines)
-  for i = #inlines-1,1,-1 do
-    local first = inlines[i]
-    local second = inlines[i+1]
-    local correct_tags = first.tag == 'Str' and second.tag == 'Code'
-    if correct_tags then
-      -- docutils supports alphanumeric strings separated by [-._:]
-      -- We are slightly more liberal for simplicity.
-      local role = first.text:match('^{([-._+:%w]+)}$')
-      if role ~= nil then
-        inlines:remove(i)
-        second.attributes['role'] = role
-        second.classes:insert('interpreted-text')
-      end
-    end
-  end
-  return inlines
-end
@@ -1,25 +0,0 @@
--[[
-Replaces Code nodes with attrs that would be produced by rST reader
-from the role syntax by a Str AST node containing {role}, followed by a Code node.
-
-This is to emulate MyST syntax in Pandoc.
-(MyST is a CommonMark flavour with rST features mixed in.)
-
-Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point
-]]
-
-function Code(elem)
-  local role = elem.attributes['role']
-
-  if elem.classes:includes('interpreted-text') and role ~= nil then
-    elem.classes = elem.classes:filter(function (c)
-      return c ~= 'interpreted-text'
-    end)
-    elem.attributes['role'] = nil
-
-    return {
-      pandoc.Str('{' .. role .. '}'),
-      elem,
-    }
-  end
-end
@@ -0,0 +1,12 @@
+# Builders {#part-builders}
+
+```{=include=} chapters
+builders/fetchers.chapter.md
+builders/trivial-builders.chapter.md
+builders/testers.chapter.md
+builders/special.md
+builders/images.md
+hooks/index.md
+languages-frameworks/index.md
+builders/packages/index.md
+```
@@ -3,7 +3,7 @@
 Building software with Nix often requires downloading source code and other files from the internet.
 `nixpkgs` provides *fetchers* for different protocols and services. Fetchers are functions that simplify downloading files.

-## Caveats
+## Caveats {#chap-pkgs-fetchers-caveats}

 Fetchers create [fixed output derivations](https://nixos.org/manual/nix/stable/#fixed-output-drvs) from downloaded files.
 Nix can reuse the downloaded files via the hash of the resulting derivation.
@@ -14,7 +14,7 @@ For example, consider the following fetcher:
 ```nix
 fetchurl {
  url = "http://www.example.org/hello-1.0.tar.gz";
-  sha256 = "0v6r3wwnsk5pdjr188nip3pjgn1jrn5pc5ajpcfy6had6b3v4dwm";
+  hash = "sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww=";
 };
 ```

@@ -23,17 +23,17 @@ A common mistake is to update a fetcher’s URL, or a version parameter, without
 ```nix
 fetchurl {
  url = "http://www.example.org/hello-1.1.tar.gz";
-  sha256 = "0v6r3wwnsk5pdjr188nip3pjgn1jrn5pc5ajpcfy6had6b3v4dwm";
+  hash = "sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww=";
 };
 ```

 **This will reuse the old contents**.
-Remember to invalidate the hash argument, in this case by setting the `sha256` attribute to an empty string.
+Remember to invalidate the hash argument, in this case by setting the `hash` attribute to an empty string.

 ```nix
 fetchurl {
  url = "http://www.example.org/hello-1.1.tar.gz";
-  sha256 = "";
+  hash = "";
 };
 ```

@@ -42,14 +42,14 @@ Use the resulting error message to determine the correct hash.
 ```
 error: hash mismatch in fixed-output derivation '/path/to/my.drv':
         specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
-            got:    sha256-RApQUm78dswhBLC/rfU9y0u6pSAzHceIJqgmetRD24E=
+            got:    sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww=
 ```

 A similar problem arises while testing changes to a fetcher's implementation. If the output of the derivation already exists in the Nix store, test failures can go undetected. The [`invalidateFetcherByDrvHash`](#tester-invalidateFetcherByDrvHash) function helps prevent reusing cached derivations.

 ## `fetchurl` and `fetchzip` {#fetchurl}

-Two basic fetchers are `fetchurl` and `fetchzip`. Both of these have two required arguments, a URL and a hash. The hash is typically `sha256`, although many more hash algorithms are supported. Nixpkgs contributors are currently recommended to use `sha256`. This hash will be used by Nix to identify your source. A typical usage of `fetchurl` is provided below.
+Two basic fetchers are `fetchurl` and `fetchzip`. Both of these have two required arguments, a URL and a hash. The hash is typically `hash`, although many more hash algorithms are supported. Nixpkgs contributors are currently recommended to use `hash`. This hash will be used by Nix to identify your source. A typical usage of `fetchurl` is provided below.

 ```nix
 { stdenv, fetchurl }:
@@ -58,7 +58,7 @@ stdenv.mkDerivation {
  name = "hello";
  src = fetchurl {
    url = "http://www.example.org/hello.tar.gz";
-    sha256 = "1111111111111111111111111111111111111111111111111111";
+    hash = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";
  };
 }
 ```
@@ -71,23 +71,24 @@ The main difference between `fetchurl` and `fetchzip` is in how they store the c

 - `relative`: Similar to using `git-diff`'s `--relative` flag, only keep changes inside the specified directory, making paths relative to it.
 - `stripLen`: Remove the first `stripLen` components of pathnames in the patch.
+- `decode`: Pipe the downloaded data through this command before processing it as a patch.
 - `extraPrefix`: Prefix pathnames by this string.
 - `excludes`: Exclude files matching these patterns (applies after the above arguments).
 - `includes`: Include only files matching these patterns (applies after the above arguments).
 - `revert`: Revert the patch.

-Note that because the checksum is computed after applying these effects, using or modifying these arguments will have no effect unless the `sha256` argument is changed as well.
+Note that because the checksum is computed after applying these effects, using or modifying these arguments will have no effect unless the `hash` argument is changed as well.


 Most other fetchers return a directory rather than a single file.

 ## `fetchsvn` {#fetchsvn}

-Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `sha256`.
+Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `hash`.

 ## `fetchgit` {#fetchgit}

-Used with Git. Expects `url` to a Git repo, `rev`, and `sha256`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`.
+Used with Git. Expects `url` to a Git repo, `rev`, and `hash`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`.

 Additionally, the following optional arguments can be given: `fetchSubmodules = true` makes `fetchgit` also fetch the submodules of a repository. If `deepClone` is set to true, the entire repository is cloned as opposing to just creating a shallow clone. `deepClone = true` also implies `leaveDotGit = true` which means that the `.git` directory of the clone won't be removed after checkout.

@@ -100,42 +101,47 @@ stdenv.mkDerivation {
  name = "hello";
  src = fetchgit {
    url = "https://...";
-    sparseCheckout = ''
-      directory/to/be/included
-      another/directory
-    '';
-    sha256 = "0000000000000000000000000000000000000000000000000000";
+    sparseCheckout = [
+      "directory/to/be/included"
+      "another/directory"
+    ];
+    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };
 }
 ```

 ## `fetchfossil` {#fetchfossil}

-Used with Fossil. Expects `url` to a Fossil archive, `rev`, and `sha256`.
+Used with Fossil. Expects `url` to a Fossil archive, `rev`, and `hash`.

 ## `fetchcvs` {#fetchcvs}

-Used with CVS. Expects `cvsRoot`, `tag`, and `sha256`.
+Used with CVS. Expects `cvsRoot`, `tag`, and `hash`.

 ## `fetchhg` {#fetchhg}

-Used with Mercurial. Expects `url`, `rev`, and `sha256`.
+Used with Mercurial. Expects `url`, `rev`, and `hash`.

 A number of fetcher functions wrap part of `fetchurl` and `fetchzip`. They are mainly convenience functions intended for commonly used destinations of source code in Nixpkgs. These wrapper fetchers are listed below.

 ## `fetchFromGitea` {#fetchfromgitea}

-`fetchFromGitea` expects five arguments. `domain` is the gitea server name. `owner` is a string corresponding to the Gitea user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every Gitea HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `sha256` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available but `sha256` is currently preferred.
+`fetchFromGitea` expects five arguments. `domain` is the gitea server name. `owner` is a string corresponding to the Gitea user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every Gitea HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available but `hash` is currently preferred.

 ## `fetchFromGitHub` {#fetchfromgithub}

-`fetchFromGitHub` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `sha256` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `sha256` is currently preferred.
+`fetchFromGitHub` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `hash` is currently preferred.
+
+To use a different GitHub instance, use `githubBase` (defaults to `"github.com"`).

 `fetchFromGitHub` uses `fetchzip` to download the source archive generated by GitHub for the specified revision. If `leaveDotGit`, `deepClone` or `fetchSubmodules` are set to `true`, `fetchFromGitHub` will use `fetchgit` instead. Refer to its section for documentation of these options.

 ## `fetchFromGitLab` {#fetchfromgitlab}

-This is used with GitLab repositories. The arguments expected are very similar to `fetchFromGitHub` above.
+This is used with GitLab repositories. It behaves similarly to `fetchFromGitHub`, and expects `owner`, `repo`, `rev`, and `hash`.
+
+To use a specific GitLab instance, use `domain` (defaults to `"gitlab.com"`).
+

 ## `fetchFromGitiles` {#fetchfromgitiles}

@@ -143,7 +149,7 @@ This is used with Gitiles repositories. The arguments expected are similar to `f

 ## `fetchFromBitbucket` {#fetchfrombitbucket}

-This is used with BitBucket repositories. The arguments expected are very similar to fetchFromGitHub above.
+This is used with BitBucket repositories. The arguments expected are very similar to `fetchFromGitHub` above.

 ## `fetchFromSavannah` {#fetchfromsavannah}

@@ -156,10 +162,37 @@ This is used with repo.or.cz repositories. The arguments expected are very simil
 ## `fetchFromSourcehut` {#fetchfromsourcehut}

 This is used with sourcehut repositories. Similar to `fetchFromGitHub` above,
-it expects `owner`, `repo`, `rev` and `sha256`, but don't forget the tilde (~)
+it expects `owner`, `repo`, `rev` and `hash`, but don't forget the tilde (~)
 in front of the username! Expected arguments also include `vc` ("git" (default)
 or "hg"), `domain` and `fetchSubmodules`.

 If `fetchSubmodules` is `true`, `fetchFromSourcehut` uses `fetchgit`
 or `fetchhg` with `fetchSubmodules` or `fetchSubrepos` set to `true`,
 respectively. Otherwise, the fetcher uses `fetchzip`.
+
+## `requireFile` {#requirefile}
+
+`requireFile` allows requesting files that cannot be fetched automatically, but whose content is known.
+This is a useful last-resort workaround for license restrictions that prohibit redistribution, or for downloads that are only accessible after authenticating interactively in a browser.
+If the requested file is present in the Nix store, the resulting derivation will not be built, because its expected output is already available.
+Otherwise, the builder will run, but fail with a message explaining to the user how to provide the file. The following code, for example:
+
+```
+requireFile {
+  name = "jdk-${version}_linux-x64_bin.tar.gz";
+  url = "https://www.oracle.com/java/technologies/javase-jdk11-downloads.html";
+  sha256 = "94bd34f85ee38d3ef59e5289ec7450b9443b924c55625661fffe66b03f2c8de2";
+}
+```
+results in this error message:
+```
+***
+Unfortunately, we cannot download file jdk-11.0.10_linux-x64_bin.tar.gz automatically.
+Please go to https://www.oracle.com/java/technologies/javase-jdk11-downloads.html to download it yourself, and add it to the Nix store
+using either
+  nix-store --add-fixed sha256 jdk-11.0.10_linux-x64_bin.tar.gz
+or
+  nix-prefetch-url --type sha256 file:///path/to/jdk-11.0.10_linux-x64_bin.tar.gz
+
+***
+```
@@ -0,0 +1,13 @@
+# Images {#chap-images}
+
+This chapter describes tools for creating various types of images.
+
+```{=include=} sections
+images/appimagetools.section.md
+images/dockertools.section.md
+images/ocitools.section.md
+images/snaptools.section.md
+images/portableservice.section.md
+images/makediskimage.section.md
+images/binarycache.section.md
+```
@@ -1,12 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="chap-images">
- <title>Images</title>
- <para>
-  This chapter describes tools for creating various types of images.
- </para>
- <xi:include href="images/appimagetools.section.xml" />
- <xi:include href="images/dockertools.section.xml" />
- <xi:include href="images/ocitools.section.xml" />
- <xi:include href="images/snaptools.section.xml" />
-</chapter>
@@ -35,7 +35,7 @@ appimageTools.wrapType2 { # or wrapType1
  name = "patchwork";
  src = fetchurl {
    url = "https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage";
-    sha256 = "1blsprpkvm0ws9b96gb36f0rbf8f5jgmw4x6dsb1kswr4ysf591s";
+    hash = "sha256-OqTitCeZ6xmWbqYTXp8sDrmVgTNjPZNW0hzUPW++mq4=";
  };
  extraPkgs = pkgs: with pkgs; [ ];
 }
@@ -0,0 +1,49 @@
+# pkgs.mkBinaryCache {#sec-pkgs-binary-cache}
+
+`pkgs.mkBinaryCache` is a function for creating Nix flat-file binary caches. Such a cache exists as a directory on disk, and can be used as a Nix substituter by passing `--substituter file:///path/to/cache` to Nix commands.
+
+Nix packages are most commonly shared between machines using [HTTP, SSH, or S3](https://nixos.org/manual/nix/stable/package-management/sharing-packages.html), but a flat-file binary cache can still be useful in some situations. For example, you can copy it directly to another machine, or make it available on a network file system. It can also be a convenient way to make some Nix packages available inside a container via bind-mounting.
+
+Note that this function is meant for advanced use-cases. The more idiomatic way to work with flat-file binary caches is via the [nix-copy-closure](https://nixos.org/manual/nix/stable/command-ref/nix-copy-closure.html) command. You may also want to consider [dockerTools](#sec-pkgs-dockerTools) for your containerization needs.
+
+## Example {#sec-pkgs-binary-cache-example}
+
+The following derivation will construct a flat-file binary cache containing the closure of `hello`.
+
+```nix
+mkBinaryCache {
+  rootPaths = [hello];
+}
+```
+
+- `rootPaths` specifies a list of root derivations. The transitive closure of these derivations' outputs will be copied into the cache.
+
+Here's an example of building and using the cache.
+
+Build the cache on one machine, `host1`:
+
+```shellSession
+nix-build -E 'with import <nixpkgs> {}; mkBinaryCache { rootPaths = [hello]; }'
+```
+
+```shellSession
+/nix/store/cc0562q828rnjqjyfj23d5q162gb424g-binary-cache
+```
+
+Copy the resulting directory to the other machine, `host2`:
+
+```shellSession
+scp result host2:/tmp/hello-cache
+```
+
+Substitute the derivation using the flat-file binary cache on the other machine, `host2`:
+```shellSession
+nix-build -A hello '<nixpkgs>' \
+  --option require-sigs false \
+  --option trusted-substituters file:///tmp/hello-cache \
+  --option substituters file:///tmp/hello-cache
+```
+
+```shellSession
+/nix/store/gl5a41azbpsadfkfmbilh9yk40dh5dl0-hello-2.12.1
+```
@@ -62,6 +62,8 @@ The above example will build a Docker image `redis/latest` from the given base i

 - `config` is used to specify the configuration of the containers that will be started off the built image in Docker. The available options are listed in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions).

+- `architecture` is _optional_ and used to specify the image architecture, this is useful for multi-architecture builds that don't need cross compiling. If not specified it will default to `hostPlatform`.
+
 - `diskSize` is used to specify the disk size of the VM used to build the image in megabytes. By default it's 1024 MiB.

 - `buildVMMemorySize` is used to specify the memory size of the VM to build the image in megabytes. By default it's 512 MiB.
@@ -141,7 +143,9 @@ Create a Docker image with many of the store paths being on their own layer to i

 `config` _optional_

-: Run-time configuration of the container. A full list of the options are available at in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions).
+`architecture` is _optional_ and used to specify the image architecture, this is useful for multi-architecture builds that don't need cross compiling. If not specified it will default to `hostPlatform`.
+
+: Run-time configuration of the container. A full list of the options available is in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions).

    *Default:* `{}`

@@ -245,10 +249,10 @@ Its parameters are described in the example below:
 pullImage {
  imageName = "nixos/nix";
  imageDigest =
-    "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b";
+    "sha256:473a2b527958665554806aea24d0131bacec46d23af09fef4598eeab331850fa";
  finalImageName = "nix";
-  finalImageTag = "1.11";
-  sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8";
+  finalImageTag = "2.11.1";
+  sha256 = "sha256-qvhj+Hlmviz+KEBVmsyPIzTB3QlVAFzwAY1zDPIBGxc=";
  os = "linux";
  arch = "x86_64";
 }
@@ -394,3 +398,142 @@ buildImage {
  };
 }
 ```
+
+## buildNixShellImage {#ssec-pkgs-dockerTools-buildNixShellImage}
+
+Create a Docker image that sets up an environment similar to that of running `nix-shell` on a derivation.
+When run in Docker, this environment somewhat resembles the Nix sandbox typically used by `nix-build`, with a major difference being that access to the internet is allowed.
+It additionally also behaves like an interactive `nix-shell`, running things like `shellHook` and setting an interactive prompt.
+If the derivation is fully buildable (i.e. `nix-build` can be used on it), running `buildDerivation` inside such a Docker image will build the derivation, with all its outputs being available in the correct `/nix/store` paths, pointed to by the respective environment variables like `$out`, etc.
+
+::: {.warning}
+The behavior doesn't match `nix-shell` or `nix-build` exactly and this function is known not to work correctly for e.g. fixed-output derivations, content-addressed derivations, impure derivations and other special types of derivations.
+:::
+
+### Arguments {#ssec-pkgs-dockerTools-buildNixShellImage-arguments}
+
+`drv`
+
+: The derivation on which to base the Docker image.
+
+    Adding packages to the Docker image is possible by e.g. extending the list of `nativeBuildInputs` of this derivation like
+
+    ```nix
+    buildNixShellImage {
+      drv = someDrv.overrideAttrs (old: {
+        nativeBuildInputs = old.nativeBuildInputs or [] ++ [
+          somethingExtra
+        ];
+      });
+      # ...
+    }
+    ```
+
+    Similarly, you can extend the image initialization script by extending `shellHook`
+
+`name` _optional_
+
+: The name of the resulting image.
+
+    *Default:* `drv.name + "-env"`
+
+`tag` _optional_
+
+: Tag of the generated image.
+
+    *Default:* the resulting image derivation output path's hash
+
+`uid`/`gid` _optional_
+
+: The user/group ID to run the container as. This is like a `nixbld` build user.
+
+    *Default:* 1000/1000
+
+`homeDirectory` _optional_
+
+: The home directory of the user the container is running as
+
+    *Default:* `/build`
+
+`shell` _optional_
+
+: The path to the `bash` binary to use as the shell. This shell is started when running the image.
+
+    *Default:* `pkgs.bashInteractive + "/bin/bash"`
+
+`command` _optional_
+
+: Run this command in the environment of the derivation, in an interactive shell. See the `--command` option in the [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html?highlight=nix-shell#options).
+
+    *Default:* (none)
+
+`run` _optional_
+
+: Same as `command`, but runs the command in a non-interactive shell instead. See the `--run` option in the [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html?highlight=nix-shell#options).
+
+    *Default:* (none)
+
+### Example {#ssec-pkgs-dockerTools-buildNixShellImage-example}
+
+The following shows how to build the `pkgs.hello` package inside a Docker container built with `buildNixShellImage`.
+
+```nix
+with import <nixpkgs> {};
+dockerTools.buildNixShellImage {
+  drv = hello;
+}
+```
+
+Build the derivation:
+
+```console
+nix-build hello.nix
+```
+
+    these 8 derivations will be built:
+      /nix/store/xmw3a5ln29rdalavcxk1w3m4zb2n7kk6-nix-shell-rc.drv
+    ...
+    Creating layer 56 from paths: ['/nix/store/crpnj8ssz0va2q0p5ibv9i6k6n52gcya-stdenv-linux']
+    Creating layer 57 with customisation...
+    Adding manifests...
+    Done.
+    /nix/store/cpyn1lc897ghx0rhr2xy49jvyn52bazv-hello-2.12-env.tar.gz
+
+Load the image:
+
+```console
+docker load -i result
+```
+
+    0d9f4c4cd109: Loading layer [==================================================>]   2.56MB/2.56MB
+    ...
+    ab1d897c0697: Loading layer [==================================================>]  10.24kB/10.24kB
+    Loaded image: hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz
+
+Run the container:
+
+```console
+docker run -it hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz
+```
+
+    [nix-shell:/build]$
+
+In the running container, run the build:
+
+```console
+buildDerivation
+```
+
+    unpacking sources
+    unpacking source archive /nix/store/8nqv6kshb3vs5q5bs2k600xpj5bkavkc-hello-2.12.tar.gz
+    ...
+    patching script interpreter paths in /nix/store/z5wwy5nagzy15gag42vv61c2agdpz2f2-hello-2.12
+    checking for references to /build/ in /nix/store/z5wwy5nagzy15gag42vv61c2agdpz2f2-hello-2.12...
+
+Check the build result:
+
+```console
+$out/bin/hello
+```
+
+    Hello, world!
@@ -0,0 +1,108 @@
+# `<nixpkgs/nixos/lib/make-disk-image.nix>` {#sec-make-disk-image}
+
+`<nixpkgs/nixos/lib/make-disk-image.nix>` is a function to create _disk images_ in multiple formats: raw, QCOW2 (QEMU), QCOW2-Compressed (compressed version), VDI (VirtualBox), VPC (VirtualPC).
+
+This function can create images in two ways:
+
+- using `cptofs` without any virtual machine to create a Nix store disk image,
+- using a virtual machine to create a full NixOS installation.
+
+When testing early-boot or lifecycle parts of NixOS such as a bootloader or multiple generations, it is necessary to opt for a full NixOS system installation.
+Whereas for many web servers, applications, it is possible to work with a Nix store only disk image and is faster to build.
+
+NixOS tests also use this function when preparing the VM. The `cptofs` method is used when `virtualisation.useBootLoader` is false (the default). Otherwise the second method is used.
+
+## Features {#sec-make-disk-image-features}
+
+For reference, read the function signature source code for documentation on arguments: <https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/make-disk-image.nix>.
+Features are separated in various sections depending on if you opt for a Nix-store only image or a full NixOS image.
+
+### Common {#sec-make-disk-image-features-common}
+
+- arbitrary NixOS configuration
+- automatic or bound disk size: `diskSize` parameter, `additionalSpace` can be set when `diskSize` is `auto` to add a constant of disk space
+- multiple partition table layouts: EFI, legacy, legacy + GPT, hybrid, none through `partitionTableType` parameter
+- OVMF or EFI firmwares and variables templates can be customized
+- root filesystem `fsType` can be customized to whatever `mkfs.${fsType}` exist during operations
+- root filesystem label can be customized, defaults to `nix-store` if it's a Nix store image, otherwise `nixpkgs/nixos`
+- arbitrary code can be executed after disk image was produced with `postVM`
+- the current nixpkgs can be realized as a channel in the disk image, which will change the hash of the image when the sources are updated
+- additional store paths can be provided through `additionalPaths`
+
+### Full NixOS image {#sec-make-disk-image-features-full-image}
+
+- arbitrary contents with permissions can be placed in the target filesystem using `contents`
+- a `/etc/nixpkgs/nixos/configuration.nix` can be provided through `configFile`
+- bootloaders are supported
+- EFI variables can be mutated during image production and the result is exposed in `$out`
+- boot partition size when partition table is `efi` or `hybrid`
+
+### On bit-to-bit reproducibility {#sec-make-disk-image-features-reproducibility}
+
+Images are **NOT** deterministic, please do not hesitate to try to fix this, source of determinisms are (not exhaustive) :
+
+- bootloader installation have timestamps
+- SQLite Nix store database contain registration times
+- `/etc/shadow` is in a non-deterministic order
+
+A `deterministic` flag is available for best efforts determinism.
+
+## Usage {#sec-make-disk-image-usage}
+
+To produce a Nix-store only image:
+```nix
+let
+  pkgs = import <nixpkgs> {};
+  lib = pkgs.lib;
+  make-disk-image = import <nixpkgs/nixos/lib/make-disk-image.nix>;
+in
+  make-disk-image {
+    inherit pkgs lib;
+    config = {};
+    additionalPaths = [ ];
+    format = "qcow2";
+    onlyNixStore = true;
+    partitionTableType = "none";
+    installBootLoader = false;
+    touchEFIVars = false;
+    diskSize = "auto";
+    additionalSpace = "0M"; # Defaults to 512M.
+    copyChannel = false;
+  }
+```
+
+Some arguments can be left out, they are shown explicitly for the sake of the example.
+
+Building this derivation will provide a QCOW2 disk image containing only the Nix store and its registration information.
+
+To produce a NixOS installation image disk with UEFI and bootloader installed:
+```nix
+let
+  pkgs = import <nixpkgs> {};
+  lib = pkgs.lib;
+  make-disk-image = import <nixpkgs/nixos/lib/make-disk-image.nix>;
+  evalConfig = import <nixpkgs/nixos/lib/eval-config.nix>;
+in
+  make-disk-image {
+    inherit pkgs lib;
+    config = evalConfig {
+      modules = [
+        {
+          fileSystems."/" = { device = "/dev/vda"; fsType = "ext4"; autoFormat = true; };
+          boot.grub.device = "/dev/vda";
+        }
+      ];
+    };
+    format = "qcow2";
+    onlyNixStore = false;
+    partitionTableType = "legacy+gpt";
+    installBootLoader = true;
+    touchEFIVars = true;
+    diskSize = "auto";
+    additionalSpace = "0M"; # Defaults to 512M.
+    copyChannel = false;
+    memSize = 2048; # Qemu VM memory size in megabytes. Defaults to 1024M.
+  }
+```
+
+
@@ -34,4 +34,4 @@ buildContainer {

 - `mounts` specifies additional mount points chosen by the user. By default only a minimal set of necessary filesystems are mounted into the container (e.g procfs, cgroupfs)

- `readonly` makes the container\'s rootfs read-only if it is set to true. The default value is false `false`.
+- `readonly` makes the container's rootfs read-only if it is set to true. The default value is false `false`.
@@ -0,0 +1,81 @@
+# pkgs.portableService {#sec-pkgs-portableService}
+
+`pkgs.portableService` is a function to create _portable service images_,
+as read-only, immutable, `squashfs` archives.
+
+systemd supports a concept of [Portable Services](https://systemd.io/PORTABLE_SERVICES/).
+Portable Services are a delivery method for system services that uses two specific features of container management:
+
+* Applications are bundled. I.e. multiple services, their binaries and
+  all their dependencies are packaged in an image, and are run directly from it.
+* Stricter default security policies, i.e. sandboxing of applications.
+
+This allows using Nix to build images which can be run on many recent Linux distributions.
+
+The primary tool for interacting with Portable Services is `portablectl`,
+and they are managed by the `systemd-portabled` system service.
+
+::: {.note}
+Portable services are supported starting with systemd 239 (released on 2018-06-22).
+:::
+
+A very simple example of using `portableService` is described below:
+
+[]{#ex-pkgs-portableService}
+
+```nix
+pkgs.portableService {
+  pname = "demo";
+  version = "1.0";
+  units = [ demo-service demo-socket ];
+}
+```
+
+The above example will build an squashfs archive image in `result/$pname_$version.raw`. The image will contain the
+file system structure as required by the portable service specification, and a subset of the Nix store with all the
+dependencies of the two derivations in the `units` list.
+`units` must be a list of derivations, and their names must be prefixed with the service name (`"demo"` in this case).
+Otherwise `systemd-portabled` will ignore them.
+
+::: {.note}
+The `.raw` file extension of the image is required by the portable services specification.
+:::
+
+Some other options available are:
+- `description`, `homepage`
+
+  Are added to the `/etc/os-release` in the image and are shown by the portable services tooling.
+  Default to empty values, not added to os-release.
+- `symlinks`
+
+  A list of attribute sets {object, symlink}. Symlinks will be created  in the root filesystem of the image to
+  objects in the Nix store. Defaults to an empty list.
+- `contents`
+
+  A list of additional derivations to be included in the image Nix store, as-is. Defaults to an empty list.
+- `squashfsTools`
+
+  Defaults to `pkgs.squashfsTools`, allows you to override the package that provides `mksquashfs`.
+- `squash-compression`, `squash-block-size`
+
+  Options to `mksquashfs`. Default to `"xz -Xdict-size 100%"` and `"1M"` respectively.
+
+A typical usage of `symlinks` would be:
+```nix
+  symlinks = [
+    { object = "${pkgs.cacert}/etc/ssl"; symlink = "/etc/ssl"; }
+    { object = "${pkgs.bash}/bin/bash"; symlink = "/bin/sh"; }
+    { object = "${pkgs.php}/bin/php"; symlink = "/usr/bin/php"; }
+  ];
+```
+to create these symlinks for legacy applications that assume them existing globally.
+
+Once the image is created, and deployed on a host in `/var/lib/portables/`, you can attach the image and run the service. As root run:
+```console
+portablectl attach demo_1.0.raw
+systemctl enable --now demo.socket
+systemctl enable --now demo.service
+```
+::: {.note}
+See the [man page](https://www.freedesktop.org/software/systemd/man/portablectl.html) of `portablectl` for more info on its usage.
+:::
@@ -103,7 +103,7 @@ let
        owner = "Someone";
        repo = "AwesomeMod";
        rev = "...";
-        sha256 = "...";
+        hash = "...";
      };
      # Path to be installed in the unpacked source (default: ".")
      modRoot = "contents/under/this/path/will/be/installed";
@@ -4,7 +4,7 @@ The [Citrix Workspace App](https://www.citrix.com/products/workspace-app/) is a

 ## 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.de/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.
+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}

@@ -19,7 +19,7 @@ $ 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://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/), 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`:
+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; };
@@ -1,10 +1,10 @@
 # DLib {#dlib}

-[DLib](http://dlib.net/) is a modern, C++-based toolkit which provides several machine learning algorithms.
+[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.
+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:

@@ -43,11 +43,11 @@ packageOverrides = pkgs: {
        name = "myplugin1-1.0";
        srcFeature = fetchurl {
          url = "http://…/features/myplugin1.jar";
-          sha256 = "123…";
+          hash = "sha256-123…";
        };
        srcPlugin = fetchurl {
          url = "http://…/plugins/myplugin1.jar";
-          sha256 = "123…";
+          hash = "sha256-123…";
        };
      });
      (plugins.buildEclipseUpdateSite {
@@ -55,7 +55,7 @@ packageOverrides = pkgs: {
        src = fetchurl {
          stripRoot = false;
          url = "http://…/myplugin2.zip";
-          sha256 = "123…";
+          hash = "sha256-123…";
        };
      });
    ];
@@ -12,7 +12,7 @@ The `wrapFirefox` function allows to pass policies, preferences and extensions t
      (fetchFirefoxAddon {
        name = "ublock"; # Has to be unique!
        url = "https://addons.mozilla.org/firefox/downloads/file/3679754/ublock_origin-1.31.0-an+fx.xpi";
-        sha256 = "1h768ljlh3pi23l27qp961v1hd0nbj2vasgy11bmcrlqp40zgvnr";
+        hash = "sha256-2e73AbmYZlZXCP5ptYVcFjQYdjDp4iPoEPEOSCVF5sA=";
      })
    ];

@@ -4,7 +4,7 @@ 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/documentation.html).
+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:

@@ -34,5 +34,7 @@ The `ibus-engines.typing-booster` package contains a program named `emoji-picker
 On NixOS, it can be installed using the following expression:

 ```nix
-{ pkgs, ... }: { fonts.fonts = with pkgs; [ noto-fonts-emoji ]; }
+{ pkgs, ... }: {
+  fonts.packages = with pkgs; [ noto-fonts-emoji ];
+}
 ```
@@ -0,0 +1,27 @@
+# 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
+dlib.section.md
+eclipse.section.md
+elm.section.md
+emacs.section.md
+firefox.section.md
+fish.section.md
+fuse.section.md
+ibus.section.md
+kakoune.section.md
+linux.section.md
+locales.section.md
+etc-files.section.md
+nginx.section.md
+opengl.section.md
+shell-helpers.section.md
+steam.section.md
+cataclysm-dda.section.md
+urxvt.section.md
+weechat.section.md
+xorg.section.md
+```
@@ -1,29 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="chap-packages">
- <title>Packages</title>
- <para>
-  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.
- </para>
- <xi:include href="citrix.section.xml" />
- <xi:include href="dlib.section.xml" />
- <xi:include href="eclipse.section.xml" />
- <xi:include href="elm.section.xml" />
- <xi:include href="emacs.section.xml" />
- <xi:include href="firefox.section.xml" />
- <xi:include href="fish.section.xml" />
- <xi:include href="fuse.section.xml" />
- <xi:include href="ibus.section.xml" />
- <xi:include href="kakoune.section.xml" />
- <xi:include href="linux.section.xml" />
- <xi:include href="locales.section.xml" />
- <xi:include href="etc-files.section.xml" />
- <xi:include href="nginx.section.xml" />
- <xi:include href="opengl.section.xml" />
- <xi:include href="shell-helpers.section.xml" />
- <xi:include href="steam.section.xml" />
- <xi:include href="cataclysm-dda.section.xml" />
- <xi:include href="urxvt.section.xml" />
- <xi:include href="weechat.section.xml" />
- <xi:include href="xorg.section.xml" />
-</chapter>
@@ -73,7 +73,7 @@ stdenv.mkDerivation {
  name = "exemplary-weechat-script";
  src = fetchurl {
    url = "https://scripts.tld/your-scripts.tar.gz";
-    sha256 = "...";
+    hash = "...";
  };
  passthru.scripts = [ "foo.py" "bar.lua" ];
  installPhase = ''
@@ -0,0 +1,11 @@
+# Special builders {#chap-special}
+
+This chapter describes several special builders.
+
+```{=include=} sections
+special/fhs-environments.section.md
+special/makesetuphook.section.md
+special/mkshell.section.md
+special/darwin-builder.section.md
+special/vm-tools.section.md
+```
@@ -1,10 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="chap-special">
- <title>Special builders</title>
- <para>
-  This chapter describes several special builders.
- </para>
- <xi:include href="special/fhs-environments.section.xml" />
- <xi:include href="special/mkshell.section.xml" />
-</chapter>
@@ -0,0 +1,159 @@
+# darwin.linux-builder {#sec-darwin-builder}
+
+`darwin.linux-builder` provides a way to bootstrap a Linux builder on a macOS machine.
+
+This requires macOS version 12.4 or later.
+
+The 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 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 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}
+
+```
+{
+  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/macos-builder.nix"
+        { virtualisation.host.pkgs = pkgs; }
+      ];
+    };
+  in {
+
+    darwinConfigurations = {
+      machine1 = darwinSystem {
+        inherit system;
+        modules = [
+          {
+            nix.distributedBuilds = true;
+            nix.buildMachines = [{
+              hostName = "ssh://builder@localhost";
+              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 builder {#sec-darwin-builder-reconfiguring}
+
+Initially you should not change the builder configuration else you will not be
+able to use the binary cache. However, after you have the builder running locally
+you may use it to build a modified 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.
+
+```
+    darwin-builder = nixpkgs.lib.nixosSystem {
+      system = linuxSystem;
+      modules = [
+        "${nixpkgs}/nixos/modules/profiles/macos-builder.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.
+
@@ -1,13 +1,18 @@
-# buildFHSUserEnv {#sec-fhs-environments}
+# buildFHSEnv {#sec-fhs-environments}

-`buildFHSUserEnv` provides a way to build and run FHS-compatible lightweight sandboxes. It creates an isolated root with bound `/nix/store`, so its footprint in terms of disk space needed is quite small. This allows one to run software which is hard or unfeasible to patch for NixOS -- 3rd-party source trees with FHS assumptions, games distributed as tarballs, software with integrity checking and/or external self-updated binaries. It uses Linux namespaces feature to create temporary lightweight environments which are destroyed after all child processes exit, without root user rights requirement. Accepted arguments are:
+`buildFHSEnv` provides a way to build and run FHS-compatible lightweight sandboxes. It creates an isolated root filesystem with the host's `/nix/store`, so its footprint in terms of disk space is quite small. This allows you to run software which is hard or unfeasible to patch for NixOS; 3rd-party source trees with FHS assumptions, games distributed as tarballs, software with integrity checking and/or external self-updated binaries for instance.
+It uses Linux' namespaces feature to create temporary lightweight environments which are destroyed after all child processes exit, without requiring elevated privileges. It works similar to containerisation technology such as Docker or FlatPak but provides no security-relevant separation from the host system.
+
+Accepted arguments are:

 - `name`
-        Environment name.
+        The name of the environment and the wrapper executable.
 - `targetPkgs`
        Packages to be installed for the main host's architecture (i.e. x86_64 on x86_64 installations). Along with libraries binaries are also installed.
 - `multiPkgs`
        Packages to be installed for all architectures supported by a host (i.e. i686 and x86_64 on x86_64 installations). Only libraries are installed by default.
+- `multiArch`
+        Whether to install 32bit multiPkgs into the FHSEnv in 64bit environments
 - `extraBuildCommands`
        Additional commands to be executed for finalizing the directory structure.
 - `extraBuildCommandsMulti`
@@ -17,33 +22,35 @@
 - `extraInstallCommands`
        Additional commands to be executed for finalizing the derivation with runner script.
 - `runScript`
-        A command that would be executed inside the sandbox and passed all the command line arguments. It defaults to `bash`.
+        A shell command to be executed inside the sandbox. It defaults to `bash`. Command line arguments passed to the resulting wrapper are appended to this command by default.
+        This command must be escaped; i.e. `"foo app" --do-stuff --with "some file"`. See `lib.escapeShellArgs`.
 - `profile`
        Optional script for `/etc/profile` within the sandbox.

-One can create a simple environment using a `shell.nix` like that:
+You can create a simple environment using a `shell.nix` like this:

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

-(pkgs.buildFHSUserEnv {
+(pkgs.buildFHSEnv {
  name = "simple-x11-env";
-  targetPkgs = pkgs: (with pkgs;
-    [ udev
-      alsa-lib
-    ]) ++ (with pkgs.xorg;
-    [ libX11
-      libXcursor
-      libXrandr
-    ]);
-  multiPkgs = pkgs: (with pkgs;
-    [ udev
-      alsa-lib
-    ]);
+  targetPkgs = pkgs: (with pkgs; [
+    udev
+    alsa-lib
+  ]) ++ (with pkgs.xorg; [
+    libX11
+    libXcursor
+    libXrandr
+  ]);
+  multiPkgs = pkgs: (with pkgs; [
+    udev
+    alsa-lib
+  ]);
  runScript = "bash";
 }).env
 ```

-Running `nix-shell` would then drop you into a shell with these libraries and binaries available. You can use this to run closed-source applications which expect FHS structure without hassles: simply change `runScript` to the application path, e.g. `./bin/start.sh` -- relative paths are supported.
+Running `nix-shell` on it would drop you into a shell inside an FHS env where those libraries and binaries are available in FHS-compliant paths. Applications that expect an FHS structure (i.e. proprietary binaries) can run inside this environment without modification.
+You can build a wrapper by running your binary in `runScript`, e.g. `./bin/start.sh`. Relative paths work as expected.

 Additionally, the FHS builder links all relocated gsettings-schemas (the glib setup-hook moves them to `share/gsettings-schemas/${name}/glib-2.0/schemas`) to their standard FHS location. This means you don't need to wrap binaries with `wrapGAppsHook`.
@@ -0,0 +1,37 @@
+# pkgs.makeSetupHook {#sec-pkgs.makeSetupHook}
+
+`pkgs.makeSetupHook` is a builder that produces hooks that go in to `nativeBuildInputs`
+
+## Usage {#sec-pkgs.makeSetupHook-usage}
+
+```nix
+pkgs.makeSetupHook {
+  name = "something-hook";
+  propagatedBuildInputs = [ pkgs.commandsomething ];
+  depsTargetTargetPropagated = [ pkgs.libsomething ];
+} ./script.sh
+```
+
+### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash {#sec-pkgs.makeSetupHook-usage-example}
+
+```nix
+pkgs.makeSetupHook {
+    name = "run-hello-hook";
+    propagatedBuildInputs = [ pkgs.hello ];
+    substitutions = { shell = "${pkgs.bash}/bin/bash"; };
+    passthru.tests.greeting = callPackage ./test { };
+    meta.platforms = lib.platforms.linux;
+} (writeScript "run-hello-hook.sh" ''
+    #!@shell@
+    hello
+'')
+```
+
+## Attributes {#sec-pkgs.makeSetupHook-attributes}
+
+* `name` Set the name of the hook.
+* `propagatedBuildInputs` Runtime dependencies (such as binaries) of the hook.
+* `depsTargetTargetPropagated` Non-binary dependencies.
+* `meta`
+* `passthru`
+* `substitutions` Variables for `substituteAll`
@@ -20,7 +20,7 @@ pkgs.mkShell {
 }
 ```

-## Attributes
+## Attributes {#sec-pkgs-mkShell-attributes}

 * `name` (default: `nix-shell`). Set the name of the derivation.
 * `packages` (default: `[]`). Add executable packages to the `nix-shell` environment.
@@ -29,7 +29,7 @@ pkgs.mkShell {

 ... all the attributes of `stdenv.mkDerivation`.

-## Building the shell
+## Building the shell {#sec-pkgs-mkShell-building}

 This derivation output will contain a text file that contains a reference to
 all the build inputs. This is useful in CI where we want to make sure that
@@ -0,0 +1,148 @@
+# vmTools {#sec-vm-tools}
+
+A set of VM related utilities, that help in building some packages in more advanced scenarios.
+
+## `vmTools.createEmptyImage` {#vm-tools-createEmptyImage}
+
+A bash script fragment that produces a disk image at `destination`.
+
+### Attributes {#vm-tools-createEmptyImage-attributes}
+
+* `size`. The disk size, in MiB.
+* `fullName`. Name that will be written to `${destination}/nix-support/full-name`.
+* `destination` (optional, default `$out`). Where to write the image files.
+
+## `vmTools.runInLinuxVM` {#vm-tools-runInLinuxVM}
+
+Run a derivation in a Linux virtual machine (using Qemu/KVM).
+By default, there is no disk image; the root filesystem is a `tmpfs`, and the Nix store is shared with the host (via the [9P protocol](https://wiki.qemu.org/Documentation/9p#9p_Protocol)).
+Thus, any pure Nix derivation should run unmodified.
+
+If the build fails and Nix is run with the `-K/--keep-failed` option, a script `run-vm` will be left behind in the temporary build directory that allows you to boot into the VM and debug it interactively.
+
+### Attributes {#vm-tools-runInLinuxVM-attributes}
+
+* `preVM` (optional). Shell command to be evaluated *before* the VM is started (i.e., on the host).
+* `memSize` (optional, default `512`). The memory size of the VM in MiB.
+* `diskImage` (optional). A file system image to be attached to `/dev/sda`.
+  Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
+
+### Examples {#vm-tools-runInLinuxVM-examples}
+
+Build the derivation hello inside a VM:
+```nix
+{ pkgs }: with pkgs; with vmTools;
+runInLinuxVM hello
+```
+
+Build inside a VM with extra memory:
+```nix
+{ pkgs }: with pkgs; with vmTools;
+runInLinuxVM (hello.overrideAttrs (_: { memSize = 1024; }))
+```
+
+Use VM with a disk image (implicitly sets `diskImage`, see [`vmTools.createEmptyImage`](#vm-tools-createEmptyImage)):
+```nix
+{ pkgs }: with pkgs; with vmTools;
+runInLinuxVM (hello.overrideAttrs (_: {
+  preVM = createEmptyImage {
+    size = 1024;
+    fullName = "vm-image";
+  };
+}))
+```
+
+## `vmTools.extractFs` {#vm-tools-extractFs}
+
+Takes a file, such as an ISO, and extracts its contents into the store.
+
+### Attributes {#vm-tools-extractFs-attributes}
+
+* `file`. Path to the file to be extracted.
+  Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
+* `fs` (optional). Filesystem of the contents of the file.
+
+### Examples {#vm-tools-extractFs-examples}
+
+Extract the contents of an ISO file:
+```nix
+{ pkgs }: with pkgs; with vmTools;
+extractFs { file = ./image.iso; }
+```
+
+## `vmTools.extractMTDfs` {#vm-tools-extractMTDfs}
+
+Like [](#vm-tools-extractFs), but it makes use of a [Memory Technology Device (MTD)](https://en.wikipedia.org/wiki/Memory_Technology_Device).
+
+## `vmTools.runInLinuxImage` {#vm-tools-runInLinuxImage}
+
+Like [](#vm-tools-runInLinuxVM), but instead of using `stdenv` from the Nix store, run the build using the tools provided by `/bin`, `/usr/bin`, etc. from the specified filesystem image, which typically is a filesystem containing a [FHS](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard)-based Linux distribution.
+
+## `vmTools.makeImageTestScript` {#vm-tools-makeImageTestScript}
+
+Generate a script that can be used to run an interactive session in the given image.
+
+### Examples {#vm-tools-makeImageTestScript-examples}
+
+Create a script for running a Fedora 27 VM:
+```nix
+{ pkgs }: with pkgs; with vmTools;
+makeImageTestScript diskImages.fedora27x86_64
+```
+
+Create a script for running an Ubuntu 20.04 VM:
+```nix
+{ pkgs }: with pkgs; with vmTools;
+makeImageTestScript diskImages.ubuntu2004x86_64
+```
+
+## `vmTools.diskImageFuns` {#vm-tools-diskImageFuns}
+
+A set of functions that build a predefined set of minimal Linux distributions images.
+
+### Images {#vm-tools-diskImageFuns-images}
+
+* Fedora
+  * `fedora26x86_64`
+  * `fedora27x86_64`
+* CentOS
+  * `centos6i386`
+  * `centos6x86_64`
+  * `centos7x86_64`
+* Ubuntu
+  * `ubuntu1404i386`
+  * `ubuntu1404x86_64`
+  * `ubuntu1604i386`
+  * `ubuntu1604x86_64`
+  * `ubuntu1804i386`
+  * `ubuntu1804x86_64`
+  * `ubuntu2004i386`
+  * `ubuntu2004x86_64`
+  * `ubuntu2204i386`
+  * `ubuntu2204x86_64`
+* Debian
+  * `debian10i386`
+  * `debian10x86_64`
+  * `debian11i386`
+  * `debian11x86_64`
+
+### Attributes {#vm-tools-diskImageFuns-attributes}
+
+* `size` (optional, defaults to `4096`). The size of the image, in MiB.
+* `extraPackages` (optional). A list names of additional packages from the distribution that should be included in the image.
+
+### Examples {#vm-tools-diskImageFuns-examples}
+
+8GiB image containing Firefox in addition to the default packages:
+```nix
+{ pkgs }: with pkgs; with vmTools;
+diskImageFuns.ubuntu2004x86_64 { extraPackages = [ "firefox" ]; size = 8192; }
+```
+
+## `vmTools.diskImageExtraFuns` {#vm-tools-diskImageExtraFuns}
+
+Shorthand for `vmTools.diskImageFuns.<attr> { extraPackages = ... }`.
+
+## `vmTools.diskImages` {#vm-tools-diskImages}
+
+Shorthand for `vmTools.diskImageFuns.<attr> { }`.
@@ -1,5 +1,32 @@
 # Testers {#chap-testers}
-This chapter describes several testing builders which are available in the <literal>testers</literal> namespace.
+This chapter describes several testing builders which are available in the `testers` namespace.
+
+## `hasPkgConfigModules` {#tester-hasPkgConfigModules}
+
+<!-- Old anchor name so links still work -->
+[]{#tester-hasPkgConfigModule}
+Checks whether a package exposes a given list of `pkg-config` modules.
+If the `moduleNames` argument is omitted, `hasPkgConfigModules` will
+use `meta.pkgConfigModules`.
+
+Example:
+
+```nix
+passthru.tests.pkg-config = testers.hasPkgConfigModules {
+  package = finalAttrs.finalPackage;
+  moduleNames = [ "libfoo" ];
+};
+```
+
+If the package in question has `meta.pkgConfigModules` set, it is even simpler:
+
+```nix
+passthru.tests.pkg-config = testers.hasPkgConfigModules {
+  package = finalAttrs.finalPackage;
+};
+
+meta.pkgConfigModules = [ "libfoo" ];
+```

 ## `testVersion` {#tester-testVersion}

@@ -35,6 +62,70 @@ passthru.tests.version = testers.testVersion {
 };
 ```

+## `testBuildFailure` {#tester-testBuildFailure}
+
+Make sure that a build does not succeed. This is useful for testing testers.
+
+This returns a derivation with an override on the builder, with the following effects:
+
+ - Fail the build when the original builder succeeds
+ - Move `$out` to `$out/result`, if it exists (assuming `out` is the default output)
+ - Save the build log to `$out/testBuildFailure.log` (same)
+
+Example:
+
+```nix
+runCommand "example" {
+  failed = testers.testBuildFailure (runCommand "fail" {} ''
+    echo ok-ish >$out
+    echo failing though
+    exit 3
+  '');
+} ''
+  grep -F 'ok-ish' $failed/result
+  grep -F 'failing though' $failed/testBuildFailure.log
+  [[ 3 = $(cat $failed/testBuildFailure.exit) ]]
+  touch $out
+'';
+```
+
+While `testBuildFailure` is designed to keep changes to the original builder's
+environment to a minimum, some small changes are inevitable.
+
+ - The file `$TMPDIR/testBuildFailure.log` is present. It should not be deleted.
+ - `stdout` and `stderr` are a pipe instead of a tty. This could be improved.
+ - One or two extra processes are present in the sandbox during the original
+   builder's execution.
+ - The derivation and output hashes are different, but not unusual.
+ - The derivation includes a dependency on `buildPackages.bash` and
+   `expect-failure.sh`, which is built to include a transitive dependency on
+   `buildPackages.coreutils` and possibly more. These are not added to `PATH`
+   or any other environment variable, so they should be hard to observe.
+
+## `testEqualContents` {#tester-equalContents}
+
+Check that two paths have the same contents.
+
+Example:
+
+```nix
+testers.testEqualContents {
+  assertion = "sed -e performs replacement";
+  expected = writeText "expected" ''
+    foo baz baz
+  '';
+  actual = runCommand "actual" {
+    # not really necessary for a package that's in stdenv
+    nativeBuildInputs = [ gnused ];
+    base = writeText "base" ''
+      foo bar baz
+    '';
+  } ''
+    sed -e 's/bar/baz/g' $base >$out
+  '';
+}
+```
+
 ## `testEqualDerivation` {#tester-testEqualDerivation}

 Checks that two packages produce the exact same build instructions.
@@ -83,10 +174,30 @@ tests.fetchgit = testers.invalidateFetcherByDrvHash fetchgit {
  name = "nix-source";
  url = "https://github.com/NixOS/nix";
  rev = "9d9dbe6ed05854e03811c361a3380e09183f4f4a";
-  sha256 = "sha256-7DszvbCNTjpzGRmpIVAWXk20P0/XTrWZ79KSOGLrUWY=";
+  hash = "sha256-7DszvbCNTjpzGRmpIVAWXk20P0/XTrWZ79KSOGLrUWY=";
 };
 ```

+## `runNixOSTest` {#tester-runNixOSTest}
+
+A helper function that behaves exactly like the NixOS `runTest`, except it also assigns this Nixpkgs package set as the `pkgs` of the test and makes the `nixpkgs.*` options read-only.
+
+If your test is part of the Nixpkgs repository, or if you need a more general entrypoint, see ["Calling a test" in the NixOS manual](https://nixos.org/manual/nixos/stable/index.html#sec-calling-nixos-tests).
+
+Example:
+
+```nix
+pkgs.testers.runNixOSTest ({ lib, ... }: {
+  name = "hello";
+  nodes.machine = { pkgs, ... }: {
+    environment.systemPackages = [ pkgs.hello ];
+  };
+  testScript = ''
+    machine.succeed("hello")
+  '';
+})
+```
+
 ## `nixosTest` {#tester-nixosTest}

 Run a NixOS VM network test using this evaluation of Nixpkgs.
@@ -101,7 +212,7 @@ letting NixOS invoke Nixpkgs anew.
 If a test machine needs to set NixOS options under `nixpkgs`, it must set only the
 `nixpkgs.pkgs` option.

-### Parameter
+### Parameter {#tester-nixosTest-parameter}

 A [NixOS VM test network](https://nixos.org/nixos/manual/index.html#sec-nixos-tests), or path to it. Example:

@@ -123,7 +234,7 @@ A [NixOS VM test network](https://nixos.org/nixos/manual/index.html#sec-nixos-te
 }
 ```

-### Result
+### Result {#tester-nixosTest-result}

 A derivation that runs the VM test.

@@ -0,0 +1,4 @@
+{
+  outputPath = "share/doc/nixpkgs";
+  indexPath = "manual.html";
+}
@@ -0,0 +1,10 @@
+# Contributing to Nixpkgs {#part-contributing}
+
+```{=include=} chapters
+contributing/quick-start.chapter.md
+contributing/coding-conventions.chapter.md
+contributing/submitting-changes.chapter.md
+contributing/vulnerability-roundup.chapter.md
+contributing/reviewing-contributions.chapter.md
+contributing/contributing-to-documentation.chapter.md
+```
@@ -204,13 +204,13 @@ The key words _must_, _must not_, _required_, _shall_, _shall not_, _should_, _s

 In Nixpkgs, there are generally three different names associated with a package:

- The `name` attribute of the derivation (excluding the version part). This is what most users see, in particular when using `nix-env`.
+- The `pname` attribute of the derivation. This is what most users see, in particular when using `nix-env`.

 - The variable name used for the instantiated package in `all-packages.nix`, and when passing it as a dependency to other functions. Typically this is called the _package attribute name_. This is what Nix expression authors see. It can also be used when installing using `nix-env -iA`.

 - The filename for (the directory containing) the Nix expression.

-Most of the time, these are the same. For instance, the package `e2fsprogs` has a `name` attribute `"e2fsprogs-version"`, is bound to the variable name `e2fsprogs` in `all-packages.nix`, and the Nix expression is in `pkgs/os-specific/linux/e2fsprogs/default.nix`.
+Most of the time, these are the same. For instance, the package `e2fsprogs` has a `pname` attribute `"e2fsprogs"`, is bound to the variable name `e2fsprogs` in `all-packages.nix`, and the Nix expression is in `pkgs/os-specific/linux/e2fsprogs/default.nix`.

 There are a few naming guidelines:

@@ -220,7 +220,9 @@ There are a few naming guidelines:

 - The `version` attribute _must_ start with a digit e.g`"0.3.1rc2".

- If a package is not a release but a commit from a repository, then the `version` attribute _must_ be the date of that (fetched) commit. The date _must_ be in `"unstable-YYYY-MM-DD"` format.
+- If a package is a commit from a repository without a version assigned, then the `version` attribute _should_ be the latest upstream version preceding that commit, followed by `-unstable-` and the date of the (fetched) commit. The date _must_ be in `"YYYY-MM-DD"` format.
+
+Example: Given a project had its latest releases `2.2` in November 2021, and `3.0` in January 2022, a commit authored on March 15, 2022 for an upcoming bugfix release `2.2.1` would have `version = "2.2-unstable-2022-03-15"`.

 - Dashes in the package `pname` _should_ be preserved in new variable names, rather than converted to underscores or camel cased — e.g., `http-parser` instead of `http_parser` or `httpParser`. The hyphenated style is preferred in all three package names.

@@ -260,6 +262,10 @@ When in doubt, consider refactoring the `pkgs/` tree, e.g. creating new categori

    - `development/tools/build-managers` (e.g. `gnumake`)

+  - **If it’s a _language server_:**
+
+    - `development/tools/language-servers` (e.g. `ccls` or `rnix-lsp`)
+
  - **Else:**

    - `development/tools/misc` (e.g. `binutils`)
@@ -426,9 +432,10 @@ In the file `pkgs/top-level/all-packages.nix` you can find fetch helpers, these

  ```nix
  src = fetchgit {
+    url = "git@github.com:NixOS/nix.git"
    url = "git://github.com/NixOS/nix.git";
    rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
-    sha256 = "1cw5fszffl5pkpa6s6wjnkiv6lm5k618s32sp60kvmvpy7a2v9kg";
+    hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
  }
  ```

@@ -438,7 +445,7 @@ In the file `pkgs/top-level/all-packages.nix` you can find fetch helpers, these
  src = fetchgit {
    url = "https://github.com/NixOS/nix.git";
    rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
-    sha256 = "1cw5fszffl5pkpa6s6wjnkiv6lm5k618s32sp60kvmvpy7a2v9kg";
+    hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
  }
  ```

@@ -449,14 +456,14 @@ In the file `pkgs/top-level/all-packages.nix` you can find fetch helpers, these
    owner = "NixOS";
    repo = "nix";
    rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
-    sha256 = "1i2yxndxb6yc9l6c99pypbd92lfq5aac4klq7y2v93c9qvx2cgpc";
+    hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
  }
  ```

 When fetching from GitHub, commits must always be referenced by their full commit hash. This is because GitHub shares commit hashes among all forks and returns `404 Not Found` when a short commit hash is ambiguous. It already happens for some short, 6-character commit hashes in `nixpkgs`.
 It is a practical vector for a denial-of-service attack by pushing large amounts of auto generated commits into forks and was already [demonstrated against GitHub Actions Beta](https://blog.teddykatz.com/2019/11/12/github-actions-dos.html).

-Find the value to put as `sha256` by running `nix-shell -p nix-prefetch-github --run "nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix"`. 
+Find the value to put as `hash` by running `nix-shell -p nix-prefetch-github --run "nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix"`.

 ## Obtaining source hash {#sec-source-hashes}

@@ -480,15 +487,23 @@ Preferred source hash type is sha256. There are several ways to get it.

 4. Extracting hash from local source tarball can be done with `sha256sum`. Use `nix-prefetch-url file:///path/to/tarball` if you want base32 hash.

-5. Fake hash: set fake hash in package expression, perform build and extract correct hash from error Nix prints.
+5. Fake hash: set the hash to one of

-    For package updates it is enough to change one symbol to make hash fake. For new packages, you can use `lib.fakeSha256`, `lib.fakeSha512` or any other fake hash.
+   - `""`
+   - `lib.fakeHash`
+   - `lib.fakeSha256`
+   - `lib.fakeSha512`
+
+   in the package expression, attempt build and extract correct hash from error messages.
+
+   ::: {.warning}
+   You must use one of these four fake hashes and not some arbitrarily-chosen hash.
+
+   See [](#sec-source-hashes-security).
+   :::

    This is last resort method when reconstructing source URL is non-trivial and `nix-prefetch-url -A` isn’t applicable (for example, [one of `kodi` dependencies](https://github.com/NixOS/nixpkgs/blob/d2ab091dd308b99e4912b805a5eb088dd536adb9/pkgs/applications/video/kodi/default.nix#L73)). The easiest way then would be replace hash with a fake one and rebuild. Nix build will fail and error message will contain desired hash.

-::: {.warning}
-This method has security problems. Check below for details.
-:::

 ### Obtaining hashes securely {#sec-source-hashes-security}

@@ -500,7 +515,7 @@ Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead of f

 - `https://` URLs are secure in methods 1, 2, 3;

- `https://` URLs are not secure in method 5. When obtaining hashes with fake hash method, TLS checks are disabled. So refetch source hash from several different networks to exclude MITM scenario. Alternatively, use fake hash method to make Nix error, but instead of extracting hash from error, extract `https://` URL and prefetch it with method 1.
+- `https://` URLs are secure in method 5 *only if* you use one of the listed fake hashes. If you use any other hash, `fetchurl` will pass `--insecure` to `curl` and may then degrade to HTTP in case of TLS certificate expiration.

 ## Patches {#sec-patches}

@@ -511,7 +526,7 @@ patches = [
  (fetchpatch {
    name = "fix-check-for-using-shared-freetype-lib.patch";
    url = "http://git.ghostscript.com/?p=ghostpdl.git;a=patch;h=8f5d285";
-    sha256 = "1f0k043rng7f0rfl9hhb89qzvvksqmkrikmm38p61yfx51l325xr";
+    hash = "sha256-uRcxaCjd+WAuGrXOmGfFeu79cUILwkRdBu48mwcBE7g=";
  })
 ];
 ```
@@ -661,3 +676,18 @@ stdenv.mkDerivation {
  ...
 }
 ```
+
+### Import From Derivation {#ssec-import-from-derivation}
+
+Import From Derivation (IFD) is disallowed in Nixpkgs for performance reasons:
+[Hydra] evaluates the entire package set, and sequential builds during evaluation would increase evaluation times to become impractical.
+
+[Hydra]: https://github.com/NixOS/hydra
+
+Import From Derivation can be worked around in some cases by committing generated intermediate files to version control and reading those instead.
+
+<!-- TODO: remove the following and link to Nix manual once https://github.com/NixOS/nix/pull/7332 is merged -->
+
+See also [NixOS Wiki: Import From Derivation].
+
+[NixOS Wiki: Import From Derivation]: https://nixos.wiki/wiki/Import_From_Derivation
@@ -1,33 +1,32 @@
-# Contributing to this documentation {#chap-contributing}
+# Contributing to Nixpkgs documentation {#chap-contributing}

-The sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository. The manual is still partially written in DocBook but it is progressively being converted to [Markdown](#sec-contributing-markup).
+The sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository.

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

 ```ShellSession
-$ cd /path/to/nixpkgs/doc
-$ nix-shell
-[nix-shell]$ make
-```
-
-If you experience problems, run `make debug` to help understand the docbook errors.
-
-After making modifications to the manual, it's important to build it before committing. You can do that as follows:
-
-```ShellSession
-$ cd /path/to/nixpkgs/doc
-$ nix-shell
-[nix-shell]$ make clean
-[nix-shell]$ nix-build .
+$ cd /path/to/nixpkgs
+$ nix-build doc
 ```

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

+## devmode {#sec-contributing-devmode}
+
+The shell in the manual source directory makes available a command, `devmode`.
+It is a daemon, that:
+1. watches the manual's source for changes and when they occur — rebuilds
+2. HTTP serves the manual, injecting a script that triggers reload on changes
+3. opens the manual in the default browser
+
 ## Syntax {#sec-contributing-markup}

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

-Additional syntax extensions are available, though not all extensions can be used in NixOS option documentation. The following extensions are currently used:
+Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:
+
+- []{#ssec-contributing-markup-tables}
+  Tables, using the [GitHub-flavored Markdown syntax](https://github.github.com/gfm/#tables-extension-).

 - []{#ssec-contributing-markup-anchors}
  Explicitly defined **anchors** on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md).
@@ -38,6 +37,10 @@ Additional syntax extensions are available, though not all extensions can be use
  ## Syntax {#sec-contributing-markup}
  ```

+  ::: {.note}
+  NixOS option documentation does not support headings in general.
+  :::
+
 - []{#ssec-contributing-markup-anchors-inline}
  **Inline anchors**, which allow linking arbitrary place in the text (e.g. individual list items, sentences…).

@@ -53,7 +56,7 @@ Additional syntax extensions are available, though not all extensions can be use
  This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).

 - []{#ssec-contributing-markup-inline-roles}
-  If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in {file}`doc/build-aux/pandoc-filters/link-unix-man-references.lua`.
+  If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in {file}`doc/manpage-urls.json`.

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

@@ -67,10 +70,6 @@ Additional syntax extensions are available, though not all extensions can be use

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

-  ::: {.note}
-  Inline roles are available for option documentation.
-  :::
-
 - []{#ssec-contributing-markup-admonitions}
  **Admonitions**, set off from the text to bring attention to something.

@@ -96,10 +95,6 @@ Additional syntax extensions are available, though not all extensions can be use
    - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)
    - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)

-  ::: {.note}
-  Admonitions are available for option documentation.
-  :::
-
 - []{#ssec-contributing-markup-definition-lists}
  [**Definition lists**](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md), for defining a group of terms:

@@ -118,5 +113,3 @@ Additional syntax extensions are available, though not all extensions can be use
  >
  > watermelon
  > :   green fruit with red flesh
-
-For contributing to the legacy parts, please see [DocBook: The Definitive Guide](https://tdg.docbook.org/) or the [DocBook rocks! primer](https://web.archive.org/web/20200816233747/https://docbook.rocks/).
@@ -34,7 +34,7 @@ To add a package to Nixpkgs:

   - Apache HTTPD: [`pkgs/servers/http/apache-httpd/2.4.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/http/apache-httpd/2.4.nix). A bunch of optional features, variable substitutions in the configure flags, a post-install hook, and miscellaneous hackery.

-   - Thunderbird: [`pkgs/applications/networking/mailreaders/thunderbird/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/mailreaders/thunderbird/default.nix). Lots of dependencies.
+   - buildMozillaMach: [`pkgs/applications/networking/browser/firefox/common.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/browsers/firefox/common.nix). A reusable build function for Firefox, Thunderbird and Librewolf.

   - JDiskReport, a Java utility: [`pkgs/tools/misc/jdiskreport/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/default.nix). Nixpkgs doesn’t have a decent `stdenv` for Java yet so this is pretty ad-hoc.

@@ -12,7 +12,7 @@ When reviewing a pull request, please always be nice and polite. Controversial c

 GitHub provides reactions as a simple and quick way to provide feedback to pull requests or any comments. The thumb-down reaction should be used with care and if possible accompanied with some explanation so the submitter has directions to improve their contribution.

-pull request reviews should include a list of what has been reviewed in a comment, so other reviewers and mergers can know the state of the review.
+Pull request reviews should include a list of what has been reviewed in a comment, so other reviewers and mergers can know the state of the review.

 All the review template samples provided in this section are generic and meant as examples. Their usage is optional and the reviewer is free to adapt them to their liking.

@@ -62,6 +62,8 @@ Sample template for a package update review is provided below.
 - [ ] package build on ARCHITECTURE
 - [ ] executables tested on ARCHITECTURE
 - [ ] all depending packages build
+- [ ] patches have a comment describing either the upstream URL or a reason why the patch wasn't upstreamed
+- [ ] patches that are remotely available are fetched rather than vendored

 ##### Possible improvements

@@ -105,7 +107,8 @@ Sample template for a new package review is provided below.
 - [ ] source is fetched using the appropriate function
 - [ ] the list of `phases` is not overridden
 - [ ] when a phase (like `installPhase`) is overridden it starts with `runHook preInstall` and ends with `runHook postInstall`.
- [ ] patches that are remotely available are fetched with `fetchpatch`
+- [ ] patches have a comment describing either the upstream URL or a reason why the patch wasn't upstreamed
+- [ ] patches that are remotely available are fetched rather than vendored

 ##### Possible improvements

@@ -185,7 +188,7 @@ Sample template for a new module review is provided below.
 ##### Comments
 ```

-## Individual maintainer list {#reviewing-contributions-indvidual-maintainer-list}
+## Individual maintainer list {#reviewing-contributions-individual-maintainer-list}

 When adding users to `maintainers/maintainer-list.nix`, the following
 checks should be performed:
@@ -201,7 +204,7 @@ checks should be performed:
    them to either recommit using that key or to remove their key
    information.

-    Given a maintainter entry like this:
+    Given a maintainer entry like this:

    ``` nix
    {
@@ -302,6 +305,12 @@ Container system, boot system and library changes are some examples of the pull

 It is possible for community members that have enough knowledge and experience on a special topic to contribute by merging pull requests.

+In case the PR is stuck waiting for the original author to apply a trivial
+change (a typo, capitalisation change, etc.) and the author allowed the members
+to modify the PR, consider applying it yourself. (or commit the existing review
+suggestion) You should pay extra attention to make sure the addition doesn't go
+against the idea of the original PR and would not be opposed by the author.
+
 <!--
 The following paragraphs about how to deal with unactive contributors is just a proposition and should be modified to what the community agrees to be the right policy.

@@ -0,0 +1,16 @@
+digraph {
+    "small changes" [shape=none]
+    "mass-rebuilds and other large changes" [shape=none]
+    "critical security fixes" [shape=none]
+    "broken staging-next fixes" [shape=none]
+
+    "small changes" -> master
+    "mass-rebuilds and other large changes" -> staging
+    "critical security fixes" -> master
+    "broken staging-next fixes" -> "staging-next"
+
+    "staging-next" -> master [color="#E85EB0"] [label="stabilization ends"] [fontcolor="#E85EB0"]
+    "staging" -> "staging-next" [color="#E85EB0"] [label="stabilization starts"] [fontcolor="#E85EB0"]
+
+    master -> "staging-next" -> staging [color="#5F5EE8"] [label="every six hours (GitHub Action)"] [fontcolor="#5F5EE8"]
+}
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 7.1.0 (0)
+ -->
+<!-- Pages: 1 -->
+<svg width="743pt" height="291pt"
+ viewBox="0.00 0.00 743.00 291.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 287)">
+<polygon fill="white" stroke="none" points="-4,4 -4,-287 739,-287 739,4 -4,4"/>
+<!-- small changes -->
+<g id="node1" class="node">
+<title>small changes</title>
+<text text-anchor="middle" x="59" y="-261.3" font-family="Times,serif" font-size="14.00">small changes</text>
+</g>
+<!-- master -->
+<g id="node5" class="node">
+<title>master</title>
+<ellipse fill="none" stroke="black" cx="139" cy="-192" rx="43.59" ry="18"/>
+<text text-anchor="middle" x="139" y="-188.3" font-family="Times,serif" font-size="14.00">master</text>
+</g>
+<!-- small changes&#45;&gt;master -->
+<g id="edge1" class="edge">
+<title>small changes&#45;&gt;master</title>
+<path fill="none" stroke="black" d="M77.96,-247.17C88.42,-237.89 101.55,-226.23 112.96,-216.11"/>
+<polygon fill="black" stroke="black" points="114.99,-218.99 120.14,-209.74 110.34,-213.76 114.99,-218.99"/>
+</g>
+<!-- mass&#45;rebuilds and other large changes -->
+<g id="node2" class="node">
+<title>mass&#45;rebuilds and other large changes</title>
+<text text-anchor="middle" x="588" y="-101.3" font-family="Times,serif" font-size="14.00">mass&#45;rebuilds and other large changes</text>
+</g>
+<!-- staging -->
+<g id="node6" class="node">
+<title>staging</title>
+<ellipse fill="none" stroke="black" cx="438" cy="-18" rx="45.49" ry="18"/>
+<text text-anchor="middle" x="438" y="-14.3" font-family="Times,serif" font-size="14.00">staging</text>
+</g>
+<!-- mass&#45;rebuilds and other large changes&#45;&gt;staging -->
+<g id="edge2" class="edge">
+<title>mass&#45;rebuilds and other large changes&#45;&gt;staging</title>
+<path fill="none" stroke="black" d="M587.48,-87.47C586.26,-76.55 582.89,-62.7 574,-54 553.19,-33.63 522.2,-24.65 495.05,-20.86"/>
+<polygon fill="black" stroke="black" points="495.53,-17.39 485.2,-19.71 494.72,-24.35 495.53,-17.39"/>
+</g>
+<!-- critical security fixes -->
+<g id="node3" class="node">
+<title>critical security fixes</title>
+<text text-anchor="middle" x="219" y="-261.3" font-family="Times,serif" font-size="14.00">critical security fixes</text>
+</g>
+<!-- critical security fixes&#45;&gt;master -->
+<g id="edge3" class="edge">
+<title>critical security fixes&#45;&gt;master</title>
+<path fill="none" stroke="black" d="M200.04,-247.17C189.58,-237.89 176.45,-226.23 165.04,-216.11"/>
+<polygon fill="black" stroke="black" points="167.66,-213.76 157.86,-209.74 163.01,-218.99 167.66,-213.76"/>
+</g>
+<!-- broken staging&#45;next fixes -->
+<g id="node4" class="node">
+<title>broken staging&#45;next fixes</title>
+<text text-anchor="middle" x="414" y="-188.3" font-family="Times,serif" font-size="14.00">broken staging&#45;next fixes</text>
+</g>
+<!-- staging&#45;next -->
+<g id="node7" class="node">
+<title>staging&#45;next</title>
+<ellipse fill="none" stroke="black" cx="272" cy="-105" rx="68.79" ry="18"/>
+<text text-anchor="middle" x="272" y="-101.3" font-family="Times,serif" font-size="14.00">staging&#45;next</text>
+</g>
+<!-- broken staging&#45;next fixes&#45;&gt;staging&#45;next -->
+<g id="edge4" class="edge">
+<title>broken staging&#45;next fixes&#45;&gt;staging&#45;next</title>
+<path fill="none" stroke="black" d="M410.2,-174.42C406.88,-163.48 400.98,-149.62 391,-141 377.77,-129.56 360.96,-121.86 344.17,-116.67"/>
+<polygon fill="black" stroke="black" points="345.21,-113.33 334.63,-114.02 343.33,-120.07 345.21,-113.33"/>
+</g>
+<!-- master&#45;&gt;staging&#45;next -->
+<g id="edge7" class="edge">
+<title>master&#45;&gt;staging&#45;next</title>
+<path fill="none" stroke="#5f5ee8" d="M96.55,-187.26C53.21,-181.83 -4.5,-169.14 20,-141 41.99,-115.74 126.36,-108.13 191.48,-106.11"/>
+<polygon fill="#5f5ee8" stroke="#5f5ee8" points="191.57,-109.61 201.47,-105.85 191.38,-102.62 191.57,-109.61"/>
+<text text-anchor="middle" x="133" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#5f5ee8">every six hours (GitHub Action)</text>
+</g>
+<!-- staging&#45;&gt;staging&#45;next -->
+<g id="edge6" class="edge">
+<title>staging&#45;&gt;staging&#45;next</title>
+<path fill="none" stroke="#e85eb0" d="M434.55,-36.2C431.48,-47.12 425.89,-60.72 416,-69 397.61,-84.41 373.51,-93.23 350.31,-98.23"/>
+<polygon fill="#e85eb0" stroke="#e85eb0" points="349.67,-94.79 340.5,-100.1 350.98,-101.66 349.67,-94.79"/>
+<text text-anchor="middle" x="493.5" y="-57.8" font-family="Times,serif" font-size="14.00" fill="#e85eb0">stabilization starts</text>
+</g>
+<!-- staging&#45;next&#45;&gt;master -->
+<g id="edge5" class="edge">
+<title>staging&#45;next&#45;&gt;master</title>
+<path fill="none" stroke="#e85eb0" d="M268.22,-123.46C265.05,-134.22 259.46,-147.52 250,-156 233.94,-170.4 211.98,-178.87 191.83,-183.86"/>
+<polygon fill="#e85eb0" stroke="#e85eb0" points="191.35,-180.38 182.34,-185.96 192.86,-187.22 191.35,-180.38"/>
+<text text-anchor="middle" x="323.5" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#e85eb0">stabilization ends</text>
+</g>
+<!-- staging&#45;next&#45;&gt;staging -->
+<g id="edge8" class="edge">
+<title>staging&#45;next&#45;&gt;staging</title>
+<path fill="none" stroke="#5f5ee8" d="M221.07,-92.46C194.72,-84.14 170.92,-71.32 186,-54 210.78,-25.54 314.74,-19.48 381.15,-18.6"/>
+<polygon fill="#5f5ee8" stroke="#5f5ee8" points="380.79,-22.1 390.76,-18.51 380.73,-15.1 380.79,-22.1"/>
+<text text-anchor="middle" x="299" y="-57.8" font-family="Times,serif" font-size="14.00" fill="#5f5ee8">every six hours (GitHub Action)</text>
+</g>
+</g>
+</svg>
@@ -76,7 +76,7 @@ Security fixes are submitted in the same way as other changes and thus the same
  (fetchpatch {
    name = "CVE-2019-11068.patch";
    url = "https://gitlab.gnome.org/GNOME/libxslt/commit/e03553605b45c88f0b4b2980adfbbb8f6fca2fd6.patch";
-    sha256 = "0pkpb4837km15zgg6h57bncp66d5lwrlvkr73h0lanywq7zrwhj8";
+    hash = "sha256-SEKe/8HcW0UBHCfPTTOnpRlzmV2nQPPeL6HOMxBZd14=";
  })
  ```

@@ -199,7 +199,7 @@ It’s important to test any executables generated by a build when you change or

 ### Meets Nixpkgs contribution standards {#submitting-changes-contribution-standards}

-The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md). The contributing document has detailed information on standards the Nix community has for commit messages, reviews, licensing of contributions you make to the project, etc\... Everyone should read and understand the standards the community has for contributing before submitting a pull request.
+The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md). The contributing document has detailed information on standards the Nix community has for commit messages, reviews, licensing of contributions you make to the project, etc... Everyone should read and understand the standards the community has for contributing before submitting a pull request.

 ## Hotfixing pull requests {#submitting-changes-hotfixing-pull-requests}

@@ -214,43 +214,89 @@ The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blo
 - Hydra builds for master and staging should not be used as testing platform, it’s a build farm for changes that have been already tested.
 - When changing the bootloader installation process, extra care must be taken. Grub installations cannot be rolled back, hence changes may break people’s installations forever. For any non-trivial change to the bootloader please file a PR asking for review, especially from \@edolstra.

+### Branches {#submitting-changes-branches}
+
+The `nixpkgs` repository has three major branches:
+- `master`
+- `staging`
+- `staging-next`
+
+The most important distinction between them is that `staging`
+(colored red in the diagram below) can receive commits which cause
+a mass-rebuild (for example, anything that changes the `drvPath` of
+`stdenv`).  The other two branches `staging-next` and `master`
+(colored green in the diagram below) can *not* receive commits which
+cause a mass-rebuild.
+
+Arcs between the branches show possible merges into these branches,
+either from other branches or from independently submitted PRs.  The
+colors of these edges likewise show whether or not they could
+trigger a mass rebuild (red) or must not trigger a mass rebuild
+(green).
+
+Hydra runs automatic builds for the green branches.
+
+Notice that the automatic merges are all green arrows.  This is by
+design.  Any merge which might cause a mass rebuild on a branch
+which has automatic builds (`staging-next`, `master`) will be a
+manual merge to make sure it is good use of compute power.
+
+Nixpkgs has two branches so that there is one branch (`staging`)
+which accepts mass-rebuilding commits, and one fast-rebuilding
+branch which accepts independent PRs (`master`).  The `staging-next`
+branch allows the Hydra operators to batch groups of commits to
+`staging` to be built.  By keeping the `staging-next` branch
+separate from `staging`, this batching does not block
+developers from merging changes into `staging`.
+
 ```{.graphviz caption="Staging workflow"}
 digraph {
-    "small changes" [shape=none]
-    "mass-rebuilds and other large changes" [shape=none]
-    "critical security fixes" [shape=none]
-    "broken staging-next fixes" [shape=none]
+    master [color="green" fontcolor=green]
+    "staging-next" [color="green" fontcolor=green]
+    staging [color="red" fontcolor=red]

-    "small changes" -> master
-    "mass-rebuilds and other large changes" -> staging
-    "critical security fixes" -> master
-    "broken staging-next fixes" -> "staging-next"
+    "small changes" [fontcolor=green shape=none]
+    "small changes" -> master [color=green]

-    "staging-next" -> master [color="#E85EB0"] [label="stabilization ends"] [fontcolor="#E85EB0"]
-    "staging" -> "staging-next" [color="#E85EB0"] [label="stabilization starts"] [fontcolor="#E85EB0"]
+    "mass-rebuilds and other large changes" [fontcolor=red shape=none]
+    "mass-rebuilds and other large changes" -> staging [color=red]

-    master -> "staging-next" -> staging [color="#5F5EE8"] [label="every six hours (GitHub Action)"] [fontcolor="#5F5EE8"]
+    "critical security fixes" [fontcolor=green shape=none]
+    "critical security fixes" -> master [color=green]
+
+    "staging fixes which do not cause staging to mass-rebuild" [fontcolor=green shape=none]
+    "staging fixes which do not cause staging to mass-rebuild" -> "staging-next" [color=green]
+
+    "staging-next" -> master [color="red"] [label="manual merge"] [fontcolor="red"]
+    "staging" -> "staging-next" [color="red"] [label="manual merge"] [fontcolor="red"]
+
+    master -> "staging-next" [color="green"] [label="automatic merge (GitHub Action)"] [fontcolor="green"]
+    "staging-next" -> staging [color="green"] [label="automatic merge (GitHub Action)"] [fontcolor="green"]
 }
 ```

-[This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/periodic-merge-6h.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours; these are the blue arrows in the diagram above.  The purple arrows in the diagram above are done manually and much less frequently.  You can get an idea of how often these merges occur by looking at the git history.
+[This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/periodic-merge-6h.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours; these are the green arrows in the diagram above.  The red arrows in the diagram above are done manually and much less frequently.  You can get an idea of how often these merges occur by looking at the git history.


-### Master branch {#submitting-changes-master-branch}
+#### Master branch {#submitting-changes-master-branch}

 The `master` branch is the main development branch. It should only see non-breaking commits that do not cause mass rebuilds.

-### Staging branch {#submitting-changes-staging-branch}
+#### Staging branch {#submitting-changes-staging-branch}

 The `staging` branch is a development branch where mass-rebuilds go. Mass rebuilds are commits that cause rebuilds for many packages, like more than 500 (or perhaps, if it's 'light' packages, 1000). It should only see non-breaking mass-rebuild commits. That means it is not to be used for testing, and changes must have been well tested already. If the branch is already in a broken state, please refrain from adding extra new breakages.

-### Staging-next branch {#submitting-changes-staging-next-branch}
+During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes.
+
+#### Staging-next branch {#submitting-changes-staging-next-branch}

 The `staging-next` branch is for stabilizing mass-rebuilds submitted to the `staging` branch prior to merging them into `master`. Mass-rebuilds must go via the `staging` branch. It must only see non-breaking commits that are fixing issues blocking it from being merged into the `master` branch.

 If the branch is already in a broken state, please refrain from adding extra new breakages. Stabilize it for a few days and then merge into master.

-### Stable release branches {#submitting-changes-stable-release-branches}
+During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes.
+
+#### Stable release branches {#submitting-changes-stable-release-branches}

 The same staging workflow applies to stable release branches, but the main branch is called `release-*` instead of `master`.

@@ -286,7 +332,7 @@ Other examples of reasons are:
 - The previous download links were all broken
 - Crash when starting on some X11 systems

-#### Acceptable backport criteria
+#### Acceptable backport criteria {#acceptable-backport-criteria}

 The stable branch does have some changes which cannot be backported. Most notable are breaking changes. The desire is to have stable users be uninterrupted when updating packages.

@@ -1,39 +1,148 @@
 { pkgs ? (import ./.. { }), nixpkgs ? { }}:
 let
-  lib = pkgs.lib;
-  doc-support = import ./doc-support { inherit pkgs nixpkgs; };
+  inherit (pkgs) lib;
+  inherit (lib) hasPrefix removePrefix;
+
+  common = import ./common.nix;
+
+  lib-docs = import ./doc-support/lib-function-docs.nix {
+    inherit pkgs nixpkgs;
+    libsets = [
+      { name = "asserts"; description = "assertion functions"; }
+      { name = "attrsets"; description = "attribute set functions"; }
+      { name = "strings"; description = "string manipulation functions"; }
+      { name = "versions"; description = "version string functions"; }
+      { name = "trivial"; description = "miscellaneous functions"; }
+      { name = "fixedPoints"; baseName = "fixed-points"; description = "explicit recursion functions"; }
+      { name = "lists"; description = "list manipulation functions"; }
+      { name = "debug"; description = "debugging functions"; }
+      { name = "options"; description = "NixOS / nixpkgs option handling"; }
+      { name = "path"; description = "path functions"; }
+      { name = "filesystem"; description = "filesystem functions"; }
+      { name = "sources"; description = "source filtering functions"; }
+      { name = "cli"; description = "command-line serialization functions"; }
+    ];
+  };
+
+  epub = pkgs.runCommand "manual.epub" {
+    nativeBuildInputs = with pkgs; [ libxslt zip ];
+
+    epub = ''
+      <book xmlns="http://docbook.org/ns/docbook"
+            xmlns:xlink="http://www.w3.org/1999/xlink"
+            version="5.0"
+            xml:id="nixpkgs-manual">
+        <info>
+          <title>Nixpkgs Manual</title>
+          <subtitle>Version ${pkgs.lib.version}</subtitle>
+        </info>
+        <chapter>
+          <title>Temporarily unavailable</title>
+          <para>
+            The Nixpkgs manual is currently not available in EPUB format,
+            please use the <link xlink:href="https://nixos.org/nixpkgs/manual">HTML manual</link>
+            instead.
+          </para>
+          <para>
+            If you've used the EPUB manual in the past and it has been useful to you, please
+            <link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>.
+          </para>
+        </chapter>
+      </book>
+    '';
+
+    passAsFile = [ "epub" ];
+  } ''
+    mkdir scratch
+    xsltproc \
+      --param chapter.autolabel 0 \
+      --nonet \
+      --output scratch/ \
+      ${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \
+      $epubPath
+
+    echo "application/epub+zip" > mimetype
+    zip -0Xq "$out" mimetype
+    cd scratch && zip -Xr9D "$out" *
+  '';
+
+  # NB: This file describes the Nixpkgs manual, which happens to use module
+  #     docs infra originally developed for NixOS.
+  optionsDoc = pkgs.nixosOptionsDoc {
+    inherit (pkgs.lib.evalModules {
+      modules = [ ../pkgs/top-level/config.nix ];
+      class = "nixpkgsConfig";
+    }) options;
+    documentType = "none";
+    transformOptions = opt:
+      opt // {
+        declarations =
+          map
+            (decl:
+              if hasPrefix (toString ../..) (toString decl)
+              then
+                let subpath = removePrefix "/" (removePrefix (toString ../.) (toString decl));
+                in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; }
+              else decl)
+            opt.declarations;
+        };
+  };
 in pkgs.stdenv.mkDerivation {
  name = "nixpkgs-manual";

  nativeBuildInputs = with pkgs; [
-    pandoc
-    graphviz
-    libxml2
-    libxslt
-    zip
-    jing
-    xmlformat
+    nixos-render-docs
  ];

-  src = lib.cleanSource ./.;
+  src = ./.;

  postPatch = ''
-    ln -s ${doc-support} ./doc-support/result
+    ln -s ${optionsDoc.optionsJSON}/share/doc/nixos/options.json ./config-options.json
+  '';
+
+  buildPhase = ''
+    cat \
+      ./functions/library.md.in \
+      ${lib-docs}/index.md \
+      > ./functions/library.md
+    substitute ./manual.md.in ./manual.md \
+      --replace '@MANUAL_VERSION@' '${pkgs.lib.version}'
+
+    mkdir -p out/media
+
+    mkdir -p out/highlightjs
+    cp -t out/highlightjs \
+      ${pkgs.documentation-highlighter}/highlight.pack.js \
+      ${pkgs.documentation-highlighter}/LICENSE \
+      ${pkgs.documentation-highlighter}/mono-blue.css \
+      ${pkgs.documentation-highlighter}/loader.js
+
+    cp -t out ./overrides.css ./style.css
+
+    nixos-render-docs manual html \
+      --manpage-urls ./manpage-urls.json \
+      --revision ${pkgs.lib.trivial.revisionWithDefault (pkgs.rev or "master")} \
+      --stylesheet style.css \
+      --stylesheet overrides.css \
+      --stylesheet highlightjs/mono-blue.css \
+      --script ./highlightjs/highlight.pack.js \
+      --script ./highlightjs/loader.js \
+      --toc-depth 1 \
+      --section-toc-depth 1 \
+      manual.md \
+      out/index.html
  '';

  installPhase = ''
-    dest="$out/share/doc/nixpkgs"
+    dest="$out/${common.outputPath}"
    mkdir -p "$(dirname "$dest")"
-    mv out/html "$dest"
-    mv "$dest/index.html" "$dest/manual.html"
+    mv out "$dest"
+    mv "$dest/index.html" "$dest/${common.indexPath}"

-    mv out/epub/manual.epub "$dest/nixpkgs-manual.epub"
+    cp ${epub} "$dest/nixpkgs-manual.epub"

    mkdir -p $out/nix-support/
-    echo "doc manual $dest manual.html" >> $out/nix-support/hydra-build-products
+    echo "doc manual $dest ${common.indexPath}" >> $out/nix-support/hydra-build-products
    echo "doc manual $dest nixpkgs-manual.epub" >> $out/nix-support/hydra-build-products
  '';
-
-  # Environment variables
-  PANDOC_LUA_FILTERS_DIR = "${pkgs.pandoc-lua-filters}/share/pandoc/filters";
 }
@@ -1,69 +0,0 @@
-{ pkgs ? (import ../.. {}), nixpkgs ? { }}:
-let
-  inherit (pkgs) lib;
-  inherit (lib) hasPrefix removePrefix;
-
-  locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs; };
-  functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs; };
-  version = pkgs.lib.version;
-
-  epub-xsl = pkgs.writeText "epub.xsl" ''
-    <?xml version='1.0'?>
-    <xsl:stylesheet
-      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-      version="1.0">
-      <xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl" />
-      <xsl:import href="${./parameters.xml}"/>
-    </xsl:stylesheet>
-  '';
-
-  xhtml-xsl = pkgs.writeText "xhtml.xsl" ''
-    <?xml version='1.0'?>
-    <xsl:stylesheet
-      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-      version="1.0">
-      <xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/xhtml/docbook.xsl" />
-      <xsl:import href="${./parameters.xml}"/>
-    </xsl:stylesheet>
-  '';
-
-  # NB: This file describes the Nixpkgs manual, which happens to use module
-  #     docs infra originally developed for NixOS.
-  optionsDoc = pkgs.nixosOptionsDoc {
-    inherit (pkgs.lib.evalModules { modules = [ ../../pkgs/top-level/config.nix ]; }) options;
-    documentType = "none";
-    transformOptions = opt:
-      opt // {
-        declarations =
-          map
-            (decl:
-              if hasPrefix (toString ../..) (toString decl)
-              then
-                let subpath = removePrefix "/" (removePrefix (toString ../..) (toString decl));
-                in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; }
-              else decl)
-            opt.declarations;
-        };
-  };
-
-in pkgs.runCommand "doc-support" {}
-''
-  mkdir result
-  (
-    cd result
-    ln -s ${locationsXml} ./function-locations.xml
-    ln -s ${functionDocs} ./function-docs
-    ln -s ${optionsDoc.optionsDocBook} ./config-options.docbook.xml
-
-    ln -s ${pkgs.docbook5}/xml/rng/docbook/docbook.rng ./docbook.rng
-    ln -s ${pkgs.docbook_xsl_ns}/xml/xsl ./xsl
-    ln -s ${epub-xsl} ./epub.xsl
-    ln -s ${xhtml-xsl} ./xhtml.xsl
-
-    ln -s ${../../nixos/doc/xmlformat.conf} ./xmlformat.conf
-    ln -s ${pkgs.documentation-highlighter} ./highlightjs
-
-    echo -n "${version}" > ./version
-  )
-  mv result $out
-''
@@ -1,27 +1,41 @@
-# Generates the documentation for library functons via nixdoc. To add
-# another library function file to this list, the include list in the
-# file `doc/functions/library.xml` must also be updated.
+# Generates the documentation for library functions via nixdoc.

-{ pkgs ? import ./.. {}, locationsXml }:
+{ pkgs, nixpkgs, libsets }:

-with pkgs; stdenv.mkDerivation {
+with pkgs;
+
+let
+  locationsJSON = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; };
+in
+stdenv.mkDerivation {
  name = "nixpkgs-lib-docs";
-  src = ./../../lib;
+  src = ../../lib;

  buildInputs = [ nixdoc ];
  installPhase = ''
    function docgen {
-      nixdoc -c "$1" -d "$2" -f "../lib/$1.nix"  > "$out/$1.xml"
+      name=$1
+      baseName=$2
+      description=$3
+      # TODO: wrap lib.$name in <literal>, make nixdoc not escape it
+      if [[ -e "../lib/$baseName.nix" ]]; then
+        nixdoc -c "$name" -d "lib.$name: $description" -l ${locationsJSON} -f "$baseName.nix" > "$out/$name.md"
+      else
+        nixdoc -c "$name" -d "lib.$name: $description" -l ${locationsJSON} -f "$baseName/default.nix" > "$out/$name.md"
+      fi
+      echo "$out/$name.md" >> "$out/index.md"
    }

-    mkdir -p $out
-    ln -s ${locationsXml} $out/locations.xml
+    mkdir -p "$out"

-    docgen strings 'String manipulation functions'
-    docgen trivial 'Miscellaneous functions'
-    docgen lists 'List manipulation functions'
-    docgen debug 'Debugging functions'
-    docgen options 'NixOS / nixpkgs option handling'
-    docgen sources 'Source filtering functions'
+    cat > "$out/index.md" << 'EOF'
+    ```{=include=} sections
+    EOF
+
+    ${lib.concatMapStrings ({ name, baseName ? name, description }: ''
+      docgen ${name} ${baseName} ${lib.escapeShellArg description}
+    '') libsets}
+
+    echo '```' >> "$out/index.md"
  '';
 }
@@ -1,24 +1,24 @@
-{ pkgs ? (import ./.. { }), nixpkgs ? { }}:
+{ pkgs, nixpkgs ? { }, libsets }:
 let
-  revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.revision or "master");
+  revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.rev or "master");

-  libDefPos = set:
-    builtins.map
-      (name: {
-        name = name;
+  libDefPos = prefix: set:
+    builtins.concatMap
+      (name: [{
+        name = builtins.concatStringsSep "." (prefix ++ [name]);
        location = builtins.unsafeGetAttrPos name set;
-      })
-      (builtins.attrNames set);
+      }] ++ nixpkgsLib.optionals
+        (builtins.length prefix == 0 && builtins.isAttrs set.${name})
+        (libDefPos (prefix ++ [name]) set.${name})
+      ) (builtins.attrNames set);

  libset = toplib:
    builtins.map
      (subsetname: {
        subsetname = subsetname;
-        functions = libDefPos toplib.${subsetname};
+        functions = libDefPos [] toplib.${subsetname};
      })
-      (builtins.filter
-        (name: builtins.isAttrs toplib.${name})
-        (builtins.attrNames toplib));
+      (builtins.map (x: x.name) libsets);

  nixpkgsLib = pkgs.lib;

@@ -58,28 +58,18 @@ let
    [ "-prime" ];

  urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}";
-  xmlstrings = (nixpkgsLib.strings.concatMapStrings
-      ({ name, value }:
-      ''
-      <section><title>${name}</title>
-        <para xml:id="${sanitizeId name}">
-        Located at
-        <link
-          xlink:href="${urlPrefix}/${value.file}#L${builtins.toString value.line}">${value.file}:${builtins.toString value.line}</link>
-        in  <literal>&lt;nixpkgs&gt;</literal>.
-        </para>
-        </section>
-      '')
-      relativeLocs);
+  jsonLocs = builtins.listToAttrs
+    (builtins.map
+      ({ name, value }: {
+        name = sanitizeId name;
+        value =
+          let
+            text = "${value.file}:${builtins.toString value.line}";
+            target = "${urlPrefix}/${value.file}#L${builtins.toString value.line}";
+          in
+            "[${text}](${target}) in `<nixpkgs>`";
+      })
+    relativeLocs);

-in pkgs.writeText
-    "locations.xml"
-    ''
-    <section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         version="5">
-         <title>All the locations for every lib function</title>
-         <para>This file is only for inclusion by other files.</para>
-         ${xmlstrings}
-    </section>
-    ''
+in
+pkgs.writeText "locations.json" (builtins.toJSON jsonLocs)
@@ -1,15 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet
-    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-    version="1.0">
- <xsl:param name="section.autolabel" select="1" />
- <xsl:param name="section.label.includes.component.label" select="1" />
- <xsl:param name="html.stylesheet" select="'style.css overrides.css highlightjs/mono-blue.css'" />
- <xsl:param name="html.script" select="'./highlightjs/highlight.pack.js ./highlightjs/loader.js'" />
- <xsl:param name="xref.with.number.and.title" select="1" />
- <xsl:param name="use.id.as.filename" select="1" />
- <xsl:param name="toc.section.depth" select="0" />
- <xsl:param name="admon.style" select="''" />
- <xsl:param name="callout.graphics.extension" select="'.svg'" />
- <xsl:param name="generate.consistent.ids" select="1" />
-</xsl:stylesheet>
@@ -0,0 +1,11 @@
+# Functions reference {#chap-functions}
+
+The nixpkgs repository has several utility functions to manipulate Nix expressions.
+
+```{=include=} sections
+functions/library.md
+functions/generators.section.md
+functions/debug.section.md
+functions/prefer-remote-fetch.section.md
+functions/nix-gitignore.section.md
+```
@@ -1,14 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="chap-functions">
- <title>Functions reference</title>
- <para>
-  The nixpkgs repository has several utility functions to manipulate Nix expressions.
- </para>
- <xi:include href="functions/library.xml" />
- <xi:include href="functions/generators.section.xml" />
- <xi:include href="functions/debug.section.xml" />
- <xi:include href="functions/prefer-remote-fetch.section.xml" />
- <xi:include href="functions/nix-gitignore.section.xml" />
-</chapter>
@@ -16,7 +16,7 @@ let
             if v == true then ''"yes"''
        else if v == false then ''"no"''
        else if isString v then ''"${v}"''
-        # and delegats all other values to the default generator
+        # and delegates all other values to the default generator
        else generators.mkValueStringDefault {} v;
    } ":";
  };
@@ -0,0 +1,5 @@
+# Nixpkgs Library Functions {#sec-functions-library}
+
+Nixpkgs provides a standard library at `pkgs.lib`, or through `import <nixpkgs/lib>`.
+
+<!-- nixdoc-generated documentation must be appended here during build! -->
@@ -1,30 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="sec-functions-library">
- <title>Nixpkgs Library Functions</title>
-
- <para>
-  Nixpkgs provides a standard library at <varname>pkgs.lib</varname>, or through <code>import &lt;nixpkgs/lib&gt;</code>.
- </para>
-
- <xi:include href="./library/asserts.xml" />
-
- <xi:include href="./library/attrsets.xml" />
-
-<!-- These docs are generated via nixdoc. To add another generated
-      library function file to this list, the file
-      `lib-function-docs.nix` must also be updated. -->
-
- <xi:include href="./library/generated/strings.xml" />
-
- <xi:include href="./library/generated/trivial.xml" />
-
- <xi:include href="./library/generated/lists.xml" />
-
- <xi:include href="./library/generated/debug.xml" />
-
- <xi:include href="./library/generated/options.xml" />
-
- <xi:include href="./library/generated/sources.xml" />
-</section>
@@ -1,112 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="sec-functions-library-asserts">
- <title>Assert functions</title>
-
- <section xml:id="function-library-lib.asserts.assertMsg">
-  <title><function>lib.asserts.assertMsg</function></title>
-
-  <subtitle><literal>assertMsg :: Bool -> String -> Bool</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.asserts.assertMsg" />
-
-  <para>
-   Print a trace message if <literal>pred</literal> is false.
-  </para>
-
-  <para>
-   Intended to be used to augment asserts with helpful error messages.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>pred</varname>
-    </term>
-    <listitem>
-     <para>
-      Condition under which the <varname>msg</varname> should <emphasis>not</emphasis> be printed.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>msg</varname>
-    </term>
-    <listitem>
-     <para>
-      Message to print.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.asserts.assertMsg-example-false">
-   <title>Printing when the predicate is false</title>
-<programlisting><![CDATA[
-assert lib.asserts.assertMsg ("foo" == "bar") "foo is not bar, silly"
-stderr> trace: foo is not bar, silly
-stderr> assert failed
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.asserts.assertOneOf">
-  <title><function>lib.asserts.assertOneOf</function></title>
-
-  <subtitle><literal>assertOneOf :: String -> String ->
-      StringList -> Bool</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.asserts.assertOneOf" />
-
-  <para>
-   Specialized <function>asserts.assertMsg</function> for checking if <varname>val</varname> is one of the elements of <varname>xs</varname>. Useful for checking enums.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>name</varname>
-    </term>
-    <listitem>
-     <para>
-      The name of the variable the user entered <varname>val</varname> into, for inclusion in the error message.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>val</varname>
-    </term>
-    <listitem>
-     <para>
-      The value of what the user provided, to be compared against the values in <varname>xs</varname>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>xs</varname>
-    </term>
-    <listitem>
-     <para>
-      The list of valid values.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.asserts.assertOneOf-example">
-   <title>Ensuring a user provided a possible value</title>
-<programlisting><![CDATA[
-let sslLibrary = "bearssl";
-in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "libressl" ];
-=> false
-stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl"
-        ]]></programlisting>
-  </example>
- </section>
-</section>
@@ -4,7 +4,7 @@

 ## Usage {#sec-pkgs-nix-gitignore-usage}

-`pkgs.nix-gitignore` exports a number of functions, but you\'ll most likely need either `gitignoreSource` or `gitignoreSourcePure`. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string.
+`pkgs.nix-gitignore` exports a number of functions, but you'll most likely need either `gitignoreSource` or `gitignoreSourcePure`. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string.

 ```nix
 { pkgs ? import <nixpkgs> {} }:
@@ -30,7 +30,7 @@ gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
 gitignoreSource = gitignoreFilterSource (_: _: true);
 ```

-Those filter functions accept the same arguments the `builtins.filterSource` function would pass to its filters, thus `fn: gitignoreFilterSourcePure fn ""` should be extensionally equivalent to `filterSource`. The file is blacklisted if it\'s blacklisted by either your filter or the gitignoreFilter.
+Those filter functions accept the same arguments the `builtins.filterSource` function would pass to its filters, thus `fn: gitignoreFilterSourcePure fn ""` should be extensionally equivalent to `filterSource`. The file is blacklisted if it's blacklisted by either your filter or the gitignoreFilter.

 If you want to make your own filter from scratch, you may use

@@ -0,0 +1,3 @@
+# Autoconf {#setup-hook-autoconf}
+
+The `autoreconfHook` derivation adds `autoreconfPhase`, which runs autoreconf, libtoolize and automake, essentially preparing the configure script in autotools-based builds. Most autotools-based packages come with the configure script pre-generated, but this hook is necessary for a few packages and when you need to patch the package’s configure scripts.
@@ -0,0 +1,3 @@
+# Automake {#setup-hook-automake}
+
+Adds the `share/aclocal` subdirectory of each build input to the `ACLOCAL_PATH` environment variable.
@@ -0,0 +1,11 @@
+# autoPatchelfHook {#setup-hook-autopatchelfhook}
+
+This is a special setup hook which helps in packaging proprietary software in that it automatically tries to find missing shared library dependencies of ELF files based on the given `buildInputs` and `nativeBuildInputs`.
+
+You can also specify a `runtimeDependencies` variable which lists dependencies to be unconditionally added to rpath of all executables. This is useful for programs that use dlopen 3 to load libraries at runtime.
+
+In certain situations you may want to run the main command (`autoPatchelf`) of the setup hook on a file or a set of directories instead of unconditionally patching all outputs. This can be done by setting the `dontAutoPatchelf` environment variable to a non-empty value.
+
+By default `autoPatchelf` will fail as soon as any ELF file requires a dependency which cannot be resolved via the given build inputs. In some situations you might prefer to just leave missing dependencies unpatched and continue to patch the rest. This can be achieved by setting the `autoPatchelfIgnoreMissingDeps` environment variable to a non-empty value. `autoPatchelfIgnoreMissingDeps` can be set to a list like `autoPatchelfIgnoreMissingDeps = [ "libcuda.so.1" "libcudart.so.1" ];` or to simply `[ "*" ]` to ignore all missing dependencies.
+
+The `autoPatchelf` command also recognizes a `--no-recurse` command line flag, which prevents it from recursing into subdirectories.
@@ -0,0 +1,15 @@
+# breakpointHook {#breakpointhook}
+
+This hook will make a build pause instead of stopping when a failure happens. It prevents nix from cleaning up the build environment immediately and allows the user to attach to a build environment using the `cntr` command. Upon build error it will print instructions on how to use `cntr`, which can be used to enter the environment for debugging. Installing cntr and running the command will provide shell access to the build sandbox of failed build. At `/var/lib/cntr` the sandboxed filesystem is mounted. All commands and files of the system are still accessible within the shell. To execute commands from the sandbox use the cntr exec subcommand. `cntr` is only supported on Linux-based platforms. To use it first add `cntr` to your `environment.systemPackages` on NixOS or alternatively to the root user on non-NixOS systems. Then in the package that is supposed to be inspected, add `breakpointHook` to `nativeBuildInputs`.
+
+```nix
+nativeBuildInputs = [ breakpointHook ];
+```
+
+When a build failure happens there will be an instruction printed that shows how to attach with `cntr` to the build sandbox.
+
+::: {.note}
+Caution with remote builds
+
+This won’t work with remote builds as the build environment is on a different machine and can’t be accessed by `cntr`. Remote builds can be turned off by setting `--option builders ''` for `nix-build` or `--builders ''` for `nix build`.
+:::
@@ -0,0 +1,3 @@
+# cmake {#cmake}
+
+Overrides the default configure phase to run the CMake command. By default, we use the Make generator of CMake. In addition, dependencies are added automatically to `CMAKE_PREFIX_PATH` so that packages are correctly detected by CMake. Some additional flags are passed in to give similar behavior to configure-based packages. You can disable this hook’s behavior by setting `configurePhase` to a custom value, or by setting `dontUseCmakeConfigure`. `cmakeFlags` controls flags passed only to CMake. By default, parallel building is enabled as CMake supports parallel building almost everywhere. When Ninja is also in use, CMake will detect that and use the ninja generator.
@@ -0,0 +1,3 @@
+# gdk-pixbuf {#setup-hook-gdk-pixbuf}
+
+Exports `GDK_PIXBUF_MODULE_FILE` environment variable to the builder. Add librsvg package to `buildInputs` to get svg support. See also the [setup hook description in GNOME platform docs](#ssec-gnome-hooks-gdk-pixbuf).
--- a/Show More
+++ b/Show More
@@ -1 +1 @@
 .11
 .11