Browse Source

Merge remote-tracking branch 'upstream/master' into js-unknown-ghcjs

nixos-unstable
John Ericson 2 years ago
parent
commit
c2b34b2b57
  1. 37
      .github/CODEOWNERS
  2. 3
      .github/ISSUE_TEMPLATE.md
  3. 37
      .github/ISSUE_TEMPLATE/bug_report.md
  4. 18
      .github/ISSUE_TEMPLATE/packaging_request.md
  5. 8
      .github/PULL_REQUEST_TEMPLATE.md
  6. 2
      .version
  7. 2
      COPYING
  8. 9
      README.md
  9. 7
      doc/.gitignore
  10. 52
      doc/Makefile
  11. 108
      doc/coding-conventions.xml
  12. 19
      doc/configuration.xml
  13. 14
      doc/contributing.xml
  14. 454
      doc/cross-compilation.xml
  15. 27
      doc/default.nix
  16. 45
      doc/doc-support/default.nix
  17. 2
      doc/doc-support/lib-function-docs.nix
  18. 0
      doc/doc-support/lib-function-locations.nix
  19. 14
      doc/doc-support/parameters.xml
  20. 2
      doc/functions.xml
  21. 118
      doc/functions/appimagetools.xml
  22. 112
      doc/functions/dockertools.xml
  23. 318
      doc/functions/fetchers.xml
  24. 7
      doc/functions/library.xml
  25. 40
      doc/functions/nix-gitignore.xml
  26. 30
      doc/functions/prefer-remote-fetch.xml
  27. 28
      doc/functions/snap/example-firefox.nix
  28. 12
      doc/functions/snap/example-hello.nix
  29. 74
      doc/functions/snaptools.xml
  30. 137
      doc/functions/trivial-builders.xml
  31. 9
      doc/languages-frameworks/android.section.md
  32. 254
      doc/languages-frameworks/beam.xml
  33. 71
      doc/languages-frameworks/crystal.section.md
  34. 289
      doc/languages-frameworks/go.xml
  35. 10
      doc/languages-frameworks/haskell.section.md
  36. 33
      doc/languages-frameworks/idris.section.md
  37. 1
      doc/languages-frameworks/index.xml
  38. 11
      doc/languages-frameworks/java.xml
  39. 2
      doc/languages-frameworks/lua.xml
  40. 66
      doc/languages-frameworks/ocaml.xml
  41. 41
      doc/languages-frameworks/perl.xml
  42. 214
      doc/languages-frameworks/python.section.md
  43. 225
      doc/languages-frameworks/qt.xml
  44. 6
      doc/languages-frameworks/rust.section.md
  45. 4
      doc/languages-frameworks/texlive.xml
  46. 170
      doc/languages-frameworks/vim.section.md
  47. 3
      doc/manual.xml
  48. 25
      doc/meta.xml
  49. 7
      doc/multiple-output.xml
  50. 455
      doc/package-notes.xml
  51. 482
      doc/package-specific-user-notes.xml
  52. 74
      doc/platform-notes.xml
  53. 28
      doc/quick-start.xml
  54. 33
      doc/reviewing-contributions.xml
  55. 677
      doc/stdenv.xml
  56. 27
      doc/submitting-changes.xml
  57. 10
      lib/default.nix
  58. 9
      lib/fixed-points.nix
  59. 2
      lib/generators.nix
  60. 21
      lib/licenses.nix
  61. 18
      lib/lists.nix
  62. 50
      lib/modules.nix
  63. 8
      lib/options.nix
  64. 24
      lib/sources.nix
  65. 2
      lib/strings.nix
  66. 31
      lib/systems/default.nix
  67. 18
      lib/systems/doubles.nix
  68. 49
      lib/systems/examples.nix
  69. 37
      lib/systems/for-meta.nix
  70. 4
      lib/systems/inspect.nix
  71. 123
      lib/systems/parse.nix
  72. 11
      lib/systems/platforms.nix
  73. 11
      lib/tests/modules.sh
  74. 9
      lib/tests/modules/alias-with-priority-can-override.nix
  75. 5
      lib/tests/modules/alias-with-priority.nix
  76. 5
      lib/tests/modules/declare-either.nix
  77. 9
      lib/tests/modules/declare-oneOf.nix
  78. 15
      lib/tests/release.nix
  79. 12
      lib/tests/systems.nix
  80. 7
      lib/trivial.nix
  81. 26
      lib/types.nix
  82. 1964
      maintainers/maintainer-list.nix
  83. 9
      maintainers/scripts/fetch-kde-qt.sh
  84. 100
      maintainers/scripts/luarocks-packages.csv
  85. 2
      maintainers/scripts/nixpkgs-lint.nix
  86. 36
      maintainers/scripts/update-discord
  87. 125
      maintainers/scripts/update-luarocks-packages
  88. 9
      maintainers/scripts/update-luarocks-shell.nix
  89. 25
      maintainers/scripts/update.nix
  90. 7
      nixos/doc/manual/Makefile
  91. 10
      nixos/doc/manual/administration/cleaning-store.xml
  92. 4
      nixos/doc/manual/administration/container-networking.xml
  93. 2
      nixos/doc/manual/administration/control-groups.xml
  94. 7
      nixos/doc/manual/administration/imperative-containers.xml
  95. 6
      nixos/doc/manual/administration/logging.xml
  96. 2
      nixos/doc/manual/administration/rollback.xml
  97. 2
      nixos/doc/manual/administration/running.xml
  98. 4
      nixos/doc/manual/administration/service-mgmt.xml
  99. 4
      nixos/doc/manual/administration/store-corruption.xml
  100. 4
      nixos/doc/manual/administration/user-sessions.xml

37
.github/CODEOWNERS

@ -47,8 +47,8 @@
/nixos/doc/manual/man-nixos-option.xml @nbp
/nixos/modules/installer/tools/nixos-option.sh @nbp
# NixOS modules
/nixos/modules @Infinisil
# New NixOS modules
/nixos/modules/module-list.nix @Infinisil
# Python-related code and docs
/maintainers/scripts/update-python-libraries @FRidh
@ -58,11 +58,11 @@
/doc/languages-frameworks/python.section.md @FRidh
# Haskell
/pkgs/development/compilers/ghc @peti @ryantm @basvandijk
/pkgs/development/haskell-modules @peti @ryantm @basvandijk
/pkgs/development/haskell-modules/default.nix @peti @ryantm @basvandijk
/pkgs/development/haskell-modules/generic-builder.nix @peti @ryantm @basvandijk
/pkgs/development/haskell-modules/hoogle.nix @peti @ryantm @basvandijk
/pkgs/development/compilers/ghc @basvandijk
/pkgs/development/haskell-modules @basvandijk
/pkgs/development/haskell-modules/default.nix @basvandijk
/pkgs/development/haskell-modules/generic-builder.nix @basvandijk
/pkgs/development/haskell-modules/hoogle.nix @basvandijk
# Perl
/pkgs/development/interpreters/perl @volth
@ -107,8 +107,8 @@
# Eclipse
/pkgs/applications/editors/eclipse @rycee
# https://github.com/NixOS/nixpkgs/issues/31401
/lib/licenses.nix @ghost
# Licenses
/lib/licenses.nix @alyssais
# Qt / KDE
/pkgs/applications/kde @ttuegel
@ -122,6 +122,14 @@
/nixos/modules/services/databases/postgresql.nix @thoughtpolice
/nixos/tests/postgresql.nix @thoughtpolice
# Hardened profile & related modules
/nixos/modules/profiles/hardened.nix @joachifm
/nixos/modules/security/hidepid.nix @joachifm
/nixos/modules/security/lock-kernel-modules.nix @joachifm
/nixos/modules/security/misc.nix @joachifm
/nixos/tests/hardened.nix @joachifm
/pkgs/os-specific/linux/kernel/hardened-config.nix @joachifm
# Dhall
/pkgs/development/dhall-modules @Gabriel439 @Profpatsch
/pkgs/development/interpreters/dhall @Gabriel439 @Profpatsch
@ -131,3 +139,14 @@
# Bazel
/pkgs/development/tools/build-managers/bazel @mboes @Profpatsch
# NixOS modules for e-mail and dns services
/nixos/modules/services/mail/mailman.nix @peti
/nixos/modules/services/mail/postfix.nix @peti
/nixos/modules/services/networking/bind.nix @peti
/nixos/modules/services/mail/rspamd.nix @peti
# Emacs
/pkgs/applications/editors/emacs-modes @adisbladis
/pkgs/applications/editors/emacs @adisbladis
/pkgs/top-level/emacs-packages.nix @adisbladis

3
.github/ISSUE_TEMPLATE.md

@ -8,5 +8,4 @@
## Technical details
Please run `nix-shell -p nix-info --run "nix-info -m"` and paste the
results.
Please run `nix run nixpkgs.nix-info -c nix-info -m` and paste the result.

37
.github/ISSUE_TEMPLATE/bug_report.md

@ -0,0 +1,37 @@
---
name: Bug report
about: Create a report to help us improve
title: ''
labels: '0.kind: bug'
assignees: ''
---
**Describe the bug**
A clear and concise description of what the bug is.
**To Reproduce**
Steps to reproduce the behavior:
1. ...
2. ...
3. ...
**Expected behavior**
A clear and concise description of what you expected to happen.
**Screenshots**
If applicable, add screenshots to help explain your problem.
**Additional context**
Add any other context about the problem here.
**Metadata**
Please run `nix run nixpkgs.nix-info -c nix-info -m` and paste the result.
Maintainer information:
```yaml
# a list of nixpkgs attributes affected by the problem
attribute:
# a list of nixos modules affected by the problem
module:
```

18
.github/ISSUE_TEMPLATE/packaging_request.md

@ -0,0 +1,18 @@
---
name: Packaging requests
about: For packages that are missing
title: ''
labels: '0.kind: packaging request'
assignees: ''
---
**Project description**
_describe the project a little_
**Metadata**
* homepage URL:
* source URL:
* license: mit, bsd, gpl2+ , ...
* platforms: unix, linux, darwin, ...

8
.github/PULL_REQUEST_TEMPLATE.md

@ -1,3 +1,4 @@
<!-- Nixpkgs has a lot of new incoming Pull Requests, but not enough people to review this constant stream. Even if you aren't a committer, we would appreciate reviews of other PRs, especially simple ones like package updates. Just testing the relevant package/service and leaving a comment saying what you tested, how you tested it and whether it worked would be great. List of open PRs: <https://github.com/NixOS/nixpkgs/pulls>, for more about reviewing contributions: <https://hydra.nixos.org/job/nixpkgs/trunk/manual/latest/download/1/nixpkgs/manual.html#sec-reviewing-contributions>. Reviewing isn't mandatory, but it would help out a lot and reduce the average time-to-merge for all of us. Thanks a lot if you do! -->
###### Motivation for this change
@ -11,11 +12,12 @@
- [ ] macOS
- [ ] other Linux distributions
- [ ] Tested via one or more NixOS test(s) if existing and applicable for the change (look inside [nixos/tests](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests))
- [ ] Tested compilation of all pkgs that depend on this change using `nix-shell -p nox --run "nox-review wip"`
- [ ] Tested compilation of all pkgs that depend on this change using `nix-shell -p nix-review --run "nix-review wip"`
- [ ] Tested execution of all binary files (usually in `./result/bin/`)
- [ ] Determined the impact on package closure size (by running `nix path-info -S` before and after)
- [ ] Assured whether relevant documentation is up to date
- [ ] Ensured that relevant documentation is up to date
- [ ] Fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/.github/CONTRIBUTING.md).
---
###### Notify maintainers
cc @

2
.version

@ -1 +1 @@
19.03
19.09

2
COPYING

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

9
README.md

@ -1,6 +1,7 @@
[<img src="https://nixos.org/logo/nixos-hires.png" width="500px" alt="logo" />](https://nixos.org/nixos)
[![Code Triagers Badge](https://www.codetriage.com/nixos/nixpkgs/badges/users.svg)](https://www.codetriage.com/nixos/nixpkgs)
[![Open Collective supporters](https://opencollective.com/nixos/tiers/supporter/badge.svg?label=Supporter&color=brightgreen)](https://opencollective.com/nixos)
Nixpkgs is a collection of packages for the [Nix](https://nixos.org/nix/) package
manager. It is periodically built and tested by the [Hydra](https://hydra.nixos.org/)
@ -12,12 +13,12 @@ build daemon as so-called channels. To get channel information via git, add
```
For stability and maximum binary package support, it is recommended to maintain
custom changes on top of one of the channels, e.g. `nixos-18.09` for the latest
custom changes on top of one of the channels, e.g. `nixos-19.03` for the latest
release and `nixos-unstable` for the latest successful build of master:
```
% git remote update channels
% git rebase channels/nixos-18.09
% git rebase channels/nixos-19.03
```
For pull requests, please rebase onto nixpkgs `master`.
@ -31,9 +32,9 @@ For pull requests, please rebase onto nixpkgs `master`.
* [Manual (NixOS)](https://nixos.org/nixos/manual/)
* [Community maintained wiki](https://nixos.wiki/)
* [Continuous package builds for unstable/master](https://hydra.nixos.org/jobset/nixos/trunk-combined)
* [Continuous package builds for 18.09 release](https://hydra.nixos.org/jobset/nixos/release-18.09)
* [Continuous package builds for 19.03 release](https://hydra.nixos.org/jobset/nixos/release-19.03)
* [Tests for unstable/master](https://hydra.nixos.org/job/nixos/trunk-combined/tested#tabs-constituents)
* [Tests for 18.09 release](https://hydra.nixos.org/job/nixos/release-18.09/tested#tabs-constituents)
* [Tests for 19.03 release](https://hydra.nixos.org/job/nixos/release-19.03/tested#tabs-constituents)
Communication:

7
doc/.gitignore

@ -1,7 +1,8 @@
*.chapter.xml
*.section.xml
.version
out
manual-full.xml
highlightjs
functions/library/generated
functions/library/locations.xml
highlightjs
manual-full.xml
out

52
doc/Makefile

@ -8,10 +8,10 @@ debug:
nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"
.PHONY: format
format:
format: doc-support/result
find . -iname '*.xml' -type f | while read f; do \
echo $$f ;\
xmlformat --config-file "$$XMLFORMAT_CONFIG" -i $$f ;\
xmlformat --config-file "doc-support/result/xmlformat.conf" -i $$f ;\
done
.PHONY: fix-misc-xml
@ -21,19 +21,19 @@ fix-misc-xml:
.PHONY: clean
clean:
rm -f ${MD_TARGETS} .version manual-full.xml functions/library/locations.xml functions/library/generated
rm -f ${MD_TARGETS} doc-support/result .version manual-full.xml functions/library/locations.xml functions/library/generated
rm -rf ./out/ ./highlightjs
.PHONY: validate
validate: manual-full.xml
jing "$$RNG" manual-full.xml
validate: manual-full.xml doc-support/result
jing doc-support/result/docbook.rng manual-full.xml
out/html/index.html: manual-full.xml style.css highlightjs
out/html/index.html: doc-support/result manual-full.xml style.css highlightjs
mkdir -p out/html
xsltproc ${xsltFlags} \
xsltproc \
--nonet --xinclude \
--output $@ \
"$$XSL/docbook/xhtml/docbook.xsl" \
doc-support/result/xhtml.xsl \
./manual-full.xml
mkdir -p out/html/highlightjs/
@ -43,50 +43,48 @@ out/html/index.html: manual-full.xml style.css highlightjs
cp ./style.css out/html/style.css
mkdir -p out/html/images/callouts
cp "$$XSL/docbook/images/callouts/"*.svg 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 ${xsltFlags} --nonet \
xsltproc --nonet \
--output out/epub/scratch/ \
"$$XSL/docbook/epub/docbook.xsl" \
doc-support/result/epub.xsl \
./manual-full.xml
cp ./overrides.css out/epub/scratch/OEBPS
cp ./style.css out/epub/scratch/OEBPS
mkdir -p out/epub/scratch/OEBPS/images/callouts/
cp "$$XSL/docbook/images/callouts/"*.svg 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:
highlightjs: doc-support/result
mkdir -p highlightjs
cp -r "$$HIGHLIGHTJS/highlight.pack.js" highlightjs/
cp -r "$$HIGHLIGHTJS/LICENSE" highlightjs/
cp -r "$$HIGHLIGHTJS/mono-blue.css" highlightjs/
cp -r "$$HIGHLIGHTJS/loader.js" 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:
nix-instantiate --eval \
-E '(import ../lib).version' > .version
.version: doc-support/result
ln -rfs ./doc-support/result/version .version
function_locations := $(shell nix-build --no-out-link ./lib-function-locations.nix)
doc-support/result: doc-support/default.nix
(cd doc-support; nix-build)
functions/library/locations.xml:
ln -s $(function_locations) ./functions/library/locations.xml
functions/library/locations.xml: doc-support/result
ln -rfs ./doc-support/result/function-locations.xml functions/library/locations.xml
functions/library/generated:
nix-build ./lib-function-docs.nix \
--arg locationsXml $(function_locations)\
--out-link ./functions/library/generated
functions/library/generated: doc-support/result
ln -rfs ./doc-support/result/function-docs functions/library/generated
%.section.xml: %.section.md
pandoc $^ -w docbook+smart \

108
doc/coding-conventions.xml

@ -197,20 +197,14 @@ args.stdenv.mkDerivation (args // {
<title>Package naming</title>
<para>
The key words
<emphasis>must</emphasis>,
<emphasis>must not</emphasis>,
<emphasis>required</emphasis>,
<emphasis>shall</emphasis>,
<emphasis>shall not</emphasis>,
<emphasis>should</emphasis>,
<emphasis>should not</emphasis>,
<emphasis>recommended</emphasis>,
<emphasis>may</emphasis>,
and <emphasis>optional</emphasis> in this section
are to be interpreted as described in
<link xlink:href="https://tools.ietf.org/html/rfc2119">RFC 2119</link>.
Only <emphasis>emphasized</emphasis> words are to be interpreted in this way.
The key words <emphasis>must</emphasis>, <emphasis>must not</emphasis>,
<emphasis>required</emphasis>, <emphasis>shall</emphasis>, <emphasis>shall
not</emphasis>, <emphasis>should</emphasis>, <emphasis>should
not</emphasis>, <emphasis>recommended</emphasis>, <emphasis>may</emphasis>,
and <emphasis>optional</emphasis> in this section are to be interpreted as
described in <link xlink:href="https://tools.ietf.org/html/rfc2119">RFC
2119</link>. Only <emphasis>emphasized</emphasis> words are to be
interpreted in this way.
</para>
<para>
@ -253,15 +247,15 @@ args.stdenv.mkDerivation (args // {
<itemizedlist>
<listitem>
<para>
The <literal>name</literal> attribute <emphasis>should</emphasis>
be identical to the upstream package name.
The <literal>name</literal> attribute <emphasis>should</emphasis> be
identical to the upstream package name.
</para>
</listitem>
<listitem>
<para>
The <literal>name</literal> attribute <emphasis>must not</emphasis>
contain uppercase letters — e.g., <literal>"mplayer-1.0rc2"</literal>
instead of <literal>"MPlayer-1.0rc2"</literal>.
The <literal>name</literal> attribute <emphasis>must not</emphasis>
contain uppercase letters — e.g., <literal>"mplayer-1.0rc2"</literal>
instead of <literal>"MPlayer-1.0rc2"</literal>.
</para>
</listitem>
<listitem>
@ -275,28 +269,29 @@ args.stdenv.mkDerivation (args // {
<para>
If a package is not a release but a commit from a repository, then the
version part of the name <emphasis>must</emphasis> be the date of that
(fetched) commit. The date <emphasis>must</emphasis> be in <literal>"YYYY-MM-DD"</literal>
format. Also append <literal>"unstable"</literal> to the name - e.g.,
(fetched) commit. The date <emphasis>must</emphasis> be in
<literal>"YYYY-MM-DD"</literal> format. Also append
<literal>"unstable"</literal> to the name - e.g.,
<literal>"pkgname-unstable-2014-09-23"</literal>.
</para>
</listitem>
<listitem>
<para>
Dashes in the package name <emphasis>should</emphasis> be preserved in new variable names,
rather than converted to underscores or camel cased — e.g.,
<varname>http-parser</varname> instead of <varname>http_parser</varname>
or <varname>httpParser</varname>. The hyphenated style is preferred in
all three package names.
Dashes in the package name <emphasis>should</emphasis> be preserved in
new variable names, rather than converted to underscores or camel cased
— e.g., <varname>http-parser</varname> instead of
<varname>http_parser</varname> or <varname>httpParser</varname>. The
hyphenated style is preferred in all three package names.
</para>
</listitem>
<listitem>
<para>
If there are multiple versions of a package, this <emphasis>should</emphasis> be reflected in
the variable names in <filename>all-packages.nix</filename>, e.g.
<varname>json-c-0-9</varname> and <varname>json-c-0-11</varname>. If
there is an obvious “default” version, make an attribute like
<literal>json-c = json-c-0-9;</literal>. See also
<xref linkend="sec-versioning" />
If there are multiple versions of a package, this
<emphasis>should</emphasis> be reflected in the variable names in
<filename>all-packages.nix</filename>, e.g. <varname>json-c-0-9</varname>
and <varname>json-c-0-11</varname>. If there is an obvious “default”
version, make an attribute like <literal>json-c = json-c-0-9;</literal>.
See also <xref linkend="sec-versioning" />
</para>
</listitem>
</itemizedlist>
@ -814,8 +809,8 @@ args.stdenv.mkDerivation (args // {
<para>
There are multiple ways to fetch a package source in nixpkgs. The general
guideline is that you should package reproducible sources with a high degree of
availability. Right now there is only one fetcher which has mirroring
guideline is that you should package reproducible sources with a high degree
of availability. Right now there is only one fetcher which has mirroring
support and that is <literal>fetchurl</literal>. Note that you should also
prefer protocols which have a corresponding proxy environment variable.
</para>
@ -869,8 +864,10 @@ src = fetchFromGitHub {
}
</programlisting>
Find the value to put as <literal>sha256</literal> by running
<literal>nix run -f '&lt;nixpkgs&gt;' nix-prefetch-github -c nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix</literal>
or <literal>nix-prefetch-url --unpack https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz</literal>.
<literal>nix run -f '&lt;nixpkgs&gt;' nix-prefetch-github -c
nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS
nix</literal> or <literal>nix-prefetch-url --unpack
https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz</literal>.
</para>
</listitem>
</itemizedlist>
@ -924,7 +921,7 @@ src = fetchFromGitHub {
<para>
You can convert between formats with nix-hash, for example:
<screen>
$ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable>
<prompt>$ </prompt>nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable>
</screen>
</para>
</listitem>
@ -953,17 +950,23 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable>
would be replace hash with a fake one and rebuild. Nix build will fail and
error message will contain desired hash.
</para>
<warning><para>This method has security problems. Check below for details.</para></warning>
<warning>
<para>
This method has security problems. Check below for details.
</para>
</warning>
</listitem>
</orderedlist>
<section xml:id="sec-source-hashes-security">
<title>Obtaining hashes securely</title>
<para>
Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead of fetching
source you can fetch malware, and instead of source hash you get hash of malware. Here are
security considerations for this scenario:
Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead
of fetching source you can fetch malware, and instead of source hash you
get hash of malware. Here are security considerations for this scenario:
</para>
<itemizedlist>
<listitem>
<para>
@ -972,7 +975,8 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable>
</listitem>
<listitem>
<para>
hashes from upstream (in method 3) should be obtained via secure protocol;
hashes from upstream (in method 3) should be obtained via secure
protocol;
</para>
</listitem>
<listitem>
@ -982,12 +986,12 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable>
</listitem>
<listitem>
<para>
<literal>https://</literal> URLs are not secure in method 5. When obtaining hashes
with fake hash method, TLS checks are disabled. So
refetch source hash from several different networks to exclude MITM scenario.
Alternatively, use fake hash method to make Nix error, but instead of extracting
hash from error, extract <literal>https://</literal> URL and prefetch it
with method 1.
<literal>https://</literal> URLs are not secure in method 5. When
obtaining hashes with fake hash method, TLS checks are disabled. So
refetch source hash from several different networks to exclude MITM
scenario. Alternatively, use fake hash method to make Nix error, but
instead of extracting hash from error, extract
<literal>https://</literal> URL and prefetch it with method 1.
</para>
</listitem>
</itemizedlist>
@ -1034,7 +1038,7 @@ patches = [ ./0001-changes.patch ];
<para>
Move to the root directory of the source code you're patching.
<screen>
$ cd the/program/source</screen>
<prompt>$ </prompt>cd the/program/source</screen>
</para>
</listitem>
<listitem>
@ -1042,8 +1046,8 @@ $ cd the/program/source</screen>
If a git repository is not already present, create one and stage all of
the source files.
<screen>
$ git init
$ git add .</screen>
<prompt>$ </prompt>git init
<prompt>$ </prompt>git add .</screen>
</para>
</listitem>
<listitem>
@ -1056,7 +1060,7 @@ $ git add .</screen>
<para>
Use git to create a diff, and pipe the output to a patch file:
<screen>
$ git diff > nixpkgs/pkgs/the/package/0001-changes.patch</screen>
<prompt>$ </prompt>git diff > nixpkgs/pkgs/the/package/0001-changes.patch</screen>
</para>
</listitem>
</orderedlist>

19
doc/configuration.xml

@ -132,13 +132,13 @@
</itemizedlist>
<para>
The difference between a package being unsupported on some system and
being broken is admittedly a bit fuzzy. If a program
<emphasis>ought</emphasis> to work on a certain platform, but doesn't, the
platform should be included in <literal>meta.platforms</literal>, but marked
as broken with e.g. <literal>meta.broken =
!hostPlatform.isWindows</literal>. Of course, this begs the question of what
"ought" means exactly. That is left to the package maintainer.
The difference between a package being unsupported on some system and being
broken is admittedly a bit fuzzy. If a program <emphasis>ought</emphasis> to
work on a certain platform, but doesn't, the platform should be included in
<literal>meta.platforms</literal>, but marked as broken with e.g.
<literal>meta.broken = !hostPlatform.isWindows</literal>. Of course, this
begs the question of what "ought" means exactly. That is left to the package
maintainer.
</para>
</section>
<section xml:id="sec-allow-unfree">
@ -175,9 +175,8 @@
</programlisting>
</para>
<para>
For a more useful example, try the following. This configuration
only allows unfree packages named flash player and visual studio
code:
For a more useful example, try the following. This configuration only
allows unfree packages named flash player and visual studio code:
<programlisting>
{
allowUnfreePredicate = (pkg: builtins.elem

14
doc/contributing.xml

@ -12,9 +12,9 @@ xlink:href="https://github.com/NixOS/nixpkgs/tree/master/doc">doc</filename>
You can quickly check your edits with <command>make</command>:
</para>
<screen>
$ cd /path/to/nixpkgs/doc
$ nix-shell
[nix-shell]$ make
<prompt>$ </prompt>cd /path/to/nixpkgs/doc
<prompt>$ </prompt>nix-shell
<prompt>[nix-shell]$ </prompt>make
</screen>
<para>
If you experience problems, run <command>make debug</command> to help
@ -24,10 +24,10 @@ xlink:href="https://github.com/NixOS/nixpkgs/tree/master/doc">doc</filename>
After making modifications to the manual, it's important to build it before
committing. You can do that as follows:
<screen>
$ cd /path/to/nixpkgs/doc
$ nix-shell
[nix-shell]$ make clean
[nix-shell]$ nix-build .
<prompt>$ </prompt>cd /path/to/nixpkgs/doc
<prompt>$ </prompt>nix-shell
<prompt>[nix-shell]$ </prompt>make clean
<prompt>[nix-shell]$ </prompt>nix-build .
</screen>
If the build succeeds, the manual will be in
<filename>./result/share/doc/nixpkgs/manual.html</filename>.

454
doc/cross-compilation.xml

@ -6,17 +6,18 @@
<title>Introduction</title>
<para>
"Cross-compilation" means compiling a program on one machine for another type
of machine. For example, a typical use of cross-compilation is to compile
programs for embedded devices. These devices often don't have the computing
power and memory to compile their own programs. One might think that
cross-compilation is a fairly niche concern. However, there are significant
advantages to rigorously distinguishing between build-time and run-time
environments! This applies even when one is developing and deploying on the
same machine. Nixpkgs is increasingly adopting the opinion that packages
should be written with cross-compilation in mind, and nixpkgs should evaluate
in a similar way (by minimizing cross-compilation-specific special cases)
whether or not one is cross-compiling.
"Cross-compilation" means compiling a program on one machine for another
type of machine. For example, a typical use of cross-compilation is to
compile programs for embedded devices. These devices often don't have the
computing power and memory to compile their own programs. One might think
that cross-compilation is a fairly niche concern. However, there are
significant advantages to rigorously distinguishing between build-time and
run-time environments! Significant, because the benefits apply even when one
is developing and deploying on the same machine. Nixpkgs is increasingly
adopting the opinion that packages should be written with cross-compilation
in mind, and nixpkgs should evaluate in a similar way (by minimizing
cross-compilation-specific special cases) whether or not one is
cross-compiling.
</para>
<para>
@ -30,19 +31,20 @@
<section xml:id="sec-cross-packaging">
<title>Packaging in a cross-friendly manner</title>
<section xml:id="sec-cross-platform-parameters">
<section xml:id="ssec-cross-platform-parameters">
<title>Platform parameters</title>
<para>
Nixpkgs follows the <link
Nixpkgs follows the
<link
xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html">conventions
of GNU autoconf</link>. We distinguish between 3 types of platforms when
building a derivation: <wordasword>build</wordasword>,
<wordasword>host</wordasword>, and <wordasword>target</wordasword>. In
summary, <wordasword>build</wordasword> is the platform on which a package
is being built, <wordasword>host</wordasword> is the platform on which it
will run. The third attribute, <wordasword>target</wordasword>, is relevant
only for certain specific compilers and build tools.
of GNU autoconf</link>. We distinguish between 3 types of platforms when
building a derivation: <wordasword>build</wordasword>,
<wordasword>host</wordasword>, and <wordasword>target</wordasword>. In
summary, <wordasword>build</wordasword> is the platform on which a package
is being built, <wordasword>host</wordasword> is the platform on which it
will run. The third attribute, <wordasword>target</wordasword>, is relevant
only for certain specific compilers and build tools.
</para>
<para>
@ -95,10 +97,10 @@
The build process of certain compilers is written in such a way that the
compiler resulting from a single build can itself only produce binaries
for a single platform. The task of specifying this single "target
platform" is thus pushed to build time of the compiler. The root cause of
this that the compiler (which will be run on the host) and the standard
library/runtime (which will be run on the target) are built by a single
build process.
platform" is thus pushed to build time of the compiler. The root cause
of this is that the compiler (which will be run on the host) and the
standard library/runtime (which will be run on the target) are built by
a single build process.
</para>
<para>
There is no fundamental need to think about a single target ahead of
@ -136,9 +138,9 @@
This is a two-component shorthand for the platform. Examples of this
would be "x86_64-darwin" and "i686-linux"; see
<literal>lib.systems.doubles</literal> for more. The first component
corresponds to the CPU architecture of the platform and the second to the
operating system of the platform (<literal>[cpu]-[os]</literal>). This
format has built-in support in Nix, such as the
corresponds to the CPU architecture of the platform and the second to
the operating system of the platform (<literal>[cpu]-[os]</literal>).
This format has built-in support in Nix, such as the
<varname>builtins.currentSystem</varname> impure string.
</para>
</listitem>
@ -149,14 +151,14 @@
</term>
<listitem>
<para>
This is a 3- or 4- component shorthand for the platform. Examples of this
would be <literal>x86_64-unknown-linux-gnu</literal> and
This is a 3- or 4- component shorthand for the platform. Examples of
this would be <literal>x86_64-unknown-linux-gnu</literal> and
<literal>aarch64-apple-darwin14</literal>. This is a standard format
called the "LLVM target triple", as they are pioneered by LLVM. In the
4-part form, this corresponds to
<literal>[cpu]-[vendor]-[os]-[abi]</literal>. This format is strictly
more informative than the "Nix host double", as the previous format could
analogously be termed. This needs a better name than
more informative than the "Nix host double", as the previous format
could analogously be termed. This needs a better name than
<varname>config</varname>!
</para>
</listitem>
@ -167,11 +169,10 @@
</term>
<listitem>
<para>
This is a Nix representation of a parsed LLVM target triple
with white-listed components. This can be specified directly,
or actually parsed from the <varname>config</varname>. See
<literal>lib.systems.parse</literal> for the exact
representation.
This is a Nix representation of a parsed LLVM target triple with
white-listed components. This can be specified directly, or actually
parsed from the <varname>config</varname>. See
<literal>lib.systems.parse</literal> for the exact representation.
</para>
</listitem>
</varlistentry>
@ -218,8 +219,20 @@
</variablelist>
</section>
<section xml:id="sec-cross-specifying-dependencies">
<title>Specifying Dependencies</title>
<section xml:id="ssec-cross-dependency-categorization">
<title>Theory of dependency categorization</title>
<note>
<para>
This is a rather philosophical description that isn't very
Nixpkgs-specific. For an overview of all the relevant attributes given to
<varname>mkDerivation</varname>, see
<xref
linkend="ssec-stdenv-dependencies"/>. For a description of how
everything is implemented, see
<xref linkend="ssec-cross-dependency-implementation" />.
</para>
</note>
<para>
In this section we explore the relationship between both runtime and
@ -227,83 +240,98 @@
</para>
<para>
A runtime dependency between 2 packages implies that between them both the
host and target platforms match. This is directly implied by the meaning of
"host platform" and "runtime dependency": The package dependency exists
while both packages are running on a single host platform.
A run time dependency between two packages requires that their host
platforms match. This is directly implied by the meaning of "host platform"
and "runtime dependency": The package dependency exists while both packages
are running on a single host platform.
</para>
<para>
A build time dependency, however, implies a shift in platforms between the
depending package and the depended-on package. The meaning of a build time
dependency is that to build the depending package we need to be able to run
the depended-on's package. The depending package's build platform is
therefore equal to the depended-on package's host platform. Analogously,
the depending package's host platform is equal to the depended-on package's
target platform.
A build time dependency, however, has a shift in platforms between the
depending package and the depended-on package. "build time dependency"
means that to build the depending package we need to be able to run the
depended-on's package. The depending package's build platform is therefore
equal to the depended-on package's host platform.
</para>
<para>
In this manner, given the 3 platforms for one package, we can determine the
three platforms for all its transitive dependencies. This is the most
important guiding principle behind cross-compilation with Nixpkgs, and will
be called the <wordasword>sliding window principle</wordasword>.
If both the dependency and depending packages aren't compilers or other
machine-code-producing tools, we're done. And indeed
<varname>buildInputs</varname> and <varname>nativeBuildInputs</varname>
have covered these simpler build-time and run-time (respectively) changes
for many years. But if the dependency does produce machine code, we might
need to worry about its target platform too. In principle, that target
platform might be any of the depending package's build, host, or target
platforms, but we prohibit dependencies from a "later" platform to an
earlier platform to limit confusion because we've never seen a legitimate
use for them.
</para>
<para>
Some examples will make this clearer. If a package is being built with a
<literal>(build, host, target)</literal> platform triple of <literal>(foo,
bar, bar)</literal>, then its build-time dependencies would have a triple of
<literal>(foo, foo, bar)</literal>, and <emphasis>those packages'</emphasis>
build-time dependencies would have a triple of <literal>(foo, foo,
foo)</literal>. In other words, it should take two "rounds" of following
build-time dependency edges before one reaches a fixed point where, by the
sliding window principle, the platform triple no longer changes. Indeed,
this happens with cross-compilation, where only rounds of native
dependencies starting with the second necessarily coincide with native
packages.
Finally, if the depending package is a compiler or other
machine-code-producing tool, it might need dependencies that run at "emit
time". This is for compilers that (regrettably) insist on being built
together with their source langauges' standard libraries. Assuming build !=
host != target, a run-time dependency of the standard library cannot be run
at the compiler's build time or run time, but only at the run time of code
emitted by the compiler.
</para>
<note>
<para>
The depending package's target platform is unconstrained by the sliding
window principle, which makes sense in that one can in principle build
cross compilers targeting arbitrary platforms.
</para>
</note>
<para>
How does this work in practice? Nixpkgs is now structured so that build-time
dependencies are taken from <varname>buildPackages</varname>, whereas
run-time dependencies are taken from the top level attribute set. For
example, <varname>buildPackages.gcc</varname> should be used at build-time,
while <varname>gcc</varname> should be used at run-time. Now, for most of
Nixpkgs's history, there was no <varname>buildPackages</varname>, and most
packages have not been refactored to use it explicitly. Instead, one can use
the six (<emphasis>gasp</emphasis>) attributes used for specifying
dependencies as documented in <xref linkend="ssec-stdenv-dependencies"/>. We
"splice" together the run-time and build-time package sets with
<varname>callPackage</varname>, and then <varname>mkDerivation</varname> for
each of four attributes pulls the right derivation out. This splicing can be
skipped when not cross-compiling as the package sets are the same, but is a
bit slow for cross-compiling. Because of this, a best-of-both-worlds
solution is in the works with no splicing or explicit access of
<varname>buildPackages</varname> needed. For now, feel free to use either
method.
Putting this all together, that means we have dependencies in the form
"host → target", in at most the following six combinations:
<table>
<caption>Possible dependency types</caption>
<thead>
<tr>
<th>Dependency's host platform</th>
<th>Dependency's target platform</th>
</tr>
</thead>
<tbody>
<tr>
<td>build</td>
<td>build</td>
</tr>
<tr>
<td>build</td>
<td>host</td>
</tr>
<tr>
<td>build</td>
<td>target</td>
</tr>
<tr>
<td>host</td>
<td>host</td>
</tr>
<tr>
<td>host</td>
<td>target</td>
</tr>
<tr>
<td>target</td>
<td>target</td>
</tr>
</tbody>
</table>
</para>
<note>
<para>
There is also a "backlink" <varname>targetPackages</varname>, yielding a
package set whose <varname>buildPackages</varname> is the current package
set. This is a hack, though, to accommodate compilers with lousy build
systems. Please do not use this unless you are absolutely sure you are
packaging such a compiler and there is no other way.
</para>
</note>
<para>
Some examples will make this table clearer. Suppose there's some package
that is being built with a <literal>(build, host, target)</literal>
platform triple of <literal>(foo, bar, baz)</literal>. If it has a
build-time library dependency, that would be a "host → build" dependency
with a triple of <literal>(foo, foo, *)</literal> (the target platform is
irrelevant). If it needs a compiler to be built, that would be a "build →
host" dependency with a triple of <literal>(foo, foo, *)</literal> (the
target platform is irrelevant). That compiler, would be built with another
compiler, also "build → host" dependency, with a triple of <literal>(foo,
foo, foo)</literal>.
</para>
</section>
<section xml:id="sec-cross-cookbook">
<section xml:id="ssec-cross-cookbook">
<title>Cross packaging cookbook</title>
<para>
@ -311,8 +339,8 @@
should be answered here. Ideally, the information above is exhaustive, so
this section cannot provide any new information, but it is ludicrous and
cruel to expect everyone to spend effort working through the interaction of
many features just to figure out the same answer to the same common problem.
Feel free to add to this list!
many features just to figure out the same answer to the same common
problem. Feel free to add to this list!
</para>
<qandaset>
@ -434,35 +462,217 @@ nix-build &lt;nixpkgs&gt; --arg crossSystem '{ config = "&lt;arch&gt;-&lt;os&gt;
build plan or package set. A simple "build vs deploy" dichotomy is adequate:
the sliding window principle described in the previous section shows how to
interpolate between the these two "end points" to get the 3 platform triple
for each bootstrapping stage. That means for any package a given package set,
even those not bound on the top level but only reachable via dependencies or
<varname>buildPackages</varname>, the three platforms will be defined as one
of <varname>localSystem</varname> or <varname>crossSystem</varname>, with the
former replacing the latter as one traverses build-time dependencies. A last
simple difference is that <varname>crossSystem</varname> should be null when
one doesn't want to cross-compile, while the <varname>*Platform</varname>s
are always non-null. <varname>localSystem</varname> is always non-null.
for each bootstrapping stage. That means for any package a given package
set, even those not bound on the top level but only reachable via
dependencies or <varname>buildPackages</varname>, the three platforms will
be defined as one of <varname>localSystem</varname> or
<varname>crossSystem</varname>, with the former replacing the latter as one
traverses build-time dependencies. A last simple difference is that
<varname>crossSystem</varname> should be null when one doesn't want to
cross-compile, while the <varname>*Platform</varname>s are always non-null.
<varname>localSystem</varname> is always non-null.
</para>
</section>
<!--============================================================-->
<section xml:id="sec-cross-infra">
<title>Cross-compilation infrastructure</title>
<para>
To be written.
</para>
<section xml:id="ssec-cross-dependency-implementation">
<title>Implementation of dependencies</title>
<note>
<para>
If one explores Nixpkgs, they will see derivations with names like
<literal>gccCross</literal>. Such <literal>*Cross</literal> derivations is a
holdover from before we properly distinguished between the host and target
platforms—the derivation with "Cross" in the name covered the <literal>build
= host != target</literal> case, while the other covered the <literal>host =
target</literal>, with build platform the same or not based on whether one
was using its <literal>.nativeDrv</literal> or <literal>.crossDrv</literal>.
This ugliness will disappear soon.
The categorizes of dependencies developed in
<xref
linkend="ssec-cross-dependency-categorization"/> are specified as
lists of derivations given to <varname>mkDerivation</varname>, as
documented in <xref linkend="ssec-stdenv-dependencies"/>. In short,
each list of dependencies for "host → target" of "foo → bar" is called
<varname>depsFooBar</varname>, with exceptions for backwards
compatibility that <varname>depsBuildHost</varname> is instead called
<varname>nativeBuildInputs</varname> and <varname>depsHostTarget</varname>
is instead called <varname>buildInputs</varname>. Nixpkgs is now structured
so that each <varname>depsFooBar</varname> is automatically taken from
<varname>pkgsFooBar</varname>. (These <varname>pkgsFooBar</varname>s are
quite new, so there is no special case for
<varname>nativeBuildInputs</varname> and <varname>buildInputs</varname>.)
For example, <varname>pkgsBuildHost.gcc</varname> should be used at
build-time, while <varname>pkgsHostTarget.gcc</varname> should be used at
run-time.
</para>
</note>
<para>
Now, for most of Nixpkgs's history, there were no
<varname>pkgsFooBar</varname> attributes, and most packages have not been
refactored to use it explicitly. Prior to those, there were just
<varname>buildPackages</varname>, <varname>pkgs</varname>, and
<varname>targetPackages</varname>. Those are now redefined as aliases to
<varname>pkgsBuildHost</varname>, <varname>pkgsHostTarget</varname>, and
<varname>pkgsTargetTarget</varname>. It is acceptable, even
recommended, to use them for libraries to show that the host platform is
irrelevant.
</para>
<para>
But before that, there was just <varname>pkgs</varname>, even though both
<varname>buildInputs</varname> and <varname>nativeBuildInputs</varname>
existed. [Cross barely worked, and those were implemented with some hacks
on <varname>mkDerivation</varname> to override dependencies.] What this
means is the vast majority of packages do not use any explicit package set
to populate their dependencies, just using whatever
<varname>callPackage</varname> gives them even if they do correctly sort
their dependencies into the multiple lists described above. And indeed,
asking that users both sort their dependencies, <emphasis>and</emphasis>
take them from the right attribute set, is both too onerous and redundant,
so the recommended approach (for now) is to continue just categorizing by
list and not using an explicit package set.
</para>
<para>
To make this work, we "splice" together the six
<varname>pkgsFooBar</varname> package sets and have
<varname>callPackage</varname> actually take its arguments from that. This
is currently implemented in <filename>pkgs/top-level/splice.nix</filename>.
<varname>mkDerivation</varname> then, for each dependency attribute, pulls
the right derivation out from the splice. This splicing can be skipped when
not cross-compiling as the package sets are the same, but still is a bit
slow for cross-compiling. We'd like to do something better, but haven't
come up with anything yet.
</para>
</section>
<section xml:id="ssec-bootstrapping">
<title>Bootstrapping</title>
<para>
Each of the package sets described above come from a single bootstrapping
stage. While <filename>pkgs/top-level/default.nix</filename>, coordinates
the composition of stages at a high level,
<filename>pkgs/top-level/stage.nix</filename> "ties the knot" (creates the
fixed point) of each stage. The package sets are defined per-stage however,
so they can be thought of as edges between stages (the nodes) in a graph.
Compositions like <literal>pkgsBuildTarget.targetPackages</literal> can be
thought of as paths to this graph.
</para>
<para>
While there are many package sets, and thus many edges, the stages can also
be arranged in a linear chain. In other words, many of the edges are
redundant as far as connectivity is concerned. This hinges on the type of
bootstrapping we do. Currently for cross it is:
<orderedlist>
<listitem>
<para>
<literal>(native, native, native)</literal>
</para>
</listitem>
<listitem>
<para>
<literal>(native, native, foreign)</literal>
</para>
</listitem>
<listitem>
<para>
<literal>(native, foreign, foreign)</literal>
</para>
</listitem>
</orderedlist>
In each stage, <varname>pkgsBuildHost</varname> refers the the previous
stage, <varname>pkgsBuildBuild</varname> refers to the one before that, and
<varname>pkgsHostTarget</varname> refers to the current one, and
<varname>pkgsTargetTarget</varname> refers to the next one. When there is
no previous or next stage, they instead refer to the current stage. Note
how all the invariants regarding the mapping between dependency and depending
packages' build host and target platforms are preserved.
<varname>pkgsBuildTarget</varname> and <varname>pkgsHostHost</varname> are
more complex in that the stage fitting the requirements isn't always a
fixed chain of "prevs" and "nexts" away (modulo the "saturating"
self-references at the ends). We just special case each instead. All the primary
edges are implemented is in <filename>pkgs/stdenv/booter.nix</filename>,
and secondarily aliases in <filename>pkgs/top-level/stage.nix</filename>.
</para>
<note>
<para>
Note the native stages are bootstrapped in legacy ways that predate the
current cross implementation. This is why the the bootstrapping stages
leading up to the final stages are ignored inthe previous paragraph.
</para>
</note>
<para>
If one looks at the 3 platform triples, one can see that they overlap such
that one could put them together into a chain like:
<programlisting>
(native, native, native, foreign, foreign)
</programlisting>
If one imagines the saturating self references at the end being replaced
with infinite stages, and then overlays those platform triples, one ends up
with the infinite tuple:
<programlisting>
(native..., native, native, native, foreign, foreign, foreign...)
</programlisting>
On can then imagine any sequence of platforms such that there are bootstrap
stages with their 3 platforms determined by "sliding a window" that is the
3 tuple through the sequence. This was the original model for
bootstrapping. Without a target platform (assume a better world where all
compilers are multi-target and all standard libraries are built in their
own derivation), this is sufficient. Conversely if one wishes to cross
compile "faster", with a "Canadian Cross" bootstraping stage where
<literal>build != host != target</literal>, more bootstrapping stages are
needed since no sliding window providess the pesky
<varname>pkgsBuildTarget</varname> package set since it skips the Canadian
cross stage's "host".
</para>
<note>
<para>
It is much better to refer to <varname>buildPackages</varname> than
<varname>targetPackages</varname>, or more broadly package sets that do
not mention "target". There are three reasons for this.
</para>
<para>
First, it is because bootstrapping stages do not have a unique
<varname>targetPackages</varname>. For example a <literal>(x86-linux,
x86-linux, arm-linux)</literal> and <literal>(x86-linux, x86-linux,
x86-windows)</literal> package set both have a <literal>(x86-linux,
x86-linux, x86-linux)</literal> package set. Because there is no canonical
<varname>targetPackages</varname> for such a native (<literal>build ==
host == target</literal>) package set, we set their
<varname>targetPackages</varname>
</para>
<para>
Second, it is because this is a frequent source of hard-to-follow
"infinite recursions" / cycles. When only package sets that don't mention
target are used, the package set forms a directed acyclic graph. This
means that all cycles that exist are confined to one stage. This means
they are a lot smaller, and easier to follow in the code or a backtrace. It
also means they are present in native and cross builds alike, and so more
likely to be caught by CI and other users.
</para>
<para>
Thirdly, it is because everything target-mentioning only exists to
accommodate compilers with lousy build systems that insist on the compiler
itself and standard library being built together. Of course that is bad
because bigger derivations means longer rebuilds. It is also problematic because
it tends to make the standard libraries less like other libraries than
they could be, complicating code and build systems alike. Because of the
other problems, and because of these innate disadvantages, compilers ought
to be packaged another way where possible.
</para>
</note>
<note>
<para>
If one explores Nixpkgs, they will see derivations with names like
<literal>gccCross</literal>. Such <literal>*Cross</literal> derivations is
a holdover from before we properly distinguished between the host and
target platforms—the derivation with "Cross" in the name covered the
<literal>build = host != target</literal> case, while the other covered
the <literal>host = target</literal>, with build platform the same or not
based on whether one was using its <literal>.nativeDrv</literal> or
<literal>.crossDrv</literal>. This ugliness will disappear soon.
</para>
</note>
</section>
</section>
</chapter>

27
doc/default.nix

@ -1,8 +1,7 @@
{ pkgs ? (import ./.. { }), nixpkgs ? { }}:
let
lib = pkgs.lib;
locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs; };
functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs; };
doc-support = import ./doc-support { inherit pkgs nixpkgs; };
in pkgs.stdenv.mkDerivation {
name = "nixpkgs-manual";
@ -10,30 +9,8 @@ in pkgs.stdenv.mkDerivation {
src = ./.;
# Hacking on these variables? Make sure to close and open
# nix-shell between each test, maybe even:
# $ nix-shell --run "make clean all"
# otherwise they won't reapply :)
HIGHLIGHTJS = pkgs.documentation-highlighter;
XSL = "${pkgs.docbook_xsl_ns}/xml/xsl";
RNG = "${pkgs.docbook5}/xml/rng/docbook/docbook.rng";
XMLFORMAT_CONFIG = ../nixos/doc/xmlformat.conf;
xsltFlags = lib.concatStringsSep " " [
"--param section.autolabel 1"
"--param section.label.includes.component.label 1"
"--stringparam html.stylesheet 'style.css overrides.css highlightjs/mono-blue.css'"
"--stringparam html.script './highlightjs/highlight.pack.js ./highlightjs/loader.js'"
"--param xref.with.number.and.title 1"
"--param toc.section.depth 3"
"--stringparam admon.style ''"
"--stringparam callout.graphics.extension .svg"
];
postPatch = ''
rm -rf ./functions/library/locations.xml
ln -s ${locationsXml} ./functions/library/locations.xml
ln -s ${functionDocs} ./functions/library/generated
echo ${lib.version} > .version
ln -s ${doc-support} ./doc-support/result
'';
installPhase = ''

45
doc/doc-support/default.nix

@ -0,0 +1,45 @@
{ pkgs ? (import ../.. {}), nixpkgs ? { }}:
let
locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs; };
functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs; };
version = pkgs.lib.version;
epub-xsl = pkgs.writeText "epub.xsl" ''
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl" />
<xsl:import href="${./parameters.xml}"/>
</xsl:stylesheet>
'';
xhtml-xsl = pkgs.writeText "xhtml.xsl" ''
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/xhtml/docbook.xsl" />
<xsl:import href="${./parameters.xml}"/>
</xsl:stylesheet>
'';
in pkgs.runCommand "doc-support" {}
''
mkdir result
(
cd result
ln -s ${locationsXml} ./function-locations.xml
ln -s ${functionDocs} ./function-docs
ln -s ${pkgs.docbook5}/xml/rng/docbook/docbook.rng ./docbook.rng
ln -s ${pkgs.docbook_xsl_ns}/xml/xsl ./xsl
ln -s ${epub-xsl} ./epub.xsl
ln -s ${xhtml-xsl} ./xhtml.xsl
ln -s ${../../nixos/doc/xmlformat.conf} ./xmlformat.conf
ln -s ${pkgs.documentation-highlighter} ./highlightjs
echo -n "${version}" > ./version
)
mv result $out
''

2
doc/lib-function-docs.nix → doc/doc-support/lib-function-docs.nix

@ -6,7 +6,7 @@
with pkgs; stdenv.mkDerivation {
name = "nixpkgs-lib-docs";
src = ./../lib;
src = ./../../lib;
buildInputs = [ nixdoc ];
installPhase = ''

0
doc/lib-function-locations.nix → doc/doc-support/lib-function-locations.nix

14
doc/doc-support/parameters.xml

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

2
doc/functions.xml

@ -16,6 +16,8 @@
<xi:include href="functions/fhs-environments.xml" />
<xi:include href="functions/shell.xml" />
<xi:include href="functions/dockertools.xml" />
<xi:include href="functions/snaptools.xml" />
<xi:include href="functions/appimagetools.xml" />
<xi:include href="functions/prefer-remote-fetch.xml" />
<xi:include href="functions/nix-gitignore.xml" />
</chapter>

118
doc/functions/appimagetools.xml

@ -0,0 +1,118 @@
<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-pkgs-appimageTools">
<title>pkgs.appimageTools</title>
<para>
<varname>pkgs.appimageTools</varname> is a set of functions for extracting
and wrapping <link xlink:href="https://appimage.org/">AppImage</link> files.
They are meant to be used if traditional packaging from source is infeasible,
or it would take too long. To quickly run an AppImage file,
<literal>pkgs.appimage-run</literal> can be used as well.
</para>
<warning>
<para>
The <varname>appimageTools</varname> API is unstable and may be subject to
backwards-incompatible changes in the future.
</para>
</warning>
<section xml:id="ssec-pkgs-appimageTools-formats">
<title>AppImage formats</title>
<para>
There are different formats for AppImages, see
<link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the
specification</link> for details.
</para>
<itemizedlist>
<listitem>
<para>
Type 1 images are ISO 9660 files that are also ELF executables.
</para>
</listitem>
<listitem>
<para>
Type 2 images are ELF executables with an appended filesystem.
</para>
</listitem>
</itemizedlist>
<para>
They can be told apart with <command>file -k</command>:
</para>
<screen>
<prompt>$ </prompt>file -k type1.AppImage
type1.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) ISO 9660 CD-ROM filesystem data 'AppImage' (Lepton 3.x), scale 0-0,
spot sensor temperature 0.000000, unit celsius, color scheme 0, calibration: offset 0.000000, slope 0.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=d629f6099d2344ad82818172add1d38c5e11bc6d, stripped\012- data
<prompt>$ </prompt>file -k type2.AppImage
type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x), scale 232-60668, spot sensor temperature -4.187500, color scheme 15, show scale bar, calibration: offset -0.000000, slope 0.000000 (Lepton 2.x), scale 4111-45000, spot sensor temperature 412442.250000, color scheme 3, minimum point enabled, calibration: offset -75402534979642766821519867692934234112.000000, slope 5815371847733706829839455140374904832.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=79dcc4e55a61c293c5e19edbd8d65b202842579f, stripped\012- data
</screen>
<para>
Note how the type 1 AppImage is described as an <literal>ISO 9660 CD-ROM
filesystem</literal>, and the type 2 AppImage is not.
</para>
</section>
<section xml:id="ssec-pkgs-appimageTools-wrapping">
<title>Wrapping</title>
<para>
Depending on the type of AppImage you're wrapping, you'll have to use
<varname>wrapType1</varname> or <varname>wrapType2</varname>.
</para>
<programlisting>
appimageTools.wrapType2 { # or wrapType1
name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' />
src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' />
url = https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage;
sha256 = "1blsprpkvm0ws9b96gb36f0rbf8f5jgmw4x6dsb1kswr4ysf591s";
};
extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' />
}</programlisting>
<calloutlist>
<callout arearefs='ex-appimageTools-wrapping-1'>
<para>
<varname>name</varname> specifies the name of the resulting image.
</para>
</callout>
<callout arearefs='ex-appimageTools-wrapping-2'>
<para>
<varname>src</varname> specifies the AppImage file to extract.
</para>
</callout>
<callout arearefs='ex-appimageTools-wrapping-2'>
<para>
<varname>extraPkgs</varname> allows you to pass a function to include
additional packages inside the FHS environment your AppImage is going to
run in. There are a few ways to learn which dependencies an application
needs:
<itemizedlist>
<listitem>
<para>
Looking through the extracted AppImage files, reading its scripts and
running <command>patchelf</command> and <command>ldd</command> on its
executables. This can also be done in <command>appimage-run</command>,
by setting <command>APPIMAGE_DEBUG_EXEC=bash</command>.
</para>
</listitem>
<listitem>
<para>
Running <command>strace -vfefile</command> on the wrapped executable,
looking for libraries that can't be found.
</para>
</listitem>
</itemizedlist>
</para>
</callout>
</calloutlist>
</section>
</section>

112
doc/functions/dockertools.xml

@ -24,9 +24,9 @@
<para>
This function is analogous to the <command>docker build</command> command,
in that it can be used to build a Docker-compatible repository tarball containing
a single image with one or multiple layers. As such, the result is suitable
for being loaded in Docker with <command>docker load</command>.
in that it can be used to build a Docker-compatible repository tarball
containing a single image with one or multiple layers. As such, the result
is suitable for being loaded in Docker with <command>docker load</command>.
</para>
<para>
@ -47,7 +47,7 @@ buildImage {
contents = pkgs.redis; <co xml:id='ex-dockerTools-buildImage-6' />
runAsRoot = '' <co xml:id='ex-dockerTools-buildImage-runAsRoot' />
#!${stdenv.shell}
#!${pkgs.runtimeShell}
mkdir -p /data
'';
@ -190,8 +190,8 @@ buildImage {
By default <function>buildImage</function> will use a static date of one
second past the UNIX Epoch. This allows <function>buildImage</function> to
produce binary reproducible images. When listing images with
<command>docker images</command>, the newly created images will be
listed like this:
<command>docker images</command>, the newly created images will be listed
like this:
</para>
<screen><![CDATA[
$ docker images
@ -312,7 +312,23 @@ hello latest de2bf4786de6 About a minute ago 25.2MB
Maximum number of layers to create.
</para>
<para>
<emphasis>Default:</emphasis> <literal>24</literal>
<emphasis>Default:</emphasis> <literal>100</literal>
</para>
<para>
<emphasis>Maximum:</emphasis> <literal>125</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>extraCommands</varname> <emphasis>optional</emphasis>
</term>
<listitem>
<para>
Shell commands to run while building the final layer, without access
to most of the layer contents. Changes to this layer are "on top"
of all the other layers, so can create additional directories
and files.
</para>
</listitem>
</varlistentry>
@ -402,9 +418,9 @@ pkgs.dockerTools.buildLayeredImage {
<para>
This function is analogous to the <command>docker pull</command> command, in
that it can be used to pull a Docker image from a Docker registry. By default
<link xlink:href="https://hub.docker.com/">Docker Hub</link> is used to pull
images.
that it can be used to pull a Docker image from a Docker registry. By
default <link xlink:href="https://hub.docker.com/">Docker Hub</link> is used
to pull images.
</para>
<para>
@ -417,10 +433,11 @@ pkgs.dockerTools.buildLayeredImage {
pullImage {
imageName = "nixos/nix"; <co xml:id='ex-dockerTools-pullImage-1' />
imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; <co xml:id='ex-dockerTools-pullImage-2' />
finalImageTag = "1.11"; <co xml:id='ex-dockerTools-pullImage-3' />
sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; <co xml:id='ex-dockerTools-pullImage-4' />
os = "linux"; <co xml:id='ex-dockerTools-pullImage-5' />
arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-6' />
finalImageName = "nix"; <co xml:id='ex-dockerTools-pullImage-3' />
finalImageTag = "1.11"; <co xml:id='ex-dockerTools-pullImage-4' />
sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; <co xml:id='ex-dockerTools-pullImage-5' />
os = "linux"; <co xml:id='ex-dockerTools-pullImage-6' />
arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-7' />
}
</programlisting>
</example>
@ -436,21 +453,18 @@ pullImage {
<callout arearefs='ex-dockerTools-pullImage-2'>
<para>