colin
/
nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'master' into license-updates

This commit is contained in:
Jörg Thalheim 2024-03-06 20:26:06 +01:00 committed by GitHub
parent 88c08be88f 557b9754bc
commit 39ac57b7c5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
12471 changed files with 559576 additions and 242694 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
.editorconfig
View File

@ -17,6 +17,10 @@ end_of_line = unset
insert_final_newline = unset
trim_trailing_whitespace = unset
# We want readFile .version to return the version without a newline.
[.version]
insert_final_newline = false
# see https://nixos.org/nixpkgs/manual/#chap-conventions
# Match json/lockfiles/markdown/nix/perl/python/ruby/shell/docbook files, set indent to spaces
@ -108,3 +112,7 @@ charset = unset
[lib/tests/*.plist]
indent_style = tab
insert_final_newline = unset
[pkgs/kde/generated/**]
insert_final_newline = unset
end_of_line = unset

6
.git-blame-ignore-revs
View File

@ -96,3 +96,9 @@ fb0e5be84331188a69b3edd31679ca6576edb75a
# nixos/*: add trivial defaultText for options with simple defaults
25124556397ba17bfd70297000270de1e6523b0a
# systemd: rewrite comments
92dfeb7b3dab820ae307c56c216d175c69ee93cd
# systemd: break too long lines of Nix code
67643f8ec84bef1482204709073e417c9f07eb87

72
.github/CODEOWNERS vendored
View File

@ -20,7 +20,7 @@
# Libraries
/lib @infinisil
/lib/systems @alyssais @ericson2314 @amjoseph-nixpkgs
/lib/systems @alyssais @ericson2314
/lib/generators.nix @infinisil @Profpatsch
/lib/cli.nix @infinisil @Profpatsch
/lib/debug.nix @infinisil @Profpatsch
@ -41,17 +41,18 @@
/pkgs/top-level/stage.nix @Ericson2314
/pkgs/top-level/splice.nix @Ericson2314
/pkgs/top-level/release-cross.nix @Ericson2314
/pkgs/stdenv/generic @Ericson2314 @amjoseph-nixpkgs
/pkgs/stdenv/generic @Ericson2314
/pkgs/stdenv/generic/check-meta.nix @Ericson2314 @piegamesde
/pkgs/stdenv/cross @Ericson2314 @amjoseph-nixpkgs
/pkgs/build-support/cc-wrapper @Ericson2314 @amjoseph-nixpkgs
/pkgs/stdenv/cross @Ericson2314
/pkgs/build-support/cc-wrapper @Ericson2314
/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
## Format generators/serializers
/pkgs/pkgs-lib/formats/libconfig @ckiee
/pkgs/pkgs-lib/formats/libconfig @ckiee @h7x4
/pkgs/pkgs-lib/formats/hocon @h7x4
# pkgs/by-name
/pkgs/test/nixpkgs-check-by-name @infinisil
@ -66,6 +67,10 @@
/doc/build-helpers/images/makediskimage.section.md @raitobezarius
/nixos/lib/make-disk-image.nix @raitobezarius
# Nix, the package manager
pkgs/tools/package-management/nix/ @raitobezarius @ma27
nixos/modules/installer/tools/nix-fallback-paths.nix @raitobezarius @ma27
# Nixpkgs documentation
/maintainers/scripts/db-to-md.sh @jtojnar @ryantm
/maintainers/scripts/doc @jtojnar @ryantm
@ -80,7 +85,6 @@
/nixos/README.md @infinisil
/pkgs/README.md @infinisil
/maintainers/README.md @infinisil
/maintainers/* @piegamesde @Janik-Haag
# User-facing development documentation
/doc/development.md @infinisil
@ -154,7 +158,7 @@
/doc/languages-frameworks/rust.section.md @zowoq @winterqt @figsoda
# C compilers
/pkgs/development/compilers/gcc @amjoseph-nixpkgs
/pkgs/development/compilers/gcc
/pkgs/development/compilers/llvm @RaitoBezarius
/pkgs/development/compilers/emscripten @raitobezarius
/doc/languages-frameworks/emscripten.section.md @raitobezarius
@ -167,6 +171,8 @@
# Browsers
/pkgs/applications/networking/browsers/firefox @mweinelt
/pkgs/applications/networking/browsers/chromium @emilylange
/nixos/tests/chromium.nix @emilylange
# Certificate Authorities
pkgs/data/misc/cacert/ @ajs124 @lukegb @mweinelt
@ -179,11 +185,18 @@ pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt
# Licenses
/lib/licenses.nix @alyssais
# Qt / KDE
/pkgs/applications/kde @ttuegel
/pkgs/desktops/plasma-5 @ttuegel
/pkgs/development/libraries/kde-frameworks @ttuegel
/pkgs/development/libraries/qt-5 @ttuegel
# Qt
/pkgs/development/libraries/qt-5 @NixOS/qt-kde
/pkgs/development/libraries/qt-6 @NixOS/qt-kde
# KDE / Plasma 5
/pkgs/applications/kde @NixOS/qt-kde
/pkgs/desktops/plasma-5 @NixOS/qt-kde
/pkgs/development/libraries/kde-frameworks @NixOS/qt-kde
# KDE / Plasma 6
/pkgs/kde @NixOS/qt-kde
/maintainers/scripts/kde @NixOS/qt-kde
# PostgreSQL and related stuff
/pkgs/servers/sql/postgresql @thoughtpolice @marsam
@ -191,6 +204,10 @@ pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt
/nixos/modules/services/databases/postgresql.nix @thoughtpolice
/nixos/tests/postgresql.nix @thoughtpolice
# Linux kernel
/pkgs/os-specific/linux/kernel @raitobezarius
/pkgs/top-level/linux-kernels.nix @raitobezarius
# Hardened profile & related modules
/nixos/modules/profiles/hardened.nix @joachifm
/nixos/modules/security/hidepid.nix @joachifm
@ -214,6 +231,7 @@ pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt
/nixos/modules/services/networking/ntp @thoughtpolice
# Network
/pkgs/tools/networking/octodns @Janik-Haag
/pkgs/tools/networking/kea/default.nix @mweinelt
/pkgs/tools/networking/babeld/default.nix @mweinelt
/nixos/modules/services/networking/babeld.nix @mweinelt
@ -260,20 +278,13 @@ pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt
/pkgs/applications/editors/vscode/extensions @jonringer
# PHP interpreter, packages, extensions, tests and documentation
/doc/languages-frameworks/php.section.md @aanderse @drupol @etu @globin @ma27 @talyz
/nixos/tests/php @aanderse @drupol @etu @globin @ma27 @talyz
/pkgs/build-support/php/build-pecl.nix @aanderse @drupol @etu @globin @ma27 @talyz
/pkgs/build-support/php @drupol @etu
/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 @adisbladis
/nixos/modules/virtualisation/cri-o.nix @adisbladis
/nixos/modules/virtualisation/podman @adisbladis
/nixos/tests/cri-o.nix @adisbladis
/nixos/tests/podman @adisbladis
/doc/languages-frameworks/php.section.md @aanderse @drupol @globin @ma27 @talyz
/nixos/tests/php @aanderse @drupol @globin @ma27 @talyz
/pkgs/build-support/php/build-pecl.nix @aanderse @drupol @globin @ma27 @talyz
/pkgs/build-support/php @drupol
/pkgs/development/interpreters/php @jtojnar @aanderse @drupol @globin @ma27 @talyz
/pkgs/development/php-packages @aanderse @drupol @globin @ma27 @talyz
/pkgs/top-level/php-packages.nix @jtojnar @aanderse @drupol @globin @ma27 @talyz
# Docker tools
/pkgs/build-support/docker @roberth
@ -326,6 +337,9 @@ pkgs/applications/version-management/forgejo @bendlas @emilylange
/pkgs/build-support/node/fetch-npm-deps @lilyinstarlight @winterqt
/doc/languages-frameworks/javascript.section.md @lilyinstarlight @winterqt
# environment.noXlibs option aka NoX
/nixos/modules/config/no-x-libs.nix @SuperSandro2000
# OCaml
/pkgs/build-support/ocaml @ulrikstrid
/pkgs/development/compilers/ocaml @ulrikstrid
@ -341,5 +355,7 @@ nixos/tests/zfs.nix @raitobezarius
/pkgs/development/compilers/zig @figsoda
/doc/hooks/zig.section.md @figsoda
# Linux Kernel
pkgs/os-specific/linux/kernel/manual-config.nix @amjoseph-nixpkgs
# Buildbot
nixos/modules/services/continuous-integration/buildbot @Mic92 @zowoq
nixos/tests/buildbot.nix @Mic92 @zowoq
pkgs/development/tools/continuous-integration/buildbot @Mic92 @zowoq

4
.github/workflows/basic-eval.yml vendored
View File

@ -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@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
- uses: cachix/install-nix-action@7ac1ec25491415c381d9b62f0657c7a028df52a7 # v24
- uses: cachix/cachix-action@6a2e08b5ebf7a9f285ff57b1870a4262b06e0bee # v13
- uses: cachix/install-nix-action@6004951b182f8860210c8d6f0d808ec5b1a33d28 # v25
- uses: cachix/cachix-action@18cf96c7c98e048e10a83abd92116114cd8504be # v14
with:
# This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.
name: nixpkgs-ci

25
.github/workflows/check-by-name.yml vendored
View File

@ -4,11 +4,19 @@
# When you make changes to this workflow, also update pkgs/test/nixpkgs-check-by-name/scripts/run-local.sh adequately
name: Check pkgs/by-name
# The pre-built tool is fetched from a channel,
# making it work predictable on all PRs.
# The tool is pinned to a pre-built version on Hydra,
# see pkgs/test/nixpkgs-check-by-name/scripts/README.md
on:
# Using pull_request_target instead of pull_request avoids having to approve first time contributors
pull_request_target
pull_request_target:
# This workflow depends on the base branch of the PR,
# but changing the base branch is not included in the default trigger events,
# which would be `opened`, `synchronize` or `reopened`.
# Instead it causes an `edited` event, so we need to add it explicitly here
# While `edited` is also triggered when the PR title/body is changed,
# this PR action is fairly quick, and PR's don't get edited that often,
# so it shouldn't be a problem
types: [opened, synchronize, reopened, edited]
permissions:
# We need this permission to cancel the workflow run if there's a merge conflict
@ -90,9 +98,14 @@ jobs:
base=$(mktemp -d)
git worktree add "$base" "$(git rev-parse HEAD^1)"
echo "base=$base" >> "$GITHUB_ENV"
- uses: cachix/install-nix-action@7ac1ec25491415c381d9b62f0657c7a028df52a7 # v24
- name: Fetching the tool
run: pkgs/test/nixpkgs-check-by-name/scripts/fetch-tool.sh "$GITHUB_BASE_REF" result
- uses: cachix/install-nix-action@6004951b182f8860210c8d6f0d808ec5b1a33d28 # v25
- name: Fetching the pinned tool
# Update the pinned version using pkgs/test/nixpkgs-check-by-name/scripts/update-pinned-tool.sh
run: |
# Get the direct /nix/store path from the pin to avoid having to evaluate Nixpkgs
toolPath=$(jq -r '."ci-path"' pkgs/test/nixpkgs-check-by-name/scripts/pinned-tool.json)
# This asks the substituter for the path, which should be there because Hydra will have pre-built and pushed it
nix-store --realise "$toolPath" --add-root result
- name: Running nixpkgs-check-by-name
run: |
if result/bin/nixpkgs-check-by-name --base "$base" .; then

2
.github/workflows/check-maintainers-sorted.yaml vendored
View File

@ -16,7 +16,7 @@ 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@7ac1ec25491415c381d9b62f0657c7a028df52a7 # v24
- uses: cachix/install-nix-action@6004951b182f8860210c8d6f0d808ec5b1a33d28 # v25
with:
# explicitly enable sandbox
extra_nix_config: sandbox = true

2
.github/workflows/editorconfig.yml vendored
View File

@ -28,7 +28,7 @@ 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@7ac1ec25491415c381d9b62f0657c7a028df52a7 # v24
- uses: cachix/install-nix-action@6004951b182f8860210c8d6f0d808ec5b1a33d28 # v25
with:
# nixpkgs commit is pinned so that it doesn't break
# editorconfig-checker 2.4.0

4
.github/workflows/manual-nixos.yml vendored
View File

@ -18,11 +18,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@7ac1ec25491415c381d9b62f0657c7a028df52a7 # v24
- uses: cachix/install-nix-action@6004951b182f8860210c8d6f0d808ec5b1a33d28 # v25
with:
# explicitly enable sandbox
extra_nix_config: sandbox = true
- uses: cachix/cachix-action@6a2e08b5ebf7a9f285ff57b1870a4262b06e0bee # v13
- uses: cachix/cachix-action@18cf96c7c98e048e10a83abd92116114cd8504be # v14
with:
# This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.
name: nixpkgs-ci

4
.github/workflows/manual-nixpkgs.yml vendored
View File

@ -19,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@7ac1ec25491415c381d9b62f0657c7a028df52a7 # v24
- uses: cachix/install-nix-action@6004951b182f8860210c8d6f0d808ec5b1a33d28 # v25
with:
# explicitly enable sandbox
extra_nix_config: sandbox = true
- uses: cachix/cachix-action@6a2e08b5ebf7a9f285ff57b1870a4262b06e0bee # v13
- uses: cachix/cachix-action@18cf96c7c98e048e10a83abd92116114cd8504be # v14
with:
# This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.
name: nixpkgs-ci

42
.github/workflows/nix-parse.yml vendored Normal file
View File

@ -0,0 +1,42 @@
name: "Check whether nix files are parseable"
permissions: read-all
on:
# avoids approving first time contributors
pull_request_target:
branches-ignore:
- 'release-**'
jobs:
tests:
runs-on: ubuntu-latest
if: "github.repository_owner == 'NixOS' && !contains(github.event.pull_request.title, '[skip treewide]')"
steps:
- name: Get list of changed files from PR
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh api \
repos/NixOS/nixpkgs/pulls/${{github.event.number}}/files --paginate \
| jq --raw-output '.[] | select(.status != "removed" and (.filename | endswith(".nix"))) | .filename' \
> "$HOME/changed_files"
if [[ -s "$HOME/changed_files" ]]; then
echo "CHANGED_FILES=$HOME/changed_files" > "$GITHUB_ENV"
fi
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
with:
# pull_request_target checks out the base branch by default
ref: refs/pull/${{ github.event.pull_request.number }}/merge
if: ${{ env.CHANGED_FILES && env.CHANGED_FILES != '' }}
- uses: cachix/install-nix-action@6004951b182f8860210c8d6f0d808ec5b1a33d28 # v25
with:
nix_path: nixpkgs=channel:nixpkgs-unstable
- name: Parse all changed or added nix files
run: |
ret=0
while IFS= read -r file; do
out="$(nix-instantiate --parse "$file")" || { echo "$out" && ret=1; }
done < "$HOME/changed_files"
exit "$ret"
if: ${{ env.CHANGED_FILES && env.CHANGED_FILES != '' }}

6
.github/workflows/periodic-merge-24h.yml vendored
View File

@ -35,10 +35,6 @@ jobs:
pairs:
- from: master
into: haskell-updates
- from: release-23.05
into: staging-next-23.05
- from: staging-next-23.05
into: staging-23.05
- from: release-23.11
into: staging-next-23.11
- from: staging-next-23.11
@ -56,7 +52,7 @@ jobs:
github_token: ${{ secrets.GITHUB_TOKEN }}
- name: Comment on failure
uses: peter-evans/create-or-update-comment@23ff15729ef2fc348714a3bb66d2f655ca9066f2 # v3.1.0
uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0
if: ${{ failure() }}
with:
issue-number: 105153

2
.github/workflows/periodic-merge-6h.yml vendored
View File

@ -50,7 +50,7 @@ jobs:
github_token: ${{ secrets.GITHUB_TOKEN }}
- name: Comment on failure
uses: peter-evans/create-or-update-comment@23ff15729ef2fc348714a3bb66d2f655ca9066f2 # v3.1.0
uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0
if: ${{ failure() }}
with:
issue-number: 105153

4
.github/workflows/update-terraform-providers.yml vendored
View File

@ -17,7 +17,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
- uses: cachix/install-nix-action@7ac1ec25491415c381d9b62f0657c7a028df52a7 # v24
- uses: cachix/install-nix-action@6004951b182f8860210c8d6f0d808ec5b1a33d28 # v25
with:
nix_path: nixpkgs=channel:nixpkgs-unstable
- name: setup
@ -46,7 +46,7 @@ jobs:
run: |
git clean -f
- name: create PR
uses: peter-evans/create-pull-request@153407881ec5c347639a548ade7d8ad1d6740e38 # v5.0.2
uses: peter-evans/create-pull-request@a4f52f8033a6168103c2538976c07b467e8163bc # v6.0.1
with:
body: |
Automatic update by [update-terraform-providers](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/update-terraform-providers.yml) action.

1
.gitignore vendored
View File

@ -11,6 +11,7 @@ outputs/
result-*
result
repl-result-*
tags
!pkgs/development/python-modules/result
/doc/NEWS.html
/doc/NEWS.txt

1
.version
View File

@ -1 +0,0 @@
24.05

1
.version Symbolic link
View File

@ -0,0 +1 @@
lib/.version

36
CONTRIBUTING.md
View File

@ -129,19 +129,17 @@ When a PR is created, it will be pre-populated with some checkboxes detailed bel
#### Tested using sandboxing
When sandbox builds are enabled, Nix will setup an isolated environment for each build process. It is used to remove further hidden dependencies set by the build environment to improve reproducibility. This includes access to the network during the build outside of `fetch*` functions and files outside the Nix store. Depending on the operating system access to other resources are blocked as well (ex. inter process communication is isolated on Linux); see [sandbox](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-sandbox) in the Nix manual for details.
When sandbox builds are enabled, Nix will set up an isolated environment for each build process.
It is used to remove further hidden dependencies set by the build environment to improve reproducibility.
This includes access to the network during the build outside of `fetch*` functions and files outside the Nix store.
Depending on the operating system, access to other resources is blocked as well (e.g., inter-process communication is isolated on Linux); see [sandbox](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-sandbox) in the Nix manual for details.
Sandboxing is not enabled by default in Nix due to a small performance hit on each build. In pull requests for [nixpkgs](https://github.com/NixOS/nixpkgs/) people are asked to test builds with sandboxing enabled (see `Tested using sandboxing` in the pull request template) because in [Hydra](https://nixos.org/hydra/) sandboxing is also used.
In pull requests for [nixpkgs](https://github.com/NixOS/nixpkgs/) people are asked to test builds with sandboxing enabled (see `Tested using sandboxing` in the pull request template) because in [Hydra](https://nixos.org/hydra/) sandboxing is also used.
Depending if you use NixOS or other platforms you can use one of the following methods to enable sandboxing **before** building the package:
If you are on Linux, sandboxing is enabled by default.
On other platforms, sandboxing is disabled by default due to a small performance hit on each build.
- **Globally enable sandboxing on NixOS**: add the following to `configuration.nix`
```nix
nix.settings.sandbox = true;
```
- **Globally enable sandboxing on non-NixOS platforms**: add the following to: `/etc/nix/nix.conf`
Please enable sandboxing **before** building the package by adding the following to: `/etc/nix/nix.conf`:
```ini
sandbox = true
@ -323,7 +321,7 @@ All the review template samples provided in this section are generic and meant a
To get more information about how to review specific parts of Nixpkgs, refer to the documents linked to in the [overview section][overview].
If a pull request contains documentation changes that might require feedback from the documentation team, ping @NixOS/documentation-team on the pull request.
If a pull request contains documentation changes that might require feedback from the documentation team, ping [@NixOS/documentation-reviewers](https://github.com/orgs/nixos/teams/documentation-reviewers) on the pull request.
If you consider having enough knowledge and experience in a topic and would like to be a long-term reviewer for related submissions, please contact the current reviewers for that topic. They will give you information about the reviewing process. The main reviewers for a topic can be hard to find as there is no list, but checking past pull requests to see who reviewed or git-blaming the code to see who committed to that topic can give some hints.
@ -378,7 +376,7 @@ The staging workflow exists to batch Hydra builds of many packages together.
It works by directing commits that cause [mass rebuilds][mass-rebuild] to a separate `staging` branch that isn't directly built by Hydra.
Regularly, the `staging` branch is _manually_ merged into a `staging-next` branch to be built by Hydra using the [`nixpkgs:staging-next` jobset](https://hydra.nixos.org/jobset/nixpkgs/staging-next).
The `staging-next` branch should then only receive direct commits in order to fix Hydra builds.
Once it is verified that there are no major regressions, it is merged into `master` using [a pull requests](https://github.com/NixOS/nixpkgs/pulls?q=head%3Astaging-next).
Once it is verified that there are no major regressions, it is merged into `master` using [a pull request](https://github.com/NixOS/nixpkgs/pulls?q=head%3Astaging-next).
This is done manually in order to ensure it's a good use of Hydra's computing resources.
By keeping the `staging-next` branch separate from `staging`, this batching does not block developers from merging changes into `staging`.
@ -441,14 +439,14 @@ gitGraph
Here's an overview of the different branches:
| branch | `master` | `staging` | `staging-next` |
| branch | `master` | `staging-next` | `staging` |
| --- | --- | --- | --- |
| Used for development | ✔️ | ✔️ | ❌ |
| Built by Hydra | ✔️ | ❌ | ✔️ |
| [Mass rebuilds][mass-rebuild] | ❌ | ✔️ | ⚠️ Only to fix Hydra builds |
| Critical security fixes | ✔️ for non-mass-rebuilds | ❌ | ✔️ for mass-rebuilds |
| Automatically merged into | `staging-next` | - | `staging` |
| Manually merged into | - | `staging-next` | `master` |
| Used for development | ✔️ | ❌ | ✔️ |
| Built by Hydra | ✔️ | ✔️ | ❌ |
| [Mass rebuilds][mass-rebuild] | ❌ | ⚠️ Only to fix Hydra builds | ✔️ |
| Critical security fixes | ✔️ for non-mass-rebuilds | ✔️ for mass-rebuilds | ❌ |
| Automatically merged into | `staging-next` | `staging` | - |
| Manually merged into | - | `master` | `staging-next` |
The staging workflow is used for all main branches, `master` and `release-YY.MM`, with corresponding names:
- `master`/`release-YY.MM`

2
COPYING
View File

@ -1,4 +1,4 @@
Copyright (c) 2003-2023 Eelco Dolstra and the Nixpkgs/NixOS contributors
Copyright (c) 2003-2024 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

207
doc/README.md
View File

@ -71,6 +71,11 @@ If you **omit a link text** for a link pointing to a section, the text will be s
This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
#### HTML
Inlining HTML is not allowed. Parts of the documentation gets rendered to various non-HTML formats, such as man pages in the case of NixOS manual.
#### Roles
If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``. The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json).
@ -106,6 +111,19 @@ The following are supported:
- [`note`](https://tdg.docbook.org/tdg/5.0/note.html)
- [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)
- [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)
- [`example`](https://tdg.docbook.org/tdg/5.0/example.html)
Example admonitions require a title to work.
If you don't provide one, the manual won't be built.
```markdown
::: {.example #ex-showing-an-example}
# Title for this example
Text for the example.
:::
```
#### [Definition lists](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md)
@ -139,3 +157,192 @@ watermelon
Closes #216321.
- If the commit contains more than just documentation changes, follow the commit message format relevant for the rest of the changes.
## Documentation conventions
In an effort to keep the Nixpkgs manual in a consistent style, please follow the conventions below, unless they prevent you from properly documenting something.
In that case, please open an issue about the particular documentation convention and tag it with a "needs: documentation" label.
When needed, each convention explain why it exists, so you can make a decision whether to follow it or not based on your particular case.
Note that these conventions are about the **structure** of the manual (and its source files), not about the content that goes in it.
You, as the writer of documentation, are still in charge of its content.
- Put each sentence in its own line.
This makes reviews and suggestions much easier, since GitHub's review system is based on lines.
It also helps identifying long sentences at a glance.
- Use the [admonition syntax](#admonitions) for callouts and examples.
- Provide at least one example per function, and make examples self-contained.
This is easier to understand for beginners.
It also helps with testing that it actually works – especially once we introduce automation.
Example code should be such that it can be passed to `pkgs.callPackage`.
Instead of something like:
```nix
pkgs.dockerTools.buildLayeredImage {
name = "hello";
contents = [ pkgs.hello ];
}
```
Write something like:
```nix
{ dockerTools, hello }:
dockerTools.buildLayeredImage {
name = "hello";
contents = [ hello ];
}
```
- When showing inputs/outputs of any [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop), such as a shell or the Nix REPL, use a format as you'd see in the REPL, while trying to visually separate inputs from outputs.
This means that for a shell, you should use a format like the following:
```shell
$ nix-build -A hello '<nixpkgs>' \
--option require-sigs false \
--option trusted-substituters file:///tmp/hello-cache \
--option substituters file:///tmp/hello-cache
/nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1
```
Note how the input is preceded by `$` on the first line and indented on subsequent lines, and how the output is provided as you'd see on the shell.
For the Nix REPL, you should use a format like the following:
```shell
nix-repl> builtins.attrNames { a = 1; b = 2; }
[ "a" "b" ]
```
Note how the input is preceded by `nix-repl>` and the output is provided as you'd see on the Nix REPL.
- When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples.
Keep examples as the last nested heading, and link to the examples wherever applicable in the documentation.
The purpose of this convention is to provide a familiar structure for navigating the manual, so any reader can expect to find content related to inputs in an "inputs" heading, examples in an "examples" heading, and so on.
An example:
```
## buildImage
Some explanation about the function here.
Describe a particular scenario, and point to [](#ex-dockerTools-buildImage), which is an example demonstrating it.
### Inputs
Documentation for the inputs of `buildImage`.
Perhaps even point to [](#ex-dockerTools-buildImage) again when talking about something specifically linked to it.
### Passthru outputs
Documentation for any passthru outputs of `buildImage`.
### Examples
Note that this is the last nested heading in the `buildImage` section.
:::{.example #ex-dockerTools-buildImage}
# Using `buildImage`
Example of how to use `buildImage` goes here.
:::
```
- Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments as well as their [types](https://nixos.org/manual/nix/stable/language/values).
For example:
```markdown
# pkgs.coolFunction
Description of what `coolFunction` does.
## Inputs
`coolFunction` expects a single argument which should be an attribute set, with the following possible attributes:
`name` (String)
: The name of the resulting image.
`tag` (String; _optional_)
: Tag of the generated image.
_Default:_ the output path's hash.
```
#### Examples
To define a referenceable figure use the following fencing:
```markdown
:::{.example #an-attribute-set-example}
# An attribute set example
You can add text before
```nix
{ a = 1; b = 2;}
```
and after code fencing
:::
```
Defining examples through the `example` fencing class adds them to a "List of Examples" section after the Table of Contents.
Though this is not shown in the rendered documentation on nixos.org.
#### Figures
To define a referencable figure use the following fencing:
```markdown
::: {.figure #nixos-logo}
# NixOS Logo
![NixOS logo](./nixos_logo.png)
:::
```
Defining figures through the `figure` fencing class adds them to a `List of Figures` after the `Table of Contents`.
Though this is not shown in the rendered documentation on nixos.org.
#### Footnotes
To add a foonote explanation, use the following syntax:
```markdown
Sometimes it's better to add context [^context] in a footnote.
[^context]: This explanation will be rendered at the end of the chapter.
```
#### Inline comments
Inline comments are supported with following syntax:
```markdown
<!-- This is an inline comment -->
```
The comments will not be rendered in the rendered HTML.
#### Link reference definitions
Links can reference a label, for example, to make the link target reusable:
```markdown
::: {.note}
Reference links can also be used to [shorten URLs][url-id] and keep the markdown readable.
:::
[url-id]: https://github.com/NixOS/nixpkgs/blob/19d4f7dc485f74109bd66ef74231285ff797a823/doc/README.md
```
This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-reference-definitions).
#### Typographic replacements
Typographic replacements are enabled. Check the [list of possible replacement patterns check](https://github.com/executablebooks/markdown-it-py/blob/3613e8016ecafe21709471ee0032a90a4157c2d1/markdown_it/rules_core/replacements.py#L1-L15).
## Getting help
If you need documentation-specific help or reviews, ping [@NixOS/documentation-reviewers](https://github.com/orgs/nixos/teams/documentation-reviewers) on your pull request.

4
doc/build-helpers/fetchers.chapter.md
View File

@ -80,6 +80,10 @@ stdenv.mkDerivation {
The main difference between `fetchurl` and `fetchzip` is in how they store the contents. `fetchurl` will store the unaltered contents of the URL within the Nix store. `fetchzip` on the other hand, will decompress the archive for you, making files and directories directly accessible in the future. `fetchzip` can only be used with archives. Despite the name, `fetchzip` is not limited to .zip files and can also be used with any tarball.
Additional parameters to `fetchurl`:
- `downloadToTemp`: Defaults to `false`. If `true`, saves the source to `$downloadedFile`, to be used in conjunction with `postFetch`
- `postFetch`: Shell code executed after the file has been fetched successfully. Use it for postprocessing, to check or transform the file.
## `fetchpatch` {#fetchpatch}
`fetchpatch` works very similarly to `fetchurl` with the same arguments expected. It expects patch files as a source and performs normalization on them before computing the checksum. For example, it will remove comments or other unstable parts that are sometimes added by version control systems and can change over time.

181
doc/build-helpers/images/appimagetools.section.md
View File

@ -1,48 +1,167 @@
# pkgs.appimageTools {#sec-pkgs-appimageTools}
`pkgs.appimageTools` is a set of functions for extracting and wrapping [AppImage](https://appimage.org/) files. They are meant to be used if traditional packaging from source is infeasible, or it would take too long. To quickly run an AppImage file, `pkgs.appimage-run` can be used as well.
`pkgs.appimageTools` is a set of functions for extracting and wrapping [AppImage](https://appimage.org/) files.
They are meant to be used if traditional packaging from source is infeasible, or if it would take too long.
To quickly run an AppImage file, `pkgs.appimage-run` can be used as well.
::: {.warning}
The `appimageTools` API is unstable and may be subject to backwards-incompatible changes in the future.
:::
## AppImage formats {#ssec-pkgs-appimageTools-formats}
There are different formats for AppImages, see [the specification](https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format) for details.
- Type 1 images are ISO 9660 files that are also ELF executables.
- Type 2 images are ELF executables with an appended filesystem.
They can be told apart with `file -k`:
```ShellSession
$ file -k type1.AppImage
type1.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) ISO 9660 CD-ROM filesystem data 'AppImage' (Lepton 3.x), scale 0-0,
spot sensor temperature 0.000000, unit celsius, color scheme 0, calibration: offset 0.000000, slope 0.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=d629f6099d2344ad82818172add1d38c5e11bc6d, stripped\012- data
$ file -k type2.AppImage
type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x), scale 232-60668, spot sensor temperature -4.187500, color scheme 15, show scale bar, calibration: offset -0.000000, slope 0.000000 (Lepton 2.x), scale 4111-45000, spot sensor temperature 412442.250000, color scheme 3, minimum point enabled, calibration: offset -75402534979642766821519867692934234112.000000, slope 5815371847733706829839455140374904832.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=79dcc4e55a61c293c5e19edbd8d65b202842579f, stripped\012- data
```
Note how the type 1 AppImage is described as an `ISO 9660 CD-ROM filesystem`, and the type 2 AppImage is not.
## Wrapping {#ssec-pkgs-appimageTools-wrapping}
Depending on the type of AppImage you're wrapping, you'll have to use `wrapType1` or `wrapType2`.
Use `wrapType2` to wrap any AppImage.
This will create a FHS environment with many packages [expected to exist](https://github.com/AppImage/pkg2appimage/blob/master/excludelist) for the AppImage to work.
`wrapType2` expects an argument with the `src` attribute, and either a `name` attribute or `pname` and `version` attributes.
It will eventually call into [`buildFHSEnv`](#sec-fhs-environments), and any extra attributes in the argument to `wrapType2` will be passed through to it.
This means that you can pass the `extraInstallCommands` attribute, for example, and it will have the same effect as described in [`buildFHSEnv`](#sec-fhs-environments).
::: {.note}
In the past, `appimageTools` provided both `wrapType1` and `wrapType2`, to be used depending on the type of AppImage that was being wrapped.
However, [those were unified early 2020](https://github.com/NixOS/nixpkgs/pull/81833), meaning that both `wrapType1` and `wrapType2` have the same behaviour now.
:::
:::{.example #ex-wrapping-appimage-from-github}
# Wrapping an AppImage from GitHub
```nix
appimageTools.wrapType2 { # or wrapType1
name = "patchwork";
{ appimageTools, fetchurl }:
let
pname = "nuclear";
version = "0.6.30";
src = fetchurl {
url = "https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage";
hash = "sha256-OqTitCeZ6xmWbqYTXp8sDrmVgTNjPZNW0hzUPW++mq4=";
url = "https://github.com/nukeop/nuclear/releases/download/v${version}/${pname}-v${version}.AppImage";
hash = "sha256-he1uGC1M/nFcKpMM9JKY4oeexJcnzV0ZRxhTjtJz6xw=";
};
extraPkgs = pkgs: with pkgs; [ ];
in
appimageTools.wrapType2 {
inherit pname version src;
}
```
- `name` specifies the name of the resulting image.
- `src` specifies the AppImage file to extract.
- `extraPkgs` allows you to pass a function to include additional packages inside the FHS environment your AppImage is going to run in. There are a few ways to learn which dependencies an application needs:
- Looking through the extracted AppImage files, reading its scripts and running `patchelf` and `ldd` on its executables. This can also be done in `appimage-run`, by setting `APPIMAGE_DEBUG_EXEC=bash`.
:::
The argument passed to `wrapType2` can also contain an `extraPkgs` attribute, which allows you to include additional packages inside the FHS environment your AppImage is going to run in.
`extraPkgs` must be a function that returns a list of packages.
There are a few ways to learn which dependencies an application needs:
- Looking through the extracted AppImage files, reading its scripts and running `patchelf` and `ldd` on its executables.
This can also be done in `appimage-run`, by setting `APPIMAGE_DEBUG_EXEC=bash`.
- Running `strace -vfefile` on the wrapped executable, looking for libraries that can't be found.
:::{.example #ex-wrapping-appimage-with-extrapkgs}
# Wrapping an AppImage with extra packages
```nix
{ appimageTools, fetchurl }:
let
pname = "irccloud";
version = "0.16.0";
src = fetchurl {
url = "https://github.com/irccloud/irccloud-desktop/releases/download/v${version}/IRCCloud-${version}-linux-x86_64.AppImage";
sha256 = "sha256-/hMPvYdnVB1XjKgU2v47HnVvW4+uC3rhRjbucqin4iI=";
};
in appimageTools.wrapType2 {
inherit pname version src;
extraPkgs = pkgs: [ pkgs.at-spi2-core ];
}
```
:::
## Extracting {#ssec-pkgs-appimageTools-extracting}
Use `extract` if you need to extract the contents of an AppImage.
This is usually used in Nixpkgs to install extra files in addition to [wrapping](#ssec-pkgs-appimageTools-wrapping) the AppImage.
`extract` expects an argument with the `src` attribute, and either a `name` attribute or `pname` and `version` attributes.
::: {.note}
In the past, `appimageTools` provided both `extractType1` and `extractType2`, to be used depending on the type of AppImage that was being extracted.
However, [those were unified early 2020](https://github.com/NixOS/nixpkgs/pull/81572), meaning that both `extractType1` and `extractType2` have the same behaviour as `extract` now.
:::
:::{.example #ex-extracting-appimage}
# Extracting an AppImage to install extra files
This example was adapted from a real package in Nixpkgs to show how `extract` is usually used in combination with `wrapType2`.
Note how `appimageContents` is used in `extraInstallCommands` to install additional files that were extracted from the AppImage.
```nix
{ appimageTools, fetchurl }:
let
pname = "irccloud";
version = "0.16.0";
src = fetchurl {
url = "https://github.com/irccloud/irccloud-desktop/releases/download/v${version}/IRCCloud-${version}-linux-x86_64.AppImage";
sha256 = "sha256-/hMPvYdnVB1XjKgU2v47HnVvW4+uC3rhRjbucqin4iI=";
};
appimageContents = appimageTools.extract {
inherit pname version src;
};
in appimageTools.wrapType2 {
inherit pname version src;
extraPkgs = pkgs: [ pkgs.at-spi2-core ];
extraInstallCommands = ''
mv $out/bin/${pname}-${version} $out/bin/${pname}
install -m 444 -D ${appimageContents}/irccloud.desktop $out/share/applications/irccloud.desktop
install -m 444 -D ${appimageContents}/usr/share/icons/hicolor/512x512/apps/irccloud.png \
$out/share/icons/hicolor/512x512/apps/irccloud.png
substituteInPlace $out/share/applications/irccloud.desktop \
--replace 'Exec=AppRun' 'Exec=${pname}'
'';
}
```
:::
The argument passed to `extract` can also contain a `postExtract` attribute, which allows you to execute additional commands after the files are extracted from the AppImage.
`postExtract` must be a string with commands to run.
:::{.example #ex-extracting-appimage-with-postextract}
# Extracting an AppImage to install extra files, using `postExtract`
This is a rewrite of [](#ex-extracting-appimage) to use `postExtract`.
```nix
{ appimageTools, fetchurl }:
let
pname = "irccloud";
version = "0.16.0";
src = fetchurl {
url = "https://github.com/irccloud/irccloud-desktop/releases/download/v${version}/IRCCloud-${version}-linux-x86_64.AppImage";
sha256 = "sha256-/hMPvYdnVB1XjKgU2v47HnVvW4+uC3rhRjbucqin4iI=";
};
appimageContents = appimageTools.extract {
inherit pname version src;
postExtract = ''
substituteInPlace $out/irccloud.desktop --replace 'Exec=AppRun' 'Exec=${pname}'
'';
};
in appimageTools.wrapType2 {
inherit pname version src;
extraPkgs = pkgs: [ pkgs.at-spi2-core ];
extraInstallCommands = ''
mv $out/bin/${pname}-${version} $out/bin/${pname}
install -m 444 -D ${appimageContents}/irccloud.desktop $out/share/applications/irccloud.desktop
install -m 444 -D ${appimageContents}/usr/share/icons/hicolor/512x512/apps/irccloud.png \
$out/share/icons/hicolor/512x512/apps/irccloud.png
'';
}
```
:::

51
doc/build-helpers/images/binarycache.section.md
View File

@ -1,49 +1,58 @@
# 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.
`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.
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.
`mkBinaryCache` expects an argument with the `rootPaths` attribute.
`rootPaths` must be a list of derivations.
The transitive closure of these derivations' outputs will be copied into the cache.
## Example {#sec-pkgs-binary-cache-example}
::: {.note}
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.
:::
[]{#sec-pkgs-binary-cache-example}
:::{.example #ex-mkbinarycache-copying-package-closure}
# Copying a package and its closure to another machine with `mkBinaryCache`
The following derivation will construct a flat-file binary cache containing the closure of `hello`.
```nix
{ mkBinaryCache, hello }:
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`:
Build the cache on a machine.
Note that the command still builds the exact nix package above, but adds some boilerplate to build it directly from an expression.
```shellSession
nix-build -E 'with import <nixpkgs> {}; mkBinaryCache { rootPaths = [hello]; }'
$ nix-build -E 'let pkgs = import <nixpkgs> {}; in pkgs.callPackage ({ mkBinaryCache, hello }: mkBinaryCache { rootPaths = [hello]; }) {}'
/nix/store/azf7xay5xxdnia4h9fyjiv59wsjdxl0g-binary-cache
```
Copy the resulting directory to another machine, which we'll call `host2`:
```shellSession
/nix/store/cc0562q828rnjqjyfj23d5q162gb424g-binary-cache
$ scp result host2:/tmp/hello-cache
```
Copy the resulting directory to the other machine, `host2`:
At this point, the cache can be used as a substituter when building derivations on `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>' \
$ nix-build -A hello '<nixpkgs>' \
--option require-sigs false \
--option trusted-substituters file:///tmp/hello-cache \
--option substituters file:///tmp/hello-cache
/nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1
```
```shellSession
/nix/store/gl5a41azbpsadfkfmbilh9yk40dh5dl0-hello-2.12.1
```
:::

1865
doc/build-helpers/images/dockertools.section.md
View File

File diff suppressed because it is too large Load Diff

107
doc/build-helpers/images/ocitools.section.md
View File

@ -1,37 +1,104 @@
# pkgs.ociTools {#sec-pkgs-ociTools}
`pkgs.ociTools` is a set of functions for creating containers according to the [OCI container specification v1.0.0](https://github.com/opencontainers/runtime-spec). Beyond that, it makes no assumptions about the container runner you choose to use to run the created container.
`pkgs.ociTools` is a set of functions for creating runtime container bundles according to the [OCI runtime specification v1.0.0](https://github.com/opencontainers/runtime-spec/blob/v1.0.0/spec.md).
It makes no assumptions about the container runner you choose to use to run the created container.
The set of functions in `pkgs.ociTools` currently does not handle the [OCI image specification](https://github.com/opencontainers/image-spec).
At a high-level an OCI implementation would download an OCI Image then unpack that image into an OCI Runtime filesystem bundle.
At this point the OCI Runtime Bundle would be run by an OCI Runtime.
`pkgs.ociTools` provides utilities to create OCI Runtime bundles.
## buildContainer {#ssec-pkgs-ociTools-buildContainer}
This function creates a simple OCI container that runs a single command inside of it. An OCI container consists of a `config.json` and a rootfs directory. The nix store of the container will contain all referenced dependencies of the given command.
This function creates an OCI runtime container (consisting of a `config.json` and a root filesystem directory) that runs a single command inside of it.
The nix store of the container will contain all referenced dependencies of the given command.
The parameters of `buildContainer` with an example value are described below:
This function has an assumption that the container will run on POSIX platforms, and sets configurations (such as the user running the process or certain mounts) according to this assumption.
Because of this, a container built with `buildContainer` will not work on Windows or other non-POSIX platforms without modifications to the container configuration.
These modifications aren't supported by `buildContainer`.
For `linux` platforms, `buildContainer` also configures the following namespaces (see {manpage}`unshare(1)`) to isolate the OCI container from the global namespace:
PID, network, mount, IPC, and UTS.
Note that no user namespace is created, which means that you won't be able to run the container unless you are the `root` user.
### Inputs {#ssec-pkgs-ociTools-buildContainer-inputs}
`buildContainer` expects an argument with the following attributes:
`args` (List of String)
: Specifies a set of arguments to run inside the container.
Any packages referenced by `args` will be made available inside the container.
`mounts` (Attribute Set; _optional_)
: Would specify additional mounts that the runtime must make available to the container.
:::{.warning}
As explained in [issue #290879](https://github.com/NixOS/nixpkgs/issues/290879), this attribute is currently ignored.
:::
:::{.note}
`buildContainer` includes a minimal set of necessary filesystems to be mounted into the container, and this set can't be changed with the `mounts` attribute.
:::
_Default value:_ `{}`.
`readonly` (Boolean; _optional_)
: If `true`, sets the container's root filesystem as read-only.
_Default value:_ `false`.
`os` **DEPRECATED**
: Specifies the operating system on which the container filesystem is based on.
If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).
According to the linked specification, all possible values for `$GOOS` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `darwin` or `linux`.
_Default value:_ `"linux"`.
`arch` **DEPRECATED**
: Used to specify the architecture for which the binaries in the container filesystem have been compiled.
If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).
According to the linked specification, all possible values for `$GOARCH` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `386`, `amd64`, `arm`, or `arm64`.
_Default value:_ `x86_64`.
### Examples {#ssec-pkgs-ociTools-buildContainer-examples}
::: {.example #ex-ociTools-buildContainer-bash}
# Creating an OCI runtime container that runs `bash`
This example uses `ociTools.buildContainer` to create a simple container that runs `bash`.
```nix
buildContainer {
{ ociTools, lib, bash }:
ociTools.buildContainer {
args = [
(with pkgs;
writeScript "run.sh" ''
#!${bash}/bin/bash
exec ${bash}/bin/bash
'').outPath
(lib.getExe bash)
];
mounts = {
"/data" = {
type = "none";
source = "/var/lib/mydata";
options = [ "bind" ];
};
};
readonly = false;
}
```
- `args` specifies a set of arguments to run inside the container. This is the only required argument for `buildContainer`. All referenced packages inside the derivation will be made available inside the container.
As an example of how to run the container generated by this package, we'll use `runc` to start the container.
Any other tool that supports OCI containers could be used instead.
- `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)
```shell
$ nix-build
(some output removed for clarity)
/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join
- `readonly` makes the container's rootfs read-only if it is set to true. The default value is false `false`.
$ cd /nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join
$ nix-shell -p runc
[nix-shell:/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join]$ sudo runc run ocitools-example
help
GNU bash, version 5.2.26(1)-release (x86_64-pc-linux-gnu)
(some output removed for clarity)
```
:::

207
doc/build-helpers/images/portableservice.section.md
View File

@ -1,81 +1,174 @@
# 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.
`pkgs.portableService` is a function to create [Portable Services](https://systemd.io/PORTABLE_SERVICES/) in a read-only, immutable, `squashfs` raw disk image.
This lets you use Nix to build images which can be run on many recent Linux distributions.
::: {.note}
Portable services are supported starting with systemd 239 (released on 2018-06-22).
:::
A very simple example of using `portableService` is described below:
The generated image will contain the file system structure as required by the Portable Services specification, along with the packages given to `portableService` and all of their dependencies.
When generated, the image will exist in the Nix store with the `.raw` file extension, as required by the specification.
See [](#ex-portableService-hello) to understand how to use the output of `portableService`.
## Inputs {#ssec-pkgs-portableService-inputs}
`portableService` expects one argument with the following attributes:
`pname` (String)
: The name of the portable service.
The generated image will be named according to the template `$pname_$version.raw`, which is supported by the Portable Services specification.
`version` (String)
: The version of the portable service.
The generated image will be named according to the template `$pname_$version.raw`, which is supported by the Portable Services specification.
`units` (List of Attribute Set)
: A list of derivations for systemd unit files.
Each derivation must produce a single file, and must have a name that starts with the value of `pname` and ends with the suffix of the unit type (e.g. ".service", ".socket", ".timer", and so on).
See [](#ex-portableService-hello) to better understand this naming constraint.
`description` (String or Null; _optional_)
: If specified, the value is added as `PORTABLE_PRETTY_NAME` to the `/etc/os-release` file in the generated image.
This could be used to provide more information to anyone inspecting the image.
_Default value:_ `null`.
`homepage` (String or Null; _optional_)
: If specified, the value is added as `HOME_URL` to the `/etc/os-release` file in the generated image.
This could be used to provide more information to anyone inspecting the image.
_Default value:_ `null`.
`symlinks` (List of Attribute Set; _optional_)
: A list of attribute sets in the format `{object, symlink}`.
For each item in the list, `portableService` will create a symlink in the path specified by `symlink` (relative to the root of the image) that points to `object`.
All packages that `object` depends on and their dependencies are automatically copied into the image.
This can be used to create symlinks for applications that assume some files to exist globally (`/etc/ssl` or `/bin/bash`, for example).
See [](#ex-portableService-symlinks) to understand how to do that.
_Default value:_ `[]`.
`contents` (List of Attribute Set; _optional_)
: A list of additional derivations to be included as-is in the image.
These derivations will be included directly in a `/nix/store` directory inside the image.
_Default value:_ `[]`.
`squashfsTools` (Attribute Set; _optional_)
: Allows you to override the package that provides {manpage}`mksquashfs(1)`, which is used internally by `portableService`.
_Default value:_ `pkgs.squashfsTools`.
`squash-compression` (String; _optional_)
: Passed as the compression option to {manpage}`mksquashfs(1)`, which is used internally by `portableService`.
_Default value:_ `"xz -Xdict-size 100%"`.
`squash-block-size` (String; _optional_)
: Passed as the block size option to {manpage}`mksquashfs(1)`, which is used internally by `portableService`.
_Default value:_ `"1M"`.
## Examples {#ssec-pkgs-portableService-examples}
[]{#ex-pkgs-portableService}
:::{.example #ex-portableService-hello}
# Building a Portable Service image
The following example builds a Portable Service image with the `hello` package, along with a service unit that runs it.
```nix
pkgs.portableService {
pname = "demo";
version = "1.0";
units = [ demo-service demo-socket ];
{ lib, writeText, portableService, hello }:
let
hello-service = writeText "hello.service" ''
[Unit]
Description=Hello world service
[Service]
Type=oneshot
ExecStart=${lib.getExe hello}
'';
in
portableService {
pname = "hello";
inherit (hello) version;
units = [ hello-service ];
}
```
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.
After building the package, the generated image can be loaded into a system through {manpage}`portablectl(1)`:
::: {.note}
The `.raw` file extension of the image is required by the portable services specification.
```shell
$ nix-build
(some output removed for clarity)
/nix/store/8c20z1vh7z8w8dwagl8w87b45dn5k6iq-hello-img-2.12.1
$ portablectl attach /nix/store/8c20z1vh7z8w8dwagl8w87b45dn5k6iq-hello-img-2.12.1/hello_2.12.1.raw
Created directory /etc/systemd/system.attached.
Created directory /etc/systemd/system.attached/hello.service.d.
Written /etc/systemd/system.attached/hello.service.d/20-portable.conf.
Created symlink /etc/systemd/system.attached/hello.service.d/10-profile.conf → /usr/lib/systemd/portable/profile/default/service.conf.
Copied /etc/systemd/system.attached/hello.service.
Created symlink /etc/portables/hello_2.12.1.raw → /nix/store/8c20z1vh7z8w8dwagl8w87b45dn5k6iq-hello-img-2.12.1/hello_2.12.1.raw.
$ systemctl start hello
$ journalctl -u hello
Feb 28 22:39:16 hostname systemd[1]: Starting Hello world service...
Feb 28 22:39:16 hostname hello[102887]: Hello, world!
Feb 28 22:39:16 hostname systemd[1]: hello.service: Deactivated successfully.
Feb 28 22:39:16 hostname systemd[1]: Finished Hello world service.
$ portablectl detach hello_2.12.1
Removed /etc/systemd/system.attached/hello.service.
Removed /etc/systemd/system.attached/hello.service.d/10-profile.conf.
Removed /etc/systemd/system.attached/hello.service.d/20-portable.conf.
Removed /etc/systemd/system.attached/hello.service.d.
Removed /etc/portables/hello_2.12.1.raw.
Removed /etc/systemd/system.attached.
```
:::
Some other options available are:
- `description`, `homepage`
:::{.example #ex-portableService-symlinks}
# Specifying symlinks when building a Portable Service image
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`
Some services may expect files or directories to be available globally.
An example is a service which expects all trusted SSL certificates to exist in a specific location by default.
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`
To make things available globally, you must specify the `symlinks` attribute when using `portableService`.
The following package builds on the package from [](#ex-portableService-hello) to make `/etc/ssl` available globally (this is only for illustrative purposes, because `hello` doesn't use `/etc/ssl`).
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.
{ lib, writeText, portableService, hello, cacert }:
let
hello-service = writeText "hello.service" ''
[Unit]
Description=Hello world service
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
[Service]
Type=oneshot
ExecStart=${lib.getExe hello}
'';
in
portableService {
pname = "hello";
inherit (hello) version;
units = [ hello-service ];
symlinks = [
{ object = "${cacert}/etc/ssl"; symlink = "/etc/ssl"; }
];
}
```
::: {.note}
See the [man page](https://www.freedesktop.org/software/systemd/man/portablectl.html) of `portablectl` for more info on its usage.
:::

1
doc/build-helpers/special.md
View File

@ -3,6 +3,7 @@
This chapter describes several special build helpers.
```{=include=} sections
special/fakenss.section.md
special/fhs-environments.section.md
special/makesetuphook.section.md
special/mkshell.section.md

21
doc/build-helpers/special/checkpoint-build.section.md
View File

@ -2,35 +2,38 @@
`pkgs.checkpointBuildTools` provides a way to build derivations incrementally. It consists of two functions to make checkpoint builds using Nix possible.
For hermeticity, Nix derivations do not allow any state to carry over between builds, making a transparent incremental build within a derivation impossible.
For hermeticity, Nix derivations do not allow any state to be carried over between builds, making a transparent incremental build within a derivation impossible.
However, we can tell Nix explicitly what the previous build state was, by representing that previous state as a derivation output. This allows the passed build state to be used for an incremental build.
To change a normal derivation to a checkpoint based build, these steps must be taken:
- apply `prepareCheckpointBuild` on the desired derivation
e.g.:
- apply `prepareCheckpointBuild` on the desired derivation, e.g.
```nix
checkpointArtifacts = (pkgs.checkpointBuildTools.prepareCheckpointBuild pkgs.virtualbox);
```
- change something you want in the sources of the package. (e.g. using a source override)
- change something you want in the sources of the package, e.g. use a source override:
```nix
changedVBox = pkgs.virtualbox.overrideAttrs (old: {
src = path/to/vbox/sources;
}
});
```
- use `mkCheckpointedBuild changedVBox buildOutput`
- use `mkCheckpointBuild changedVBox checkpointArtifacts`
- enjoy shorter build times
## Example {#sec-checkpoint-build-example}
```nix
{ pkgs ? import <nixpkgs> {} }: with (pkgs) checkpointBuildTools;
{ pkgs ? import <nixpkgs> {} }:
let
helloCheckpoint = checkpointBuildTools.prepareCheckpointBuild pkgs.hello;
inherit (pkgs.checkpointBuildTools)
prepareCheckpointBuild
mkCheckpointBuild
;
helloCheckpoint = prepareCheckpointBuild pkgs.hello;
changedHello = pkgs.hello.overrideAttrs (_: {
doCheck = false;
patchPhase = ''
sed -i 's/Hello, world!/Hello, Nix!/g' src/hello.c
'';
});
in checkpointBuildTools.mkCheckpointBuild changedHello helloCheckpoint
in mkCheckpointBuild changedHello helloCheckpoint
```

77
doc/build-helpers/special/fakenss.section.md Normal file
View File

@ -0,0 +1,77 @@
# fakeNss {#sec-fakeNss}
Provides `/etc/passwd` and `/etc/group` files that contain `root` and `nobody`, allowing user/group lookups to work in binaries that insist on doing those.
This might be a better choice than a custom script running `useradd` and related utilities if you only need those files to exist with some entries.
`fakeNss` also provides `/etc/nsswitch.conf`, configuring NSS host resolution to first check `/etc/hosts` before checking DNS, since the default in the absence of a config file (`dns [!UNAVAIL=return] files`) is quite unexpected.
It also creates an empty directory at `/var/empty` because it uses that as the home directory for the `root` and `nobody` users.
The `/var/empty` directory can also be used as a `chroot` target to prevent file access in processes that do not need to access files, if your container runs such processes.
The user entries created by `fakeNss` use the `/bin/sh` shell, which is not provided by `fakeNss` because in most cases it won't be used.
If you need that to be available, see [`dockerTools.binSh`](#sssec-pkgs-dockerTools-helpers-binSh) or provide your own.
## Inputs {#sec-fakeNss-inputs}
`fakeNss` is made available in Nixpkgs as a package rather than a function, but it has two attributes that can be overridden and might be useful in particular cases.
For more details on how overriding works, see [](#ex-fakeNss-overriding) and [](#sec-pkg-override).
`extraPasswdLines` (List of Strings; _optional_)
: A list of lines that will be added to `/etc/passwd`.
Useful if extra users need to exist in the output of `fakeNss`.
If `extraPasswdLines` is specified, it will **not** override the `root` and `nobody` entries created by `fakeNss`.
Those entries will always exist.
Lines specified here must follow the format in {manpage}`passwd(5)`.
_Default value:_ `[]`.
`extraGroupLines` (List of Strings; _optional_)
: A list of lines that will be added to `/etc/group`.
Useful if extra groups need to exist in the output of `fakeNss`.
If `extraGroupLines` is specified, it will **not** override the `root` and `nobody` entries created by `fakeNss`.
Those entries will always exist.
Lines specified here must follow the format in {manpage}`group(5)`.
_Default value:_ `[]`.
## Examples {#sec-fakeNss-examples}
:::{.example #ex-fakeNss-dockerTools-buildImage}
# Using `fakeNss` with `dockerTools.buildImage`
This example shows how to use `fakeNss` as-is.
It is useful with functions in `dockerTools` to allow building Docker images that have the `/etc/passwd` and `/etc/group` files.
This example includes the `hello` binary in the image so it can do something besides just have the extra files.
```nix
{ dockerTools, fakeNss, hello }:
dockerTools.buildImage {
name = "image-with-passwd";
tag = "latest";
copyToRoot = [ fakeNss hello ];
config = {
Cmd = [ "/bin/hello" ];
};
}
```
:::
:::{.example #ex-fakeNss-overriding}
# Using `fakeNss` with an override to add extra lines
The following code uses `override` to add extra lines to `/etc/passwd` and `/etc/group` to create another user and group entry.
```nix
{ fakeNss }:
fakeNss.override {
extraPasswdLines = ["newuser:x:9001:9001:new user:/var/empty:/bin/sh"];
extraGroupLines = ["newuser:x:9001:"];
}
```
:::

4
doc/build-helpers/special/mkshell.section.md
View File

@ -29,6 +29,10 @@ pkgs.mkShell {
... all the attributes of `stdenv.mkDerivation`.
## Variants {#sec-pkgs-mkShell-variants}
`pkgs.mkShellNoCC` is a variant that uses `stdenvNoCC` instead of `stdenv` as base environment. This is useful if no C compiler is needed in the shell environment.
## Building the shell {#sec-pkgs-mkShell-building}
This derivation output will contain a text file that contains a reference to

445
doc/build-helpers/trivial-build-helpers.chapter.md
View File

@ -1,6 +1,7 @@
# Trivial build helpers {#chap-trivial-builders}
Nixpkgs provides a couple of functions that help with building derivations. The most important one, `stdenv.mkDerivation`, has already been documented above. The following functions wrap `stdenv.mkDerivation`, making it easier to use in certain cases.
Nixpkgs provides a variety of wrapper functions that help build commonly useful derivations.
Like [`stdenv.mkDerivation`](#sec-using-stdenv), each of these build helpers creates a derivation, but the arguments passed are different (usually simpler) from those required by `stdenv.mkDerivation`.
## `runCommand` {#trivial-builder-runCommand}
@ -58,63 +59,416 @@ Variant of `runCommand` that forces the derivation to be built locally, it is no
This sets [`allowSubstitutes` to `false`](https://nixos.org/nix/manual/#adv-attr-allowSubstitutes), so only use `runCommandLocal` if you are certain the user will always have a builder for the `system` of the derivation. This should be true for most trivial use cases (e.g., just copying some files to a different location or adding symlinks) because there the `system` is usually the same as `builtins.currentSystem`.
:::
## `writeTextFile`, `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin` {#trivial-builder-writeText}
## Writing text files {#trivial-builder-text-writing}
These functions write `text` to the Nix store. This is useful for creating scripts from Nix expressions. `writeTextFile` takes an attribute set and expects two arguments, `name` and `text`. `name` corresponds to the name used in the Nix store path. `text` will be the contents of the file. You can also set `executable` to true to make this file have the executable bit set.
Nixpkgs provides the following functions for producing derivations which write text files or executable scripts into the Nix store.
They are useful for creating files from Nix expression, and are all implemented as convenience wrappers around `writeTextFile`.
Many more commands wrap `writeTextFile` including `writeText`, `writeTextDir`, `writeScript`, and `writeScriptBin`. These are convenience functions over `writeTextFile`.
Each of these functions will cause a derivation to be produced.
When you coerce the result of each of these functions to a string with [string interpolation](https://nixos.org/manual/nix/stable/language/string-interpolation) or [`builtins.toString`](https://nixos.org/manual/nix/stable/language/builtins#builtins-toString), it will evaluate to the [store path](https://nixos.org/manual/nix/stable/store/store-path) of this derivation.
:::: {.note}
Some of these functions will put the resulting files within a directory inside the [derivation output](https://nixos.org/manual/nix/stable/language/derivations#attr-outputs).
If you need to refer to the resulting files somewhere else in a Nix expression, append their path to the derivation's store path.
For example, if the file destination is a directory:
```nix
my-file = writeTextFile {
name = "my-file";
text = ''
Contents of File
'';
destination = "/share/my-file";
}
```
Remember to append "/share/my-file" to the resulting store path when using it elsewhere:
```nix
writeShellScript "evaluate-my-file.sh" ''
cat ${my-file}/share/my-file
'';
```
::::
### `writeTextFile` {#trivial-builder-writeTextFile}
Write a text file to the Nix store.
`writeTextFile` takes an attribute set with the following possible attributes:
`name` (String)
: Corresponds to the name used in the Nix store path identifier.
`text` (String)
: The contents of the file.
`executable` (Bool, _optional_)
: Make this file have the executable bit set.
Default: `false`
`destination` (String, _optional_)
: A subpath under the derivation's output path into which to put the file.
Subdirectories are created automatically when the derivation is realised.
By default, the store path itself will be a file containing the text contents.
Default: `""`
`checkPhase` (String, _optional_)
: Commands to run after generating the file.
Default: `""`
`meta` (Attribute set, _optional_)
: Additional metadata for the derivation.
Default: `{}`
`allowSubstitutes` (Bool, _optional_)
: Whether to allow substituting from a binary cache.
Passed through to [`allowSubsitutes`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-allowSubstitutes) of the underlying call to `builtins.derivation`.
It defaults to `false`, as running the derivation's simple `builder` executable locally is assumed to be faster than network operations.
Set it to true if the `checkPhase` step is expensive.
Default: `false`
`preferLocalBuild` (Bool, _optional_)
: Whether to prefer building locally, even if faster [remote build machines](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-substituters) are available.
Passed through to [`preferLocalBuild`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-preferLocalBuild) of the underlying call to `builtins.derivation`.
It defaults to `true` for the same reason `allowSubstitutes` defaults to `false`.
Default: `true`
The resulting store path will include some variation of the name, and it will be a file unless `destination` is used, in which case it will be a directory.
::: {.example #ex-writeTextFile}
# Usage 1 of `writeTextFile`
Write `my-file` to `/nix/store/<store path>/some/subpath/my-cool-script`, making it executable.
Also run a check on the resulting file in a `checkPhase`, and supply values for the less-used options.
```nix
writeTextFile {
name = "my-cool-script";
text = ''
#!/bin/sh
echo "This is my cool script!"
'';
executable = true;
destination = "/some/subpath/my-cool-script";
checkPhase = ''
${pkgs.shellcheck}/bin/shellcheck $out/some/subpath/my-cool-script
'';
meta = {
license = pkgs.lib.licenses.cc0;
};
allowSubstitutes = true;
preferLocalBuild = false;
};
```
:::
::: {.example #ex2-writeTextFile}
# Usage 2 of `writeTextFile`
Write the string `Contents of File` to `/nix/store/<store path>`.
See also the [](#trivial-builder-writeText) helper function.
Here are a few examples:
```nix
# Writes my-file to /nix/store/<store path>
writeTextFile {
name = "my-file";
text = ''
Contents of File
'';
}
# See also the `writeText` helper function below.
```
:::
# Writes executable my-file to /nix/store/<store path>/bin/my-file
::: {.example #ex3-writeTextFile}
# Usage 3 of `writeTextFile`
Write an executable script `my-script` to `/nix/store/<store path>/bin/my-script`.
See also the [](#trivial-builder-writeScriptBin) helper function.
```nix
writeTextFile {
name = "my-script";
text = ''
echo "hi"
'';
executable = true;
destination = "/bin/my-script";
}
```
:::
### `writeText` {#trivial-builder-writeText}
Write a text file to the Nix store
`writeText` takes the following arguments:
a string.
`name` (String)
: The name used in the Nix store path.
`text` (String)
: The contents of the file.
The store path will include the name, and it will be a file.
::: {.example #ex-writeText}
# Usage of `writeText`
Write the string `Contents of File` to `/nix/store/<store path>`:
```nix
writeText "my-file"
''
Contents of File
'';
```
:::
This is equivalent to:
```nix
writeTextFile {
name = "my-file";
text = ''
Contents of File
'';
}
```
### `writeTextDir` {#trivial-builder-writeTextDir}
Write a text file within a subdirectory of the Nix store.
`writeTextDir` takes the following arguments:
`path` (String)
: The destination within the Nix store path under which to create the file.
`text` (String)
: The contents of the file.
The store path will be a directory.
::: {.example #ex-writeTextDir}
# Usage of `writeTextDir`
Write the string `Contents of File` to `/nix/store/<store path>/share/my-file`:
```nix
writeTextDir "share/my-file"
''
Contents of File
'';
```
:::
This is equivalent to:
```nix
writeTextFile {
name = "my-file";
text = ''
Contents of File
'';
destination = "share/my-file";
}
```
### `writeScript` {#trivial-builder-writeScript}
Write an executable script file to the Nix store.
`writeScript` takes the following arguments:
`name` (String)
: The name used in the Nix store path.
`text` (String)
: The contents of the file.
The created file is marked as executable.
The store path will include the name, and it will be a file.
::: {.example #ex-writeScript}
# Usage of `writeScript`
Write the string `Contents of File` to `/nix/store/<store path>` and make the file executable.
```nix
writeScript "my-file"
''
Contents of File
'';
```
:::
This is equivalent to:
```nix
writeTextFile {
name = "my-file";
text = ''
Contents of File
'';
executable = true;
destination = "/bin/my-file";
}
# Writes contents of file to /nix/store/<store path>
writeText "my-file"
''
Contents of File
'';
# Writes contents of file to /nix/store/<store path>/share/my-file
writeTextDir "share/my-file"
''
Contents of File
'';
# Writes my-file to /nix/store/<store path> and makes executable
writeScript "my-file"
''
Contents of File
'';
# Writes my-file to /nix/store/<store path>/bin/my-file and makes executable.
writeScriptBin "my-file"
''
Contents of File
'';
# Writes my-file to /nix/store/<store path> and makes executable.
writeShellScript "my-file"
''
Contents of File
'';
# Writes my-file to /nix/store/<store path>/bin/my-file and makes executable.
writeShellScriptBin "my-file"
''
Contents of File
'';
```
### `writeScriptBin` {#trivial-builder-writeScriptBin}
Write a script within a `bin` subirectory of a directory in the Nix store.
This is for consistency with the convention of software packages placing executables under `bin`.
`writeScriptBin` takes the following arguments:
`name` (String)
: The name used in the Nix store path and within the file created under the store path.
`text` (String)
: The contents of the file.
The created file is marked as executable.
The file's contents will be put into `/nix/store/<store path>/bin/<name>`.
The store path will include the the name, and it will be a directory.
::: {.example #ex-writeScriptBin}
# Usage of `writeScriptBin`
```nix
writeScriptBin "my-script"
''
echo "hi"
'';
```
:::
This is equivalent to:
```nix
writeTextFile {
name = "my-script";
text = ''
echo "hi"
'';
executable = true;
destination = "bin/my-script"
}
```
### `writeShellScript` {#trivial-builder-writeShellScript}
Write a Bash script to the store.
`writeShellScript` takes the following arguments:
`name` (String)
: The name used in the Nix store path.
`text` (String)
: The contents of the file.
The created file is marked as executable.
The store path will include the name, and it will be a file.
This function is almost exactly like [](#trivial-builder-writeScript), except that it prepends to the file a [shebang](https://en.wikipedia.org/wiki/Shebang_%28Unix%29) line that points to the version of Bash used in Nixpkgs.
<!-- this cannot be changed in practice, so there is no point pretending it's somehow generic -->
::: {.example #ex-writeShellScript}
# Usage of `writeShellScript`
```nix
writeShellScript "my-script"
''
echo "hi"
'';
```
:::
This is equivalent to:
```nix
writeTextFile {
name = "my-script";
text = ''
#! ${pkgs.runtimeShell}
echo "hi"
'';
executable = true;
}
```
### `writeShellScriptBin` {#trivial-builder-writeShellScriptBin}
Write a Bash script to a "bin" subdirectory of a directory in the Nix store.
`writeShellScriptBin` takes the following arguments:
`name` (String)
: The name used in the Nix store path and within the file generated under the store path.
`text` (String)
: The contents of the file.
The file's contents will be put into `/nix/store/<store path>/bin/<name>`.
The store path will include the the name, and it will be a directory.
This function is a combination of [](#trivial-builder-writeShellScript) and [](#trivial-builder-writeScriptBin).
::: {.example #ex-writeShellScriptBin}
# Usage of `writeShellScriptBin`
```nix
writeShellScriptBin "my-script"
''
echo "hi"
'';
```
:::
This is equivalent to:
```nix
writeTextFile {
name = "my-script";
text = ''
#! ${pkgs.runtimeShell}
echo "hi"
'';
executable = true;
destination = "bin/my-script"
}
```
## `concatTextFile`, `concatText`, `concatScript` {#trivial-builder-concatText}
@ -148,9 +502,14 @@ concatScript "my-file" [ file1 file2 ]
## `writeShellApplication` {#trivial-builder-writeShellApplication}
This can be used to easily produce a shell script that has some dependencies (`runtimeInputs`). It automatically sets the `PATH` of the script to contain all of the listed inputs, sets some sanity shellopts (`errexit`, `nounset`, `pipefail`), and checks the resulting script with [`shellcheck`](https://github.com/koalaman/shellcheck).
`writeShellApplication` is similar to `writeShellScriptBin` and `writeScriptBin` but supports runtime dependencies with `runtimeInputs`.
Writes an executable shell script to `/nix/store/<store path>/bin/<name>` and checks its syntax with [`shellcheck`](https://github.com/koalaman/shellcheck) and the `bash`'s `-n` option.
Some basic Bash options are set by default (`errexit`, `nounset`, and `pipefail`), but can be overridden with `bashOptions`.
For example, look at the following code:
Extra arguments may be passed to `stdenv.mkDerivation` by setting `derivationArgs`; note that variables set in this manner will be set when the shell script is _built,_ not when it's run.
Runtime environment variables can be set with the `runtimeEnv` argument.
For example, the following shell application can refer to `curl` directly, rather than needing to write `${curl}/bin/curl`:
```nix
writeShellApplication {
@ -164,10 +523,6 @@ writeShellApplication {
}
```
Unlike with normal `writeShellScriptBin`, there is no need to manually write out `${curl}/bin/curl`, setting the PATH
was handled by `writeShellApplication`. Moreover, the script is being checked with `shellcheck` for more strict
validation.
## `symlinkJoin` {#trivial-builder-symlinkJoin}
This can be used to put many derivations into the same directory structure. It works by creating a new derivation and adding symlinks to each of the paths listed. It expects two arguments, `name`, and `paths`. `name` is the name used in the Nix store path for the created derivation. `paths` is a list of paths that will be symlinked. These paths can be to Nix store derivations or any other subdirectory contained within.

1
doc/default.nix
View File

@ -25,6 +25,7 @@ let
{ name = "gvariant"; description = "GVariant formatted string serialization functions"; }
{ name = "customisation"; description = "Functions to customise (derivation-related) functions, derivatons, or attribute sets"; }
{ name = "meta"; description = "functions for derivation metadata"; }
{ name = "derivations"; description = "miscellaneous derivation-specific functions"; }
];
};

2
doc/doc-support/lib-function-docs.nix
View File

@ -29,7 +29,7 @@ stdenv.mkDerivation {
mkdir -p "$out"
cat > "$out/index.md" << 'EOF'
```{=include=} sections
```{=include=} sections auto-id-prefix=auto-generated
EOF
${lib.concatMapStrings ({ name, baseName ? name, description }: ''

2
doc/hooks/installShellFiles.section.md
View File

@ -2,7 +2,7 @@
This hook helps with installing manpages and shell completion files. It exposes 2 shell functions `installManPage` and `installShellCompletion` that can be used from your `postInstall` hook.
The `installManPage` function takes one or more paths to manpages to install. The manpages must have a section suffix, and may optionally be compressed (with `.gz` suffix). This function will place them into the correct directory.
The `installManPage` function takes one or more paths to manpages to install. The manpages must have a section suffix, and may optionally be compressed (with `.gz` suffix). This function will place them into the correct `share/man/man<section>/` directory, in [`outputMan`](#outputman).
The `installShellCompletion` function takes one or more paths to shell completion files. By default it will autodetect the shell type from the completion file extension, but you may also specify it by passing one of `--bash`, `--fish`, or `--zsh`. These flags apply to all paths listed after them (up until another shell flag is given). Each path may also have a custom installation name provided by providing a flag `--name NAME` before the path. If this flag is not provided, zsh completions will be renamed automatically such that `foobar.zsh` becomes `_foobar`. A root name may be provided for all paths using the flag `--cmd NAME`; this synthesizes the appropriate name depending on the shell (e.g. `--cmd foo` will synthesize the name `foo.bash` for bash and `_foo` for zsh). The path may also be a fifo or named fd (such as produced by `<(cmd)`), in which case the shell and name must be provided.

1
doc/hooks/postgresql-test-hook.section.md
View File

@ -45,6 +45,7 @@ Bash-only variables:
- `postgresqlTestSetupCommands`: bash commands to run after database start, defaults to running `$postgresqlTestSetupSQL` as database administrator.
- `postgresqlEnableTCP`: set to `1` to enable TCP listening. Flaky; not recommended.
- `postgresqlStartCommands`: defaults to `pg_ctl start`.
- `postgresqlExtraSettings`: Additional configuration to add to `postgresql.conf`
## Hooks {#sec-postgresqlTestHook-hooks}

2
doc/hooks/python.section.md
View File

@ -1,3 +1,3 @@
# Python {#setup-hook-python}
Adds the `lib/${python.libPrefix}/site-packages` subdirectory of each build input to the `PYTHONPATH` environment variable.
Adds the `python.sitePackages` subdirectory (i.e. `lib/pythonX.Y/site-packages`) of each build input to the `PYTHONPATH` environment variable.

2
doc/languages-frameworks/beam.section.md
View File

@ -216,7 +216,7 @@ in packages.mixRelease {
Setup will require the following steps:
- Move your secrets to runtime environment variables. For more information refer to the [runtime.exs docs](https://hexdocs.pm/mix/Mix.Tasks.Release.html#module-runtime-configuration). On a fresh Phoenix build that would mean that both `DATABASE_URL` and `SECRET_KEY` need to be moved to `runtime.exs`.
- `cd assets` and `nix-shell -p node2nix --run node2nix --development` will generate a Nix expression containing your frontend dependencies
- `cd assets` and `nix-shell -p node2nix --run "node2nix --development"` will generate a Nix expression containing your frontend dependencies
- commit and push those changes
- you can now `nix-build .`
- To run the release, set the `RELEASE_TMP` environment variable to a directory that your program has write access to. It will be used to store the BEAM settings.

94
doc/languages-frameworks/dart.section.md
View File

@ -4,22 +4,33 @@
The function `buildDartApplication` builds Dart applications managed with pub.
It fetches its Dart dependencies automatically through `fetchDartDeps`, and (through a series of hooks) builds and installs the executables specified in the pubspec file. The hooks can be used in other derivations, if needed. The phases can also be overridden to do something different from installing binaries.
It fetches its Dart dependencies automatically through `pub2nix`, and (through a series of hooks) builds and installs the executables specified in the pubspec file. The hooks can be used in other derivations, if needed. The phases can also be overridden to do something different from installing binaries.
If you are packaging a Flutter desktop application, use [`buildFlutterApplication`](#ssec-dart-flutter) instead.
`vendorHash`: is the hash of the output of the dependency fetcher derivation. To obtain it, set it to `lib.fakeHash` (or omit it) and run the build ([more details here](#sec-source-hashes)).
`pubspecLock` is the parsed pubspec.lock file. pub2nix uses this to download required packages.
This can be converted to JSON from YAML with something like `yq . pubspec.lock`, and then read by Nix.
If the upstream source is missing a `pubspec.lock` file, you'll have to vendor one and specify it using `pubspecLockFile`. If it is needed, one will be generated for you and printed when attempting to build the derivation.
Alternatively, `autoPubspecLock` can be used instead, and set to a path to a regular `pubspec.lock` file. This relies on import-from-derivation, and is not permitted in Nixpkgs, but can be useful at other times.
The `depsListFile` must always be provided when packaging in Nixpkgs. It will be generated and printed if the derivation is attempted to be built without one. Alternatively, `autoDepsList` may be set to `true` only when outside of Nixpkgs, as it relies on import-from-derivation.
::: {.warning}
When using `autoPubspecLock` with a local source directory, make sure to use a
concatenation operator (e.g. `autoPubspecLock = src + "/pubspec.lock";`), and
not string interpolation.
String interpolation will copy your entire source directory to the Nix store and
use its store path, meaning that unrelated changes to your source tree will
cause the generated `pubspec.lock` derivation to rebuild!
:::
If the package has Git package dependencies, the hashes must be provided in the `gitHashes` set. If a hash is missing, an error message prompting you to add it will be shown.
The `dart` commands run can be overridden through `pubGetScript` and `dartCompileCommand`, you can also add flags using `dartCompileFlags` or `dartJitFlags`.
Dart supports multiple [outputs types](https://dart.dev/tools/dart-compile#types-of-output), you can choose between them using `dartOutputType` (defaults to `exe`). If you want to override the binaries path or the source path they come from, you can use `dartEntryPoints`. Outputs that require a runtime will automatically be wrapped with the relevant runtime (`dartaotruntime` for `aot-snapshot`, `dart run` for `jit-snapshot` and `kernel`, `node` for `js`), this can be overridden through `dartRuntimeCommand`.
```nix
{ buildDartApplication, fetchFromGitHub }:
{ lib, buildDartApplication, fetchFromGitHub }:
buildDartApplication rec {
pname = "dart-sass";
@ -32,12 +43,55 @@ buildDartApplication rec {
hash = "sha256-U6enz8yJcc4Wf8m54eYIAnVg/jsGi247Wy8lp1r1wg4=";
};
pubspecLockFile = ./pubspec.lock;
depsListFile = ./deps.json;
vendorHash = "sha256-Atm7zfnDambN/BmmUf4BG0yUz/y6xWzf0reDw3Ad41s=";
pubspecLock = lib.importJSON ./pubspec.lock.json;
}
```
### Patching dependencies {#ssec-dart-applications-patching-dependencies}
Some Dart packages require patches or build environment changes. Package derivations can be customised with the `customSourceBuilders` argument.
A collection of such customisations can be found in Nixpkgs, in the `development/compilers/dart/package-source-builders` directory.
This allows fixes for packages to be shared between all applications that use them. It is strongly recommended to add to this collection instead of including fixes in your application derivation itself.
### Running executables from dev_dependencies {#ssec-dart-applications-build-tools}
Many Dart applications require executables from the `dev_dependencies` section in `pubspec.yaml` to be run before building them.
This can be done in `preBuild`, in one of two ways:
1. Packaging the tool with `buildDartApplication`, adding it to Nixpkgs, and running it like any other application
2. Running the tool from the package cache
Of these methods, the first is recommended when using a tool that does not need
to be of a specific version.
For the second method, the `packageRun` function from the `dartConfigHook` can be used.
This is an alternative to `dart run` that does not rely on Pub.
e.g., for `build_runner`:
```bash
packageRun build_runner build
```
Do _not_ use `dart run <package_name>`, as this will attempt to download dependencies with Pub.
### Usage with nix-shell {#ssec-dart-applications-nix-shell}
#### Using dependencies from the Nix store {#ssec-dart-applications-nix-shell-deps}
As `buildDartApplication` provides dependencies instead of `pub get`, Dart needs to be explicitly told where to find them.
Run the following commands in the source directory to configure Dart appropriately.
Do not use `pub` after doing so; it will download the dependencies itself and overwrite these changes.
```bash
cp --no-preserve=all "$pubspecLockFilePath" pubspec.lock
mkdir -p .dart_tool && cp --no-preserve=all "$packageConfig" .dart_tool/package_config.json
```
## Flutter applications {#ssec-dart-flutter}
The function `buildFlutterApplication` builds Flutter applications.
@ -49,7 +103,10 @@ See the [Dart documentation](#ssec-dart-applications) for more details on requir
flutter.buildFlutterApplication {
pname = "firmware-updater";
version = "unstable-2023-04-30";
version = "0-unstable-2023-04-30";
# To build for the Web, use the targetFlutterPlatform argument.
# targetFlutterPlatform = "web";
src = fetchFromGitHub {
owner = "canonical";
@ -59,8 +116,21 @@ flutter.buildFlutterApplication {
fetchSubmodules = true;
};
pubspecLockFile = ./pubspec.lock;
depsListFile = ./deps.json;
vendorHash = "sha256-cdMO+tr6kYiN5xKXa+uTMAcFf2C75F3wVPrn21G4QPQ=";
pubspecLock = lib.importJSON ./pubspec.lock.json;
}
```
### Usage with nix-shell {#ssec-dart-flutter-nix-shell}
Flutter-specific `nix-shell` usage notes are included here. See the [Dart documentation](#ssec-dart-applications-nix-shell) for general `nix-shell` instructions.
#### Entering the shell {#ssec-dart-flutter-nix-shell-enter}
By default, dependencies for only the `targetFlutterPlatform` are available in the
build environment. This is useful for keeping closures small, but be problematic
during development. It's common, for example, to build Web apps for Linux during
development to take advantage of native features such as stateful hot reload.
To enter a shell with all the usual target platforms available, use the `multiShell` attribute.
e.g. `nix-shell '<nixpkgs>' -A fluffychat-web.multiShell`.

50
doc/languages-frameworks/dotnet.section.md
View File

@ -93,7 +93,11 @@ The `dotnetCorePackages.sdk` contains both a runtime and the full sdk of a given
To package Dotnet applications, you can use `buildDotnetModule`. This has similar arguments to `stdenv.mkDerivation`, with the following additions:
* `projectFile` is used for specifying the dotnet project file, relative to the source root. These have `.sln` (entire solution) or `.csproj` (single project) file extensions. This can be a list of multiple projects as well. When omitted, will attempt to find and build the solution (`.sln`). If running into problems, make sure to set it to a file (or a list of files) with the `.csproj` extension - building applications as entire solutions is not fully supported by the .NET CLI.
* `nugetDeps` takes either a path to a `deps.nix` file, or a derivation. The `deps.nix` file can be generated using the script attached to `passthru.fetch-deps`. This file can also be generated manually using `nuget-to-nix` tool, which is available in nixpkgs. If the argument is a derivation, it will be used directly and assume it has the same output as `mkNugetDeps`.
* `nugetDeps` takes either a path to a `deps.nix` file, or a derivation. The `deps.nix` file can be generated using the script attached to `passthru.fetch-deps`. If the argument is a derivation, it will be used directly and assume it has the same output as `mkNugetDeps`.
::: {.note}
For more detail about managing the `deps.nix` file, see [Generating and updating NuGet dependencies](#generating-and-updating-nuget-dependencies)
:::
* `packNupkg` is used to pack project as a `nupkg`, and installs it to `$out/share`. If set to `true`, the derivation can be used as a dependency for another dotnet project by adding it to `projectReferences`.
* `projectReferences` can be used to resolve `ProjectReference` project items. Referenced projects can be packed with `buildDotnetModule` by setting the `packNupkg = true` attribute and passing a list of derivations to `projectReferences`. Since we are sharing referenced projects as NuGets they must be added to csproj/fsproj files as `PackageReference` as well.
For example, your project has a local dependency:
@ -144,7 +148,7 @@ in buildDotnetModule rec {
projectReferences = [ referencedProject ]; # `referencedProject` must contain `nupkg` in the folder structure.
dotnet-sdk = dotnetCorePackages.sdk_6.0;
dotnet-sdk = dotnetCorePackages.sdk_6_0;
dotnet-runtime = dotnetCorePackages.runtime_6_0;
executables = [ "foo" ]; # This wraps "$out/lib/$pname/foo" to `$out/bin/foo`.
@ -156,6 +160,8 @@ in buildDotnetModule rec {
}
```
Keep in mind that you can tag the [`@NixOS/dotnet`](https://github.com/orgs/nixos/teams/dotnet) team for help and code review.
## Dotnet global tools {#dotnet-global-tools}
[.NET Global tools](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools) are a mechanism provided by the dotnet CLI to install .NET binaries from Nuget packages.
@ -212,5 +218,43 @@ buildDotnetGlobalTool {
};
}
```
## Generating and updating NuGet dependencies {#generating-and-updating-nuget-dependencies}
First, restore the packages to the `out` directory, ensure you have cloned
the upstream repository and you are inside it.
```bash
$ dotnet restore --packages out
Determining projects to restore...
Restored /home/lychee/Celeste64/Celeste64.csproj (in 1.21 sec).
```
Next, use `nuget-to-nix` tool provided in nixpkgs to generate a lockfile to `deps.nix` from
the packages inside the `out` directory.
```bash
$ nuget-to-nix out > deps.nix
```
Which `nuget-to-nix` will generate an output similar to below
```
{ fetchNuGet }: [
(fetchNuGet { pname = "FosterFramework"; version = "0.1.15-alpha"; sha256 = "0pzsdfbsfx28xfqljcwy100xhbs6wyx0z1d5qxgmv3l60di9xkll"; })
(fetchNuGet { pname = "Microsoft.AspNetCore.App.Runtime.linux-x64"; version = "8.0.1"; sha256 = "1gjz379y61ag9whi78qxx09bwkwcznkx2mzypgycibxk61g11da1"; })
(fetchNuGet { pname = "Microsoft.NET.ILLink.Tasks"; version = "8.0.1"; sha256 = "1drbgqdcvbpisjn8mqfgba1pwb6yri80qc4mfvyczqwrcsj5k2ja"; })
(fetchNuGet { pname = "Microsoft.NETCore.App.Runtime.linux-x64"; version = "8.0.1"; sha256 = "1g5b30f4l8a1zjjr3b8pk9mcqxkxqwa86362f84646xaj4iw3a4d"; })
(fetchNuGet { pname = "SharpGLTF.Core"; version = "1.0.0-alpha0031"; sha256 = "0ln78mkhbcxqvwnf944hbgg24vbsva2jpih6q3x82d3h7rl1pkh6"; })
(fetchNuGet { pname = "SharpGLTF.Runtime"; version = "1.0.0-alpha0031"; sha256 = "0lvb3asi3v0n718qf9y367km7qpkb9wci38y880nqvifpzllw0jg"; })
(fetchNuGet { pname = "Sledge.Formats"; version = "1.2.2"; sha256 = "1y0l66m9rym0p1y4ifjlmg3j9lsmhkvbh38frh40rpvf1axn2dyh"; })
(fetchNuGet { pname = "Sledge.Formats.Map"; version = "1.1.5"; sha256 = "1bww60hv9xcyxpvkzz5q3ybafdxxkw6knhv97phvpkw84pd0jil6"; })
(fetchNuGet { pname = "System.Numerics.Vectors"; version = "4.5.0"; sha256 = "1kzrj37yzawf1b19jq0253rcs8hsq1l2q8g69d7ipnhzb0h97m59"; })
]
```
Finally, you move the `deps.nix` file to the appropriate location to be used by `nugetDeps`, then you're all set!
If you ever need to update the dependencies of a package, you instead do
* `nix-build -A package.fetch-deps` to generate the update script for `package`
* Run `./result deps.nix` to regenerate the lockfile to `deps.nix`, keep in mind if a location isn't provided, it will write to a temporary path instead
* Finally, move the file where needed and look at its contents to confirm it has updated the dependencies.
When packaging a new .NET application in nixpkgs, you can tag the [`@NixOS/dotnet`](https://github.com/orgs/nixos/teams/dotnet) team for help and code review.

6
doc/languages-frameworks/emscripten.section.md
View File

@ -86,9 +86,9 @@ One advantage is that when `pkgs.zlib` is updated, it will automatically update
postPatch = pkgs.lib.optionalString pkgs.stdenv.isDarwin ''
substituteInPlace configure \
--replace '/usr/bin/libtool' 'ar' \
--replace 'AR="libtool"' 'AR="ar"' \
--replace 'ARFLAGS="-o"' 'ARFLAGS="-r"'
--replace-fail '/usr/bin/libtool' 'ar' \
--replace-fail 'AR="libtool"' 'AR="ar"' \
--replace-fail 'ARFLAGS="-o"' 'ARFLAGS="-r"'
'';
})
```

149
doc/languages-frameworks/go.section.md
View File

@ -1,26 +1,41 @@
# Go {#sec-language-go}
## Go modules {#ssec-language-go}
## Building Go modules with `buildGoModule` {#ssec-language-go}
The function `buildGoModule` builds Go programs managed with Go modules. It builds a [Go Modules](https://github.com/golang/go/wiki/Modules) through a two phase build:
The function `buildGoModule` builds Go programs managed with Go modules. It builds [Go Modules](https://github.com/golang/go/wiki/Modules) through a two phase build:
- An intermediate fetcher derivation. This derivation will be used to fetch all of the dependencies of the Go module.
- An intermediate fetcher derivation called `goModules`. This derivation will be used to fetch all the dependencies of the Go module.
- A final derivation will use the output of the intermediate derivation to build the binaries and produce the final output.
### Attributes of `buildGoModule` {#buildgomodule-parameters}
The `buildGoModule` function accepts the following parameters in addition to the [attributes accepted by both Go builders](#ssec-go-common-attributes):
- `vendorHash`: is the hash of the output of the intermediate fetcher derivation (the dependencies of the Go modules).
`vendorHash` can be set to `null`.
In that case, rather than fetching the dependencies, the dependencies already vendored in the `vendor` directory of the source repo will be used.
To avoid updating this field when dependencies change, run `go mod vendor` in your source repo and set `vendorHash = null;`.
You can read more about [vendoring in the Go documentation](https://go.dev/ref/mod#vendoring).
To obtain the actual hash, set `vendorHash = lib.fakeHash;` and run the build ([more details here](#sec-source-hashes)).
- `proxyVendor`: If `true`, the intermediate fetcher downloads dependencies from the
[Go module proxy](https://go.dev/ref/mod#module-proxy) (using `go mod download`) instead of vendoring them. The resulting
[module cache](https://go.dev/ref/mod#module-cache) is then passed to the final derivation.
This is useful if your code depends on C code and `go mod tidy` does not include the needed sources to build or
if any dependency has case-insensitive conflicts which will produce platform-dependent `vendorHash` checksums.
Defaults to `false`.
- `modPostBuild`: Shell commands to run after the build of the goModules executes `go mod vendor`, and before calculating fixed output derivation's `vendorHash`.
Note that if you change this attribute, you need to update `vendorHash` attribute.
- `modRoot`: The root directory of the Go module that contains the `go.mod` file.
Defaults to `./`, which is the root of `src`.
### Example for `buildGoModule` {#ex-buildGoModule}
In the following is an example expression using `buildGoModule`, the following arguments are of special significance to the function:
- `vendorHash`: is the hash of the output of the intermediate fetcher derivation.
`vendorHash` can also be set to `null`.
In that case, rather than fetching the dependencies and vendoring them, the dependencies vendored in the source repo will be used.
To avoid updating this field when dependencies change, run `go mod vendor` in your source repo and set `vendorHash = null;`
To obtain the actual hash, set `vendorHash = lib.fakeHash;` and run the build ([more details here](#sec-source-hashes)).
- `proxyVendor`: Fetches (go mod download) and proxies the vendor directory. This is useful if your code depends on c code and go mod tidy does not include the needed sources to build or if any dependency has case-insensitive conflicts which will produce platform-dependent `vendorHash` checksums.
- `modPostBuild`: Shell commands to run after the build of the goModules executes `go mod vendor`, and before calculating fixed output derivation's `vendorHash`. Note that if you change this attribute, you need to update `vendorHash` attribute.
The following is an example expression using `buildGoModule`:
```nix
pet = buildGoModule rec {
@ -51,7 +66,7 @@ The function `buildGoPackage` builds legacy Go programs, not supporting Go modul
### Example for `buildGoPackage` {#example-for-buildgopackage}
In the following is an example expression using buildGoPackage, the following arguments are of special significance to the function:
In the following is an example expression using `buildGoPackage`, the following arguments are of special significance to the function:
- `goPackagePath` specifies the package's canonical Go import path.
- `goDeps` is where the Go dependencies of a Go program are listed as a list of package source identified by Go import path. It could be imported as a separate `deps.nix` file for readability. The dependency data structure is described below.
@ -103,7 +118,7 @@ The `goDeps` attribute can be imported from a separate `nix` file that defines w
]
```
To extract dependency information from a Go package in automated way use [go2nix](https://github.com/kamilchm/go2nix). It can produce complete derivation and `goDeps` file for Go programs.
To extract dependency information from a Go package in automated way use [go2nix (deprecated)](https://github.com/kamilchm/go2nix). It can produce complete derivation and `goDeps` file for Go programs.
You may use Go packages installed into the active Nix profiles by adding the following to your ~/.bashrc:
@ -113,7 +128,7 @@ for p in $NIX_PROFILES; do
done
```
## Attributes used by the builders {#ssec-go-common-attributes}
## Attributes used by both builders {#ssec-go-common-attributes}
Many attributes [controlling the build phase](#variables-controlling-the-build-phase) are respected by both `buildGoModule` and `buildGoPackage`. Note that `buildGoModule` reads the following attributes also when building the `vendor/` goModules fixed output derivation as well:
@ -124,11 +139,18 @@ Many attributes [controlling the build phase](#variables-controlling-the-build-p
- [`postPatch`](#var-stdenv-postPatch)
- [`preBuild`](#var-stdenv-preBuild)
To control test execution of the build derivation, the following attributes are of interest:
- [`checkInputs`](#var-stdenv-checkInputs)
- [`preCheck`](#var-stdenv-preCheck)
- [`checkFlags`](#var-stdenv-checkFlags)
In addition to the above attributes, and the many more variables respected also by `stdenv.mkDerivation`, both `buildGoModule` and `buildGoPackage` respect Go-specific attributes that tweak them to behave slightly differently:
### `ldflags` {#var-go-ldflags}
Arguments to pass to the Go linker tool via the `-ldflags` argument of `go build`. The most common use case for this argument is to make the resulting executable aware of its own version. For example:
A string list of flags to pass to the Go linker tool via the `-ldflags` argument of `go build`. Possible values can be retrieved by running `go tool link --help`.
The most common use case for this argument is to make the resulting executable aware of its own version by injecting the value of string variable using the `-X` flag. For example:
```nix
ldflags = [
@ -139,7 +161,7 @@ Arguments to pass to the Go linker tool via the `-ldflags` argument of `go build
### `tags` {#var-go-tags}
Arguments to pass to the Go via the `-tags` argument of `go build`. For example:
A string list of [Go build tags (also called build constraints)](https://pkg.go.dev/cmd/go#hdr-Build_constraints) that are passed via the `-tags` argument of `go build`. These constraints control whether Go files from the source should be included in the build. For example:
```nix
tags = [
@ -148,18 +170,101 @@ Arguments to pass to the Go via the `-tags` argument of `go build`. For example:
];
```
Tags can also be set conditionally:
```nix
tags = [ "production" ] ++ lib.optionals withSqlite [ "sqlite" ];
```
### `deleteVendor` {#var-go-deleteVendor}
Removes the pre-existing vendor directory. This should only be used if the dependencies included in the vendor folder are broken or incomplete.
If set to `true`, removes the pre-existing vendor directory. This should only be used if the dependencies included in the vendor folder are broken or incomplete.
### `subPackages` {#var-go-subPackages}
Specified as a string or list of strings. Limits the builder from building child packages that have not been listed. If `subPackages` is not specified, all child packages will be built.
Many Go projects keep the main package in a `cmd` directory.
Following example could be used to only build the example-cli and example-server binaries:
```nix
subPackages = [
"cmd/example-cli"
"cmd/example-server"
];
```
### `excludedPackages` {#var-go-excludedPackages}
Specified as a string or list of strings. Causes the builder to skip building child packages that match any of the provided values. If `excludedPackages` is not specified, all child packages will be built.
Specified as a string or list of strings. Causes the builder to skip building child packages that match any of the provided values.
### `CGO_ENABLED` {#var-go-CGO_ENABLED}
When set to `0`, the [cgo](https://pkg.go.dev/cmd/cgo) command is disabled. As consequence, the build
program can't link against C libraries anymore, and the resulting binary is statically linked.
When building with CGO enabled, Go will likely link some packages from the Go standard library against C libraries,
even when the target code does not explicitly call into C dependencies. With `CGO_ENABLED = 0;`, Go
will always use the Go native implementation of these internal packages. For reference see
[net](https://pkg.go.dev/net#hdr-Name_Resolution) and [os/user](https://pkg.go.dev/os/user#pkg-overview) packages.
Notice that the decision whether these packages should use native Go implementation or not can also be controlled
on a per package level using build tags (`tags`). In case CGO is disabled, these tags have no additional effect.
When a Go program depends on C libraries, place those dependencies in `buildInputs`:
```nix
buildInputs = [
libvirt
libxml2
];
```
`CGO_ENABLED` defaults to `1`.
### `enableParallelBuilding` {#var-go-enableParallelBuilding}
Whether builds and tests should run in parallel.
Defaults to `true`.
### `allowGoReference` {#var-go-allowGoReference}
Whether the build result should be allowed to contain references to the Go tool chain. This might be needed for programs that are coupled with the compiler, but shouldn't be set without a good reason.
Defaults to `false`
## Controlling the Go environment {#ssec-go-environment}
The Go build can be further tweaked by setting environment variables. In most cases, this isn't needed. Possible values can be found in the [Go documentation of accepted environment variables](https://pkg.go.dev/cmd/go#hdr-Environment_variables). Notice that some of these flags are set by the builder itself and should not be set explicitly. If in doubt, grep the implementation of the builder.
## Skipping tests {#ssec-skip-go-tests}
`buildGoModule` runs tests by default. Failing tests can be disabled using the `checkFlags` parameter.
This is done with the [`-skip` or `-run`](https://pkg.go.dev/cmd/go#hdr-Testing_flags) flags of the `go test` command.
For example, only a selection of tests could be run with:
```nix
# -run and -skip accept regular expressions
checkFlags = [
"-run=^Test(Simple|Fast)$"
];
```
If a larger amount of tests should be skipped, the following pattern can be used:
```nix
checkFlags =
let
# Skip tests that require network access
skippedTests = [
"TestNetwork"
"TestDatabase/with_mysql" # exclude only the subtest
"TestIntegration"
];
in
[ "-skip=^${builtins.concatStringsSep "$|^" skippedTests}$" ];
```
To disable tests altogether, set `doCheck = false;`.
`buildGoPackage` does not execute tests by default.

101
doc/languages-frameworks/haskell.section.md
View File

@ -70,39 +70,42 @@ compilers like this:
```console
$ nix-env -f '<nixpkgs>' -qaP -A haskell.compiler
haskell.compiler.ghc810 ghc-8.10.7
haskell.compiler.ghc88 ghc-8.8.4
haskell.compiler.ghc90 ghc-9.0.2
haskell.compiler.ghc924 ghc-9.2.4
haskell.compiler.ghc925 ghc-9.2.5
haskell.compiler.ghc926 ghc-9.2.6
haskell.compiler.ghc92 ghc-9.2.7
haskell.compiler.ghc942 ghc-9.4.2
haskell.compiler.ghc943 ghc-9.4.3
haskell.compiler.ghc94 ghc-9.4.4
haskell.compiler.ghcHEAD ghc-9.7.20221224
haskell.compiler.ghc8102Binary ghc-binary-8.10.2
haskell.compiler.ghc8102BinaryMinimal ghc-binary-8.10.2
haskell.compiler.ghc8107BinaryMinimal ghc-binary-8.10.7
haskell.compiler.ghc927 ghc-9.2.7
haskell.compiler.ghc92 ghc-9.2.8
haskell.compiler.ghc945 ghc-9.4.5
haskell.compiler.ghc946 ghc-9.4.6
haskell.compiler.ghc947 ghc-9.4.7
haskell.compiler.ghc94 ghc-9.4.8
haskell.compiler.ghc963 ghc-9.6.3
haskell.compiler.ghc96 ghc-9.6.4
haskell.compiler.ghc98 ghc-9.8.1
haskell.compiler.ghcHEAD ghc-9.9.20231121
haskell.compiler.ghc8107Binary ghc-binary-8.10.7
haskell.compiler.ghc865Binary ghc-binary-8.6.5
haskell.compiler.ghc924Binary ghc-binary-9.2.4
haskell.compiler.ghc924BinaryMinimal ghc-binary-9.2.4
haskell.compiler.integer-simple.ghc810 ghc-integer-simple-8.10.7
haskell.compiler.integer-simple.ghc8107 ghc-integer-simple-8.10.7
haskell.compiler.integer-simple.ghc88 ghc-integer-simple-8.8.4
haskell.compiler.integer-simple.ghc884 ghc-integer-simple-8.8.4
haskell.compiler.integer-simple.ghc810 ghc-integer-simple-8.10.7
haskell.compiler.native-bignum.ghc90 ghc-native-bignum-9.0.2
haskell.compiler.native-bignum.ghc902 ghc-native-bignum-9.0.2
haskell.compiler.native-bignum.ghc924 ghc-native-bignum-9.2.4
haskell.compiler.native-bignum.ghc925 ghc-native-bignum-9.2.5
haskell.compiler.native-bignum.ghc926 ghc-native-bignum-9.2.6
haskell.compiler.native-bignum.ghc92 ghc-native-bignum-9.2.7
haskell.compiler.native-bignum.ghc927 ghc-native-bignum-9.2.7
haskell.compiler.native-bignum.ghc942 ghc-native-bignum-9.4.2
haskell.compiler.native-bignum.ghc943 ghc-native-bignum-9.4.3
haskell.compiler.native-bignum.ghc94 ghc-native-bignum-9.4.4
haskell.compiler.native-bignum.ghc944 ghc-native-bignum-9.4.4
haskell.compiler.native-bignum.ghcHEAD ghc-native-bignum-9.7.20221224
haskell.compiler.native-bignum.ghc92 ghc-native-bignum-9.2.8
haskell.compiler.native-bignum.ghc928 ghc-native-bignum-9.2.8
haskell.compiler.native-bignum.ghc945 ghc-native-bignum-9.4.5
haskell.compiler.native-bignum.ghc946 ghc-native-bignum-9.4.6
haskell.compiler.native-bignum.ghc947 ghc-native-bignum-9.4.7
haskell.compiler.native-bignum.ghc94 ghc-native-bignum-9.4.8
haskell.compiler.native-bignum.ghc948 ghc-native-bignum-9.4.8
haskell.compiler.native-bignum.ghc963 ghc-native-bignum-9.6.3
haskell.compiler.native-bignum.ghc96 ghc-native-bignum-9.6.4
haskell.compiler.native-bignum.ghc964 ghc-native-bignum-9.6.4
haskell.compiler.native-bignum.ghc98 ghc-native-bignum-9.8.1
haskell.compiler.native-bignum.ghc981 ghc-native-bignum-9.8.1
haskell.compiler.native-bignum.ghcHEAD ghc-native-bignum-9.9.20231121
haskell.compiler.ghcjs ghcjs-8.10.7
```
@ -1226,10 +1229,12 @@ in
in
{
haskell = lib.recursiveUpdate prev.haskell {
compiler.${ghcName} = prev.haskell.compiler.${ghcName}.override {
# Unfortunately, the GHC setting is named differently for historical reasons
enableProfiledLibs = enableProfiling;
haskell = prev.haskell // {
compiler = prev.haskell.compiler // {
${ghcName} = prev.haskell.compiler.${ghcName}.override {
# Unfortunately, the GHC setting is named differently for historical reasons
enableProfiledLibs = enableProfiling;
};
};
};
})
@ -1241,31 +1246,33 @@ in
in
{
haskell = lib.recursiveUpdate prev.haskell {
packages.${ghcName} = prev.haskell.packages.${ghcName}.override {
overrides = hfinal: hprev: {
mkDerivation = args: hprev.mkDerivation (args // {
# Since we are forcing our ideas upon mkDerivation, this change will
# affect every package in the package set.
enableLibraryProfiling = enableProfiling;
haskell = prev.haskell // {
packages = prev.haskell.packages // {
${ghcName} = prev.haskell.packages.${ghcName}.override {
overrides = hfinal: hprev: {
mkDerivation = args: hprev.mkDerivation (args // {
# Since we are forcing our ideas upon mkDerivation, this change will
# affect every package in the package set.
enableLibraryProfiling = enableProfiling;
# To actually use profiling on an executable, executable profiling
# needs to be enabled for the executable you want to profile. You
# can either do this globally or…
enableExecutableProfiling = enableProfiling;
});
# To actually use profiling on an executable, executable profiling
# needs to be enabled for the executable you want to profile. You
# can either do this globally or…
enableExecutableProfiling = enableProfiling;
});
# …only for the package that contains an executable you want to profile.
# That saves on unnecessary rebuilds for packages that you only depend
# on for their library, but also contain executables (e.g. pandoc).
my-executable = haskellLib.enableExecutableProfiling hprev.my-executable;
# …only for the package that contains an executable you want to profile.
# That saves on unnecessary rebuilds for packages that you only depend
# on for their library, but also contain executables (e.g. pandoc).
my-executable = haskellLib.enableExecutableProfiling hprev.my-executable;
# If you are disabling profiling to save on build time, but want to
# retain the ability to substitute from the binary cache. Drop the
# override for mkDerivation above and instead have an override like
# this for the specific packages you are building locally and want
# to make cheaper to build.
my-library = haskellLib.disableLibraryProfiling hprev.my-library;
# If you are disabling profiling to save on build time, but want to
# retain the ability to substitute from the binary cache. Drop the
# override for mkDerivation above and instead have an override like
# this for the specific packages you are building locally and want
# to make cheaper to build.
my-library = haskellLib.disableLibraryProfiling hprev.my-library;
};
};
};
};

47
doc/languages-frameworks/idris2.section.md Normal file
View File

@ -0,0 +1,47 @@
# Idris2 {#sec-idris2}
In addition to exposing the Idris2 compiler itself, Nixpkgs exposes an `idris2Packages.buildIdris` helper to make it a bit more ergonomic to build Idris2 executables or libraries.
The `buildIdris` function takes an attribute set that defines at a minimum the `src` and `ipkgName` of the package to be built and any `idrisLibraries` required to build it. The `src` is the same source you're familiar with and the `ipkgName` must be the name of the `ipkg` file for the project (omitting the `.ipkg` extension). The `idrisLibraries` is a list of other library derivations created with `buildIdris`. You can optionally specify other derivation properties as needed but sensible defaults for `configurePhase`, `buildPhase`, and `installPhase` are provided.
Importantly, `buildIdris` does not create a single derivation but rather an attribute set with two properties: `executable` and `library`. The `executable` property is a derivation and the `library` property is a function that will return a derivation for the library with or without source code included. Source code need not be included unless you are aiming to use IDE or LSP features that are able to jump to definitions within an editor.
A simple example of a fully packaged library would be the [`LSP-lib`](https://github.com/idris-community/LSP-lib) found in the `idris-community` GitHub organization.
```nix
{ fetchFromGitHub, idris2Packages }:
let lspLibPkg = idris2Packages.buildIdris {
ipkgName = "lsp-lib";
src = fetchFromGitHub {
owner = "idris-community";
repo = "LSP-lib";
rev = "main";
hash = "sha256-EvSyMCVyiy9jDZMkXQmtwwMoLaem1GsKVFqSGNNHHmY=";
};
idrisLibraries = [ ];
};
in lspLibPkg.library
```
The above results in a derivation with the installed library results (with sourcecode).
A slightly more involved example of a fully packaged executable would be the [`idris2-lsp`](https://github.com/idris-community/idris2-lsp) which is an Idris2 language server that uses the `LSP-lib` found above.
```nix
{ callPackage, fetchFromGitHub, idris2Packages }:
# Assuming the previous example lives in `lsp-lib.nix`:
let lspLib = callPackage ./lsp-lib.nix { };
lspPkg = idris2Packages.buildIdris {
ipkgName = "idris2-lsp";
src = fetchFromGitHub {
owner = "idris-community";
repo = "idris2-lsp";
rev = "main";
hash = "sha256-vQTzEltkx7uelDtXOHc6QRWZ4cSlhhm5ziOqWA+aujk=";
};
idrisLibraries = [(idris2Packages.idris2Api { }) (lspLib { })];
};
in lspPkg.executable
```
The above uses the default value of `withSource = false` for both of the two required Idris libraries that the `idris2-lsp` executable depends on. `idris2Api` in the above derivation comes built in with `idris2Packages`. This library exposes many of the otherwise internal APIs of the Idris2 compiler.

1
doc/languages-frameworks/index.md
View File

@ -21,6 +21,7 @@ go.section.md
haskell.section.md
hy.section.md
idris.section.md
idris2.section.md
ios.section.md
java.section.md
javascript.section.md

1
doc/languages-frameworks/javascript.section.md
View File

@ -354,6 +354,7 @@ mkYarnPackage rec {
- The `echo 9` steps comes from this answer: <https://stackoverflow.com/a/49139496>
- Exporting the headers in `npm_config_nodedir` comes from this issue: <https://github.com/nodejs/node-gyp/issues/1191#issuecomment-301243919>
- `offlineCache` (described [above](#javascript-yarn2nix-preparation)) must be specified to avoid [Import From Derivation](#ssec-import-from-derivation) (IFD) when used inside Nixpkgs.
## Outside Nixpkgs {#javascript-outside-nixpkgs}

5
doc/languages-frameworks/lua.section.md
View File

@ -215,6 +215,11 @@ install the package
environment variable and add dependent libraries to script's `LUA_PATH` and
`LUA_CPATH`.
It accepts as arguments:
* 'luarocksConfig': a nix value that directly maps to the luarocks config used during
the installation
By default `meta.platforms` is set to the same value as the interpreter unless overridden otherwise.
#### `buildLuaApplication` function {#buildluaapplication-function}

97
doc/languages-frameworks/python.section.md
View File

@ -7,7 +7,6 @@
| Package | Aliases | Interpreter |
|------------|-----------------|-------------|
| python27 | python2, python | CPython 2.7 |
| python38 | | CPython 3.8 |
| python39 | | CPython 3.9 |
| python310 | | CPython 3.10 |
| python311 | python3 | CPython 3.11 |
@ -60,7 +59,6 @@ sets are
* `pkgs.python27Packages`
* `pkgs.python3Packages`
* `pkgs.python38Packages`
* `pkgs.python39Packages`
* `pkgs.python310Packages`
* `pkgs.python311Packages`
@ -116,11 +114,11 @@ buildPythonPackage rec {
rm testing/test_argcomplete.py
'';
nativeBuildInputs = [
build-system = [
setuptools-scm
];
propagatedBuildInputs = [
dependencies = [
attrs
py
setuptools
@ -172,10 +170,10 @@ following are specific to `buildPythonPackage`:
variable in wrapped programs.
* `pyproject`: Whether the pyproject format should be used. When set to `true`,
`pypaBuildHook` will be used, and you can add the required build dependencies
from `build-system.requires` to `nativeBuildInputs`. Note that the pyproject
from `build-system.requires` to `build-system`. Note that the pyproject
format falls back to using `setuptools`, so you can use `pyproject = true`
even if the package only has a `setup.py`. When set to `false`, you can
use the existing [hooks](#setup-hooks0 or provide your own logic to build the
use the existing [hooks](#setup-hooks) or provide your own logic to build the
package. This can be useful for packages that don't support the pyproject
format. When unset, the legacy `setuptools` hooks are used for backwards
compatibility.
@ -206,17 +204,22 @@ build inputs (see "Specifying dependencies"). The following are of special
interest for Python packages, either because these are primarily used, or
because their behaviour is different:
* `nativeBuildInputs ? []`: Build-time only dependencies. Typically executables
as well as the items listed in `setup_requires`.
* `nativeBuildInputs ? []`: Build-time only dependencies. Typically executables.
* `build-system ? []`: Build-time only Python dependencies. Items listed in `build-system.requires`/`setup_requires`.
* `buildInputs ? []`: Build and/or run-time dependencies that need to be
compiled for the host machine. Typically non-Python libraries which are being
linked.
* `nativeCheckInputs ? []`: Dependencies needed for running the [`checkPhase`](#ssec-check-phase). These
are added to [`nativeBuildInputs`](#var-stdenv-nativeBuildInputs) when [`doCheck = true`](#var-stdenv-doCheck). Items listed in
`tests_require` go here.
* `propagatedBuildInputs ? []`: Aside from propagating dependencies,
* `dependencies ? []`: Aside from propagating dependencies,
`buildPythonPackage` also injects code into and wraps executables with the
paths included in this list. Items listed in `install_requires` go here.
* `optional-dependencies ? { }`: Optional feature flagged dependencies. Items listed in `extras_requires` go here.
Aside from propagating dependencies,
`buildPythonPackage` also injects code into and wraps executables with the
paths included in this list. Items listed in `extras_requires` go here.
##### Overriding Python packages {#overriding-python-packages}
@ -299,14 +302,14 @@ python3Packages.buildPythonApplication rec {
hash = "sha256-Pe229rT0aHwA98s+nTHQMEFKZPo/yw6sot8MivFDvAw=";
};
nativeBuildInputs = [
python3Packages.setuptools
python3Packages.wheel
build-system = with python3Packages; [
setuptools
wheel
];
propagatedBuildInputs = [
python3Packages.tornado
python3Packages.python-daemon
dependencies = with python3Packages; [
tornado
python-daemon
];
meta = with lib; {
@ -463,14 +466,14 @@ are used in [`buildPythonPackage`](#buildpythonpackage-function).
- `eggBuildHook` to skip building for eggs.
- `eggInstallHook` to install eggs.
- `pipBuildHook` to build a wheel using `pip` and PEP 517. Note a build system
(e.g. `setuptools` or `flit`) should still be added as `nativeBuildInput`.
(e.g. `setuptools` or `flit`) should still be added as `build-system`.
- `pypaBuildHook` to build a wheel using
[`pypa/build`](https://pypa-build.readthedocs.io/en/latest/index.html) and
PEP 517/518. Note a build system (e.g. `setuptools` or `flit`) should still
be added as `nativeBuildInput`.
be added as `build-system`.
- `pipInstallHook` to install wheels.
- `pytestCheckHook` to run tests with `pytest`. See [example usage](#using-pytestcheckhook).
- `pythonCatchConflictsHook` to check whether a Python package is not already existing.
- `pythonCatchConflictsHook` to fail if the package depends on two different versions of the same dependency.
- `pythonImportsCheckHook` to check whether importing the listed modules works.
- `pythonRelaxDepsHook` will relax Python dependencies restrictions for the package.
See [example usage](#using-pythonrelaxdepshook).
@ -882,7 +885,7 @@ buildPythonPackage rec {
hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
};
nativeBuildInputs = [
build-system = [
setuptools
wheel
];
@ -942,7 +945,7 @@ with import <nixpkgs> {};
hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
};
nativeBuildInputs = [
build-system = [
python311.pkgs.setuptools
python311.pkgs.wheel
];
@ -978,13 +981,15 @@ that we introduced with the `let` expression.
#### Handling dependencies {#handling-dependencies}
Our example, `toolz`, does not have any dependencies on other Python packages or
system libraries. According to the manual, [`buildPythonPackage`](#buildpythonpackage-function) uses the
arguments [`buildInputs`](#var-stdenv-buildInputs) and [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs) to specify dependencies. If
something is exclusively a build-time dependency, then the dependency should be
included in [`buildInputs`](#var-stdenv-buildInputs), but if it is (also) a runtime dependency, then it
should be added to [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs). Test dependencies are considered
build-time dependencies and passed to [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs).
Our example, `toolz`, does not have any dependencies on other Python packages or system libraries.
[`buildPythonPackage`](#buildpythonpackage-function) uses the the following arguments in the following circumstances:
- `dependencies` - For Python runtime dependencies.
- `build-system` - For Python build-time requirements.
- [`buildInputs`](#var-stdenv-buildInputs) - For non-Python build-time requirements.
- [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs) - For test dependencies
Dependencies can belong to multiple arguments, for example if something is both a build time requirement & a runtime dependency.
The following example shows which arguments are given to [`buildPythonPackage`](#buildpythonpackage-function) in
order to build [`datashape`](https://github.com/blaze/datashape).
@ -1014,12 +1019,12 @@ buildPythonPackage rec {
hash = "sha256-FLLvdm1MllKrgTGC6Gb0k0deZeVYvtCCLji/B7uhong=";
};
nativeBuildInputs = [
build-system = [
setuptools
wheel
];
propagatedBuildInputs = [
dependencies = [
multipledispatch
numpy
python-dateutil
@ -1042,7 +1047,7 @@ buildPythonPackage rec {
We can see several runtime dependencies, `numpy`, `multipledispatch`, and
`python-dateutil`. Furthermore, we have [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs) with `pytest`.
`pytest` is a test runner and is only used during the [`checkPhase`](#ssec-check-phase) and is
therefore not added to [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs).
therefore not added to `dependencies`.
In the previous case we had only dependencies on other Python packages to consider.
Occasionally you have also system libraries to consider. E.g., `lxml` provides
@ -1069,7 +1074,7 @@ buildPythonPackage rec {
hash = "sha256-s9NiusRxFydHzaNRMjjxFcvWxfi45jGb9ql6eJJyQJk=";
};
nativeBuildInputs = [
build-system = [
setuptools
wheel
];
@ -1126,7 +1131,7 @@ buildPythonPackage rec {
hash = "sha256-9ru2r6kwhUCaskiFoaPNuJCfCVoUL01J40byvRt4kHQ=";
};
nativeBuildInputs = [
build-system = [
setuptools
wheel
];
@ -1137,7 +1142,7 @@ buildPythonPackage rec {
fftwLongDouble
];
propagatedBuildInputs = [
dependencies = [
numpy
scipy
];
@ -1460,9 +1465,7 @@ mode is activated.
In the following example, we create a simple environment that has a Python 3.11
version of our package in it, as well as its dependencies and other packages we
like to have in the environment, all specified with [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs).
Indeed, we can just add any package we like to have in our environment to
[`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs).
like to have in the environment, all specified with `dependencies`.
```nix
with import <nixpkgs> {};
@ -1471,9 +1474,11 @@ with python311Packages;
buildPythonPackage rec {
name = "mypackage";
src = ./path/to/package/source;
propagatedBuildInputs = [
dependencies = [
pytest
numpy
];
propagatedBuildInputs = [
pkgs.libsndfile
];
}
@ -1520,7 +1525,7 @@ buildPythonPackage rec {
hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
};
nativeBuildInputs = [
build-system = [
setuptools
wheel
];
@ -1904,8 +1909,8 @@ configure alternatives](#sec-overlays-alternatives-blas-lapack)".
In a `setup.py` or `setup.cfg` it is common to declare dependencies:
* `setup_requires` corresponds to [`nativeBuildInputs`](#var-stdenv-nativeBuildInputs)
* `install_requires` corresponds to [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs)
* `setup_requires` corresponds to `build-system`
* `install_requires` corresponds to `dependencies`
* `tests_require` corresponds to [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs)
### How to enable interpreter optimizations? {#optimizations}
@ -1929,12 +1934,10 @@ in mypython
Some packages define optional dependencies for additional features. With
`setuptools` this is called `extras_require` and `flit` calls it
`extras-require`, while PEP 621 calls these `optional-dependencies`. A
method for supporting this is by declaring the extras of a package in its
`passthru`, e.g. in case of the package `dask`
`extras-require`, while PEP 621 calls these `optional-dependencies`.
```nix
passthru.optional-dependencies = {
optional-dependencies = {
complete = [ distributed ];
};
```
@ -1942,11 +1945,13 @@ passthru.optional-dependencies = {
and letting the package requiring the extra add the list to its dependencies
```nix
propagatedBuildInputs = [
dependencies = [
...
] ++ dask.optional-dependencies.complete;
```
This method is using `passthru`, meaning that changing `optional-dependencies` of a package won't cause it to rebuild.
Note this method is preferred over adding parameters to builders, as that can
result in packages depending on different variants and thereby causing
collisions.
@ -2061,7 +2066,7 @@ and create update commits, and supports the `fetchPypi`, `fetchurl` and
hosted on GitHub, exporting a `GITHUB_API_TOKEN` is highly recommended.
Updating packages in bulk leads to lots of breakages, which is why a
stabilization period on the `python-unstable` branch is required.
stabilization period on the `python-updates` branch is required.
If a package is fragile and often breaks during these bulks updates, it
may be reasonable to set `passthru.skipBulkUpdate = true` in the

50
doc/languages-frameworks/qt.section.md
View File

@ -3,61 +3,63 @@
Writing Nix expressions for Qt libraries and applications is largely similar as for other C++ software.
This section assumes some knowledge of the latter.
The major caveat with Qt applications is that Qt uses a plugin system to load additional modules at runtime,
from a list of well-known locations. In Nixpkgs, we patch QtCore to instead use an environment variable,
and wrap Qt applications to set it to the right paths. This effectively makes the runtime dependencies
pure and explicit at build-time, at the cost of introducing an extra indirection.
The major caveat with Qt applications is that Qt uses a plugin system to load additional modules at runtime.
In Nixpkgs, we wrap Qt applications to inject environment variables telling Qt where to discover the required plugins and QML modules.
This effectively makes the runtime dependencies pure and explicit at build-time, at the cost of introducing
an extra indirection.
## Nix expression for a Qt package (default.nix) {#qt-default-nix}
```nix
{ stdenv, lib, qtbase, wrapQtAppsHook }:
{ stdenv, qt6 }:
stdenv.mkDerivation {
pname = "myapp";
version = "1.0";
buildInputs = [ qtbase ];
nativeBuildInputs = [ wrapQtAppsHook ];
buildInputs = [ qt6.qtbase ];
nativeBuildInputs = [ qt6.wrapQtAppsHook ];
}
```
It is important to import Qt modules directly, that is: `qtbase`, `qtdeclarative`, etc. *Do not* import Qt package sets such as `qt5` because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
The same goes for Qt 5 where libraries and tools are under `libsForQt5`.
Additionally all Qt packages must include `wrapQtAppsHook` in `nativeBuildInputs`, or you must explicitly set `dontWrapQtApps`.
Any Qt package should include `wrapQtAppsHook` in `nativeBuildInputs`, or explicitly set `dontWrapQtApps` to bypass generating the wrappers.
## Locating runtime dependencies {#qt-runtime-dependencies}
::: {.note}
Qt 6 graphical applications should also include `qtwayland` in `buildInputs` on Linux (but not on platforms e.g. Darwin, where `qtwayland` is not available), to ensure the Wayland platform plugin is available.
Qt applications must be wrapped to find runtime dependencies.
Include `wrapQtAppsHook` in `nativeBuildInputs`:
This may become default in the future, see [NixOS/nixpkgs#269674](https://github.com/NixOS/nixpkgs/pull/269674).
:::
```nix
{ stdenv, wrapQtAppsHook }:
## Packages supporting multiple Qt versions {#qt-versions}
stdenv.mkDerivation {
# ...
nativeBuildInputs = [ wrapQtAppsHook ];
}
```
If your package is a library that can be built with multiple Qt versions, you may want to take Qt modules as separate arguments (`qtbase`, `qtdeclarative` etc.), and invoke the package from `pkgs/top-level/qt5-packages.nix` or `pkgs/top-level/qt6-packages.nix` using the respective `callPackage` functions.
Applications should generally be built with upstream's preferred Qt version.
## Locating additional runtime dependencies {#qt-runtime-dependencies}
Add entries to `qtWrapperArgs` are to modify the wrappers created by
`wrapQtAppsHook`:
```nix
{ stdenv, wrapQtAppsHook }:
{ stdenv, qt6 }:
stdenv.mkDerivation {
# ...
nativeBuildInputs = [ wrapQtAppsHook ];
nativeBuildInputs = [ qt6.wrapQtAppsHook ];
qtWrapperArgs = [ ''--prefix PATH : /path/to/bin'' ];
}
```
The entries are passed as arguments to [wrapProgram](#fun-wrapProgram).
Set `dontWrapQtApps` to stop applications from being wrapped automatically.
Wrap programs manually with `wrapQtApp`, using the syntax of
[wrapProgram](#fun-wrapProgram):
If you need more control over the wrapping process, set `dontWrapQtApps` to disable automatic wrapper generation,
and then create wrappers manually in `fixupPhase`, using `wrapQtApp`, which itself is a small wrapper over [wrapProgram](#fun-wrapProgram):
The `makeWrapper` arguments required for Qt are also exposed in the environment as `$qtWrapperArgs`.
```nix
{ stdenv, lib, wrapQtAppsHook }:

8
doc/languages-frameworks/ruby.section.md
View File

@ -2,13 +2,13 @@
## Using Ruby {#using-ruby}
Several versions of Ruby interpreters are available on Nix, as well as over 250 gems and many applications written in Ruby. The attribute `ruby` refers to the default Ruby interpreter, which is currently MRI 2.6. It's also possible to refer to specific versions, e.g. `ruby_2_y`, `jruby`, or `mruby`.
Several versions of Ruby interpreters are available on Nix, as well as over 250 gems and many applications written in Ruby. The attribute `ruby` refers to the default Ruby interpreter, which is currently MRI 3.1. It's also possible to refer to specific versions, e.g. `ruby_3_y`, `jruby`, or `mruby`.
In the Nixpkgs tree, Ruby packages can be found throughout, depending on what they do, and are called from the main package set. Ruby gems, however are separate sets, and there's one default set for each interpreter (currently MRI only).
There are two main approaches for using Ruby with gems. One is to use a specifically locked `Gemfile` for an application that has very strict dependencies. The other is to depend on the common gems, which we'll explain further down, and rely on them being updated regularly.
The interpreters have common attributes, namely `gems`, and `withPackages`. So you can refer to `ruby.gems.nokogiri`, or `ruby_2_7.gems.nokogiri` to get the Nokogiri gem already compiled and ready to use.
The interpreters have common attributes, namely `gems`, and `withPackages`. So you can refer to `ruby.gems.nokogiri`, or `ruby_3_2.gems.nokogiri` to get the Nokogiri gem already compiled and ready to use.
Since not all gems have executables like `nokogiri`, it's usually more convenient to use the `withPackages` function like this: `ruby.withPackages (p: with p; [ nokogiri ])`. This will also make sure that the Ruby in your environment will be able to find the gem and it can be used in your Ruby code (for example via `ruby` or `irb` executables) via `require "nokogiri"` as usual.
@ -33,7 +33,7 @@ Again, it's possible to launch the interpreter from the shell. The Ruby interpre
#### Load Ruby environment from `.nix` expression {#load-ruby-environment-from-.nix-expression}
As explained [in the `nix-shell` section](https://nixos.org/manual/nix/stable/command-ref/nix-shell) of the Nix manual, `nix-shell` can also load an expression from a `.nix` file.
Say we want to have Ruby 2.6, `nokogori`, and `pry`. Consider a `shell.nix` file with:
Say we want to have Ruby, `nokogori`, and `pry`. Consider a `shell.nix` file with:
```nix
with import <nixpkgs> {};
@ -114,7 +114,7 @@ With this file in your directory, you can run `nix-shell` to build and use the g
The `bundlerEnv` is a wrapper over all the gems in your gemset. This means that all the `/lib` and `/bin` directories will be available, and the executables of all gems (even of indirect dependencies) will end up in your `$PATH`. The `wrappedRuby` provides you with all executables that come with Ruby itself, but wrapped so they can easily find the gems in your gemset.
One common issue that you might have is that you have Ruby 2.6, but also `bundler` in your gemset. That leads to a conflict for `/bin/bundle` and `/bin/bundler`. You can resolve this by wrapping either your Ruby or your gems in a `lowPrio` call. So in order to give the `bundler` from your gemset priority, it would be used like this:
One common issue that you might have is that you have Ruby, but also `bundler` in your gemset. That leads to a conflict for `/bin/bundle` and `/bin/bundler`. You can resolve this by wrapping either your Ruby or your gems in a `lowPrio` call. So in order to give the `bundler` from your gemset priority, it would be used like this:
```nix
# ...

45
doc/languages-frameworks/rust.section.md
View File

@ -44,37 +44,38 @@ rustPlatform.buildRustPackage rec {
}
```
`buildRustPackage` requires either the `cargoSha256` or the
`cargoHash` attribute which is computed over all crate sources of this
package. `cargoHash256` is used for traditional Nix SHA-256 hashes,
such as the one in the example above. `cargoHash` should instead be
used for [SRI](https://www.w3.org/TR/SRI/) hashes. For example:
Exception: If the application has cargo `git` dependencies, the `cargoHash`/`cargoSha256`
approach will not work, and you will need to copy the `Cargo.lock` file of the application
to nixpkgs and continue with the next section for specifying the options of the`cargoLock`
section.
`buildRustPackage` requires either a `cargoHash` (preferred) or a
`cargoSha256` attribute, computed over all crate sources of this package.
`cargoHash` supports [SRI](https://www.w3.org/TR/SRI/) hashes and should be
preferred over `cargoSha256` which was used for traditional Nix SHA-256 hashes.
For example:
```nix
cargoHash = "sha256-l1vL2ZdtDRxSGvP0X/l3nMw8+6WF67KPutJEzUROjg8=";
```
Exception: If the application has cargo `git` dependencies, the `cargoHash`/`cargoSha256`
approach will not work, and you will need to copy the `Cargo.lock` file of the application
to nixpkgs and continue with the next section for specifying the options of the `cargoLock`
section.
Both types of hashes are permitted when contributing to nixpkgs. The
Cargo hash is obtained by inserting a fake checksum into the
expression and building the package once. The correct checksum can
then be taken from the failed build. A fake hash can be used for
`cargoSha256` as follows:
```nix
cargoSha256 = lib.fakeSha256;
```
For `cargoHash` you can use:
`cargoHash` as follows:
```nix
cargoHash = lib.fakeHash;
```
For `cargoSha256` you can use:
```nix
cargoSha256 = lib.fakeSha256;
```
Per the instructions in the [Cargo Book](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)
best practices guide, Rust applications should always commit the `Cargo.lock`
file in git to ensure a reproducible build. However, a few packages do not, and
@ -89,7 +90,7 @@ directory into a tar.gz archive.
The tarball with vendored dependencies contains a directory with the
package's `name`, which is normally composed of `pname` and
`version`. This means that the vendored dependencies hash
(`cargoSha256`/`cargoHash`) is dependent on the package name and
(`cargoHash`/`cargoSha256`) is dependent on the package name and
version. The `cargoDepsName` attribute can be used to use another name
for the directory of vendored dependencies. For example, the hash can
be made invariant to the version by setting `cargoDepsName` to
@ -114,7 +115,7 @@ rustPlatform.buildRustPackage rec {
### Importing a `Cargo.lock` file {#importing-a-cargo.lock-file}
Using `cargoSha256` or `cargoHash` is tedious when using
Using a vendored hash (`cargoHash`/`cargoSha256`) is tedious when using
`buildRustPackage` within a project, since it requires that the hash
is updated after every change to `Cargo.lock`. Therefore,
`buildRustPackage` also supports vendoring dependencies directly from
@ -700,7 +701,7 @@ with import <nixpkgs> {};
hello = attrs: lib.optionalAttrs (lib.versionAtLeast attrs.version "1.0") {
postPatch = ''
substituteInPlace lib/zoneinfo.rs \
--replace "/usr/share/zoneinfo" "${tzdata}/share/zoneinfo"
--replace-fail "/usr/share/zoneinfo" "${tzdata}/share/zoneinfo"
'';
};
};
@ -902,8 +903,8 @@ with import <nixpkgs>
};
let
rustPlatform = makeRustPlatform {
cargo = rust-bin.stable.latest.minimal;
rustc = rust-bin.stable.latest.minimal;
cargo = rust-bin.selectLatestNightlyWith (toolchain: toolchain.default);
rustc = rust-bin.selectLatestNightlyWith (toolchain: toolchain.default);
};
in

20
doc/languages-frameworks/texlive.section.md
View File

@ -208,3 +208,23 @@ EOF
cp test.pdf $out
''
```
## LuaLaTeX font cache {#sec-language-texlive-lualatex-font-cache}
The font cache for LuaLaTeX is written to `$HOME`.
Therefore, it is necessary to set `$HOME` to a writable path, e.g. [before using LuaLaTeX in nix derivations](https://github.com/NixOS/nixpkgs/issues/180639):
```nix
runCommandNoCC "lualatex-hello-world" {
buildInputs = [ texliveFull ];
} ''
mkdir $out
echo '\documentclass{article} \begin{document} Hello world \end{document}' > main.tex
env HOME=$(mktemp -d) lualatex -interaction=nonstopmode -output-format=pdf -output-directory=$out ./main.tex
''
```
Additionally, [the cache of a user can diverge from the nix store](https://github.com/NixOS/nixpkgs/issues/278718).
To resolve font issues that might follow, the cache can be removed by the user:
```ShellSession
luaotfload-tool --cache=erase --flush-lookups --force
```

8
doc/manpage-urls.json
View File

@ -314,5 +314,11 @@
"systemd-veritysetup@.service(8)": "https://www.freedesktop.org/software/systemd/man/systemd-veritysetup@.service.html",
"systemd-volatile-root(8)": "https://www.freedesktop.org/software/systemd/man/systemd-volatile-root.html",
"systemd-xdg-autostart-generator(8)": "https://www.freedesktop.org/software/systemd/man/systemd-xdg-autostart-generator.html",
"udevadm(8)": "https://www.freedesktop.org/software/systemd/man/udevadm.html"
"udevadm(8)": "https://www.freedesktop.org/software/systemd/man/udevadm.html",
"passwd(5)": "https://man.archlinux.org/man/passwd.5",
"group(5)": "https://man.archlinux.org/man/group.5",
"login.defs(5)": "https://man.archlinux.org/man/login.defs.5",
"unshare(1)": "https://man.archlinux.org/man/unshare.1.en",
"nix-shell(1)": "https://nixos.org/manual/nix/stable/command-ref/nix-shell.html",
"mksquashfs(1)": "https://man.archlinux.org/man/extra/squashfs-tools/mksquashfs.1.en"
}

14
doc/packages/darwin-builder.section.md
View File

@ -1,5 +1,12 @@
# darwin.linux-builder {#sec-darwin-builder}
:::{.warning}
By default, `darwin.linux-builder` uses a publicly-known private SSH **host key** (this is different from the SSH key used by the user that connects to the builder).
Given the intended use case for it (a Linux builder that runs **on the same machine**), this shouldn't be an issue.
However, if you plan to deviate from this use case in any way (e.g. by exposing this builder to remote machines), you should understand the security implications of doing so and take any appropriate measures.
:::
`darwin.linux-builder` provides a way to bootstrap a Linux remote builder on a macOS machine.
This requires macOS version 12.4 or later.
@ -97,8 +104,9 @@ $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
{ virtualisation = {
host.pkgs = pkgs;
darwin-builder.workingDirectory = "/var/lib/darwin-builder";
darwin-builder.hostPort = 22;
};
};
}
];
};
in {
@ -110,7 +118,9 @@ $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
{
nix.distributedBuilds = true;
nix.buildMachines = [{
hostName = "ssh://builder@localhost";
hostName = "localhost";
sshUser = "builder";
sshKey = "/etc/nix/builder_ed25519";
system = linuxSystem;
maxJobs = 4;
supportedFeatures = [ "kvm" "benchmark" "big-parallel" ];

14
doc/packages/linux.section.md
View File

@ -12,20 +12,6 @@ Both functions have an argument `kernelPatches` which should be a list of `{name
The kernel derivation created with `pkgs.buildLinux` exports an attribute `features` specifying whether optional functionality is or isn’t enabled. This is used in NixOS to implement kernel-specific behaviour.
:::{.example #ex-skip-package-from-kernel-feature}
# Skipping an external package because of a kernel feature
For instance, if the kernel has the `iwlwifi` feature (i.e., has built-in support for Intel wireless chipsets), then NixOS doesn’t have to build the external `iwlwifi` package:
```nix
modulesTree = [kernel]
++ pkgs.lib.optional (!kernel.features ? iwlwifi) kernelPackages.iwlwifi
++ ...;
```
:::
If you are using a kernel packaged in Nixpkgs, you can customize it by overriding its arguments. For details on how each argument affects the generated kernel, refer to [the `pkgs.buildLinux` source code](https://github.com/NixOS/nixpkgs/blob/d77bda728d5041c1294a68fb25c79e2d161f62b9/pkgs/os-specific/linux/kernel/generic.nix).
:::{.example #ex-overriding-kernel-derivation}

2
doc/packages/nginx.section.md
View File

@ -8,4 +8,4 @@ HTTP has a couple of different mechanisms for caching to prevent clients from ha
Fortunately, HTTP supports an alternative (and more effective) caching mechanism: the [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) response header. The value of the `ETag` header specifies some identifier for the particular content that the server is sending (e.g., a hash). When a client makes a second request for the same resource, it sends that value back in an `If-None-Match` header. If the ETag value is unchanged, then the server does not need to resend the content.
As of NixOS 19.09, the nginx package in Nixpkgs is patched such that when nginx serves a file out of `/nix/store`, the hash in the store path is used as the `ETag` header in the HTTP response, thus providing proper caching functionality. This happens automatically; you do not need to do modify any configuration to get this behavior.
As of NixOS 19.09, the nginx package in Nixpkgs is patched such that when nginx serves a file out of `/nix/store`, the hash in the store path is used as the `ETag` header in the HTTP response, thus providing proper caching functionality. With NixOS 24.05 and later, the `ETag` additionally includes the response content length, to ensure files served with static compression do not share `ETag`s with their uncompressed version. This `ETag` functionality is enabled automatically; you do not need to do modify any configuration to get this behavior.

12
doc/preface.chapter.md
View File

@ -27,18 +27,18 @@ With these expressions the Nix package manager can build binary packages.
Packages, including the Nix packages collection, are distributed through
[channels](https://nixos.org/nix/manual/#sec-channels). The collection is
distributed for users of Nix on non-NixOS distributions through the channel
`nixpkgs`. Users of NixOS generally use one of the `nixos-*` channels, e.g.
`nixos-22.11`, which includes all packages and modules for the stable NixOS
`nixpkgs-unstable`. Users of NixOS generally use one of the `nixos-*` channels,
e.g. `nixos-22.11`, which includes all packages and modules for the stable NixOS
22.11. Stable NixOS releases are generally only given
security updates. More up to date packages and modules are available via the
`nixos-unstable` channel.
Both `nixos-unstable` and `nixpkgs` follow the `master` branch of the Nixpkgs
repository, although both do lag the `master` branch by generally
Both `nixos-unstable` and `nixpkgs-unstable` follow the `master` branch of the
nixpkgs repository, although both do lag the `master` branch by generally
[a couple of days](https://status.nixos.org/). Updates to a channel are
distributed as soon as all tests for that channel pass, e.g.
[this table](https://hydra.nixos.org/job/nixpkgs/trunk/unstable#tabs-constituents)
shows the status of tests for the `nixpkgs` channel.
shows the status of tests for the `nixpkgs-unstable` channel.
The tests are conducted by a cluster called [Hydra](https://nixos.org/hydra/),
which also builds binary packages from the Nix expressions in Nixpkgs for
@ -46,5 +46,5 @@ which also builds binary packages from the Nix expressions in Nixpkgs for
The binaries are made available via a [binary cache](https://cache.nixos.org).
The current Nix expressions of the channels are available in the
[`nixpkgs`](https://github.com/NixOS/nixpkgs) repository in branches
[nixpkgs repository](https://github.com/NixOS/nixpkgs) in branches
that correspond to the channel names (e.g. `nixos-22.11-small`).

2
doc/stdenv/platform-notes.chapter.md
View File

@ -54,7 +54,7 @@ Some common issues when packaging software for Darwin:
# ...
prePatch = ''
substituteInPlace Makefile \
--replace '/usr/bin/xcrun clang' clang
--replace-fail '/usr/bin/xcrun clang' clang
'';
}
```

27
doc/stdenv/stdenv.chapter.md
View File

@ -230,9 +230,9 @@ stdenv.mkDerivation rec {
postInstall = ''
substituteInPlace $out/bin/solo5-virtio-mkimage \
--replace "/usr/lib/syslinux" "${syslinux}/share/syslinux" \
--replace "/usr/share/syslinux" "${syslinux}/share/syslinux" \
--replace "cp " "cp --no-preserve=mode "
--replace-fail "/usr/lib/syslinux" "${syslinux}/share/syslinux" \
--replace-fail "/usr/share/syslinux" "${syslinux}/share/syslinux" \
--replace-fail "cp " "cp --no-preserve=mode "
wrapProgram $out/bin/solo5-virtio-mkimage \
--prefix PATH : ${lib.makeBinPath [ dosfstools mtools parted syslinux ]}
@ -475,11 +475,11 @@ A script to be run by `maintainers/scripts/update.nix` when the package is match
```nix
passthru.updateScript = writeScript "update-zoom-us" ''
#!/usr/bin/env nix-shell
#!nix-shell -i bash -p curl pcre common-updater-scripts
#!nix-shell -i bash -p curl pcre2 common-updater-scripts
set -eu -o pipefail
version="$(curl -sI https://zoom.us/client/latest/zoom_x86_64.tar.xz | grep -Fi 'Location:' | pcregrep -o1 '/(([0-9]\.?)+)/')"
version="$(curl -sI https://zoom.us/client/latest/zoom_x86_64.tar.xz | grep -Fi 'Location:' | pcre2grep -o1 '/(([0-9]\.?)+)/')"
update-source-version zoom-us "$version"
'';
```
@ -1253,9 +1253,20 @@ postInstall = ''
Performs string substitution on the contents of \<infile\>, writing the result to \<outfile\>. The substitutions in \<subs\> are of the following form:
#### `--replace` \<s1\> \<s2\> {#fun-substitute-replace}
#### `--replace-fail` \<s1\> \<s2\> {#fun-substitute-replace-fail}
Replace every occurrence of the string \<s1\> by \<s2\>.
Will error if no change is made.
#### `--replace-warn` \<s1\> \<s2\> {#fun-substitute-replace-warn}
Replace every occurrence of the string \<s1\> by \<s2\>.
Will print a warning if no change is made.
#### `--replace-quiet` \<s1\> \<s2\> {#fun-substitute-replace-quiet}
Replace every occurrence of the string \<s1\> by \<s2\>.
Will do nothing if no change can be made.
#### `--subst-var` \<varName\> {#fun-substitute-subst-var}
@ -1269,8 +1280,8 @@ Example:
```shell
substitute ./foo.in ./foo.out \
--replace /usr/bin/bar $bar/bin/bar \
--replace "a string containing spaces" "some other text" \
--replace-fail /usr/bin/bar $bar/bin/bar \
--replace-fail "a string containing spaces" "some other text" \
--subst-var someVar
```

40
flake.nix
View File

@ -21,16 +21,50 @@
nixosSystem = args:
import ./nixos/lib/eval-config.nix (
args // { inherit (self) lib; } // lib.optionalAttrs (! args?system) {
{
lib = final;
# Allow system to be set modularly in nixpkgs.system.
# We set it to null, to remove the "legacy" entrypoint's
# non-hermetic default.
system = null;
}
modules = args.modules ++ [
# This module is injected here since it exposes the nixpkgs self-path in as
# constrained of contexts as possible to avoid more things depending on it and
# introducing unnecessary potential fragility to changes in flakes itself.
#
# See: failed attempt to make pkgs.path not copy when using flakes:
# https://github.com/NixOS/nixpkgs/pull/153594#issuecomment-1023287913
({ config, pkgs, lib, ... }: {
config.nixpkgs.flake.source = self.outPath;
})
];
} // builtins.removeAttrs args [ "modules" ]
);
});
checks.x86_64-linux.tarball = jobs.tarball;
checks.x86_64-linux = {
tarball = jobs.tarball;
# Test that ensures that the nixosSystem function can accept a lib argument
# Note: prefer not to extend or modify `lib`, especially if you want to share reusable modules
# alternatives include: `import` a file, or put a custom library in an option or in `_module.args.<libname>`
nixosSystemAcceptsLib = (self.lib.nixosSystem {
lib = self.lib.extend (final: prev: {
ifThisFunctionIsMissingTheTestFails = final.id;
});
modules = [
./nixos/modules/profiles/minimal.nix
({ lib, ... }: lib.ifThisFunctionIsMissingTheTestFails {
# Define a minimal config without eval warnings
nixpkgs.hostPlatform = "x86_64-linux";
boot.loader.grub.enable = false;
fileSystems."/".device = "nodev";
# See https://search.nixos.org/options?show=system.stateVersion&query=stateversion
system.stateVersion = lib.versions.majorMinor lib.version; # DON'T do this in real configs!
})
];
}).config.system.build.toplevel;
};
htmlDocs = {
nixpkgsManual = jobs.manual;

1
lib/.version Normal file
View File

@ -0,0 +1 @@
24.05

125
lib/attrsets.nix
View File

@ -2,10 +2,10 @@
{ lib }:
let
inherit (builtins) head tail length;
inherit (lib.trivial) id mergeAttrs;
inherit (builtins) head length;
inherit (lib.trivial) mergeAttrs warn;
inherit (lib.strings) concatStringsSep concatMapStringsSep escapeNixIdentifier sanitizeDerivationName;
inherit (lib.lists) foldr foldl' concatMap concatLists elemAt all partition groupBy take foldl;
inherit (lib.lists) foldr foldl' concatMap elemAt all partition groupBy take foldl;
in
rec {
@ -216,8 +216,7 @@ rec {
attrPath:
# The nested attribute set to find the value in.
set:
let errorMsg = "cannot find attribute `" + concatStringsSep "." attrPath + "'";
in attrByPath attrPath (abort errorMsg) set;
attrByPath attrPath (abort ("cannot find attribute `" + concatStringsSep "." attrPath + "'")) set;
/* Map each attribute in the given set and merge them into a new attribute set.
@ -369,7 +368,7 @@ rec {
Type:
attrValues :: AttrSet -> [Any]
*/
attrValues = builtins.attrValues or (attrs: attrVals (attrNames attrs) attrs);
attrValues = builtins.attrValues;
/* Given a set of attribute names, return the set of the corresponding
@ -398,8 +397,7 @@ rec {
Type:
catAttrs :: String -> [AttrSet] -> [Any]
*/
catAttrs = builtins.catAttrs or
(attr: l: concatLists (map (s: if s ? ${attr} then [s.${attr}] else []) l));
catAttrs = builtins.catAttrs;
/* Filter an attribute set by removing all attributes for which the
@ -608,9 +606,7 @@ rec {
Type:
mapAttrs :: (String -> Any -> Any) -> AttrSet -> AttrSet
*/
mapAttrs = builtins.mapAttrs or
(f: set:
listToAttrs (map (attr: { name = attr; value = f attr set.${attr}; }) (attrNames set)));
mapAttrs = builtins.mapAttrs;
/* Like `mapAttrs`, but allows the name of each attribute to be
@ -683,65 +679,79 @@ rec {
attrsToList = mapAttrsToList nameValuePair;
/* Like `mapAttrs`, except that it recursively applies itself to
the *leaf* attributes of a potentially-nested attribute set:
the second argument of the function will never be an attrset.
Also, the first argument of the argument function is a *list*
of the attribute names that form the path to the leaf attribute.
/**
Like `mapAttrs`, except that it recursively applies itself to the *leaf* attributes of a potentially-nested attribute set:
the second argument of the function will never be an attrset.
Also, the first argument of the mapping function is a *list* of the attribute names that form the path to the leaf attribute.
For a function that gives you control over what counts as a leaf,
see `mapAttrsRecursiveCond`.
For a function that gives you control over what counts as a leaf, see `mapAttrsRecursiveCond`.
Example:
mapAttrsRecursive (path: value: concatStringsSep "-" (path ++ [value]))
{ n = { a = "A"; m = { b = "B"; c = "C"; }; }; d = "D"; }
=> { n = { a = "n-a-A"; m = { b = "n-m-b-B"; c = "n-m-c-C"; }; }; d = "d-D"; }
:::{#map-attrs-recursive-example .example}
# Map over leaf attributes
Type:
mapAttrsRecursive :: ([String] -> a -> b) -> AttrSet -> AttrSet
```nix
mapAttrsRecursive (path: value: concatStringsSep "-" (path ++ [value]))
{ n = { a = "A"; m = { b = "B"; c = "C"; }; }; d = "D"; }
```
evaluates to
```nix
{ n = { a = "n-a-A"; m = { b = "n-m-b-B"; c = "n-m-c-C"; }; }; d = "d-D"; }
```
:::
# Type
```
mapAttrsRecursive :: ([String] -> a -> b) -> AttrSet -> AttrSet
```
*/
mapAttrsRecursive =
# A function, given a list of attribute names and a value, returns a new value.
# A function that, given an attribute path as a list of strings and the corresponding attribute value, returns a new value.
f:
# Set to recursively map over.
# Attribute set to recursively map over.
set:
mapAttrsRecursiveCond (as: true) f set;
/* Like `mapAttrsRecursive`, but it takes an additional predicate
function that tells it whether to recurse into an attribute
set. If it returns false, `mapAttrsRecursiveCond` does not
recurse, but does apply the map function. If it returns true, it
does recurse, and does not apply the map function.
/**
Like `mapAttrsRecursive`, but it takes an additional predicate that tells it whether to recurse into an attribute set.
If the predicate returns false, `mapAttrsRecursiveCond` does not recurse, but instead applies the mapping function.
If the predicate returns true, it does recurse, and does not apply the mapping function.
Example:
# To prevent recursing into derivations (which are attribute
# sets with the attribute "type" equal to "derivation"):
mapAttrsRecursiveCond
(as: !(as ? "type" && as.type == "derivation"))
(x: ... do something ...)
attrs
:::{#map-attrs-recursive-cond-example .example}
# Map over an leaf attributes defined by a condition
Type:
mapAttrsRecursiveCond :: (AttrSet -> Bool) -> ([String] -> a -> b) -> AttrSet -> AttrSet
Map derivations to their `name` attribute.
Derivatons are identified as attribute sets that contain `{ type = "derivation"; }`.
```nix
mapAttrsRecursiveCond
(as: !(as ? "type" && as.type == "derivation"))
(x: x.name)
attrs
```
:::
# Type
```
mapAttrsRecursiveCond :: (AttrSet -> Bool) -> ([String] -> a -> b) -> AttrSet -> AttrSet
```
*/
mapAttrsRecursiveCond =
# A function, given the attribute set the recursion is currently at, determine if to recurse deeper into that attribute set.
# A function that, given the attribute set the recursion is currently at, determines if to recurse deeper into that attribute set.
cond:
# A function, given a list of attribute names and a value, returns a new value.
# A function that, given an attribute path as a list of strings and the corresponding attribute value, returns a new value.
# The attribute value is either an attribute set for which `cond` returns false, or something other than an attribute set.
f:
# Attribute set to recursively map over.
set:
let
recurse = path:
let
g =
name: value:
mapAttrs
(name: value:
if isAttrs value && cond value
then recurse (path ++ [name]) value
else f (path ++ [name]) value;
in mapAttrs g;
in recurse [] set;
then recurse (path ++ [ name ]) value
else f (path ++ [ name ]) value);
in
recurse [ ] set;
/* Generate an attribute set by mapping a function over a list of
@ -873,10 +883,7 @@ rec {
Type:
zipAttrs :: [ AttrSet ] -> AttrSet
*/
zipAttrs =
# List of attribute sets to zip together.
sets:
zipAttrsWith (name: values: values) sets;
zipAttrs = zipAttrsWith (name: values: values);
/*
Merge a list of attribute sets together using the `//` operator.
@ -1141,10 +1148,7 @@ rec {
Type: chooseDevOutputs :: [Derivation] -> [String]
*/
chooseDevOutputs =
# List of packages to pick `dev` outputs from
drvs:
builtins.map getDev drvs;
chooseDevOutputs = builtins.map getDev;
/* Make various Nix tools consider the contents of the resulting
attribute set when looking for what to build, find, etc.
@ -1197,9 +1201,10 @@ rec {
(x // y) // mask;
# DEPRECATED
zipWithNames = zipAttrsWithNames;
zipWithNames = warn
"lib.zipWithNames is a deprecated alias of lib.zipAttrsWithNames." zipAttrsWithNames;
# DEPRECATED
zip = builtins.trace
"lib.zip is deprecated, use lib.zipAttrsWith instead" zipAttrsWith;
zip = warn
"lib.zip is a deprecated alias of lib.zipAttrsWith." zipAttrsWith;
}

9
lib/customisation.nix
View File

@ -203,7 +203,11 @@ rec {
in if missingArgs == {}
then makeOverridable f allArgs
else throw "lib.customisation.callPackageWith: ${error}";
# This needs to be an abort so it can't be caught with `builtins.tryEval`,
# which is used by nix-env and ofborg to filter out packages that don't evaluate.
# This way we're forced to fix such errors in Nixpkgs,
# which is especially relevant with allowAliases = false
else abort "lib.customisation.callPackageWith: ${error}";
/* Like callPackage, but for a function that returns an attribute
@ -217,9 +221,10 @@ rec {
let
f = if isFunction fn then fn else import fn;
auto = intersectAttrs (functionArgs f) autoArgs;
mirrorArgs = mirrorFunctionArgs f;
origArgs = auto // args;
pkgs = f origArgs;
mkAttrOverridable = name: _: makeOverridable (newArgs: (f newArgs).${name}) origArgs;
mkAttrOverridable = name: _: makeOverridable (mirrorArgs (newArgs: (f newArgs).${name})) origArgs;
in
if isDerivation pkgs then throw
("function `callPackages` was called on a *single* derivation "

6
lib/default.nix
View File

@ -84,8 +84,8 @@ let
mapAttrs' mapAttrsToList attrsToList concatMapAttrs mapAttrsRecursive
mapAttrsRecursiveCond genAttrs isDerivation toDerivation optionalAttrs
zipAttrsWithNames zipAttrsWith zipAttrs recursiveUpdateUntil
recursiveUpdate matchAttrs overrideExisting showAttrPath getOutput getBin
getLib getDev getMan chooseDevOutputs zipWithNames zip
recursiveUpdate matchAttrs mergeAttrsList overrideExisting showAttrPath getOutput
getBin getLib getDev getMan chooseDevOutputs zipWithNames zip
recurseIntoAttrs dontRecurseIntoAttrs cartesianProductOfSets
updateManyAttrsByPath;
inherit (self.lists) singleton forEach foldr fold foldl foldl' imap0 imap1
@ -116,7 +116,7 @@ let
inherit (self.customisation) overrideDerivation makeOverridable
callPackageWith callPackagesWith extendDerivation hydraJob
makeScope makeScopeWithSplicing makeScopeWithSplicing';
inherit (self.derivations) lazyDerivation;
inherit (self.derivations) lazyDerivation optionalDrvAttr;
inherit (self.meta) addMetaAttrs dontDistribute setName updateName
appendToName mapDerivationAttrset setPrio lowPrio lowPrioSet hiPrio
hiPrioSet getLicenseFromSpdxId getExe getExe';

90
lib/derivations.nix
View File

@ -1,7 +1,20 @@
{ lib }:
let
inherit (lib) throwIfNot;
inherit (lib)
genAttrs
isString
throwIfNot
;
showMaybeAttrPosPre = prefix: attrName: v:
let pos = builtins.unsafeGetAttrPos attrName v;
in if pos == null then "" else "${prefix}${pos.file}:${toString pos.line}:${toString pos.column}";
showMaybePackagePosPre = prefix: pkg:
if pkg?meta.position && isString pkg.meta.position
then "${prefix}${pkg.meta.position}"
else "";
in
{
/*
@ -64,6 +77,11 @@ in
#
# This can be used for adding package attributes, such as `tests`.
passthru ? { }
, # Optional list of assumed outputs. Default: ["out"]
#
# This must match the set of outputs that the returned derivation has.
# You must use this when the derivation has multiple outputs.
outputs ? [ "out" ]
}:
let
# These checks are strict in `drv` and some `drv` attributes, but the
@ -71,11 +89,40 @@ in
# Instead, the individual derivation attributes do depend on it.
checked =
throwIfNot (derivation.type or null == "derivation")
"lazySimpleDerivation: input must be a derivation."
"lazyDerivation: input must be a derivation."
throwIfNot
(derivation.outputs == [ "out" ])
# Supporting multiple outputs should be a matter of inheriting more attrs.
"The derivation ${derivation.name or "<unknown>"} has multiple outputs. This is not supported by lazySimpleDerivation yet. Support could be added, and be useful as long as the set of outputs is known in advance, without evaluating the actual derivation."
# NOTE: Technically we could require our outputs to be a subset of the
# actual ones, or even leave them unchecked and fail on a lazy basis.
# However, consider the case where an output is added in the underlying
# derivation, such as dev. lazyDerivation would remove it and cause it
# to fail as a buildInputs item, without any indication as to what
# happened. Hence the more stringent condition. We could consider
# adding a flag to control this behavior if there's a valid case for it,
# but the documentation must have a note like this.
(derivation.outputs == outputs)
''
lib.lazyDerivation: The derivation ${derivation.name or "<unknown>"} has outputs that don't match the assumed outputs.
Assumed outputs passed to lazyDerivation${showMaybeAttrPosPre ",\n at " "outputs" args}:
${lib.generators.toPretty { multiline = false; } outputs};
Actual outputs of the derivation${showMaybePackagePosPre ",\n defined at " derivation}:
${lib.generators.toPretty { multiline = false; } derivation.outputs}
If the outputs are known ahead of evaluating the derivation,
then update the lazyDerivation call to match the actual outputs, in the same order.
If lazyDerivation is passed a literal value, just change it to the actual outputs.
As a result it will work as before / as intended.
Otherwise, when the outputs are dynamic and can't be known ahead of time, it won't
be possible to add laziness, but lib.lazyDerivation may still be useful for trimming
the attributes.
If you want to keep trimming the attributes, make sure that the package is in a
variable (don't evaluate it twice!) and pass the variable and its outputs attribute
to lib.lazyDerivation. This largely defeats laziness, but keeps the trimming.
If none of the above works for you, replace the lib.lazyDerivation call by the
expression in the derivation argument.
''
derivation;
in
{
@ -92,10 +139,39 @@ in
# A fixed set of derivation values, so that `lazyDerivation` can return
# its attrset before evaluating `derivation`.
# This must only list attributes that are available on _all_ derivations.
inherit (checked) outputs out outPath outputName drvPath name system;
inherit (checked) outPath outputName drvPath name system;
inherit outputs;
# The meta attribute can either be taken from the derivation, or if the
# `lazyDerivation` caller knew a shortcut, be taken from there.
meta = args.meta or checked.meta;
} // passthru;
}
// genAttrs outputs (outputName: checked.${outputName})
// passthru;
/* Conditionally set a derivation attribute.
Because `mkDerivation` sets `__ignoreNulls = true`, a derivation
attribute set to `null` will not impact the derivation output hash.
Thus, this function passes through its `value` argument if the `cond`
is `true`, but returns `null` if not.
Type: optionalDrvAttr :: Bool -> a -> a | Null
Example:
(stdenv.mkDerivation {
name = "foo";
x = optionalDrvAttr true 1;
y = optionalDrvAttr false 1;
}).drvPath == (stdenv.mkDerivation {
name = "foo";
x = 1;
}).drvPath
=> true
*/
optionalDrvAttr =
# Condition
cond:
# Attribute value
value: if cond then value else null;
}

37
lib/fileset/default.nix
View File

@ -23,6 +23,10 @@
Add files in file sets to the store to use as derivation sources.
- [`lib.fileset.toList`](#function-library-lib.fileset.toList):
The list of files contained in a file set.
Combinators:
- [`lib.fileset.union`](#function-library-lib.fileset.union)/[`lib.fileset.unions`](#function-library-lib.fileset.unions):
@ -102,6 +106,7 @@ let
_coerceMany
_toSourceFilter
_fromSourceFilter
_toList
_unionMany
_fileFilter
_printFileset
@ -412,6 +417,38 @@ in {
filter = sourceFilter;
};
/*
The list of file paths contained in the given file set.
:::{.note}
This function is strict in the entire file set.
This is in contrast with combinators [`lib.fileset.union`](#function-library-lib.fileset.union),
[`lib.fileset.intersection`](#function-library-lib.fileset.intersection) and [`lib.fileset.difference`](#function-library-lib.fileset.difference).
Thus it is recommended to call `toList` on file sets created using the combinators,
instead of doing list processing on the result of `toList`.
:::
The resulting list of files can be turned back into a file set using [`lib.fileset.unions`](#function-library-lib.fileset.unions).
Type:
toList :: FileSet -> [ Path ]
Example:
toList ./.
[ ./README.md ./Makefile ./src/main.c ./src/main.h ]
toList (difference ./. ./src)
[ ./README.md ./Makefile ]
*/
toList =
# The file set whose file paths to return.
# This argument can also be a path,
# which gets [implicitly coerced to a file set](#sec-fileset-path-coercion).
fileset:
_toList (_coerce "lib.fileset.toList: Argument" fileset);
/*
The file set containing all files that are in either of two given file sets.
This is the same as [`unions`](#function-library-lib.fileset.unions),

42
lib/fileset/internal.nix
View File

@ -5,6 +5,7 @@ let
isAttrs
isPath
isString
nixVersion
pathExists
readDir
split
@ -17,6 +18,8 @@ let
attrNames
attrValues
mapAttrs
mapAttrsToList
optionalAttrs
zipAttrsWith
;
@ -27,6 +30,7 @@ let
inherit (lib.lists)
all
commonPrefix
concatLists
elemAt
filter
findFirst
@ -56,6 +60,7 @@ let
substring
stringLength
hasSuffix
versionAtLeast
;
inherit (lib.trivial)
@ -536,6 +541,27 @@ rec {
${baseNameOf root} = rootPathType;
};
# Turns a file set into the list of file paths it includes.
# Type: fileset -> [ Path ]
_toList = fileset:
let
recurse = path: tree:
if isAttrs tree then
concatLists (mapAttrsToList (name: value:
recurse (path + "/${name}") value
) tree)
else if tree == "directory" then
recurse path (readDir path)
else if tree == null then
[ ]
else
[ path ];
in
if fileset._internalIsEmptyWithoutBase then
[ ]
else
recurse fileset._internalBase fileset._internalTree;
# Transforms the filesetTree of a file set to a shorter base path, e.g.
# _shortenTreeBase [ "foo" ] (_create /foo/bar null)
# => { bar = null; }
@ -840,6 +866,10 @@ rec {
# https://github.com/NixOS/nix/commit/55cefd41d63368d4286568e2956afd535cb44018
_fetchGitSubmodulesMinver = "2.4";
# Support for `builtins.fetchGit` with `shallow = true` was introduced in 2.4
# https://github.com/NixOS/nix/commit/d1165d8791f559352ff6aa7348e1293b2873db1c
_fetchGitShallowMinver = "2.4";
# Mirrors the contents of a Nix store path relative to a local path as a file set.
# Some notes:
# - The store path is read at evaluation time.
@ -894,7 +924,17 @@ rec {
# However a simpler alternative still would be [a builtins.gitLsFiles](https://github.com/NixOS/nix/issues/2944).
fetchResult = fetchGit ({
url = path;
} // extraFetchGitAttrs);
}
# In older Nix versions, repositories were always assumed to be deep clones, which made `fetchGit` fail for shallow clones
# For newer versions this was fixed, but the `shallow` flag is required.
# The only behavioral difference is that for shallow clones, `fetchGit` doesn't return a `revCount`,
# which we don't need here, so it's fine to always pass it.
# Unfortunately this means older Nix versions get a poor error message for shallow repositories, and there's no good way to improve that.
# Checking for `.git/shallow` doesn't seem worth it, especially since that's more of an implementation detail,
# and would also require more code to handle worktrees where `.git` is a file.
// optionalAttrs (versionAtLeast nixVersion _fetchGitShallowMinver) { shallow = true; }
// extraFetchGitAttrs);
in
# We can identify local working directories by checking for .git,
# see https://git-scm.com/docs/gitrepository-layout#_description.

137
lib/fileset/tests.sh
View File

@ -275,7 +275,6 @@ createTree() {
# )
# checkFileset './a' # Pass the fileset as the argument
checkFileset() {
# New subshell so that we can have a separate trap handler, see `trap` below
local fileset=$1
# Create the tree
@ -283,16 +282,20 @@ checkFileset() {
# Process the tree into separate arrays for included paths, excluded paths and excluded files.
local -a included=()
local -a includedFiles=()
local -a excluded=()
local -a excludedFiles=()
for p in "${!tree[@]}"; do
case "${tree[$p]}" in
1)
included+=("$p")
# If keys end with a `/` we treat them as directories, otherwise files
if [[ ! "$p" =~ /$ ]]; then
includedFiles+=("$p")
fi
;;
0)
excluded+=("$p")
# If keys end with a `/` we treat them as directories, otherwise files
if [[ ! "$p" =~ /$ ]]; then
excludedFiles+=("$p")
fi
@ -302,6 +305,10 @@ checkFileset() {
esac
done
# Test that lib.fileset.toList contains exactly the included files.
# The /#/./ part prefixes each element with `./`
expectEqual "toList ($fileset)" "sort lessThan [ ${includedFiles[*]/#/./} ]"
expression="toSource { root = ./.; fileset = $fileset; }"
# We don't have lambda's in bash unfortunately,
@ -338,13 +345,17 @@ checkFileset() {
#### Error messages #####
# We're using [[:blank:]] here instead of \s, because only the former is POSIX
# (see https://pubs.opengroup.org/onlinepubs/007908799/xbd/re.html#tag_007_003_005).
# And indeed, Darwin's bash only supports the former
# Absolute paths in strings cannot be passed as `root`
expectFailure 'toSource { root = "/nix/store/foobar"; fileset = ./.; }' 'lib.fileset.toSource: `root` \(/nix/store/foobar\) is a string-like value, but it should be a path instead.
\s*Paths in strings are not supported by `lib.fileset`, use `lib.sources` or derivations instead.'
[[:blank:]]*Paths in strings are not supported by `lib.fileset`, use `lib.sources` or derivations instead.'
expectFailure 'toSource { root = cleanSourceWith { src = ./.; }; fileset = ./.; }' 'lib.fileset.toSource: `root` is a `lib.sources`-based value, but it should be a path instead.
\s*To use a `lib.sources`-based value, convert it to a file set using `lib.fileset.fromSource` and pass it as `fileset`.
\s*Note that this only works for sources created from paths.'
[[:blank:]]*To use a `lib.sources`-based value, convert it to a file set using `lib.fileset.fromSource` and pass it as `fileset`.
[[:blank:]]*Note that this only works for sources created from paths.'
# Only paths are accepted as `root`
expectFailure 'toSource { root = 10; fileset = ./.; }' 'lib.fileset.toSource: `root` is of type int, but it should be a path instead.'
@ -354,9 +365,9 @@ mkdir -p {foo,bar}/mock-root
expectFailure 'with ((import <nixpkgs/lib>).extend (import <nixpkgs/lib/fileset/mock-splitRoot.nix>)).fileset;
toSource { root = ./foo/mock-root; fileset = ./bar/mock-root; }
' 'lib.fileset.toSource: Filesystem roots are not the same for `fileset` and `root` \('"$work"'/foo/mock-root\):
\s*`root`: Filesystem root is "'"$work"'/foo/mock-root"
\s*`fileset`: Filesystem root is "'"$work"'/bar/mock-root"
\s*Different filesystem roots are not supported.'
[[:blank:]]*`root`: Filesystem root is "'"$work"'/foo/mock-root"
[[:blank:]]*`fileset`: Filesystem root is "'"$work"'/bar/mock-root"
[[:blank:]]*Different filesystem roots are not supported.'
rm -rf -- *
# `root` needs to exist
@ -365,8 +376,8 @@ expectFailure 'toSource { root = ./a; fileset = ./.; }' 'lib.fileset.toSource: `
# `root` needs to be a file
touch a
expectFailure 'toSource { root = ./a; fileset = ./a; }' 'lib.fileset.toSource: `root` \('"$work"'/a\) is a file, but it should be a directory instead. Potential solutions:
\s*- If you want to import the file into the store _without_ a containing directory, use string interpolation or `builtins.path` instead of this function.
\s*- If you want to import the file into the store _with_ a containing directory, set `root` to the containing directory, such as '"$work"', and set `fileset` to the file path.'
[[:blank:]]*- If you want to import the file into the store _without_ a containing directory, use string interpolation or `builtins.path` instead of this function.
[[:blank:]]*- If you want to import the file into the store _with_ a containing directory, set `root` to the containing directory, such as '"$work"', and set `fileset` to the file path.'
rm -rf -- *
# The fileset argument should be evaluated, even if the directory is empty
@ -375,36 +386,36 @@ expectFailure 'toSource { root = ./.; fileset = abort "This should be evaluated"
# Only paths under `root` should be able to influence the result
mkdir a
expectFailure 'toSource { root = ./a; fileset = ./.; }' 'lib.fileset.toSource: `fileset` could contain files in '"$work"', which is not under the `root` \('"$work"'/a\). Potential solutions:
\s*- Set `root` to '"$work"' or any directory higher up. This changes the layout of the resulting store path.
\s*- Set `fileset` to a file set that cannot contain files outside the `root` \('"$work"'/a\). This could change the files included in the result.'
[[:blank:]]*- Set `root` to '"$work"' or any directory higher up. This changes the layout of the resulting store path.
[[:blank:]]*- Set `fileset` to a file set that cannot contain files outside the `root` \('"$work"'/a\). This could change the files included in the result.'
rm -rf -- *
# non-regular and non-symlink files cannot be added to the Nix store
mkfifo a
expectFailure 'toSource { root = ./.; fileset = ./a; }' 'lib.fileset.toSource: `fileset` contains a file that cannot be added to the store: '"$work"'/a
\s*This file is neither a regular file nor a symlink, the only file types supported by the Nix store.
\s*Therefore the file set cannot be added to the Nix store as is. Make sure to not include that file to avoid this error.'
[[:blank:]]*This file is neither a regular file nor a symlink, the only file types supported by the Nix store.
[[:blank:]]*Therefore the file set cannot be added to the Nix store as is. Make sure to not include that file to avoid this error.'
rm -rf -- *
# Path coercion only works for paths
expectFailure 'toSource { root = ./.; fileset = 10; }' 'lib.fileset.toSource: `fileset` is of type int, but it should be a file set or a path instead.'
expectFailure 'toSource { root = ./.; fileset = "/some/path"; }' 'lib.fileset.toSource: `fileset` \("/some/path"\) is a string-like value, but it should be a file set or a path instead.
\s*Paths represented as strings are not supported by `lib.fileset`, use `lib.sources` or derivations instead.'
[[:blank:]]*Paths represented as strings are not supported by `lib.fileset`, use `lib.sources` or derivations instead.'
expectFailure 'toSource { root = ./.; fileset = cleanSourceWith { src = ./.; }; }' 'lib.fileset.toSource: `fileset` is a `lib.sources`-based value, but it should be a file set or a path instead.
\s*To convert a `lib.sources`-based value to a file set you can use `lib.fileset.fromSource`.
\s*Note that this only works for sources created from paths.'
[[:blank:]]*To convert a `lib.sources`-based value to a file set you can use `lib.fileset.fromSource`.
[[:blank:]]*Note that this only works for sources created from paths.'
# Path coercion errors for non-existent paths
expectFailure 'toSource { root = ./.; fileset = ./a; }' 'lib.fileset.toSource: `fileset` \('"$work"'/a\) is a path that does not exist.
\s*To create a file set from a path that may not exist, use `lib.fileset.maybeMissing`.'
[[:blank:]]*To create a file set from a path that may not exist, use `lib.fileset.maybeMissing`.'
# File sets cannot be evaluated directly
expectFailure 'union ./. ./.' 'lib.fileset: Directly evaluating a file set is not supported.
\s*To turn it into a usable source, use `lib.fileset.toSource`.
\s*To pretty-print the contents, use `lib.fileset.trace` or `lib.fileset.traceVal`.'
[[:blank:]]*To turn it into a usable source, use `lib.fileset.toSource`.
[[:blank:]]*To pretty-print the contents, use `lib.fileset.trace` or `lib.fileset.traceVal`.'
expectFailure '_emptyWithoutBase' 'lib.fileset: Directly evaluating a file set is not supported.
\s*To turn it into a usable source, use `lib.fileset.toSource`.
\s*To pretty-print the contents, use `lib.fileset.trace` or `lib.fileset.traceVal`.'
[[:blank:]]*To turn it into a usable source, use `lib.fileset.toSource`.
[[:blank:]]*To pretty-print the contents, use `lib.fileset.trace` or `lib.fileset.traceVal`.'
# Past versions of the internal representation are supported
expectEqual '_coerce "<tests>: value" { _type = "fileset"; _internalVersion = 0; _internalBase = ./.; }' \
@ -416,9 +427,9 @@ expectEqual '_coerce "<tests>: value" { _type = "fileset"; _internalVersion = 2;
# Future versions of the internal representation are unsupported
expectFailure '_coerce "<tests>: value" { _type = "fileset"; _internalVersion = 4; }' '<tests>: value is a file set created from a future version of the file set library with a different internal representation:
\s*- Internal version of the file set: 4
\s*- Internal version of the library: 3
\s*Make sure to update your Nixpkgs to have a newer version of `lib.fileset`.'
[[:blank:]]*- Internal version of the file set: 4
[[:blank:]]*- Internal version of the library: 3
[[:blank:]]*Make sure to update your Nixpkgs to have a newer version of `lib.fileset`.'
# _create followed by _coerce should give the inputs back without any validation
expectEqual '{
@ -511,6 +522,19 @@ expectEqual '_toSourceFilter (_create /. { foo = "regular"; }) "/foo" ""' 'true'
expectEqual '_toSourceFilter (_create /. { foo = null; }) "/foo" ""' 'false'
## lib.fileset.toList
# This function is mainly tested in checkFileset
# The error context for an invalid argument must be correct
expectFailure 'toList null' 'lib.fileset.toList: Argument is of type null, but it should be a file set or a path instead.'
# Works for the empty fileset
expectEqual 'toList _emptyWithoutBase' '[ ]'
# Works on empty paths
expectEqual 'toList ./.' '[ ]'
## lib.fileset.union, lib.fileset.unions
@ -519,16 +543,16 @@ mkdir -p {foo,bar}/mock-root
expectFailure 'with ((import <nixpkgs/lib>).extend (import <nixpkgs/lib/fileset/mock-splitRoot.nix>)).fileset;
toSource { root = ./.; fileset = union ./foo/mock-root ./bar/mock-root; }
' 'lib.fileset.union: Filesystem roots are not the same:
\s*First argument: Filesystem root is "'"$work"'/foo/mock-root"
\s*Second argument: Filesystem root is "'"$work"'/bar/mock-root"
\s*Different filesystem roots are not supported.'
[[:blank:]]*First argument: Filesystem root is "'"$work"'/foo/mock-root"
[[:blank:]]*Second argument: Filesystem root is "'"$work"'/bar/mock-root"
[[:blank:]]*Different filesystem roots are not supported.'
expectFailure 'with ((import <nixpkgs/lib>).extend (import <nixpkgs/lib/fileset/mock-splitRoot.nix>)).fileset;
toSource { root = ./.; fileset = unions [ ./foo/mock-root ./bar/mock-root ]; }
' 'lib.fileset.unions: Filesystem roots are not the same:
\s*Element 0: Filesystem root is "'"$work"'/foo/mock-root"
\s*Element 1: Filesystem root is "'"$work"'/bar/mock-root"
\s*Different filesystem roots are not supported.'
[[:blank:]]*Element 0: Filesystem root is "'"$work"'/foo/mock-root"
[[:blank:]]*Element 1: Filesystem root is "'"$work"'/bar/mock-root"
[[:blank:]]*Different filesystem roots are not supported.'
rm -rf -- *
# Coercion errors show the correct context
@ -632,9 +656,9 @@ mkdir -p {foo,bar}/mock-root
expectFailure 'with ((import <nixpkgs/lib>).extend (import <nixpkgs/lib/fileset/mock-splitRoot.nix>)).fileset;
toSource { root = ./.; fileset = intersection ./foo/mock-root ./bar/mock-root; }
' 'lib.fileset.intersection: Filesystem roots are not the same:
\s*First argument: Filesystem root is "'"$work"'/foo/mock-root"
\s*Second argument: Filesystem root is "'"$work"'/bar/mock-root"
\s*Different filesystem roots are not supported.'
[[:blank:]]*First argument: Filesystem root is "'"$work"'/foo/mock-root"
[[:blank:]]*Second argument: Filesystem root is "'"$work"'/bar/mock-root"
[[:blank:]]*Different filesystem roots are not supported.'
rm -rf -- *
# Coercion errors show the correct context
@ -741,8 +765,8 @@ rm -rf -- *
# Also not the other way around
mkdir a
expectFailure 'toSource { root = ./a; fileset = difference ./. ./a; }' 'lib.fileset.toSource: `fileset` could contain files in '"$work"', which is not under the `root` \('"$work"'/a\). Potential solutions:
\s*- Set `root` to '"$work"' or any directory higher up. This changes the layout of the resulting store path.
\s*- Set `fileset` to a file set that cannot contain files outside the `root` \('"$work"'/a\). This could change the files included in the result.'
[[:blank:]]*- Set `root` to '"$work"' or any directory higher up. This changes the layout of the resulting store path.
[[:blank:]]*- Set `fileset` to a file set that cannot contain files outside the `root` \('"$work"'/a\). This could change the files included in the result.'
rm -rf -- *
# Difference actually works
@ -819,7 +843,7 @@ expectFailure 'fileFilter null (abort "this is not needed")' 'lib.fileset.fileFi
# The second argument needs to be an existing path
expectFailure 'fileFilter (file: abort "this is not needed") _emptyWithoutBase' 'lib.fileset.fileFilter: Second argument is a file set, but it should be a path instead.
\s*If you need to filter files in a file set, use `intersection fileset \(fileFilter pred \./\.\)` instead.'
[[:blank:]]*If you need to filter files in a file set, use `intersection fileset \(fileFilter pred \./\.\)` instead.'
expectFailure 'fileFilter (file: abort "this is not needed") null' 'lib.fileset.fileFilter: Second argument is of type null, but it should be a path instead.'
expectFailure 'fileFilter (file: abort "this is not needed") ./a' 'lib.fileset.fileFilter: Second argument \('"$work"'/a\) is a path that does not exist.'
@ -1083,7 +1107,7 @@ rm -rf -- *
# String-like values are not supported
expectFailure 'fromSource (lib.cleanSource "")' 'lib.fileset.fromSource: The source origin of the argument is a string-like value \(""\), but it should be a path instead.
\s*Sources created from paths in strings cannot be turned into file sets, use `lib.sources` or derivations instead.'
[[:blank:]]*Sources created from paths in strings cannot be turned into file sets, use `lib.sources` or derivations instead.'
# Wrong type
expectFailure 'fromSource null' 'lib.fileset.fromSource: The source origin of the argument is of type null, but it should be a path instead.'
@ -1400,10 +1424,10 @@ expectEqual '(import '"$storePath"' { fs = lib.fileset; }).outPath' \""$storePat
## But it fails if the path is imported with a fetcher that doesn't remove .git (like just using "${./.}")
expectFailure 'import "${./.}" { fs = lib.fileset; }' 'lib.fileset.gitTracked: The argument \(.*\) is a store path within a working tree of a Git repository.
\s*This indicates that a source directory was imported into the store using a method such as `import "\$\{./.\}"` or `path:.`.
\s*This function currently does not support such a use case, since it currently relies on `builtins.fetchGit`.
\s*You could make this work by using a fetcher such as `fetchGit` instead of copying the whole repository.
\s*If you can'\''t avoid copying the repo to the store, see https://github.com/NixOS/nix/issues/9292.'
[[:blank:]]*This indicates that a source directory was imported into the store using a method such as `import "\$\{./.\}"` or `path:.`.
[[:blank:]]*This function currently does not support such a use case, since it currently relies on `builtins.fetchGit`.
[[:blank:]]*You could make this work by using a fetcher such as `fetchGit` instead of copying the whole repository.
[[:blank:]]*If you can'\''t avoid copying the repo to the store, see https://github.com/NixOS/nix/issues/9292.'
## Even with submodules
if [[ -n "$fetchGitSupportsSubmodules" ]]; then
@ -1427,18 +1451,31 @@ if [[ -n "$fetchGitSupportsSubmodules" ]]; then
## But it fails if the path is imported with a fetcher that doesn't remove .git (like just using "${./.}")
expectFailure 'import "${./.}" { fs = lib.fileset; }' 'lib.fileset.gitTrackedWith: The second argument \(.*\) is a store path within a working tree of a Git repository.
\s*This indicates that a source directory was imported into the store using a method such as `import "\$\{./.\}"` or `path:.`.
\s*This function currently does not support such a use case, since it currently relies on `builtins.fetchGit`.
\s*You could make this work by using a fetcher such as `fetchGit` instead of copying the whole repository.
\s*If you can'\''t avoid copying the repo to the store, see https://github.com/NixOS/nix/issues/9292.'
[[:blank:]]*This indicates that a source directory was imported into the store using a method such as `import "\$\{./.\}"` or `path:.`.
[[:blank:]]*This function currently does not support such a use case, since it currently relies on `builtins.fetchGit`.
[[:blank:]]*You could make this work by using a fetcher such as `fetchGit` instead of copying the whole repository.
[[:blank:]]*If you can'\''t avoid copying the repo to the store, see https://github.com/NixOS/nix/issues/9292.'
expectFailure 'import "${./.}/sub" { fs = lib.fileset; }' 'lib.fileset.gitTracked: The argument \(.*/sub\) is a store path within a working tree of a Git repository.
\s*This indicates that a source directory was imported into the store using a method such as `import "\$\{./.\}"` or `path:.`.
\s*This function currently does not support such a use case, since it currently relies on `builtins.fetchGit`.
\s*You could make this work by using a fetcher such as `fetchGit` instead of copying the whole repository.
\s*If you can'\''t avoid copying the repo to the store, see https://github.com/NixOS/nix/issues/9292.'
[[:blank:]]*This indicates that a source directory was imported into the store using a method such as `import "\$\{./.\}"` or `path:.`.
[[:blank:]]*This function currently does not support such a use case, since it currently relies on `builtins.fetchGit`.
[[:blank:]]*You could make this work by using a fetcher such as `fetchGit` instead of copying the whole repository.
[[:blank:]]*If you can'\''t avoid copying the repo to the store, see https://github.com/NixOS/nix/issues/9292.'
fi
rm -rf -- *
# shallow = true is not supported on all Nix versions
# and older versions don't support shallow clones at all
if [[ "$(nix-instantiate --eval --expr "$prefixExpression (versionAtLeast builtins.nixVersion _fetchGitShallowMinver)")" == true ]]; then
createGitRepo full
# Extra commit such that there's a commit that won't be in the shallow clone
git -C full commit --allow-empty -q -m extra
git clone -q --depth 1 "file://${PWD}/full" shallow
cd shallow
checkGitTracked
cd ..
rm -rf -- *
fi
# Go through all stages of Git files
# See https://www.git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository

160
lib/fixed-points.nix
View File

@ -103,42 +103,154 @@ rec {
else converge f x';
/*
Modify the contents of an explicitly recursive attribute set in a way that
honors `self`-references. This is accomplished with a function
Extend a function using an overlay.
Overlays allow modifying and extending fixed-point functions, specifically ones returning attribute sets.
A fixed-point function is a function which is intended to be evaluated by passing the result of itself as the argument.
This is possible due to Nix's lazy evaluation.
A fixed-point function returning an attribute set has the form
```nix
g = self: super: { foo = super.foo + " + "; }
final: { # attributes }
```
that has access to the unmodified input (`super`) as well as the final
non-recursive representation of the attribute set (`self`). `extends`
differs from the native `//` operator insofar as that it's applied *before*
references to `self` are resolved:
where `final` refers to the lazily evaluated attribute set returned by the fixed-point function.
```
nix-repl> fix (extends g f)
{ bar = "bar"; foo = "foo + "; foobar = "foo + bar"; }
An overlay to such a fixed-point function has the form
```nix
final: prev: { # attributes }
```
The name of the function is inspired by object-oriented inheritance, i.e.
think of it as an infix operator `g extends f` that mimics the syntax from
Java. It may seem counter-intuitive to have the "base class" as the second
argument, but it's nice this way if several uses of `extends` are cascaded.
where `prev` refers to the result of the original function to `final`, and `final` is the result of the composition of the overlay and the original function.
To get a better understanding how `extends` turns a function with a fix
point (the package set we start with) into a new function with a different fix
point (the desired packages set) lets just see, how `extends g f`
unfolds with `g` and `f` defined above:
Applying an overlay is done with `extends`:
```nix
let
f = final: { # attributes };
overlay = final: prev: { # attributes };
in extends overlay f;
```
extends g f = self: let super = f self; in super // g self super;
= self: let super = { foo = "foo"; bar = "bar"; foobar = self.foo + self.bar; }; in super // g self super
= self: { foo = "foo"; bar = "bar"; foobar = self.foo + self.bar; } // g self { foo = "foo"; bar = "bar"; foobar = self.foo + self.bar; }
= self: { foo = "foo"; bar = "bar"; foobar = self.foo + self.bar; } // { foo = "foo" + " + "; }
= self: { foo = "foo + "; bar = "bar"; foobar = self.foo + self.bar; }
To get the value of `final`, use `lib.fix`:
```nix
let
f = final: { # attributes };
overlay = final: prev: { # attributes };
g = extends overlay f;
in fix g
```
:::{.note}
The argument to the given fixed-point function after applying an overlay will *not* refer to its own return value, but rather to the value after evaluating the overlay function.
The given fixed-point function is called with a separate argument than if it was evaluated with `lib.fix`.
:::
:::{.example}
# Extend a fixed-point function with an overlay
Define a fixed-point function `f` that expects its own output as the argument `final`:
```nix-repl
f = final: {
# Constant value a
a = 1;
# b depends on the final value of a, available as final.a
b = final.a + 2;
}
```
Evaluate this using [`lib.fix`](#function-library-lib.fixedPoints.fix) to get the final result:
```nix-repl
fix f
=> { a = 1; b = 3; }
```
An overlay represents a modification or extension of such a fixed-point function.
Here's an example of an overlay:
```nix-repl
overlay = final: prev: {
# Modify the previous value of a, available as prev.a
a = prev.a + 10;
# Extend the attribute set with c, letting it depend on the final values of a and b
c = final.a + final.b;
}
```
Use `extends overlay f` to apply the overlay to the fixed-point function `f`.
This produces a new fixed-point function `g` with the combined behavior of `f` and `overlay`:
```nix-repl
g = extends overlay f
```
The result is a function, so we can't print it directly, but it's the same as:
```nix-repl
g' = final: {
# The constant from f, but changed with the overlay
a = 1 + 10;
# Unchanged from f
b = final.a + 2;
# Extended in the overlay
c = final.a + final.b;
}
```
Evaluate this using [`lib.fix`](#function-library-lib.fixedPoints.fix) again to get the final result:
```nix-repl
fix g
=> { a = 11; b = 13; c = 24; }
```
:::
Type:
extends :: (Attrs -> Attrs -> Attrs) # The overlay to apply to the fixed-point function
-> (Attrs -> Attrs) # A fixed-point function
-> (Attrs -> Attrs) # The resulting fixed-point function
Example:
f = final: { a = 1; b = final.a + 2; }
fix f
=> { a = 1; b = 3; }
fix (extends (final: prev: { a = prev.a + 10; }) f)
=> { a = 11; b = 13; }
fix (extends (final: prev: { b = final.a + 5; }) f)
=> { a = 1; b = 6; }
fix (extends (final: prev: { c = final.a + final.b; }) f)
=> { a = 1; b = 3; c = 4; }
*/
extends = f: rattrs: self: let super = rattrs self; in super // f self super;
extends =
# The overlay to apply to the fixed-point function
overlay:
# The fixed-point function
f:
# Wrap with parenthesis to prevent nixdoc from rendering the `final` argument in the documentation
# The result should be thought of as a function, the argument of that function is not an argument to `extends` itself
(
final:
let
prev = f final;
in
prev // overlay final prev
);
/*
Compose two extending functions of the type expected by 'extends'

19
lib/licenses.nix
View File

@ -104,6 +104,7 @@ in mkLicense lset) ({
};
arphicpl = {
spdxId = "Arphic-1999";
fullName = "Arphic Public License";
url = "https://www.freedesktop.org/wiki/Arphic_Public_License/";
};
@ -236,6 +237,7 @@ in mkLicense lset) ({
};
cal10 = {
spdxId = "CAL-1.0";
fullName = "Cryptographic Autonomy License version 1.0 (CAL-1.0)";
url = "https://opensource.org/licenses/CAL-1.0";
};
@ -335,6 +337,11 @@ in mkLicense lset) ({
fullName = "Creative Commons Attribution 1.0";
};
cc-by-20 = {
spdxId = "CC-BY-2.0";
fullName = "Creative Commons Attribution 2.0";
};
cc-by-30 = {
spdxId = "CC-BY-3.0";
fullName = "Creative Commons Attribution 3.0";
@ -434,6 +441,7 @@ in mkLicense lset) ({
};
elastic20 = {
spdxId = "Elastic-2.0";
fullName = "Elastic License 2.0";
url = "https://github.com/elastic/elasticsearch/blob/main/licenses/ELASTIC-LICENSE-2.0.txt";
free = false;
@ -603,6 +611,7 @@ in mkLicense lset) ({
# Intel's license, seems free
iasl = {
spdxId = "Intel-ACPI";
fullName = "iASL";
url = "https://old.calculate-linux.org/packages/licenses/iASL";
};
@ -614,7 +623,7 @@ in mkLicense lset) ({
imagemagick = {
fullName = "ImageMagick License";
spdxId = "imagemagick";
spdxId = "ImageMagick";
};
imlib2 = {
@ -808,6 +817,7 @@ in mkLicense lset) ({
};
miros = {
spdxId = "MirOS";
fullName = "MirOS License";
url = "https://opensource.org/licenses/MirOS";
};
@ -849,6 +859,11 @@ in mkLicense lset) ({
fullName = "Mozilla Public License 2.0";
};
mplus = {
spdxId = "mplus";
fullName = "M+ Font License";
};
mspl = {
spdxId = "MS-PL";
fullName = "Microsoft Public License";
@ -1148,6 +1163,7 @@ in mkLicense lset) ({
};
upl = {
spdxId = "UPL-1.0";
fullName = "Universal Permissive License";
url = "https://oss.oracle.com/licenses/upl/";
};
@ -1204,6 +1220,7 @@ in mkLicense lset) ({
};
xfig = {
spdxId = "Xfig";
fullName = "xfig";
url = "https://mcj.sourceforge.net/authors.html#xfig";
};

37
lib/lists.nix
View File

@ -2,9 +2,8 @@
{ lib }:
let
inherit (lib.strings) toInt;
inherit (lib.trivial) compare min id;
inherit (lib.trivial) compare min id warn;
inherit (lib.attrsets) mapAttrs;
inherit (lib.lists) sort;
in
rec {
@ -172,7 +171,7 @@ rec {
concatMap (x: [x] ++ ["z"]) ["a" "b"]
=> [ "a" "z" "b" "z" ]
*/
concatMap = builtins.concatMap or (f: list: concatLists (map f list));
concatMap = builtins.concatMap;
/* Flatten the argument into a single list; that is, nested lists are
spliced into the top-level lists.
@ -316,7 +315,7 @@ rec {
any isString [ 1 { } ]
=> false
*/
any = builtins.any or (pred: foldr (x: y: if pred x then true else y) false);
any = builtins.any;
/* Return true if function `pred` returns true for all elements of
`list`.
@ -329,7 +328,7 @@ rec {
all (x: x < 3) [ 1 2 3 ]
=> false
*/
all = builtins.all or (pred: foldr (x: y: if pred x then y else false) true);
all = builtins.all;
/* Count how many elements of `list` match the supplied predicate
function.
@ -428,12 +427,7 @@ rec {
partition (x: x > 2) [ 5 1 2 3 4 ]
=> { right = [ 5 3 4 ]; wrong = [ 1 2 ]; }
*/
partition = builtins.partition or (pred:
foldr (h: t:
if pred h
then { right = [h] ++ t.right; wrong = t.wrong; }
else { right = t.right; wrong = [h] ++ t.wrong; }
) { right = []; wrong = []; });
partition = builtins.partition;
/* Splits the elements of a list into many lists, using the return value of a predicate.
Predicate should return a string which becomes keys of attrset `groupBy` returns.
@ -602,22 +596,7 @@ rec {
Type:
sort :: (a -> a -> Bool) -> [a] -> [a]
*/
sort = builtins.sort or (
strictLess: list:
let
len = length list;
first = head list;
pivot' = n: acc@{ left, right }: let el = elemAt list n; next = pivot' (n + 1); in
if n == len
then acc
else if strictLess first el
then next { inherit left; right = [ el ] ++ right; }
else
next { left = [ el ] ++ left; inherit right; };
pivot = pivot' 1 { left = []; right = []; };
in
if len < 2 then list
else (sort strictLess pivot.left) ++ [ first ] ++ (sort strictLess pivot.right));
sort = builtins.sort;
/*
Sort a list based on the default comparison of a derived property `b`.
@ -848,8 +827,8 @@ rec {
crossLists (x:y: "${toString x}${toString y}") [[1 2] [3 4]]
=> [ "13" "14" "23" "24" ]
*/
crossLists = builtins.trace
"lib.crossLists is deprecated, use lib.cartesianProductOfSets instead"
crossLists = warn
"lib.crossLists is deprecated, use lib.cartesianProductOfSets instead."
(f: foldl (fs: args: concatMap (f: map f args) fs) [f]);

8
lib/meta.nix
View File

@ -87,6 +87,10 @@ rec {
We can inject these into a pattern for the whole of a structured platform,
and then match that.
Example:
lib.meta.platformMatch { system = "aarch64-darwin"; } "aarch64-darwin"
=> true
*/
platformMatch = platform: elem: (
# Check with simple string comparison if elem was a string.
@ -112,6 +116,10 @@ rec {
platform, or `meta.platforms` is not present.
2. None of `meta.badPlatforms` pattern matches the given platform.
Example:
lib.meta.availableOn { system = "aarch64-darwin"; } pkg.zsh
=> true
*/
availableOn = platform: pkg:
((!pkg?meta.platforms) || any (platformMatch platform) pkg.meta.platforms) &&

81
lib/modules.nix
View File

@ -81,9 +81,9 @@ let
, # `class`:
# A nominal type for modules. When set and non-null, this adds a check to
# make sure that only compatible modules are imported.
# This would be remove in the future, Prefer _module.args option instead.
class ? null
, args ? {}
, # This would be remove in the future, Prefer _module.args option instead.
args ? {}
, # This would be remove in the future, Prefer _module.check option instead.
check ? true
}:
@ -1256,7 +1256,78 @@ let
(opt.highestPrio or defaultOverridePriority)
(f opt.value);
doRename = { from, to, visible, warn, use, withPriority ? true }:
/*
Return a module that help declares an option that has been renamed.
When a value is defined for the old option, it is forwarded to the `to` option.
*/
doRename = {
# List of strings representing the attribute path of the old option.
from,
# List of strings representing the attribute path of the new option.
to,
# Boolean, whether the old option is to be included in documentation.
visible,
# Whether to warn when a value is defined for the old option.
# NOTE: This requires the NixOS assertions module to be imported, so
# - this generally does not work in submodules
# - this may or may not work outside NixOS
warn,
# A function that is applied to the option value, to form the value
# of the old `from` option.
#
# For example, the identity function can be passed, to return the option value unchanged.
# ```nix
# use = x: x;
# ```
#
# To add a warning, you can pass the partially applied `warn` function.
# ```nix
# use = lib.warn "Obsolete option `${opt.old}' is used. Use `${opt.to}' instead.";
# ```
use,
# Legacy option, enabled by default: whether to preserve the priority of definitions in `old`.
withPriority ? true,
# A boolean that defines the `mkIf` condition for `to`.
# If the condition evaluates to `true`, and the `to` path points into an
# `attrsOf (submodule ...)`, then `doRename` would cause an empty module to
# be created, even if the `from` option is undefined.
# By setting this to an expression that may return `false`, you can inhibit
# this undesired behavior.
#
# Example:
#
# ```nix
# { config, lib, ... }:
# let
# inherit (lib) mkOption mkEnableOption types doRename;
# in
# {
# options = {
#
# # Old service
# services.foo.enable = mkEnableOption "foo";
#
# # New multi-instance service
# services.foos = mkOption {
# type = types.attrsOf (types.submodule …);
# };
# };
# imports = [
# (doRename {
# from = [ "services" "foo" "bar" ];
# to = [ "services" "foos" "" "bar" ];
# visible = true;
# warn = false;
# use = x: x;
# withPriority = true;
# # Only define services.foos."" if needed. (It's not just about `bar`)
# condition = config.services.foo.enable;
# })
# ];
# }
# ```
condition ? true
}:
{ config, options, ... }:
let
fromOpt = getAttrFromPath from options;
@ -1272,7 +1343,7 @@ let
} // optionalAttrs (toType != null) {
type = toType;
});
config = mkMerge [
config = mkIf condition (mkMerge [
(optionalAttrs (options ? warnings) {
warnings = optional (warn && fromOpt.isDefined)
"The option `${showOption from}' defined in ${showFiles fromOpt.files} has been renamed to `${showOption to}'.";
@ -1280,7 +1351,7 @@ let
(if withPriority
then mkAliasAndWrapDefsWithPriority (setAttrByPath to) fromOpt
else mkAliasAndWrapDefinitions (setAttrByPath to) fromOpt)
];
]);
};
/* Use this function to import a JSON file as NixOS configuration.

30
lib/options.nix
View File

@ -254,13 +254,31 @@ rec {
else if all isInt list && all (x: x == head list) list then head list
else throw "Cannot merge definitions of `${showOption loc}'. Definition values:${showDefs defs}";
/*
Require a single definition.
WARNING: Does not perform nested checks, as this does not run the merge function!
*/
mergeOneOption = mergeUniqueOption { message = ""; };
mergeUniqueOption = { message }: loc: defs:
if length defs == 1
then (head defs).value
else assert length defs > 1;
throw "The option `${showOption loc}' is defined multiple times while it's expected to be unique.\n${message}\nDefinition values:${showDefs defs}\n${prioritySuggestion}";
/*
Require a single definition.
NOTE: When the type is not checked completely by check, pass a merge function for further checking (of sub-attributes, etc).
*/
mergeUniqueOption = args@{
message,
# WARNING: the default merge function assumes that the definition is a valid (option) value. You MUST pass a merge function if the return value needs to be
# - type checked beyond what .check does (which should be very litte; only on the value head; not attribute values, etc)
# - if you want attribute values to be checked, or list items
# - if you want coercedTo-like behavior to work
merge ? loc: defs: (head defs).value }:
loc: defs:
if length defs == 1
then merge loc defs
else
assert length defs > 1;
throw "The option `${showOption loc}' is defined multiple times while it's expected to be unique.\n${message}\nDefinition values:${showDefs defs}\n${prioritySuggestion}";
/* "Merge" option definitions by checking that they all have the same value. */
mergeEqualOption = loc: defs:
@ -379,7 +397,7 @@ rec {
if ! isString text then throw "literalExpression expects a string."
else { _type = "literalExpression"; inherit text; };
literalExample = lib.warn "literalExample is deprecated, use literalExpression instead, or use literalMD for a non-Nix description." literalExpression;
literalExample = lib.warn "lib.literalExample is deprecated, use lib.literalExpression instead, or use lib.literalMD for a non-Nix description." literalExpression;
/* Transition marker for documentation that's already migrated to markdown
syntax. This is a no-op and no longer needed.

34
lib/strings.nix
View File

@ -95,8 +95,7 @@ rec {
concatStringsSep "/" ["usr" "local" "bin"]
=> "usr/local/bin"
*/
concatStringsSep = builtins.concatStringsSep or (separator: list:
lib.foldl' (x: y: x + y) "" (intersperse separator list));
concatStringsSep = builtins.concatStringsSep;
/* Maps a function over a list of strings and then concatenates the
result with the specified separator interspersed between
@ -561,7 +560,7 @@ rec {
["&quot;" "&apos;" "&lt;" "&gt;" "&amp;"];
# warning added 12-12-2022
replaceChars = lib.warn "replaceChars is a deprecated alias of replaceStrings, replace usages of it with replaceStrings." builtins.replaceStrings;
replaceChars = lib.warn "lib.replaceChars is a deprecated alias of lib.replaceStrings." builtins.replaceStrings;
# Case conversion utilities.
lowerChars = stringToCharacters "abcdefghijklmnopqrstuvwxyz";
@ -1039,30 +1038,32 @@ rec {
toInt "3.14"
=> error: floating point JSON numbers are not supported
*/
toInt = str:
toInt =
let
matchStripInput = match "[[:space:]]*(-?[[:digit:]]+)[[:space:]]*";
matchLeadingZero = match "0[[:digit:]]+";
in
str:
let
# RegEx: Match any leading whitespace, possibly a '-', one or more digits,
# and finally match any trailing whitespace.
strippedInput = match "[[:space:]]*(-?[[:digit:]]+)[[:space:]]*" str;
strippedInput = matchStripInput str;
# RegEx: Match a leading '0' then one or more digits.
isLeadingZero = match "0[[:digit:]]+" (head strippedInput) == [];
isLeadingZero = matchLeadingZero (head strippedInput) == [];
# Attempt to parse input
parsedInput = fromJSON (head strippedInput);
generalError = "toInt: Could not convert ${escapeNixString str} to int.";
octalAmbigError = "toInt: Ambiguity in interpretation of ${escapeNixString str}"
+ " between octal and zero padded integer.";
in
# Error on presence of non digit characters.
if strippedInput == null
then throw generalError
# Error on presence of leading zero/octal ambiguity.
else if isLeadingZero
then throw octalAmbigError
then throw "toInt: Ambiguity in interpretation of ${escapeNixString str} between octal and zero padded integer."
# Error if parse function fails.
else if !isInt parsedInput
then throw generalError
@ -1090,15 +1091,20 @@ rec {
toIntBase10 "3.14"
=> error: floating point JSON numbers are not supported
*/
toIntBase10 = str:
toIntBase10 =
let
matchStripInput = match "[[:space:]]*0*(-?[[:digit:]]+)[[:space:]]*";
matchZero = match "0+";
in
str:
let
# RegEx: Match any leading whitespace, then match any zero padding,
# capture possibly a '-' followed by one or more digits,
# and finally match any trailing whitespace.
strippedInput = match "[[:space:]]*0*(-?[[:digit:]]+)[[:space:]]*" str;
strippedInput = matchStripInput str;
# RegEx: Match at least one '0'.
isZero = match "0+" (head strippedInput) == [];
isZero = matchZero (head strippedInput) == [];
# Attempt to parse input
parsedInput = fromJSON (head strippedInput);
@ -1133,7 +1139,7 @@ rec {
"/prefix/nix-profiles-library-paths.patch"
"/prefix/compose-search-path.patch" ]
*/
readPathsFromFile = lib.warn "lib.readPathsFromFile is deprecated, use a list instead"
readPathsFromFile = lib.warn "lib.readPathsFromFile is deprecated, use a list instead."
(rootPath: file:
let
lines = lib.splitString "\n" (readFile file);

7
lib/systems/inspect.nix
View File

@ -48,6 +48,7 @@ rec {
isRiscV64 = { cpu = { family = "riscv"; bits = 64; }; };
isRx = { cpu = { family = "rx"; }; };
isSparc = { cpu = { family = "sparc"; }; };
isSparc64 = { cpu = { family = "sparc"; bits = 64; }; };
isWasm = { cpu = { family = "wasm"; }; };
isMsp430 = { cpu = { family = "msp430"; }; };
isVc4 = { cpu = { family = "vc4"; }; };
@ -62,7 +63,8 @@ rec {
is32bit = { cpu = { bits = 32; }; };
is64bit = { cpu = { bits = 64; }; };
isILP32 = map (a: { abi = { abi = a; }; }) [ "n32" "ilp32" "x32" ];
isILP32 = [ { cpu = { family = "wasm"; bits = 32; }; } ] ++
map (a: { abi = { abi = a; }; }) [ "n32" "ilp32" "x32" ];
isBigEndian = { cpu = { significantByte = significantBytes.bigEndian; }; };
isLittleEndian = { cpu = { significantByte = significantBytes.littleEndian; }; };
@ -98,6 +100,9 @@ rec {
{ cpu = { family = "riscv"; }; }
{ cpu = { family = "x86"; }; }
];
isElf = { kernel.execFormat = execFormats.elf; };
isMacho = { kernel.execFormat = execFormats.macho; };
};
# given two patterns, return a pattern which is their logical AND.

68
lib/tests/misc.nix
View File

@ -55,6 +55,24 @@ runTests {
expected = { a = false; b = false; c = true; };
};
testCallPackageWithOverridePreservesArguments =
let
f = { a ? 0, b }: {};
f' = callPackageWith { a = 1; b = 2; } f {};
in {
expr = functionArgs f'.override;
expected = functionArgs f;
};
testCallPackagesWithOverridePreservesArguments =
let
f = { a ? 0, b }: { nested = {}; };
f' = callPackagesWith { a = 1; b = 2; } f {};
in {
expr = functionArgs f'.nested.override;
expected = functionArgs f;
};
# TRIVIAL
testId = {
@ -1902,7 +1920,7 @@ runTests {
expected = true;
};
# lazyDerivation
# DERIVATIONS
testLazyDerivationIsLazyInDerivationForAttrNames = {
expr = attrNames (lazyDerivation {
@ -1955,10 +1973,58 @@ runTests {
expected = derivation;
};
testOptionalDrvAttr = let
mkDerivation = args: derivation (args // {
builder = "builder";
system = "system";
__ignoreNulls = true;
});
in {
expr = (mkDerivation {
name = "foo";
x = optionalDrvAttr true 1;
y = optionalDrvAttr false 1;
}).drvPath;
expected = (mkDerivation {
name = "foo";
x = 1;
}).drvPath;
};
testLazyDerivationMultiOutputReturnsDerivationAttrs = let
derivation = {
type = "derivation";
outputs = ["out" "dev"];
dev = "test dev";
out = "test out";
outPath = "test outPath";
outputName = "out";
drvPath = "test drvPath";
name = "test name";
system = "test system";
meta.position = "/hi:23";
};
in {
expr = lazyDerivation { inherit derivation; outputs = ["out" "dev"]; passthru.meta.position = "/hi:23"; };
expected = derivation;
};
testTypeDescriptionInt = {
expr = (with types; int).description;
expected = "signed integer";
};
testTypeDescriptionIntsPositive = {
expr = (with types; ints.positive).description;
expected = "positive integer, meaning >0";
};
testTypeDescriptionIntsPositiveOrEnumAuto = {
expr = (with types; either ints.positive (enum ["auto"])).description;
expected = ''positive integer, meaning >0, or value "auto" (singular enum)'';
};
testTypeDescriptionListOfPositive = {
expr = (with types; listOf ints.positive).description;
expected = "list of (positive integer, meaning >0)";
};
testTypeDescriptionListOfInt = {
expr = (with types; listOf int).description;
expected = "list of signed integer";

14
lib/tests/modules.sh
View File

@ -101,6 +101,7 @@ checkConfigError 'It seems as if you.re trying to declare an option by placing i
checkConfigError 'It seems as if you.re trying to declare an option by placing it into .config. rather than .options.' config.nest.wrong2 ./error-mkOption-in-config.nix
checkConfigError 'The option .sub.wrong2. does not exist. Definition values:' config.sub ./error-mkOption-in-submodule-config.nix
checkConfigError '.*This can happen if you e.g. declared your options in .types.submodule.' config.sub ./error-mkOption-in-submodule-config.nix
checkConfigError '.*A definition for option .bad. is not of type .non-empty .list of .submodule...\.' config.bad ./error-nonEmptyListOf-submodule.nix
# types.pathInStore
checkConfigOutput '".*/store/0lz9p8xhf89kb1c1kk6jxrzskaiygnlh-bash-5.2-p15.drv"' config.pathInStore.ok1 ./types.nix
@ -406,6 +407,16 @@ checkConfigOutput "{}" config.submodule.a ./emptyValues.nix
checkConfigError 'The option .int.a. is used but not defined' config.int.a ./emptyValues.nix
checkConfigError 'The option .nonEmptyList.a. is used but not defined' config.nonEmptyList.a ./emptyValues.nix
# types.unique
# requires a single definition
checkConfigError 'The option .examples\.merged. is defined multiple times while it.s expected to be unique' config.examples.merged.a ./types-unique.nix
# user message is printed
checkConfigError 'We require a single definition, because seeing the whole value at once helps us maintain critical invariants of our system.' config.examples.merged.a ./types-unique.nix
# let the inner merge function check the values (on demand)
checkConfigError 'A definition for option .examples\.badLazyType\.a. is not of type .string.' config.examples.badLazyType.a ./types-unique.nix
# overriding still works (unlike option uniqueness)
checkConfigOutput '^"bee"$' config.examples.override.b ./types-unique.nix
## types.raw
checkConfigOutput '^true$' config.unprocessedNestingEvaluates.success ./raw.nix
checkConfigOutput "10" config.processedToplevel ./raw.nix
@ -464,6 +475,9 @@ checkConfigOutput '^1234$' config.c.d.e ./doRename-basic.nix
checkConfigOutput '^"The option `a\.b. defined in `.*/doRename-warnings\.nix. has been renamed to `c\.d\.e.\."$' \
config.result \
./doRename-warnings.nix
checkConfigOutput "^true$" config.result ./doRename-condition.nix ./doRename-condition-enable.nix
checkConfigOutput "^true$" config.result ./doRename-condition.nix ./doRename-condition-no-enable.nix
checkConfigOutput "^true$" config.result ./doRename-condition.nix ./doRename-condition-migrated.nix
# Anonymous modules get deduplicated by key
checkConfigOutput '^"pear"$' config.once.raw ./merge-module-with-key.nix

10
lib/tests/modules/doRename-condition-enable.nix Normal file
View File

@ -0,0 +1,10 @@
{ config, lib, ... }:
{
config = {
services.foo.enable = true;
services.foo.bar = "baz";
result =
assert config.services.foos == { "" = { bar = "baz"; }; };
true;
};
}

10
lib/tests/modules/doRename-condition-migrated.nix Normal file
View File

@ -0,0 +1,10 @@
{ config, lib, ... }:
{
config = {
services.foos."".bar = "baz";
result =
assert config.services.foos == { "" = { bar = "baz"; }; };
assert config.services.foo.bar == "baz";
true;
};
}

9
lib/tests/modules/doRename-condition-no-enable.nix Normal file
View File

@ -0,0 +1,9 @@
{ config, lib, options, ... }:
{
config = {
result =
assert config.services.foos == { };
assert ! options.services.foo.bar.isDefined;
true;
};
}

42
lib/tests/modules/doRename-condition.nix Normal file
View File

@ -0,0 +1,42 @@
/*
Simulate a migration from a single-instance `services.foo` to a multi instance
`services.foos.<name>` module, where `name = ""` serves as the legacy /
compatibility instance.
- No instances must exist, unless one is defined in the multi-instance module,
or if the legacy enable option is set to true.
- The legacy instance options must be renamed to the new instance, if it exists.
The relevant scenarios are tested in separate files:
- ./doRename-condition-enable.nix
- ./doRename-condition-no-enable.nix
*/
{ config, lib, ... }:
let
inherit (lib) mkOption mkEnableOption types doRename;
in
{
options = {
services.foo.enable = mkEnableOption "foo";
services.foos = mkOption {
type = types.attrsOf (types.submodule {
options = {
bar = mkOption { type = types.str; };
};
});
default = { };
};
result = mkOption {};
};
imports = [
(doRename {
from = [ "services" "foo" "bar" ];
to = [ "services" "foos" "" "bar" ];
visible = true;
warn = false;
use = x: x;
withPriority = true;
condition = config.services.foo.enable;
})
];
}

7
lib/tests/modules/error-nonEmptyListOf-submodule.nix Normal file
View File

@ -0,0 +1,7 @@
{ lib, ... }:
{
options.bad = lib.mkOption {
type = lib.types.nonEmptyListOf (lib.types.submodule { });
default = [ ];
};
}

27
lib/tests/modules/types-unique.nix Normal file
View File

@ -0,0 +1,27 @@
{ lib, ... }:
let
inherit (lib) mkOption types;
in
{
options.examples = mkOption {
type = types.lazyAttrsOf
(types.unique
{ message = "We require a single definition, because seeing the whole value at once helps us maintain critical invariants of our system."; }
(types.attrsOf types.str));
};
imports = [
{ examples.merged = { b = "bee"; }; }
{ examples.override = lib.mkForce { b = "bee"; }; }
];
config.examples = {
merged = {
a = "aye";
};
override = {
a = "aye";
};
badLazyType = {
a = true;
};
};
}

1
lib/tests/packages-from-directory/c/not-a-namespace/not-a-package.nix
View File

@ -0,0 +1 @@
{ }

1
lib/tests/packages-from-directory/c/support-definitions.nix
View File

@ -0,0 +1 @@
{ }

55
lib/tests/release.nix
View File

@ -9,60 +9,7 @@
let
lib = import ../.;
testWithNix = nix:
pkgs.runCommand "nixpkgs-lib-tests-nix-${nix.version}" {
buildInputs = [
(import ./check-eval.nix)
(import ./maintainers.nix {
inherit pkgs;
lib = import ../.;
})
(import ./teams.nix {
inherit pkgs;
lib = import ../.;
})
(import ../path/tests {
inherit pkgs;
})
];
nativeBuildInputs = [
nix
pkgs.gitMinimal
] ++ lib.optional pkgs.stdenv.isLinux pkgs.inotify-tools;
strictDeps = true;
} ''
datadir="${nix}/share"
export TEST_ROOT=$(pwd)/test-tmp
export HOME=$(mktemp -d)
export NIX_BUILD_HOOK=
export NIX_CONF_DIR=$TEST_ROOT/etc
export NIX_LOCALSTATE_DIR=$TEST_ROOT/var
export NIX_LOG_DIR=$TEST_ROOT/var/log/nix
export NIX_STATE_DIR=$TEST_ROOT/var/nix
export NIX_STORE_DIR=$TEST_ROOT/store
export PAGER=cat
cacheDir=$TEST_ROOT/binary-cache
nix-store --init
cp -r ${../.} lib
echo "Running lib/tests/modules.sh"
bash lib/tests/modules.sh
echo "Running lib/tests/filesystem.sh"
TEST_LIB=$PWD/lib bash lib/tests/filesystem.sh
echo "Running lib/tests/sources.sh"
TEST_LIB=$PWD/lib bash lib/tests/sources.sh
echo "Running lib/fileset/tests.sh"
TEST_LIB=$PWD/lib bash lib/fileset/tests.sh
echo "Running lib/tests/systems.nix"
[[ $(nix-instantiate --eval --strict lib/tests/systems.nix | tee /dev/stderr) == '[ ]' ]];
mkdir $out
echo success > $out/${nix.version}
'';
import ./test-with-nix.nix { inherit lib nix pkgs; };
in
pkgs.symlinkJoin {

76
lib/tests/test-with-nix.nix Normal file
View File

@ -0,0 +1,76 @@
/**
* Instantiate the library tests for a given Nix version.
*
* IMPORTANT:
* This is used by the github.com/NixOS/nix CI.
*
* Try not to change the interface of this file, or if you need to, ping the
* Nix maintainers for help. Thank you!
*/
{
pkgs,
lib,
# Only ever use this nix; see comment at top
nix,
}:
pkgs.runCommand "nixpkgs-lib-tests-nix-${nix.version}" {
buildInputs = [
(import ./check-eval.nix)
(import ./maintainers.nix {
inherit pkgs;
lib = import ../.;
})
(import ./teams.nix {
inherit pkgs;
lib = import ../.;
})
(import ../path/tests {
inherit pkgs;
})
];
nativeBuildInputs = [
nix
pkgs.gitMinimal
] ++ lib.optional pkgs.stdenv.isLinux pkgs.inotify-tools;
strictDeps = true;
} ''
datadir="${nix}/share"
export TEST_ROOT=$(pwd)/test-tmp
export HOME=$(mktemp -d)
export NIX_BUILD_HOOK=
export NIX_CONF_DIR=$TEST_ROOT/etc
export NIX_LOCALSTATE_DIR=$TEST_ROOT/var
export NIX_LOG_DIR=$TEST_ROOT/var/log/nix
export NIX_STATE_DIR=$TEST_ROOT/var/nix
export NIX_STORE_DIR=$TEST_ROOT/store
export PAGER=cat
cacheDir=$TEST_ROOT/binary-cache
nix-store --init
cp -r ${../.} lib
echo "Running lib/tests/modules.sh"
bash lib/tests/modules.sh
echo "Checking lib.version"
nix-instantiate lib -A version --eval || {
echo "lib.version does not evaluate when lib is isolated from the rest of the nixpkgs tree"
exit 1
}
echo "Running lib/tests/filesystem.sh"
TEST_LIB=$PWD/lib bash lib/tests/filesystem.sh
echo "Running lib/tests/sources.sh"
TEST_LIB=$PWD/lib bash lib/tests/sources.sh
echo "Running lib/fileset/tests.sh"
TEST_LIB=$PWD/lib bash lib/fileset/tests.sh
echo "Running lib/tests/systems.nix"
[[ $(nix-instantiate --eval --strict lib/tests/systems.nix | tee /dev/stderr) == '[ ]' ]];
mkdir $out
echo success > $out/${nix.version}
''

25
lib/trivial.nix
View File

@ -95,21 +95,6 @@ in {
/* boolean “and” */
and = x: y: x && y;
/* bitwise “and” */
bitAnd = builtins.bitAnd
or (import ./zip-int-bits.nix
(a: b: if a==1 && b==1 then 1 else 0));
/* bitwise “or” */
bitOr = builtins.bitOr
or (import ./zip-int-bits.nix
(a: b: if a==1 || b==1 then 1 else 0));
/* bitwise “xor” */
bitXor = builtins.bitXor
or (import ./zip-int-bits.nix
(a: b: if a!=b then 1 else 0));
/* bitwise “not” */
bitNot = builtins.sub (-1);
@ -165,8 +150,8 @@ in {
inherit (builtins)
pathExists readFile isBool
isInt isFloat add sub lessThan
seq deepSeq genericClosure;
seq deepSeq genericClosure
bitAnd bitOr bitXor;
## nixpkgs version strings
@ -174,7 +159,7 @@ in {
version = release + versionSuffix;
/* Returns the current nixpkgs release number as string. */
release = lib.strings.fileContents ../.version;
release = lib.strings.fileContents ./.version;
/* The latest release that is supported, at the time of release branch-off,
if applicable.
@ -189,7 +174,7 @@ in {
they take effect as soon as the oldest release reaches end of life. */
oldestSupportedRelease =
# Update on master only. Do not backport.
2305;
2311;
/* Whether a feature is supported in all supported releases (at the time of
release branch-off, if applicable). See `oldestSupportedRelease`. */
@ -230,7 +215,7 @@ in {
else if lib.pathExists revisionFile then lib.fileContents revisionFile
else default;
nixpkgsVersion = builtins.trace "`lib.nixpkgsVersion` is deprecated, use `lib.version` instead!" version;
nixpkgsVersion = warn "lib.nixpkgsVersion is a deprecated alias of lib.version." version;
/* Determine whether the function is being called from inside a Nix
shell.

38
lib/types.nix
View File

@ -113,9 +113,14 @@ rec {
, # Description of the type, defined recursively by embedding the wrapped type if any.
description ? null
# A hint for whether or not this description needs parentheses. Possible values:
# - "noun": a simple noun phrase such as "positive integer"
# - "conjunction": a phrase with a potentially ambiguous "or" connective.
# - "noun": a noun phrase
# Example description: "positive integer",
# - "conjunction": a phrase with a potentially ambiguous "or" connective
# Example description: "int or string"
# - "composite": a phrase with an "of" connective
# Example description: "list of string"
# - "nonRestrictiveClause": a noun followed by a comma and a clause
# Example description: "positive integer, meaning >0"
# See the `optionDescriptionPhrase` function.
, descriptionClass ? null
, # DO NOT USE WITHOUT KNOWING WHAT YOU ARE DOING!
@ -338,10 +343,12 @@ rec {
unsigned = addCheck types.int (x: x >= 0) // {
name = "unsignedInt";
description = "unsigned integer, meaning >=0";
descriptionClass = "nonRestrictiveClause";
};
positive = addCheck types.int (x: x > 0) // {
name = "positiveInt";
description = "positive integer, meaning >0";
descriptionClass = "nonRestrictiveClause";
};
u8 = unsign 8 256;
u16 = unsign 16 65536;
@ -383,10 +390,12 @@ rec {
nonnegative = addCheck number (x: x >= 0) // {
name = "numberNonnegative";
description = "nonnegative integer or floating point number, meaning >=0";
descriptionClass = "nonRestrictiveClause";
};
positive = addCheck number (x: x > 0) // {
name = "numberPositive";
description = "positive integer or floating point number, meaning >0";
descriptionClass = "nonRestrictiveClause";
};
};
@ -463,6 +472,7 @@ rec {
passwdEntry = entryType: addCheck entryType (str: !(hasInfix ":" str || hasInfix "\n" str)) // {
name = "passwdEntry ${entryType.name}";
description = "${optionDescriptionPhrase (class: class == "noun") entryType}, not containing newlines or colons";
descriptionClass = "nonRestrictiveClause";
};
attrs = mkOptionType {
@ -547,6 +557,7 @@ rec {
in list // {
description = "non-empty ${optionDescriptionPhrase (class: class == "noun") list}";
emptyValue = { }; # no .value attr, meaning unset
substSubModules = m: nonEmptyListOf (elemType.substSubModules m);
};
attrsOf = elemType: mkOptionType rec {
@ -603,23 +614,12 @@ rec {
nestedTypes.elemType = elemType;
};
# Value of given type but with no merging (i.e. `uniq list`s are not concatenated).
uniq = elemType: mkOptionType rec {
name = "uniq";
inherit (elemType) description descriptionClass check;
merge = mergeOneOption;
emptyValue = elemType.emptyValue;
getSubOptions = elemType.getSubOptions;
getSubModules = elemType.getSubModules;
substSubModules = m: uniq (elemType.substSubModules m);
functor = (defaultFunctor name) // { wrapped = elemType; };
nestedTypes.elemType = elemType;
};
uniq = unique { message = ""; };
unique = { message }: type: mkOptionType rec {
name = "unique";
inherit (type) description descriptionClass check;
merge = mergeUniqueOption { inherit message; };
merge = mergeUniqueOption { inherit message; inherit (type) merge; };
emptyValue = type.emptyValue;
getSubOptions = type.getSubOptions;
getSubModules = type.getSubModules;
@ -870,7 +870,13 @@ rec {
# Either value of type `t1` or `t2`.
either = t1: t2: mkOptionType rec {
name = "either";
description = "${optionDescriptionPhrase (class: class == "noun" || class == "conjunction") t1} or ${optionDescriptionPhrase (class: class == "noun" || class == "conjunction" || class == "composite") t2}";
description =
if t1.descriptionClass or null == "nonRestrictiveClause"
then
# Plain, but add comma
"${t1.description}, or ${optionDescriptionPhrase (class: class == "noun" || class == "conjunction") t2}"
else
"${optionDescriptionPhrase (class: class == "noun" || class == "conjunction") t1} or ${optionDescriptionPhrase (class: class == "noun" || class == "conjunction" || class == "composite") t2}";
descriptionClass = "conjunction";
check = x: t1.check x || t2.check x;
merge = loc: defs:

2
lib/versions.nix
View File

@ -9,7 +9,7 @@ rec {
splitVersion "1.2.3"
=> ["1" "2" "3"]
*/
splitVersion = builtins.splitVersion or (lib.splitString ".");
splitVersion = builtins.splitVersion;
/* Get the major version string from a string.

39
lib/zip-int-bits.nix
View File

@ -1,39 +0,0 @@
/* Helper function to implement a fallback for the bit operators
`bitAnd`, `bitOr` and `bitXor` on older nix version.
See ./trivial.nix
*/
f: x: y:
let
# (intToBits 6) -> [ 0 1 1 ]
intToBits = x:
if x == 0 || x == -1 then
[]
else
let
headbit = if (x / 2) * 2 != x then 1 else 0; # x & 1
tailbits = if x < 0 then ((x + 1) / 2) - 1 else x / 2; # x >> 1
in
[headbit] ++ (intToBits tailbits);
# (bitsToInt [ 0 1 1 ] 0) -> 6
# (bitsToInt [ 0 1 0 ] 1) -> -6
bitsToInt = l: signum:
if l == [] then
(if signum == 0 then 0 else -1)
else
(builtins.head l) + (2 * (bitsToInt (builtins.tail l) signum));
xsignum = if x < 0 then 1 else 0;
ysignum = if y < 0 then 1 else 0;
zipListsWith' = fst: snd:
if fst==[] && snd==[] then
[]
else if fst==[] then
[(f xsignum (builtins.head snd))] ++ (zipListsWith' [] (builtins.tail snd))
else if snd==[] then
[(f (builtins.head fst) ysignum )] ++ (zipListsWith' (builtins.tail fst) [] )
else
[(f (builtins.head fst) (builtins.head snd))] ++ (zipListsWith' (builtins.tail fst) (builtins.tail snd));
in
assert (builtins.isInt x) && (builtins.isInt y);
bitsToInt (zipListsWith' (intToBits x) (intToBits y)) (f xsignum ysignum)

1159
maintainers/maintainer-list.nix
View File

File diff suppressed because it is too large Load Diff

85
maintainers/scripts/bootstrap-files/README.md Normal file
View File

@ -0,0 +1,85 @@
# Bootstrap files
Currently `nixpkgs` builds most of it's packages using bootstrap seed
binaries (without the reliance on external inputs):
- `bootstrap-tools`: an archive with the compiler toolchain and other
helper tools enough to build the rest of the `nixpkgs`.
- initial binaries needed to unpack `bootstrap-tools.*`. On `linux`
it's just `busybox`, on `darwin` it's `sh`, `bzip2`, `mkdir` and
`cpio`. These binaries can be executed directly from the store.
These are called "bootstrap files".
Bootstrap files should always be fetched from hydra and uploaded to
`tarballs.nixos.org` to guarantee that all the binaries were built from
the code committed into `nixpkgs` repository.
The uploads to `tarballs.nixos.org` are done by `@lovesegfault` today.
This document describes the procedure of updating bootstrap files in
`nixpkgs`.
## How to request the bootstrap seed update
To get the tarballs updated let's use an example `i686-unknown-linux-gnu`
target:
1. Create a local update:
```
$ maintainers/scripts/bootstrap-files/refresh-tarballs.bash --commit --targets=i686-unknown-linux-gnu
```
2. Test the update locally. I'll build local `hello` derivation with
the result:
```
$ nix-build -A hello --argstr system i686-linux
```
To validate cross-targets `binfmt` `NixOS` helper can be useful.
For `riscv64-unknown-linux-gnu` the `/etc/nixos/configuration.nix`
entry would be `boot.binfmt.emulatedSystems = [ "riscv64-linux" ]`.
3. Propose the commit as a PR to update bootstrap tarballs, tag people
who can help you test the updated architecture and once reviewed tag
`@lovesegfault` to upload the tarballs.
## Bootstrap files job definitions
There are two types of bootstrap files:
- natively built `stdenvBootstrapTools.build` hydra jobs in
[`nixpkgs:trunk`](https://hydra.nixos.org/jobset/nixpkgs/trunk#tabs-jobs)
jobset. Incomplete list of examples is:
* `aarch64-unknown-linux-musl.nix`
* `i686-unknown-linux-gnu.nix`
These are Tier 1 hydra platforms.
- cross-built by `bootstrapTools.build` hydra jobs in
[`nixpkgs:cross-trunk`](https://hydra.nixos.org/jobset/nixpkgs/cross-trunk#tabs-jobs)
jobset. Incomplete list of examples is:
* `mips64el-unknown-linux-gnuabi64.nix`
* `mips64el-unknown-linux-gnuabin32.nix`
* `mipsel-unknown-linux-gnu.nix`
* `powerpc64le-unknown-linux-gnu.nix`
* `riscv64-unknown-linux-gnu.nix`
These are usually Tier 2 and lower targets.
The `.build` job contains `/on-server/` subdirectory with binaries to
be uploaded to `tarballs.nixos.org`.
The files are uploaded to `tarballs.nixos.org` by writers to `S3` store.
## TODOs
- `pkgs/stdenv/darwin` file layout is slightly different from
`pkgs/stdenv/linux`. Once `linux` seed update becomes a routine we can
bring `darwin` in sync if it's feasible.
- `darwin` definition of `.build` `on-server/` directory layout differs
and should be updated.

282
maintainers/scripts/bootstrap-files/refresh-tarballs.bash Executable file
View File

@ -0,0 +1,282 @@
#!/usr/bin/env nix-shell
#! nix-shell --pure
#! nix-shell -i bash
#! nix-shell -p curl cacert
#! nix-shell -p git
#! nix-shell -p nix
#! nix-shell -p jq
# How the refresher works:
#
# For a given list of <targets>:
# 1. fetch latest successful '.build` job
# 2. fetch oldest evaluation that contained that '.build', extract nixpkgs commit
# 3. fetch all the `.build` artifacts from '$out/on-server/' directory
# 4. calculate hashes and craft the commit message with the details on
# how to upload the result to 'tarballs.nixos.org'
usage() {
cat >&2 <<EOF
Usage:
$0 [ --commit ] --targets=<target>[,<target>,...]
The tool must be ran from the root directory of 'nixpkgs' repository.
Synopsis:
'refresh-tarballs.bash' script fetches latest bootstrapFiles built
by hydra, registers them in 'nixpkgs' and provides commands to
upload seed files to 'tarballs.nixos.org'.
This is usually done in the following cases:
1. Single target fix: current bootstrap files for a single target
are problematic for some reason (target-specific bug). In this
case we can refresh just that target as:
\$ $0 --commit --targets=i686-unknown-linux-gnu
2. Routine refresh: all bootstrap files should be refreshed to avoid
debugging problems that only occur on very old binaries.
\$ $0 --commit --all-targets
To get help on uploading refreshed binaries to 'tarballs.nixos.org'
please have a look at <maintainers/scripts/bootstrap-files/README.md>.
EOF
exit 1
}
# log helpers
die() {
echo "ERROR: $*" >&2
exit 1
}
info() {
echo "INFO: $*" >&2
}
[[ ${#@} -eq 0 ]] && usage
# known targets
NATIVE_TARGETS=(
aarch64-unknown-linux-gnu
aarch64-unknown-linux-musl
i686-unknown-linux-gnu
x86_64-unknown-linux-gnu
x86_64-unknown-linux-musl
# TODO: add darwin here once a few prerequisites are satisfied:
# - bootstrap-files are factored out into a separate file
# - the build artifacts are factored out into an `on-server`
# directory. Right onw if does not match `linux` layout.
#
#aarch64-apple-darwin
#x86_64-apple-darwin
)
is_native() {
local t target=$1
for t in "${NATIVE_TARGETS[@]}"; do
[[ $t == $target ]] && return 0
done
return 1
}
CROSS_TARGETS=(
armv5tel-unknown-linux-gnueabi
armv6l-unknown-linux-gnueabihf
armv6l-unknown-linux-musleabihf
armv7l-unknown-linux-gnueabihf
mips64el-unknown-linux-gnuabi64
mips64el-unknown-linux-gnuabin32
mipsel-unknown-linux-gnu
powerpc64le-unknown-linux-gnu
riscv64-unknown-linux-gnu
)
is_cross() {
local t target=$1
for t in "${CROSS_TARGETS[@]}"; do
[[ $t == $target ]] && return 0
done
return 1
}
# collect passed options
targets=()
commit=no
for arg in "$@"; do
case "$arg" in
--all-targets)
targets+=(
${CROSS_TARGETS[@]}
${NATIVE_TARGETS[@]}
)
;;
--targets=*)
# Convert "--targets=a,b,c" to targets=(a b c) bash array.
comma_targets=${arg#--targets=}
targets+=(${comma_targets//,/ })
;;
--commit)
commit=yes
;;
*)
usage
;;
esac
done
for target in "${targets[@]}"; do
# Native and cross jobsets differ a bit. We'll have to pick the
# one based on target name:
if is_native $target; then
jobset=nixpkgs/trunk
job="stdenvBootstrapTools.${target}.build"
elif is_cross $target; then
jobset=nixpkgs/cross-trunk
job="bootstrapTools.${target}.build"
else
die "'$target' is not present in either of 'NATIVE_TARGETS' or 'CROSS_TARGETS'. Please add one."
fi
# 'nixpkgs' prefix where we will write new tarball hashes
case "$target" in
*linux*) nixpkgs_prefix="pkgs/stdenv/linux" ;;
*darwin*) nixpkgs_prefix="pkgs/stdenv/darwin" ;;
*) die "don't know where to put '$target'" ;;
esac
# We enforce s3 prefix for all targets here. This slightly differs
# from manual uploads targets where names were chosen inconsistently.
s3_prefix="stdenv/$target"
# resolve 'latest' build to the build 'id', construct the link.
latest_build_uri="https://hydra.nixos.org/job/$jobset/$job/latest"
latest_build="$target.latest-build"
info "Fetching latest successful build from '${latest_build_uri}'"
curl -s -H "Content-Type: application/json" -L "$latest_build_uri" > "$latest_build"
[[ $? -ne 0 ]] && die "Failed to fetch latest successful build"
latest_build_id=$(jq '.id' < "$latest_build")
[[ $? -ne 0 ]] && die "Did not find 'id' in latest build"
build_uri="https://hydra.nixos.org/build/${latest_build_id}"
# We pick oldest jobset evaluation and extract the 'nicpkgs' commit.
#
# We use oldest instead of latest to make the result more stable
# across unrelated 'nixpkgs' updates. Ideally two subsequent runs of
# this refresher should produce the same output (provided there are
# no bootstrapTools updates committed between the two runs).
oldest_eval_id=$(jq '.jobsetevals|min' < "$latest_build")
[[ $? -ne 0 ]] && die "Did not find 'jobsetevals' in latest build"
eval_uri="https://hydra.nixos.org/eval/${oldest_eval_id}"
eval_meta="$target.eval-meta"
info "Fetching oldest eval details from '${eval_uri}' (can take a minute)"
curl -s -H "Content-Type: application/json" -L "${eval_uri}" > "$eval_meta"
[[ $? -ne 0 ]] && die "Failed to fetch eval metadata"
nixpkgs_revision=$(jq --raw-output ".jobsetevalinputs.nixpkgs.revision" < "$eval_meta")
[[ $? -ne 0 ]] && die "Failed to fetch revision"
# Extract the build paths out of the build metadata
drvpath=$(jq --raw-output '.drvpath' < "${latest_build}")
[[ $? -ne 0 ]] && die "Did not find 'drvpath' in latest build"
outpath=$(jq --raw-output '.buildoutputs.out.path' < "${latest_build}")
[[ $? -ne 0 ]] && die "Did not find 'buildoutputs' in latest build"
build_timestamp=$(jq --raw-output '.timestamp' < "${latest_build}")
[[ $? -ne 0 ]] && die "Did not find 'timestamp' in latest build"
build_time=$(TZ=UTC LANG=C date --date="@${build_timestamp}" --rfc-email)
[[ $? -ne 0 ]] && die "Failed to format timestamp"
info "Fetching bootstrap tools to calculate hashes from '${outpath}'"
nix-store --realize "$outpath"
[[ $? -ne 0 ]] && die "Failed to fetch '${outpath}' from hydra"
fnames=()
target_file="${nixpkgs_prefix}/bootstrap-files/${target}.nix"
info "Writing '${target_file}'"
{
# header
cat <<EOF
# Autogenerated by maintainers/scripts/bootstrap-files/refresh-tarballs.bash as:
# $ ./refresh-tarballs.bash --targets=${target}
#
# Metadata:
# - nixpkgs revision: ${nixpkgs_revision}
# - hydra build: ${latest_build_uri}
# - resolved hydra build: ${build_uri}
# - instantiated derivation: ${drvpath}
# - output directory: ${outpath}
# - build time: ${build_time}
{
EOF
for p in "${outpath}/on-server"/*; do
fname=$(basename "$p")
fnames+=("$fname")
case "$fname" in
bootstrap-tools.tar.xz) attr=bootstrapTools ;;
busybox) attr=$fname ;;
*) die "Don't know how to map '$fname' to attribute name. Please update me."
esac
executable_arg=
executable_nix=
if [[ -x "$p" ]]; then
executable_arg="--executable"
executable_nix=" executable = true;"
fi
sha256=$(nix-prefetch-url $executable_arg --name "$fname" "file://$p")
[[ $? -ne 0 ]] && die "Failed to get the hash for '$p'"
sri=$(nix-hash --to-sri "sha256:$sha256")
[[ $? -ne 0 ]] && die "Failed to convert '$sha256' hash to an SRI form"
# individual file entries
cat <<EOF
$attr = import <nix/fetchurl.nix> {
url = "http://tarballs.nixos.org/${s3_prefix}/${nixpkgs_revision}/$fname";
hash = "${sri}";$(printf "\n%s" "${executable_nix}")
};
EOF
done
# footer
cat <<EOF
}
EOF
} > "${target_file}"
target_file_commit_msg=${target}.commit_message
cat > "$target_file_commit_msg" <<EOF
${nixpkgs_prefix}: update ${target} bootstrap-files
sha256sum of files to be uploaded:
$(
echo "$ sha256sum ${outpath}/on-server/*"
sha256sum ${outpath}/on-server/*
)
Suggested commands to upload files to 'tarballs.nixos.org':
$ nix-store --realize ${outpath}
$ aws s3 cp --recursive --acl public-read ${outpath}/on-server/ s3://nixpkgs-tarballs/${s3_prefix}/${nixpkgs_revision}
$ aws s3 cp --recursive s3://nixpkgs-tarballs/${s3_prefix}/${nixpkgs_revision} ./
$ sha256sum ${fnames[*]}
$ sha256sum ${outpath}/on-server/*
EOF
cat "$target_file_commit_msg"
if [[ $commit == yes ]]; then
git commit "${target_file}" -F "$target_file_commit_msg"
else
info "DRY RUN: git commit ${target_file} -F $target_file_commit_msg"
fi
rm -- "$target_file_commit_msg"
# delete temp files
rm -- "$latest_build" "$eval_meta"
done

4
maintainers/scripts/haskell/merge-and-open-pr.sh
View File

@ -54,8 +54,8 @@ if ! gh auth status 2>/dev/null ; then
fi
# Make sure this is configured before we start doing anything
push_remote="$(git config branch.haskell-updates.pushRemote \
|| die 'Can'\''t determine pushRemote for haskell-updates. Please set using `git config branch.haskell-updates.pushremote <remote name>`.')"
push_remote="$(git config branch.haskell-updates.pushRemote)" \
|| die 'Can'\''t determine pushRemote for haskell-updates. Please set using `git config branch.haskell-updates.pushremote <remote name>`.'
# Fetch nixpkgs to get an up-to-date origin/haskell-updates branch.
echo "Fetching origin..."

5
maintainers/scripts/haskell/update-stackage.sh
View File

@ -7,8 +7,11 @@ set -eu -o pipefail
# Stackage solver to use, LTS or Nightly
# (should be capitalized like the display name)
SOLVER=LTS
# Stackage solver verson, if any. Use latest if empty
VERSION=21
TMP_TEMPLATE=update-stackage.XXXXXXX
readonly SOLVER
readonly VERSION
readonly TMP_TEMPLATE
toLower() {
@ -23,7 +26,7 @@ stackage_config="pkgs/development/haskell-modules/configuration-hackage2nix/stac
trap 'rm "${tmpfile}" "${tmpfile_new}"' 0
touch "$tmpfile" "$tmpfile_new" # Creating files here so that trap creates no errors.
curl -L -s "https://stackage.org/$(toLower "$SOLVER")/cabal.config" >"$tmpfile"
curl -L -s "https://stackage.org/$(toLower "$SOLVER")${VERSION:+-$VERSION}/cabal.config" >"$tmpfile"
old_version=$(grep '^# Stackage' $stackage_config | sed -e 's/.\+ \([A-Za-z]\+ [0-9.-]\+\)$/\1/g')
version="$SOLVER $(sed -rn "s/^--.*http:..(www.)?stackage.org.snapshot.$(toLower "$SOLVER")-//p" "$tmpfile")"

31
maintainers/scripts/kde/collect-licenses.sh Executable file
View File

@ -0,0 +1,31 @@
#!/usr/bin/env nix-shell
#!nix-shell -i bash -p gnutar jq reuse
set -eu
cd "$(dirname "$(readlink -f "$0")")"/../../..
TMPDIR=$(mktemp -d)
trap 'rm -rf $TMPDIR' EXIT
echo "# Prebuilding sources..."
nix-build -A kdePackages.sources --no-link || true
echo "# Evaluating sources..."
declare -A sources
eval "$(nix-instantiate --eval -A kdePackages.sources --json --strict | jq 'to_entries[] | "sources[" + .key + "]=" + .value' -r)"
echo "# Collecting licenses..."
for k in "${!sources[@]}"; do
echo "- Processing $k..."
if [ ! -f "${sources[$k]}" ]; then
echo "Not found!"
continue
fi
mkdir "$TMPDIR/$k"
tar -C "$TMPDIR/$k" -xf "${sources[$k]}"
(cd "$TMPDIR/$k"; reuse lint --json) | jq --arg name "$k" '{$name: .summary.used_licenses | sort}' -c > "$TMPDIR/$k.json"
done
jq -s 'add' -S "$TMPDIR"/*.json > pkgs/kde/generated/licenses.json

11
maintainers/scripts/kde/collect-logs.nu Executable file
View File

@ -0,0 +1,11 @@
#!/usr/bin/env nix-shell
#!nix-shell -i nu -p nushell
cd $"($env.FILE_PWD)/../../.."
mkdir logs
nix-env -qaP -f . -A kdePackages --json --out-path | from json | values | par-each { |it|
echo $"Processing ($it.pname)..."
if "outputs" in $it {
nix-store --read-log $it.outputs.out | save -f $"logs/($it.pname).log"
}
}

36
maintainers/scripts/kde/collect-metadata.py Executable file
View File

@ -0,0 +1,36 @@
#!/usr/bin/env nix-shell
#!nix-shell -i python3 -p "python3.withPackages(ps: [ ps.click ps.pyyaml ])"
import pathlib
import click
import utils
@click.command
@click.argument(
"repo-metadata",
type=click.Path(
exists=True,
file_okay=False,
resolve_path=True,
path_type=pathlib.Path,
),
)
@click.option(
"--nixpkgs",
type=click.Path(
exists=True,
file_okay=False,
resolve_path=True,
writable=True,
path_type=pathlib.Path,
),
default=pathlib.Path(__file__).parent.parent.parent.parent
)
def main(repo_metadata: pathlib.Path, nixpkgs: pathlib.Path):
metadata = utils.KDERepoMetadata.from_repo_metadata_checkout(repo_metadata)
out_dir = nixpkgs / "pkgs/kde/generated"
metadata.write_json(out_dir)
if __name__ == "__main__":
main() # type: ignore

127
maintainers/scripts/kde/collect-missing-deps.py Executable file
View File

@ -0,0 +1,127 @@
#!/usr/bin/env nix-shell
#!nix-shell -i python3 -p python3
import pathlib
OK_MISSING = {
# we don't use precompiled QML
'Qt6QuickCompiler',
'Qt6QmlCompilerPlusPrivate',
# usually used for version numbers
'Git',
# useless by itself, will warn if something else is not found
'PkgConfig',
# license verification
'ReuseTool',
# dev only
'ClangFormat',
# doesn't exist
'Qt6X11Extras',
}
OK_MISSING_BY_PACKAGE = {
"angelfish": {
"Qt6Feedback", # we don't have it
},
"attica": {
"Python3", # only used for license checks
},
"discover": {
"rpm-ostree-1", # we don't have rpm-ostree (duh)
"Snapd", # we don't have snaps and probably never will
},
"elisa": {
"UPNPQT", # upstream says it's broken
},
"extra-cmake-modules": {
"Sphinx", # only used for docs, bloats closure size
"QCollectionGenerator"
},
"kio-extras-kf5": {
"KDSoapWSDiscoveryClient", # actually vendored on KF5 version
},
"kitinerary": {
"OsmTools", # used for map data updates, we use prebuilt
},
"kosmindoormap": {
"OsmTools", # same
"Protobuf",
},
"kpty": {
"UTEMPTER", # we don't have it and it probably wouldn't work anyway
},
"kpublictransport": {
"OsmTools", # same
"PolyClipping",
"Protobuf",
},
"krfb": {
"Qt6XkbCommonSupport", # not real
},
"kuserfeedback": {
"Qt6Svg", # all used for backend console stuff we don't ship
"QmlLint",
"Qt6Charts",
"FLEX",
"BISON",
"Php",
"PhpUnit",
},
"kwin": {
"display-info", # newer versions identify as libdisplay-info
},
"mlt": {
"Qt5", # intentionally disabled
"SWIG",
},
"plasma-desktop": {
"scim", # upstream is dead, not packaged in Nixpkgs
},
"powerdevil": {
"DDCUtil", # cursed, intentionally disabled
},
"pulseaudio-qt": {
"Qt6Qml", # tests only
"Qt6Quick",
},
"syntax-highlighting": {
"XercesC", # only used for extra validation at build time
}
}
def main():
here = pathlib.Path(__file__).parent.parent.parent.parent
logs = (here / "logs").glob("*.log")
for log in sorted(logs):
pname = log.stem
missing = []
is_in_block = False
with log.open(errors="replace") as fd:
for line in fd:
line = line.strip()
if line.startswith("-- No package '"):
package = line.removeprefix("-- No package '").removesuffix("' found")
missing.append(package)
if line == "-- The following OPTIONAL packages have not been found:" or line == "-- The following RECOMMENDED packages have not been found:":
is_in_block = True
elif line.startswith("--") and is_in_block:
is_in_block = False
elif line.startswith("*") and is_in_block:
package = line.removeprefix("* ")
missing.append(package)
missing = {
package
for package in missing
if not any(package.startswith(i) for i in OK_MISSING | OK_MISSING_BY_PACKAGE.get(pname, set()))
}
if missing:
print(pname + ":")
for line in missing:
print(" -", line)
print()
if __name__ == '__main__':
main()

113
maintainers/scripts/kde/generate-sources.py Executable file
View File

@ -0,0 +1,113 @@
#!/usr/bin/env nix-shell
#!nix-shell -i python3 -p "python3.withPackages(ps: [ ps.beautifulsoup4 ps.click ps.httpx ps.jinja2 ps.pyyaml ])
import base64
import binascii
import json
import pathlib
from urllib.parse import urlparse
import bs4
import click
import httpx
import jinja2
import utils
LEAF_TEMPLATE = jinja2.Template('''
{mkKdeDerivation}:
mkKdeDerivation {
pname = "{{ pname }}";
}
'''.strip())
ROOT_TEMPLATE = jinja2.Template('''
{callPackage}: {
{%- for p in packages %}
{{ p }} = callPackage ./{{ p }} {};
{%- endfor %}
}
'''.strip());
def to_sri(hash):
raw = binascii.unhexlify(hash)
b64 = base64.b64encode(raw).decode()
return f"sha256-{b64}"
@click.command
@click.argument(
"set",
type=click.Choice(["frameworks", "gear", "plasma"]),
required=True
)
@click.argument(
"version",
type=str,
required=True
)
@click.option(
"--nixpkgs",
type=click.Path(
exists=True,
file_okay=False,
resolve_path=True,
writable=True,
path_type=pathlib.Path,
),
default=pathlib.Path(__file__).parent.parent.parent.parent
)
def main(set: str, version: str, nixpkgs: pathlib.Path):
root_dir = nixpkgs / "pkgs/kde"
set_dir = root_dir / set
generated_dir = root_dir / "generated"
metadata = utils.KDERepoMetadata.from_json(generated_dir)
set_url = {
"frameworks": "kf",
"gear": "releases",
"plasma": "plasma",
}[set]
sources = httpx.get(f"https://kde.org/info/sources/source-{set_url}-{version}.html")
sources.raise_for_status()
bs = bs4.BeautifulSoup(sources.text, features="html.parser")
results = {}
for item in bs.select("tr")[1:]:
link = item.select_one("td:nth-child(1) a")
assert link
hash = item.select_one("td:nth-child(3) tt")
assert hash
project_name, version = link.text.rsplit("-", maxsplit=1)
if project_name not in metadata.projects_by_name:
print(f"Warning: unknown tarball: {project_name}")
results[project_name] = {
"version": version,
"url": "mirror://kde" + urlparse(link.attrs["href"]).path,
"hash": to_sri(hash.text)
}
pkg_dir = set_dir / project_name
pkg_file = pkg_dir / "default.nix"
if not pkg_file.exists():
print(f"Generated new package: {set}/{project_name}")
pkg_dir.mkdir(parents=True, exist_ok=True)
with pkg_file.open("w") as fd:
fd.write(LEAF_TEMPLATE.render(pname=project_name) + "\n")
set_dir.mkdir(parents=True, exist_ok=True)
with (set_dir / "default.nix").open("w") as fd:
fd.write(ROOT_TEMPLATE.render(packages=sorted(results.keys())) + "\n")
sources_dir = generated_dir / "sources"
sources_dir.mkdir(parents=True, exist_ok=True)
with (sources_dir / f"{set}.json").open("w") as fd:
json.dump(results, fd, indent=2)
if __name__ == "__main__":
main() # type: ignore

Some files were not shown because too many files have changed in this diff Show More