Project import generated by Copybara.

GitOrigin-RevId: 6cee3b5893090b0f5f0a06b4cf42ca4e60e5d222
This commit is contained in:
Default email 2023-07-15 19:15:38 +02:00
parent d1a4a792ef
commit 9c6ee729d6
7164 changed files with 291314 additions and 145986 deletions

View file

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

View file

@ -23,7 +23,7 @@
# Libraries # Libraries
/lib @edolstra @infinisil /lib @edolstra @infinisil
/lib/systems @alyssais @ericson2314 @matthewbauer /lib/systems @alyssais @ericson2314 @matthewbauer @amjoseph-nixpkgs
/lib/generators.nix @edolstra @Profpatsch /lib/generators.nix @edolstra @Profpatsch
/lib/cli.nix @edolstra @Profpatsch /lib/cli.nix @edolstra @Profpatsch
/lib/debug.nix @edolstra @Profpatsch /lib/debug.nix @edolstra @Profpatsch
@ -37,10 +37,10 @@
/pkgs/top-level/stage.nix @Ericson2314 @matthewbauer /pkgs/top-level/stage.nix @Ericson2314 @matthewbauer
/pkgs/top-level/splice.nix @Ericson2314 @matthewbauer /pkgs/top-level/splice.nix @Ericson2314 @matthewbauer
/pkgs/top-level/release-cross.nix @Ericson2314 @matthewbauer /pkgs/top-level/release-cross.nix @Ericson2314 @matthewbauer
/pkgs/stdenv/generic @Ericson2314 @matthewbauer /pkgs/stdenv/generic @Ericson2314 @matthewbauer @amjoseph-nixpkgs
/pkgs/stdenv/generic/check-meta.nix @Ericson2314 @matthewbauer @piegamesde /pkgs/stdenv/generic/check-meta.nix @Ericson2314 @matthewbauer @piegamesde
/pkgs/stdenv/cross @Ericson2314 @matthewbauer /pkgs/stdenv/cross @Ericson2314 @matthewbauer @amjoseph-nixpkgs
/pkgs/build-support/cc-wrapper @Ericson2314 /pkgs/build-support/cc-wrapper @Ericson2314 @amjoseph-nixpkgs
/pkgs/build-support/bintools-wrapper @Ericson2314 /pkgs/build-support/bintools-wrapper @Ericson2314
/pkgs/build-support/setup-hooks @Ericson2314 /pkgs/build-support/setup-hooks @Ericson2314
/pkgs/build-support/setup-hooks/auto-patchelf.sh @layus /pkgs/build-support/setup-hooks/auto-patchelf.sh @layus
@ -58,13 +58,9 @@
/maintainers/scripts/db-to-md.sh @jtojnar @ryantm /maintainers/scripts/db-to-md.sh @jtojnar @ryantm
/maintainers/scripts/doc @jtojnar @ryantm /maintainers/scripts/doc @jtojnar @ryantm
/doc/* @fricklerhandwerk
/doc/build-aux/pandoc-filters @jtojnar /doc/build-aux/pandoc-filters @jtojnar
/doc/builders/trivial-builders.chapter.md @fricklerhandwerk
/doc/contributing/ @fricklerhandwerk /doc/contributing/ @fricklerhandwerk
/doc/contributing/contributing-to-documentation.chapter.md @jtojnar @fricklerhandwerk /doc/contributing/contributing-to-documentation.chapter.md @jtojnar @fricklerhandwerk
/doc/stdenv @fricklerhandwerk
/doc/using @fricklerhandwerk
# NixOS Internals # NixOS Internals
/nixos/default.nix @infinisil /nixos/default.nix @infinisil
@ -128,7 +124,7 @@
/doc/languages-frameworks/rust.section.md @zowoq @winterqt @figsoda /doc/languages-frameworks/rust.section.md @zowoq @winterqt @figsoda
# C compilers # C compilers
/pkgs/development/compilers/gcc @matthewbauer /pkgs/development/compilers/gcc @matthewbauer @amjoseph-nixpkgs
/pkgs/development/compilers/llvm @matthewbauer @RaitoBezarius /pkgs/development/compilers/llvm @matthewbauer @RaitoBezarius
# Compatibility stuff # Compatibility stuff
@ -236,12 +232,12 @@ pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt
/nixos/tests/prometheus-exporters.nix @WilliButz /nixos/tests/prometheus-exporters.nix @WilliButz
# PHP interpreter, packages, extensions, tests and documentation # PHP interpreter, packages, extensions, tests and documentation
/doc/languages-frameworks/php.section.md @aanderse @etu @globin @ma27 @talyz /doc/languages-frameworks/php.section.md @aanderse @drupol @etu @globin @ma27 @talyz
/nixos/tests/php @aanderse @etu @globin @ma27 @talyz /nixos/tests/php @aanderse @drupol @etu @globin @ma27 @talyz
/pkgs/build-support/build-pecl.nix @aanderse @etu @globin @ma27 @talyz /pkgs/build-support/build-pecl.nix @aanderse @drupol @etu @globin @ma27 @talyz
/pkgs/development/interpreters/php @jtojnar @aanderse @etu @globin @ma27 @talyz /pkgs/development/interpreters/php @jtojnar @aanderse @drupol @etu @globin @ma27 @talyz
/pkgs/development/php-packages @aanderse @etu @globin @ma27 @talyz /pkgs/development/php-packages @aanderse @drupol @etu @globin @ma27 @talyz
/pkgs/top-level/php-packages.nix @jtojnar @aanderse @etu @globin @ma27 @talyz /pkgs/top-level/php-packages.nix @jtojnar @aanderse @drupol @etu @globin @ma27 @talyz
# Podman, CRI-O modules and related # Podman, CRI-O modules and related
/nixos/modules/virtualisation/containers.nix @zowoq @adisbladis /nixos/modules/virtualisation/containers.nix @zowoq @adisbladis
@ -297,11 +293,18 @@ pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt
/pkgs/development/compilers/dotnet @IvarWithoutBones /pkgs/development/compilers/dotnet @IvarWithoutBones
# Node.js # Node.js
/pkgs/build-support/node/build-npm-package @winterqt /pkgs/build-support/node/build-npm-package @lilyinstarlight @winterqt
/pkgs/build-support/node/fetch-npm-deps @winterqt /pkgs/build-support/node/fetch-npm-deps @lilyinstarlight @winterqt
/doc/languages-frameworks/javascript.section.md @winterqt /doc/languages-frameworks/javascript.section.md @lilyinstarlight @winterqt
# OCaml # OCaml
/pkgs/build-support/ocaml @romildo @ulrikstrid /pkgs/build-support/ocaml @ulrikstrid
/pkgs/development/compilers/ocaml @romildo @ulrikstrid /pkgs/development/compilers/ocaml @ulrikstrid
/pkgs/development/ocaml-modules @romildo @ulrikstrid /pkgs/development/ocaml-modules @ulrikstrid
# ZFS
pkgs/os-specific/linux/zfs @raitobezarius
nixos/lib/make-single-disk-zfs-image.nix @raitobezarius
nixos/lib/make-multi-disk-zfs-image.nix @raitobezarius
nixos/modules/tasks/filesystems/zfs.nix @raitobezarius
nixos/tests/zfs.nix @raitobezarius

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 - 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 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/`) - [ ] Tested basic functionality of all binary files (usually in `./result/bin/`)
- [23.05 Release Notes (or backporting 22.11 Release notes)](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#generating-2305-release-notes) - [23.11 Release Notes](https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/manual/release-notes/rl-2311.section.md) (or backporting [23.05 Release notes](https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/manual/release-notes/rl-2305.section.md))
- [ ] (Package updates) Added a release notes entry if the change is major or breaking - [ ] (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 updates) Added a release notes entry if the change is significant
- [ ] (Module addition) Added a release notes entry if adding a new NixOS module - [ ] (Module addition) Added a release notes entry if adding a new NixOS module

View file

@ -64,6 +64,9 @@
- pkgs/build-support/kernel/**/* - pkgs/build-support/kernel/**/*
- pkgs/os-specific/linux/kernel/**/* - pkgs/os-specific/linux/kernel/**/*
"6.topic: lib":
- lib/**
"6.topic: lua": "6.topic: lua":
- pkgs/development/interpreters/lua-5/**/* - pkgs/development/interpreters/lua-5/**/*
- pkgs/development/interpreters/luajit/**/* - pkgs/development/interpreters/luajit/**/*
@ -83,6 +86,13 @@
- nixos/tests/mate.nix - nixos/tests/mate.nix
- pkgs/desktops/mate/**/* - pkgs/desktops/mate/**/*
"6.topic: module system":
- lib/modules.nix
- lib/types.nix
- lib/options.nix
- lib/tests/modules.sh
- lib/tests/modules/**
"6.topic: nixos": "6.topic: nixos":
- nixos/**/* - nixos/**/*
- pkgs/os-specific/linux/nixos-rebuild/**/* - pkgs/os-specific/linux/nixos-rebuild/**/*
@ -93,6 +103,14 @@
- pkgs/development/nim-packages/**/* - pkgs/development/nim-packages/**/*
- pkgs/top-level/nim-packages.nix - pkgs/top-level/nim-packages.nix
"6.topic: nodejs":
- doc/languages-frameworks/javascript.section.md
- pkgs/build-support/node/**/*
- pkgs/development/node-packages/**/*
- pkgs/development/tools/yarn/*
- pkgs/development/tools/yarn2nix-moretea/**/*
- pkgs/development/web/nodejs/*
"6.topic: ocaml": "6.topic: ocaml":
- doc/languages-frameworks/ocaml.section.md - doc/languages-frameworks/ocaml.section.md
- pkgs/development/compilers/ocaml/**/* - pkgs/development/compilers/ocaml/**/*

View file

@ -24,7 +24,7 @@ jobs:
with: with:
ref: ${{ github.event.pull_request.head.sha }} ref: ${{ github.event.pull_request.head.sha }}
- name: Create backport PRs - name: Create backport PRs
uses: korthout/backport-action@v1.2.0 uses: korthout/backport-action@v1.3.1
with: with:
# Config README: https://github.com/korthout/backport-action#backport-action # Config README: https://github.com/korthout/backport-action#backport-action
copy_labels_pattern: 'severity:\ssecurity' copy_labels_pattern: 'severity:\ssecurity'

View file

@ -19,7 +19,7 @@ jobs:
# we don't limit this action to only NixOS repo since the checks are cheap and useful developer feedback # we don't limit this action to only NixOS repo since the checks are cheap and useful developer feedback
steps: steps:
- uses: actions/checkout@v3 - uses: actions/checkout@v3
- uses: cachix/install-nix-action@v20 - uses: cachix/install-nix-action@v22
- uses: cachix/cachix-action@v12 - uses: cachix/cachix-action@v12
with: with:
# This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere. # This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.

View file

@ -16,7 +16,7 @@ jobs:
with: with:
# pull_request_target checks out the base branch by default # pull_request_target checks out the base branch by default
ref: refs/pull/${{ github.event.pull_request.number }}/merge ref: refs/pull/${{ github.event.pull_request.number }}/merge
- uses: cachix/install-nix-action@v20 - uses: cachix/install-nix-action@v22
with: with:
# explicitly enable sandbox # explicitly enable sandbox
extra_nix_config: sandbox = true extra_nix_config: sandbox = true

View file

@ -1,21 +0,0 @@
#!/usr/bin/env nix-shell
#! nix-shell -i bash -p html-tidy
set -euo pipefail
shopt -s inherit_errexit
normalize() {
tidy \
--anchor-as-name no \
--coerce-endtags no \
--escape-scripts no \
--fix-backslash no \
--fix-style-tags no \
--fix-uri no \
--indent yes \
--wrap 0 \
< "$1" \
2> /dev/null
}
diff -U3 <(normalize "$1") <(normalize "$2")

View file

@ -28,7 +28,7 @@ jobs:
with: with:
# pull_request_target checks out the base branch by default # pull_request_target checks out the base branch by default
ref: refs/pull/${{ github.event.pull_request.number }}/merge ref: refs/pull/${{ github.event.pull_request.number }}/merge
- uses: cachix/install-nix-action@v20 - uses: cachix/install-nix-action@v22
with: with:
# nixpkgs commit is pinned so that it doesn't break # nixpkgs commit is pinned so that it doesn't break
# editorconfig-checker 2.4.0 # editorconfig-checker 2.4.0

View file

@ -18,7 +18,7 @@ jobs:
with: with:
# pull_request_target checks out the base branch by default # pull_request_target checks out the base branch by default
ref: refs/pull/${{ github.event.pull_request.number }}/merge ref: refs/pull/${{ github.event.pull_request.number }}/merge
- uses: cachix/install-nix-action@v20 - uses: cachix/install-nix-action@v22
with: with:
# explicitly enable sandbox # explicitly enable sandbox
extra_nix_config: sandbox = true extra_nix_config: sandbox = true
@ -27,13 +27,5 @@ jobs:
# This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere. # This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.
name: nixpkgs-ci name: nixpkgs-ci
signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}' signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'
- name: Building NixOS manual with DocBook options - name: Building NixOS manual
run: NIX_PATH=nixpkgs=$(pwd) nix-build --option restrict-eval true nixos/release.nix -A manual.x86_64-linux run: NIX_PATH=nixpkgs=$(pwd) nix-build --option restrict-eval true nixos/release.nix -A manual.x86_64-linux
- name: Building NixOS manual with Markdown options
run: |
export NIX_PATH=nixpkgs=$(pwd)
nix-build \
--option restrict-eval true \
--arg configuration '{ documentation.nixos.options.allowDocBook = false; }' \
nixos/release.nix \
-A manual.x86_64-linux

View file

@ -19,7 +19,7 @@ jobs:
with: with:
# pull_request_target checks out the base branch by default # pull_request_target checks out the base branch by default
ref: refs/pull/${{ github.event.pull_request.number }}/merge ref: refs/pull/${{ github.event.pull_request.number }}/merge
- uses: cachix/install-nix-action@v20 - uses: cachix/install-nix-action@v22
with: with:
# explicitly enable sandbox # explicitly enable sandbox
extra_nix_config: sandbox = true extra_nix_config: sandbox = true

View file

@ -1,64 +0,0 @@
name: "Check NixOS Manual DocBook rendering against MD rendering"
on:
schedule:
# * is a special character in YAML so you have to quote this string
# Check every 24 hours
- cron: '0 0 * * *'
permissions:
contents: read
jobs:
check-rendering-equivalence:
permissions:
pull-requests: write # for peter-evans/create-or-update-comment to create or update comment
if: github.repository_owner == 'NixOS'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: cachix/install-nix-action@v20
with:
# explicitly enable sandbox
extra_nix_config: sandbox = true
- uses: cachix/cachix-action@v12
with:
# This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.
name: nixpkgs-ci
signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'
- name: Build DocBook and MD manuals
run: |
export NIX_PATH=nixpkgs=$(pwd)
nix-build \
--option restrict-eval true \
-o docbook nixos/release.nix \
-A manual.x86_64-linux
nix-build \
--option restrict-eval true \
--arg configuration '{ documentation.nixos.options.allowDocBook = false; }' \
-o md nixos/release.nix \
-A manual.x86_64-linux
- name: Compare DocBook and MD manuals
id: check
run: |
export NIX_PATH=nixpkgs=$(pwd)
.github/workflows/compare-manuals.sh \
docbook/share/doc/nixos/options.html \
md/share/doc/nixos/options.html
# if the manual can't be built we don't want to notify anyone.
# while this may temporarily hide rendering failures it will be a lot
# less noisy until all nixpkgs pull requests have stopped using
# docbook for option docs.
- name: Comment on failure
uses: peter-evans/create-or-update-comment@v3
if: ${{ failure() && steps.check.conclusion == 'failure' }}
with:
issue-number: 189318
body: |
Markdown and DocBook manuals do not agree.
Check https://github.com/NixOS/nixpkgs/actions/runs/${{ github.run_id }} for details.

View file

@ -34,10 +34,6 @@ jobs:
pairs: pairs:
- from: master - from: master
into: haskell-updates into: haskell-updates
- from: release-22.11
into: staging-next-22.11
- from: staging-next-22.11
into: staging-22.11
- from: release-23.05 - from: release-23.05
into: staging-next-23.05 into: staging-next-23.05
- from: staging-next-23.05 - from: staging-next-23.05

View file

@ -17,7 +17,7 @@ jobs:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- uses: actions/checkout@v3 - uses: actions/checkout@v3
- uses: cachix/install-nix-action@v20 - uses: cachix/install-nix-action@v22
with: with:
nix_path: nixpkgs=channel:nixpkgs-unstable nix_path: nixpkgs=channel:nixpkgs-unstable
- name: setup - name: setup

View file

@ -61,6 +61,15 @@ Pull requests should not be squash merged in order to keep complete commit messa
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`. 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). Useful git commands that can help a lot with this are `git commit --patch --amend` and `git rebase --interactive`. For more details consult the git man pages or online resources like [git-rebase.io](https://git-rebase.io/) or [The Pro Git Book](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History).
## Testing changes
To run the main types of tests locally:
- Run package-internal tests with `nix-build --attr pkgs.PACKAGE.passthru.tests`
- Run [NixOS tests](https://nixos.org/manual/nixos/unstable/#sec-nixos-tests) with `nix-build --attr nixosTest.NAME`, where `NAME` is the name of the test listed in `nixos/tests/all-tests.nix`
- Run [global package tests](https://nixos.org/manual/nixpkgs/unstable/#sec-package-tests) with `nix-build --attr tests.PACKAGE`, where `PACKAGE` is the name of the test listed in `pkgs/test/default.nix`
- See `lib/tests/NAME.nix` for instructions on running specific library tests
## Rebasing between branches (i.e. from master to staging) ## Rebasing between branches (i.e. from master to staging)
From time to time, changes between branches must be rebased, for example, if the From time to time, changes between branches must be rebased, for example, if the
@ -68,7 +77,10 @@ number of new rebuilds they would cause is too large for the target branch. When
rebasing, care must be taken to include only the intended changes, otherwise rebasing, care must be taken to include only the intended changes, otherwise
many CODEOWNERS will be inadvertently requested for review. To achieve this, many CODEOWNERS will be inadvertently requested for review. To achieve this,
rebasing should not be performed directly on the target branch, but on the merge rebasing should not be performed directly on the target branch, but on the merge
base between the current and target branch. base between the current and target branch. As an additional precautionary measure,
you should temporarily mark the PR as draft for the duration of the operation.
This reduces the probability of mass-pinging people. (OfBorg might still
request a couple of persons for reviews though.)
In the following example, we assume that the current branch, called `feature`, In the following example, we assume that the current branch, called `feature`,
is based on `master`, and we rebase it onto the merge base between is based on `master`, and we rebase it onto the merge base between
@ -102,21 +114,51 @@ git status
git push origin feature --force-with-lease git push origin feature --force-with-lease
``` ```
### Something went wrong and a lot of people were pinged
It happens. Remember to be kind, especially to new contributors.
There is no way back, so the pull request should be closed and locked
(if possible). The changes should be re-submitted in a new PR, in which the people
originally involved in the conversation need to manually be pinged again.
No further discussion should happen on the original PR, as a lot of people
are now subscribed to it.
The following message (or a version thereof) might be left when closing to
describe the situation, since closing and locking without any explanation
is kind of rude:
```markdown
It looks like you accidentally mass-pinged a bunch of people, which are now subscribed
and getting notifications for everything in this pull request. Unfortunately, they
cannot be automatically unsubscribed from the issue (removing review request does not
unsubscribe), therefore development cannot continue in this pull request anymore.
Please open a new pull request with your changes, link back to this one and ping the
people actually involved in here over there.
In order to avoid this in the future, there are instructions for how to properly
rebase between branches in our [contribution guidelines](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#rebasing-between-branches-ie-from-master-to-staging).
Setting your pull request to draft prior to rebasing is strongly recommended.
In draft status, you can preview the list of people that are about to be requested
for review, which allows you to sidestep this issue.
This is not a bulletproof method though, as OfBorg still does review requests even on draft PRs.
```
## Backporting changes ## Backporting changes
Follow these steps to backport a change into a release branch in compliance with the [commit policy](https://nixos.org/nixpkgs/manual/#submitting-changes-stable-release-branches). 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.11` to a PR, so that merging it will You can add a label such as `backport release-23.05` to a PR, so that merging it will
automatically create a backport (via [a GitHub Action](.github/workflows/backport.yml)). automatically create a backport (via [a GitHub Action](.github/workflows/backport.yml)).
This also works for PR's that have already been merged, and might take a couple of minutes to trigger. This also works for pull requests that have already been merged, and might take a couple of minutes to trigger.
You can also create the backport manually: You can also create the backport manually:
1. Take note of the commits in which the change was introduced into `master` branch. 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.11`. Do not use a _channel branch_ like `nixos-22.11` or `nixpkgs-22.11-darwin`. 2. Check out the target _release branch_, e.g. `release-23.05`. Do not use a _channel branch_ like `nixos-23.05` or `nixpkgs-23.05-darwin`.
3. Create a branch for your change, e.g. `git checkout -b backport`. 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. 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.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]`. 5. Push to GitHub and open a backport pull request. Make sure to select the release branch (e.g. `release-23.05`) as the target branch of the pull request, and link to the pull request in which the original change was committed to `master`. The pull request title should be the commit title with the release version as prefix, e.g. `[23.05]`.
6. When the backport pull request is merged and you have the necessary privileges you can also replace the label `9.needs: port to stable` with `8.has: port to stable` on the original pull request. This way maintainers can keep track of missing backports easier. 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 ## Criteria for Backporting changes
@ -128,19 +170,6 @@ Anything that does not cause user or downstream dependency regressions can be ba
- Services which require a client to be up-to-date regardless. (E.g. `spotify`, `steam`, or `discord`) - Services which require a client to be up-to-date regardless. (E.g. `spotify`, `steam`, or `discord`)
- Security critical applications (E.g. `firefox`) - Security critical applications (E.g. `firefox`)
## Generating 23.05 Release Notes
<!--
note: title unchanged even though we don't need regeneration because extant
PRs will link here. definitely change the title for 23.11 though.
-->
Documentation in nixpkgs is transitioning to a markdown-centric workflow. In the past release notes required a translation step to convert from markdown to a compatible docbook document, but this is no longer necessary.
Steps for updating 23.05 Release notes:
1. Edit `nixos/doc/manual/release-notes/rl-2305.section.md` with the desired changes
2. Commit changes to `rl-2305.section.md`.
## Reviewing contributions ## Reviewing contributions
See the nixpkgs manual for more details on how to [Review contributions](https://nixos.org/nixpkgs/manual/#chap-reviewing-contributions). See the nixpkgs manual for more details on how to [Review contributions](https://nixos.org/nixpkgs/manual/#chap-reviewing-contributions).

View file

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

View file

@ -1,11 +0,0 @@
*.chapter.xml
*.section.xml
.version
functions/library/generated
functions/library/locations.xml
highlightjs
manual-full.xml
out
result
result-*
media

View file

@ -1,119 +0,0 @@
MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$' -not -name README.md)))
PANDOC ?= pandoc
pandoc_media_dir = media
# NOTE: Keep in sync with conversion script (/maintainers/scripts/db-to-md.sh).
# TODO: Remove raw-attribute when we can get rid of DocBook altogether.
pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
# Not needed:
# - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)
pandoc_flags = --extract-media=$(pandoc_media_dir) \
--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \
--lua-filter=$(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
.PHONY: all
all: validate format out/html/index.html out/epub/manual.epub
.PHONY: render-md
render-md: ${MD_TARGETS}
.PHONY: debug
debug:
nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"
.PHONY: format
format: doc-support/result
find . -iname '*.xml' -type f | while read f; do \
echo $$f ;\
xmlformat --config-file "doc-support/result/xmlformat.conf" -i $$f ;\
done
.PHONY: fix-misc-xml
fix-misc-xml:
find . -iname '*.xml' -type f \
-exec ../nixos/doc/varlistentry-fixer.rb {} ';'
.PHONY: clean
clean:
rm -f ${MD_TARGETS} doc-support/result .version manual-full.xml functions/library/locations.xml functions/library/generated
rm -rf ./out/ ./highlightjs ./media
.PHONY: validate
validate: manual-full.xml doc-support/result
jing doc-support/result/docbook.rng manual-full.xml
out/html/index.html: doc-support/result manual-full.xml style.css highlightjs
mkdir -p out/html
xsltproc \
--nonet --xinclude \
--output $@ \
doc-support/result/xhtml.xsl \
./manual-full.xml
mkdir -p out/html/highlightjs/
cp -r highlightjs out/html/
cp -r $(pandoc_media_dir) out/html/
cp ./overrides.css out/html/
cp ./style.css out/html/style.css
mkdir -p out/html/images/callouts
cp doc-support/result/xsl/docbook/images/callouts/*.svg out/html/images/callouts/
chmod u+w -R out/html/
out/epub/manual.epub: manual-full.xml
mkdir -p out/epub/scratch
xsltproc --nonet \
--output out/epub/scratch/ \
doc-support/result/epub.xsl \
./manual-full.xml
cp -r $(pandoc_media_dir) out/epub/scratch/OEBPS
cp ./overrides.css out/epub/scratch/OEBPS
cp ./style.css out/epub/scratch/OEBPS
mkdir -p out/epub/scratch/OEBPS/images/callouts/
cp doc-support/result/xsl/docbook/images/callouts/*.svg out/epub/scratch/OEBPS/images/callouts/
echo "application/epub+zip" > mimetype
zip -0Xq "out/epub/manual.epub" mimetype
rm mimetype
cd "out/epub/scratch/" && zip -Xr9D "../manual.epub" *
rm -rf "out/epub/scratch/"
highlightjs: doc-support/result
mkdir -p highlightjs
cp -r doc-support/result/highlightjs/highlight.pack.js highlightjs/
cp -r doc-support/result/highlightjs/LICENSE highlightjs/
cp -r doc-support/result/highlightjs/mono-blue.css highlightjs/
cp -r doc-support/result/highlightjs/loader.js highlightjs/
manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml functions/library/generated *.xml **/*.xml **/**/*.xml
xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
.version: doc-support/result
ln -rfs ./doc-support/result/version .version
doc-support/result: doc-support/default.nix
(cd doc-support; nix-build)
functions/library/locations.xml: doc-support/result
ln -rfs ./doc-support/result/function-locations.xml functions/library/locations.xml
functions/library/generated: doc-support/result
ln -rfs ./doc-support/result/function-docs functions/library/generated
%.section.xml: %.section.md
$(PANDOC) $^ -t docbook \
$(pandoc_flags) \
-o $@
%.chapter.xml: %.chapter.md
$(PANDOC) $^ -t docbook \
--top-level-division=chapter \
$(pandoc_flags) \
-o $@

View file

@ -1,23 +0,0 @@
--[[
Converts Code AST nodes produced by pandocs DocBook reader
from citerefentry elements into AST for corresponding role
for reStructuredText.
We use subset of MyST syntax (CommonMark with features from rST)
so lets use the rST AST for rST features.
Reference: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage
]]
function Code(elem)
elem.classes = elem.classes:map(function (x)
if x == 'citerefentry' then
elem.attributes['role'] = 'manpage'
return 'interpreted-text'
else
return x
end
end)
return elem
end

View file

@ -1,34 +0,0 @@
--[[
Converts Link AST nodes with empty label to DocBook xref elements.
This is a temporary script to be able use cross-references conveniently
using syntax taken from MyST, while we still use docbook-xsl
for generating the documentation.
Reference: https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing
]]
local function starts_with(start, str)
return str:sub(1, #start) == start
end
local function escape_xml_arg(arg)
amps = arg:gsub('&', '&amp;')
amps_quotes = amps:gsub('"', '&quot;')
amps_quotes_lt = amps_quotes:gsub('<', '&lt;')
return amps_quotes_lt
end
function Link(elem)
has_no_content = #elem.content == 0
targets_anchor = starts_with('#', elem.target)
has_no_attributes = elem.title == '' and elem.identifier == '' and #elem.classes == 0 and #elem.attributes == 0
if has_no_content and targets_anchor and has_no_attributes then
-- xref expects idref without the pound-sign
target_without_hash = elem.target:sub(2, #elem.target)
return pandoc.RawInline('docbook', '<xref linkend="' .. escape_xml_arg(target_without_hash) .. '" />')
end
end

View file

@ -1,44 +0,0 @@
--[[
Converts AST for reStructuredText roles into corresponding
DocBook elements.
Currently, only a subset of roles is supported.
Reference:
List of roles:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
manpage:
https://tdg.docbook.org/tdg/5.1/citerefentry.html
file:
https://tdg.docbook.org/tdg/5.1/filename.html
]]
function Code(elem)
if elem.classes:includes('interpreted-text') then
local tag = nil
local content = elem.text
if elem.attributes['role'] == 'manpage' then
tag = 'citerefentry'
local title, volnum = content:match('^(.+)%((%w+)%)$')
if title == nil then
-- No volnum in parentheses.
title = content
end
content = '<refentrytitle>' .. title .. '</refentrytitle>' .. (volnum ~= nil and ('<manvolnum>' .. volnum .. '</manvolnum>') or '')
elseif elem.attributes['role'] == 'file' then
tag = 'filename'
elseif elem.attributes['role'] == 'command' then
tag = 'command'
elseif elem.attributes['role'] == 'option' then
tag = 'option'
elseif elem.attributes['role'] == 'var' then
tag = 'varname'
elseif elem.attributes['role'] == 'env' then
tag = 'envar'
end
if tag ~= nil then
return pandoc.RawInline('docbook', '<' .. tag .. '>' .. content .. '</' .. tag .. '>')
end
end
end

View file

@ -1,28 +0,0 @@
{ pkgs ? import ../../.. {} }:
let
inherit (pkgs) lib;
manpageURLs = lib.importJSON (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
''

View file

@ -1,36 +0,0 @@
--[[
Replaces Str AST nodes containing {role}, followed by a Code node
by a Code node with attrs that would be produced by rST reader
from the role syntax.
This is to emulate MyST syntax in Pandoc.
(MyST is a CommonMark flavour with rST features mixed in.)
Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point
]]
function Inlines(inlines)
for i = #inlines-1,1,-1 do
local first = inlines[i]
local second = inlines[i+1]
local correct_tags = first.tag == 'Str' and second.tag == 'Code'
if correct_tags then
-- docutils supports alphanumeric strings separated by [-._:]
-- We are slightly more liberal for simplicity.
-- 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
end
end
return inlines
end

View file

@ -1,25 +0,0 @@
--[[
Replaces Code nodes with attrs that would be produced by rST reader
from the role syntax by a Str AST node containing {role}, followed by a Code node.
This is to emulate MyST syntax in Pandoc.
(MyST is a CommonMark flavour with rST features mixed in.)
Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point
]]
function Code(elem)
local role = elem.attributes['role']
if elem.classes:includes('interpreted-text') and role ~= nil then
elem.classes = elem.classes:filter(function (c)
return c ~= 'interpreted-text'
end)
elem.attributes['role'] = nil
return {
pandoc.Str('{' .. role .. '}'),
elem,
}
end
end

12
third_party/nixpkgs/doc/builders.md vendored Normal file
View file

@ -0,0 +1,12 @@
# Builders {#part-builders}
```{=include=} chapters
builders/fetchers.chapter.md
builders/trivial-builders.chapter.md
builders/testers.chapter.md
builders/special.md
builders/images.md
hooks/index.md
languages-frameworks/index.md
builders/packages/index.md
```

View file

@ -132,11 +132,16 @@ A number of fetcher functions wrap part of `fetchurl` and `fetchzip`. They are m
`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` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `hash` is currently preferred.
To use a different GitHub instance, use `githubBase` (defaults to `"github.com"`).
`fetchFromGitHub` uses `fetchzip` to download the source archive generated by GitHub for the specified revision. If `leaveDotGit`, `deepClone` or `fetchSubmodules` are set to `true`, `fetchFromGitHub` will use `fetchgit` instead. Refer to its section for documentation of these options. `fetchFromGitHub` uses `fetchzip` to download the source archive generated by GitHub for the specified revision. If `leaveDotGit`, `deepClone` or `fetchSubmodules` are set to `true`, `fetchFromGitHub` will use `fetchgit` instead. Refer to its section for documentation of these options.
## `fetchFromGitLab` {#fetchfromgitlab} ## `fetchFromGitLab` {#fetchfromgitlab}
This is used with GitLab repositories. The arguments expected are very similar to `fetchFromGitHub` above. This is used with GitLab repositories. It behaves similarly to `fetchFromGitHub`, and expects `owner`, `repo`, `rev`, and `hash`.
To use a specific GitLab instance, use `domain` (defaults to `"gitlab.com"`).
## `fetchFromGitiles` {#fetchfromgitiles} ## `fetchFromGitiles` {#fetchfromgitiles}
@ -144,7 +149,7 @@ This is used with Gitiles repositories. The arguments expected are similar to `f
## `fetchFromBitbucket` {#fetchfrombitbucket} ## `fetchFromBitbucket` {#fetchfrombitbucket}
This is used with BitBucket repositories. The arguments expected are very similar to fetchFromGitHub above. This is used with BitBucket repositories. The arguments expected are very similar to `fetchFromGitHub` above.
## `fetchFromSavannah` {#fetchfromsavannah} ## `fetchFromSavannah` {#fetchfromsavannah}

View file

@ -0,0 +1,13 @@
# Images {#chap-images}
This chapter describes tools for creating various types of images.
```{=include=} sections
images/appimagetools.section.md
images/dockertools.section.md
images/ocitools.section.md
images/snaptools.section.md
images/portableservice.section.md
images/makediskimage.section.md
images/binarycache.section.md
```

View file

@ -1,15 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="chap-images">
<title>Images</title>
<para>
This chapter describes tools for creating various types of images.
</para>
<xi:include href="images/appimagetools.section.xml" />
<xi:include href="images/dockertools.section.xml" />
<xi:include href="images/ocitools.section.xml" />
<xi:include href="images/snaptools.section.xml" />
<xi:include href="images/portableservice.section.xml" />
<xi:include href="images/makediskimage.section.xml" />
<xi:include href="images/binarycache.section.xml" />
</chapter>

View file

@ -1,6 +1,6 @@
# DLib {#dlib} # DLib {#dlib}
[DLib](http://dlib.net/) is a modern, C++-based toolkit which provides several machine learning algorithms. [DLib](http://dlib.net/) is a modern, C++\-based toolkit which provides several machine learning algorithms.
## Compiling without AVX support {#compiling-without-avx-support} ## Compiling without AVX support {#compiling-without-avx-support}

View file

@ -0,0 +1,27 @@
# Packages {#chap-packages}
This chapter contains information about how to use and maintain the Nix expressions for a number of specific packages, such as the Linux kernel or X.org.
```{=include=} sections
citrix.section.md
dlib.section.md
eclipse.section.md
elm.section.md
emacs.section.md
firefox.section.md
fish.section.md
fuse.section.md
ibus.section.md
kakoune.section.md
linux.section.md
locales.section.md
etc-files.section.md
nginx.section.md
opengl.section.md
shell-helpers.section.md
steam.section.md
cataclysm-dda.section.md
urxvt.section.md
weechat.section.md
xorg.section.md
```

View file

@ -1,29 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="chap-packages">
<title>Packages</title>
<para>
This chapter contains information about how to use and maintain the Nix expressions for a number of specific packages, such as the Linux kernel or X.org.
</para>
<xi:include href="citrix.section.xml" />
<xi:include href="dlib.section.xml" />
<xi:include href="eclipse.section.xml" />
<xi:include href="elm.section.xml" />
<xi:include href="emacs.section.xml" />
<xi:include href="firefox.section.xml" />
<xi:include href="fish.section.xml" />
<xi:include href="fuse.section.xml" />
<xi:include href="ibus.section.xml" />
<xi:include href="kakoune.section.xml" />
<xi:include href="linux.section.xml" />
<xi:include href="locales.section.xml" />
<xi:include href="etc-files.section.xml" />
<xi:include href="nginx.section.xml" />
<xi:include href="opengl.section.xml" />
<xi:include href="shell-helpers.section.xml" />
<xi:include href="steam.section.xml" />
<xi:include href="cataclysm-dda.section.xml" />
<xi:include href="urxvt.section.xml" />
<xi:include href="weechat.section.xml" />
<xi:include href="xorg.section.xml" />
</chapter>

View file

@ -0,0 +1,11 @@
# Special builders {#chap-special}
This chapter describes several special builders.
```{=include=} sections
special/fhs-environments.section.md
special/makesetuphook.section.md
special/mkshell.section.md
special/darwin-builder.section.md
special/vm-tools.section.md
```

View file

@ -1,13 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="chap-special">
<title>Special builders</title>
<para>
This chapter describes several special builders.
</para>
<xi:include href="special/fhs-environments.section.xml" />
<xi:include href="special/makesetuphook.section.xml" />
<xi:include href="special/mkshell.section.xml" />
<xi:include href="special/darwin-builder.section.xml" />
<xi:include href="special/vm-tools.section.xml" />
</chapter>

View file

@ -1,11 +1,12 @@
# darwin.builder {#sec-darwin-builder} # darwin.linux-builder {#sec-darwin-builder}
`darwin.builder` provides a way to bootstrap a Linux builder on a macOS machine. `darwin.linux-builder` provides a way to bootstrap a Linux builder on a macOS machine.
This requires macOS version 12.4 or later. This requires macOS version 12.4 or later.
This also requires that port 22 on your machine is free (since Nix does not The builder runs on host port 31022 by default.
permit specifying a non-default SSH port for builders). You can change it by overriding `virtualisation.darwin-builder.hostPort`.
See the [example](#sec-darwin-builder-example-flake).
You will also need to be a trusted user for your Nix installation. In other 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: words, your `/etc/nix/nix.conf` should have something like:
@ -17,7 +18,7 @@ extra-trusted-users = <your username goes here>
To launch the builder, run the following flake: To launch the builder, run the following flake:
```ShellSession ```ShellSession
$ nix run nixpkgs#darwin.builder $ nix run nixpkgs#darwin.linux-builder
``` ```
That will prompt you to enter your `sudo` password: That will prompt you to enter your `sudo` password:
@ -50,19 +51,28 @@ To delegate builds to the remote builder, add the following options to your
``` ```
# - Replace ${ARCH} with either aarch64 or x86_64 to match your host machine # - 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) # - 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= builders = ssh-ng://builder@linux-builder ${ARCH}-linux /etc/nix/builder_ed25519 ${MAX_JOBS} - - - c3NoLWVkMjU1MTkgQUFBQUMzTnphQzFsWkRJMU5URTVBQUFBSUpCV2N4Yi9CbGFxdDFhdU90RStGOFFVV3JVb3RpQzVxQkorVXVFV2RWQ2Igcm9vdEBuaXhvcwo=
# Not strictly necessary, but this will reduce your disk utilization # Not strictly necessary, but this will reduce your disk utilization
builders-use-substitutes = true builders-use-substitutes = true
``` ```
To allow Nix to connect to a builder not running on port 22, you will also need to create a new file at `/etc/ssh/ssh_config.d/100-linux-builder.conf`:
```
Host linux-builder
Hostname localhost
HostKeyAlias linux-builder
Port 31022
```
… and then restart your Nix daemon to apply the change: … and then restart your Nix daemon to apply the change:
```ShellSession ```ShellSession
$ sudo launchctl kickstart -k system/org.nixos.nix-daemon $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
``` ```
## Example flake usage ## Example flake usage {#sec-darwin-builder-example-flake}
``` ```
{ {
@ -120,7 +130,7 @@ $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
} }
``` ```
## Reconfiguring the builder ## Reconfiguring the builder {#sec-darwin-builder-reconfiguring}
Initially you should not change the builder configuration else you will not be Initially you should not change the builder configuration else you will not be
able to use the binary cache. However, after you have the builder running locally able to use the binary cache. However, after you have the builder running locally

View file

@ -11,6 +11,8 @@ Accepted arguments are:
Packages to be installed for the main host's architecture (i.e. x86_64 on x86_64 installations). Along with libraries binaries are also installed. Packages to be installed for the main host's architecture (i.e. x86_64 on x86_64 installations). Along with libraries binaries are also installed.
- `multiPkgs` - `multiPkgs`
Packages to be installed for all architectures supported by a host (i.e. i686 and x86_64 on x86_64 installations). Only libraries are installed by default. Packages to be installed for all architectures supported by a host (i.e. i686 and x86_64 on x86_64 installations). Only libraries are installed by default.
- `multiArch`
Whether to install 32bit multiPkgs into the FHSEnv in 64bit environments
- `extraBuildCommands` - `extraBuildCommands`
Additional commands to be executed for finalizing the directory structure. Additional commands to be executed for finalizing the directory structure.
- `extraBuildCommandsMulti` - `extraBuildCommandsMulti`

View file

@ -12,7 +12,7 @@ pkgs.makeSetupHook {
} ./script.sh } ./script.sh
``` ```
#### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash {#sec-pkgs.makeSetupHook-usage-example} ### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash {#sec-pkgs.makeSetupHook-usage-example}
```nix ```nix
pkgs.makeSetupHook { pkgs.makeSetupHook {

View file

@ -6,7 +6,7 @@ A set of VM related utilities, that help in building some packages in more advan
A bash script fragment that produces a disk image at `destination`. A bash script fragment that produces a disk image at `destination`.
### Attributes ### Attributes {#vm-tools-createEmptyImage-attributes}
* `size`. The disk size, in MiB. * `size`. The disk size, in MiB.
* `fullName`. Name that will be written to `${destination}/nix-support/full-name`. * `fullName`. Name that will be written to `${destination}/nix-support/full-name`.
@ -20,14 +20,14 @@ Thus, any pure Nix derivation should run unmodified.
If the build fails and Nix is run with the `-K/--keep-failed` option, a script `run-vm` will be left behind in the temporary build directory that allows you to boot into the VM and debug it interactively. If the build fails and Nix is run with the `-K/--keep-failed` option, a script `run-vm` will be left behind in the temporary build directory that allows you to boot into the VM and debug it interactively.
### Attributes ### Attributes {#vm-tools-runInLinuxVM-attributes}
* `preVM` (optional). Shell command to be evaluated *before* the VM is started (i.e., on the host). * `preVM` (optional). Shell command to be evaluated *before* the VM is started (i.e., on the host).
* `memSize` (optional, default `512`). The memory size of the VM in MiB. * `memSize` (optional, default `512`). The memory size of the VM in MiB.
* `diskImage` (optional). A file system image to be attached to `/dev/sda`. * `diskImage` (optional). A file system image to be attached to `/dev/sda`.
Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc. Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
### Examples ### Examples {#vm-tools-runInLinuxVM-examples}
Build the derivation hello inside a VM: Build the derivation hello inside a VM:
```nix ```nix
@ -56,13 +56,13 @@ runInLinuxVM (hello.overrideAttrs (_: {
Takes a file, such as an ISO, and extracts its contents into the store. Takes a file, such as an ISO, and extracts its contents into the store.
### Attributes ### Attributes {#vm-tools-extractFs-attributes}
* `file`. Path to the file to be extracted. * `file`. Path to the file to be extracted.
Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc. Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
* `fs` (optional). Filesystem of the contents of the file. * `fs` (optional). Filesystem of the contents of the file.
### Examples ### Examples {#vm-tools-extractFs-examples}
Extract the contents of an ISO file: Extract the contents of an ISO file:
```nix ```nix
@ -82,7 +82,7 @@ Like [](#vm-tools-runInLinuxVM), but instead of using `stdenv` from the Nix stor
Generate a script that can be used to run an interactive session in the given image. Generate a script that can be used to run an interactive session in the given image.
### Examples ### Examples {#vm-tools-makeImageTestScript-examples}
Create a script for running a Fedora 27 VM: Create a script for running a Fedora 27 VM:
```nix ```nix
@ -100,7 +100,7 @@ makeImageTestScript diskImages.ubuntu2004x86_64
A set of functions that build a predefined set of minimal Linux distributions images. A set of functions that build a predefined set of minimal Linux distributions images.
### Images ### Images {#vm-tools-diskImageFuns-images}
* Fedora * Fedora
* `fedora26x86_64` * `fedora26x86_64`
@ -126,12 +126,12 @@ A set of functions that build a predefined set of minimal Linux distributions im
* `debian11i386` * `debian11i386`
* `debian11x86_64` * `debian11x86_64`
### Attributes ### Attributes {#vm-tools-diskImageFuns-attributes}
* `size` (optional, defaults to `4096`). The size of the image, in MiB. * `size` (optional, defaults to `4096`). The size of the image, in MiB.
* `extraPackages` (optional). A list names of additional packages from the distribution that should be included in the image. * `extraPackages` (optional). A list names of additional packages from the distribution that should be included in the image.
### Examples ### Examples {#vm-tools-diskImageFuns-examples}
8GiB image containing Firefox in addition to the default packages: 8GiB image containing Firefox in addition to the default packages:
```nix ```nix

View file

@ -1,5 +1,5 @@
# Testers {#chap-testers} # Testers {#chap-testers}
This chapter describes several testing builders which are available in the <literal>testers</literal> namespace. This chapter describes several testing builders which are available in the `testers` namespace.
## `hasPkgConfigModule` {#tester-hasPkgConfigModule} ## `hasPkgConfigModule` {#tester-hasPkgConfigModule}

10
third_party/nixpkgs/doc/contributing.md vendored Normal file
View file

@ -0,0 +1,10 @@
# Contributing to Nixpkgs {#part-contributing}
```{=include=} chapters
contributing/quick-start.chapter.md
contributing/coding-conventions.chapter.md
contributing/submitting-changes.chapter.md
contributing/vulnerability-roundup.chapter.md
contributing/reviewing-contributions.chapter.md
contributing/contributing-to-documentation.chapter.md
```

View file

@ -220,7 +220,9 @@ There are a few naming guidelines:
- The `version` attribute _must_ start with a digit e.g`"0.3.1rc2". - The `version` attribute _must_ start with a digit e.g`"0.3.1rc2".
- If a package is not a release but a commit from a repository, then the `version` attribute _must_ be the date of that (fetched) commit. The date _must_ be in `"unstable-YYYY-MM-DD"` format. - If a package is a commit from a repository without a version assigned, then the `version` attribute _should_ be the latest upstream version preceding that commit, followed by `-unstable-` and the date of the (fetched) commit. The date _must_ be in `"YYYY-MM-DD"` format.
Example: Given a project had its latest releases `2.2` in November 2021, and `3.0` in January 2022, a commit authored on March 15, 2022 for an upcoming bugfix release `2.2.1` would have `version = "2.2-unstable-2022-03-15"`.
- Dashes in the package `pname` _should_ be preserved in new variable names, rather than converted to underscores or camel cased — e.g., `http-parser` instead of `http_parser` or `httpParser`. The hyphenated style is preferred in all three package names. - Dashes in the package `pname` _should_ be preserved in new variable names, rather than converted to underscores or camel cased — e.g., `http-parser` instead of `http_parser` or `httpParser`. The hyphenated style is preferred in all three package names.

View file

@ -12,7 +12,7 @@ When reviewing a pull request, please always be nice and polite. Controversial c
GitHub provides reactions as a simple and quick way to provide feedback to pull requests or any comments. The thumb-down reaction should be used with care and if possible accompanied with some explanation so the submitter has directions to improve their contribution. GitHub provides reactions as a simple and quick way to provide feedback to pull requests or any comments. The thumb-down reaction should be used with care and if possible accompanied with some explanation so the submitter has directions to improve their contribution.
pull request reviews should include a list of what has been reviewed in a comment, so other reviewers and mergers can know the state of the review. Pull request reviews should include a list of what has been reviewed in a comment, so other reviewers and mergers can know the state of the review.
All the review template samples provided in this section are generic and meant as examples. Their usage is optional and the reviewer is free to adapt them to their liking. All the review template samples provided in this section are generic and meant as examples. Their usage is optional and the reviewer is free to adapt them to their liking.
@ -62,6 +62,8 @@ Sample template for a package update review is provided below.
- [ ] package build on ARCHITECTURE - [ ] package build on ARCHITECTURE
- [ ] executables tested on ARCHITECTURE - [ ] executables tested on ARCHITECTURE
- [ ] all depending packages build - [ ] all depending packages build
- [ ] patches have a comment describing either the upstream URL or a reason why the patch wasn't upstreamed
- [ ] patches that are remotely available are fetched rather than vendored
##### Possible improvements ##### Possible improvements
@ -105,7 +107,8 @@ Sample template for a new package review is provided below.
- [ ] source is fetched using the appropriate function - [ ] source is fetched using the appropriate function
- [ ] the list of `phases` is not overridden - [ ] the list of `phases` is not overridden
- [ ] when a phase (like `installPhase`) is overridden it starts with `runHook preInstall` and ends with `runHook postInstall`. - [ ] when a phase (like `installPhase`) is overridden it starts with `runHook preInstall` and ends with `runHook postInstall`.
- [ ] patches that are remotely available are fetched with `fetchpatch` - [ ] patches have a comment describing either the upstream URL or a reason why the patch wasn't upstreamed
- [ ] patches that are remotely available are fetched rather than vendored
##### Possible improvements ##### Possible improvements
@ -201,7 +204,7 @@ checks should be performed:
them to either recommit using that key or to remove their key them to either recommit using that key or to remove their key
information. information.
Given a maintainter entry like this: Given a maintainer entry like this:
``` nix ``` nix
{ {

View file

@ -0,0 +1,16 @@
digraph {
"small changes" [shape=none]
"mass-rebuilds and other large changes" [shape=none]
"critical security fixes" [shape=none]
"broken staging-next fixes" [shape=none]
"small changes" -> master
"mass-rebuilds and other large changes" -> staging
"critical security fixes" -> master
"broken staging-next fixes" -> "staging-next"
"staging-next" -> master [color="#E85EB0"] [label="stabilization ends"] [fontcolor="#E85EB0"]
"staging" -> "staging-next" [color="#E85EB0"] [label="stabilization starts"] [fontcolor="#E85EB0"]
master -> "staging-next" -> staging [color="#5F5EE8"] [label="every six hours (GitHub Action)"] [fontcolor="#5F5EE8"]
}

View file

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

After

Width:  |  Height:  |  Size: 5.6 KiB

View file

@ -214,39 +214,81 @@ The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blo
- Hydra builds for master and staging should not be used as testing platform, its a build farm for changes that have been already tested. - Hydra builds for master and staging should not be used as testing platform, its a build farm for changes that have been already tested.
- When changing the bootloader installation process, extra care must be taken. Grub installations cannot be rolled back, hence changes may break peoples installations forever. For any non-trivial change to the bootloader please file a PR asking for review, especially from \@edolstra. - When changing the bootloader installation process, extra care must be taken. Grub installations cannot be rolled back, hence changes may break peoples installations forever. For any non-trivial change to the bootloader please file a PR asking for review, especially from \@edolstra.
### Branches {#submitting-changes-branches}
The `nixpkgs` repository has three major branches:
- `master`
- `staging`
- `staging-next`
The most important distinction between them is that `staging`
(colored red in the diagram below) can receive commits which cause
a mass-rebuild (for example, anything that changes the `drvPath` of
`stdenv`). The other two branches `staging-next` and `master`
(colored green in the diagram below) can *not* receive commits which
cause a mass-rebuild.
Arcs between the branches show possible merges into these branches,
either from other branches or from independently submitted PRs. The
colors of these edges likewise show whether or not they could
trigger a mass rebuild (red) or must not trigger a mass rebuild
(green).
Hydra runs automatic builds for the green branches.
Notice that the automatic merges are all green arrows. This is by
design. Any merge which might cause a mass rebuild on a branch
which has automatic builds (`staging-next`, `master`) will be a
manual merge to make sure it is good use of compute power.
Nixpkgs has two branches so that there is one branch (`staging`)
which accepts mass-rebuilding commits, and one fast-rebuilding
branch which accepts independent PRs (`master`). The `staging-next`
branch allows the Hydra operators to batch groups of commits to
`staging` to be built. By keeping the `staging-next` branch
separate from `staging`, this batching does not block
developers from merging changes into `staging`.
```{.graphviz caption="Staging workflow"} ```{.graphviz caption="Staging workflow"}
digraph { digraph {
"small changes" [shape=none] master [color="green" fontcolor=green]
"mass-rebuilds and other large changes" [shape=none] "staging-next" [color="green" fontcolor=green]
"critical security fixes" [shape=none] staging [color="red" fontcolor=red]
"broken staging-next fixes" [shape=none]
"small changes" -> master "small changes" [fontcolor=green shape=none]
"mass-rebuilds and other large changes" -> staging "small changes" -> master [color=green]
"critical security fixes" -> master
"broken staging-next fixes" -> "staging-next"
"staging-next" -> master [color="#E85EB0"] [label="stabilization ends"] [fontcolor="#E85EB0"] "mass-rebuilds and other large changes" [fontcolor=red shape=none]
"staging" -> "staging-next" [color="#E85EB0"] [label="stabilization starts"] [fontcolor="#E85EB0"] "mass-rebuilds and other large changes" -> staging [color=red]
master -> "staging-next" -> staging [color="#5F5EE8"] [label="every six hours (GitHub Action)"] [fontcolor="#5F5EE8"] "critical security fixes" [fontcolor=green shape=none]
"critical security fixes" -> master [color=green]
"staging fixes which do not cause staging to mass-rebuild" [fontcolor=green shape=none]
"staging fixes which do not cause staging to mass-rebuild" -> "staging-next" [color=green]
"staging-next" -> master [color="red"] [label="manual merge"] [fontcolor="red"]
"staging" -> "staging-next" [color="red"] [label="manual merge"] [fontcolor="red"]
master -> "staging-next" [color="green"] [label="automatic merge (GitHub Action)"] [fontcolor="green"]
"staging-next" -> staging [color="green"] [label="automatic merge (GitHub Action)"] [fontcolor="green"]
} }
``` ```
[This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/periodic-merge-6h.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours; these are the blue arrows in the diagram above. The purple arrows in the diagram above are done manually and much less frequently. You can get an idea of how often these merges occur by looking at the git history. [This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/periodic-merge-6h.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours; these are the green arrows in the diagram above. The red arrows in the diagram above are done manually and much less frequently. You can get an idea of how often these merges occur by looking at the git history.
### Master branch {#submitting-changes-master-branch} #### Master branch {#submitting-changes-master-branch}
The `master` branch is the main development branch. It should only see non-breaking commits that do not cause mass rebuilds. The `master` branch is the main development branch. It should only see non-breaking commits that do not cause mass rebuilds.
### Staging branch {#submitting-changes-staging-branch} #### Staging branch {#submitting-changes-staging-branch}
The `staging` branch is a development branch where mass-rebuilds go. Mass rebuilds are commits that cause rebuilds for many packages, like more than 500 (or perhaps, if it's 'light' packages, 1000). It should only see non-breaking mass-rebuild commits. That means it is not to be used for testing, and changes must have been well tested already. If the branch is already in a broken state, please refrain from adding extra new breakages. The `staging` branch is a development branch where mass-rebuilds go. Mass rebuilds are commits that cause rebuilds for many packages, like more than 500 (or perhaps, if it's 'light' packages, 1000). It should only see non-breaking mass-rebuild commits. That means it is not to be used for testing, and changes must have been well tested already. If the branch is already in a broken state, please refrain from adding extra new breakages.
During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes. During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes.
### Staging-next branch {#submitting-changes-staging-next-branch} #### Staging-next branch {#submitting-changes-staging-next-branch}
The `staging-next` branch is for stabilizing mass-rebuilds submitted to the `staging` branch prior to merging them into `master`. Mass-rebuilds must go via the `staging` branch. It must only see non-breaking commits that are fixing issues blocking it from being merged into the `master` branch. The `staging-next` branch is for stabilizing mass-rebuilds submitted to the `staging` branch prior to merging them into `master`. Mass-rebuilds must go via the `staging` branch. It must only see non-breaking commits that are fixing issues blocking it from being merged into the `master` branch.
@ -254,7 +296,7 @@ If the branch is already in a broken state, please refrain from adding extra new
During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes. During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes.
### Stable release branches {#submitting-changes-stable-release-branches} #### Stable release branches {#submitting-changes-stable-release-branches}
The same staging workflow applies to stable release branches, but the main branch is called `release-*` instead of `master`. The same staging workflow applies to stable release branches, but the main branch is called `release-*` instead of `master`.

View file

@ -1,43 +1,146 @@
{ pkgs ? (import ./.. { }), nixpkgs ? { }}: { pkgs ? (import ./.. { }), nixpkgs ? { }}:
let let
doc-support = import ./doc-support { inherit pkgs nixpkgs; }; inherit (pkgs) lib;
inherit (lib) hasPrefix removePrefix;
lib-docs = import ./doc-support/lib-function-docs.nix {
inherit pkgs nixpkgs;
libsets = [
{ name = "asserts"; description = "assertion functions"; }
{ name = "attrsets"; description = "attribute set functions"; }
{ name = "strings"; description = "string manipulation functions"; }
{ name = "versions"; description = "version string functions"; }
{ name = "trivial"; description = "miscellaneous functions"; }
{ name = "fixedPoints"; baseName = "fixed-points"; description = "explicit recursion functions"; }
{ name = "lists"; description = "list manipulation functions"; }
{ name = "debug"; description = "debugging functions"; }
{ name = "options"; description = "NixOS / nixpkgs option handling"; }
{ name = "path"; description = "path functions"; }
{ name = "filesystem"; description = "filesystem functions"; }
{ name = "sources"; description = "source filtering functions"; }
{ name = "cli"; description = "command-line serialization functions"; }
];
};
epub = pkgs.runCommand "manual.epub" {
nativeBuildInputs = with pkgs; [ libxslt zip ];
epub = ''
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="nixpkgs-manual">
<info>
<title>Nixpkgs Manual</title>
<subtitle>Version ${pkgs.lib.version}</subtitle>
</info>
<chapter>
<title>Temporarily unavailable</title>
<para>
The Nixpkgs manual is currently not available in EPUB format,
please use the <link xlink:href="https://nixos.org/nixpkgs/manual">HTML manual</link>
instead.
</para>
<para>
If you've used the EPUB manual in the past and it has been useful to you, please
<link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>.
</para>
</chapter>
</book>
'';
passAsFile = [ "epub" ];
} ''
mkdir scratch
xsltproc \
--param chapter.autolabel 0 \
--nonet \
--output scratch/ \
${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \
$epubPath
echo "application/epub+zip" > mimetype
zip -0Xq "$out" mimetype
cd scratch && zip -Xr9D "$out" *
'';
# NB: This file describes the Nixpkgs manual, which happens to use module
# docs infra originally developed for NixOS.
optionsDoc = pkgs.nixosOptionsDoc {
inherit (pkgs.lib.evalModules {
modules = [ ../pkgs/top-level/config.nix ];
class = "nixpkgsConfig";
}) options;
documentType = "none";
transformOptions = opt:
opt // {
declarations =
map
(decl:
if hasPrefix (toString ../..) (toString decl)
then
let subpath = removePrefix "/" (removePrefix (toString ../.) (toString decl));
in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; }
else decl)
opt.declarations;
};
};
in pkgs.stdenv.mkDerivation { in pkgs.stdenv.mkDerivation {
name = "nixpkgs-manual"; name = "nixpkgs-manual";
nativeBuildInputs = with pkgs; [ nativeBuildInputs = with pkgs; [
pandoc nixos-render-docs
graphviz
libxml2
libxslt
zip
jing
xmlformat
]; ];
src = pkgs.nix-gitignore.gitignoreSource [] ./.; src = ./.;
postPatch = '' postPatch = ''
ln -s ${doc-support} ./doc-support/result ln -s ${optionsDoc.optionsJSON}/share/doc/nixos/options.json ./config-options.json
''; '';
preBuild = '' buildPhase = ''
make -j$NIX_BUILD_CORES render-md cat \
./functions/library.md.in \
${lib-docs}/index.md \
> ./functions/library.md
substitute ./manual.md.in ./manual.md \
--replace '@MANUAL_VERSION@' '${pkgs.lib.version}'
mkdir -p out/media
mkdir -p out/highlightjs
cp -t out/highlightjs \
${pkgs.documentation-highlighter}/highlight.pack.js \
${pkgs.documentation-highlighter}/LICENSE \
${pkgs.documentation-highlighter}/mono-blue.css \
${pkgs.documentation-highlighter}/loader.js
cp -t out ./overrides.css ./style.css
nixos-render-docs manual html \
--manpage-urls ./manpage-urls.json \
--revision ${pkgs.lib.trivial.revisionWithDefault (pkgs.rev or "master")} \
--stylesheet style.css \
--stylesheet overrides.css \
--stylesheet highlightjs/mono-blue.css \
--script ./highlightjs/highlight.pack.js \
--script ./highlightjs/loader.js \
--toc-depth 1 \
--section-toc-depth 1 \
manual.md \
out/index.html
''; '';
installPhase = '' installPhase = ''
dest="$out/share/doc/nixpkgs" dest="$out/share/doc/nixpkgs"
mkdir -p "$(dirname "$dest")" mkdir -p "$(dirname "$dest")"
mv out/html "$dest" mv out "$dest"
mv "$dest/index.html" "$dest/manual.html" mv "$dest/index.html" "$dest/manual.html"
mv out/epub/manual.epub "$dest/nixpkgs-manual.epub" cp ${epub} "$dest/nixpkgs-manual.epub"
mkdir -p $out/nix-support/ mkdir -p $out/nix-support/
echo "doc manual $dest manual.html" >> $out/nix-support/hydra-build-products echo "doc manual $dest manual.html" >> $out/nix-support/hydra-build-products
echo "doc manual $dest nixpkgs-manual.epub" >> $out/nix-support/hydra-build-products echo "doc manual $dest nixpkgs-manual.epub" >> $out/nix-support/hydra-build-products
''; '';
# Environment variables
PANDOC_LUA_FILTERS_DIR = "${pkgs.pandoc-lua-filters}/share/pandoc/filters";
PANDOC_LINK_MANPAGES_FILTER = import build-aux/pandoc-filters/link-manpages.nix { inherit pkgs; };
} }

View file

@ -1,87 +0,0 @@
{ pkgs ? (import ../.. {}), nixpkgs ? { }}:
let
inherit (pkgs) lib;
inherit (lib) hasPrefix removePrefix;
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" ''
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl" />
<xsl:import href="${./parameters.xml}"/>
</xsl:stylesheet>
'';
xhtml-xsl = pkgs.writeText "xhtml.xsl" ''
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/xhtml/docbook.xsl" />
<xsl:import href="${./parameters.xml}"/>
</xsl:stylesheet>
'';
# NB: This file describes the Nixpkgs manual, which happens to use module
# docs infra originally developed for NixOS.
optionsDoc = pkgs.nixosOptionsDoc {
inherit (pkgs.lib.evalModules {
modules = [ ../../pkgs/top-level/config.nix ];
class = "nixpkgsConfig";
}) options;
documentType = "none";
transformOptions = opt:
opt // {
declarations =
map
(decl:
if hasPrefix (toString ../..) (toString decl)
then
let subpath = removePrefix "/" (removePrefix (toString ../..) (toString decl));
in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; }
else decl)
opt.declarations;
};
};
in pkgs.runCommand "doc-support" {}
''
mkdir result
(
cd result
ln -s ${locationsXml} ./function-locations.xml
ln -s ${functionDocs} ./function-docs
ln -s ${optionsDoc.optionsDocBook} ./config-options.docbook.xml
ln -s ${pkgs.docbook5}/xml/rng/docbook/docbook.rng ./docbook.rng
ln -s ${pkgs.docbook_xsl_ns}/xml/xsl ./xsl
ln -s ${epub-xsl} ./epub.xsl
ln -s ${xhtml-xsl} ./xhtml.xsl
ln -s ${./xmlformat.conf} ./xmlformat.conf
ln -s ${pkgs.documentation-highlighter} ./highlightjs
echo -n "${version}" > ./version
)
mv result $out
''

View file

@ -1,36 +1,41 @@
# Generates the documentation for library functions via nixdoc. # Generates the documentation for library functions via nixdoc.
{ pkgs, locationsXml, libsets }: { pkgs, nixpkgs, libsets }:
with pkgs; stdenv.mkDerivation { with pkgs;
let
locationsJSON = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; };
in
stdenv.mkDerivation {
name = "nixpkgs-lib-docs"; name = "nixpkgs-lib-docs";
src = ../../lib; src = ../../lib;
buildInputs = [ nixdoc ]; buildInputs = [ nixdoc ];
installPhase = '' installPhase = ''
function docgen { function docgen {
# TODO: wrap lib.$1 in <literal>, make nixdoc not escape it name=$1
if [[ -e "../lib/$1.nix" ]]; then baseName=$2
nixdoc -c "$1" -d "lib.$1: $2" -f "$1.nix" > "$out/$1.xml" description=$3
# TODO: wrap lib.$name in <literal>, make nixdoc not escape it
if [[ -e "../lib/$baseName.nix" ]]; then
nixdoc -c "$name" -d "lib.$name: $description" -l ${locationsJSON} -f "$baseName.nix" > "$out/$name.md"
else else
nixdoc -c "$1" -d "lib.$1: $2" -f "$1/default.nix" > "$out/$1.xml" nixdoc -c "$name" -d "lib.$name: $description" -l ${locationsJSON} -f "$baseName/default.nix" > "$out/$name.md"
fi fi
echo "<xi:include href='$1.xml' />" >> "$out/index.xml" echo "$out/$name.md" >> "$out/index.md"
} }
mkdir -p "$out" mkdir -p "$out"
cat > "$out/index.xml" << 'EOF' cat > "$out/index.md" << 'EOF'
<?xml version="1.0" encoding="utf-8"?> ```{=include=} sections
<root xmlns:xi="http://www.w3.org/2001/XInclude">
EOF EOF
${lib.concatMapStrings ({ name, description }: '' ${lib.concatMapStrings ({ name, baseName ? name, description }: ''
docgen ${name} ${lib.escapeShellArg description} docgen ${name} ${baseName} ${lib.escapeShellArg description}
'') libsets} '') libsets}
echo "</root>" >> "$out/index.xml" echo '```' >> "$out/index.md"
ln -s ${locationsXml} $out/locations.xml
''; '';
} }

View file

@ -58,28 +58,18 @@ let
[ "-prime" ]; [ "-prime" ];
urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}"; urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}";
xmlstrings = (nixpkgsLib.strings.concatMapStrings jsonLocs = builtins.listToAttrs
({ name, value }: (builtins.map
'' ({ name, value }: {
<section><title>${name}</title> name = sanitizeId name;
<para xml:id="${sanitizeId name}"> value =
Located at let
<link text = "${value.file}:${builtins.toString value.line}";
xlink:href="${urlPrefix}/${value.file}#L${builtins.toString value.line}">${value.file}:${builtins.toString value.line}</link> target = "${urlPrefix}/${value.file}#L${builtins.toString value.line}";
in <literal>&lt;nixpkgs&gt;</literal>. in
</para> "[${text}](${target}) in `<nixpkgs>`";
</section> })
'')
relativeLocs); relativeLocs);
in pkgs.writeText in
"locations.xml" pkgs.writeText "locations.json" (builtins.toJSON jsonLocs)
''
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5">
<title>All the locations for every lib function</title>
<para>This file is only for inclusion by other files.</para>
${xmlstrings}
</section>
''

View file

@ -1,19 +0,0 @@
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<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="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'" />
<xsl:param name="generate.consistent.ids" select="1" />
</xsl:stylesheet>

View file

@ -1,72 +0,0 @@
#
# DocBook Configuration file for "xmlformat"
# see http://www.kitebird.com/software/xmlformat/
# 10 Sept. 2004
#
# Only block elements
ackno address appendix article biblioentry bibliography bibliomixed \
biblioset blockquote book bridgehead callout calloutlist caption caution \
chapter chapterinfo classsynopsis cmdsynopsis colophon constraintdef \
constructorsynopsis dedication destructorsynopsis entry epigraph equation example \
figure formalpara funcsynopsis glossary glossdef glossdiv glossentry glosslist \
glosssee glossseealso graphic graphicco highlights imageobjectco important \
index indexdiv indexentry indexinfo info informalequation informalexample \
informalfigure informaltable legalnotice literallayout lot lotentry mediaobject \
mediaobjectco msgmain msgset note orderedlist para part preface primaryie \
procedure qandadiv qandaentry qandaset refentry refentrytitle reference \
refnamediv refsect1 refsect2 refsect3 refsection revhistory screenshot sect1 \
sect2 sect3 sect4 sect5 section seglistitem set setindex sidebar simpara \
simplesect step substeps synopfragment synopsis table term title \
toc variablelist varlistentry warning itemizedlist listitem \
footnote colspec partintro row simplelist subtitle tbody tgroup thead tip
format block
normalize no
#appendix bibliography chapter glossary preface reference
# element-break 3
sect1 section
element-break 2
#
para abstract
format block
entry-break 1
exit-break 1
normalize yes
title
format block
normalize = yes
entry-break = 0
exit-break = 0
# Inline elements
abbrev accel acronym action application citation citebiblioid citerefentry citetitle \
classname co code command computeroutput constant country database date email emphasis \
envar errorcode errorname errortext errortype exceptionname fax filename \
firstname firstterm footnoteref foreignphrase funcdef funcparams function \
glossterm group guibutton guiicon guilabel guimenu guimenuitem guisubmenu \
hardware holder honorific indexterm inlineequation inlinegraphic inlinemediaobject \
interface interfacename \
keycap keycode keycombo keysym lineage link literal manvolnum markup medialabel \
menuchoice methodname methodparam modifier mousebutton olink ooclass ooexception \
oointerface option optional otheraddr othername package paramdef parameter personname \
phrase pob postcode productname prompt property quote refpurpose replaceable \
returnvalue revnumber sgmltag state street structfield structname subscript \
superscript surname symbol systemitem token trademark type ulink userinput \
uri varargs varname void wordasword xref year mathphrase member tag
format inline
programlisting screen
format verbatim
entry-break = 0
exit-break = 0
# This is needed so that the spacing inside those tags is kept.
term cmdsynopsis arg
normalize yes
format block

11
third_party/nixpkgs/doc/functions.md vendored Normal file
View file

@ -0,0 +1,11 @@
# Functions reference {#chap-functions}
The nixpkgs repository has several utility functions to manipulate Nix expressions.
```{=include=} sections
functions/library.md
functions/generators.section.md
functions/debug.section.md
functions/prefer-remote-fetch.section.md
functions/nix-gitignore.section.md
```

View file

@ -1,14 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="chap-functions">
<title>Functions reference</title>
<para>
The nixpkgs repository has several utility functions to manipulate Nix expressions.
</para>
<xi:include href="functions/library.xml" />
<xi:include href="functions/generators.section.xml" />
<xi:include href="functions/debug.section.xml" />
<xi:include href="functions/prefer-remote-fetch.section.xml" />
<xi:include href="functions/nix-gitignore.section.xml" />
</chapter>

View file

@ -16,7 +16,7 @@ let
if v == true then ''"yes"'' if v == true then ''"yes"''
else if v == false then ''"no"'' else if v == false then ''"no"''
else if isString v then ''"${v}"'' else if isString v then ''"${v}"''
# and delegats all other values to the default generator # and delegates all other values to the default generator
else generators.mkValueStringDefault {} v; else generators.mkValueStringDefault {} v;
} ":"; } ":";
}; };

View file

@ -0,0 +1,5 @@
# Nixpkgs Library Functions {#sec-functions-library}
Nixpkgs provides a standard library at `pkgs.lib`, or through `import <nixpkgs/lib>`.
<!-- nixdoc-generated documentation must be appended here during build! -->

View file

@ -1,14 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-functions-library">
<title>Nixpkgs Library Functions</title>
<para>
Nixpkgs provides a standard library at <varname>pkgs.lib</varname>, or through <code>import &lt;nixpkgs/lib&gt;</code>.
</para>
<!-- 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>

View file

@ -1,4 +1,3 @@
# Autoconf {#setup-hook-autoconf}
### Autoconf {#setup-hook-autoconf}
The `autoreconfHook` derivation adds `autoreconfPhase`, which runs autoreconf, libtoolize and automake, essentially preparing the configure script in autotools-based builds. Most autotools-based packages come with the configure script pre-generated, but this hook is necessary for a few packages and when you need to patch the packages configure scripts. The `autoreconfHook` derivation adds `autoreconfPhase`, which runs autoreconf, libtoolize and automake, essentially preparing the configure script in autotools-based builds. Most autotools-based packages come with the configure script pre-generated, but this hook is necessary for a few packages and when you need to patch the packages configure scripts.

View file

@ -1,4 +1,3 @@
# Automake {#setup-hook-automake}
### Automake {#setup-hook-automake}
Adds the `share/aclocal` subdirectory of each build input to the `ACLOCAL_PATH` environment variable. Adds the `share/aclocal` subdirectory of each build input to the `ACLOCAL_PATH` environment variable.

View file

@ -1,5 +1,4 @@
# autoPatchelfHook {#setup-hook-autopatchelfhook}
### autoPatchelfHook {#setup-hook-autopatchelfhook}
This is a special setup hook which helps in packaging proprietary software in that it automatically tries to find missing shared library dependencies of ELF files based on the given `buildInputs` and `nativeBuildInputs`. This is a special setup hook which helps in packaging proprietary software in that it automatically tries to find missing shared library dependencies of ELF files based on the given `buildInputs` and `nativeBuildInputs`.

View file

@ -1,5 +1,4 @@
# breakpointHook {#breakpointhook}
### breakpointHook {#breakpointhook}
This hook will make a build pause instead of stopping when a failure happens. It prevents nix from cleaning up the build environment immediately and allows the user to attach to a build environment using the `cntr` command. Upon build error it will print instructions on how to use `cntr`, which can be used to enter the environment for debugging. Installing cntr and running the command will provide shell access to the build sandbox of failed build. At `/var/lib/cntr` the sandboxed filesystem is mounted. All commands and files of the system are still accessible within the shell. To execute commands from the sandbox use the cntr exec subcommand. `cntr` is only supported on Linux-based platforms. To use it first add `cntr` to your `environment.systemPackages` on NixOS or alternatively to the root user on non-NixOS systems. Then in the package that is supposed to be inspected, add `breakpointHook` to `nativeBuildInputs`. This hook will make a build pause instead of stopping when a failure happens. It prevents nix from cleaning up the build environment immediately and allows the user to attach to a build environment using the `cntr` command. Upon build error it will print instructions on how to use `cntr`, which can be used to enter the environment for debugging. Installing cntr and running the command will provide shell access to the build sandbox of failed build. At `/var/lib/cntr` the sandboxed filesystem is mounted. All commands and files of the system are still accessible within the shell. To execute commands from the sandbox use the cntr exec subcommand. `cntr` is only supported on Linux-based platforms. To use it first add `cntr` to your `environment.systemPackages` on NixOS or alternatively to the root user on non-NixOS systems. Then in the package that is supposed to be inspected, add `breakpointHook` to `nativeBuildInputs`.

View file

@ -1,4 +1,3 @@
# cmake {#cmake}
### cmake {#cmake}
Overrides the default configure phase to run the CMake command. By default, we use the Make generator of CMake. In addition, dependencies are added automatically to `CMAKE_PREFIX_PATH` so that packages are correctly detected by CMake. Some additional flags are passed in to give similar behavior to configure-based packages. You can disable this hooks behavior by setting `configurePhase` to a custom value, or by setting `dontUseCmakeConfigure`. `cmakeFlags` controls flags passed only to CMake. By default, parallel building is enabled as CMake supports parallel building almost everywhere. When Ninja is also in use, CMake will detect that and use the ninja generator. Overrides the default configure phase to run the CMake command. By default, we use the Make generator of CMake. In addition, dependencies are added automatically to `CMAKE_PREFIX_PATH` so that packages are correctly detected by CMake. Some additional flags are passed in to give similar behavior to configure-based packages. You can disable this hooks behavior by setting `configurePhase` to a custom value, or by setting `dontUseCmakeConfigure`. `cmakeFlags` controls flags passed only to CMake. By default, parallel building is enabled as CMake supports parallel building almost everywhere. When Ninja is also in use, CMake will detect that and use the ninja generator.

View file

@ -1,4 +1,3 @@
# gdk-pixbuf {#setup-hook-gdk-pixbuf}
### gdk-pixbuf {#setup-hook-gdk-pixbuf}
Exports `GDK_PIXBUF_MODULE_FILE` environment variable to the builder. Add librsvg package to `buildInputs` to get svg support. See also the [setup hook description in GNOME platform docs](#ssec-gnome-hooks-gdk-pixbuf). Exports `GDK_PIXBUF_MODULE_FILE` environment variable to the builder. Add librsvg package to `buildInputs` to get svg support. See also the [setup hook description in GNOME platform docs](#ssec-gnome-hooks-gdk-pixbuf).

View file

@ -1,4 +1,3 @@
# GHC {#ghc}
### GHC {#ghc}
Creates a temporary package database and registers every Haskell build input in it (TODO: how?). Creates a temporary package database and registers every Haskell build input in it (TODO: how?).

View file

@ -1,4 +1,3 @@
# GNOME platform {#gnome-platform}
### GNOME platform {#gnome-platform}
Hooks related to GNOME platform and related libraries like GLib, GTK and GStreamer are described in [](#sec-language-gnome). Hooks related to GNOME platform and related libraries like GLib, GTK and GStreamer are described in [](#sec-language-gnome).

33
third_party/nixpkgs/doc/hooks/index.md vendored Normal file
View file

@ -0,0 +1,33 @@
# Hooks reference {#chap-hooks}
Nixpkgs has several hook packages that augment the stdenv phases.
The stdenv built-in hooks are documented in [](#ssec-setup-hooks).
```{=include=} sections
autoconf.section.md
automake.section.md
autopatchelf.section.md
breakpoint.section.md
cmake.section.md
gdk-pixbuf.section.md
ghc.section.md
gnome.section.md
installShellFiles.section.md
libiconv.section.md
libxml2.section.md
meson.section.md
ninja.section.md
patch-rc-path-hooks.section.md
perl.section.md
pkg-config.section.md
postgresql-test-hook.section.md
python.section.md
qt-4.section.md
scons.section.md
tetex-tex-live.section.md
unzip.section.md
validatePkgConfig.section.md
waf.section.md
xcbuild.section.md
```

View file

@ -1,37 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="chap-hooks">
<title>Hooks reference</title>
<para>
Nixpkgs has several hook packages that augment the stdenv phases.
</para>
<para>
The stdenv built-in hooks are documented in <xref linkend="ssec-setup-hooks"/>.
</para>
<xi:include href="./autoconf.section.xml" />
<xi:include href="./automake.section.xml" />
<xi:include href="./autopatchelf.section.xml" />
<xi:include href="./breakpoint.section.xml" />
<xi:include href="./cmake.section.xml" />
<xi:include href="./gdk-pixbuf.section.xml" />
<xi:include href="./ghc.section.xml" />
<xi:include href="./gnome.section.xml" />
<xi:include href="./installShellFiles.section.xml" />
<xi:include href="./libiconv.section.xml" />
<xi:include href="./libxml2.section.xml" />
<xi:include href="./meson.section.xml" />
<xi:include href="./ninja.section.xml" />
<xi:include href="./patch-rc-path-hooks.section.xml" />
<xi:include href="./perl.section.xml" />
<xi:include href="./pkg-config.section.xml" />
<xi:include href="./postgresql-test-hook.section.xml" />
<xi:include href="./python.section.xml" />
<xi:include href="./qt-4.section.xml" />
<xi:include href="./scons.section.xml" />
<xi:include href="./tetex-tex-live.section.xml" />
<xi:include href="./unzip.section.xml" />
<xi:include href="./validatePkgConfig.section.xml" />
<xi:include href="./waf.section.xml" />
<xi:include href="./xcbuild.section.xml" />
</chapter>

View file

@ -1,5 +1,4 @@
# `installShellFiles` {#installshellfiles}
### `installShellFiles` {#installshellfiles}
This hook helps with installing manpages and shell completion files. It exposes 2 shell functions `installManPage` and `installShellCompletion` that can be used from your `postInstall` hook. This hook helps with installing manpages and shell completion files. It exposes 2 shell functions `installManPage` and `installShellCompletion` that can be used from your `postInstall` hook.

View file

@ -1,4 +1,3 @@
# libiconv, libintl {#libiconv-libintl}
### libiconv, libintl {#libiconv-libintl}
A few libraries automatically add to `NIX_LDFLAGS` their library, making their symbols automatically available to the linker. This includes libiconv and libintl (gettext). This is done to provide compatibility between GNU Linux, where libiconv and libintl are bundled in, and other systems where that might not be the case. Sometimes, this behavior is not desired. To disable this behavior, set `dontAddExtraLibs`. A few libraries automatically add to `NIX_LDFLAGS` their library, making their symbols automatically available to the linker. This includes libiconv and libintl (gettext). This is done to provide compatibility between GNU Linux, where libiconv and libintl are bundled in, and other systems where that might not be the case. Sometimes, this behavior is not desired. To disable this behavior, set `dontAddExtraLibs`.

View file

@ -1,4 +1,3 @@
# libxml2 {#setup-hook-libxml2}
### libxml2 {#setup-hook-libxml2}
Adds every file named `catalog.xml` found under the `xml/dtd` and `xml/xsl` subdirectories of each build input to the `XML_CATALOG_FILES` environment variable. Adds every file named `catalog.xml` found under the `xml/dtd` and `xml/xsl` subdirectories of each build input to the `XML_CATALOG_FILES` environment variable.

View file

@ -1,26 +1,25 @@
# Meson {#meson}
### Meson {#meson}
Overrides the configure phase to run meson to generate Ninja files. To run these files, you should accompany Meson with ninja. By default, `enableParallelBuilding` is enabled as Meson supports parallel building almost everywhere. Overrides the configure phase to run meson to generate Ninja files. To run these files, you should accompany Meson with ninja. By default, `enableParallelBuilding` is enabled as Meson supports parallel building almost everywhere.
#### Variables controlling Meson {#variables-controlling-meson} ## Variables controlling Meson {#variables-controlling-meson}
##### `mesonFlags` {#mesonflags} ### `mesonFlags` {#mesonflags}
Controls the flags passed to meson. Controls the flags passed to meson.
##### `mesonBuildType` {#mesonbuildtype} ### `mesonBuildType` {#mesonbuildtype}
Which [`--buildtype`](https://mesonbuild.com/Builtin-options.html#core-options) to pass to Meson. We default to `plain`. Which [`--buildtype`](https://mesonbuild.com/Builtin-options.html#core-options) to pass to Meson. We default to `plain`.
##### `mesonAutoFeatures` {#mesonautofeatures} ### `mesonAutoFeatures` {#mesonautofeatures}
What value to set [`-Dauto_features=`](https://mesonbuild.com/Builtin-options.html#core-options) to. We default to `enabled`. What value to set [`-Dauto_features=`](https://mesonbuild.com/Builtin-options.html#core-options) to. We default to `enabled`.
##### `mesonWrapMode` {#mesonwrapmode} ### `mesonWrapMode` {#mesonwrapmode}
What value to set [`-Dwrap_mode=`](https://mesonbuild.com/Builtin-options.html#core-options) to. We default to `nodownload` as we disallow network access. What value to set [`-Dwrap_mode=`](https://mesonbuild.com/Builtin-options.html#core-options) to. We default to `nodownload` as we disallow network access.
##### `dontUseMesonConfigure` {#dontusemesonconfigure} ### `dontUseMesonConfigure` {#dontusemesonconfigure}
Disables using Mesons `configurePhase`. Disables using Mesons `configurePhase`.

View file

@ -1,4 +1,3 @@
# ninja {#ninja}
### ninja {#ninja}
Overrides the build, install, and check phase to run ninja instead of make. You can disable this behavior with the `dontUseNinjaBuild`, `dontUseNinjaInstall`, and `dontUseNinjaCheck`, respectively. Parallel building is enabled by default in Ninja. Overrides the build, install, and check phase to run ninja instead of make. You can disable this behavior with the `dontUseNinjaBuild`, `dontUseNinjaInstall`, and `dontUseNinjaCheck`, respectively. Parallel building is enabled by default in Ninja.

View file

@ -1,4 +1,3 @@
# Perl {#setup-hook-perl}
### Perl {#setup-hook-perl}
Adds the `lib/site_perl` subdirectory of each build input to the `PERL5LIB` environment variable. For instance, if `buildInputs` contains Perl, then the `lib/site_perl` subdirectory of each input is added to the `PERL5LIB` environment variable. Adds the `lib/site_perl` subdirectory of each build input to the `PERL5LIB` environment variable. For instance, if `buildInputs` contains Perl, then the `lib/site_perl` subdirectory of each input is added to the `PERL5LIB` environment variable.

View file

@ -1,4 +1,3 @@
# pkg-config {#setup-hook-pkg-config}
### pkg-config {#setup-hook-pkg-config}
Adds the `lib/pkgconfig` and `share/pkgconfig` subdirectories of each build input to the `PKG_CONFIG_PATH` environment variable. Adds the `lib/pkgconfig` and `share/pkgconfig` subdirectories of each build input to the `PKG_CONFIG_PATH` environment variable.

View file

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

View file

@ -1,4 +1,3 @@
# Qt 4 {#qt-4}
### Qt 4 {#qt-4}
Sets the `QTDIR` environment variable to Qts path. Sets the `QTDIR` environment variable to Qts path.

View file

@ -1,4 +1,3 @@
# scons {#scons}
### scons {#scons}
Overrides the build, install, and check phases. This uses the scons build system as a replacement for make. scons does not provide a configure phase, so everything is managed at build and install time. Overrides the build, install, and check phases. This uses the scons build system as a replacement for make. scons does not provide a configure phase, so everything is managed at build and install time.

View file

@ -1,4 +1,3 @@
# teTeX / TeX Live {#tetex-tex-live}
### teTeX / TeX Live {#tetex-tex-live}
Adds the `share/texmf-nix` subdirectory of each build input to the `TEXINPUTS` environment variable. Adds the `share/texmf-nix` subdirectory of each build input to the `TEXINPUTS` environment variable.

View file

@ -1,4 +1,3 @@
# unzip {#unzip}
### unzip {#unzip}
This setup hook will allow you to unzip .zip files specified in `$src`. There are many similar packages like `unrar`, `undmg`, etc. This setup hook will allow you to unzip .zip files specified in `$src`. There are many similar packages like `unrar`, `undmg`, etc.

View file

@ -1,4 +1,3 @@
# validatePkgConfig {#validatepkgconfig}
### validatePkgConfig {#validatepkgconfig}
The `validatePkgConfig` hook validates all pkg-config (`.pc`) files in a package. This helps catching some common errors in pkg-config files, such as undefined variables. The `validatePkgConfig` hook validates all pkg-config (`.pc`) files in a package. This helps catching some common errors in pkg-config files, such as undefined variables.

View file

@ -1,4 +1,3 @@
# wafHook {#wafhook}
### wafHook {#wafhook}
Overrides the configure, build, and install phases. This will run the “waf” script used by many projects. If `wafPath` (default `./waf`) doesnt exist, it will copy the version of waf available in Nixpkgs. `wafFlags` can be used to pass flags to the waf script. Overrides the configure, build, and install phases. This will run the “waf” script used by many projects. If `wafPath` (default `./waf`) doesnt exist, it will copy the version of waf available in Nixpkgs. `wafFlags` can be used to pass flags to the waf script.

View file

@ -1,4 +1,3 @@
# xcbuildHook {#xcbuildhook}
### xcbuildHook {#xcbuildhook}
Overrides the build and install phases to run the "xcbuild" command. This hook is needed when a project only comes with build files for the XCode build system. You can disable this behavior by setting buildPhase and configurePhase to a custom value. xcbuildFlags controls flags passed only to xcbuild. Overrides the build and install phases to run the "xcbuild" command. This hook is needed when a project only comes with build files for the XCode build system. You can disable this behavior by setting buildPhase and configurePhase to a custom value. xcbuildFlags controls flags passed only to xcbuild.

View file

@ -1,6 +1,6 @@
# Bower {#sec-bower} # Bower {#sec-bower}
[Bower](https://bower.io) is a package manager for web site front-end components. Bower packages (comprising of build artefacts and sometimes sources) are stored in `git` repositories, typically on Github. The package registry is run by the Bower team with package metadata coming from the `bower.json` file within each package. [Bower](https://bower.io) is a package manager for web site front-end components. Bower packages (comprising of build artifacts and sometimes sources) are stored in `git` repositories, typically on Github. The package registry is run by the Bower team with package metadata coming from the `bower.json` file within each package.
The end result of running Bower is a `bower_components` directory which can be included in the web app's build process. The end result of running Bower is a `bower_components` directory which can be included in the web app's build process.
@ -41,32 +41,18 @@ The function is implemented in [pkgs/development/bower-modules/generic/default.n
### Example buildBowerComponents {#ex-buildBowerComponents} ### Example buildBowerComponents {#ex-buildBowerComponents}
```{=docbook} ```nix
<programlisting language="nix">
bowerComponents = buildBowerComponents { bowerComponents = buildBowerComponents {
name = "my-web-app"; name = "my-web-app";
generated = ./bower-packages.nix; <co xml:id="ex-buildBowerComponents-1" /> generated = ./bower-packages.nix; # note 1
src = myWebApp; <co xml:id="ex-buildBowerComponents-2" /> src = myWebApp; # note 2
}; };
</programlisting>
``` ```
In ["buildBowerComponents" example](#ex-buildBowerComponents) the following arguments are of special significance to the function: In ["buildBowerComponents" example](#ex-buildBowerComponents) the following arguments are of special significance to the function:
```{=docbook} 1. `generated` specifies the file which was created by {command}`bower2nix`.
<calloutlist> 2. `src` is your project's sources. It needs to contain a {file}`bower.json` file.
<callout arearefs="ex-buildBowerComponents-1">
<para>
<varname>generated</varname> specifies the file which was created by <command>bower2nix</command>.
</para>
</callout>
<callout arearefs="ex-buildBowerComponents-2">
<para>
<varname>src</varname> is your project's sources. It needs to contain a <filename>bower.json</filename> file.
</para>
</callout>
</calloutlist>
```
`buildBowerComponents` will run Bower to link together the output of `bower2nix`, resulting in a `bower_components` directory which can be used. `buildBowerComponents` will run Bower to link together the output of `bower2nix`, resulting in a `bower_components` directory which can be used.
@ -91,10 +77,9 @@ gulp.task('build', [], function () {
### Example Full example — default.nix {#ex-buildBowerComponentsDefaultNix} ### Example Full example — default.nix {#ex-buildBowerComponentsDefaultNix}
```{=docbook} ```nix
<programlisting language="nix">
{ myWebApp ? { outPath = ./.; name = "myWebApp"; } { myWebApp ? { outPath = ./.; name = "myWebApp"; }
, pkgs ? import &lt;nixpkgs&gt; {} , pkgs ? import <nixpkgs> {}
}: }:
pkgs.stdenv.mkDerivation { pkgs.stdenv.mkDerivation {
@ -103,49 +88,29 @@ pkgs.stdenv.mkDerivation {
buildInputs = [ pkgs.nodePackages.gulp ]; buildInputs = [ pkgs.nodePackages.gulp ];
bowerComponents = pkgs.buildBowerComponents { <co xml:id="ex-buildBowerComponentsDefault-1" /> bowerComponents = pkgs.buildBowerComponents { # note 1
name = "my-web-app"; name = "my-web-app";
generated = ./bower-packages.nix; generated = ./bower-packages.nix;
src = myWebApp; src = myWebApp;
}; };
buildPhase = '' buildPhase = ''
cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . <co xml:id="ex-buildBowerComponentsDefault-2" /> cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . # note 2
export HOME=$PWD <co xml:id="ex-buildBowerComponentsDefault-3" /> export HOME=$PWD # note 3
${pkgs.nodePackages.gulp}/bin/gulp build <co xml:id="ex-buildBowerComponentsDefault-4" /> ${pkgs.nodePackages.gulp}/bin/gulp build # note 4
''; '';
installPhase = "mv gulpdist $out"; installPhase = "mv gulpdist $out";
} }
</programlisting>
``` ```
A few notes about [Full example — `default.nix`](#ex-buildBowerComponentsDefaultNix): A few notes about [Full example — `default.nix`](#ex-buildBowerComponentsDefaultNix):
```{=docbook} 1. The result of `buildBowerComponents` is an input to the frontend build.
<calloutlist> 2. Whether to symlink or copy the {file}`bower_components` directory depends on the build tool in use.
<callout arearefs="ex-buildBowerComponentsDefault-1"> In this case a copy is used to avoid {command}`gulp` silliness with permissions.
<para> 3. {command}`gulp` requires `HOME` to refer to a writeable directory.
The result of <varname>buildBowerComponents</varname> is an input to the frontend build. 4. The actual build command in this example is {command}`gulp`. Other tools could be used instead.
</para>
</callout>
<callout arearefs="ex-buildBowerComponentsDefault-2">
<para>
Whether to symlink or copy the <filename>bower_components</filename> directory depends on the build tool in use. In this case a copy is used to avoid <command>gulp</command> silliness with permissions.
</para>
</callout>
<callout arearefs="ex-buildBowerComponentsDefault-3">
<para>
<command>gulp</command> requires <varname>HOME</varname> to refer to a writeable directory.
</para>
</callout>
<callout arearefs="ex-buildBowerComponentsDefault-4">
<para>
The actual build command. Other tools could be used.
</para>
</callout>
</calloutlist>
```
## Troubleshooting {#ssec-bower2nix-troubleshooting} ## Troubleshooting {#ssec-bower2nix-troubleshooting}

View file

@ -8,7 +8,7 @@ A package set is available for each CUDA version, so for example
`cudaPackages_11_6`. Within each set is a matching version of the above listed `cudaPackages_11_6`. Within each set is a matching version of the above listed
packages. Additionally, other versions of the packages that are packaged and packages. Additionally, other versions of the packages that are packaged and
compatible are available as well. For example, there can be a compatible are available as well. For example, there can be a
`cudaPackages.cudnn_8_3_2` package. `cudaPackages.cudnn_8_3` package.
To use one or more CUDA packages in an expression, give the expression a `cudaPackages` parameter, and in case CUDA is optional To use one or more CUDA packages in an expression, give the expression a `cudaPackages` parameter, and in case CUDA is optional
```nix ```nix
@ -28,7 +28,7 @@ set.
```nix ```nix
mypkg = let mypkg = let
cudaPackages = cudaPackages_11_5.overrideScope' (final: prev: { cudaPackages = cudaPackages_11_5.overrideScope' (final: prev: {
cudnn = prev.cudnn_8_3_2; cudnn = prev.cudnn_8_3;
}}); }});
in callPackage { inherit cudaPackages; }; in callPackage { inherit cudaPackages; };
``` ```

View file

@ -307,12 +307,12 @@ $ nix-env --install --attr haskellPackages.dhall-nixpkgs
$ nix-env --install --attr nix-prefetch-git # Used by dhall-to-nixpkgs $ nix-env --install --attr nix-prefetch-git # Used by dhall-to-nixpkgs
$ dhall-to-nixpkgs github https://github.com/Gabriel439/dhall-semver.git $ dhall-to-nixpkgs github https://github.com/Gabriella439/dhall-semver.git
{ buildDhallGitHubPackage, Prelude }: { buildDhallGitHubPackage, Prelude }:
buildDhallGitHubPackage { buildDhallGitHubPackage {
name = "dhall-semver"; name = "dhall-semver";
githubBase = "github.com"; githubBase = "github.com";
owner = "Gabriel439"; owner = "Gabriella439";
repo = "dhall-semver"; repo = "dhall-semver";
rev = "2d44ae605302ce5dc6c657a1216887fbb96392a4"; rev = "2d44ae605302ce5dc6c657a1216887fbb96392a4";
fetchSubmodules = false; fetchSubmodules = false;

View file

@ -92,7 +92,7 @@ The `dotnetCorePackages.sdk` contains both a runtime and the full sdk of a given
To package Dotnet applications, you can use `buildDotnetModule`. This has similar arguments to `stdenv.mkDerivation`, with the following additions: To package Dotnet applications, you can use `buildDotnetModule`. This has similar arguments to `stdenv.mkDerivation`, with the following additions:
* `projectFile` is used for specifying the dotnet project file, relative to the source root. These usually have `.sln` or `.csproj` file extensions. This can be a list of multiple projects as well. Most of the time dotnet can figure this location out by itself, so this should only be set if necessary. * `projectFile` is used for specifying the dotnet project file, relative to the source root. These have `.sln` (entire solution) or `.csproj` (single project) file extensions. This can be a list of multiple projects as well. When omitted, will attempt to find and build the solution (`.sln`). If running into problems, make sure to set it to a file (or a list of files) with the `.csproj` extension - building applications as entire solutions is not fully supported by the .NET CLI.
* `nugetDeps` takes either a path to a `deps.nix` file, or a derivation. The `deps.nix` file can be generated using the script attached to `passthru.fetch-deps`. This file can also be generated manually using `nuget-to-nix` tool, which is available in nixpkgs. If the argument is a derivation, it will be used directly and assume it has the same output as `mkNugetDeps`. * `nugetDeps` takes either a path to a `deps.nix` file, or a derivation. The `deps.nix` file can be generated using the script attached to `passthru.fetch-deps`. This file can also be generated manually using `nuget-to-nix` tool, which is available in nixpkgs. If the argument is a derivation, it will be used directly and assume it has the same output as `mkNugetDeps`.
* `packNupkg` is used to pack project as a `nupkg`, and installs it to `$out/share`. If set to `true`, the derivation can be used as a dependency for another dotnet project by adding it to `projectReferences`. * `packNupkg` is used to pack project as a `nupkg`, and installs it to `$out/share`. If set to `true`, the derivation can be used as a dependency for another dotnet project by adding it to `projectReferences`.
* `projectReferences` can be used to resolve `ProjectReference` project items. Referenced projects can be packed with `buildDotnetModule` by setting the `packNupkg = true` attribute and passing a list of derivations to `projectReferences`. Since we are sharing referenced projects as NuGets they must be added to csproj/fsproj files as `PackageReference` as well. * `projectReferences` can be used to resolve `ProjectReference` project items. Referenced projects can be packed with `buildDotnetModule` by setting the `packNupkg = true` attribute and passing a list of derivations to `projectReferences`. Since we are sharing referenced projects as NuGets they must be added to csproj/fsproj files as `PackageReference` as well.
@ -108,11 +108,13 @@ To package Dotnet applications, you can use `buildDotnetModule`. This has simila
* `executables` is used to specify which executables get wrapped to `$out/bin`, relative to `$out/lib/$pname`. If this is unset, all executables generated will get installed. If you do not want to install any, set this to `[]`. This gets done in the `preFixup` phase. * `executables` is used to specify which executables get wrapped to `$out/bin`, relative to `$out/lib/$pname`. If this is unset, all executables generated will get installed. If you do not want to install any, set this to `[]`. This gets done in the `preFixup` phase.
* `runtimeDeps` is used to wrap libraries into `LD_LIBRARY_PATH`. This is how dotnet usually handles runtime dependencies. * `runtimeDeps` is used to wrap libraries into `LD_LIBRARY_PATH`. This is how dotnet usually handles runtime dependencies.
* `buildType` is used to change the type of build. Possible values are `Release`, `Debug`, etc. By default, this is set to `Release`. * `buildType` is used to change the type of build. Possible values are `Release`, `Debug`, etc. By default, this is set to `Release`.
* `selfContainedBuild` allows to enable the [self-contained](https://docs.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained) build flag. By default, it is set to false and generated applications have a dependency on the selected dotnet runtime. If enabled, the dotnet runtime is bundled into the executable and the built app has no dependency on Dotnet. * `selfContainedBuild` allows to enable the [self-contained](https://docs.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained) build flag. By default, it is set to false and generated applications have a dependency on the selected dotnet runtime. If enabled, the dotnet runtime is bundled into the executable and the built app has no dependency on .NET.
* `useAppHost` will enable creation of a binary executable that runs the .NET application using the specified root. More info in [Microsoft docs](https://learn.microsoft.com/en-us/dotnet/core/deploying/#publish-framework-dependent). Enabled by default.
* `useDotnetFromEnv` will change the binary wrapper so that it uses the .NET from the environment. The runtime specified by `dotnet-runtime` is given as a fallback in case no .NET is installed in the user's environment. This is most useful for .NET global tools and LSP servers, which often extend the .NET CLI and their runtime should match the users' .NET runtime.
* `dotnet-sdk` is useful in cases where you need to change what dotnet SDK is being used. You can also set this to the result of `dotnetSdkPackages.combinePackages`, if the project uses multiple SDKs to build. * `dotnet-sdk` is useful in cases where you need to change what dotnet SDK is being used. You can also set this to the result of `dotnetSdkPackages.combinePackages`, if the project uses multiple SDKs to build.
* `dotnet-runtime` is useful in cases where you need to change what dotnet runtime is being used. This can be either a regular dotnet runtime, or an aspnetcore. * `dotnet-runtime` is useful in cases where you need to change what dotnet runtime is being used. This can be either a regular dotnet runtime, or an aspnetcore.
* `dotnet-test-sdk` is useful in cases where unit tests expect a different dotnet SDK. By default, this is set to the `dotnet-sdk` attribute. * `dotnet-test-sdk` is useful in cases where unit tests expect a different dotnet SDK. By default, this is set to the `dotnet-sdk` attribute.
* `testProjectFile` is useful in cases where the regular project file does not contain the unit tests. It gets restored and build, but not installed. You may need to regenerate your nuget lockfile after setting this. * `testProjectFile` is useful in cases where the regular project file does not contain the unit tests. It gets restored and build, but not installed. You may need to regenerate your nuget lockfile after setting this. Note that if set, only tests from this project are executed.
* `disabledTests` is used to disable running specific unit tests. This gets passed as: `dotnet test --filter "FullyQualifiedName!={}"`, to ensure compatibility with all unit test frameworks. * `disabledTests` is used to disable running specific unit tests. This gets passed as: `dotnet test --filter "FullyQualifiedName!={}"`, to ensure compatibility with all unit test frameworks.
* `dotnetRestoreFlags` can be used to pass flags to `dotnet restore`. * `dotnetRestoreFlags` can be used to pass flags to `dotnet restore`.
* `dotnetBuildFlags` can be used to pass flags to `dotnet build`. * `dotnetBuildFlags` can be used to pass flags to `dotnet build`.
@ -121,7 +123,7 @@ To package Dotnet applications, you can use `buildDotnetModule`. This has simila
* `dotnetPackFlags` can be used to pass flags to `dotnet pack`. Used only if `packNupkg` is set to `true`. * `dotnetPackFlags` can be used to pass flags to `dotnet pack`. Used only if `packNupkg` is set to `true`.
* `dotnetFlags` can be used to pass flags to all of the above phases. * `dotnetFlags` can be used to pass flags to all of the above phases.
When packaging a new application, you need to fetch its dependencies. You can run `nix-build -A package.fetch-deps` to generate a script that will build a lockfile for you. After running the script you should have the location of the generated lockfile printed to the console, which can be copied to a stable directory. Then set `nugetDeps = ./deps.nix` and you're ready to build the derivation. When packaging a new application, you need to fetch its dependencies. Create an empty `deps.nix`, set `nugetDeps = ./deps.nix`, then run `nix-build -A package.fetch-deps` to generate a script that will build the lockfile for you.
Here is an example `default.nix`, using some of the previously discussed arguments: Here is an example `default.nix`, using some of the previously discussed arguments:
```nix ```nix
@ -151,3 +153,60 @@ in buildDotnetModule rec {
runtimeDeps = [ ffmpeg ]; # This will wrap ffmpeg's library path into `LD_LIBRARY_PATH`. runtimeDeps = [ ffmpeg ]; # This will wrap ffmpeg's library path into `LD_LIBRARY_PATH`.
} }
``` ```
## Dotnet global tools {#dotnet-global-tools}
[.NET Global tools](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools) are a mechanism provided by the dotnet CLI to install .NET binaries from Nuget packages.
They can be installed either as a global tool for the entire system, or as a local tool specific to project.
The local installation is the easiest and works on NixOS in the same way as on other Linux distributions.
[See dotnet documention](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools#install-a-local-tool) to learn more.
[The global installation method](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools#install-a-global-tool)
should also work most of the time. You have to remember to update the `PATH`
value to the location the tools are installed to (the CLI will inform you about it during installation) and also set
the `DOTNET_ROOT` value, so that the tool can find the .NET SDK package.
You can find the path to the SDK by running `nix eval --raw nixpkgs#dotnet-sdk` (substitute the `dotnet-sdk` package for
another if a different SDK version is needed).
This method is not recommended on NixOS, since it's not declarative and involves installing binaries not made for NixOS,
which will not always work.
The third, and preferred way, is packaging the tool into a Nix derivation.
### Packaging Dotnet global tools {#packaging-dotnet-global-tools}
Dotnet global tools are standard .NET binaries, just made available through a special
NuGet package. Therefore, they can be built and packaged like every .NET application,
using `buildDotnetModule`.
If however the source is not available or difficult to build, the
`buildDotnetGlobalTool` helper can be used, which will package the tool
straight from its NuGet package.
This helper has the same arguments as `buildDotnetModule`, with a few differences:
* `pname` and `version` are required, and will be used to find the NuGet package of the tool
* `nugetName` can be used to override the NuGet package name that will be downloaded, if it's different from `pname`
* `nugetSha256` is the hash of the fetched NuGet package. Set this to `lib.fakeHash256` for the first build, and it will error out, giving you the proper hash. Also remember to update it during version updates (it will not error out if you just change the version while having a fetched package in `/nix/store`)
* `dotnet-runtime` is set to `dotnet-sdk` by default. When changing this, remember that .NET tools fetched from NuGet require an SDK.
Here is an example of packaging `pbm`, an unfree binary without source available:
```nix
{ buildDotnetGlobalTool, lib }:
buildDotnetGlobalTool {
pname = "pbm";
version = "1.3.1";
nugetSha256 = "sha256-ZG2HFyKYhVNVYd2kRlkbAjZJq88OADe3yjxmLuxXDUo=";
meta = with lib; {
homepage = "https://cmd.petabridge.com/index.html";
changelog = "https://cmd.petabridge.com/articles/RELEASE_NOTES.html";
license = licenses.unfree;
platforms = platforms.linux;
};
}
```

View file

@ -27,7 +27,7 @@ The modules are typically installed to `lib/gio/modules/` directory of a package
In particular, we recommend: In particular, we recommend:
* adding `dconf.lib` for any software on Linux that reads [GSettings](#ssec-gnome-settings) (even transitivily through e.g. GTKs file manager) * adding `dconf.lib` for any software on Linux that reads [GSettings](#ssec-gnome-settings) (even transitively through e.g. GTKs file manager)
* adding `glib-networking` for any software that accesses network using GIO or libsoup glib-networking contains a module that implements TLS support and loads system-wide proxy settings * adding `glib-networking` for any software that accesses network using GIO or libsoup glib-networking contains a module that implements TLS support and loads system-wide proxy settings
To allow software to use various virtual file systems, `gvfs` package can be also added. But that is usually an optional feature so we typically use `gvfs` from the system (e.g. installed globally using NixOS module). To allow software to use various virtual file systems, `gvfs` package can be also added. But that is usually an optional feature so we typically use `gvfs` from the system (e.g. installed globally using NixOS module).
@ -137,15 +137,15 @@ Most GNOME package offer [`updateScript`](#var-passthru-updateScript), it is the
## Frequently encountered issues {#ssec-gnome-common-issues} ## Frequently encountered issues {#ssec-gnome-common-issues}
#### `GLib-GIO-ERROR **: 06:04:50.903: No GSettings schemas are installed on the system` {#ssec-gnome-common-issues-no-schemas} ### `GLib-GIO-ERROR **: 06:04:50.903: No GSettings schemas are installed on the system` {#ssec-gnome-common-issues-no-schemas}
There are no schemas available in `XDG_DATA_DIRS`. Temporarily add a random package containing schemas like `gsettings-desktop-schemas` to `buildInputs`. [`glib`](#ssec-gnome-hooks-glib) and [`wrapGAppsHook`](#ssec-gnome-hooks-wrapgappshook) setup hooks will take care of making the schemas available to application and you will see the actual missing schemas with the [next error](#ssec-gnome-common-issues-missing-schema). Or you can try looking through the source code for the actual schemas used. There are no schemas available in `XDG_DATA_DIRS`. Temporarily add a random package containing schemas like `gsettings-desktop-schemas` to `buildInputs`. [`glib`](#ssec-gnome-hooks-glib) and [`wrapGAppsHook`](#ssec-gnome-hooks-wrapgappshook) setup hooks will take care of making the schemas available to application and you will see the actual missing schemas with the [next error](#ssec-gnome-common-issues-missing-schema). Or you can try looking through the source code for the actual schemas used.
#### `GLib-GIO-ERROR **: 06:04:50.903: Settings schema org.gnome.foo is not installed` {#ssec-gnome-common-issues-missing-schema} ### `GLib-GIO-ERROR **: 06:04:50.903: Settings schema org.gnome.foo is not installed` {#ssec-gnome-common-issues-missing-schema}
Package is missing some GSettings schemas. You can find out the package containing the schema with `nix-locate org.gnome.foo.gschema.xml` and let the hooks handle the wrapping as [above](#ssec-gnome-common-issues-no-schemas). Package is missing some GSettings schemas. You can find out the package containing the schema with `nix-locate org.gnome.foo.gschema.xml` and let the hooks handle the wrapping as [above](#ssec-gnome-common-issues-no-schemas).
#### When using `wrapGAppsHook` with special derivers you can end up with double wrapped binaries. {#ssec-gnome-common-issues-double-wrapped} ### When using `wrapGAppsHook` with special derivers you can end up with double wrapped binaries. {#ssec-gnome-common-issues-double-wrapped}
This is because derivers like `python.pkgs.buildPythonApplication` or `qt5.mkDerivation` have setup-hooks automatically added that produce wrappers with makeWrapper. The simplest way to workaround that is to disable the `wrapGAppsHook` automatic wrapping with `dontWrapGApps = true;` and pass the arguments it intended to pass to makeWrapper to another. This is because derivers like `python.pkgs.buildPythonApplication` or `qt5.mkDerivation` have setup-hooks automatically added that produce wrappers with makeWrapper. The simplest way to workaround that is to disable the `wrapGAppsHook` automatic wrapping with `dontWrapGApps = true;` and pass the arguments it intended to pass to makeWrapper to another.
@ -193,7 +193,7 @@ mkDerivation {
} }
``` ```
#### I am packaging a project that cannot be wrapped, like a library or GNOME Shell extension. {#ssec-gnome-common-issues-unwrappable-package} ### I am packaging a project that cannot be wrapped, like a library or GNOME Shell extension. {#ssec-gnome-common-issues-unwrappable-package}
You can rely on applications depending on the library setting the necessary environment variables but that is often easy to miss. Instead we recommend to patch the paths in the source code whenever possible. Here are some examples: You can rely on applications depending on the library setting the necessary environment variables but that is often easy to miss. Instead we recommend to patch the paths in the source code whenever possible. Here are some examples:
@ -209,6 +209,6 @@ You can rely on applications depending on the library setting the necessary envi
[]{#ssec-gnome-common-issues-unwrappable-package-gsettings-c} [Hard-coding GSettings schema path in C library](https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34) nothing special other than using [Coccinelle patch](https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467) to generate the patch itself. []{#ssec-gnome-common-issues-unwrappable-package-gsettings-c} [Hard-coding GSettings schema path in C library](https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34) nothing special other than using [Coccinelle patch](https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467) to generate the patch itself.
#### I need to wrap a binary outside `bin` and `libexec` directories. {#ssec-gnome-common-issues-weird-location} ### I need to wrap a binary outside `bin` and `libexec` directories. {#ssec-gnome-common-issues-weird-location}
You can manually trigger the wrapping with `wrapGApp` in `preFixup` phase. It takes a path to a program as a first argument; the remaining arguments are passed directly to [`wrapProgram`](#fun-wrapProgram) function. You can manually trigger the wrapping with `wrapGApp` in `preFixup` phase. It takes a path to a program as a first argument; the remaining arguments are passed directly to [`wrapProgram`](#fun-wrapProgram) function.

View file

@ -19,7 +19,7 @@ In the following is an example expression using `buildGoModule`, the following a
To avoid updating this field when dependencies change, run `go mod vendor` in your source repo and set `vendorHash = null;` 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)). 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. - `proxyVendor`: Fetches (go mod download) and proxies the vendor directory. This is useful if your code depends on c code and go mod tidy does not include the needed sources to build or if any dependency has case-insensitive conflicts which will produce platform-dependent `vendorHash` checksums.
- `modPostBuild`: Shell commands to run after the build of the go-modules executes `go mod vendor`, and before calculating fixed output derivation's `vendorHash` (or `vendorSha256`). Note that if you change this attribute, you need to update `vendorHash` (or `vendorSha256`) attribute. - `modPostBuild`: Shell commands to run after the build of the go-modules executes `go mod vendor`, and before calculating fixed output derivation's `vendorHash` (or `vendorSha256`). Note that if you change this attribute, you need to update `vendorHash` (or `vendorSha256`) attribute.
```nix ```nix

View file

@ -23,7 +23,7 @@ installing and using them.
All of these packages are originally defined in the `haskellPackages` package All of these packages are originally defined in the `haskellPackages` package
set and are re-exposed with a reduced dependency closure for convenience. set and are re-exposed with a reduced dependency closure for convenience.
(see `justStaticExecutables` below) (see `justStaticExecutables` or `separateBinOutput` below)
The `haskellPackages` set includes at least one version of every package from The `haskellPackages` set includes at least one version of every package from
Hackage as well as some manually injected packages. This amounts to a lot of Hackage as well as some manually injected packages. This amounts to a lot of
@ -45,16 +45,17 @@ The attribute names in `haskellPackages` always correspond with their name on
Hackage. Since Hackage allows names that are not valid Nix without escaping, Hackage. Since Hackage allows names that are not valid Nix without escaping,
you need to take care when handling attribute names like `3dmodels`. you need to take care when handling attribute names like `3dmodels`.
For packages that are part of [Stackage], we use the version prescribed by a For packages that are part of [Stackage] (a curated set of known to be
Stackage solver (usually the current LTS one) as the default version. For all compatible packages), we use the version prescribed by a Stackage snapshot
other packages we use the latest version from Hackage. See (usually the current LTS one) as the default version. For all other packages we
[below](#haskell-available-versions) to learn which versions are provided use the latest version from [Hackage](https://hackage.org) (the repository of
exactly. basically all open source Haskell packages). See [below](#haskell-available-
versions) for a few more details on this.
Roughly half of the 16K packages contained in `haskellPackages` don't actually Roughly half of the 16K packages contained in `haskellPackages` dont actually
build and are marked as broken semi-automatically. Most of those packages are build and are [marked as broken semi-automatically](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/broken.yaml).
deprecated or unmaintained, but sometimes packages that should build, do not Most of those packages are deprecated or unmaintained, but sometimes packages
build. Very often fixing them is not a lot of work. that should build, do not build. Very often fixing them is not a lot of work.
<!-- <!--
TODO(@sternenseemann): TODO(@sternenseemann):
@ -126,19 +127,23 @@ Every package set also re-exposes the GHC used to build its packages as `haskell
### Available package versions {#haskell-available-versions} ### Available package versions {#haskell-available-versions}
We aim for a “blessed” package set which only contains one version of each We aim for a “blessed” package set which only contains one version of each
package, like Stackage (and based on it) but with more packages. Normally in package, like [Stackage], which is a curated set of known to be compatible
nixpkgs the number of building Haskell packages is roughly two to three times packages. We use the version information from Stackage snapshots and extend it
the size of Stackage. For choosing the version to use for a certain package we with more packages. Normally in Nixpkgs the number of building Haskell packages
use the following rules: is roughly two to three times the size of Stackage. For choosing the version to
use for a certain package we use the following rules:
1. By default, for every package `haskellPackages.foo` is the newest version 1. By default, for `haskellPackages.foo` is the newest version of the package
found on Hackage (at the time of the last update of our package set). `foo` found on [Hackage](https://hackage.org), which is the central registry
2. If the Stackage snapshot that we use (usually the newest LTS snapshot) of all open source Haskell packages. Nixpkgs contains a reference to a pinned
contains a package, we use the Stackage version as default version for that Hackage snapshot, thus we use the state of Hackage as of the last time we
package. updated this pin.
3. For some packages, which are not on Stackage, we have manual overrides to 2. If the [Stackage] snapshot that we use (usually the newest LTS snapshot)
set the default version to a version older than the newest on Hackage. We do contains a package, [we use instead the version in the Stackage snapshot as
this to get them or their reverse dependencies to compile in our package set. default version for that package.](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/stackage.yaml)
3. For some packages, which are not on Stackage, we have if necessary [manual
overrides to set the default version to a version older than the newest on
Hackage.](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/main.yaml)
4. For all packages, for which the newest Hackage version is not the default 4. For all packages, for which the newest Hackage version is not the default
version, there will also be a `haskellPackages.foo_x_y_z` package with the version, there will also be a `haskellPackages.foo_x_y_z` package with the
newest version. The `x_y_z` part encodes the version with dots replaced by newest version. The `x_y_z` part encodes the version with dots replaced by
@ -146,9 +151,12 @@ underscores. When the newest version changes by a new release to Hackage the
old package will disappear under that name and be replaced by a newer one under old package will disappear under that name and be replaced by a newer one under
the name with the new version. The package name including the version will the name with the new version. The package name including the version will
also disappear when the default version e.g. from Stackage catches up with the also disappear when the default version e.g. from Stackage catches up with the
newest version from Hackage. newest version from Hackage. E.g. if `haskellPackages.foo` gets updated from
5. For some packages, we also manually add other `haskellPackages.foo_x_y_z` 1.0.0 to 1.1.0 the package `haskellPackages.foo_1_1_0` becomes obsolete and
versions, if they are required for a certain build. gets dropped.
5. For some packages, we also [manually add other `haskellPackages.foo_x_y_z`
versions](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/main.yaml),
if they are required for a certain build.
Relying on `haskellPackages.foo_x_y_z` attributes in derivations outside Relying on `haskellPackages.foo_x_y_z` attributes in derivations outside
nixpkgs is discouraged because they may change or disappear with every package nixpkgs is discouraged because they may change or disappear with every package
@ -276,6 +284,15 @@ Defaults to `true`.
: Whether to generate an index for interactive navigation of the HTML documentation. : Whether to generate an index for interactive navigation of the HTML documentation.
Defaults to `true` if supported. Defaults to `true` if supported.
`doInstallIntermediates`
: Whether to install intermediate build products (files written to `dist/build`
by GHC during the build process). With `enableSeparateIntermediatesOutput`,
these files are instead installed to [a separate `intermediates`
output.][multiple-outputs] The output can then be passed into a future build of
the same package with the `previousIntermediates` argument to support
incremental builds. See [“Incremental builds”](#haskell-incremental-builds) for
more information. Defaults to `false`.
`enableLibraryProfiling` `enableLibraryProfiling`
: Whether to enable [profiling][profiling] for libraries contained in the : Whether to enable [profiling][profiling] for libraries contained in the
package. Enabled by default if supported. package. Enabled by default if supported.
@ -371,6 +388,12 @@ Defaults to `false`.
: Whether to install documentation to a separate `doc` output. : Whether to install documentation to a separate `doc` output.
Is automatically enabled if `doHaddock` is `true`. Is automatically enabled if `doHaddock` is `true`.
`enableSeparateIntermediatesOutput`
: When `doInstallIntermediates` is true, whether to install intermediate build
products to a separate `intermediates` output. See [“Incremental
builds”](#haskell-incremental-builds) for more information. Defaults to
`false`.
`allowInconsistentDependencies` `allowInconsistentDependencies`
: If enabled, allow multiple versions of the same Haskell package in the : If enabled, allow multiple versions of the same Haskell package in the
dependency tree at configure time. Often in such a situation compilation would dependency tree at configure time. Often in such a situation compilation would
@ -381,6 +404,11 @@ later fail because of type mismatches. Defaults to `false`.
when loading the library in the REPL, but requires extra build time and when loading the library in the REPL, but requires extra build time and
disk space. Defaults to `false`. disk space. Defaults to `false`.
`previousIntermediates`
: If non-null, intermediate build artifacts are copied from this input to
`dist/build` before performing compiling. See [“Incremental
builds”](#haskell-incremental-builds) for more information. Defaults to `null`.
`buildTarget` `buildTarget`
: Name of the executable or library to build and install. : Name of the executable or library to build and install.
If unset, all available targets are built and installed. If unset, all available targets are built and installed.
@ -496,6 +524,54 @@ the [Meta-attributes section](#chap-meta) for their documentation.
* `broken` * `broken`
* `hydraPlatforms` * `hydraPlatforms`
### Incremental builds {#haskell-incremental-builds}
`haskellPackages.mkDerivation` supports incremental builds for GHC 9.4 and
newer with the `doInstallIntermediates`, `enableSeparateIntermediatesOutput`,
and `previousIntermediates` arguments.
The basic idea is to first perform a full build of the package in question,
save its intermediate build products for later, and then copy those build
products into the build directory of an incremental build performed later.
Then, GHC will use those build artifacts to avoid recompiling unchanged
modules.
For more detail on how to store and use incremental build products, see
[Gabriella Gonzalez blog post “Nixpkgs support for incremental Haskell
builds”.][incremental-builds] motivation behind this feature.
An incremental build for [the `turtle` package][turtle] can be performed like
so:
```nix
let
pkgs = import <nixpkgs> {};
inherit (pkgs) haskell;
inherit (haskell.lib.compose) overrideCabal;
# Incremental builds work with GHC >=9.4.
turtle = haskell.packages.ghc944.turtle;
# This will do a full build of `turtle`, while writing the intermediate build products
# (compiled modules, etc.) to the `intermediates` output.
turtle-full-build-with-incremental-output = overrideCabal (drv: {
doInstallIntermediates = true;
enableSeparateIntermediatesOutput = true;
}) turtle;
# This will do an incremental build of `turtle` by copying the previously
# compiled modules and intermediate build products into the source tree
# before running the build.
#
# GHC will then naturally pick up and reuse these products, making this build
# complete much more quickly than the previous one.
turtle-incremental-build = overrideCabal (drv: {
previousIntermediates = turtle-full-build-with-incremental-output.intermediates;
}) turtle;
in
turtle-incremental-build
```
## Development environments {#haskell-development-environments} ## Development environments {#haskell-development-environments}
In addition to building and installing Haskell software, nixpkgs can also In addition to building and installing Haskell software, nixpkgs can also
@ -989,7 +1065,7 @@ benchmark component.
`dontBenchmark drv` `dontBenchmark drv`
: Set `doBenchmark` to `false` for `drv`. : Set `doBenchmark` to `false` for `drv`.
`setBuildTargets list drv` `setBuildTargets drv list`
: Sets the `buildTarget` argument for `drv` so that the targets specified in `list` are built. : Sets the `buildTarget` argument for `drv` so that the targets specified in `list` are built.
`doCoverage drv` `doCoverage drv`
@ -998,6 +1074,18 @@ benchmark component.
`dontCoverage drv` `dontCoverage drv`
: Sets the `doCoverage` argument to `false` for `drv`. : Sets the `doCoverage` argument to `false` for `drv`.
`enableExecutableProfiling drv`
: Sets the `enableExecutableProfiling` argument to `true` for `drv`.
`disableExecutableProfiling drv`
: Sets the `enableExecutableProfiling` argument to `false` for `drv`.
`enableLibraryProfiling drv`
: Sets the `enableLibraryProfiling` argument to `true` for `drv`.
`disableLibraryProfiling drv`
: Sets the `enableLibraryProfiling` argument to `false` for `drv`.
#### Library functions in the Haskell package sets {#haskell-package-set-lib-functions} #### Library functions in the Haskell package sets {#haskell-package-set-lib-functions}
Some library functions depend on packages from the Haskell package sets. Thus they are Some library functions depend on packages from the Haskell package sets. Thus they are
@ -1072,6 +1160,124 @@ covered in the old [haskell4nix docs](https://haskell4nix.readthedocs.io/).
If you feel any important topic is not documented at all, feel free to comment If you feel any important topic is not documented at all, feel free to comment
on the issue linked above. on the issue linked above.
### How to enable or disable profiling builds globally? {#haskell-faq-override-profiling}
By default, Nixpkgs builds a profiling version of each Haskell library. The
exception to this rule are some platforms where it is disabled due to concerns
over output size. You may want to…
* …enable profiling globally so that you can build a project you are working on
with profiling ability giving you insight in the time spent across your code
and code you depend on using [GHC's profiling feature][profiling].
* …disable profiling (globally) to reduce the time spent building the profiling
versions of libraries which a significant amount of build time is spent on
(although they are not as expensive as the “normal” build of a Haskell library).
::: {.note}
The method described below affects the build of all libraries in the
respective Haskell package set as well as GHC. If your choices differ from
Nixpkgs' default for your (host) platform, you will lose the ability to
substitute from the official binary cache.
If you are concerned about build times and thus want to disable profiling, it
probably makes sense to use `haskell.lib.compose.disableLibraryProfiling` (see
[](#haskell-trivial-helpers)) on the packages you are building locally while
continuing to substitute their dependencies and GHC.
:::
Since we need to change the profiling settings for the desired Haskell package
set _and_ GHC (as the core libraries like `base`, `filepath` etc. are bundled
with GHC), it is recommended to use overlays for Nixpkgs to change them.
Since the interrelated parts, i.e. the package set and GHC, are connected
via the Nixpkgs fixpoint, we need to modify them both in a way that preserves
their connection (or else we'd have to wire it up again manually). This is
achieved by changing GHC and the package set in seperate overlays to prevent
the package set from pulling in GHC from `prev`.
The result is two overlays like the ones shown below. Adjustable parts are
annotated with comments, as are any optional or alternative ways to achieve
the desired profiling settings without causing too many rebuilds.
<!-- TODO(@sternenseemann): buildHaskellPackages != haskellPackages with this overlay,
affected by https://github.com/NixOS/nixpkgs/issues/235960 which needs to be fixed
properly still.
-->
```nix
let
# Name of the compiler and package set you want to change. If you are using
# the default package set `haskellPackages`, you need to look up what version
# of GHC it currently uses (note that this is subject to change).
ghcName = "ghc92";
# Desired new setting
enableProfiling = true;
in
[
# The first overlay modifies the GHC derivation so that it does or does not
# build profiling versions of the core libraries bundled with it. It is
# recommended to only use such an overlay if you are enabling profiling on a
# platform that doesn't by default, because compiling GHC from scratch is
# quite expensive.
(final: prev:
let
inherit (final) lib;
in
{
haskell = lib.recursiveUpdate prev.haskell {
compiler.${ghcName} = prev.haskell.compiler.${ghcName}.override {
# Unfortunately, the GHC setting is named differently for historical reasons
enableProfiledLibs = enableProfiling;
};
};
})
(final: prev:
let
inherit (final) lib;
haskellLib = final.haskell.lib.compose;
in
{
haskell = lib.recursiveUpdate prev.haskell {
packages.${ghcName} = prev.haskell.packages.${ghcName}.override {
overrides = hfinal: hprev: {
mkDerivation = args: hprev.mkDerivation (args // {
# Since we are forcing our ideas upon mkDerivation, this change will
# affect every package in the package set.
enableLibraryProfiling = enableProfiling;
# To actually use profiling on an executable, executable profiling
# needs to be enabled for the executable you want to profile. You
# can either do this globally or…
enableExecutableProfiling = enableProfiling;
});
# …only for the package that contains an executable you want to profile.
# That saves on unnecessary rebuilds for packages that you only depend
# on for their library, but also contain executables (e.g. pandoc).
my-executable = haskellLib.enableExecutableProfiling hprev.my-executable;
# If you are disabling profiling to save on build time, but want to
# retain the ability to substitute from the binary cache. Drop the
# override for mkDerivation above and instead have an override like
# this for the specific packages you are building locally and want
# to make cheaper to build.
my-library = haskellLib.disableLibraryProfiling hprev.my-library;
};
};
};
})
]
```
<!-- TODO(@sternenseemann): write overriding mkDerivation, overriding GHC, and
overriding the entire package set sections and link to them from here where
relevant.
-->
[Stackage]: https://www.stackage.org [Stackage]: https://www.stackage.org
[cabal-project-files]: https://cabal.readthedocs.io/en/latest/cabal-project.html [cabal-project-files]: https://cabal.readthedocs.io/en/latest/cabal-project.html
[cabal2nix]: https://github.com/nixos/cabal2nix [cabal2nix]: https://github.com/nixos/cabal2nix
@ -1083,8 +1289,11 @@ on the issue linked above.
[haskell.nix]: https://input-output-hk.github.io/haskell.nix/index.html [haskell.nix]: https://input-output-hk.github.io/haskell.nix/index.html
[HLS user guide]: https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-editor [HLS user guide]: https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-editor
[hoogle]: https://wiki.haskell.org/Hoogle [hoogle]: https://wiki.haskell.org/Hoogle
[incremental-builds]: https://www.haskellforall.com/2022/12/nixpkgs-support-for-incremental-haskell.html
[jailbreak-cabal]: https://github.com/NixOS/jailbreak-cabal/ [jailbreak-cabal]: https://github.com/NixOS/jailbreak-cabal/
[multiple-outputs]: https://nixos.org/manual/nixpkgs/stable/#chap-multiple-output
[optparse-applicative-completions]: https://github.com/pcapriotti/optparse-applicative/blob/7726b63796aa5d0df82e926d467f039b78ca09e2/README.md#bash-zsh-and-fish-completions [optparse-applicative-completions]: https://github.com/pcapriotti/optparse-applicative/blob/7726b63796aa5d0df82e926d467f039b78ca09e2/README.md#bash-zsh-and-fish-completions
[profiling-detail]: https://cabal.readthedocs.io/en/latest/cabal-project.html#cfg-field-profiling-detail [profiling-detail]: https://cabal.readthedocs.io/en/latest/cabal-project.html#cfg-field-profiling-detail
[profiling]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html [profiling]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html
[search.nixos.org]: https://search.nixos.org [search.nixos.org]: https://search.nixos.org
[turtle]: https://hackage.haskell.org/package/turtle

View file

@ -0,0 +1,45 @@
# Languages and frameworks {#chap-language-support}
The [standard build environment](#chap-stdenv) 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 `stdenv`. 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.
```{=include=} sections
agda.section.md
android.section.md
beam.section.md
bower.section.md
chicken.section.md
coq.section.md
crystal.section.md
cuda.section.md
cuelang.section.md
dart.section.md
dhall.section.md
dotnet.section.md
emscripten.section.md
gnome.section.md
go.section.md
haskell.section.md
hy.section.md
idris.section.md
ios.section.md
java.section.md
javascript.section.md
lisp.section.md
lua.section.md
maven.section.md
nim.section.md
ocaml.section.md
octave.section.md
perl.section.md
php.section.md
pkg-config.section.md
python.section.md
qt.section.md
r.section.md
ruby.section.md
rust.section.md
swift.section.md
texlive.section.md
titanium.section.md
vim.section.md
```

View file

@ -1,47 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
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 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" />
<xi:include href="beam.section.xml" />
<xi:include href="bower.section.xml" />
<xi:include href="chicken.section.xml" />
<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="dart.section.xml" />
<xi:include href="dhall.section.xml" />
<xi:include href="dotnet.section.xml" />
<xi:include href="emscripten.section.xml" />
<xi:include href="gnome.section.xml" />
<xi:include href="go.section.xml" />
<xi:include href="haskell.section.xml" />
<xi:include href="hy.section.xml" />
<xi:include href="idris.section.xml" />
<xi:include href="ios.section.xml" />
<xi:include href="java.section.xml" />
<xi:include href="javascript.section.xml" />
<xi:include href="lisp.section.xml" />
<xi:include href="lua.section.xml" />
<xi:include href="maven.section.xml" />
<xi:include href="nim.section.xml" />
<xi:include href="ocaml.section.xml" />
<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" />
<xi:include href="ruby.section.xml" />
<xi:include href="rust.section.xml" />
<xi:include href="swift.section.xml" />
<xi:include href="texlive.section.xml" />
<xi:include href="titanium.section.xml" />
<xi:include href="vim.section.xml" />
</chapter>

View file

@ -104,7 +104,7 @@ The above function takes a variety of parameters:
and the location where the source code resides and the location where the source code resides
* `sdkVersion` specifies which version of the iOS SDK to use. * `sdkVersion` specifies which version of the iOS SDK to use.
It also possile to adjust the `xcodebuild` parameters. This is only needed in It also possible to adjust the `xcodebuild` parameters. This is only needed in
rare circumstances. In most cases the default values should suffice: rare circumstances. In most cases the default values should suffice:
* Specifies which `xcodebuild` target to build. By default it takes the target * Specifies which `xcodebuild` target to build. By default it takes the target
@ -130,7 +130,7 @@ In addition, you need to set the following parameters:
store certificates. store certificates.
* `generateIPA` specifies that we want to produce an IPA file (this is probably * `generateIPA` specifies that we want to produce an IPA file (this is probably
what you want) what you want)
* `generateXCArchive` specifies thet we want to produce an xcarchive file. * `generateXCArchive` specifies that we want to produce an xcarchive file.
When building IPA files on Hydra and when it is desired to allow iOS devices to When building IPA files on Hydra and when it is desired to allow iOS devices to
install IPAs by browsing to the Hydra build products page, you can enable the install IPAs by browsing to the Hydra build products page, you can enable the

View file

@ -143,7 +143,7 @@ To update NPM packages in nixpkgs, run the same `generate.sh` script:
#### Git protocol error {#javascript-git-error} #### Git protocol error {#javascript-git-error}
Some packages may have Git dependencies from GitHub specified with `git://`. Some packages may have Git dependencies from GitHub specified with `git://`.
GitHub has [disabled unecrypted Git connections](https://github.blog/2021-09-01-improving-git-protocol-security-github/#no-more-unauthenticated-git), so you may see the following error when running the generate script: GitHub has [disabled unencrypted Git connections](https://github.blog/2021-09-01-improving-git-protocol-security-github/#no-more-unauthenticated-git), so you may see the following error when running the generate script:
``` ```
The unauthenticated git protocol on port 9418 is no longer supported The unauthenticated git protocol on port 9418 is no longer supported
@ -196,10 +196,14 @@ buildNpmPackage rec {
* `npmDepsHash`: The output hash of the dependencies for this project. Can be calculated in advance with [`prefetch-npm-deps`](#javascript-buildNpmPackage-prefetch-npm-deps). * `npmDepsHash`: The output hash of the dependencies for this project. Can be calculated in advance with [`prefetch-npm-deps`](#javascript-buildNpmPackage-prefetch-npm-deps).
* `makeCacheWritable`: Whether to make the cache writable prior to installing dependencies. Don't set this unless npm tries to write to the cache directory, as it can slow down the build. * `makeCacheWritable`: Whether to make the cache writable prior to installing dependencies. Don't set this unless npm tries to write to the cache directory, as it can slow down the build.
* `npmBuildScript`: The script to run to build the project. Defaults to `"build"`. * `npmBuildScript`: The script to run to build the project. Defaults to `"build"`.
* `npmWorkspace`: The workspace directory within the project to build and install.
* `dontNpmBuild`: Option to disable running the build script. Set to `true` if the package does not have a build script. Defaults to `false`. Alternatively, setting `buildPhase` explicitly also disables this.
* `dontNpmInstall`: Option to disable running `npm install`. Defaults to `false`. Alternatively, setting `installPhase` explicitly also disables this.
* `npmFlags`: Flags to pass to all npm commands. * `npmFlags`: Flags to pass to all npm commands.
* `npmInstallFlags`: Flags to pass to `npm ci` and `npm prune`. * `npmInstallFlags`: Flags to pass to `npm ci`.
* `npmBuildFlags`: Flags to pass to `npm run ${npmBuildScript}`. * `npmBuildFlags`: Flags to pass to `npm run ${npmBuildScript}`.
* `npmPackFlags`: Flags to pass to `npm pack`. * `npmPackFlags`: Flags to pass to `npm pack`.
* `npmPruneFlags`: Flags to pass to `npm prune`. Defaults to the value of `npmInstallFlags`.
#### prefetch-npm-deps {#javascript-buildNpmPackage-prefetch-npm-deps} #### prefetch-npm-deps {#javascript-buildNpmPackage-prefetch-npm-deps}

View file

@ -179,7 +179,7 @@ Each interpreter has the following attributes:
#### `buildLuarocksPackage` function {#buildluarockspackage-function} #### `buildLuarocksPackage` function {#buildluarockspackage-function}
The `buildLuarocksPackage` function is implemented in `pkgs/development/interpreters/lua-5/build-lua-package.nix` The `buildLuarocksPackage` function is implemented in `pkgs/development/interpreters/lua-5/build-luarocks-package.nix`
The following is an example: The following is an example:
```nix ```nix
luaposix = buildLuarocksPackage { luaposix = buildLuarocksPackage {

View file

@ -165,6 +165,39 @@ The build will fail, and tell you the expected `outputHash` to place. When you'v
If your package uses _SNAPSHOT_ dependencies or _version ranges_; there is a strong likelihood that over-time your output hash will change since the resolved dependencies may change. Hence this method is less recommended then using `buildMaven`. If your package uses _SNAPSHOT_ dependencies or _version ranges_; there is a strong likelihood that over-time your output hash will change since the resolved dependencies may change. Hence this method is less recommended then using `buildMaven`.
#### Stable Maven plugins {#stable-maven-plugins}
Maven defines default versions for its core plugins, e.g. `maven-compiler-plugin`.
If your project does not override these versions, an upgrade of Maven will change the version of the used plugins.
This changes the output of the first invocation and the plugins required by the second invocation.
However, since a hash is given for the output of the first invocation, the second invocation will simply fail
because the requested plugins are missing.
This will prevent automatic upgrades of Maven: the manual fix for this is to change the hash of the first invocation.
To make sure that your package does not add manual effort when upgrading Maven, explicitly define versions for all
plugins. You can check if this is the case by adding the following plugin to your (parent) POM:
```xml
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>3.3.0</version>
<executions>
<execution>
<id>enforce-plugin-versions</id>
<goals>
<goal>enforce</goal>
</goals>
<configuration>
<rules>
<requirePluginVersions />
</rules>
</configuration>
</execution>
</executions>
</plugin>
```
## Building a JAR {#building-a-jar} ## Building a JAR {#building-a-jar}
Regardless of which strategy is chosen above, the step to build the derivation is the same. Regardless of which strategy is chosen above, the step to build the derivation is the same.

View file

@ -15,32 +15,23 @@ case of packages not containing exported library code the attribute
The following example shows a Nim program that depends only on Nim libraries: The following example shows a Nim program that depends only on Nim libraries:
```nix ```nix
{ lib, nimPackages, fetchurl }: { lib, nimPackages, fetchFromGitHub }:
nimPackages.buildNimPackage rec {
pname = "hottext";
version = "1.4";
nimPackages.buildNimPackage (finalAttrs: {
pname = "ttop";
version = "1.0.1";
nimBinOnly = true; nimBinOnly = true;
src = fetchurl { src = fetchFromGitHub {
url = "https://git.sr.ht/~ehmry/hottext/archive/v${version}.tar.gz"; owner = "inv2004";
hash = "sha256-hIUofi81zowSMbt1lUsxCnVzfJGN3FEiTtN8CEFpwzY="; repo = "ttop";
rev = "v${finalAttrs.version}";
hash = "sha256-x4Uczksh6p3XX/IMrOFtBxIleVHdAPX9e8n32VAUTC4=";
}; };
buildInputs = with nimPackages; [ buildInputs = with nimPackages; [ asciigraph illwill parsetoml zippy ];
bumpy
chroma
flatty
nimsimd
pixie
sdl2
typography
vmath
zippy
];
}
})
``` ```
## Nim library packages in Nixpkgs {#nim-library-packages-in-nixpkgs} ## Nim library packages in Nixpkgs {#nim-library-packages-in-nixpkgs}
@ -60,15 +51,15 @@ non-Nim package:
```nix ```nix
{ lib, buildNimPackage, fetchNimble, SDL2 }: { lib, buildNimPackage, fetchNimble, SDL2 }:
buildNimPackage rec { buildNimPackage (finalAttrs: {
pname = "sdl2"; pname = "sdl2";
version = "2.0.4"; version = "2.0.4";
src = fetchNimble { src = fetchNimble {
inherit pname version; inherit (finalAttrs) pname version;
hash = "sha256-qDtVSnf+7rTq36WAxgsUZ8XoUk4sKwHyt8EJcY5WP+o="; hash = "sha256-Vtcj8goI4zZPQs2TbFoBFlcR5UqDtOldaXSH/+/xULk=";
}; };
propagatedBuildInputs = [ SDL2 ]; propagatedBuildInputs = [ SDL2 ];
} })
``` ```
## `buildNimPackage` parameters {#buildnimpackage-parameters} ## `buildNimPackage` parameters {#buildnimpackage-parameters}

View file

@ -22,7 +22,7 @@ NixOS - not necessarily the latest major release from upstream.
All available PHP attributes are wrappers around their respective All available PHP attributes are wrappers around their respective
binary PHP package and provide commonly used extensions this way. The binary PHP package and provide commonly used extensions this way. The
real PHP 7.4 package, i.e. the unwrapped one, is available as real PHP 8.1 package, i.e. the unwrapped one, is available as
`php81.unwrapped`; see the next section for more details. `php81.unwrapped`; see the next section for more details.
Interactive tools built on PHP are put in `php.packages`; composer is Interactive tools built on PHP are put in `php.packages`; composer is

View file

@ -512,9 +512,10 @@ when building the bindings and are therefore added as `buildInputs`.
```nix ```nix
{ lib { lib
, pkgs
, buildPythonPackage , buildPythonPackage
, fetchPypi , fetchPypi
, libxml2
, libxslt
}: }:
buildPythonPackage rec { buildPythonPackage rec {
@ -528,8 +529,8 @@ buildPythonPackage rec {
}; };
buildInputs = [ buildInputs = [
pkgs.libxml2 libxml2
pkgs.libxslt libxslt
]; ];
meta = with lib; { meta = with lib; {
@ -554,11 +555,13 @@ therefore we have to set `LDFLAGS` and `CFLAGS`.
```nix ```nix
{ lib { lib
, pkgs
, buildPythonPackage , buildPythonPackage
, fetchPypi , fetchPypi
# dependencies # dependencies
, fftw
, fftwFloat
, fftwLongDouble
, numpy , numpy
, scipy , scipy
}: }:
@ -574,9 +577,9 @@ buildPythonPackage rec {
}; };
buildInputs = [ buildInputs = [
pkgs.fftw fftw
pkgs.fftwFloat fftwFloat
pkgs.fftwLongDouble fftwLongDouble
]; ];
propagatedBuildInputs = [ propagatedBuildInputs = [
@ -585,8 +588,8 @@ buildPythonPackage rec {
]; ];
preConfigure = '' preConfigure = ''
export LDFLAGS="-L${pkgs.fftw.dev}/lib -L${pkgs.fftwFloat.out}/lib -L${pkgs.fftwLongDouble.out}/lib" export LDFLAGS="-L${fftw.dev}/lib -L${fftwFloat.out}/lib -L${fftwLongDouble.out}/lib"
export CFLAGS="-I${pkgs.fftw.dev}/include -I${pkgs.fftwFloat.dev}/include -I${pkgs.fftwLongDouble.dev}/include" export CFLAGS="-I${fftw.dev}/include -I${fftwFloat.dev}/include -I${fftwLongDouble.dev}/include"
''; '';
# Tests cannot import pyfftw. pyfftw works fine though. # Tests cannot import pyfftw. pyfftw works fine though.
@ -995,7 +998,7 @@ and in this case the `python3` interpreter is automatically used.
### Interpreters {#interpreters} ### Interpreters {#interpreters}
Versions 2.7, 3.8, 3.9, 3.10 and 3.11 of the CPython interpreter are available Versions 2.7, 3.8, 3.9, 3.10 and 3.11 of the CPython interpreter are available
as respectively `python27`, python38`, `python39`, `python310` and `python311`. as respectively `python27`, `python38`, `python39`, `python310` and `python311`.
The aliases `python2` and `python3` correspond to respectively `python27` and The aliases `python2` and `python3` correspond to respectively `python27` and
`python310`. The attribute `python` maps to `python2`. The PyPy interpreters `python310`. The attribute `python` maps to `python2`. The PyPy interpreters
compatible with Python 2.7 and 3 are available as `pypy27` and `pypy3`, with compatible with Python 2.7 and 3 are available as `pypy27` and `pypy3`, with
@ -1514,10 +1517,6 @@ Note: There is a boolean value `lib.inNixShell` set to `true` if nix-shell is in
Packages inside nixpkgs are written by hand. However many tools exist in Packages inside nixpkgs are written by hand. However many tools exist in
community to help save time. No tool is preferred at the moment. community to help save time. No tool is preferred at the moment.
- [pypi2nix](https://github.com/nix-community/pypi2nix): Generate Nix
expressions for your Python project. Note that [sharing derivations from
pypi2nix with nixpkgs is possible but not
encouraged](https://github.com/nix-community/pypi2nix/issues/222#issuecomment-443497376).
- [nixpkgs-pytools](https://github.com/nix-community/nixpkgs-pytools) - [nixpkgs-pytools](https://github.com/nix-community/nixpkgs-pytools)
- [poetry2nix](https://github.com/nix-community/poetry2nix) - [poetry2nix](https://github.com/nix-community/poetry2nix)

View file

@ -10,37 +10,22 @@ pure and explicit at build-time, at the cost of introducing an extra indirection
## Nix expression for a Qt package (default.nix) {#qt-default-nix} ## Nix expression for a Qt package (default.nix) {#qt-default-nix}
```{=docbook} ```nix
<programlisting> { stdenv, lib, qtbase, wrapQtAppsHook }:
{ stdenv, lib, qtbase, wrapQtAppsHook }: <co xml:id='qt-default-nix-co-1' />
stdenv.mkDerivation { stdenv.mkDerivation {
pname = "myapp"; pname = "myapp";
version = "1.0"; version = "1.0";
buildInputs = [ qtbase ]; buildInputs = [ qtbase ];
nativeBuildInputs = [ wrapQtAppsHook ]; <co xml:id='qt-default-nix-co-2' /> nativeBuildInputs = [ wrapQtAppsHook ];
} }
</programlisting>
<calloutlist>
<callout arearefs='qt-default-nix-co-1'>
<para>
Import Qt modules directly, that is: <literal>qtbase</literal>, <literal>qtdeclarative</literal>, etc.
<emphasis>Do not</emphasis> import Qt package sets such as <literal>qt5</literal>
because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
</para>
</callout>
<callout arearefs='qt-default-nix-co-2'>
<para>
All Qt packages must include <literal>wrapQtAppsHook</literal> in
<literal>nativeBuildInputs</literal>, or you must explicitly set
<literal>dontWrapQtApps</literal>.
</para>
</callout>
</calloutlist>
``` ```
It is important to import Qt modules directly, that is: `qtbase`, `qtdeclarative`, etc. *Do not* import Qt package sets such as `qt5` because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
Additionally all Qt packages must include `wrapQtAppsHook` in `nativeBuildInputs`, or you must explicitly set `dontWrapQtApps`.
## Locating runtime dependencies {#qt-runtime-dependencies} ## Locating runtime dependencies {#qt-runtime-dependencies}
Qt applications must be wrapped to find runtime dependencies. Qt applications must be wrapped to find runtime dependencies.

6
third_party/nixpkgs/doc/lib.md vendored Normal file
View file

@ -0,0 +1,6 @@
# Nixpkgs `lib` {#id-1.4}
```{=include=} chapters
functions.md
module-system/module-system.chapter.md
```

14
third_party/nixpkgs/doc/manual.md.in vendored Normal file
View file

@ -0,0 +1,14 @@
# Nixpkgs Manual {#nixpkgs-manual}
## Version @MANUAL_VERSION@
```{=include=} chapters
preface.chapter.md
```
```{=include=} parts
using-nixpkgs.md
lib.md
stdenv.md
builders.md
contributing.md
```

View file

@ -1,49 +0,0 @@
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="nixpkgs-manual">
<info>
<title>Nixpkgs Manual</title>
<subtitle>Version <xi:include href=".version" parse="text" />
</subtitle>
</info>
<xi:include href="preface.chapter.xml" />
<part xml:id="part-using">
<title>Using Nixpkgs</title>
<xi:include href="using/configuration.chapter.xml" />
<xi:include href="using/overlays.chapter.xml" />
<xi:include href="using/overrides.chapter.xml" />
</part>
<part>
<title>Nixpkgs <code>lib</code></title>
<xi:include href="functions.xml" />
<xi:include href="module-system/module-system.chapter.xml" />
</part>
<part xml:id="part-stdenv">
<title>Standard environment</title>
<xi:include href="stdenv/stdenv.chapter.xml" />
<xi:include href="stdenv/meta.chapter.xml" />
<xi:include href="stdenv/multiple-output.chapter.xml" />
<xi:include href="stdenv/cross-compilation.chapter.xml" />
<xi:include href="stdenv/platform-notes.chapter.xml" />
</part>
<part xml:id="part-builders">
<title>Builders</title>
<xi:include href="builders/fetchers.chapter.xml" />
<xi:include href="builders/trivial-builders.chapter.xml" />
<xi:include href="builders/testers.chapter.xml" />
<xi:include href="builders/special.xml" />
<xi:include href="builders/images.xml" />
<xi:include href="hooks/index.xml" />
<xi:include href="languages-frameworks/index.xml" />
<xi:include href="builders/packages/index.xml" />
</part>
<part xml:id="part-contributing">
<title>Contributing to Nixpkgs</title>
<xi:include href="contributing/quick-start.chapter.xml" />
<xi:include href="contributing/coding-conventions.chapter.xml" />
<xi:include href="contributing/submitting-changes.chapter.xml" />
<xi:include href="contributing/vulnerability-roundup.chapter.xml" />
<xi:include href="contributing/reviewing-contributions.chapter.xml" />
<xi:include href="contributing/contributing-to-documentation.chapter.xml" />
</part>
</book>

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