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

Merge branch 'NixOS:master' into swww

Browse Source
This commit is contained in:
Mateo Diaz 2023-02-03 22:08:25 -08:00 committed by GitHub
commit 3bbb6e1413
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12773 changed files with 299049 additions and 255657 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
.editorconfig
View File

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

1
.gitattributes vendored
View File

@ -1,4 +1,5 @@
**/deps.nix linguist-generated
**/deps.json linguist-generated
**/node-packages.nix linguist-generated
pkgs/applications/editors/emacs-modes/*-generated.nix linguist-generated

26
.github/CODEOWNERS vendored
View File

@ -28,6 +28,7 @@
/lib/cli.nix @edolstra @nbp @Profpatsch
/lib/debug.nix @edolstra @nbp @Profpatsch
/lib/asserts.nix @edolstra @nbp @Profpatsch
/lib/path.* @infinisil @fricklerhandwerk
# Nixpkgs Internals
/default.nix @nbp
@ -48,6 +49,10 @@
# Nixpkgs build-support
/pkgs/build-support/writers @lassulus @Profpatsch
# Nixpkgs make-disk-image
/doc/builders/images/makediskimage.section.md @raitobezarius
/nixos/lib/make-disk-image.nix @raitobezarius
# Nixpkgs documentation
/maintainers/scripts/db-to-md.sh @jtojnar @ryantm
/maintainers/scripts/doc @jtojnar @ryantm
@ -78,6 +83,8 @@
/nixos/doc/manual/man-nixos-option.xml @nbp
/nixos/modules/installer/tools/nixos-option.sh @nbp
/nixos/modules/system @dasJ
/nixos/modules/system/activation/bootspec.nix @grahamc @cole-h @raitobezarius
/nixos/modules/system/activation/bootspec.cue @grahamc @cole-h @raitobezarius
# NixOS integration test driver
/nixos/lib/test-driver @tfc
@ -100,7 +107,7 @@
/pkgs/top-level/python-packages.nix @FRidh @jonringer
/pkgs/development/interpreters/python @FRidh
/pkgs/development/python-modules @FRidh @jonringer
/doc/languages-frameworks/python.section.md @FRidh
/doc/languages-frameworks/python.section.md @FRidh @mweinelt
/pkgs/development/tools/poetry2nix @adisbladis
/pkgs/development/interpreters/python/hooks @FRidh @jonringer
@ -127,7 +134,9 @@
/pkgs/development/ruby-modules @marsam
# Rust
/pkgs/development/compilers/rust @Mic92 @LnL7 @zowoq
/pkgs/development/compilers/rust @Mic92 @LnL7 @zowoq @winterqt @figsoda
/pkgs/build-support/rust @zowoq @winterqt @figsoda
/doc/languages-frameworks/rust.section.md @zowoq @winterqt @figsoda
# C compilers
/pkgs/development/compilers/gcc @matthewbauer
@ -146,6 +155,11 @@
# Browsers
/pkgs/applications/networking/browsers/firefox @mweinelt
# Certificate Authorities
pkgs/data/misc/cacert/ @ajs124 @lukegb @mweinelt
pkgs/development/libraries/nss/ @ajs124 @lukegb @mweinelt
pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt
# Jetbrains
/pkgs/applications/editors/jetbrains @edwtjo
@ -219,10 +233,10 @@
/pkgs/top-level/emacs-packages.nix @adisbladis
# Neovim
/pkgs/applications/editors/neovim @jonringer @teto
/pkgs/applications/editors/neovim @figsoda @jonringer @teto
# VimPlugins
/pkgs/applications/editors/vim/plugins @jonringer
/pkgs/applications/editors/vim/plugins @figsoda @jonringer
# VsCode Extensions
/pkgs/applications/editors/vscode/extensions @jonringer
@ -263,6 +277,7 @@
# GNOME
/pkgs/desktops/gnome @jtojnar
/pkgs/desktops/gnome/extensions @piegamesde @jtojnar
/pkgs/build-support/make-hardcode-gsettings-patch @jtojnar
# Cinnamon
/pkgs/desktops/cinnamon @mkg20001
@ -284,11 +299,8 @@
# Matrix
/pkgs/servers/heisenbridge @piegamesde
/pkgs/servers/matrix-conduit @piegamesde
/pkgs/servers/matrix-synapse/matrix-appservice-irc @piegamesde
/nixos/modules/services/misc/heisenbridge.nix @piegamesde
/nixos/modules/services/misc/matrix-appservice-irc.nix @piegamesde
/nixos/modules/services/misc/matrix-conduit.nix @piegamesde
/nixos/tests/matrix-appservice-irc.nix @piegamesde
/nixos/tests/matrix-conduit.nix @piegamesde
# Dotnet

2
.github/ISSUE_TEMPLATE/unreproducible_package.md vendored
View File

@ -2,7 +2,7 @@
name: Unreproducible package
about: A package that does not produce a bit-by-bit reproducible result each time it is built
title: ''
labels: '0.kind: enhancement', '6.topic: reproducible builds'
labels: [ '0.kind: enhancement', '6.topic: reproducible builds' ]
assignees: ''
---

2
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

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

18
.github/labeler.yml vendored
View File

@ -19,6 +19,11 @@
- pkgs/build-support/emacs/**/*
- pkgs/top-level/emacs-packages.nix
"6.topic: Enlightenment DE":
- nixos/modules/services/x11/desktop-managers/enlightenment.nix
- pkgs/desktops/enlightenment/**/*
- pkgs/development/python-modules/python-efl/*
"6.topic: erlang":
- doc/languages-frameworks/beam.section.md
- pkgs/development/beam-modules/**/*
@ -65,6 +70,19 @@
- pkgs/development/lua-modules/**/*
- pkgs/top-level/lua-packages.nix
"6.topic: Lumina DE":
- nixos/modules/services/x11/desktop-managers/lumina.nix
- pkgs/desktops/lumina/**/*
"6.topic: LXQt":
- nixos/modules/services/x11/desktop-managers/lxqt.nix
- pkgs/desktops/lxqt/**/*
"6.topic: mate":
- nixos/modules/services/x11/desktop-managers/mate.nix
- nixos/tests/mate.nix
- pkgs/desktops/mate/**/*
"6.topic: nixos":
- nixos/**/*
- pkgs/os-specific/linux/nixos-rebuild/**/*

12
.github/workflows/backport.yml vendored
View File

@ -14,23 +14,19 @@ permissions:
jobs:
backport:
permissions:
contents: write # for zeebe-io/backport-action to create branch
pull-requests: write # for zeebe-io/backport-action to create PR to backport
contents: write # for korthout/backport-action to create branch
pull-requests: write # for korthout/backport-action to create PR to backport
name: Backport Pull Request
if: github.repository_owner == 'NixOS' && github.event.pull_request.merged == true && (github.event_name != 'labeled' || startsWith('backport', github.event.label.name))
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
# required to find all branches
fetch-depth: 0
ref: ${{ github.event.pull_request.head.sha }}
- name: Create backport PRs
uses: zeebe-io/backport-action@v0.0.8
uses: korthout/backport-action@v1.1.0
with:
# Config README: https://github.com/zeebe-io/backport-action#backport-action
github_token: ${{ secrets.GITHUB_TOKEN }}
github_workspace: ${{ github.workspace }}
# Config README: https://github.com/korthout/backport-action#backport-action
pull_description: |-
Bot-based backport to `${target_branch}`, triggered by a label in #${pull_number}.

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

@ -11,7 +11,7 @@ on:
jobs:
tests:
runs-on: ubuntu-latest
if: "github.repository_owner == 'NixOS' && !contains(github.event.pull_request.title, '[skip editorconfig]')"
if: "github.repository_owner == 'NixOS' && !contains(github.event.pull_request.title, '[skip treewide]')"
steps:
- name: Get list of changed files from PR
env:

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

@ -16,7 +16,7 @@ permissions:
jobs:
labels:
runs-on: ubuntu-latest
if: github.repository_owner == 'NixOS'
if: "github.repository_owner == 'NixOS' && !contains(github.event.pull_request.title, '[skip treewide]')"
steps:
- uses: actions/labeler@v4
with:

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

@ -38,10 +38,6 @@ jobs:
into: staging-next-22.11
- from: staging-next-22.11
into: staging-22.11
- from: release-22.05
into: staging-next-22.05
- from: staging-next-22.05
into: staging-22.05
name: ${{ matrix.pairs.from }} → ${{ matrix.pairs.into }}
steps:
- uses: actions/checkout@v3

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

@ -11,8 +11,8 @@ permissions:
jobs:
tf-providers:
permissions:
contents: write # for peter-evans/create-pull-request to create branch
pull-requests: write # for peter-evans/create-pull-request to create a PR, for peter-evans/create-or-update-comment to create or update comment
contents: write # for peter-evans/create-pull-request to create branch
pull-requests: write # for peter-evans/create-pull-request to create a PR, for peter-evans/create-or-update-comment to create or update comment
if: github.repository_owner == 'NixOS' && github.ref == 'refs/heads/master' # ensure workflow_dispatch only runs on master
runs-on: ubuntu-latest
steps:
@ -25,6 +25,8 @@ jobs:
run: |
echo "title=terraform-providers: update $(date -u +"%Y-%m-%d")" >> $GITHUB_OUTPUT
- name: update terraform-providers
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git config user.name "github-actions[bot]"

2
.gitignore vendored
View File

@ -2,6 +2,8 @@
,*
.*.swp
.*.swo
.\#*
\#*\#
.idea/
.vscode/
outputs/

13
.mailmap
View File

@ -1,3 +1,14 @@
ajs124 <git@ajs124.de> <ajs124@users.noreply.github.com>
Anderson Torres <torres.anderson.85@protonmail.com>
Daniel Løvbrøtte Olsen <me@dandellion.xyz> <daniel.olsen99@gmail.com>
Fabian Affolter <mail@fabian-affolter.ch> <fabian@affolter-engineering.ch>
Janne Heß <janne@hess.ooo> <dasJ@users.noreply.github.com>
Jörg Thalheim <joerg@thalheim.io> <Mic92@users.noreply.github.com>
Martin Weinelt <hexa@darmstadt.ccc.de> <mweinelt@users.noreply.github.com>
R. RyanTM <ryantm-bot@ryantm.com>
Sandro <sandro.jaeckel@gmail.com>
Robert Hensing <robert@roberthensing.nl> <roberth@users.noreply.github.com>
Sandro Jäckel <sandro.jaeckel@gmail.com>
Sandro Jäckel <sandro.jaeckel@gmail.com> <sandro.jaeckel@sap.com>
superherointj <5861043+superherointj@users.noreply.github.com>
Vladimír Čunát <v@cunat.cz> <vcunat@gmail.com>
Vladimír Čunát <v@cunat.cz> <vladimir.cunat@nic.cz>

25
CONTRIBUTING.md
View File

@ -38,11 +38,14 @@ Below is a short excerpt of some points in there:
The old config generation system used impure shell scripts and could break in specific circumstances (see #1234).
* `meta.description` should:
* Be short, just one sentence.
* Be capitalized.
* Not start with the package name.
* Not have a period at the end.
* More generally, it should not refer to the package name.
* Not end with a period (or any punctuation for that matter).
* `meta.license` must be set and fit the upstream license.
* If there is no upstream license, `meta.license` should default to `lib.licenses.unfree`.
* If in doubt, try to contact the upstream developers for clarification.
* `meta.maintainers` must be set.
See the nixpkgs manual for more details on [standard meta-attributes](https://nixos.org/nixpkgs/manual/#sec-standard-meta-attributes).
@ -53,6 +56,10 @@ In addition to writing properly formatted commit messages, it's important to inc
Package version upgrades usually allow for simpler commit messages, including attribute name, old and new version, as well as a reference to the relevant release notes/changelog. Every once in a while a package upgrade requires more extensive changes, and that subsequently warrants a more verbose message.
Pull requests should not be squash merged in order to keep complete commit messages and GPG signatures intact and must not be when the change doesn't make sense as a single commit.
This means that, when addressing review comments in order to keep the pull request in an always mergeable status, you will sometimes need to rewrite your branch's history and then force-push it with `git push --force-with-lease`.
Useful git commands that can help a lot with this are `git commit --patch --amend` and `git rebase --interactive`. For more details consult the git man pages or online resources like [git-rebase.io](https://git-rebase.io/) or [The Pro Git Book](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History).
## Rebasing between branches (i.e. from master to staging)
From time to time, changes between branches must be rebased, for example, if the
@ -98,17 +105,17 @@ git push origin feature --force-with-lease
Follow these steps to backport a change into a release branch in compliance with the [commit policy](https://nixos.org/nixpkgs/manual/#submitting-changes-stable-release-branches).
You can add a label such as `backport release-22.05` to a PR, so that merging it will
You can add a label such as `backport release-22.11` to a PR, so that merging it will
automatically create a backport (via [a GitHub Action](.github/workflows/backport.yml)).
This also works for PR's that have already been merged, and might take a couple of minutes to trigger.
You can also create the backport manually:
1. Take note of the commits in which the change was introduced into `master` branch.
2. Check out the target _release branch_, e.g. `release-22.05`. Do not use a _channel branch_ like `nixos-22.05` or `nixpkgs-22.05-darwin`.
2. Check out the target _release branch_, e.g. `release-22.11`. Do not use a _channel branch_ like `nixos-22.11` or `nixpkgs-22.11-darwin`.
3. Create a branch for your change, e.g. `git checkout -b backport`.
4. When the reason to backport is not obvious from the original commit message, use `git cherry-pick -xe <original commit>` and add a reason. Otherwise use `git cherry-pick -x <original commit>`. That's fine for minor version updates that only include security and bug fixes, commits that fixes an otherwise broken package or similar. Please also ensure the commits exists on the master branch; in the case of squashed or rebased merges, the commit hash will change and the new commits can be found in the merge message at the bottom of the master pull request.
5. Push to GitHub and open a backport pull request. Make sure to select the release branch (e.g. `release-22.05`) as the target branch of the pull request, and link to the pull request in which the original change was comitted to `master`. The pull request title should be the commit title with the release version as prefix, e.g. `[22.05]`.
5. Push to GitHub and open a backport pull request. Make sure to select the release branch (e.g. `release-22.11`) as the target branch of the pull request, and link to the pull request in which the original change was committed to `master`. The pull request title should be the commit title with the release version as prefix, e.g. `[22.11]`.
6. When the backport pull request is merged and you have the necessary privileges you can also replace the label `9.needs: port to stable` with `8.has: port to stable` on the original pull request. This way maintainers can keep track of missing backports easier.
## Criteria for Backporting changes
@ -120,15 +127,15 @@ Anything that does not cause user or downstream dependency regressions can be ba
- Services which require a client to be up-to-date regardless. (E.g. `spotify`, `steam`, or `discord`)
- Security critical applications (E.g. `firefox`)
## Generating 22.11 Release Notes
## Generating 23.05 Release Notes
Documentation in nixpkgs is transitioning to a markdown-centric workflow. Release notes now require a translation step to convert from markdown to a compatible docbook document.
Steps for updating 22.11 Release notes:
Steps for updating 23.05 Release notes:
1. Edit `nixos/doc/manual/release-notes/rl-2211.section.md` with the desired changes
2. Run `./nixos/doc/manual/md-to-db.sh` to render `nixos/doc/manual/from_md/release-notes/rl-2211.section.xml`
3. Include changes to `rl-2211.section.md` and `rl-2211.section.xml` in the same commit.
1. Edit `nixos/doc/manual/release-notes/rl-2305.section.md` with the desired changes
2. Run `./nixos/doc/manual/md-to-db.sh` to render `nixos/doc/manual/from_md/release-notes/rl-2305.section.xml`
3. Include changes to `rl-2305.section.md` and `rl-2305.section.xml` in the same commit.
## Reviewing contributions

2
COPYING
View File

@ -1,4 +1,4 @@
Copyright (c) 2003-2022 Eelco Dolstra and the Nixpkgs/NixOS contributors
Copyright (c) 2003-2023 Eelco Dolstra and the Nixpkgs/NixOS contributors
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the

4
README.md
View File

@ -51,9 +51,9 @@ Nixpkgs and NixOS are built and tested by our continuous integration
system, [Hydra](https://hydra.nixos.org/).
* [Continuous package builds for unstable/master](https://hydra.nixos.org/jobset/nixos/trunk-combined)
* [Continuous package builds for the NixOS 22.05 release](https://hydra.nixos.org/jobset/nixos/release-22.05)
* [Continuous package builds for the NixOS 22.11 release](https://hydra.nixos.org/jobset/nixos/release-22.11)
* [Tests for unstable/master](https://hydra.nixos.org/job/nixos/trunk-combined/tested#tabs-constituents)
* [Tests for the NixOS 22.05 release](https://hydra.nixos.org/job/nixos/release-22.05/tested#tabs-constituents)
* [Tests for the NixOS 22.11 release](https://hydra.nixos.org/job/nixos/release-22.11/tested#tabs-constituents)
Artifacts successfully built with Hydra are published to cache at
https://cache.nixos.org/. When successful build and test criteria are

2
doc/Makefile
View File

@ -11,7 +11,7 @@ pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracket
pandoc_flags = --extract-media=$(pandoc_media_dir) \
--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \
--lua-filter=build-aux/pandoc-filters/link-unix-man-references.lua \
--lua-filter=$(PANDOC_LINK_MANPAGES_FILTER) \
--lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
--lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \
-f commonmark$(pandoc_commonmark_enabled_extensions)+smart

28
doc/build-aux/pandoc-filters/link-manpages.nix Normal file
View File

@ -0,0 +1,28 @@
{ pkgs ? import ../../.. {} }:
let
inherit (pkgs) lib;
manpageURLs = builtins.fromJSON (builtins.readFile (pkgs.path + "/doc/manpage-urls.json"));
in pkgs.writeText "link-manpages.lua" ''
--[[
Adds links to known man pages that aren't already in a link.
]]
local manpage_urls = {
${lib.concatStringsSep "\n" (lib.mapAttrsToList (man: url:
" [${builtins.toJSON man}] = ${builtins.toJSON url},") manpageURLs)}
}
traverse = 'topdown'
-- Returning false as the second value aborts processing of child elements.
function Link(elem)
return elem, false
end
function Code(elem)
local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'
if is_man_role and manpage_urls[elem.text] ~= nil then
return pandoc.Link(elem, manpage_urls[elem.text]), false
end
end
''

17
doc/build-aux/pandoc-filters/link-unix-man-references.lua
View File

@ -1,17 +0,0 @@
--[[
Turns a manpage reference into a link, when a mapping is defined below.
]]
local man_urls = {
["tmpfiles.d(5)"] = "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html",
["nix.conf(5)"] = "https://nixos.org/manual/nix/stable/#sec-conf-file",
["systemd.time(7)"] = "https://www.freedesktop.org/software/systemd/man/systemd.time.html",
["systemd.timer(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.timer.html",
}
function Code(elem)
local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'
if is_man_role and man_urls[elem.text] ~= nil then
return pandoc.Link(elem, man_urls[elem.text])
end
end

13
doc/build-aux/pandoc-filters/myst-reader/roles.lua
View File

@ -17,9 +17,16 @@ function Inlines(inlines)
if correct_tags then
-- docutils supports alphanumeric strings separated by [-._:]
-- We are slightly more liberal for simplicity.
local role = first.text:match('^{([-._+:%w]+)}$')
if role ~= nil then
inlines:remove(i)
-- Allow preceding punctuation (eg '('), otherwise '({file}`...`)'
-- does not match. Also allow anything followed by a non-breaking space
-- since pandoc emits those after certain abbreviations (e.g. e.g.).
local prefix, role = first.text:match('^(.*){([-._+:%w]+)}$')
if role ~= nil and (prefix == '' or prefix:match("^.*[%p ]$") ~= nil) then
if prefix == '' then
inlines:remove(i)
else
first.text = prefix
end
second.attributes['role'] = role
second.classes:insert('interpreted-text')
end

34
doc/builders/fetchers.chapter.md
View File

@ -14,7 +14,7 @@ For example, consider the following fetcher:
```nix
fetchurl {
url = "http://www.example.org/hello-1.0.tar.gz";
sha256 = "0v6r3wwnsk5pdjr188nip3pjgn1jrn5pc5ajpcfy6had6b3v4dwm";
hash = "sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww=";
};
```
@ -23,17 +23,17 @@ A common mistake is to update a fetcher’s URL, or a version parameter, without
```nix
fetchurl {
url = "http://www.example.org/hello-1.1.tar.gz";
sha256 = "0v6r3wwnsk5pdjr188nip3pjgn1jrn5pc5ajpcfy6had6b3v4dwm";
hash = "sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww=";
};
```
**This will reuse the old contents**.
Remember to invalidate the hash argument, in this case by setting the `sha256` attribute to an empty string.
Remember to invalidate the hash argument, in this case by setting the `hash` attribute to an empty string.
```nix
fetchurl {
url = "http://www.example.org/hello-1.1.tar.gz";
sha256 = "";
hash = "";
};
```
@ -42,14 +42,14 @@ Use the resulting error message to determine the correct hash.
```
error: hash mismatch in fixed-output derivation '/path/to/my.drv':
specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
got: sha256-RApQUm78dswhBLC/rfU9y0u6pSAzHceIJqgmetRD24E=
got: sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww=
```
A similar problem arises while testing changes to a fetcher's implementation. If the output of the derivation already exists in the Nix store, test failures can go undetected. The [`invalidateFetcherByDrvHash`](#tester-invalidateFetcherByDrvHash) function helps prevent reusing cached derivations.
## `fetchurl` and `fetchzip` {#fetchurl}
Two basic fetchers are `fetchurl` and `fetchzip`. Both of these have two required arguments, a URL and a hash. The hash is typically `sha256`, although many more hash algorithms are supported. Nixpkgs contributors are currently recommended to use `sha256`. This hash will be used by Nix to identify your source. A typical usage of `fetchurl` is provided below.
Two basic fetchers are `fetchurl` and `fetchzip`. Both of these have two required arguments, a URL and a hash. The hash is typically `hash`, although many more hash algorithms are supported. Nixpkgs contributors are currently recommended to use `hash`. This hash will be used by Nix to identify your source. A typical usage of `fetchurl` is provided below.
```nix
{ stdenv, fetchurl }:
@ -58,7 +58,7 @@ stdenv.mkDerivation {
name = "hello";
src = fetchurl {
url = "http://www.example.org/hello.tar.gz";
sha256 = "1111111111111111111111111111111111111111111111111111";
hash = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";
};
}
```
@ -76,18 +76,18 @@ The main difference between `fetchurl` and `fetchzip` is in how they store the c
- `includes`: Include only files matching these patterns (applies after the above arguments).
- `revert`: Revert the patch.
Note that because the checksum is computed after applying these effects, using or modifying these arguments will have no effect unless the `sha256` argument is changed as well.
Note that because the checksum is computed after applying these effects, using or modifying these arguments will have no effect unless the `hash` argument is changed as well.
Most other fetchers return a directory rather than a single file.
## `fetchsvn` {#fetchsvn}
Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `sha256`.
Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `hash`.
## `fetchgit` {#fetchgit}
Used with Git. Expects `url` to a Git repo, `rev`, and `sha256`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`.
Used with Git. Expects `url` to a Git repo, `rev`, and `hash`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`.
Additionally, the following optional arguments can be given: `fetchSubmodules = true` makes `fetchgit` also fetch the submodules of a repository. If `deepClone` is set to true, the entire repository is cloned as opposing to just creating a shallow clone. `deepClone = true` also implies `leaveDotGit = true` which means that the `.git` directory of the clone won't be removed after checkout.
@ -104,32 +104,32 @@ stdenv.mkDerivation {
"directory/to/be/included"
"another/directory"
];
sha256 = "0000000000000000000000000000000000000000000000000000";
hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
};
}
```
## `fetchfossil` {#fetchfossil}
Used with Fossil. Expects `url` to a Fossil archive, `rev`, and `sha256`.
Used with Fossil. Expects `url` to a Fossil archive, `rev`, and `hash`.
## `fetchcvs` {#fetchcvs}
Used with CVS. Expects `cvsRoot`, `tag`, and `sha256`.
Used with CVS. Expects `cvsRoot`, `tag`, and `hash`.
## `fetchhg` {#fetchhg}
Used with Mercurial. Expects `url`, `rev`, and `sha256`.
Used with Mercurial. Expects `url`, `rev`, and `hash`.
A number of fetcher functions wrap part of `fetchurl` and `fetchzip`. They are mainly convenience functions intended for commonly used destinations of source code in Nixpkgs. These wrapper fetchers are listed below.
## `fetchFromGitea` {#fetchfromgitea}
`fetchFromGitea` expects five arguments. `domain` is the gitea server name. `owner` is a string corresponding to the Gitea user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every Gitea HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `sha256` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available but `sha256` is currently preferred.
`fetchFromGitea` expects five arguments. `domain` is the gitea server name. `owner` is a string corresponding to the Gitea user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every Gitea HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available but `hash` is currently preferred.
## `fetchFromGitHub` {#fetchfromgithub}
`fetchFromGitHub` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `sha256` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `sha256` is currently preferred.
`fetchFromGitHub` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `hash` is currently preferred.
`fetchFromGitHub` uses `fetchzip` to download the source archive generated by GitHub for the specified revision. If `leaveDotGit`, `deepClone` or `fetchSubmodules` are set to `true`, `fetchFromGitHub` will use `fetchgit` instead. Refer to its section for documentation of these options.
@ -156,7 +156,7 @@ This is used with repo.or.cz repositories. The arguments expected are very simil
## `fetchFromSourcehut` {#fetchfromsourcehut}
This is used with sourcehut repositories. Similar to `fetchFromGitHub` above,
it expects `owner`, `repo`, `rev` and `sha256`, but don't forget the tilde (~)
it expects `owner`, `repo`, `rev` and `hash`, but don't forget the tilde (~)
in front of the username! Expected arguments also include `vc` ("git" (default)
or "hg"), `domain` and `fetchSubmodules`.

1
doc/builders/images.xml
View File

@ -10,4 +10,5 @@
<xi:include href="images/ocitools.section.xml" />
<xi:include href="images/snaptools.section.xml" />
<xi:include href="images/portableservice.section.xml" />
<xi:include href="images/makediskimage.section.xml" />
</chapter>

2
doc/builders/images/appimagetools.section.md
View File

@ -35,7 +35,7 @@ appimageTools.wrapType2 { # or wrapType1
name = "patchwork";
src = fetchurl {
url = "https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage";
sha256 = "1blsprpkvm0ws9b96gb36f0rbf8f5jgmw4x6dsb1kswr4ysf591s";
hash = "sha256-OqTitCeZ6xmWbqYTXp8sDrmVgTNjPZNW0hzUPW++mq4=";
};
extraPkgs = pkgs: with pkgs; [ ];
}

151
doc/builders/images/dockertools.section.md
View File

@ -62,6 +62,8 @@ The above example will build a Docker image `redis/latest` from the given base i
- `config` is used to specify the configuration of the containers that will be started off the built image in Docker. The available options are listed in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions).
- `architecture` is _optional_ and used to specify the image architecture, this is useful for multi-architecture builds that don't need cross compiling. If not specified it will default to `hostPlatform`.
- `diskSize` is used to specify the disk size of the VM used to build the image in megabytes. By default it's 1024 MiB.
- `buildVMMemorySize` is used to specify the memory size of the VM to build the image in megabytes. By default it's 512 MiB.
@ -141,7 +143,9 @@ Create a Docker image with many of the store paths being on their own layer to i
`config` _optional_
: Run-time configuration of the container. A full list of the options are available at in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions).
`architecture` is _optional_ and used to specify the image architecture, this is useful for multi-architecture builds that don't need cross compiling. If not specified it will default to `hostPlatform`.
: Run-time configuration of the container. A full list of the options available is in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions).
*Default:* `{}`
@ -245,10 +249,10 @@ Its parameters are described in the example below:
pullImage {
imageName = "nixos/nix";
imageDigest =
"sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b";
"sha256:473a2b527958665554806aea24d0131bacec46d23af09fef4598eeab331850fa";
finalImageName = "nix";
finalImageTag = "1.11";
sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8";
finalImageTag = "2.11.1";
sha256 = "sha256-qvhj+Hlmviz+KEBVmsyPIzTB3QlVAFzwAY1zDPIBGxc=";
os = "linux";
arch = "x86_64";
}
@ -394,3 +398,142 @@ buildImage {
};
}
```
## buildNixShellImage {#ssec-pkgs-dockerTools-buildNixShellImage}
Create a Docker image that sets up an environment similar to that of running `nix-shell` on a derivation.
When run in Docker, this environment somewhat resembles the Nix sandbox typically used by `nix-build`, with a major difference being that access to the internet is allowed.
It additionally also behaves like an interactive `nix-shell`, running things like `shellHook` and setting an interactive prompt.
If the derivation is fully buildable (i.e. `nix-build` can be used on it), running `buildDerivation` inside such a Docker image will build the derivation, with all its outputs being available in the correct `/nix/store` paths, pointed to by the respective environment variables like `$out`, etc.
::: {.warning}
The behavior doesn't match `nix-shell` or `nix-build` exactly and this function is known not to work correctly for e.g. fixed-output derivations, content-addressed derivations, impure derivations and other special types of derivations.
:::
### Arguments
`drv`
: The derivation on which to base the Docker image.
Adding packages to the Docker image is possible by e.g. extending the list of `nativeBuildInputs` of this derivation like
```nix
buildNixShellImage {
drv = someDrv.overrideAttrs (old: {
nativeBuildInputs = old.nativeBuildInputs or [] ++ [
somethingExtra
];
});
# ...
}
```
Similarly, you can extend the image initialization script by extending `shellHook`
`name` _optional_
: The name of the resulting image.
*Default:* `drv.name + "-env"`
`tag` _optional_
: Tag of the generated image.
*Default:* the resulting image derivation output path's hash
`uid`/`gid` _optional_
: The user/group ID to run the container as. This is like a `nixbld` build user.
*Default:* 1000/1000
`homeDirectory` _optional_
: The home directory of the user the container is running as
*Default:* `/build`
`shell` _optional_
: The path to the `bash` binary to use as the shell. This shell is started when running the image.
*Default:* `pkgs.bashInteractive + "/bin/bash"`
`command` _optional_
: Run this command in the environment of the derivation, in an interactive shell. See the `--command` option in the [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html?highlight=nix-shell#options).
*Default:* (none)
`run` _optional_
: Same as `command`, but runs the command in a non-interactive shell instead. See the `--run` option in the [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html?highlight=nix-shell#options).
*Default:* (none)
### Example
The following shows how to build the `pkgs.hello` package inside a Docker container built with `buildNixShellImage`.
```nix
with import <nixpkgs> {};
dockerTools.buildNixShellImage {
drv = hello;
}
```
Build the derivation:
```console
nix-build hello.nix
```
these 8 derivations will be built:
/nix/store/xmw3a5ln29rdalavcxk1w3m4zb2n7kk6-nix-shell-rc.drv
...
Creating layer 56 from paths: ['/nix/store/crpnj8ssz0va2q0p5ibv9i6k6n52gcya-stdenv-linux']
Creating layer 57 with customisation...
Adding manifests...
Done.
/nix/store/cpyn1lc897ghx0rhr2xy49jvyn52bazv-hello-2.12-env.tar.gz
Load the image:
```console
docker load -i result
```
0d9f4c4cd109: Loading layer [==================================================>] 2.56MB/2.56MB
...
ab1d897c0697: Loading layer [==================================================>] 10.24kB/10.24kB
Loaded image: hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz
Run the container:
```console
docker run -it hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz
```
[nix-shell:/build]$
In the running container, run the build:
```console
buildDerivation
```
unpacking sources
unpacking source archive /nix/store/8nqv6kshb3vs5q5bs2k600xpj5bkavkc-hello-2.12.tar.gz
...
patching script interpreter paths in /nix/store/z5wwy5nagzy15gag42vv61c2agdpz2f2-hello-2.12
checking for references to /build/ in /nix/store/z5wwy5nagzy15gag42vv61c2agdpz2f2-hello-2.12...
Check the build result:
```console
$out/bin/hello
```
Hello, world!

107
doc/builders/images/makediskimage.section.md Normal file
View File

@ -0,0 +1,107 @@
# `<nixpkgs/nixos/lib/make-disk-image.nix>` {#sec-make-disk-image}
`<nixpkgs/nixos/lib/make-disk-image.nix>` is a function to create _disk images_ in multiple formats: raw, QCOW2 (QEMU), QCOW2-Compressed (compressed version), VDI (VirtualBox), VPC (VirtualPC).
This function can create images in two ways:
- using `cptofs` without any virtual machine to create a Nix store disk image,
- using a virtual machine to create a full NixOS installation.
When testing early-boot or lifecycle parts of NixOS such as a bootloader or multiple generations, it is necessary to opt for a full NixOS system installation.
Whereas for many web servers, applications, it is possible to work with a Nix store only disk image and is faster to build.
NixOS tests also use this function when preparing the VM. The `cptofs` method is used when `virtualisation.useBootLoader` is false (the default). Otherwise the second method is used.
## Features
For reference, read the function signature source code for documentation on arguments: <https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/make-disk-image.nix>.
Features are separated in various sections depending on if you opt for a Nix-store only image or a full NixOS image.
### Common
- arbitrary NixOS configuration
- automatic or bound disk size: `diskSize` parameter, `additionalSpace` can be set when `diskSize` is `auto` to add a constant of disk space
- multiple partition table layouts: EFI, legacy, legacy + GPT, hybrid, none through `partitionTableType` parameter
- OVMF or EFI firmwares and variables templates can be customized
- root filesystem `fsType` can be customized to whatever `mkfs.${fsType}` exist during operations
- root filesystem label can be customized, defaults to `nix-store` if it's a Nix store image, otherwise `nixpkgs/nixos`
- arbitrary code can be executed after disk image was produced with `postVM`
- the current nixpkgs can be realized as a channel in the disk image, which will change the hash of the image when the sources are updated
- additional store paths can be provided through `additionalPaths`
### Full NixOS image
- arbitrary contents with permissions can be placed in the target filesystem using `contents`
- a `/etc/nixpkgs/nixos/configuration.nix` can be provided through `configFile`
- bootloaders are supported
- EFI variables can be mutated during image production and the result is exposed in `$out`
- boot partition size when partition table is `efi` or `hybrid`
### On bit-to-bit reproducibility
Images are **NOT** deterministic, please do not hesitate to try to fix this, source of determinisms are (not exhaustive) :
- bootloader installation have timestamps
- SQLite Nix store database contain registration times
- `/etc/shadow` is in a non-deterministic order
A `deterministic` flag is available for best efforts determinism.
## Usage
To produce a Nix-store only image:
```nix
let
pkgs = import <nixpkgs> {};
lib = pkgs.lib;
make-disk-image = import <nixpkgs/nixos/lib/make-disk-image.nix>;
in
make-disk-image {
inherit pkgs lib;
config = {};
additionalPaths = [ ];
format = "qcow2";
onlyNixStore = true;
partitionTableType = "none";
installBootLoader = false;
touchEFIVars = false;
diskSize = "auto";
additionalSpace = "0M"; # Defaults to 512M.
copyChannel = false;
}
```
Some arguments can be left out, they are shown explicitly for the sake of the example.
Building this derivation will provide a QCOW2 disk image containing only the Nix store and its registration information.
To produce a NixOS installation image disk with UEFI and bootloader installed:
```nix
let
pkgs = import <nixpkgs> {};
lib = pkgs.lib;
make-disk-image = import <nixpkgs/nixos/lib/make-disk-image.nix>;
evalConfig = import <nixpkgs/nixos/lib/eval-config.nix>;
in
make-disk-image {
inherit pkgs lib;
config = evalConfig {
modules = [
{
fileSystems."/" = { device = "/dev/vda"; fsType = "ext4"; autoFormat = true; };
boot.grub.device = "/dev/vda";
}
];
};
format = "qcow2";
onlyNixStore = false;
partitionTableType = "legacy+gpt";
installBootLoader = true;
touchEFIVars = true;
diskSize = "auto";
additionalSpace = "0M"; # Defaults to 512M.
copyChannel = false;
}
```

2
doc/builders/images/ocitools.section.md
View File

@ -34,4 +34,4 @@ buildContainer {
- `mounts` specifies additional mount points chosen by the user. By default only a minimal set of necessary filesystems are mounted into the container (e.g procfs, cgroupfs)
- `readonly` makes the container\'s rootfs read-only if it is set to true. The default value is false `false`.
- `readonly` makes the container's rootfs read-only if it is set to true. The default value is false `false`.

2
doc/builders/packages/cataclysm-dda.section.md
View File

@ -103,7 +103,7 @@ let
owner = "Someone";
repo = "AwesomeMod";
rev = "...";
sha256 = "...";
hash = "...";
};
# Path to be installed in the unpacked source (default: ".")
modRoot = "contents/under/this/path/will/be/installed";

4
doc/builders/packages/citrix.section.md
View File

@ -4,7 +4,7 @@ The [Citrix Workspace App](https://www.citrix.com/products/workspace-app/) is a
## Basic usage {#sec-citrix-base}
The tarball archive needs to be downloaded manually, as the license agreements of the vendor for [Citrix Workspace](https://www.citrix.de/downloads/workspace-app/linux/workspace-app-for-linux-latest.html) needs to be accepted first. Then run `nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz`. With the archive available in the store, the package can be built and installed with Nix.
The tarball archive needs to be downloaded manually, as the license agreements of the vendor for [Citrix Workspace](https://www.citrix.com/downloads/workspace-app/linux/workspace-app-for-linux-latest.html) needs to be accepted first. Then run `nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz`. With the archive available in the store, the package can be built and installed with Nix.
## Citrix Self-service {#sec-citrix-selfservice}
@ -19,7 +19,7 @@ $ selfservice
## Custom certificates {#sec-citrix-custom-certs}
The `Citrix Workspace App` in `nixpkgs` trusts several certificates [from the Mozilla database](https://curl.haxx.se/docs/caextract.html) by default. However, several companies using Citrix might require their own corporate certificate. On distros with imperative packaging, these certs can be stored easily in [`$ICAROOT`](https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/), however this directory is a store path in `nixpkgs`. In order to work around this issue, the package provides a simple mechanism to add custom certificates without rebuilding the entire package using `symlinkJoin`:
The `Citrix Workspace App` in `nixpkgs` trusts several certificates [from the Mozilla database](https://curl.haxx.se/docs/caextract.html) by default. However, several companies using Citrix might require their own corporate certificate. On distros with imperative packaging, these certs can be stored easily in [`$ICAROOT`](https://citrix.github.io/receiver-for-linux-command-reference/), however this directory is a store path in `nixpkgs`. In order to work around this issue, the package provides a simple mechanism to add custom certificates without rebuilding the entire package using `symlinkJoin`:
```nix
with import <nixpkgs> { config.allowUnfree = true; };

2
doc/builders/packages/dlib.section.md
View File

@ -4,7 +4,7 @@
## Compiling without AVX support {#compiling-without-avx-support}
Especially older CPUs don\'t support [AVX](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) (Advanced Vector Extensions) instructions that are used by DLib to optimize their algorithms.
Especially older CPUs don't support [AVX](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) (Advanced Vector Extensions) instructions that are used by DLib to optimize their algorithms.
On the affected hardware errors like `Illegal instruction` will occur. In those cases AVX support needs to be disabled:

6
doc/builders/packages/eclipse.section.md
View File

@ -43,11 +43,11 @@ packageOverrides = pkgs: {
name = "myplugin1-1.0";
srcFeature = fetchurl {
url = "http://…/features/myplugin1.jar";
sha256 = "123…";
hash = "sha256-123…";
};
srcPlugin = fetchurl {
url = "http://…/plugins/myplugin1.jar";
sha256 = "123…";
hash = "sha256-123…";
};
});
(plugins.buildEclipseUpdateSite {
@ -55,7 +55,7 @@ packageOverrides = pkgs: {
src = fetchurl {
stripRoot = false;
url = "http://…/myplugin2.zip";
sha256 = "123…";
hash = "sha256-123…";
};
});
];

2
doc/builders/packages/firefox.section.md
View File

@ -12,7 +12,7 @@ The `wrapFirefox` function allows to pass policies, preferences and extensions t
(fetchFirefoxAddon {
name = "ublock"; # Has to be unique!
url = "https://addons.mozilla.org/firefox/downloads/file/3679754/ublock_origin-1.31.0-an+fx.xpi";
sha256 = "1h768ljlh3pi23l27qp961v1hd0nbj2vasgy11bmcrlqp40zgvnr";
hash = "sha256-2e73AbmYZlZXCP5ptYVcFjQYdjDp4iPoEPEOSCVF5sA=";
})
];

2
doc/builders/packages/ibus.section.md
View File

@ -4,7 +4,7 @@ This package is an ibus-based completion method to speed up typing.
## Activating the engine {#sec-ibus-typing-booster-activate}
IBus needs to be configured accordingly to activate `typing-booster`. The configuration depends on the desktop manager in use. For detailed instructions, please refer to the [upstream docs](https://mike-fabian.github.io/ibus-typing-booster/documentation.html).
IBus needs to be configured accordingly to activate `typing-booster`. The configuration depends on the desktop manager in use. For detailed instructions, please refer to the [upstream docs](https://mike-fabian.github.io/ibus-typing-booster/).
On NixOS, you need to explicitly enable `ibus` with given engines before customizing your desktop to use `typing-booster`. This can be achieved using the `ibus` module:

2
doc/builders/packages/weechat.section.md
View File

@ -73,7 +73,7 @@ stdenv.mkDerivation {
name = "exemplary-weechat-script";
src = fetchurl {
url = "https://scripts.tld/your-scripts.tar.gz";
sha256 = "...";
hash = "...";
};
passthru.scripts = [ "foo.py" "bar.lua" ];
installPhase = ''

1
doc/builders/special.xml
View File

@ -7,4 +7,5 @@
</para>
<xi:include href="special/fhs-environments.section.xml" />
<xi:include href="special/mkshell.section.xml" />
<xi:include href="special/darwin-builder.section.xml" />
</chapter>

63
doc/builders/special/darwin-builder.section.md Normal file
View File

@ -0,0 +1,63 @@
# darwin.builder {#sec-darwin-builder}
`darwin.builder` provides a way to bootstrap a Linux builder on a macOS machine.
This requires macOS version 12.4 or later.
This also requires that port 22 on your machine is free (since Nix does not
permit specifying a non-default SSH port for builders).
You will also need to be a trusted user for your Nix installation. In other
words, your `/etc/nix/nix.conf` should have something like:
```
extra-trusted-users = <your username goes here>
```
To launch the builder, run the following flake:
```ShellSession
$ nix run nixpkgs#darwin.builder
```
That will prompt you to enter your `sudo` password:
```
+ sudo --reset-timestamp /nix/store/…-install-credentials.sh ./keys
Password:
```
… so that it can install a private key used to `ssh` into the build server.
After that the script will launch the virtual machine and automatically log you
in as the `builder` user:
```
<<< Welcome to NixOS 22.11.20220901.1bd8d11 (aarch64) - ttyAMA0 >>>
Run 'nixos-help' for the NixOS manual.
nixos login: builder (automatic login)
[builder@nixos:~]$
```
> Note: When you need to stop the VM, run `shutdown now` as the `builder` user.
To delegate builds to the remote builder, add the following options to your
`nix.conf` file:
```
# - Replace ${ARCH} with either aarch64 or x86_64 to match your host machine
# - Replace ${MAX_JOBS} with the maximum number of builds (pick 4 if you're not sure)
builders = ssh-ng://builder@localhost ${ARCH}-linux /etc/nix/builder_ed25519 ${MAX_JOBS} - - - c3NoLWVkMjU1MTkgQUFBQUMzTnphQzFsWkRJMU5URTVBQUFBSUpCV2N4Yi9CbGFxdDFhdU90RStGOFFVV3JVb3RpQzVxQkorVXVFV2RWQ2Igcm9vdEBuaXhvcwo=
# Not strictly necessary, but this will reduce your disk utilization
builders-use-substitutes = true
```
… and then restart your Nix daemon to apply the change:
```ShellSession
$ sudo launchctl kickstart -k system/org.nixos.nix-daemon
```

17
doc/builders/testers.chapter.md
View File

@ -1,6 +1,19 @@
# Testers {#chap-testers}
This chapter describes several testing builders which are available in the <literal>testers</literal> namespace.
## `hasPkgConfigModule` {#tester-hasPkgConfigModule}
Checks whether a package exposes a certain `pkg-config` module.
Example:
```nix
passthru.tests.pkg-config = testers.hasPkgConfigModule {
package = finalAttrs.finalPackage;
moduleName = "libfoo";
}
```
## `testVersion` {#tester-testVersion}
Checks the command output contains the specified version
@ -62,7 +75,7 @@ runCommand "example" {
'';
```
While `testBuildFailure` is designed to keep changes to the original builder's
While `testBuildFailure` is designed to keep changes to the original builder's
environment to a minimum, some small changes are inevitable.
- The file `$TMPDIR/testBuildFailure.log` is present. It should not be deleted.
@ -147,7 +160,7 @@ tests.fetchgit = testers.invalidateFetcherByDrvHash fetchgit {
name = "nix-source";
url = "https://github.com/NixOS/nix";
rev = "9d9dbe6ed05854e03811c361a3380e09183f4f4a";
sha256 = "sha256-7DszvbCNTjpzGRmpIVAWXk20P0/XTrWZ79KSOGLrUWY=";
hash = "sha256-7DszvbCNTjpzGRmpIVAWXk20P0/XTrWZ79KSOGLrUWY=";
};
```

34
doc/contributing/coding-conventions.chapter.md
View File

@ -260,6 +260,10 @@ When in doubt, consider refactoring the `pkgs/` tree, e.g. creating new categori
- `development/tools/build-managers` (e.g. `gnumake`)
- **If it’s a _language server_:**
- `development/tools/language-servers` (e.g. `ccls` or `rnix-lsp`)
- **Else:**
- `development/tools/misc` (e.g. `binutils`)
@ -426,9 +430,10 @@ In the file `pkgs/top-level/all-packages.nix` you can find fetch helpers, these
```nix
src = fetchgit {
url = "git@github.com:NixOS/nix.git"
url = "git://github.com/NixOS/nix.git";
rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
sha256 = "1cw5fszffl5pkpa6s6wjnkiv6lm5k618s32sp60kvmvpy7a2v9kg";
hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
}
```
@ -438,7 +443,7 @@ In the file `pkgs/top-level/all-packages.nix` you can find fetch helpers, these
src = fetchgit {
url = "https://github.com/NixOS/nix.git";
rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
sha256 = "1cw5fszffl5pkpa6s6wjnkiv6lm5k618s32sp60kvmvpy7a2v9kg";
hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";
}
```
@ -449,14 +454,14 @@ In the file `pkgs/top-level/all-packages.nix` you can find fetch helpers, these
owner = "NixOS";
repo = "nix";
rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
sha256 = "1i2yxndxb6yc9l6c99pypbd92lfq5aac4klq7y2v93c9qvx2cgpc";
hash = "ha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=;
}
```
When fetching from GitHub, commits must always be referenced by their full commit hash. This is because GitHub shares commit hashes among all forks and returns `404 Not Found` when a short commit hash is ambiguous. It already happens for some short, 6-character commit hashes in `nixpkgs`.
It is a practical vector for a denial-of-service attack by pushing large amounts of auto generated commits into forks and was already [demonstrated against GitHub Actions Beta](https://blog.teddykatz.com/2019/11/12/github-actions-dos.html).
Find the value to put as `sha256` by running `nix-shell -p nix-prefetch-github --run "nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix"`.
Find the value to put as `hash` by running `nix-shell -p nix-prefetch-github --run "nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix"`.
## Obtaining source hash {#sec-source-hashes}
@ -486,12 +491,12 @@ Preferred source hash type is sha256. There are several ways to get it.
- `lib.fakeHash`
- `lib.fakeSha256`
- `lib.fakeSha512`
in the package expression, attempt build and extract correct hash from error messages.
::: {.warning}
You must use one of these four fake hashes and not some arbitrarily-chosen hash.
See [](#sec-source-hashes-security).
:::
@ -519,7 +524,7 @@ patches = [
(fetchpatch {
name = "fix-check-for-using-shared-freetype-lib.patch";
url = "http://git.ghostscript.com/?p=ghostpdl.git;a=patch;h=8f5d285";
sha256 = "1f0k043rng7f0rfl9hhb89qzvvksqmkrikmm38p61yfx51l325xr";
hash = "sha256-uRcxaCjd+WAuGrXOmGfFeu79cUILwkRdBu48mwcBE7g=";
})
];
```
@ -669,3 +674,18 @@ stdenv.mkDerivation {
...
}
```
### Import From Derivation {#ssec-import-from-derivation}
Import From Derivation (IFD) is disallowed in Nixpkgs for performance reasons:
[Hydra] evaluates the entire package set, and sequential builds during evaluation would increase evaluation times to become impractical.
[Hydra]: https://github.com/NixOS/hydra
Import From Derivation can be worked around in some cases by committing generated intermediate files to version control and reading those instead.
<!-- TODO: remove the following and link to Nix manual once https://github.com/NixOS/nix/pull/7332 is merged -->
See also [NixOS Wiki: Import From Derivation].
[NixOS Wiki: Import From Derivation]: https://nixos.wiki/wiki/Import_From_Derivation

16
doc/contributing/contributing-to-documentation.chapter.md
View File

@ -27,7 +27,7 @@ If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.
As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.
Additional syntax extensions are available, though not all extensions can be used in NixOS option documentation. The following extensions are currently used:
Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:
- []{#ssec-contributing-markup-anchors}
Explicitly defined **anchors** on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md).
@ -38,6 +38,10 @@ Additional syntax extensions are available, though not all extensions can be use
## Syntax {#sec-contributing-markup}
```
::: {.note}
NixOS option documentation does not support headings in general.
:::
- []{#ssec-contributing-markup-anchors-inline}
**Inline anchors**, which allow linking arbitrary place in the text (e.g. individual list items, sentences…).
@ -53,7 +57,7 @@ Additional syntax extensions are available, though not all extensions can be use
This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
- []{#ssec-contributing-markup-inline-roles}
If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in {file}`doc/build-aux/pandoc-filters/link-unix-man-references.lua`.
If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in {file}`doc/manpage-urls.json`.
A few markups for other kinds of literals are also available:
@ -67,10 +71,6 @@ Additional syntax extensions are available, though not all extensions can be use
This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax.
::: {.note}
Inline roles are available for option documentation.
:::
- []{#ssec-contributing-markup-admonitions}
**Admonitions**, set off from the text to bring attention to something.
@ -96,10 +96,6 @@ Additional syntax extensions are available, though not all extensions can be use
- [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)
- [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)
::: {.note}
Admonitions are available for option documentation.
:::
- []{#ssec-contributing-markup-definition-lists}
[**Definition lists**](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md), for defining a group of terms:

2
doc/contributing/quick-start.chapter.md
View File

@ -34,7 +34,7 @@ To add a package to Nixpkgs:
- Apache HTTPD: [`pkgs/servers/http/apache-httpd/2.4.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/http/apache-httpd/2.4.nix). A bunch of optional features, variable substitutions in the configure flags, a post-install hook, and miscellaneous hackery.
- Thunderbird: [`pkgs/applications/networking/mailreaders/thunderbird/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/mailreaders/thunderbird/default.nix). Lots of dependencies.
- buildMozillaMach: [`pkgs/applications/networking/browser/firefox/common.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/browsers/firefox/common.nix). A reusable build function for Firefox, Thunderbird and Librewolf.
- JDiskReport, a Java utility: [`pkgs/tools/misc/jdiskreport/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/default.nix). Nixpkgs doesn’t have a decent `stdenv` for Java yet so this is pretty ad-hoc.

2
doc/contributing/reviewing-contributions.chapter.md
View File

@ -185,7 +185,7 @@ Sample template for a new module review is provided below.
##### Comments
```
## Individual maintainer list {#reviewing-contributions-indvidual-maintainer-list}
## Individual maintainer list {#reviewing-contributions-individual-maintainer-list}
When adding users to `maintainers/maintainer-list.nix`, the following
checks should be performed:

4
doc/contributing/submitting-changes.chapter.md
View File

@ -76,7 +76,7 @@ Security fixes are submitted in the same way as other changes and thus the same
(fetchpatch {
name = "CVE-2019-11068.patch";
url = "https://gitlab.gnome.org/GNOME/libxslt/commit/e03553605b45c88f0b4b2980adfbbb8f6fca2fd6.patch";
sha256 = "0pkpb4837km15zgg6h57bncp66d5lwrlvkr73h0lanywq7zrwhj8";
hash = "sha256-SEKe/8HcW0UBHCfPTTOnpRlzmV2nQPPeL6HOMxBZd14=";
})
```
@ -199,7 +199,7 @@ It’s important to test any executables generated by a build when you change or
### Meets Nixpkgs contribution standards {#submitting-changes-contribution-standards}
The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md). The contributing document has detailed information on standards the Nix community has for commit messages, reviews, licensing of contributions you make to the project, etc\... Everyone should read and understand the standards the community has for contributing before submitting a pull request.
The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md). The contributing document has detailed information on standards the Nix community has for commit messages, reviews, licensing of contributions you make to the project, etc... Everyone should read and understand the standards the community has for contributing before submitting a pull request.
## Hotfixing pull requests {#submitting-changes-hotfixing-pull-requests}

1
doc/default.nix
View File

@ -36,4 +36,5 @@ in pkgs.stdenv.mkDerivation {
# Environment variables
PANDOC_LUA_FILTERS_DIR = "${pkgs.pandoc-lua-filters}/share/pandoc/filters";
PANDOC_LINK_MANPAGES_FILTER = import build-aux/pandoc-filters/link-manpages.nix { inherit pkgs; };
}

19
doc/doc-support/default.nix
View File

@ -3,8 +3,23 @@ let
inherit (pkgs) lib;
inherit (lib) hasPrefix removePrefix;
locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs; };
functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs; };
libsets = [
{ name = "asserts"; description = "assertion functions"; }
{ name = "attrsets"; description = "attribute set functions"; }
{ name = "strings"; description = "string manipulation functions"; }
{ name = "versions"; description = "version string functions"; }
{ name = "trivial"; description = "miscellaneous functions"; }
{ name = "lists"; description = "list manipulation functions"; }
{ name = "debug"; description = "debugging functions"; }
{ name = "options"; description = "NixOS / nixpkgs option handling"; }
{ name = "path"; description = "path functions"; }
{ name = "filesystem"; description = "filesystem functions"; }
{ name = "sources"; description = "source filtering functions"; }
{ name = "cli"; description = "command-line serialization functions"; }
];
locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; };
functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs libsets; };
version = pkgs.lib.version;
epub-xsl = pkgs.writeText "epub.xsl" ''

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

@ -1,28 +1,36 @@
# Generates the documentation for library functons via nixdoc. To add
# another library function file to this list, the include list in the
# file `doc/functions/library.xml` must also be updated.
# Generates the documentation for library functions via nixdoc.
{ pkgs ? import ./.. {}, locationsXml }:
{ pkgs, locationsXml, libsets }:
with pkgs; stdenv.mkDerivation {
name = "nixpkgs-lib-docs";
src = ./../../lib;
src = ../../lib;
buildInputs = [ nixdoc ];
installPhase = ''
function docgen {
nixdoc -c "$1" -d "$2" -f "../lib/$1.nix" > "$out/$1.xml"
# TODO: wrap lib.$1 in <literal>, make nixdoc not escape it
if [[ -e "../lib/$1.nix" ]]; then
nixdoc -c "$1" -d "lib.$1: $2" -f "$1.nix" > "$out/$1.xml"
else
nixdoc -c "$1" -d "lib.$1: $2" -f "$1/default.nix" > "$out/$1.xml"
fi
echo "<xi:include href='$1.xml' />" >> "$out/index.xml"
}
mkdir -p $out
ln -s ${locationsXml} $out/locations.xml
mkdir -p "$out"
docgen strings 'String manipulation functions'
docgen trivial 'Miscellaneous functions'
docgen lists 'List manipulation functions'
docgen debug 'Debugging functions'
docgen options 'NixOS / nixpkgs option handling'
docgen filesystem 'Filesystem functions'
docgen sources 'Source filtering functions'
cat > "$out/index.xml" << 'EOF'
<?xml version="1.0" encoding="utf-8"?>
<root xmlns:xi="http://www.w3.org/2001/XInclude">
EOF
${lib.concatMapStrings ({ name, description }: ''
docgen ${name} ${lib.escapeShellArg description}
'') libsets}
echo "</root>" >> "$out/index.xml"
ln -s ${locationsXml} $out/locations.xml
'';
}

22
doc/doc-support/lib-function-locations.nix
View File

@ -1,24 +1,24 @@
{ pkgs ? (import ./.. { }), nixpkgs ? { }}:
{ pkgs, nixpkgs ? { }, libsets }:
let
revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.revision or "master");
libDefPos = set:
builtins.map
(name: {
name = name;
libDefPos = prefix: set:
builtins.concatMap
(name: [{
name = builtins.concatStringsSep "." (prefix ++ [name]);
location = builtins.unsafeGetAttrPos name set;
})
(builtins.attrNames set);
}] ++ nixpkgsLib.optionals
(builtins.length prefix == 0 && builtins.isAttrs set.${name})
(libDefPos (prefix ++ [name]) set.${name})
) (builtins.attrNames set);
libset = toplib:
builtins.map
(subsetname: {
subsetname = subsetname;
functions = libDefPos toplib.${subsetname};
functions = libDefPos [] toplib.${subsetname};
})
(builtins.filter
(name: builtins.isAttrs toplib.${name})
(builtins.attrNames toplib));
(builtins.map (x: x.name) libsets);
nixpkgsLib = pkgs.lib;

10
doc/doc-support/parameters.xml
View File

@ -2,12 +2,16 @@
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:param name="section.autolabel" select="1" />
<xsl:param name="section.label.includes.component.label" select="1" />
<xsl:param name="chapter.autolabel" select="0" />
<xsl:param name="part.autolabel" select="0" />
<xsl:param name="preface.autolabel" select="0" />
<xsl:param name="reference.autolabel" select="0" />
<xsl:param name="section.autolabel" select="0" />
<xsl:param name="html.stylesheet" select="'style.css overrides.css highlightjs/mono-blue.css'" />
<xsl:param name="html.script" select="'./highlightjs/highlight.pack.js ./highlightjs/loader.js'" />
<xsl:param name="xref.with.number.and.title" select="1" />
<xsl:param name="xref.with.number.and.title" select="0" />
<xsl:param name="use.id.as.filename" select="1" />
<xsl:param name="generate.section.toc.level" select="1" />
<xsl:param name="toc.section.depth" select="0" />
<xsl:param name="admon.style" select="''" />
<xsl:param name="callout.graphics.extension" select="'.svg'" />

24
doc/functions/library.xml
View File

@ -8,25 +8,7 @@
Nixpkgs provides a standard library at <varname>pkgs.lib</varname>, or through <code>import &lt;nixpkgs/lib&gt;</code>.
</para>
<xi:include href="./library/asserts.xml" />
<xi:include href="./library/attrsets.xml" />
<!-- These docs are generated via nixdoc. To add another generated
library function file to this list, the file
`lib-function-docs.nix` must also be updated. -->
<xi:include href="./library/generated/strings.xml" />
<xi:include href="./library/generated/trivial.xml" />
<xi:include href="./library/generated/lists.xml" />
<xi:include href="./library/generated/debug.xml" />
<xi:include href="./library/generated/options.xml" />
<xi:include href="./library/generated/filesystem.xml" />
<xi:include href="./library/generated/sources.xml" />
<!-- The index must have a root element to declare namespaces, but we
don't want to include it, so we select all of its children. -->
<xi:include href="./library/generated/index.xml" xpointer="xpointer(/root/*)" />
</section>

0
doc/functions/library/.gitkeep Normal file
View File

112
doc/functions/library/asserts.xml
View File

@ -1,112 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-functions-library-asserts">
<title>Assert functions</title>
<section xml:id="function-library-lib.asserts.assertMsg">
<title><function>lib.asserts.assertMsg</function></title>
<subtitle><literal>assertMsg :: Bool -> String -> Bool</literal>
</subtitle>
<xi:include href="./locations.xml" xpointer="lib.asserts.assertMsg" />
<para>
Print a trace message if <literal>pred</literal> is false.
</para>
<para>
Intended to be used to augment asserts with helpful error messages.
</para>
<variablelist>
<varlistentry>
<term>
<varname>pred</varname>
</term>
<listitem>
<para>
Condition under which the <varname>msg</varname> should <emphasis>not</emphasis> be printed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>msg</varname>
</term>
<listitem>
<para>
Message to print.
</para>
</listitem>
</varlistentry>
</variablelist>
<example xml:id="function-library-lib.asserts.assertMsg-example-false">
<title>Printing when the predicate is false</title>
<programlisting><![CDATA[
assert lib.asserts.assertMsg ("foo" == "bar") "foo is not bar, silly"
stderr> trace: foo is not bar, silly
stderr> assert failed
]]></programlisting>
</example>
</section>
<section xml:id="function-library-lib.asserts.assertOneOf">
<title><function>lib.asserts.assertOneOf</function></title>
<subtitle><literal>assertOneOf :: String -> String ->
StringList -> Bool</literal>
</subtitle>
<xi:include href="./locations.xml" xpointer="lib.asserts.assertOneOf" />
<para>
Specialized <function>asserts.assertMsg</function> for checking if <varname>val</varname> is one of the elements of <varname>xs</varname>. Useful for checking enums.
</para>
<variablelist>
<varlistentry>
<term>
<varname>name</varname>
</term>
<listitem>
<para>
The name of the variable the user entered <varname>val</varname> into, for inclusion in the error message.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>val</varname>
</term>
<listitem>
<para>
The value of what the user provided, to be compared against the values in <varname>xs</varname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>xs</varname>
</term>
<listitem>
<para>
The list of valid values.
</para>
</listitem>
</varlistentry>
</variablelist>
<example xml:id="function-library-lib.asserts.assertOneOf-example">
<title>Ensuring a user provided a possible value</title>
<programlisting><![CDATA[
let sslLibrary = "bearssl";
in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "libressl" ];
=> false
stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl"
]]></programlisting>
</example>
</section>
</section>

1751
doc/functions/library/attrsets.xml
View File

File diff suppressed because it is too large Load Diff

4
doc/functions/nix-gitignore.section.md
View File

@ -4,7 +4,7 @@
## Usage {#sec-pkgs-nix-gitignore-usage}
`pkgs.nix-gitignore` exports a number of functions, but you\'ll most likely need either `gitignoreSource` or `gitignoreSourcePure`. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string.
`pkgs.nix-gitignore` exports a number of functions, but you'll most likely need either `gitignoreSource` or `gitignoreSourcePure`. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string.
```nix
{ pkgs ? import <nixpkgs> {} }:
@ -30,7 +30,7 @@ gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
gitignoreSource = gitignoreFilterSource (_: _: true);
```
Those filter functions accept the same arguments the `builtins.filterSource` function would pass to its filters, thus `fn: gitignoreFilterSourcePure fn ""` should be extensionally equivalent to `filterSource`. The file is blacklisted if it\'s blacklisted by either your filter or the gitignoreFilter.
Those filter functions accept the same arguments the `builtins.filterSource` function would pass to its filters, thus `fn: gitignoreFilterSourcePure fn ""` should be extensionally equivalent to `filterSource`. The file is blacklisted if it's blacklisted by either your filter or the gitignoreFilter.
If you want to make your own filter from scratch, you may use

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

@ -9,7 +9,7 @@ stdenv.mkDerivation {
# ...
checkInputs = [
nativeCheckInputs = [
postgresql
postgresqlTestHook
];
@ -46,6 +46,12 @@ Bash-only variables:
- `postgresqlEnableTCP`: set to `1` to enable TCP listening. Flaky; not recommended.
- `postgresqlStartCommands`: defaults to `pg_ctl start`.
## Hooks {#sec-postgresqlTestHook-hooks}
A number of additional hooks are ran in postgresqlTestHook
- `postgresqlTestSetupPost`: ran after postgresql has been set up.
## TCP and the Nix sandbox {#sec-postgresqlTestHook-tcp}
`postgresqlEnableTCP` relies on network sandboxing, which is not available on macOS and some custom Nix installations, resulting in flaky tests.

4
doc/languages-frameworks/agda.section.md
View File

@ -52,7 +52,7 @@ agda.withPackages (p: [
repo = "agda-stdlib";
owner = "agda";
rev = "v1.5";
sha256 = "16fcb7ssj6kj687a042afaa2gq48rc8abihpm14k684ncihb2k4w";
hash = "sha256-nEyxYGSWIDNJqBfGpRDLiOAnlHJKEKAOMnIaqfVZzJk=";
};
}))
])
@ -83,7 +83,7 @@ agda.withPackages (p: [
owner = "owner";
version = "...";
rev = "...";
sha256 = "...";
hash = "...";
};
})
])

7
doc/languages-frameworks/android.section.md
View File

@ -13,6 +13,7 @@ with import <nixpkgs> {};
let
androidComposition = androidenv.composeAndroidPackages {
cmdLineToolsVersion = "8.0";
toolsVersion = "26.1.1";
platformToolsVersion = "30.0.5";
buildToolsVersions = [ "30.0.3" ];
@ -42,7 +43,10 @@ exceptions are the tools, platform-tools and build-tools sub packages.
The following parameters are supported:
* `toolsVersion`, specifies the version of the tools package to use
* `cmdLineToolsVersion `, specifies the version of the `cmdline-tools` package to use
* `toolsVersion`, specifies the version of the `tools` package. Notice `tools` is
obsolete, and currently only `26.1.1` is available, so there's not a lot of
options here, however, you can set it as `null` if you don't want it.
* `platformsToolsVersion` specifies the version of the `platform-tools` plugin
* `buildToolsVersions` specifies the versions of the `build-tools` plugins to
use.
@ -232,7 +236,6 @@ androidenv.emulateApp {
platformVersion = "24";
abiVersion = "armeabi-v7a"; # mips, x86, x86_64
systemImageType = "default";
useGoogleAPIs = false;
app = ./MyApp.apk;
package = "MyApp";
activity = "MainActivity";

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

@ -93,7 +93,7 @@ Practical steps:
- run `mix2nix > mix_deps.nix` in the upstream repo.
- pass `mixNixDeps = with pkgs; import ./mix_deps.nix { inherit lib beamPackages; };` as an argument to mixRelease.
If there are git depencencies.
If there are git dependencies.
- You'll need to fix the version artificially in mix.exs and regenerate the mix.lock with fixed version (on upstream). This will enable you to run `mix2nix > mix_deps.nix`.
- From the mix_deps.nix file, remove the dependencies that had git versions and pass them as an override to the import function.
@ -115,7 +115,7 @@ If there are git depencencies.
owner = "elixir-libraries";
repo = "prometheus.ex";
rev = "a4e9beb3c1c479d14b352fd9d6dd7b1f6d7deee5";
sha256 = "1v0q4bi7sb253i8q016l7gwlv5562wk5zy3l2sa446csvsacnpjk";
hash = "sha256-U17LlN6aGUKUFnT4XyYXppRN+TvUBIBRHEUsfeIiGOw=";
};
# you can re-use the same beamDeps argument as generated
beamDeps = with final; [ prometheus ];
@ -124,11 +124,11 @@ If there are git depencencies.
};
```
You will need to run the build process once to fix the sha256 to correspond to your new git src.
You will need to run the build process once to fix the hash to correspond to your new git src.
###### FOD {#fixed-output-derivation}
A fixed output derivation will download mix dependencies from the internet. To ensure reproducibility, a hash will be supplied. Note that mix is relatively reproducible. An FOD generating a different hash on each run hasn't been observed (as opposed to npm where the chances are relatively high). See [elixir_ls](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/beam-modules/elixir_ls.nix) for a usage example of FOD.
A fixed output derivation will download mix dependencies from the internet. To ensure reproducibility, a hash will be supplied. Note that mix is relatively reproducible. An FOD generating a different hash on each run hasn't been observed (as opposed to npm where the chances are relatively high). See [elixir_ls](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/beam-modules/elixir-ls/default.nix) for a usage example of FOD.
Practical steps
@ -138,13 +138,13 @@ Practical steps
mixFodDeps = fetchMixDeps {
pname = "mix-deps-${pname}";
inherit src version;
sha256 = lib.fakeSha256;
hash = lib.fakeHash;
};
```
The first build will complain about the sha256 value, you can replace with the suggested value after that.
The first build will complain about the hash value, you can replace with the suggested value after that.
Note that if after you've replaced the value, nix suggests another sha256, then mix is not fetching the dependencies reproducibly. An FOD will not work in that case and you will have to use mix2nix.
Note that if after you've replaced the value, nix suggests another hash, then mix is not fetching the dependencies reproducibly. An FOD will not work in that case and you will have to use mix2nix.
##### mixRelease - example {#mix-release-example}
@ -170,7 +170,7 @@ let
pname = "mix-deps-${pname}";
inherit src version;
# nix will complain and tell you the right value to replace this with
sha256 = lib.fakeSha256;
hash = lib.fakeHash;
# if you have build time environment variables add them here
MY_ENV_VAR="my_value";
};
@ -282,7 +282,7 @@ mkShell {
### Using an overlay
If you need to use an overlay to change some attributes of a derivation, e.g. if you need a bugfix from a version that is not yet available in nixpkgs, you can override attributes such as `version` (and the corresponding `sha256`) and then use this overlay in your development environment:
If you need to use an overlay to change some attributes of a derivation, e.g. if you need a bugfix from a version that is not yet available in nixpkgs, you can override attributes such as `version` (and the corresponding `hash`) and then use this overlay in your development environment:
#### `shell.nix`
@ -291,7 +291,7 @@ let
elixir_1_13_1_overlay = (self: super: {
elixir_1_13 = super.elixir_1_13.override {
version = "1.13.1";
sha256 = "0z0b1w2vvw4vsnb99779c2jgn9bgslg7b1pmd9vlbv02nza9qj5p";
sha256 = "sha256-t0ic1LcC7EV3avWGdR7VbyX7pGDpnJSW1ZvwvQUPC3w=";
};
});
pkgs = import <nixpkgs> { overlays = [ elixir_1_13_1_overlay ]; };

4
doc/languages-frameworks/coq.section.md
View File

@ -8,7 +8,7 @@ The Coq derivation is overridable through the `coq.override overrides`, where ov
* `customOCamlPackages` (optional, defaults to `null`, which lets Coq choose a version automatically), which can be set to any of the ocaml packages attribute of `ocaml-ng` (such as `ocaml-ng.ocamlPackages_4_10` which is the default for Coq 8.11 for example).
* `coq-version` (optional, defaults to the short version e.g. "8.10"), is a version number of the form "x.y" that indicates which Coq's version build behavior to mimic when using a source which is not a release. E.g. `coq.override { version = "d370a9d1328a4e1cdb9d02ee032f605a9d94ec7a"; coq-version = "8.10"; }`.
The associated package set can be optained using `mkCoqPackages coq`, where `coq` is the derivation to use.
The associated package set can be obtained using `mkCoqPackages coq`, where `coq` is the derivation to use.
## Coq packages attribute sets: `coqPackages` {#coq-packages-attribute-sets-coqpackages}
@ -24,7 +24,7 @@ The recommended way of defining a derivation for a Coq library, is to use the `c
* if it is a string of the form `"#N"`, and the domain is github, then it tries to download the current head of the pull request `#N` from github,
* `defaultVersion` (optional). Coq libraries may be compatible with some specific versions of Coq only. The `defaultVersion` attribute is used when no `version` is provided (or if `version = null`) to select the version of the library to use by default, depending on the context. This selection will mainly depend on a `coq` version number but also possibly on other packages versions (e.g. `mathcomp`). If its value ends up to be `null`, the package is marked for removal in end-user `coqPackages` attribute set.
* `release` (optional, defaults to `{}`), lists all the known releases of the library and for each of them provides an attribute set with at least a `sha256` attribute (you may put the empty string `""` in order to automatically insert a fake sha256, this will trigger an error which will allow you to find the correct sha256), each attribute set of the list of releases also takes optional overloading arguments for the fetcher as below (i.e.`domain`, `owner`, `repo`, `rev` assuming the default fetcher is used) and optional overrides for the result of the fetcher (i.e. `version` and `src`).
* `fetcher` (optional, defaults to a generic fetching mechanism supporting github or gitlab based infrastructures), is a function that takes at least an `owner`, a `repo`, a `rev`, and a `sha256` and returns an attribute set with a `version` and `src`.
* `fetcher` (optional, defaults to a generic fetching mechanism supporting github or gitlab based infrastructures), is a function that takes at least an `owner`, a `repo`, a `rev`, and a `hash` and returns an attribute set with a `version` and `src`.
* `repo` (optional, defaults to the value of `pname`),
* `owner` (optional, defaults to `"coq-community"`).
* `domain` (optional, defaults to `"github.com"`), domains including the strings `"github"` or `"gitlab"` in their names are automatically supported, otherwise, one must change the `fetcher` argument to support them (cf `pkgs/development/coq-modules/heq/default.nix` for an example),

4
doc/languages-frameworks/crystal.section.md
View File

@ -27,7 +27,7 @@ crystal.buildCrystalPackage rec {
owner = "mint-lang";
repo = "mint";
rev = version;
sha256 = "0vxbx38c390rd2ysvbwgh89v2232sh5rbsp3nk9wzb70jybpslvl";
hash = "sha256-dFN9l5fgrM/TtOPqlQvUYgixE4KPr629aBmkwdDoq28=";
};
# Insert the path to your shards.nix file here
@ -62,7 +62,7 @@ crystal.buildCrystalPackage rec {
owner = "mint-lang";
repo = "mint";
rev = version;
sha256 = "0vxbx38c390rd2ysvbwgh89v2232sh5rbsp3nk9wzb70jybpslvl";
hash = "sha256-dFN9l5fgrM/TtOPqlQvUYgixE4KPr629aBmkwdDoq28=";
};
shardsFile = ./shards.nix;

19
doc/languages-frameworks/cuda.section.md
View File

@ -32,3 +32,22 @@ mypkg = let
}});
in callPackage { inherit cudaPackages; };
```
The CUDA NVCC compiler requires flags to determine which hardware you
want to target for in terms of SASS (real hardware) or PTX (JIT kernels).
Nixpkgs tries to target support real architecture defaults based on the
CUDA toolkit version with PTX support for future hardware. Experienced
users may optimize this configuration for a variety of reasons such as
reducing binary size and compile time, supporting legacy hardware, or
optimizing for specific hardware.
You may provide capabilities to add support or reduce binary size through
`config` using `cudaCapabilities = [ "6.0" "7.0" ];` and
`cudaForwardCompat = true;` if you want PTX support for future hardware.
Please consult [GPUs supported](https://en.wikipedia.org/wiki/CUDA#GPUs_supported)
for your specific card(s).
Library maintainers should consult [NVCC Docs](https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/)
and release notes for their software package.

93
doc/languages-frameworks/cuelang.section.md Normal file
View File

@ -0,0 +1,93 @@
# Cue (Cuelang) {#cuelang}
[Cuelang](https://cuelang.org/) is a language to:
- describe schemas and validate backward-compatibility
- generate code and schemas in various formats (e.g. JSON Schema, OpenAPI)
- do configuration akin to [Dhall Lang](https://dhall-lang.org/)
- perform data validation
## Cuelang schema quick start
Cuelang schemas are similar to JSON, here is a quick cheatsheet:
- Default types includes: `null`, `string`, `bool`, `bytes`, `number`, `int`, `float`, lists as `[...T]` where `T` is a type.
- All structures, defined by: `myStructName: { <fields> }` are **open** -- they accept fields which are not specified.
- Closed structures can be built by doing `myStructName: close({ <fields> })` -- they are strict in what they accept.
- `#X` are **definitions**, referenced definitions are **recursively closed**, i.e. all its children structures are **closed**.
- `&` operator is the [unification operator](https://cuelang.org/docs/references/spec/#unification) (similar to a type-level merging operator), `|` is the [disjunction operator](https://cuelang.org/docs/references/spec/#disjunction) (similar to a type-level union operator).
- Values **are** types, i.e. `myStruct: { a: 3 }` is a valid type definition that only allows `3` as value.
- Read <https://cuelang.org/docs/concepts/logic/> to learn more about the semantics.
- Read <https://cuelang.org/docs/references/spec/> to learn about the language specification.
## `writeCueValidator`
Nixpkgs provides a `pkgs.writeCueValidator` helper, which will write a validation script based on the provided Cuelang schema.
Here is an example:
```
pkgs.writeCueValidator
(pkgs.writeText "schema.cue" ''
#Def1: {
field1: string
}
'')
{ document = "#Def1"; }
```
- The first parameter is the Cue schema file.
- The second parameter is an options parameter, currently, only: `document` can be passed.
`document` : match your input data against this fragment of structure or definition, e.g. you may use the same schema file but different documents based on the data you are validating.
Another example, given the following `validator.nix` :
```
{ pkgs ? import <nixpkgs> {} }:
let
genericValidator = version:
pkgs.writeCueValidator
(pkgs.writeText "schema.cue" ''
#Version1: {
field1: string
}
#Version2: #Version1 & {
field1: "unused"
}''
)
{ document = "#Version${toString version}"; };
in
{
validateV1 = genericValidator 1;
validateV2 = genericValidator 2;
}
```
The result is a script that will validate the file you pass as the first argument against the schema you provided `writeCueValidator`.
It can be any format that `cue vet` supports, i.e. YAML or JSON for example.
Here is an example, named `example.json`, given the following JSON:
```
{ "field1": "abc" }
```
You can run the result script (named `validate`) as the following:
```console
$ nix-build validator.nix
$ ./result example.json
$ ./result-2 example.json
field1: conflicting values "unused" and "abc":
./example.json:1:13
../../../../../../nix/store/v64dzx3vr3glpk0cq4hzmh450lrwh6sg-schema.cue:5:11
$ sed -i 's/"abc"/3/' example.json
$ ./result example.json
field1: conflicting values 3 and string (mismatched types int and string):
./example.json:1:13
../../../../../../nix/store/v64dzx3vr3glpk0cq4hzmh450lrwh6sg-schema.cue:5:11
```
**Known limitations**
* The script will enforce **concrete** values and will not accept lossy transformations (strictness). You can add these options if you need them.

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

@ -91,7 +91,7 @@ buildDhallPackage {
let
nixpkgs = builtins.fetchTarball {
url = "https://github.com/NixOS/nixpkgs/archive/94b2848559b12a8ed1fe433084686b2a81123c99.tar.gz";
sha256 = "1pbl4c2dsaz2lximgd31m96jwbps6apn3anx8cvvhk1gl9rkg107";
sha256 = "sha256-B4Q3c6IvTLg3Q92qYa8y+i4uTaphtFdjp+Ir3QQjdN0=";
};
dhallOverlay = self: super: {
@ -295,7 +295,7 @@ terms of `buildDhallPackage` that accepts the following arguments:
* `document`: Set to `true` to generate documentation for the package
Additionally, `buildDhallGitHubPackage` accepts the same arguments as
`fetchFromGitHub`, such as `sha256` or `fetchSubmodules`.
`fetchFromGitHub`, such as `hash` or `fetchSubmodules`.
## `dhall-to-nixpkgs` {#ssec-dhall-dhall-to-nixpkgs}
@ -316,7 +316,7 @@ $ dhall-to-nixpkgs github https://github.com/Gabriel439/dhall-semver.git
repo = "dhall-semver";
rev = "2d44ae605302ce5dc6c657a1216887fbb96392a4";
fetchSubmodules = false;
sha256 = "0y8shvp8srzbjjpmnsvz9c12ciihnx1szs0yzyi9ashmrjvd0jcz";
hash = "sha256-n0nQtswVapWi/x7or0O3MEYmAkt/a1uvlOtnje6GGnk=";
directory = "";
file = "package.dhall";
source = false;

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

@ -28,13 +28,13 @@ mkShell {
packages = [
(with dotnetCorePackages; combinePackages [
sdk_3_1
sdk_5_0
sdk_6_0
])
];
}
```
This will produce a dotnet installation that has the dotnet 3.1, 3.0, and 2.1 sdk. The first sdk listed will have it's cli utility present in the resulting environment. Example info output:
This will produce a dotnet installation that has the dotnet 3.1 6.0 sdk. The first sdk listed will have it's cli utility present in the resulting environment. Example info output:
```ShellSession
$ dotnet --info
@ -120,8 +120,7 @@ in buildDotnetModule rec {
projectReferences = [ referencedProject ]; # `referencedProject` must contain `nupkg` in the folder structure.
dotnet-sdk = dotnetCorePackages.sdk_3_1;
dotnet-runtime = dotnetCorePackages.net_5_0;
dotnetFlags = [ "--runtime linux-x64" ];
dotnet-runtime = dotnetCorePackages.net_6_0;
executables = [ "foo" ]; # This wraps "$out/lib/$pname/foo" to `$out/bin/foo`.
executables = []; # Don't install any executables.

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

@ -121,7 +121,7 @@ This `xmlmirror` example features a emscriptenPackage which is defined completel
src = pkgs.fetchgit {
url = "https://gitlab.com/odfplugfest/xmlmirror.git";
rev = "4fd7e86f7c9526b8f4c1733e5c8b45175860a8fd";
sha256 = "1jasdqnbdnb83wbcnyrp32f36w3xwhwp0wq8lwwmhqagxrij1r4b";
hash = "sha256-i+QgY+5PYVg5pwhzcDnkfXAznBg3e8sWH2jZtixuWsk=";
};
configurePhase = ''

4
doc/languages-frameworks/gnome.section.md
View File

@ -34,7 +34,7 @@ To allow software to use various virtual file systems, `gvfs` package can be als
### GdkPixbuf loaders {#ssec-gnome-gdk-pixbuf-loaders}
GTK applications typically use [GdkPixbuf](https://developer.gnome.org/gdk-pixbuf/stable/) to load images. But `gdk-pixbuf` package only supports basic bitmap formats like JPEG, PNG or TIFF, requiring to use third-party loader modules for other formats. This is especially painful since GTK itself includes SVG icons, which cannot be rendered without a loader provided by `librsvg`.
GTK applications typically use [GdkPixbuf](https://gitlab.gnome.org/GNOME/gdk-pixbuf/) to load images. But `gdk-pixbuf` package only supports basic bitmap formats like JPEG, PNG or TIFF, requiring to use third-party loader modules for other formats. This is especially painful since GTK itself includes SVG icons, which cannot be rendered without a loader provided by `librsvg`.
Unlike other libraries mentioned in this section, GdkPixbuf only supports a single value in its controlling environment variable `GDK_PIXBUF_MODULE_FILE`. It is supposed to point to a cache file containing information about the available loaders. Each loader package will contain a `lib/gdk-pixbuf-2.0/2.10.0/loaders.cache` file describing the default loaders in `gdk-pixbuf` package plus the loader contained in the package itself. If you want to use multiple third-party loaders, you will need to create your own cache file manually. Fortunately, this is pretty rare as [not many loaders exist](https://gitlab.gnome.org/federico/gdk-pixbuf-survey/blob/master/src/modules.md).
@ -70,7 +70,7 @@ Also make sure that `icon-theme.cache` is installed for each theme provided by t
### GTK Themes {#ssec-gnome-themes}
Previously, a GTK theme needed to be in `XDG_DATA_DIRS`. This is no longer necessary for most programs since GTK incorporated Adwaita theme. Some programs (for example, those designed for [elementary HIG](https://elementary.io/docs/human-interface-guidelines#human-interface-guidelines)) might require a special theme like `pantheon.elementary-gtk-theme`.
Previously, a GTK theme needed to be in `XDG_DATA_DIRS`. This is no longer necessary for most programs since GTK incorporated Adwaita theme. Some programs (for example, those designed for [elementary HIG](https://docs.elementary.io/hig)) might require a special theme like `pantheon.elementary-gtk-theme`.
### GObject introspection typelibs {#ssec-gnome-typelibs}

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

@ -11,7 +11,14 @@ The function `buildGoModule` builds Go programs managed with Go modules. It buil
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 take `null` as an input. When `null` is used as a value, rather than fetching the dependencies and vendoring them, we use the vendoring included within the source repo. If you'd like to not have to update this field on dependency changes, run `go mod vendor` in your source repo and set `vendorHash = null;`
- `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.fakeSha256;` 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 dependant `vendorHash` checksums.
```nix
@ -23,7 +30,7 @@ pet = buildGoModule rec {
owner = "knqyf263";
repo = "pet";
rev = "v${version}";
sha256 = "0m2fzpqxk7hrbxsgqplkg7h2p7gv6s1miymv3gvw0cz039skag0s";
hash = "sha256-Gjw1dRrgM8D3G7v6WIM2+50r4HmTXvx0Xxme2fH9TlQ=";
};
vendorHash = "sha256-ciBIR+a1oaYH+H1PcC8cD8ncfJczk1IiJ8iYNM+R6aA=";
@ -59,7 +66,7 @@ deis = buildGoPackage rec {
owner = "deis";
repo = "deis";
rev = "v${version}";
sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
hash = "sha256-XCPD4LNWtAd8uz7zyCLRfT8rzxycIUmTACjU03GnaeM=";
};
goDeps = ./deps.nix;
@ -76,11 +83,11 @@ The `goDeps` attribute can be imported from a separate `nix` file that defines w
goPackagePath = "gopkg.in/yaml.v2";
fetch = {
# `fetch type` that needs to be used to get package source.
# If `git` is used there should be `url`, `rev` and `sha256` defined next to it.
# If `git` is used there should be `url`, `rev` and `hash` defined next to it.
type = "git";
url = "https://gopkg.in/yaml.v2";
rev = "a83829b6f1293c91addabc89d0571c246397bbf4";
sha256 = "1m4dsmk90sbi17571h6pld44zxz7jc4lrnl4f27dpd1l8g5xvjhh";
hash = "sha256-EMrdy0M0tNuOcITaTAmT5/dPSKPXwHDKCXFpkGbVjdQ=";
};
}
{
@ -89,7 +96,7 @@ The `goDeps` attribute can be imported from a separate `nix` file that defines w
type = "git";
url = "https://github.com/docopt/docopt-go";
rev = "784ddc588536785e7299f7272f39101f7faccc3f";
sha256 = "0wwz48jl9fvl1iknvn9dqr4gfy1qs03gxaikrxxp9gry6773v3sj";
hash = "sha256-Uo89zjE+v3R7zzOq/gbQOHj3SMYt2W1nDHS7RCUin3M=";
};
}
]

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

File diff suppressed because it is too large Load Diff

4
doc/languages-frameworks/hy.section.md
View File

@ -4,10 +4,10 @@
### Installation without packages {#installation-without-packages}
You can install `hy` via nix-env or by adding it to `configuration.nix` by reffering to it as a `hy` attribute. This kind of installation adds `hy` to your environment and it succesfully works with `python3`.
You can install `hy` via nix-env or by adding it to `configuration.nix` by referring to it as a `hy` attribute. This kind of installation adds `hy` to your environment and it successfully works with `python3`.
::: {.caution}
Packages that are installed with your python derivation, are not accesible by `hy` this way.
Packages that are installed with your python derivation, are not accessible by `hy` this way.
:::
### Installation with packages {#installation-with-packages}

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

@ -90,7 +90,7 @@ build-idris-package {
owner = "Heather";
repo = "Idris.Yaml";
rev = "5afa51ffc839844862b8316faba3bafa15656db4";
sha256 = "1g4pi0swmg214kndj85hj50ccmckni7piprsxfdzdfhg87s0avw7";
hash = "sha256-h28F9EEPuvab6zrfeE+0k1XGQJGwINnsJEG8yjWIl7w=";
};
meta = with lib; {

4
doc/languages-frameworks/index.xml
View File

@ -3,7 +3,7 @@
xml:id="chap-language-support">
<title>Languages and frameworks</title>
<para>
The <link linkend="chap-stdenv">standard build environment</link> makes it easy to build typical Autotools-based packages with very little code. Any other kind of package can be accomodated by overriding the appropriate phases of <literal>stdenv</literal>. However, there are specialised functions in Nixpkgs to easily build packages for other programming languages, such as Perl or Haskell. These are described in this chapter.
The <link linkend="chap-stdenv">standard build environment</link> makes it easy to build typical Autotools-based packages with very little code. Any other kind of package can be accommodated by overriding the appropriate phases of <literal>stdenv</literal>. However, there are specialised functions in Nixpkgs to easily build packages for other programming languages, such as Perl or Haskell. These are described in this chapter.
</para>
<xi:include href="agda.section.xml" />
<xi:include href="android.section.xml" />
@ -13,6 +13,7 @@
<xi:include href="coq.section.xml" />
<xi:include href="crystal.section.xml" />
<xi:include href="cuda.section.xml" />
<xi:include href="cuelang.section.xml" />
<xi:include href="dhall.section.xml" />
<xi:include href="dotnet.section.xml" />
<xi:include href="emscripten.section.xml" />
@ -31,6 +32,7 @@
<xi:include href="octave.section.xml" />
<xi:include href="perl.section.xml" />
<xi:include href="php.section.xml" />
<xi:include href="pkg-config.section.xml" />
<xi:include href="python.section.xml" />
<xi:include href="qt.section.xml" />
<xi:include href="r.section.xml" />

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

@ -175,9 +175,10 @@ buildNpmPackage rec {
hash = "sha256-BR+ZGkBBfd0dSQqAvujsbgsEPFYw/ThrylxUbOksYxM=";
};
patches = [ ./remove-prepack-script.patch ];
npmDepsHash = "sha256-tuEfyePwlOy2/mOPdXbqJskO6IowvAP4DWg8xSZwbJw=";
npmDepsHash = "sha256-s8SpZY/1tKZVd3vt7sA9vsqHvEaNORQBMrSyhWpj048=";
# The prepack script runs the build script, which we'd rather do in the build phase.
npmPackFlags = [ "--ignore-scripts" ];
NODE_OPTIONS = "--openssl-legacy-provider";
@ -242,7 +243,7 @@ If the downloaded files contain the `package.json` and `yarn.lock` files they ca
```nix
offlineCache = fetchYarnDeps {
yarnLock = src + "/yarn.lock";
sha256 = "....";
hash = "....";
};
```
@ -330,13 +331,16 @@ 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>
## Outside of nixpkgs {#javascript-outside-nixpkgs}
## Outside Nixpkgs {#javascript-outside-nixpkgs}
There are some other options available that can't be used inside nixpkgs. Those other options are written in Nix. Importing them in nixpkgs will require moving the source code into nixpkgs. Using [Import From Derivation](https://nixos.wiki/wiki/Import_From_Derivation) is not allowed in Hydra at present. If you are packaging something outside nixpkgs, those can be considered
There are some other tools available, which are written in the Nix language.
These that can't be used inside Nixpkgs because they require [Import From Derivation](#ssec-import-from-derivation), which is not allowed in Nixpkgs.
If you are packaging something outside Nixpkgs, consider the following:
### npmlock2nix {#javascript-npmlock2nix}
[npmlock2nix](https://github.com/nix-community/npmlock2nix) aims at building node_modules without code generation. It hasn't reached v1 yet, the API might be subject to change.
[npmlock2nix](https://github.com/nix-community/npmlock2nix) aims at building `node_modules` without code generation. It hasn't reached v1 yet, the API might be subject to change.
#### Pitfalls {#javascript-npmlock2nix-pitfalls}
@ -344,7 +348,7 @@ There are some [problems with npm v7](https://github.com/tweag/npmlock2nix/issue
### nix-npm-buildpackage {#javascript-nix-npm-buildpackage}
[nix-npm-buildpackage](https://github.com/serokell/nix-npm-buildpackage) aims at building node_modules without code generation. It hasn't reached v1 yet, the API might change. It supports both package-lock.json and yarn.lock.
[nix-npm-buildpackage](https://github.com/serokell/nix-npm-buildpackage) aims at building `node_modules` without code generation. It hasn't reached v1 yet, the API might change. It supports both `package-lock.json` and yarn.lock.
#### Pitfalls {#javascript-nix-npm-buildpackage-pitfalls}

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

@ -183,7 +183,7 @@ luaposix = buildLuarocksPackage {
src = fetchurl {
url = "https://raw.githubusercontent.com/rocks-moonscript-org/moonrocks-mirror/master/luaposix-34.0.4-1.src.rock";
sha256 = "0yrm5cn2iyd0zjd4liyj27srphvy0gjrjx572swar6zqr4dwjqp2";
hash = "sha256-4mLJG8n4m6y4Fqd0meUDfsOb9RHSR0qa/KD5KCwrNXs=";
};
disabled = (luaOlder "5.1") || (luaAtLeast "5.4");
propagatedBuildInputs = [ bit32 lua std_normalize ];

4
doc/languages-frameworks/nim.section.md
View File

@ -25,7 +25,7 @@ nimPackages.buildNimPackage rec {
src = fetchurl {
url = "https://git.sr.ht/~ehmry/hottext/archive/v${version}.tar.gz";
sha256 = "sha256-hIUofi81zowSMbt1lUsxCnVzfJGN3FEiTtN8CEFpwzY=";
hash = "sha256-hIUofi81zowSMbt1lUsxCnVzfJGN3FEiTtN8CEFpwzY=";
};
buildInputs = with nimPackages; [
@ -65,7 +65,7 @@ buildNimPackage rec {
version = "2.0.4";
src = fetchNimble {
inherit pname version;
hash = "sha256-Vtcj8goI4zZPQs2TbFoBFlcR5UqDtOldaXSH/+/xULk=";
hash = "sha256-qDtVSnf+7rTq36WAxgsUZ8XoUk4sKwHyt8EJcY5WP+o=";
};
propagatedBuildInputs = [ SDL2 ];
}

9
doc/languages-frameworks/ocaml.section.md
View File

@ -79,7 +79,7 @@ buildDunePackage rec {
owner = "inhabitedtype";
repo = pname;
rev = version;
sha256 = "1hmrkdcdlkwy7rxhngf3cv3sa61cznnd9p5lmqhx20664gx2ibrh";
hash = "sha256-MK8o+iPGANEhrrTc1Kz9LBilx2bDPQt7Pp5P2libucI=";
};
checkInputs = [ alcotest ppx_let ];
@ -110,7 +110,7 @@ buildDunePackage rec {
src = fetchurl {
url = "https://github.com/flowtype/ocaml-${pname}/releases/download/v${version}/${pname}-v${version}.tbz";
sha256 = "09ygcxxd5warkdzz17rgpidrd0pg14cy2svvnvy1hna080lzg7vp";
hash = "sha256-d5/3KUBAWRj8tntr4RkJ74KWW7wvn/B/m1nx0npnzyc=";
};
meta = with lib; {
@ -129,3 +129,8 @@ packaged libraries may still use the old spelling: maintainers are invited to
fix this when updating packages. Massive renaming is strongly discouraged as it
would be challenging to review, difficult to test, and will cause unnecessary
rebuild.
The build will automatically fail if two distinct versions of the same library
are added to `buildInputs` (which usually happens transitively because of
`propagatedBuildInputs`). Set `dontDetectOcamlConflicts` to true to disable this
behavior.

14
doc/languages-frameworks/perl.section.md
View File

@ -39,7 +39,7 @@ ClassC3 = buildPerlPackage rec {
version = "0.21";
src = fetchurl {
url = "mirror://cpan/authors/id/F/FL/FLORA/${pname}-${version}.tar.gz";
sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz";
hash = "sha256-/5GE5xHT0uYGOQxroqj6LMU7CtKn2s6vMVoSXxL4iK4=";
};
};
```
@ -78,7 +78,7 @@ buildPerlPackage rec {
src = fetchurl {
url = "mirror://cpan/authors/id/P/PM/PMQS/${pname}-${version}.tar.gz";
sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1";
hash = "sha256-4Y+HGgGQqcOfdiKcFIyMrWBEccVNVAMDBWZlFTMorh8=";
};
preConfigure = ''
@ -96,7 +96,7 @@ ClassC3Componentised = buildPerlPackage rec {
version = "1.0004";
src = fetchurl {
url = "mirror://cpan/authors/id/A/AS/ASH/${pname}-${version}.tar.gz";
sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1";
hash = "sha256-ASO9rV/FzJYZ0BH572Fxm2ZrFLMZLFATJng1NuU4FHc=";
};
propagatedBuildInputs = [
ClassC3 ClassInspector TestException MROCompat
@ -111,11 +111,11 @@ On Darwin, if a script has too many `-Idir` flags in its first line (its “sheb
ImageExifTool = buildPerlPackage {
pname = "Image-ExifTool";
version = "11.50";
version = "12.50";
src = fetchurl {
url = "https://www.sno.phy.queensu.ca/~phil/exiftool/${pname}-${version}.tar.gz";
sha256 = "0d8v48y94z8maxkmw1rv7v9m0jg2dc8xbp581njb6yhr7abwqdv3";
url = "https://exiftool.org/${pname}-${version}.tar.gz";
hash = "sha256-vOhB/FwQMC8PPvdnjDvxRpU6jAZcC6GMQfc0AH4uwKg=";
};
buildInputs = lib.optional stdenv.isDarwin shortenPerlShebang;
@ -146,7 +146,7 @@ $ nix-generate-from-cpan XML::Simple
version = "2.22";
src = fetchurl {
url = "mirror://cpan/authors/id/G/GR/GRANTM/XML-Simple-2.22.tar.gz";
sha256 = "b9450ef22ea9644ae5d6ada086dc4300fa105be050a2030ebd4efd28c198eb49";
hash = "sha256-uUUO8i6pZErl1q2ghtxDAPoQW+BQogMOvU79KMGY60k=";
};
propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ];
meta = {

9
doc/languages-frameworks/pkg-config.section.md Normal file
View File

@ -0,0 +1,9 @@
# pkg-config {#sec-pkg-config}
*pkg-config* is a unified interface for declaring and querying built C/C++ libraries.
Nixpkgs provides a couple of facilities for working with this tool.
- A [setup hook](#setup-hook-pkg-config) bundled with in the `pkg-config` package, to bring a derivation's declared build inputs into the environment.
- The [`validatePkgConfig` setup hook](https://nixos.org/manual/nixpkgs/stable/#validatepkgconfig), for packages that provide pkg-config modules.
- The `defaultPkgConfigPackages` package set: a set of aliases, named after the modules they provide. This is meant to be used by language-to-nix integrations. Hand-written packages should use the normal Nixpkgs attribute name instead.

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

@ -58,7 +58,7 @@ with a nix-shell that has `numpy` and `toolz` in Python 3.9; then we will create
a re-usable environment in a single-file Python script; then we will create a
full Python environment for development with this same environment.
Philosphically, this should be familiar to users who are used to a `venv` style
Philosophically, this should be familiar to users who are used to a `venv` style
of development: individual projects create their own Python environments without
impacting the global environment or each other.
@ -356,7 +356,7 @@ buildPythonPackage rec {
src = fetchPypi {
inherit pname version;
sha256 = "08fdd5ef7c96480ad11c12d472de21acd32359996f69a5259299b540feba4560";
hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
};
doCheck = false;
@ -401,7 +401,7 @@ with import <nixpkgs> {};
src = python39.pkgs.fetchPypi {
inherit pname version;
sha256 = "08fdd5ef7c96480ad11c12d472de21acd32359996f69a5259299b540feba4560";
hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
};
doCheck = false;
@ -436,7 +436,7 @@ arguments `buildInputs` and `propagatedBuildInputs` to specify dependencies. If
something is exclusively a build-time dependency, then the dependency should be
included in `buildInputs`, but if it is (also) a runtime dependency, then it
should be added to `propagatedBuildInputs`. Test dependencies are considered
build-time dependencies and passed to `checkInputs`.
build-time dependencies and passed to `nativeCheckInputs`.
The following example shows which arguments are given to `buildPythonPackage` in
order to build [`datashape`](https://github.com/blaze/datashape).
@ -450,10 +450,10 @@ buildPythonPackage rec {
src = fetchPypi {
inherit pname version;
sha256 = "14b2ef766d4c9652ab813182e866f493475e65e558bed0822e38bf07bba1a278";
hash = "sha256-FLLvdm1MllKrgTGC6Gb0k0deZeVYvtCCLji/B7uhong=";
};
checkInputs = [ pytest ];
nativeCheckInputs = [ pytest ];
propagatedBuildInputs = [ numpy multipledispatch python-dateutil ];
meta = with lib; {
@ -466,7 +466,7 @@ buildPythonPackage rec {
```
We can see several runtime dependencies, `numpy`, `multipledispatch`, and
`python-dateutil`. Furthermore, we have one `checkInputs`, i.e. `pytest`. `pytest` is a
`python-dateutil`. Furthermore, we have one `nativeCheckInputs`, i.e. `pytest`. `pytest` is a
test runner and is only used during the `checkPhase` and is therefore not added
to `propagatedBuildInputs`.
@ -484,7 +484,7 @@ buildPythonPackage rec {
src = fetchPypi {
inherit pname version;
sha256 = "16a0fa97hym9ysdk3rmqz32xdjqmy4w34ld3rm3jf5viqjx65lxk";
hash = "sha256-s9NiusRxFydHzaNRMjjxFcvWxfi45jGb9ql6eJJyQJk=";
};
buildInputs = [ pkgs.libxml2 pkgs.libxslt ];
@ -517,7 +517,7 @@ buildPythonPackage rec {
src = fetchPypi {
inherit pname version;
sha256 = "f6bbb6afa93085409ab24885a1a3cdb8909f095a142f4d49e346f2bd1b789074";
hash = "sha256-9ru2r6kwhUCaskiFoaPNuJCfCVoUL01J40byvRt4kHQ=";
};
buildInputs = [ pkgs.fftw pkgs.fftwFloat pkgs.fftwLongDouble];
@ -569,8 +569,14 @@ Pytest is the most common test runner for python repositories. A trivial
test run would be:
```
checkInputs = [ pytest ];
checkPhase = "pytest";
nativeCheckInputs = [ pytest ];
checkPhase = ''
runHook preCheck
pytest
runHook postCheck
'';
```
However, many repositories' test suites do not translate well to nix's build
@ -579,10 +585,14 @@ sandbox, and will generally need many tests to be disabled.
To filter tests using pytest, one can do the following:
```
checkInputs = [ pytest ];
nativeCheckInputs = [ pytest ];
# avoid tests which need additional data or touch network
checkPhase = ''
runHook preCheck
pytest tests/ --ignore=tests/integration -k 'not download and not update'
runHook postCheck
'';
```
@ -605,10 +615,10 @@ been removed, in this case, it's recommended to use `pytestCheckHook`.
`test` command for a `checkPhase` which runs `pytest`. This is also beneficial
when a package may need many items disabled to run the test suite.
Using the example above, the analagous `pytestCheckHook` usage would be:
Using the example above, the analogous `pytestCheckHook` usage would be:
```
checkInputs = [ pytestCheckHook ];
nativeCheckInputs = [ pytestCheckHook ];
# requires additional data
pytestFlagsArray = [ "tests/" "--ignore=tests/integration" ];
@ -624,7 +634,7 @@ Using the example above, the analagous `pytestCheckHook` usage would be:
];
```
This is expecially useful when tests need to be conditionally disabled,
This is especially useful when tests need to be conditionally disabled,
for example:
```
@ -734,17 +744,17 @@ work in any of the formats supported by `buildPythonPackage` currently,
with the exception of `other` (see `format` in
[`buildPythonPackage` parameters](#buildpythonpackage-parameters) for more details).
### Using unittestCheckHook {#using-unittestcheckhook}
#### Using unittestCheckHook {#using-unittestcheckhook}
`unittestCheckHook` is a hook which will substitute the setuptools `test` command for a `checkPhase` which runs `python -m unittest discover`:
```
checkInputs = [ unittestCheckHook ];
nativeCheckInputs = [ unittestCheckHook ];
unittestFlags = [ "-s" "tests" "-v" ];
unittestFlagsArray = [ "-s" "tests" "-v" ];
```
##### Using sphinxHook {#using-sphinxhook}
#### Using sphinxHook {#using-sphinxhook}
The `sphinxHook` is a helpful tool to build documentation and manpages
using the popular Sphinx documentation generator.
@ -855,7 +865,7 @@ buildPythonPackage rec {
src = fetchPypi {
inherit pname version;
sha256 = "08fdd5ef7c96480ad11c12d472de21acd32359996f69a5259299b540feba4560";
hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
};
meta = with lib; {
@ -988,7 +998,7 @@ buildPythonPackage rec {
src = fetchPypi {
inherit pname version;
sha256 = "cf8436dc59d8695346fcd3ab296de46425ecab00d64096cebe79fb51ecb2eb93";
hash = "sha256-z4Q23FnYaVNG/NOrKW3kZCXsqwDWQJbOvnn7Ueyy65M=";
};
postPatch = ''
@ -996,7 +1006,7 @@ buildPythonPackage rec {
rm testing/test_argcomplete.py
'';
checkInputs = [ hypothesis ];
nativeCheckInputs = [ hypothesis ];
nativeBuildInputs = [ setuptools-scm ];
propagatedBuildInputs = [ attrs py setuptools six pluggy ];
@ -1018,7 +1028,7 @@ The `buildPythonPackage` mainly does four things:
* In the `installCheck` phase, `${python.interpreter} setup.py test` is run.
By default tests are run because `doCheck = true`. Test dependencies, like
e.g. the test runner, should be added to `checkInputs`.
e.g. the test runner, should be added to `nativeCheckInputs`.
By default `meta.platforms` is set to the same value
as the interpreter unless overridden otherwise.
@ -1072,7 +1082,7 @@ because their behaviour is different:
* `buildInputs ? []`: Build and/or run-time dependencies that need to be
compiled for the host machine. Typically non-Python libraries which are being
linked.
* `checkInputs ? []`: Dependencies needed for running the `checkPhase`. These
* `nativeCheckInputs ? []`: Dependencies needed for running the `checkPhase`. These
are added to `nativeBuildInputs` when `doCheck = true`. Items listed in
`tests_require` go here.
* `propagatedBuildInputs ? []`: Aside from propagating dependencies,
@ -1098,7 +1108,7 @@ with import <nixpkgs> {};
src = super.fetchPypi {
pname = "pandas";
inherit version;
sha256 = "08blshqj9zj1wyjhhw3kl2vas75vhhicvv72flvf1z3jvapgw295";
hash = "sha256-JQn+rtpy/OA2deLszSKEuxyttqBzcAil50H+JDHUdCE=";
};
});
};
@ -1158,7 +1168,7 @@ python3.pkgs.buildPythonApplication rec {
src = python3.pkgs.fetchPypi {
inherit pname version;
sha256 = "035w8gqql36zlan0xjrzz9j4lh9hs0qrsgnbyw07qs7lnkvbdv9x";
hash = "sha256-Pe229rT0aHwA98s+nTHQMEFKZPo/yw6sot8MivFDvAw=";
};
propagatedBuildInputs = with python3.pkgs; [ tornado python-daemon ];
@ -1406,9 +1416,13 @@ example of such a situation is when `py.test` is used.
buildPythonPackage {
# ...
# assumes the tests are located in tests
checkInputs = [ pytest ];
nativeCheckInputs = [ pytest ];
checkPhase = ''
runHook preCheck
py.test -k 'not function_name and not other_function' tests
runHook postCheck
'';
}
```
@ -1674,9 +1688,9 @@ If you need to change a package's attribute(s) from `configuration.nix` you coul
packageOverrides = python-self: python-super: {
twisted = python-super.twisted.overridePythonAttrs (oldAttrs: {
src = super.fetchPypi {
pname = "twisted";
pname = "Twisted";
version = "19.10.0";
sha256 = "7394ba7f272ae722a74f3d969dcf599bc4ef093bc392038748a490f1724a515d";
hash = "sha256-c5S6fycq5yKnTz2Wnc9Zm8TvCTvDkgOHSKSQ8XJKUV0=";
extension = "tar.bz2";
};
});
@ -1712,9 +1726,9 @@ self: super: {
packageOverrides = python-self: python-super: {
twisted = python-super.twisted.overrideAttrs (oldAttrs: {
src = super.fetchPypi {
pname = "twisted";
pname = "Twisted";
version = "19.10.0";
sha256 = "7394ba7f272ae722a74f3d969dcf599bc4ef093bc392038748a490f1724a515d";
hash = "sha256-c5S6fycq5yKnTz2Wnc9Zm8TvCTvDkgOHSKSQ8XJKUV0=";
extension = "tar.bz2";
};
});
@ -1754,7 +1768,7 @@ In a `setup.py` or `setup.cfg` it is common to declare dependencies:
* `setup_requires` corresponds to `nativeBuildInputs`
* `install_requires` corresponds to `propagatedBuildInputs`
* `tests_require` corresponds to `checkInputs`
* `tests_require` corresponds to `nativeCheckInputs`
## Contributing {#contributing}

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

@ -2,14 +2,11 @@
Writing Nix expressions for Qt libraries and applications is largely similar as for other C++ software.
This section assumes some knowledge of the latter.
There are two problems that the Nixpkgs Qt infrastructure addresses,
which are not shared by other C++ software:
1. There are usually multiple supported versions of Qt in Nixpkgs.
All of a package's dependencies must be built with the same version of Qt.
This is similar to the version constraints imposed on interpreted languages like Python.
2. Qt makes extensive use of runtime dependency detection.
Runtime dependencies are made into build dependencies through wrappers.
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.
## Nix expression for a Qt package (default.nix) {#qt-default-nix}
@ -95,66 +92,3 @@ stdenv.mkDerivation {
This means that scripts won't be automatically wrapped so you'll need to manually wrap them as previously mentioned.
An example of when you'd always need to do this is with Python applications that use PyQt.
:::
## Adding a library to Nixpkgs {#adding-a-library-to-nixpkgs}
Add Qt libraries to `qt5-packages.nix` to make them available for every
supported Qt version.
### Example adding a Qt library {#qt-library-all-packages-nix}
The following represents the contents of `qt5-packages.nix`.
```nix
{
# ...
mylib = callPackage ../path/to/mylib {};
# ...
}
```
Libraries are built with every available version of Qt.
Use the `meta.broken` attribute to disable the package for unsupported Qt versions:
```nix
{ stdenv, lib, qtbase }:
stdenv.mkDerivation {
# ...
# Disable this library with Qt < 5.9.0
meta.broken = lib.versionOlder qtbase.version "5.9.0";
}
```
## Adding an application to Nixpkgs {#adding-an-application-to-nixpkgs}
Add Qt applications to `qt5-packages.nix`. Add an alias to `all-packages.nix`
to select the Qt 5 version used for the application.
### Example adding a Qt application {#qt-application-all-packages-nix}
The following represents the contents of `qt5-packages.nix`.
```nix
{
# ...
myapp = callPackage ../path/to/myapp {};
# ...
}
```
The following represents the contents of `all-packages.nix`.
```nix
{
# ...
myapp = libsForQt5.myapp;
# ...
}
```

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

@ -30,10 +30,10 @@ rustPlatform.buildRustPackage rec {
owner = "BurntSushi";
repo = pname;
rev = version;
sha256 = "1hqps7l5qrjh9f914r5i6kmcz6f1yb951nv4lby0cjnp5l253kps";
hash = "sha256-+s5RBC3XSgb8omTbUNLywZnP6jSxZBKSS1BmXOjRF8M=";
};
cargoSha256 = "03wf9r2csi6jpa7v5sw5lpxkrk4wfzwmzx7k3991q3bdjzcwnnwp";
cargoHash = "sha256-jtBw4ahSl88L0iuCXxQgZVm1EcboWRJMNtjxLVTtzts=";
meta = with lib; {
description = "A fast line-oriented regex search tool, similar to ag and ack";
@ -97,10 +97,10 @@ rustPlatform.buildRustPackage rec {
src = fetchCrate {
inherit pname version;
sha256 = "1mqaynrqaas82f5957lx31x80v74zwmwmjxxlbywajb61vh00d38";
sha256 = "sha256-aDQA4A5mScX9or3Lyiv/5GyAehidnpKKE0grhbP1Ctc=";
};
cargoHash = "sha256-JmBZcDVYJaK1cK05cxx5BrnGWp4t8ca6FLUbvIot67s=";
cargoHash = "sha256-tbrTbutUs5aPSV+yE0IBUZAAytgmZV7Eqxia7g+9zRs=";
cargoDepsName = pname;
# ...
@ -186,6 +186,23 @@ added. To find the correct hash, you can first use `lib.fakeSha256` or
`lib.fakeHash` as a stub hash. Building the package (and thus the
vendored dependencies) will then inform you of the correct hash.
For usage outside nixpkgs, `allowBuiltinFetchGit` could be used to
avoid having to specify `outputHashes`. For example:
```nix
rustPlatform.buildRustPackage rec {
pname = "myproject";
version = "1.0.0";
cargoLock = {
lockFile = ./Cargo.lock;
allowBuiltinFetchGit = true;
};
# ...
}
```
### Cargo features {#cargo-features}
You can disable default features using `buildNoDefaultFeatures`, and
@ -319,7 +336,7 @@ The above are just guidelines, and exceptions may be granted on a case-by-case b
However, please check if it's possible to disable a problematic subset of the
test suite and leave a comment explaining your reasoning.
This can be achived with `--skip` in `checkFlags`:
This can be achieved with `--skip` in `checkFlags`:
```nix
rustPlatform.buildRustPackage {
@ -331,6 +348,20 @@ rustPlatform.buildRustPackage {
}
```
#### Using `cargo-nextest` {#using-cargo-nextest}
Tests can be run with [cargo-nextest](https://github.com/nextest-rs/nextest)
by setting `useNextest = true`. The same options still apply, but nextest
accepts a different set of arguments and the settings might need to be
adapted to be compatible with cargo-nextest.
```nix
rustPlatform.buildRustPackage {
/* ... */
useNextest = true;
}
```
#### Setting `test-threads` {#setting-test-threads}
`buildRustPackage` will use parallel test threads by default,
@ -403,8 +434,8 @@ cargoDeps = rustPlatform.fetchCargoTarball {
```
The `src` attribute is required, as well as a hash specified through
one of the `sha256` or `hash` attributes. The following optional
attributes can also be used:
one of the `hash` attribute. The following optional attributes can
also be used:
* `name`: the name that is used for the dependencies tarball. If
`name` is not specified, then the name `cargo-deps` will be used.
@ -474,6 +505,9 @@ you of the correct hash.
flags can be passed to the tests using `checkFlags` and
`checkFlagsArray`. By default, tests are run in parallel. This can
be disabled by setting `dontUseCargoParallelTests`.
* `cargoNextestHook`: run tests using
[cargo-nextest](https://github.com/nextest-rs/nextest). The same
options for `cargoCheckHook` also applies to `cargoNextestHook`.
* `cargoInstallHook`: install binaries and static/shared libraries
that were built using `cargoBuildHook`.
* `bindgenHook`: for crates which use `bindgen` as a build dependency, lets
@ -514,7 +548,7 @@ buildPythonPackage rec {
cargoDeps = rustPlatform.fetchCargoTarball {
inherit src sourceRoot;
name = "${pname}-${version}";
hash = "sha256-BoHIN/519Top1NUBjpB/oEMqi86Omt3zTQcXFWqrek0=";
hash = "sha256-miW//pnOmww2i6SOGbkrAIdc/JMDT4FJLqdMFojZeoY=";
};
sourceRoot = "source/bindings/python";
@ -551,7 +585,7 @@ buildPythonPackage rec {
src = fetchPypi {
inherit pname version;
sha256 = "1i1mx5y9hkyfi9jrrkcw804hmkcglxi6rmf7vin7jfnbr2bf4q64";
hash = "sha256-xGDilsjLOnls3MfVbGKnj80KCUCczZxlis5PmHzpNcQ=";
};
cargoDeps = rustPlatform.fetchCargoTarball {
@ -591,7 +625,7 @@ buildPythonPackage rec {
owner = "Qiskit";
repo = "retworkx";
rev = version;
sha256 = "11n30ldg3y3y6qxg3hbj837pnbwjkqw3nxq6frds647mmmprrd20";
hash = "sha256-11n30ldg3y3y6qxg3hbj837pnbwjkqw3nxq6frds647mmmprrd20=";
};
cargoDeps = rustPlatform.fetchCargoTarball {
@ -608,227 +642,6 @@ buildPythonPackage rec {
}
```
## `buildRustCrate`: Compiling Rust crates using Nix instead of Cargo {#compiling-rust-crates-using-nix-instead-of-cargo}
### Simple operation {#simple-operation}
When run, `cargo build` produces a file called `Cargo.lock`,
containing pinned versions of all dependencies. Nixpkgs contains a
tool called `carnix` (`nix-env -iA nixos.carnix`), which can be used
to turn a `Cargo.lock` into a Nix expression.
That Nix expression calls `rustc` directly (hence bypassing Cargo),
and can be used to compile a crate and all its dependencies. Here is
an example for a minimal `hello` crate:
```ShellSession
$ cargo new hello
$ cd hello
$ cargo build
Compiling hello v0.1.0 (file:///tmp/hello)
Finished dev [unoptimized + debuginfo] target(s) in 0.20 secs
$ carnix -o hello.nix --src ./. Cargo.lock --standalone
$ nix-build hello.nix -A hello_0_1_0
```
Now, the file produced by the call to `carnix`, called `hello.nix`, looks like:
```nix
# Generated by carnix 0.6.5: carnix -o hello.nix --src ./. Cargo.lock --standalone
{ stdenv, buildRustCrate, fetchgit }:
let kernel = stdenv.buildPlatform.parsed.kernel.name;
# ... (content skipped)
in
rec {
hello = f: hello_0_1_0 { features = hello_0_1_0_features { hello_0_1_0 = f; }; };
hello_0_1_0_ = { dependencies?[], buildDependencies?[], features?[] }: buildRustCrate {
crateName = "hello";
version = "0.1.0";
authors = [ "pe@pijul.org <pe@pijul.org>" ];
src = ./.;
inherit dependencies buildDependencies features;
};
hello_0_1_0 = { features?(hello_0_1_0_features {}) }: hello_0_1_0_ {};
hello_0_1_0_features = f: updateFeatures f (rec {
hello_0_1_0.default = (f.hello_0_1_0.default or true);
}) [ ];
}
```
In particular, note that the argument given as `--src` is copied
verbatim to the source. If we look at a more complicated
dependencies, for instance by adding a single line `libc="*"` to our
`Cargo.toml`, we first need to run `cargo build` to update the
`Cargo.lock`. Then, `carnix` needs to be run again, and produces the
following nix file:
```nix
# Generated by carnix 0.6.5: carnix -o hello.nix --src ./. Cargo.lock --standalone
{ stdenv, buildRustCrate, fetchgit }:
let kernel = stdenv.buildPlatform.parsed.kernel.name;
# ... (content skipped)
in
rec {
hello = f: hello_0_1_0 { features = hello_0_1_0_features { hello_0_1_0 = f; }; };
hello_0_1_0_ = { dependencies?[], buildDependencies?[], features?[] }: buildRustCrate {
crateName = "hello";
version = "0.1.0";
authors = [ "pe@pijul.org <pe@pijul.org>" ];
src = ./.;
inherit dependencies buildDependencies features;
};
libc_0_2_36_ = { dependencies?[], buildDependencies?[], features?[] }: buildRustCrate {
crateName = "libc";
version = "0.2.36";
authors = [ "The Rust Project Developers" ];
sha256 = "01633h4yfqm0s302fm0dlba469bx8y6cs4nqc8bqrmjqxfxn515l";
inherit dependencies buildDependencies features;
};
hello_0_1_0 = { features?(hello_0_1_0_features {}) }: hello_0_1_0_ {
dependencies = mapFeatures features ([ libc_0_2_36 ]);
};
hello_0_1_0_features = f: updateFeatures f (rec {
hello_0_1_0.default = (f.hello_0_1_0.default or true);
libc_0_2_36.default = true;
}) [ libc_0_2_36_features ];
libc_0_2_36 = { features?(libc_0_2_36_features {}) }: libc_0_2_36_ {
features = mkFeatures (features.libc_0_2_36 or {});
};
libc_0_2_36_features = f: updateFeatures f (rec {
libc_0_2_36.default = (f.libc_0_2_36.default or true);
libc_0_2_36.use_std =
(f.libc_0_2_36.use_std or false) ||
(f.libc_0_2_36.default or false) ||
(libc_0_2_36.default or false);
}) [];
}
```
Here, the `libc` crate has no `src` attribute, so `buildRustCrate`
will fetch it from [crates.io](https://crates.io). A `sha256`
attribute is still needed for Nix purity.
### Handling external dependencies {#handling-external-dependencies}
Some crates require external libraries. For crates from
[crates.io](https://crates.io), such libraries can be specified in
`defaultCrateOverrides` package in nixpkgs itself.
Starting from that file, one can add more overrides, to add features
or build inputs by overriding the hello crate in a separate file.
```nix
with import <nixpkgs> {};
((import ./hello.nix).hello {}).override {
crateOverrides = defaultCrateOverrides // {
hello = attrs: { buildInputs = [ openssl ]; };
};
}
```
Here, `crateOverrides` is expected to be a attribute set, where the
key is the crate name without version number and the value a function.
The function gets all attributes passed to `buildRustCrate` as first
argument and returns a set that contains all attribute that should be
overwritten.
For more complicated cases, such as when parts of the crate's
derivation depend on the crate's version, the `attrs` argument of
the override above can be read, as in the following example, which
patches the derivation:
```nix
with import <nixpkgs> {};
((import ./hello.nix).hello {}).override {
crateOverrides = defaultCrateOverrides // {
hello = attrs: lib.optionalAttrs (lib.versionAtLeast attrs.version "1.0") {
postPatch = ''
substituteInPlace lib/zoneinfo.rs \
--replace "/usr/share/zoneinfo" "${tzdata}/share/zoneinfo"
'';
};
};
}
```
Another situation is when we want to override a nested
dependency. This actually works in the exact same way, since the
`crateOverrides` parameter is forwarded to the crate's
dependencies. For instance, to override the build inputs for crate
`libc` in the example above, where `libc` is a dependency of the main
crate, we could do:
```nix
with import <nixpkgs> {};
((import hello.nix).hello {}).override {
crateOverrides = defaultCrateOverrides // {
libc = attrs: { buildInputs = []; };
};
}
```
### Options and phases configuration {#options-and-phases-configuration}
Actually, the overrides introduced in the previous section are more
general. A number of other parameters can be overridden:
- The version of `rustc` used to compile the crate:
```nix
(hello {}).override { rust = pkgs.rust; };
```
- Whether to build in release mode or debug mode (release mode by
default):
```nix
(hello {}).override { release = false; };
```
- Whether to print the commands sent to `rustc` when building
(equivalent to `--verbose` in cargo:
```nix
(hello {}).override { verbose = false; };
```
- Extra arguments to be passed to `rustc`:
```nix
(hello {}).override { extraRustcOpts = "-Z debuginfo=2"; };
```
- Phases, just like in any other derivation, can be specified using
the following attributes: `preUnpack`, `postUnpack`, `prePatch`,
`patches`, `postPatch`, `preConfigure` (in the case of a Rust crate,
this is run before calling the "build" script), `postConfigure`
(after the "build" script),`preBuild`, `postBuild`, `preInstall` and
`postInstall`. As an example, here is how to create a new module
before running the build script:
```nix
(hello {}).override {
preConfigure = ''
echo "pub const PATH=\"${hi.out}\";" >> src/path.rs"
'';
};
```
### Features {#features}
One can also supply features switches. For example, if we want to
compile `diesel_cli` only with the `postgres` feature, and no default
features, we would write:
```nix
(callPackage ./diesel.nix {}).diesel {
default = false;
postgres = true;
}
```
Where `diesel.nix` is the file generated by Carnix, as explained above.
## Setting Up `nix-shell` {#setting-up-nix-shell}
Oftentimes you want to develop code from within `nix-shell`. Unfortunately
@ -886,7 +699,7 @@ let src = fetchFromGitHub {
repo = "nixpkgs-mozilla";
# commit from: 2019-05-15
rev = "9f35c4b09fd44a77227e79ff0c1b4b6a69dff533";
sha256 = "18h0nvh55b5an4gmlgfbvwbyqj91bklf1zymis6lbdh75571qaz0";
hash = "sha256-18h0nvh55b5an4gmlgfbvwbyqj91bklf1zymis6lbdh75571qaz0=";
};
in
with import "${src.out}/rust-overlay.nix" pkgs pkgs;
@ -977,7 +790,7 @@ rustPlatform.buildRustPackage rec {
owner = "BurntSushi";
repo = "ripgrep";
rev = version;
sha256 = "1hqps7l5qrjh9f914r5i6kmcz6f1yb951nv4lby0cjnp5l253kps";
hash = "sha256-1hqps7l5qrjh9f914r5i6kmcz6f1yb951nv4lby0cjnp5l253kps=";
};
cargoSha256 = "03wf9r2csi6jpa7v5sw5lpxkrk4wfzwmzx7k3991q3bdjzcwnnwp";

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

@ -55,11 +55,11 @@ let
srcs = [
(fetchurl {
url = "http://mirrors.ctan.org/macros/latex/contrib/foiltex/foiltex.dtx";
sha256 = "07frz0krpz7kkcwlayrwrj2a2pixmv0icbngyw92srp9fp23cqpz";
hash = "sha256-/2I2xHXpZi0S988uFsGuPV6hhMw8e0U5m/P8myf42R0=";
})
(fetchurl {
url = "http://mirrors.ctan.org/macros/latex/contrib/foiltex/foiltex.ins";
sha256 = "09wkyidxk3n3zvqxfs61wlypmbhi1pxmjdi1kns9n2ky8ykbff99";
hash = "sha256-KTm3pkd+Cpu0nSE2WfsNEa56PeXBaNfx/sOO2Vv0kyc=";
})
];

19
doc/languages-frameworks/vim.section.md
View File

@ -10,12 +10,21 @@ At the moment we support two different methods for managing plugins:
- Vim packages (*recommended*)
- vim-plug (vim only)
Right now two Vim packages are available: `vim` which has most features that require extra
dependencies disabled and `vim-full` which has them configurable and enabled by default.
::: {.note}
`vim_configurable` is a deprecated alias for `vim-full` and refers to the fact that its
build-time features are configurable. It has nothing to do with user configuration,
and both the `vim` and `vim-full` packages can be customized as explained in the next section.
:::
## Custom configuration {#custom-configuration}
Adding custom .vimrc lines can be done using the following code:
```nix
vim_configurable.customize {
vim-full.customize {
# `name` optionally specifies the name of the executable and package
name = "vim-with-plugins";
@ -62,7 +71,7 @@ neovim-qt.override {
To store your plugins in Vim packages (the native Vim plugin manager, see `:help packages`) the following example can be used:
```nix
vim_configurable.customize {
vim-full.customize {
vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
# loaded on launch
start = [ youcompleteme fugitive ];
@ -101,7 +110,7 @@ The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.n
```nix
{
packageOverrides = pkgs: with pkgs; {
myVim = vim_configurable.customize {
myVim = vim-full.customize {
# `name` specifies the name of the executable and package
name = "vim-with-plugins";
# add here code from the example section
@ -131,7 +140,7 @@ let
owner = "dkprice";
repo = "vim-easygrep";
rev = "d0c36a77cc63c22648e792796b1815b44164653a";
sha256 = "0y2p5mz0d5fhg6n68lhfhl8p4mlwkb82q337c22djs4w5zyzggbc";
hash = "sha256-bL33/S+caNmEYGcMLNCanFZyEYUOUmSsedCVBn4tV3g=";
};
};
in
@ -190,7 +199,7 @@ To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim
plugins the following example can be used:
```nix
vim_configurable.customize {
vim-full.customize {
vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
# loaded on launch
plug.plugins = [ youcompleteme fugitive phpCompletion elm-vim ];

32
doc/manpage-urls.json Normal file
View File

@ -0,0 +1,32 @@
{
"gnunet.conf(5)": "https://docs.gnunet.org/users/configuration.html",
"mpd(1)": "https://mpd.readthedocs.io/en/latest/mpd.1.html",
"mpd.conf(5)": "https://mpd.readthedocs.io/en/latest/mpd.conf.5.html",
"nix.conf(5)": "https://nixos.org/manual/nix/stable/command-ref/conf-file.html",
"journald.conf(5)": "https://www.freedesktop.org/software/systemd/man/journald.conf.html",
"logind.conf(5)": "https://www.freedesktop.org/software/systemd/man/logind.conf.html",
"networkd.conf(5)": "https://www.freedesktop.org/software/systemd/man/networkd.conf.html",
"systemd.automount(5)": "https://www.freedesktop.org/software/systemd/man/systemd.automount.html",
"systemd.exec(5)": "https://www.freedesktop.org/software/systemd/man/systemd.exec.html",
"systemd.link(5)": "https://www.freedesktop.org/software/systemd/man/systemd.link.html",
"systemd.mount(5)": "https://www.freedesktop.org/software/systemd/man/systemd.mount.html",
"systemd.netdev(5)": "https://www.freedesktop.org/software/systemd/man/systemd.netdev.html",
"systemd.network(5)": "https://www.freedesktop.org/software/systemd/man/systemd.network.html",
"systemd.nspawn(5)": "https://www.freedesktop.org/software/systemd/man/systemd.nspawn.html",
"systemd.path(5)": "https://www.freedesktop.org/software/systemd/man/systemd.path.html",
"systemd.resource-control(5)": "https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html",
"systemd.scope(5)": "https://www.freedesktop.org/software/systemd/man/systemd.scope.html",
"systemd.service(5)": "https://www.freedesktop.org/software/systemd/man/systemd.service.html",
"systemd.slice(5)": "https://www.freedesktop.org/software/systemd/man/systemd.slice.html",
"systemd.socket(5)": "https://www.freedesktop.org/software/systemd/man/systemd.socket.html",
"systemd.timer(5)": "https://www.freedesktop.org/software/systemd/man/systemd.timer.html",
"systemd.unit(5)": "https://www.freedesktop.org/software/systemd/man/systemd.unit.html",
"systemd-system.conf(5)": "https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html",
"systemd-user.conf(5)": "https://www.freedesktop.org/software/systemd/man/systemd-user.conf.html",
"timesyncd.conf(5)": "https://www.freedesktop.org/software/systemd/man/timesyncd.conf.html",
"tmpfiles.d(5)": "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html",
"systemd.time(7)": "https://www.freedesktop.org/software/systemd/man/systemd.time.html",
"systemd-fstab-generator(8)": "https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html",
"systemd-networkd-wait-online.service(8)": "https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html"
}

10
doc/old/cross.txt
View File

@ -61,7 +61,7 @@ stdenv.mkDerivation {
builder = ./builder.sh;
src = fetchurl {
url = "http://ftp.nluug.nl/gnu/binutils/binutils-2.16.1.tar.bz2";
sha256 = "1ian3kwh2vg6hr3ymrv48s04gijs539vzrq62xr76bxbhbwnz2np";
hash = "sha256-14pv+YKrL3NyFwbnv9MoWsZHgEZk5+pHhuZtAfkcVsU=";
};
inherit noSysDirs;
configureFlags = [ "--target=arm-linux" ];
@ -85,7 +85,7 @@ stdenv.mkDerivation {
builder = ./builder.sh;
src = fetchurl {
url = "http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.13.1.tar.bz2";
sha256 = "12qxmc827fjhaz53kjy7vyrzsaqcg78amiqsb3qm20z26w705lma";
hash = "sha256-qtICDjfiA1HxWBrHqtB5DCv9s9/HyznKV1C6IxCrHYs=";
};
}
---
@ -151,8 +151,8 @@ stdenv.mkDerivation {
name = "gcc-4.0.2-arm";
builder = ./builder.sh;
src = fetchurl {
url = ftp://ftp.nluug.nl/pub/gnu/gcc/gcc-4.0.2/gcc-core-4.0.2.tar.bz2;
sha256 = "02fxh0asflm8825w23l2jq1wvs7hbnam0jayrivg7zdv2ifnc0rc";
url = "ftp://ftp.nluug.nl/pub/gnu/gcc/gcc-4.0.2/gcc-core-4.0.2.tar.bz2";
hash = "sha256-LANmXRS7/fN2zF5JUJVd8OjNA5aCDsGLQKhSpxWA3Qk=";
};
# !!! apply only if noSysDirs is set
patches = [./no-sys-dirs.patch ./gcc-inhibit.patch];
@ -303,7 +303,7 @@ One of the compiler flags that GCC uses for this compiler is called X_CFLAGS.
This is used by the Nix build process to set the dynamic linker, glibc
in the case of i686-linux using the default Nix packages collection.
Obiously, since we need to compile libstc++ for arm-linux with uClibc linking
Obviously, since we need to compile libstc++ for arm-linux with uClibc linking
will not be done correctly: you can't link object files built for arm-linux
with a glibc built for i686-linux.

6
doc/preface.chapter.md
View File

@ -24,8 +24,8 @@ 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-19.09`, which includes all packages and modules for the stable NixOS
19.09. Stable NixOS releases are generally only given
`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.
@ -43,4 +43,4 @@ 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
that correspond to the channel names (e.g. `nixos-19.09-small`).
that correspond to the channel names (e.g. `nixos-22.11-small`).

2
doc/stdenv/cross-compilation.chapter.md
View File

@ -150,7 +150,7 @@ depsBuildBuild = [ buildPackages.stdenv.cc ];
Add the following to your `mkDerivation` invocation.
```nix
doCheck = stdenv.hostPlatform == stdenv.buildPlatform;
doCheck = stdenv.buildPlatform.canExecute stdenv.hostPlatform;
```
#### Package using Meson needs to run binaries for the host platform during build. {#cross-meson-runs-host-code}

52
doc/stdenv/meta.chapter.md
View File

@ -11,58 +11,12 @@ meta = with lib; {
'';
homepage = "https://www.gnu.org/software/hello/manual/";
license = licenses.gpl3Plus;
maintainers = [ maintainers.eelco ];
maintainers = with maintainers; [ eelco ];
platforms = platforms.all;
};
```
Meta-attributes are not passed to the builder of the package. Thus, a change to a meta-attribute doesn’t trigger a recompilation of the package. The value of a meta-attribute must be a string.
The meta-attributes of a package can be queried from the command-line using `nix-env`:
```ShellSession
$ nix-env -qa hello --json
{
"hello": {
"meta": {
"description": "A program that produces a familiar, friendly greeting",
"homepage": "https://www.gnu.org/software/hello/manual/",
"license": {
"fullName": "GNU General Public License version 3 or later",
"shortName": "GPLv3+",
"url": "http://www.fsf.org/licensing/licenses/gpl.html"
},
"longDescription": "GNU Hello is a program that prints \"Hello, world!\" when you run it.\nIt is fully customizable.\n",
"maintainers": [
"Ludovic Court\u00e8s <ludo@gnu.org>"
],
"platforms": [
"i686-linux",
"x86_64-linux",
"armv5tel-linux",
"armv7l-linux",
"mips32-linux",
"x86_64-darwin",
"i686-cygwin",
"i686-freebsd13",
"x86_64-freebsd13",
"i686-openbsd",
"x86_64-openbsd"
],
"position": "/home/user/dev/nixpkgs/pkgs/applications/misc/hello/default.nix:14"
},
"name": "hello-2.9",
"system": "x86_64-linux"
}
}
```
`nix-env` knows about the `description` field specifically:
```ShellSession
$ nix-env -qa hello --description
hello-2.3 A program that produces a familiar, friendly greeting
```
Meta-attributes are not passed to the builder of the package. Thus, a change to a meta-attribute doesn’t trigger a recompilation of the package.
## Standard meta-attributes {#sec-standard-meta-attributes}
@ -112,7 +66,7 @@ For details, see [Licenses](#sec-meta-license).
### `maintainers` {#var-meta-maintainers}
A list of the maintainers of this Nix expression. Maintainers are defined in [`nixpkgs/maintainers/maintainer-list.nix`](https://github.com/NixOS/nixpkgs/blob/master/maintainers/maintainer-list.nix). There is no restriction to becoming a maintainer, just add yourself to that list in a separate commit titled “maintainers: add alice”, and reference maintainers with `maintainers = with lib.maintainers; [ alice bob ]`.
A list of the maintainers of this Nix expression. Maintainers are defined in [`nixpkgs/maintainers/maintainer-list.nix`](https://github.com/NixOS/nixpkgs/blob/master/maintainers/maintainer-list.nix). There is no restriction to becoming a maintainer, just add yourself to that list in a separate commit titled “maintainers: add alice” in the same pull request, and reference maintainers with `maintainers = with lib.maintainers; [ alice bob ]`.
### `mainProgram` {#var-meta-mainProgram}

2
doc/stdenv/multiple-output.chapter.md
View File

@ -29,7 +29,7 @@ NixOS provides two ways to select the outputs to install for packages listed in
`nix-env` lacks an easy way to select the outputs to install. When installing a package, `nix-env` always installs the outputs listed in `meta.outputsToInstall`, even when the user explicitly selects an output.
::: {.warning}
`nix-env` silenty disregards the outputs selected by the user, and instead installs the outputs from `meta.outputsToInstall`. For example,
`nix-env` silently disregards the outputs selected by the user, and instead installs the outputs from `meta.outputsToInstall`. For example,
```ShellSession
$ nix-env -iA nixpkgs.coreutils.info

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

@ -11,7 +11,7 @@ stdenv.mkDerivation {
name = "libfoo-1.2.3";
src = fetchurl {
url = "http://example.org/libfoo-1.2.3.tar.bz2";
sha256 = "0x2g1jqygyr5wiwg4ma1nd7w4ydpy82z9gkcv8vh2v8dn3y58v5m";
hash = "sha256-tWxU/LANbQE32my+9AXyt3nCT7NBVfJ45CX757EMT3Q=";
};
}
```
@ -24,7 +24,7 @@ stdenv.mkDerivation rec {
version = "1.2.3";
src = fetchurl {
url = "http://example.org/libfoo-source-${version}.tar.bz2";
sha256 = "0x2g1jqygyr5wiwg4ma1nd7w4ydpy82z9gkcv8vh2v8dn3y58v5m";
hash = "sha256-tWxU/LANbQE32my+9AXyt3nCT7NBVfJ45CX757EMT3Q=";
};
}
```
@ -253,7 +253,7 @@ The propagated equivalent of `depsTargetTarget`. This is prefixed for the same r
#### `NIX_DEBUG` {#var-stdenv-NIX_DEBUG}
A natural number indicating how much information to log. If set to 1 or higher, `stdenv` will print moderate debugging information during the build. In particular, the `gcc` and `ld` wrapper scripts will print out the complete command line passed to the wrapped tools. If set to 6 or higher, the `stdenv` setup script will be run with `set -x` tracing. If set to 7 or higher, the `gcc` and `ld` wrapper scripts will also be run with `set -x` tracing.
A number between 0 and 7 indicating how much information to log. If set to 1 or higher, `stdenv` will print moderate debugging information during the build. In particular, the `gcc` and `ld` wrapper scripts will print out the complete command line passed to the wrapped tools. If set to 6 or higher, the `stdenv` setup script will be run with `set -x` tracing. If set to 7 or higher, the `gcc` and `ld` wrapper scripts will also be run with `set -x` tracing.
### Attributes affecting build properties {#attributes-affecting-build-properties}
@ -626,7 +626,7 @@ Before and after running `make`, the hooks `preBuild` and `postBuild` are called
### The check phase {#ssec-check-phase}
The check phase checks whether the package was built correctly by running its test suite. The default `checkPhase` calls `make check`, but only if the `doCheck` variable is enabled.
The check phase checks whether the package was built correctly by running its test suite. The default `checkPhase` calls `make $checkTarget`, but only if the `doCheck` variable is enabled (see below).
#### Variables controlling the check phase {#variables-controlling-the-check-phase}
@ -646,7 +646,7 @@ See the [build phase](#var-stdenv-makeFlags) for details.
##### `checkTarget` {#var-stdenv-checkTarget}
The make target that runs the tests. Defaults to `check`.
The make target that runs the tests. Defaults to `check` if it exists, otherwise `test`; if neither is found, do nothing.
##### `checkFlags` / `checkFlagsArray` {#var-stdenv-checkFlags}
@ -654,7 +654,11 @@ A list of strings passed as additional flags to `make`. Like `makeFlags` and `ma
##### `checkInputs` {#var-stdenv-checkInputs}
A list of dependencies used by the phase. This gets included in `nativeBuildInputs` when `doCheck` is set.
A list of host dependencies used by the phase, usually libraries linked into executables built during tests. This gets included in `buildInputs` when `doCheck` is set.
##### `nativeCheckInputs` {#var-stdenv-nativeCheckInputs}
A list of native dependencies used by the phase, notably tools needed on `$PATH`. This gets included in `nativeBuildInputs` when `doCheck` is set.
##### `preCheck` {#var-stdenv-preCheck}
@ -719,11 +723,11 @@ If set, libraries and executables are not stripped. By default, they are.
##### `dontStripHost` {#var-stdenv-dontStripHost}
Like `dontStrip`, but only affects the `strip` command targetting the package’s host platform. Useful when supporting cross compilation, but otherwise feel free to ignore.
Like `dontStrip`, but only affects the `strip` command targeting the package’s host platform. Useful when supporting cross compilation, but otherwise feel free to ignore.
##### `dontStripTarget` {#var-stdenv-dontStripTarget}
Like `dontStrip`, but only affects the `strip` command targetting the packages’ target platform. Useful when supporting cross compilation, but otherwise feel free to ignore.
Like `dontStrip`, but only affects the `strip` command targeting the packages’ target platform. Useful when supporting cross compilation, but otherwise feel free to ignore.
##### `dontMoveSbin` {#var-stdenv-dontMoveSbin}
@ -821,7 +825,11 @@ A list of strings passed as additional flags to `make`. Like `makeFlags` and `ma
##### `installCheckInputs` {#var-stdenv-installCheckInputs}
A list of dependencies used by the phase. This gets included in `nativeBuildInputs` when `doInstallCheck` is set.
A list of host dependencies used by the phase, usually libraries linked into executables built during tests. This gets included in `buildInputs` when `doInstallCheck` is set.
##### `nativeInstallCheckInputs` {#var-stdenv-nativeInstallCheckInputs}
A list of native dependencies used by the phase, notably tools needed on `$PATH`. This gets included in `nativeBuildInputs` when `doInstallCheck` is set.
##### `preInstallCheck` {#var-stdenv-preInstallCheck}
@ -837,6 +845,10 @@ The distribution phase is intended to produce a source distribution of the packa
#### Variables controlling the distribution phase {#variables-controlling-the-distribution-phase}
##### `doDist` {#var-stdenv-doDist}
If set, the distribution phase is executed.
##### `distTarget` {#var-stdenv-distTarget}
The make target that produces the distribution. Defaults to `dist`.
@ -990,6 +1002,32 @@ Convenience function for `makeWrapper` that replaces `<\executable\>` with a wra
If you will apply it multiple times, it will overwrite the wrapper file and you will end up with double wrapping, which should be avoided.
### `prependToVar` \<variableName\> \<elements...\> {#fun-prependToVar}
Prepend elements to a variable.
Example:
```shellSession
$ configureFlags="--disable-static"
$ prependToVar configureFlags --disable-dependency-tracking --enable-foo
$ echo $configureFlags
--disable-dependency-tracking --enable-foo --disable-static
```
### `appendToVar` \<variableName\> \<elements...\> {#fun-appendToVar}
Append elements to a variable.
Example:
```shellSession
$ configureFlags="--disable-static"
$ appendToVar configureFlags --disable-dependency-tracking --enable-foo
$ echo $configureFlags
--disable-static --disable-dependency-tracking --enable-foo
```
## Package setup hooks {#ssec-setup-hooks}
Nix itself considers a build-time dependency as merely something that should previously be built and accessible at build time—packages themselves are on their own to perform any additional setup. In most cases, that is fine, and the downstream derivation can deal with its own dependencies. But for a few common tasks, that would result in almost every package doing the same sort of setup work—depending not on the package itself, but entirely on which dependencies were used.

12
doc/using/configuration.chapter.md
View File

@ -73,7 +73,7 @@ There are also two ways to try compiling a package which has been marked as unsu
}
```
The difference between a package being unsupported on some system and being broken is admittedly a bit fuzzy. If a program *ought* to work on a certain platform, but doesn't, the platform should be included in `meta.platforms`, but marked as broken with e.g. `meta.broken = !hostPlatform.isWindows`. Of course, this begs the question of what \"ought\" means exactly. That is left to the package maintainer.
The difference between a package being unsupported on some system and being broken is admittedly a bit fuzzy. If a program *ought* to work on a certain platform, but doesn't, the platform should be included in `meta.platforms`, but marked as broken with e.g. `meta.broken = !hostPlatform.isWindows`. Of course, this begs the question of what "ought" means exactly. That is left to the package maintainer.
## Installing unfree packages {#sec-allow-unfree}
@ -310,16 +310,16 @@ For this to work fully, you must also have this script sourced when you are logg
```ShellSession
#!/bin/sh
if [ -d $HOME/.nix-profile/etc/profile.d ]; then
for i in $HOME/.nix-profile/etc/profile.d/*.sh; do
if [ -r $i ]; then
. $i
if [ -d "${HOME}/.nix-profile/etc/profile.d" ]; then
for i in "${HOME}/.nix-profile/etc/profile.d/"*.sh; do
if [ -r "$i" ]; then
. "$i"
fi
done
fi
```
Now just run `source $HOME/.profile` and you can starting loading man pages from your environment.
Now just run `. "${HOME}/.profile"` and you can start loading man pages from your environment.
### GNU info setup {#sec-gnu-info-setup}

6
doc/using/overrides.chapter.md
View File

@ -63,7 +63,7 @@ You should prefer `overrideAttrs` in almost all cases, see its documentation for
:::
::: {.warning}
Do not use this function in Nixpkgs as it evaluates a Derivation before modifying it, which breaks package abstraction and removes error-checking of function arguments. In addition, this evaluation-per-function application incurs a performance penalty, which can become a problem if many overrides are used. It is only intended for ad-hoc customisation, such as in `~/.config/nixpkgs/config.nix`.
Do not use this function in Nixpkgs as it evaluates a derivation before modifying it, which breaks package abstraction. In addition, this evaluation-per-function application incurs a performance penalty, which can become a problem if many overrides are used. It is only intended for ad-hoc customisation, such as in `~/.config/nixpkgs/config.nix`.
:::
The function `overrideDerivation` creates a new derivation based on an existing one by overriding the original's attributes with the attribute set produced by the specified function. This function is available on all derivations defined using the `makeOverridable` function. Most standard derivation-producing functions, such as `stdenv.mkDerivation`, are defined using this function, which means most packages in the nixpkgs expression, `pkgs`, have this function.
@ -74,8 +74,8 @@ Example usage:
mySed = pkgs.gnused.overrideDerivation (oldAttrs: {
name = "sed-4.2.2-pre";
src = fetchurl {
url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2;
sha256 = "11nq06d131y4wmf3drm0yk502d2xc6n5qy82cg88rb9nqd2lj41k";
url = "ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2";
hash = "sha256-MxBJRcM2rYzQYwJ5XKxhXTQByvSg5jZc5cSHEZoB2IY=";
};
patches = [];
});

19
lib/asserts.nix
View File

@ -16,11 +16,15 @@ rec {
assertMsg :: Bool -> String -> Bool
*/
# TODO(Profpatsch): add tests that check stderr
assertMsg = pred: msg:
assertMsg =
# Predicate that needs to succeed, otherwise `msg` is thrown
pred:
# Message to throw in case `pred` fails
msg:
pred || builtins.throw msg;
/* Specialized `assertMsg` for checking if val is one of the elements
of a list. Useful for checking enums.
/* Specialized `assertMsg` for checking if `val` is one of the elements
of the list `xs`. Useful for checking enums.
Example:
let sslLibrary = "libressl";
@ -33,7 +37,14 @@ rec {
Type:
assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool
*/
assertOneOf = name: val: xs: assertMsg
assertOneOf =
# The name of the variable the user entered `val` into, for inclusion in the error message
name:
# The value of what the user provided, to be compared against the values in `xs`
val:
# The list of valid values
xs:
assertMsg
(lib.elem val xs)
"${name} must be one of ${
lib.generators.toPretty {} xs}, but is: ${

511
lib/attrsets.nix
View File

@ -16,17 +16,29 @@ rec {
Example:
x = { a = { b = 3; }; }
# ["a" "b"] is equivalent to x.a.b
# 6 is a default value to return if the path does not exist in attrset
attrByPath ["a" "b"] 6 x
=> 3
attrByPath ["z" "z"] 6 x
=> 6
Type:
attrByPath :: [String] -> Any -> AttrSet -> Any
*/
attrByPath = attrPath: default: e:
attrByPath =
# A list of strings representing the attribute path to return from `set`
attrPath:
# Default value if `attrPath` does not resolve to an existing value
default:
# The nested attribute set to select values from
set:
let attr = head attrPath;
in
if attrPath == [] then e
else if e ? ${attr}
then attrByPath (tail attrPath) default e.${attr}
if attrPath == [] then set
else if set ? ${attr}
then attrByPath (tail attrPath) default set.${attr}
else default;
/* Return if an attribute from nested attribute set exists.
@ -38,8 +50,14 @@ rec {
hasAttrByPath ["z" "z"] x
=> false
Type:
hasAttrByPath :: [String] -> AttrSet -> Bool
*/
hasAttrByPath = attrPath: e:
hasAttrByPath =
# A list of strings representing the attribute path to check from `set`
attrPath:
# The nested attribute set to check
e:
let attr = head attrPath;
in
if attrPath == [] then true
@ -48,13 +66,20 @@ rec {
else false;
/* Return nested attribute set in which an attribute is set.
/* Create a new attribute set with `value` set at the nested attribute location specified in `attrPath`.
Example:
setAttrByPath ["a" "b"] 3
=> { a = { b = 3; }; }
Type:
setAttrByPath :: [String] -> Any -> AttrSet
*/
setAttrByPath = attrPath: value:
setAttrByPath =
# A list of strings representing the attribute path to set
attrPath:
# The value to set at the location described by `attrPath`
value:
let
len = length attrPath;
atDepth = n:
@ -63,8 +88,8 @@ rec {
else { ${elemAt attrPath n} = atDepth (n + 1); };
in atDepth 0;
/* Like `attrByPath' without a default value. If it doesn't find the
path it will throw.
/* Like `attrByPath`, but without a default value. If it doesn't find the
path it will throw an error.
Example:
x = { a = { b = 3; }; }
@ -72,18 +97,22 @@ rec {
=> 3
getAttrFromPath ["z" "z"] x
=> error: cannot find attribute `z.z'
Type:
getAttrFromPath :: [String] -> AttrSet -> Any
*/
getAttrFromPath = attrPath:
getAttrFromPath =
# A list of strings representing the attribute path to get from `set`
attrPath:
# The nested attribute set to find the value in.
set:
let errorMsg = "cannot find attribute `" + concatStringsSep "." attrPath + "'";
in attrByPath attrPath (abort errorMsg);
in attrByPath attrPath (abort errorMsg) set;
/* Map each attribute in the given set and merge them into a new attribute set.
Type:
concatMapAttrs ::
(String -> a -> AttrSet)
-> AttrSet
-> AttrSet
concatMapAttrs :: (String -> a -> AttrSet) -> AttrSet -> AttrSet
Example:
concatMapAttrs
@ -101,19 +130,23 @@ rec {
Takes a list of updates to apply and an attribute set to apply them to,
and returns the attribute set with the updates applied. Updates are
represented as { path = ...; update = ...; } values, where `path` is a
represented as `{ path = ...; update = ...; }` values, where `path` is a
list of strings representing the attribute path that should be updated,
and `update` is a function that takes the old value at that attribute path
as an argument and returns the new
value it should be.
Properties:
- Updates to deeper attribute paths are applied before updates to more
shallow attribute paths
- Multiple updates to the same attribute path are applied in the order
they appear in the update list
- If any but the last `path` element leads into a value that is not an
attribute set, an error is thrown
- If there is an update for an attribute path that doesn't exist,
accessing the argument in the update function causes an error, but
intermediate attribute sets are implicitly created as needed
@ -134,6 +167,8 @@ rec {
}
] { a.b.c = 0; }
=> { a = { b = { d = 1; }; }; x = { y = "xy"; }; }
Type: updateManyAttrsByPath :: [{ path :: [String]; update :: (Any -> Any); }] -> AttrSet -> AttrSet
*/
updateManyAttrsByPath = let
# When recursing into attributes, instead of updating the `path` of each
@ -199,8 +234,15 @@ rec {
Example:
attrVals ["a" "b" "c"] as
=> [as.a as.b as.c]
Type:
attrVals :: [String] -> AttrSet -> [Any]
*/
attrVals = nameList: set: map (x: set.${x}) nameList;
attrVals =
# The list of attributes to fetch from `set`. Each attribute name must exist on the attrbitue set
nameList:
# The set to get attribute values from
set: map (x: set.${x}) nameList;
/* Return the values of all attributes in the given set, sorted by
@ -209,6 +251,9 @@ rec {
Example:
attrValues {c = 3; a = 1; b = 2;}
=> [1 2 3]
Type:
attrValues :: AttrSet -> [Any]
*/
attrValues = builtins.attrValues or (attrs: attrVals (attrNames attrs) attrs);
@ -219,15 +264,25 @@ rec {
Example:
getAttrs [ "a" "b" ] { a = 1; b = 2; c = 3; }
=> { a = 1; b = 2; }
*/
getAttrs = names: attrs: genAttrs names (name: attrs.${name});
/* Collect each attribute named `attr' from a list of attribute
Type:
getAttrs :: [String] -> AttrSet -> AttrSet
*/
getAttrs =
# A list of attribute names to get out of `set`
names:
# The set to get the named attributes from
attrs: genAttrs names (name: attrs.${name});
/* Collect each attribute named `attr` from a list of attribute
sets. Sets that don't contain the named attribute are ignored.
Example:
catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]
=> [1 2]
Type:
catAttrs :: String -> [AttrSet] -> [Any]
*/
catAttrs = builtins.catAttrs or
(attr: l: concatLists (map (s: if s ? ${attr} then [s.${attr}] else []) l));
@ -239,8 +294,15 @@ rec {
Example:
filterAttrs (n: v: n == "foo") { foo = 1; bar = 2; }
=> { foo = 1; }
Type:
filterAttrs :: (String -> Any -> Bool) -> AttrSet -> AttrSet
*/
filterAttrs = pred: set:
filterAttrs =
# Predicate taking an attribute name and an attribute value, which returns `true` to include the attribute, or `false` to exclude the attribute.
pred:
# The attribute set to filter
set:
listToAttrs (concatMap (name: let v = set.${name}; in if pred name v then [(nameValuePair name v)] else []) (attrNames set));
@ -250,8 +312,15 @@ rec {
Example:
filterAttrsRecursive (n: v: v != null) { foo = { bar = null; }; }
=> { foo = {}; }
Type:
filterAttrsRecursive :: (String -> Any -> Bool) -> AttrSet -> AttrSet
*/
filterAttrsRecursive = pred: set:
filterAttrsRecursive =
# Predicate taking an attribute name and an attribute value, which returns `true` to include the attribute, or `false` to exclude the attribute.
pred:
# The attribute set to filter
set:
listToAttrs (
concatMap (name:
let v = set.${name}; in
@ -269,23 +338,29 @@ rec {
Example:
foldAttrs (item: acc: [item] ++ acc) [] [{ a = 2; } { a = 3; }]
=> { a = [ 2 3 ]; }
Type:
foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any
*/
foldAttrs = op: nul:
foldAttrs =
# A function, given a value and a collector combines the two.
op:
# The starting value.
nul:
# A list of attribute sets to fold together by key.
list_of_attrs:
foldr (n: a:
foldr (name: o:
o // { ${name} = op n.${name} (a.${name} or nul); }
) a (attrNames n)
) {};
) {} list_of_attrs;
/* Recursively collect sets that verify a given predicate named `pred'
from the set `attrs'. The recursion is stopped when the predicate is
/* Recursively collect sets that verify a given predicate named `pred`
from the set `attrs`. The recursion is stopped when the predicate is
verified.
Type:
collect ::
(AttrSet -> Bool) -> AttrSet -> [x]
Example:
collect isList { a = { b = ["b"]; }; c = [1]; }
=> [["b"] [1]]
@ -293,8 +368,15 @@ rec {
collect (x: x ? outPath)
{ a = { outPath = "a/"; }; b = { outPath = "b/"; }; }
=> [{ outPath = "a/"; } { outPath = "b/"; }]
Type:
collect :: (AttrSet -> Bool) -> AttrSet -> [x]
*/
collect = pred: attrs:
collect =
# Given an attribute's value, determine if recursion should stop.
pred:
# The attribute set to recursively collect.
attrs:
if pred attrs then
[ attrs ]
else if isAttrs attrs then
@ -312,8 +394,12 @@ rec {
{ a = 2; b = 10; }
{ a = 2; b = 20; }
]
Type:
cartesianProductOfSets :: AttrSet -> [AttrSet]
*/
cartesianProductOfSets = attrsOfLists:
cartesianProductOfSets =
# Attribute set with attributes that are lists of values
attrsOfLists:
foldl' (listOfAttrs: attrName:
concatMap (attrs:
map (listValue: attrs // { ${attrName} = listValue; }) attrsOfLists.${attrName}
@ -321,85 +407,108 @@ rec {
) [{}] (attrNames attrsOfLists);
/* Utility function that creates a {name, value} pair as expected by
builtins.listToAttrs.
/* Utility function that creates a `{name, value}` pair as expected by `builtins.listToAttrs`.
Example:
nameValuePair "some" 6
=> { name = "some"; value = 6; }
Type:
nameValuePair :: String -> Any -> { name :: String; value :: Any; }
*/
nameValuePair = name: value: { inherit name value; };
nameValuePair =
# Attribute name
name:
# Attribute value
value:
{ inherit name value; };
/* Apply a function to each element in an attribute set. The
function takes two arguments --- the attribute name and its value
--- and returns the new value for the attribute. The result is a
new attribute set.
/* Apply a function to each element in an attribute set, creating a new attribute set.
Example:
mapAttrs (name: value: name + "-" + value)
{ x = "foo"; y = "bar"; }
=> { x = "x-foo"; y = "y-bar"; }
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)));
/* Like `mapAttrs', but allows the name of each attribute to be
/* Like `mapAttrs`, but allows the name of each attribute to be
changed in addition to the value. The applied function should
return both the new name and value as a `nameValuePair'.
return both the new name and value as a `nameValuePair`.
Example:
mapAttrs' (name: value: nameValuePair ("foo_" + name) ("bar-" + value))
{ x = "a"; y = "b"; }
=> { foo_x = "bar-a"; foo_y = "bar-b"; }
Type:
mapAttrs' :: (String -> Any -> { name :: String; value :: Any; }) -> AttrSet -> AttrSet
*/
mapAttrs' = f: set:
mapAttrs' =
# A function, given an attribute's name and value, returns a new `nameValuePair`.
f:
# Attribute set to map over.
set:
listToAttrs (map (attr: f attr set.${attr}) (attrNames set));
/* Call a function for each attribute in the given set and return
the result in a list.
Type:
mapAttrsToList ::
(String -> a -> b) -> AttrSet -> [b]
Example:
mapAttrsToList (name: value: name + value)
{ x = "a"; y = "b"; }
=> [ "xa" "yb" ]
Type:
mapAttrsToList :: (String -> a -> b) -> AttrSet -> [b]
*/
mapAttrsToList = f: attrs:
mapAttrsToList =
# A function, given an attribute's name and value, returns a new value.
f:
# Attribute set to map over.
attrs:
map (name: f name attrs.${name}) (attrNames attrs);
/* Like `mapAttrs', except that it recursively applies itself to
attribute sets. Also, the first argument of the argument
function is a *list* of the names of the containing attributes.
/* 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.
Type:
mapAttrsRecursive ::
([String] -> a -> b) -> AttrSet -> AttrSet
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"; }
*/
mapAttrsRecursive = mapAttrsRecursiveCond (as: true);
/* 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.
Type:
mapAttrsRecursiveCond ::
(AttrSet -> Bool) -> ([String] -> a -> b) -> AttrSet -> AttrSet
mapAttrsRecursive :: ([String] -> a -> b) -> AttrSet -> AttrSet
*/
mapAttrsRecursive =
# A function, given a list of attribute names and a value, returns a new value.
f:
# 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.
Example:
# To prevent recursing into derivations (which are attribute
@ -408,8 +517,17 @@ rec {
(as: !(as ? "type" && as.type == "derivation"))
(x: ... do something ...)
attrs
Type:
mapAttrsRecursiveCond :: (AttrSet -> Bool) -> ([String] -> a -> b) -> AttrSet -> AttrSet
*/
mapAttrsRecursiveCond = cond: f: set:
mapAttrsRecursiveCond =
# A function, given the attribute set the recursion is currently at, determine if to recurse deeper into that attribute set.
cond:
# A function, given a list of attribute names and a value, returns a new value.
f:
# Attribute set to recursively map over.
set:
let
recurse = path:
let
@ -428,13 +546,20 @@ rec {
Example:
genAttrs [ "foo" "bar" ] (name: "x_" + name)
=> { foo = "x_foo"; bar = "x_bar"; }
Type:
genAttrs :: [ String ] -> (String -> Any) -> AttrSet
*/
genAttrs = names: f:
genAttrs =
# Names of values in the resulting attribute set.
names:
# A function, given the name of the attribute, returns the attribute's value.
f:
listToAttrs (map (n: nameValuePair n (f n)) names);
/* Check whether the argument is a derivation. Any set with
{ type = "derivation"; } counts as a derivation.
`{ type = "derivation"; }` counts as a derivation.
Example:
nixpkgs = import <nixpkgs> {}
@ -442,25 +567,36 @@ rec {
=> true
isDerivation "foobar"
=> false
*/
isDerivation = x: x.type or null == "derivation";
/* Converts a store path to a fake derivation. */
toDerivation = path:
let
path' = builtins.storePath path;
res =
{ type = "derivation";
name = sanitizeDerivationName (builtins.substring 33 (-1) (baseNameOf path'));
outPath = path';
outputs = [ "out" ];
out = res;
outputName = "out";
};
Type:
isDerivation :: Any -> Bool
*/
isDerivation =
# Value to check.
value: value.type or null == "derivation";
/* Converts a store path to a fake derivation.
Type:
toDerivation :: Path -> Derivation
*/
toDerivation =
# A store path to convert to a derivation.
path:
let
path' = builtins.storePath path;
res =
{ type = "derivation";
name = sanitizeDerivationName (builtins.substring 33 (-1) (baseNameOf path'));
outPath = path';
outputs = [ "out" ];
out = res;
outputName = "out";
};
in res;
/* If `cond' is true, return the attribute set `as',
/* If `cond` is true, return the attribute set `as`,
otherwise an empty attribute set.
Example:
@ -468,47 +604,82 @@ rec {
=> { my = "set"; }
optionalAttrs (false) { my = "set"; }
=> { }
Type:
optionalAttrs :: Bool -> AttrSet -> AttrSet
*/
optionalAttrs = cond: as: if cond then as else {};
optionalAttrs =
# Condition under which the `as` attribute set is returned.
cond:
# The attribute set to return if `cond` is `true`.
as:
if cond then as else {};
/* Merge sets of attributes and use the function f to merge attributes
/* Merge sets of attributes and use the function `f` to merge attributes
values.
Example:
zipAttrsWithNames ["a"] (name: vs: vs) [{a = "x";} {a = "y"; b = "z";}]
=> { a = ["x" "y"]; }
Type:
zipAttrsWithNames :: [ String ] -> (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet
*/
zipAttrsWithNames = names: f: sets:
zipAttrsWithNames =
# List of attribute names to zip.
names:
# A function, accepts an attribute name, all the values, and returns a combined value.
f:
# List of values from the list of attribute sets.
sets:
listToAttrs (map (name: {
inherit name;
value = f name (catAttrs name sets);
}) names);
/* Implementation note: Common names appear multiple times in the list of
/* Merge sets of attributes and use the function f to merge attribute values.
Like `lib.attrsets.zipAttrsWithNames` with all key names are passed for `names`.
Implementation note: Common names appear multiple times in the list of
names, hopefully this does not affect the system because the maximal
laziness avoid computing twice the same expression and listToAttrs does
laziness avoid computing twice the same expression and `listToAttrs` does
not care about duplicated attribute names.
Example:
zipAttrsWith (name: values: values) [{a = "x";} {a = "y"; b = "z";}]
=> { a = ["x" "y"]; b = ["z"] }
=> { a = ["x" "y"]; b = ["z"]; }
Type:
zipAttrsWith :: (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet
*/
zipAttrsWith =
builtins.zipAttrsWith or (f: sets: zipAttrsWithNames (concatMap attrNames sets) f sets);
/* Like `zipAttrsWith' with `(name: values: values)' as the function.
Example:
zipAttrs [{a = "x";} {a = "y"; b = "z";}]
=> { a = ["x" "y"]; b = ["z"] }
/* Merge sets of attributes and combine each attribute value in to a list.
Like `lib.attrsets.zipAttrsWith` with `(name: values: values)` as the function.
Example:
zipAttrs [{a = "x";} {a = "y"; b = "z";}]
=> { a = ["x" "y"]; b = ["z"]; }
Type:
zipAttrs :: [ AttrSet ] -> AttrSet
*/
zipAttrs = zipAttrsWith (name: values: values);
zipAttrs =
# List of attribute sets to zip together.
sets:
zipAttrsWith (name: values: values) sets;
/* Does the same as the update operator '//' except that attributes are
merged until the given predicate is verified. The predicate should
accept 3 arguments which are the path to reach the attribute, a part of
the first attribute set and a part of the second attribute set. When
the predicate is verified, the value of the first attribute set is
the predicate is satisfied, the value of the first attribute set is
replaced by the value of the second attribute set.
Example:
@ -524,15 +695,23 @@ rec {
baz = 4;
}
returns: {
=> {
foo.bar = 1; # 'foo.*' from the second set
foo.quz = 2; #
bar = 3; # 'bar' from the first set
baz = 4; # 'baz' from the second set
}
*/
recursiveUpdateUntil = pred: lhs: rhs:
Type:
recursiveUpdateUntil :: ( [ String ] -> AttrSet -> AttrSet -> Bool ) -> AttrSet -> AttrSet -> AttrSet
*/
recursiveUpdateUntil =
# Predicate, taking the path to the current attribute as a list of strings for attribute names, and the two values at that path from the original arguments.
pred:
# Left attribute set of the merge.
lhs:
# Right attribute set of the merge.
rhs:
let f = attrPath:
zipAttrsWith (n: values:
let here = attrPath ++ [n]; in
@ -544,6 +723,7 @@ rec {
);
in f [] [rhs lhs];
/* A recursive variant of the update operator ‘//’. The recursion
stops when one of the attribute values is not an attribute set,
in which case the right hand side value takes precedence over the
@ -562,16 +742,32 @@ rec {
boot.loader.grub.device = "";
}
*/
recursiveUpdate = recursiveUpdateUntil (path: lhs: rhs: !(isAttrs lhs && isAttrs rhs));
Type:
recursiveUpdate :: AttrSet -> AttrSet -> AttrSet
*/
recursiveUpdate =
# Left attribute set of the merge.
lhs:
# Right attribute set of the merge.
rhs:
recursiveUpdateUntil (path: lhs: rhs: !(isAttrs lhs && isAttrs rhs)) lhs rhs;
/* Returns true if the pattern is contained in the set. False otherwise.
Example:
matchAttrs { cpu = {}; } { cpu = { bits = 64; }; }
=> true
*/
matchAttrs = pattern: attrs: assert isAttrs pattern;
Type:
matchAttrs :: AttrSet -> AttrSet -> Bool
*/
matchAttrs =
# Attribute set structure to match
pattern:
# Attribute set to find patterns in
attrs:
assert isAttrs pattern;
all id (attrValues (zipAttrsWithNames (attrNames pattern) (n: values:
let pat = head values; val = elemAt values 1; in
if length values == 1 then false
@ -579,6 +775,7 @@ rec {
else pat == val
) [pattern attrs]));
/* Override only the attributes that are already present in the old set
useful for deep-overriding.
@ -589,62 +786,155 @@ rec {
=> { b = 2; }
overrideExisting { a = 3; b = 2; } { a = 1; }
=> { a = 1; b = 2; }
Type:
overrideExisting :: AttrSet -> AttrSet -> AttrSet
*/
overrideExisting = old: new:
overrideExisting =
# Original attribute set
old:
# Attribute set with attributes to override in `old`.
new:
mapAttrs (name: value: new.${name} or value) old;
/* Turns a list of strings into a human-readable description of those
strings represented as an attribute path. The result of this function is
not intended to be machine-readable.
Create a new attribute set with `value` set at the nested attribute location specified in `attrPath`.
Example:
showAttrPath [ "foo" "10" "bar" ]
=> "foo.\"10\".bar"
showAttrPath []
=> "<root attribute path>"
Type:
showAttrPath :: [String] -> String
*/
showAttrPath = path:
showAttrPath =
# Attribute path to render to a string
path:
if path == [] then "<root attribute path>"
else concatMapStringsSep "." escapeNixIdentifier path;
/* Get a package output.
If no output is found, fallback to `.out` and then to the default.
Example:
getOutput "dev" pkgs.openssl
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev"
Type:
getOutput :: String -> Derivation -> String
*/
getOutput = output: pkg:
if ! pkg ? outputSpecified || ! pkg.outputSpecified
then pkg.${output} or pkg.out or pkg
else pkg;
/* Get a package's `bin` output.
If the output does not exist, fallback to `.out` and then to the default.
Example:
getBin pkgs.openssl
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r"
Type:
getBin :: Derivation -> String
*/
getBin = getOutput "bin";
/* Get a package's `lib` output.
If the output does not exist, fallback to `.out` and then to the default.
Example:
getLib pkgs.openssl
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-lib"
Type:
getLib :: Derivation -> String
*/
getLib = getOutput "lib";
/* Get a package's `dev` output.
If the output does not exist, fallback to `.out` and then to the default.
Example:
getDev pkgs.openssl
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev"
Type:
getDev :: Derivation -> String
*/
getDev = getOutput "dev";
/* Get a package's `man` output.
If the output does not exist, fallback to `.out` and then to the default.
Example:
getMan pkgs.openssl
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-man"
Type:
getMan :: Derivation -> String
*/
getMan = getOutput "man";
/* Pick the outputs of packages to place in buildInputs */
chooseDevOutputs = builtins.map getDev;
/* Pick the outputs of packages to place in `buildInputs`
Type: chooseDevOutputs :: [Derivation] -> [String]
*/
chooseDevOutputs =
# List of packages to pick `dev` outputs from
drvs:
builtins.map getDev drvs;
/* Make various Nix tools consider the contents of the resulting
attribute set when looking for what to build, find, etc.
This function only affects a single attribute set; it does not
apply itself recursively for nested attribute sets.
Example:
{ pkgs ? import <nixpkgs> {} }:
{
myTools = pkgs.lib.recurseIntoAttrs {
inherit (pkgs) hello figlet;
};
}
Type:
recurseIntoAttrs :: AttrSet -> AttrSet
*/
recurseIntoAttrs =
attrs: attrs // { recurseForDerivations = true; };
# An attribute set to scan for derivations.
attrs:
attrs // { recurseForDerivations = true; };
/* Undo the effect of recurseIntoAttrs.
Type:
dontRecurseIntoAttrs :: AttrSet -> AttrSet
*/
dontRecurseIntoAttrs =
attrs: attrs // { recurseForDerivations = false; };
# An attribute set to not scan for derivations.
attrs:
attrs // { recurseForDerivations = false; };
/* `unionOfDisjoint x y` is equal to `x // y // z` where the
attrnames in `z` are the intersection of the attrnames in `x` and
`y`, and all values `assert` with an error message. This
operator is commutative, unlike (//). */
operator is commutative, unlike (//).
Type: unionOfDisjoint :: AttrSet -> AttrSet -> AttrSet
*/
unionOfDisjoint = x: y:
let
intersection = builtins.intersectAttrs x y;
@ -655,9 +945,10 @@ rec {
in
(x // y) // mask;
/*** deprecated stuff ***/
# DEPRECATED
zipWithNames = zipAttrsWithNames;
# DEPRECATED
zip = builtins.trace
"lib.zip is deprecated, use lib.zipAttrsWith instead" zipAttrsWith;
}

35
lib/customisation.nix
View File

@ -3,13 +3,13 @@
rec {
/* `overrideDerivation drv f' takes a derivation (i.e., the result
of a call to the builtin function `derivation') and returns a new
/* `overrideDerivation drv f` takes a derivation (i.e., the result
of a call to the builtin function `derivation`) and returns a new
derivation in which the attributes of the original are overridden
according to the function `f'. The function `f' is called with
according to the function `f`. The function `f` is called with
the original derivation attributes.
`overrideDerivation' allows certain "ad-hoc" customisation
`overrideDerivation` allows certain "ad-hoc" customisation
scenarios (e.g. in ~/.config/nixpkgs/config.nix). For instance,
if you want to "patch" the derivation returned by a package
function in Nixpkgs to build another version than what the
@ -27,11 +27,19 @@ rec {
For another application, see build-support/vm, where this
function is used to build arbitrary derivations inside a QEMU
virtual machine.
Note that in order to preserve evaluation errors, the new derivation's
outPath depends on the old one's, which means that this function cannot
be used in circular situations when the old derivation also depends on the
new one.
You should in general prefer `drv.overrideAttrs` over this function;
see the nixpkgs manual for more information on overriding.
*/
overrideDerivation = drv: f:
let
newDrv = derivation (drv.drvAttrs // (f drv));
in lib.flip (extendDerivation true) newDrv (
in lib.flip (extendDerivation (builtins.seq drv.drvPath true)) newDrv (
{ meta = drv.meta or {};
passthru = if drv ? passthru then drv.passthru else {};
}
@ -96,10 +104,10 @@ rec {
else result;
/* Call the package function in the file `fn' with the required
/* Call the package function in the file `fn` with the required
arguments automatically. The function is called with the
arguments `args', but any missing arguments are obtained from
`autoArgs'. This function is intended to be partially
arguments `args`, but any missing arguments are obtained from
`autoArgs`. This function is intended to be partially
parameterised, e.g.,
callPackage = callPackageWith pkgs;
@ -108,9 +116,9 @@ rec {
libbar = callPackage ./bar.nix { };
};
If the `libbar' function expects an argument named `libfoo', it is
If the `libbar` function expects an argument named `libfoo`, it is
automatically passed as an argument. Overrides or missing
arguments can be supplied in `args', e.g.
arguments can be supplied in `args`, e.g.
libbar = callPackage ./bar.nix {
libfoo = null;
@ -244,16 +252,17 @@ rec {
outputsList = map makeOutput outputs;
drv' = (lib.head outputsList).value;
in lib.deepSeq drv' drv';
in if drv == null then null else
lib.deepSeq drv' drv';
/* Make a set of packages with a common scope. All packages called
with the provided `callPackage' will be evaluated with the same
with the provided `callPackage` will be evaluated with the same
arguments. Any package in the set may depend on any other. The
`overrideScope'` function allows subsequent modification of the package
set in a consistent way, i.e. all packages in the set will be
called with the overridden packages. The package sets may be
hierarchical: the packages in the set are called with the scope
provided by `newScope' and the set provides a `newScope' attribute
provided by `newScope` and the set provides a `newScope` attribute
which can form the parent scope for later package sets. */
makeScope = newScope: f:
let self = f self // {

21
lib/default.nix
View File

@ -1,7 +1,7 @@
/* Library of low-level helper functions for nix expressions.
*
* Please implement (mostly) exhaustive unit tests
* for new functions in `./tests.nix'.
* for new functions in `./tests.nix`.
*/
let
@ -27,7 +27,6 @@ let
maintainers = import ../maintainers/maintainer-list.nix;
teams = callLibs ../maintainers/team-list.nix;
meta = callLibs ./meta.nix;
sources = callLibs ./sources.nix;
versions = callLibs ./versions.nix;
# module system
@ -53,7 +52,9 @@ let
fetchers = callLibs ./fetchers.nix;
# Eval-time filesystem handling
path = callLibs ./path;
filesystem = callLibs ./filesystem.nix;
sources = callLibs ./sources.nix;
# back-compat aliases
platforms = self.systems.doubles;
@ -63,7 +64,7 @@ let
inherit (builtins) add addErrorContext attrNames concatLists
deepSeq elem elemAt filter genericClosure genList getAttr
hasAttr head isAttrs isBool isInt isList isString length
hasAttr head isAttrs isBool isInt isList isPath isString length
lessThan listToAttrs pathExists readFile replaceStrings seq
stringLength sub substring tail trace;
inherit (self.trivial) id const pipe concat or and bitAnd bitOr bitXor
@ -93,16 +94,19 @@ let
subtractLists mutuallyExclusive groupBy groupBy';
inherit (self.strings) concatStrings concatMapStrings concatImapStrings
intersperse concatStringsSep concatMapStringsSep
concatImapStringsSep makeSearchPath makeSearchPathOutput
concatImapStringsSep concatLines makeSearchPath makeSearchPathOutput
makeLibraryPath makeBinPath optionalString
hasInfix hasPrefix hasSuffix stringToCharacters stringAsChars escape
escapeShellArg escapeShellArgs isValidPosixName toShellVar toShellVars
escapeShellArg escapeShellArgs
isStorePath isStringLike
isValidPosixName toShellVar toShellVars
escapeRegex escapeXML replaceChars lowerChars
upperChars toLower toUpper addContextFrom splitString
removePrefix removeSuffix versionOlder versionAtLeast
getName getVersion
mesonOption mesonBool mesonEnable
nameFromURL enableFeature enableFeatureAs withFeature
withFeatureAs fixedWidthString fixedWidthNumber isStorePath
withFeatureAs fixedWidthString fixedWidthNumber
toInt toIntBase10 readPathsFromFile fileContents;
inherit (self.stringsWithDeps) textClosureList textClosureMap
noDepEntry fullDepEntry packEntry stringAfter;
@ -127,14 +131,15 @@ let
mkAliasAndWrapDefinitions fixMergeModules mkRemovedOptionModule
mkRenamedOptionModule mkRenamedOptionModuleWith
mkMergedOptionModule mkChangedOptionModule
mkAliasOptionModule mkDerivedConfig doRename;
mkAliasOptionModule mkDerivedConfig doRename
mkAliasOptionModuleMD;
inherit (self.options) isOption mkEnableOption mkSinkUndeclaredOptions
mergeDefaultOption mergeOneOption mergeEqualOption mergeUniqueOption
getValues getFiles
optionAttrSetToDocList optionAttrSetToDocList'
scrubOptionValue literalExpression literalExample literalDocBook
showOption showOptionWithDefLocs showFiles
unknownModule mkOption mkPackageOption
unknownModule mkOption mkPackageOption mkPackageOptionMD
mdDoc literalMD;
inherit (self.types) isType setType defaultTypeMerge defaultFunctor
isOptionType mkOptionType;

2
lib/derivations.nix
View File

@ -17,7 +17,7 @@ in
situations below.
For illustration and/or testing, we define derivation such that its
evaluation is very noticable.
evaluation is very noticeable.
let derivation = throw "This won't be evaluated.";

4
lib/fixed-points.nix
View File

@ -107,7 +107,7 @@ rec {
# Same as `makeExtensible` but the name of the extending attribute is
# customized.
makeExtensibleWithCustomName = extenderName: rattrs:
fix' rattrs // {
fix' (self: (rattrs self) // {
${extenderName} = f: makeExtensibleWithCustomName extenderName (extends f rattrs);
};
});
}

51
lib/generators.nix
View File

@ -278,15 +278,20 @@ rec {
mapAny 0;
/* Pretty print a value, akin to `builtins.trace`.
* Should probably be a builtin as well.
*/
* Should probably be a builtin as well.
* The pretty-printed string should be suitable for rendering default values
* in the NixOS manual. In particular, it should be as close to a valid Nix expression
* as possible.
*/
toPretty = {
/* If this option is true, attrsets like { __pretty = fn; val = …; }
will use fn to convert val to a pretty printed representation.
(This means fn is type Val -> String.) */
allowPrettyValues ? false,
/* If this option is true, the output is indented with newlines for attribute sets and lists */
multiline ? true
multiline ? true,
/* Initial indentation level */
indent ? ""
}:
let
go = indent: v: with builtins;
@ -294,20 +299,25 @@ rec {
introSpace = if multiline then "\n${indent} " else " ";
outroSpace = if multiline then "\n${indent}" else " ";
in if isInt v then toString v
else if isFloat v then "~${toString v}"
# toString loses precision on floats, so we use toJSON instead. This isn't perfect
# as the resulting string may not parse back as a float (e.g. 42, 1e-06), but for
# pretty-printing purposes this is acceptable.
else if isFloat v then builtins.toJSON v
else if isString v then
let
# Separate a string into its lines
newlineSplits = filter (v: ! isList v) (builtins.split "\n" v);
# For a '' string terminated by a \n, which happens when the closing '' is on a new line
multilineResult = "''" + introSpace + concatStringsSep introSpace (lib.init newlineSplits) + outroSpace + "''";
# For a '' string not terminated by a \n, which happens when the closing '' is not on a new line
multilineResult' = "''" + introSpace + concatStringsSep introSpace newlineSplits + "''";
# For single lines, replace all newlines with their escaped representation
singlelineResult = "\"" + libStr.escape [ "\"" ] (concatStringsSep "\\n" newlineSplits) + "\"";
in if multiline && length newlineSplits > 1 then
if lib.last newlineSplits == "" then multilineResult else multilineResult'
else singlelineResult
lines = filter (v: ! isList v) (builtins.split "\n" v);
escapeSingleline = libStr.escape [ "\\" "\"" "\${" ];
escapeMultiline = libStr.replaceStrings [ "\${" "''" ] [ "''\${" "'''" ];
singlelineResult = "\"" + concatStringsSep "\\n" (map escapeSingleline lines) + "\"";
multilineResult = let
escapedLines = map escapeMultiline lines;
# The last line gets a special treatment: if it's empty, '' is on its own line at the "outer"
# indentation level. Otherwise, '' is appended to the last line.
lastLine = lib.last escapedLines;
in "''" + introSpace + concatStringsSep introSpace (lib.init escapedLines)
+ (if lastLine == "" then outroSpace else introSpace + lastLine) + "''";
in
if multiline && length lines > 1 then multilineResult else singlelineResult
else if true == v then "true"
else if false == v then "false"
else if null == v then "null"
@ -326,18 +336,21 @@ rec {
else "<function, args: {${showFnas}}>"
else if isAttrs v then
# apply pretty values if allowed
if attrNames v == [ "__pretty" "val" ] && allowPrettyValues
if allowPrettyValues && v ? __pretty && v ? val
then v.__pretty v.val
else if v == {} then "{ }"
else if v ? type && v.type == "derivation" then
"<derivation ${v.drvPath or "???"}>"
"<derivation ${v.name or "???"}>"
else "{" + introSpace
+ libStr.concatStringsSep introSpace (libAttr.mapAttrsToList
(name: value:
"${libStr.escapeNixIdentifier name} = ${go (indent + " ") value};") v)
"${libStr.escapeNixIdentifier name} = ${
builtins.addErrorContext "while evaluating an attribute `${name}`"
(go (indent + " ") value)
};") v)
+ outroSpace + "}"
else abort "generators.toPretty: should never happen (v = ${v})";
in go "";
in go indent;
# PLIST handling
toPlist = {}: v: let

24
lib/licenses.nix
View File

@ -558,6 +558,12 @@ in mkLicense lset) ({
redistributable = false;
};
fair = {
fullName = "Fair License";
spdxId = "Fair";
free = true;
};
issl = {
fullName = "Intel Simplified Software License";
url = "https://software.intel.com/en-us/license/intel-simplified-software-license";
@ -709,7 +715,12 @@ in mkLicense lset) ({
ncsa = {
spdxId = "NCSA";
fullName = "University of Illinois/NCSA Open Source License";
fullName = "University of Illinois/NCSA Open Source License";
};
nlpl = {
spdxId = "NLPL";
fullName = "No Limit Public License";
};
nposl3 = {
@ -842,6 +853,12 @@ in mkLicense lset) ({
fullName = "SGI Free Software License B v2.0";
};
# Gentoo seems to treat it as a license:
# https://gitweb.gentoo.org/repo/gentoo.git/tree/licenses/SGMLUG?id=7d999af4a47bf55e53e54713d98d145f935935c1
sgmlug = {
fullName = "SGML UG SGML Parser Materials license";
};
sleepycat = {
spdxId = "Sleepycat";
fullName = "Sleepycat License";
@ -969,6 +986,11 @@ in mkLicense lset) ({
fullName = "wxWindows Library Licence, Version 3.1";
};
x11 = {
spdxId = "X11";
fullName = "X11 License";
};
xfig = {
fullName = "xfig";
url = "http://mcj.sourceforge.net/authors.html#xfig"; # https is broken

10
lib/lists.nix
View File

@ -242,7 +242,7 @@ rec {
/* Return a singleton list or an empty list, depending on a boolean
value. Useful when building lists with optional elements
(e.g. `++ optional (system == "i686-linux") firefox').
(e.g. `++ optional (system == "i686-linux") firefox`).
Type: optional :: bool -> a -> [a]
@ -283,7 +283,7 @@ rec {
*/
toList = x: if isList x then x else [x];
/* Return a list of integers from `first' up to and including `last'.
/* Return a list of integers from `first` up to and including `last`.
Type: range :: int -> int -> [int]
@ -306,7 +306,7 @@ rec {
/* Splits the elements of a list in two lists, `right` and
`wrong`, depending on the evaluation of a predicate.
Type: (a -> bool) -> [a] -> { right :: [a], wrong :: [a] }
Type: (a -> bool) -> [a] -> { right :: [a]; wrong :: [a]; }
Example:
partition (x: x > 2) [ 5 1 2 3 4 ]
@ -320,7 +320,7 @@ rec {
) { right = []; wrong = []; });
/* 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.
Predicate should return a string which becomes keys of attrset `groupBy` returns.
`groupBy'` allows to customise the combining function and initial value
@ -374,7 +374,7 @@ rec {
/* Merges two lists of the same size together. If the sizes aren't the same
the merging stops at the shortest.
Type: zipLists :: [a] -> [b] -> [{ fst :: a, snd :: b}]
Type: zipLists :: [a] -> [b] -> [{ fst :: a; snd :: b; }]
Example:
zipLists [ 1 2 ] [ "a" "b" ]

13
lib/meta.nix
View File

@ -27,7 +27,7 @@ rec {
setName = name: drv: drv // {inherit name;};
/* Like `setName', but takes the previous name as an argument.
/* Like `setName`, but takes the previous name as an argument.
Example:
updateName (oldName: oldName + "-experimental") somePkg
@ -76,7 +76,9 @@ rec {
1. (legacy) a system string.
2. (modern) a pattern for the platform `parsed` field.
2. (modern) a pattern for the entire platform structure (see `lib.systems.inspect.platformPatterns`).
3. (modern) a pattern for the platform `parsed` field (see `lib.systems.inspect.patterns`).
We can inject these into a pattern for the whole of a structured platform,
and then match that.
@ -85,6 +87,8 @@ rec {
pattern =
if builtins.isString elem
then { system = elem; }
else if elem?parsed
then elem
else { parsed = elem; };
in lib.matchAttrs pattern platform;
@ -92,12 +96,13 @@ rec {
A package is available on a platform if both
1. One of `meta.platforms` pattern matches the given platform.
1. One of `meta.platforms` pattern matches the given
platform, or `meta.platforms` is not present.
2. None of `meta.badPlatforms` pattern matches the given platform.
*/
availableOn = platform: pkg:
lib.any (platformMatch platform) pkg.meta.platforms &&
((!pkg?meta.platforms) || lib.any (platformMatch platform) pkg.meta.platforms) &&
lib.all (elem: !platformMatch platform elem) (pkg.meta.badPlatforms or []);
/* Get the corresponding attribute in lib.licenses

54
lib/modules.nix
View File

@ -157,6 +157,11 @@ rec {
${if prefix == []
then null # unset => visible
else "internal"} = true;
# TODO: hidden during the markdown transition to not expose downstream
# users of the docs infra to markdown if they're not ready for it.
# we don't make this visible conditionally because it can impact
# performance (https://github.com/NixOS/nixpkgs/pull/208407#issuecomment-1368246192)
visible = false;
# TODO: Change the type of this option to a submodule with a
# freeformType, so that individual arguments can be documented
# separately
@ -284,7 +289,18 @@ rec {
if config._module.check && config._module.freeformType == null && merged.unmatchedDefns != [] then
let
firstDef = head merged.unmatchedDefns;
baseMsg = "The option `${showOption (prefix ++ firstDef.prefix)}' does not exist. Definition values:${showDefs [ firstDef ]}";
baseMsg =
let
optText = showOption (prefix ++ firstDef.prefix);
defText =
builtins.addErrorContext
"while evaluating the error message for definitions for `${optText}', which is an option that does not exist"
(builtins.addErrorContext
"while evaluating a definition from `${firstDef.file}'"
( showDefs [ firstDef ])
);
in
"The option `${optText}' does not exist. Definition values:${defText}";
in
if attrNames options == [ "_module" ]
then
@ -468,7 +484,7 @@ rec {
) (lib.functionArgs f);
# Note: we append in the opposite order such that we can add an error
# context on the explicited arguments of "args" too. This update
# context on the explicit arguments of "args" too. This update
# operator is used to make the "args@{ ... }: with args.lib;" notation
# works.
in f (args // extraArgs)
@ -833,7 +849,7 @@ rec {
filterOverrides' = defs:
let
getPrio = def: if def.value._type or "" == "override" then def.value.priority else defaultPriority;
getPrio = def: if def.value._type or "" == "override" then def.value.priority else defaultOverridePriority;
highestPrio = foldl' (prio: def: min (getPrio def) prio) 9999 defs;
strip = def: if def.value._type or "" == "override" then def // { value = def.value.content; } else def;
in {
@ -842,7 +858,7 @@ rec {
};
/* Sort a list of properties. The sort priority of a property is
1000 by default, but can be overridden by wrapping the property
defaultOrderPriority by default, but can be overridden by wrapping the property
using mkOrder. */
sortProperties = defs:
let
@ -851,7 +867,7 @@ rec {
then def // { value = def.value.content; inherit (def.value) priority; }
else def;
defs' = map strip defs;
compare = a: b: (a.priority or 1000) < (b.priority or 1000);
compare = a: b: (a.priority or defaultOrderPriority) < (b.priority or defaultOrderPriority);
in sort compare defs';
# This calls substSubModules, whose entire purpose is only to ensure that
@ -887,10 +903,13 @@ rec {
mkOptionDefault = mkOverride 1500; # priority of option defaults
mkDefault = mkOverride 1000; # used in config sections of non-user modules to set a default
defaultOverridePriority = 100;
mkImageMediaOverride = mkOverride 60; # image media profiles can be derived by inclusion into host config, hence needing to override host config, but do allow user to mkForce
mkForce = mkOverride 50;
mkVMOverride = mkOverride 10; # used by ‘nixos-rebuild build-vm’
defaultPriority = lib.warnIf (lib.isInOldestRelease 2305) "lib.modules.defaultPriority is deprecated, please use lib.modules.defaultOverridePriority instead." defaultOverridePriority;
mkFixStrictness = lib.warn "lib.mkFixStrictness has no effect and will be removed. It returns its argument unmodified, so you can just remove any calls." id;
mkOrder = priority: content:
@ -899,11 +918,9 @@ rec {
};
mkBefore = mkOrder 500;
defaultOrderPriority = 1000;
mkAfter = mkOrder 1500;
# The default priority for things that don't have a priority specified.
defaultPriority = 100;
# Convenient property used to transfer all definitions and their
# properties from one option to another. This property is useful for
# renaming options, and also for including properties from another module
@ -930,10 +947,10 @@ rec {
# Similar to mkAliasAndWrapDefinitions but copies over the priority from the
# option as well.
#
# If a priority is not set, it assumes a priority of defaultPriority.
# If a priority is not set, it assumes a priority of defaultOverridePriority.
mkAliasAndWrapDefsWithPriority = wrap: option:
let
prio = option.highestPrio or defaultPriority;
prio = option.highestPrio or defaultOverridePriority;
defsWithPrio = map (mkOverride prio) option.definitions;
in mkAliasIfDef option (wrap (mkMerge defsWithPrio));
@ -1098,6 +1115,15 @@ rec {
use = id;
};
/* Transitional version of mkAliasOptionModule that uses MD docs. */
mkAliasOptionModuleMD = from: to: doRename {
inherit from to;
visible = true;
warn = false;
use = id;
markdown = true;
};
/* mkDerivedConfig : Option a -> (a -> Definition b) -> Definition b
Create config definitions with the same priority as the definition of another option.
@ -1115,10 +1141,10 @@ rec {
# to definitions.
mkDerivedConfig = opt: f:
mkOverride
(opt.highestPrio or defaultPriority)
(opt.highestPrio or defaultOverridePriority)
(f opt.value);
doRename = { from, to, visible, warn, use, withPriority ? true }:
doRename = { from, to, visible, warn, use, withPriority ? true, markdown ? false }:
{ config, options, ... }:
let
fromOpt = getAttrFromPath from options;
@ -1129,7 +1155,9 @@ rec {
{
options = setAttrByPath from (mkOption {
inherit visible;
description = lib.mdDoc "Alias of {option}`${showOption to}`.";
description = if markdown
then lib.mdDoc "Alias of {option}`${showOption to}`."
else "Alias of <option>${showOption to}</option>.";
apply = x: use (toOf config);
} // optionalAttrs (toType != null) {
type = toType;

49
lib/options.nix
View File

@ -104,8 +104,6 @@ rec {
/* Creates an Option attribute set for an option that specifies the
package a module should use for some purpose.
Type: mkPackageOption :: pkgs -> string -> { default :: [string], example :: null | string | [string] } -> option
The package is specified as a list of strings representing its attribute path in nixpkgs.
Because of this, you need to pass nixpkgs itself as the first argument.
@ -116,6 +114,8 @@ rec {
You can omit the default path if the name of the option is also attribute path in nixpkgs.
Type: mkPackageOption :: pkgs -> string -> { default :: [string]; example :: null | string | [string]; } -> option
Example:
mkPackageOption pkgs "hello" { }
=> { _type = "option"; default = «derivation /nix/store/3r2vg51hlxj3cx5vscp0vkv60bqxkaq0-hello-2.10.drv»; defaultText = { ... }; description = "The hello package to use."; type = { ... }; }
@ -136,7 +136,7 @@ rec {
let default' = if !isList default then [ default ] else default;
in mkOption {
type = lib.types.package;
description = lib.mdDoc "The ${name} package to use.";
description = "The ${name} package to use.";
default = attrByPath default'
(throw "${concatStringsSep "." default'} cannot be found in pkgs") pkgs;
defaultText = literalExpression ("pkgs." + concatStringsSep "." default');
@ -144,6 +144,11 @@ rec {
(if isList example then "pkgs." + concatStringsSep "." example else example);
};
/* Like mkPackageOption, but emit an mdDoc description instead of DocBook. */
mkPackageOptionMD = args: name: extra:
let option = mkPackageOption args name extra;
in option // { description = lib.mdDoc option.description; };
/* This option accepts anything, but it does not produce any result.
This is useful for sharing a module across different module sets
@ -196,7 +201,7 @@ rec {
/* Extracts values of all "value" keys of the given list.
Type: getValues :: [ { value :: a } ] -> [a]
Type: getValues :: [ { value :: a; } ] -> [a]
Example:
getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
@ -206,7 +211,7 @@ rec {
/* Extracts values of all "file" keys of the given list
Type: getFiles :: [ { file :: a } ] -> [a]
Type: getFiles :: [ { file :: a; } ] -> [a]
Example:
getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
@ -218,12 +223,13 @@ rec {
# the set generated with filterOptionSets.
optionAttrSetToDocList = optionAttrSetToDocList' [];
optionAttrSetToDocList' = prefix: options:
optionAttrSetToDocList' = _: options:
concatMap (opt:
let
name = showOption opt.loc;
docOption = rec {
loc = opt.loc;
name = showOption opt.loc;
inherit name;
description = opt.description or null;
declarations = filter (x: x != unknownModule) opt.declarations;
internal = opt.internal or false;
@ -234,9 +240,18 @@ rec {
readOnly = opt.readOnly or false;
type = opt.type.description or "unspecified";
}
// optionalAttrs (opt ? example) { example = scrubOptionValue opt.example; }
// optionalAttrs (opt ? default) { default = scrubOptionValue opt.default; }
// optionalAttrs (opt ? defaultText) { default = opt.defaultText; }
// optionalAttrs (opt ? example) {
example =
builtins.addErrorContext "while evaluating the example of option `${name}`" (
renderOptionValue opt.example
);
}
// optionalAttrs (opt ? default) {
default =
builtins.addErrorContext "while evaluating the default value of option `${name}`" (
renderOptionValue (opt.defaultText or opt.default)
);
}
// optionalAttrs (opt ? relatedPackages && opt.relatedPackages != null) { inherit (opt) relatedPackages; };
subOptions =
@ -256,6 +271,9 @@ rec {
efficient: the XML representation of derivations is very large
(on the order of megabytes) and is not actually used by the
manual generator.
This function was made obsolete by renderOptionValue and is kept for
compatibility with out-of-tree code.
*/
scrubOptionValue = x:
if isDerivation x then
@ -265,6 +283,17 @@ rec {
else x;
/* Ensures that the given option value (default or example) is a `_type`d string
by rendering Nix values to `literalExpression`s.
*/
renderOptionValue = v:
if v ? _type && v ? text then v
else literalExpression (lib.generators.toPretty {
multiline = true;
allowPrettyValues = true;
} v);
/* For use in the `defaultText` and `example` option attributes. Causes the
given string to be rendered verbatim in the documentation as Nix code. This
is necessary for complex values, e.g. functions, or values that depend on

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