movefasta/nixpkgs
1
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2025-06-12 20:55:31 +03:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source
This commit is contained in:
John Ericson 2019-09-02 01:31:31 -04:00
commit c33d80c071
12702 changed files with 456501 additions and 349462 deletions
Download patch file Download diff file Expand all files Collapse all files

37
.github/CODEOWNERS vendored
View file

@ -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 vendored
View file

@ -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 vendored Normal file
View file

@ -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 vendored Normal file
View file

@ -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 vendored
View file

@ -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
View file

@ -1 +1 @@
19.03
19.09

2
COPYING
View file

@ -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
View file

@ -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 vendored
View file

@ -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
View file

@ -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 \

102
doc/coding-conventions.xml
View file

@ -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,8 +247,8 @@ 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>
@ -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
View file

@ -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
View file

@ -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>.

426
doc/cross-compilation.xml
View file

@ -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,11 +31,12 @@
<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>,
@ -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.
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>
</note>
</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>
<section xml:id="ssec-cross-dependency-implementation">
<title>Implementation of dependencies</title>
<para>
To be written.
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>
<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.
<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
View file

@ -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 Normal file
View file

@ -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
View file

@ -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
View file

14
doc/doc-support/parameters.xml Normal file
View file

@ -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
View file

@ -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 Normal file
View file

@ -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>

110
doc/functions/dockertools.xml
View file

@ -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>
<varname>imageDigest</varname> specifies the digest of the image to be
downloaded. Skopeo can be used to get the digest of an image, with its
<varname>inspect</varname> subcommand. Since a given
<varname>imageName</varname> may transparently refer to a manifest list of
images which support multiple architectures and/or operating systems,
supply the `--override-os` and `--override-arch` arguments to specify
exactly which image you want. By default it will match the OS and
architecture of the host the command is run on.
<programlisting>
$ nix-shell --packages skopeo jq --command "skopeo --override-os linux --override-arch x86_64 inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'"
sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
</programlisting>
This argument is required.
downloaded. This argument is required.
</para>
</callout>
<callout arearefs='ex-dockerTools-pullImage-3'>
<para>
<varname>finalImageName</varname>, if specified, this is the name of the
image to be created. Note it is never used to fetch the image since we
prefer to rely on the immutable digest ID. By default it's equal to
<varname>imageName</varname>.
</para>
</callout>
<callout arearefs='ex-dockerTools-pullImage-4'>
<para>
<varname>finalImageTag</varname>, if specified, this is the tag of the
image to be created. Note it is never used to fetch the image since we
@ -458,25 +472,53 @@ sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
<literal>latest</literal>.
</para>
</callout>
<callout arearefs='ex-dockerTools-pullImage-4'>
<callout arearefs='ex-dockerTools-pullImage-5'>
<para>
<varname>sha256</varname> is the checksum of the whole fetched image. This
argument is required.
</para>
</callout>
<callout arearefs='ex-dockerTools-pullImage-5'>
<callout arearefs='ex-dockerTools-pullImage-6'>
<para>
<varname>os</varname>, if specified, is the operating system of the
fetched image. By default it's <literal>linux</literal>.
</para>
</callout>
<callout arearefs='ex-dockerTools-pullImage-6'>
<callout arearefs='ex-dockerTools-pullImage-7'>
<para>
<varname>arch</varname>, if specified, is the cpu architecture of the
fetched image. By default it's <literal>x86_64</literal>.
</para>
</callout>
</calloutlist>
<para>
<literal>nix-prefetch-docker</literal> command can be used to get required
image parameters:
<screen>
<prompt>$ </prompt>nix run nixpkgs.nix-prefetch-docker -c nix-prefetch-docker --image-name mysql --image-tag 5
</screen>
Since a given <varname>imageName</varname> may transparently refer to a
manifest list of images which support multiple architectures and/or
operating systems, you can supply the <option>--os</option> and
<option>--arch</option> arguments to specify exactly which image you want.
By default it will match the OS and architecture of the host the command is
run on.
<screen>
<prompt>$ </prompt>nix-prefetch-docker --image-name mysql --image-tag 5 --arch x86_64 --os linux
</screen>
Desired image name and tag can be set using
<option>--final-image-name</option> and <option>--final-image-tag</option>
arguments:
<screen>
<prompt>$ </prompt>nix-prefetch-docker --image-name mysql --image-tag 5 --final-image-name eu.gcr.io/my-project/mysql --final-image-tag prod
</screen>
</para>
</section>
<section xml:id="ssec-pkgs-dockerTools-exportImage">
@ -484,10 +526,10 @@ sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
<para>
This function is analogous to the <command>docker export</command> command,
in that it can be used to flatten a Docker image that contains multiple layers. It
is in fact the result of the merge of all the layers of the image. As such,
the result is suitable for being imported in Docker with <command>docker
import</command>.
in that it can be used to flatten a Docker image that contains multiple
layers. It is in fact the result of the merge of all the layers of the
image. As such, the result is suitable for being imported in Docker with
<command>docker import</command>.
</para>
<note>
@ -544,7 +586,7 @@ buildImage {
name = "shadow-basic";
runAsRoot = ''
#!${stdenv.shell}
#!${pkgs.runtimeShell}
${shadowSetup}
groupadd -r redis
useradd -r -g redis redis

114
doc/functions/fetchers.xml
View file

@ -5,21 +5,18 @@
<title>Fetcher functions</title>
<para>
When using Nix, you will frequently need to download source code
and other files from the internet. Nixpkgs comes with a few helper
functions that allow you to fetch fixed-output derivations in a
structured way.
When using Nix, you will frequently need to download source code and other
files from the internet. Nixpkgs comes with a few helper functions that allow
you to fetch fixed-output derivations in a structured way.
</para>
<para>
The two fetcher primitives are <function>fetchurl</function> and
<function>fetchzip</function>. Both of these have two required
arguments, a URL and a hash. The hash is typically
<literal>sha256</literal>, although many more hash algorithms are
supported. Nixpkgs contributors are currently recommended to use
<literal>sha256</literal>. This hash will be used by Nix to
identify your source. A typical usage of fetchurl is provided
below.
<function>fetchzip</function>. Both of these have two required arguments, a
URL and a hash. The hash is typically <literal>sha256</literal>, although
many more hash algorithms are supported. Nixpkgs contributors are currently
recommended to use <literal>sha256</literal>. This hash will be used by Nix
to identify your source. A typical usage of fetchurl is provided below.
</para>
<programlisting><![CDATA[
@ -37,30 +34,28 @@ stdenv.mkDerivation {
<para>
The main difference between <function>fetchurl</function> and
<function>fetchzip</function> is in how they store the contents.
<function>fetchurl</function> will store the unaltered contents of
the URL within the Nix store. <function>fetchzip</function> on the
other hand will decompress the archive for you, making files and
directories directly accessible in the future.
<function>fetchzip</function> can only be used with archives.
Despite the name, <function>fetchzip</function> is not limited to
<function>fetchurl</function> will store the unaltered contents of the URL
within the Nix store. <function>fetchzip</function> on the other hand will
decompress the archive for you, making files and directories directly
accessible in the future. <function>fetchzip</function> can only be used with
archives. Despite the name, <function>fetchzip</function> is not limited to
.zip files and can also be used with any tarball.
</para>
<para>
<function>fetchpatch</function> works very similarly to
<function>fetchurl</function> with the same arguments expected. It
expects patch files as a source and and performs normalization on
them before computing the checksum. For example it will remove
comments or other unstable parts that are sometimes added by
version control systems and can change over time.
<function>fetchurl</function> with the same arguments expected. It expects
patch files as a source and and performs normalization on them before
computing the checksum. For example it will remove comments or other unstable
parts that are sometimes added by version control systems and can change over
time.
</para>
<para>
Other fetcher functions allow you to add source code directly from
a VCS such as subversion or git. These are mostly straightforward
names based on the name of the command used with the VCS system.
Because they give you a working repository, they act most like
<function>fetchzip</function>.
Other fetcher functions allow you to add source code directly from a VCS such
as subversion or git. These are mostly straightforward names based on the
name of the command used with the VCS system. Because they give you a working
repository, they act most like <function>fetchzip</function>.
</para>
<variablelist>
@ -70,9 +65,8 @@ stdenv.mkDerivation {
</term>
<listitem>
<para>
Used with Subversion. Expects <literal>url</literal> to a
Subversion directory, <literal>rev</literal>, and
<literal>sha256</literal>.
Used with Subversion. Expects <literal>url</literal> to a Subversion
directory, <literal>rev</literal>, and <literal>sha256</literal>.
</para>
</listitem>
</varlistentry>
@ -84,9 +78,8 @@ stdenv.mkDerivation {
<para>
Used with Git. Expects <literal>url</literal> to a Git repo,
<literal>rev</literal>, and <literal>sha256</literal>.
<literal>rev</literal> in this case can be full the git commit
id (SHA1 hash) or a tag name like
<literal>refs/tags/v1.0</literal>.
<literal>rev</literal> in this case can be full the git commit id (SHA1
hash) or a tag name like <literal>refs/tags/v1.0</literal>.
</para>
</listitem>
</varlistentry>
@ -96,8 +89,8 @@ stdenv.mkDerivation {
</term>
<listitem>
<para>
Used with Fossil. Expects <literal>url</literal> to a Fossil
archive, <literal>rev</literal>, and <literal>sha256</literal>.
Used with Fossil. Expects <literal>url</literal> to a Fossil archive,
<literal>rev</literal>, and <literal>sha256</literal>.
</para>
</listitem>
</varlistentry>
@ -107,8 +100,8 @@ stdenv.mkDerivation {
</term>
<listitem>
<para>
Used with CVS. Expects <literal>cvsRoot</literal>,
<literal>tag</literal>, and <literal>sha256</literal>.
Used with CVS. Expects <literal>cvsRoot</literal>, <literal>tag</literal>,
and <literal>sha256</literal>.
</para>
</listitem>
</varlistentry>
@ -126,11 +119,10 @@ stdenv.mkDerivation {
</variablelist>
<para>
A number of fetcher functions wrap part of
<function>fetchurl</function> and <function>fetchzip</function>.
They are mainly convenience functions intended for commonly used
destinations of source code in Nixpkgs. These wrapper fetchers are
listed below.
A number of fetcher functions wrap part of <function>fetchurl</function> and
<function>fetchzip</function>. They are mainly convenience functions intended
for commonly used destinations of source code in Nixpkgs. These wrapper
fetchers are listed below.
</para>
<variablelist>
@ -141,17 +133,15 @@ stdenv.mkDerivation {
<listitem>
<para>
<function>fetchFromGitHub</function> expects four arguments.
<literal>owner</literal> is a string corresponding to the
GitHub user or organization that controls this repository.
<literal>repo</literal> corresponds to the name of the
software repository. These are located at the top of every
GitHub HTML page as
<literal>owner</literal>/<literal>repo</literal>.
<literal>rev</literal> corresponds to the Git commit hash or
tag (e.g <literal>v1.0</literal>) that will be downloaded from
Git. Finally, <literal>sha256</literal> corresponds to the
hash of the extracted directory. Again, other hash algorithms
are also available but <literal>sha256</literal> is currently
<literal>owner</literal> is a string corresponding to the GitHub user or
organization that controls this repository. <literal>repo</literal>
corresponds to the name of the software repository. These are located at
the top of every GitHub HTML page as
<literal>owner</literal>/<literal>repo</literal>. <literal>rev</literal>
corresponds to the Git commit hash or tag (e.g <literal>v1.0</literal>)
that will be downloaded from Git. Finally, <literal>sha256</literal>
corresponds to the hash of the extracted directory. Again, other hash
algorithms are also available but <literal>sha256</literal> is currently
preferred.
</para>
</listitem>
@ -162,8 +152,8 @@ stdenv.mkDerivation {
</term>
<listitem>
<para>
This is used with GitLab repositories. The arguments expected
are very similar to fetchFromGitHub above.
This is used with GitLab repositories. The arguments expected are very
similar to fetchFromGitHub above.
</para>
</listitem>
</varlistentry>
@ -173,8 +163,8 @@ stdenv.mkDerivation {
</term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
@ -184,8 +174,8 @@ stdenv.mkDerivation {
</term>
<listitem>
<para>
This is used with Savannah repositories. The arguments expected
are very similar to fetchFromGitHub above.
This is used with Savannah repositories. The arguments expected are very
similar to fetchFromGitHub above.
</para>
</listitem>
</varlistentry>
@ -195,12 +185,10 @@ stdenv.mkDerivation {
</term>
<listitem>
<para>
This is used with repo.or.cz repositories. The arguments
expected are very similar to fetchFromGitHub above.
This is used with repo.or.cz repositories. The arguments expected are very
similar to fetchFromGitHub above.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>

5
doc/functions/library.xml
View file

@ -16,9 +16,14 @@
<!-- These docs are generated via nixdoc. To add another generated
library function file to this list, the file
`lib-function-docs.nix` must also be updated. -->
<xi:include href="./library/generated/strings.xml" />
<xi:include href="./library/generated/trivial.xml" />
<xi:include href="./library/generated/lists.xml" />
<xi:include href="./library/generated/debug.xml" />
<xi:include href="./library/generated/options.xml" />
</section>

20
doc/functions/nix-gitignore.xml
View file

@ -17,9 +17,9 @@
<literal>pkgs.nix-gitignore</literal> exports a number of functions, but
you'll most likely need either <literal>gitignoreSource</literal> or
<literal>gitignoreSourcePure</literal>. As their first argument, they both
accept either 1. a file with gitignore lines or 2. a string
with gitignore lines, or 3. a list of either of the two. They will be
concatenated into a single big string.
accept either 1. a file with gitignore lines or 2. a string with gitignore
lines, or 3. a list of either of the two. They will be concatenated into a
single big string.
</para>
<programlisting><![CDATA[
@ -40,8 +40,8 @@
]]></programlisting>
<para>
These functions are derived from the <literal>Filter</literal> functions
by setting the first filter argument to <literal>(_: _: true)</literal>:
These functions are derived from the <literal>Filter</literal> functions by
setting the first filter argument to <literal>(_: _: true)</literal>:
</para>
<programlisting><![CDATA[
@ -50,7 +50,12 @@ gitignoreSource = gitignoreFilterSource (_: _: true);
]]></programlisting>
<para>
Those filter functions accept the same arguments the <literal>builtins.filterSource</literal> function would pass to its filters, thus <literal>fn: gitignoreFilterSourcePure fn ""</literal> should be extensionally equivalent to <literal>filterSource</literal>. The file is blacklisted iff it's blacklisted by either your filter or the gitignoreFilter.
Those filter functions accept the same arguments the
<literal>builtins.filterSource</literal> function would pass to its filters,
thus <literal>fn: gitignoreFilterSourcePure fn ""</literal> should be
extensionally equivalent to <literal>filterSource</literal>. The file is
blacklisted iff it's blacklisted by either your filter or the
gitignoreFilter.
</para>
<para>
@ -66,7 +71,8 @@ gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
<title>gitignore files in subdirectories</title>
<para>
If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:
If you wish to use a filter that would search for .gitignore files in
subdirectories, just like git does by default, use this function:
</para>
<programlisting><![CDATA[

18
doc/functions/prefer-remote-fetch.xml
View file

@ -7,21 +7,19 @@
<para>
<function>prefer-remote-fetch</function> is an overlay that download sources
on remote builder. This is useful when the evaluating machine has a slow
upload while the builder can fetch faster directly from the source.
To use it, put the following snippet as a new overlay:
upload while the builder can fetch faster directly from the source. To use
it, put the following snippet as a new overlay:
<programlisting>
self: super:
(super.prefer-remote-fetch self super)
</programlisting>
A full configuration example for that sets the overlay up for your own account,
could look like this
<programlisting>
$ mkdir ~/.config/nixpkgs/overlays/
$ cat &gt; ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix &lt;&lt;EOF
A full configuration example for that sets the overlay up for your own
account, could look like this
<screen>
<prompt>$ </prompt>mkdir ~/.config/nixpkgs/overlays/
<prompt>$ </prompt>cat &gt; ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix &lt;&lt;EOF
self: super: super.prefer-remote-fetch self super
EOF
</programlisting>
</screen>
</para>
</section>

28
doc/functions/snap/example-firefox.nix Normal file
View file

@ -0,0 +1,28 @@
let
inherit (import <nixpkgs> { }) snapTools firefox;
in snapTools.makeSnap {
meta = {
name = "nix-example-firefox";
summary = firefox.meta.description;
architectures = [ "amd64" ];
apps.nix-example-firefox = {
command = "${firefox}/bin/firefox";
plugs = [
"pulseaudio"
"camera"
"browser-support"
"avahi-observe"
"cups-control"
"desktop"
"desktop-legacy"
"gsettings"
"home"
"network"
"mount-observe"
"removable-media"
"x11"
];
};
confinement = "strict";
};
}

12
doc/functions/snap/example-hello.nix Normal file
View file

@ -0,0 +1,12 @@
let
inherit (import <nixpkgs> { }) snapTools hello;
in snapTools.makeSnap {
meta = {
name = "hello";
summary = hello.meta.description;
description = hello.meta.longDescription;
architectures = [ "amd64" ];
confinement = "strict";
apps.hello.command = "${hello}/bin/hello";
};
}

74
doc/functions/snaptools.xml Normal file
View file

@ -0,0 +1,74 @@
<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-snapTools">
<title>pkgs.snapTools</title>
<para>
<varname>pkgs.snapTools</varname> is a set of functions for creating
Snapcraft images. Snap and Snapcraft is not used to perform these operations.
</para>
<section xml:id="ssec-pkgs-snapTools-makeSnap-signature">
<title>The makeSnap Function</title>
<para>
<function>makeSnap</function> takes a single named argument,
<parameter>meta</parameter>. This argument mirrors
<link xlink:href="https://docs.snapcraft.io/snap-format">the upstream
<filename>snap.yaml</filename> format</link> exactly.
</para>
<para>
The <parameter>base</parameter> should not be be specified, as
<function>makeSnap</function> will force set it.
</para>
<para>
Currently, <function>makeSnap</function> does not support creating GUI
stubs.
</para>
</section>
<section xml:id="ssec-pkgs-snapTools-build-a-snap-hello">
<title>Build a Hello World Snap</title>
<example xml:id="ex-snapTools-buildSnap-hello">
<title>Making a Hello World Snap</title>
<para>
The following expression packages GNU Hello as a Snapcraft snap.
</para>
<programlisting><xi:include href="./snap/example-hello.nix" parse="text" /></programlisting>
<para>
<command>nix-build</command> this expression and install it with
<command>snap install ./result --dangerous</command>.
<command>hello</command> will now be the Snapcraft version of the package.
</para>
</example>
</section>
<section xml:id="ssec-pkgs-snapTools-build-a-snap-firefox">
<title>Build a Hello World Snap</title>
<example xml:id="ex-snapTools-buildSnap-firefox">
<title>Making a Graphical Snap</title>
<para>
Graphical programs require many more integrations with the host. This
example uses Firefox as an example, because it is one of the most
complicated programs we could package.
</para>
<programlisting><xi:include href="./snap/example-firefox.nix" parse="text" /></programlisting>
<para>
<command>nix-build</command> this expression and install it with
<command>snap install ./result --dangerous</command>.
<command>nix-example-firefox</command> will now be the Snapcraft version of
the Firefox package.
</para>
<para>
The specific meaning behind plugs can be looked up in the
<link xlink:href="https://docs.snapcraft.io/supported-interfaces">Snapcraft
interface documentation</link>.
</para>
</example>
</section>
</section>

87
doc/functions/trivial-builders.xml
View file

@ -5,12 +5,11 @@
<title>Trivial builders</title>
<para>
Nixpkgs provides a couple of functions that help with building
derivations. The most important one,
<function>stdenv.mkDerivation</function>, has already been
documented above. The following functions wrap
<function>stdenv.mkDerivation</function>, making it easier to use
in certain cases.
Nixpkgs provides a couple of functions that help with building derivations.
The most important one, <function>stdenv.mkDerivation</function>, has already
been documented above. The following functions wrap
<function>stdenv.mkDerivation</function>, making it easier to use in certain
cases.
</para>
<variablelist>
@ -22,21 +21,18 @@
<para>
This takes three arguments, <literal>name</literal>,
<literal>env</literal>, and <literal>buildCommand</literal>.
<literal>name</literal> is just the name that Nix will append
to the store path in the same way that
<literal>stdenv.mkDerivation</literal> uses its
<literal>name</literal> attribute. <literal>env</literal> is an
attribute set specifying environment variables that will be set
for this derivation. These attributes are then passed to the
wrapped <literal>stdenv.mkDerivation</literal>.
<literal>buildCommand</literal> specifies the commands that
will be run to create this derivation. Note that you will need
to create <literal>$out</literal> for Nix to register the
command as successful.
<literal>name</literal> is just the name that Nix will append to the store
path in the same way that <literal>stdenv.mkDerivation</literal> uses its
<literal>name</literal> attribute. <literal>env</literal> is an attribute
set specifying environment variables that will be set for this derivation.
These attributes are then passed to the wrapped
<literal>stdenv.mkDerivation</literal>. <literal>buildCommand</literal>
specifies the commands that will be run to create this derivation. Note
that you will need to create <literal>$out</literal> for Nix to register
the command as successful.
</para>
<para>
An example of using <literal>runCommand</literal> is provided
below.
An example of using <literal>runCommand</literal> is provided below.
</para>
<programlisting>
(import &lt;nixpkgs&gt; {}).runCommand "my-example" {} ''
@ -66,39 +62,33 @@
</term>
<listitem>
<para>
This works just like <literal>runCommand</literal>. The only
difference is that it also provides a C compiler in
<literal>buildCommand</literal>’s environment. To minimize your
dependencies, you should only use this if you are sure you will
need a C compiler as part of running your command.
This works just like <literal>runCommand</literal>. The only difference is
that it also provides a C compiler in <literal>buildCommand</literal>’s
environment. To minimize your dependencies, you should only use this if
you are sure you will need a C compiler as part of running your command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>writeTextFile</literal>, <literal>writeText</literal>,
<literal>writeTextDir</literal>, <literal>writeScript</literal>,
<literal>writeScriptBin</literal>
<literal>writeTextFile</literal>, <literal>writeText</literal>, <literal>writeTextDir</literal>, <literal>writeScript</literal>, <literal>writeScriptBin</literal>
</term>
<listitem>
<para>
These functions write <literal>text</literal> to the Nix store.
This is useful for creating scripts from Nix expressions.
<literal>writeTextFile</literal> takes an attribute set and
expects two arguments, <literal>name</literal> and
<literal>text</literal>. <literal>name</literal> corresponds to
the name used in the Nix store path. <literal>text</literal>
will be the contents of the file. You can also set
<literal>executable</literal> to true to make this file have
the executable bit set.
These functions write <literal>text</literal> to the Nix store. This is
useful for creating scripts from Nix expressions.
<literal>writeTextFile</literal> takes an attribute set and expects two
arguments, <literal>name</literal> and <literal>text</literal>.
<literal>name</literal> corresponds to the name used in the Nix store
path. <literal>text</literal> will be the contents of the file. You can
also set <literal>executable</literal> to true to make this file have the
executable bit set.
</para>
<para>
Many more commands wrap <literal>writeTextFile</literal>
including <literal>writeText</literal>,
<literal>writeTextDir</literal>,
<literal>writeScript</literal>, and
<literal>writeScriptBin</literal>. These are convenience
functions over <literal>writeTextFile</literal>.
Many more commands wrap <literal>writeTextFile</literal> including
<literal>writeText</literal>, <literal>writeTextDir</literal>,
<literal>writeScript</literal>, and <literal>writeScriptBin</literal>.
These are convenience functions over <literal>writeTextFile</literal>.
</para>
</listitem>
</varlistentry>
@ -109,16 +99,15 @@
<listitem>
<para>
This can be used to put many derivations into the same directory
structure. It works by creating a new derivation and adding
symlinks to each of the paths listed. It expects two arguments,
structure. It works by creating a new derivation and adding symlinks to
each of the paths listed. It expects two arguments,
<literal>name</literal>, and <literal>paths</literal>.
<literal>name</literal> is the name used in the Nix store path
for the created derivation. <literal>paths</literal> is a list of
paths that will be symlinked. These paths can be to Nix store
derivations or any other subdirectory contained within.
<literal>name</literal> is the name used in the Nix store path for the
created derivation. <literal>paths</literal> is a list of paths that will
be symlinked. These paths can be to Nix store derivations or any other
subdirectory contained within.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>

9
doc/languages-frameworks/android.section.md
View file

@ -185,10 +185,9 @@ with import <nixpkgs> {};
androidenv.emulateApp {
name = "emulate-MyAndroidApp";
platformVersion = "24";
abiVersion = "armeabi-v7a"; # mips, x86 or x86_64
systemImageType = "default";
useGoogleAPIs = false;
platformVersion = "28";
abiVersion = "x86_64"; # armeabi-v7a, mips, x86
systemImageType = "google_apis_playstore";
}
```
@ -201,7 +200,7 @@ with import <nixpkgs> {};
androidenv.emulateApp {
name = "emulate-MyAndroidApp";
platformVersion = "24";
abiVersion = "armeabi-v7a"; # mips, x86 or x86_64
abiVersion = "armeabi-v7a"; # mips, x86, x86_64
systemImageType = "default";
useGoogleAPIs = false;
app = ./MyApp.apk;

36
doc/languages-frameworks/beam.xml
View file

@ -131,8 +131,8 @@
in <literal>beamPackages</literal>, use the following command:
</para>
<programlisting>
$ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A beamPackages
<screen>
<prompt>$ </prompt>nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A beamPackages
beamPackages.esqlite esqlite-0.2.1
beamPackages.goldrush goldrush-0.1.7
beamPackages.ibrowse ibrowse-4.2.2
@ -140,16 +140,16 @@ beamPackages.jiffy jiffy-0.14.5
beamPackages.lager lager-3.0.2
beamPackages.meck meck-0.8.3
beamPackages.rebar3-pc pc-1.1.0
</programlisting>
</screen>
<para>
To install any of those packages into your profile, refer to them by their
attribute path (first column):
</para>
<programlisting>
$ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
</programlisting>
<screen>
<prompt>$ </prompt>nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
</screen>
<para>
The attribute path of any BEAM package corresponds to the name of that
@ -330,13 +330,13 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
could do the following:
</para>
<programlisting>
$ nix-shell -A beamPackages.ibrowse.env --run "erl"
Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false]
<screen>
<prompt>$ </prompt><userinput>nix-shell -A beamPackages.ibrowse.env --run "erl"</userinput>
<computeroutput>Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false]
Eshell V7.0 (abort with ^G)
1> m(ibrowse).
Module: ibrowse
Eshell V7.0 (abort with ^G)</computeroutput>
<prompt>1> </prompt><userinput>m(ibrowse).</userinput>
<computeroutput>Module: ibrowse
MD5: 3b3e0137d0cbb28070146978a3392945
Compiled: January 10 2016, 23:34
Object file: /nix/store/g1rlf65rdgjs4abbyj4grp37ry7ywivj-ibrowse-4.2.2/lib/erlang/lib/ibrowse-4.2.2/ebin/ibrowse.beam
@ -368,9 +368,9 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
send_req_direct/5 trace_off/2
send_req_direct/6 trace_on/0
trace_on/2
ok
2>
</programlisting>
ok</computeroutput>
<prompt>2></prompt>
</screen>
<para>
Notice the <literal>-A beamPackages.ibrowse.env</literal>. That is the key
@ -513,9 +513,9 @@ analyze: build plt
<literal>nixpkgs</literal> repository:
</para>
<programlisting>
$ nix-build -A beamPackages
</programlisting>
<screen>
<prompt>$ </prompt>nix-build -A beamPackages
</screen>
<para>
That will attempt to build every package in <literal>beamPackages</literal>.

71
doc/languages-frameworks/crystal.section.md Normal file
View file

@ -0,0 +1,71 @@
# Crystal
## Building a Crystal package
This section uses [Mint](https://github.com/mint-lang/mint) as an example for how to build a Crystal package.
If the Crystal project has any dependencies, the first step is to get a `shards.nix` file encoding those. Get a copy of the project and go to its root directory such that its `shard.lock` file is in the current directory, then run `crystal2nix` in it
```bash
$ git clone https://github.com/mint-lang/mint
$ cd mint
$ git checkout 0.5.0
$ nix-shell -p crystal2nix --run crystal2nix
```
This should have generated a `shards.nix` file.
Next create a Nix file for your derivation and use `pkgs.crystal.buildCrystalPackage` as follows:
```nix
with import <nixpkgs> {};
crystal.buildCrystalPackage rec {
pname = "mint";
version = "0.5.0";
src = fetchFromGitHub {
owner = "mint-lang";
repo = "mint";
rev = version;
sha256 = "0vxbx38c390rd2ysvbwgh89v2232sh5rbsp3nk9wzb70jybpslvl";
};
# Insert the path to your shards.nix file here
shardsFile = ./shards.nix;
...
}
```
This won't build anything yet, because we haven't told it what files build. We can specify a mapping from binary names to source files with the `crystalBinaries` attribute. The project's compilation instructions should show this. For Mint, the binary is called "mint", which is compiled from the source file `src/mint.cr`, so we'll specify this as follows:
```nix
crystalBinaries.mint.src = "src/mint.cr";
# ...
```
Additionally you can override the default `crystal build` options (which are currently `--release --progress --no-debug --verbose`) with
```nix
crystalBinaries.mint.options = [ "--release" "--verbose" ];
```
Depending on the project, you might need additional steps to get it to compile successfully. In Mint's case, we need to link against openssl, so in the end the Nix file looks as follows:
```nix
with import <nixpkgs> {};
crystal.buildCrystalPackage rec {
version = "0.5.0";
pname = "mint";
src = fetchFromGitHub {
owner = "mint-lang";
repo = "mint";
rev = version;
sha256 = "0vxbx38c390rd2ysvbwgh89v2232sh5rbsp3nk9wzb70jybpslvl";
};
shardsFile = ./shards.nix;
crystalBinaries.mint.src = "src/mint.cr";
buildInputs = [ openssl_1_0_2 ];
}
```

99
doc/languages-frameworks/go.xml
View file

@ -3,8 +3,87 @@
xml:id="sec-language-go">
<title>Go</title>
<section xml:id="ssec-go-modules">
<title>Go modules</title>
<para>
The function <varname>buildGoPackage</varname> builds standard Go programs.
The function <varname> buildGoModule </varname> builds Go programs managed
with Go modules. It builds a
<link xlink:href="https://github.com/golang/go/wiki/Modules">Go
modules</link> through a two phase build:
<itemizedlist>
<listitem>
<para>
An intermediate fetcher derivation. This derivation will be used to fetch
all of the dependencies of the Go module.
</para>
</listitem>
<listitem>
<para>
A final derivation will use the output of the intermediate derivation to
build the binaries and produce the final output.
</para>
</listitem>
</itemizedlist>
</para>
<example xml:id='ex-buildGoModule'>
<title>buildGoModule</title>
<programlisting>
pet = buildGoModule rec {
name = "pet-${version}";
version = "0.3.4";
src = fetchFromGitHub {
owner = "knqyf263";
repo = "pet";
rev = "v${version}";
sha256 = "0m2fzpqxk7hrbxsgqplkg7h2p7gv6s1miymv3gvw0cz039skag0s";
};
modSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j"; <co xml:id='ex-buildGoModule-1' />
subPackages = [ "." ]; <co xml:id='ex-buildGoModule-2' />
meta = with lib; {
description = "Simple command-line snippet manager, written in Go";
homepage = https://github.com/knqyf263/pet;
license = licenses.mit;
maintainers = with maintainers; [ kalbasit ];
platforms = platforms.linux ++ platforms.darwin;
};
}
</programlisting>
</example>
<para>
<xref linkend='ex-buildGoModule'/> is an example expression using
buildGoModule, the following arguments are of special significance to the
function:
<calloutlist>
<callout arearefs='ex-buildGoModule-1'>
<para>
<varname>modSha256</varname> is the hash of the output of the
intermediate fetcher derivation.
</para>
</callout>
<callout arearefs='ex-buildGoModule-2'>
<para>
<varname>subPackages</varname> limits the builder from building child
packages that have not been listed. If <varname>subPackages</varname> is
not specified, all child packages will be built.
</para>
</callout>
</calloutlist>
</para>
</section>
<section xml:id="ssec-go-legacy">
<title>Go legacy</title>
<para>
The function <varname> buildGoPackage </varname> builds legacy Go programs,
not supporting Go modules.
</para>
<example xml:id='ex-buildGoPackage'>
@ -55,9 +134,9 @@ deis = buildGoPackage rec {
</callout>
<callout arearefs='ex-buildGoPackage-3'>
<para>
<varname>goDeps</varname> is where the Go dependencies of a Go program are
listed as a list of package source identified by Go import path. It could
be imported as a separate <varname>deps.nix</varname> file for
<varname>goDeps</varname> is where the Go dependencies of a Go program
are listed as a list of package source identified by Go import path. It
could be imported as a separate <varname>deps.nix</varname> file for
readability. The dependency data structure is described below.
</para>
</callout>
@ -117,9 +196,10 @@ deis = buildGoPackage rec {
</callout>
<callout arearefs='ex-goDeps-3'>
<para>
<varname>fetch type</varname> that needs to be used to get package source.
If <varname>git</varname> is used there should be <varname>url</varname>,
<varname>rev</varname> and <varname>sha256</varname> defined next to it.
<varname>fetch type</varname> that needs to be used to get package
source. If <varname>git</varname> is used there should be
<varname>url</varname>, <varname>rev</varname> and
<varname>sha256</varname> defined next to it.
</para>
</callout>
</calloutlist>
@ -138,11 +218,11 @@ deis = buildGoPackage rec {
<varname>bin</varname> includes program binaries. You can test build a Go
binary as follows:
<screen>
$ nix-build -A deis.bin
<prompt>$ </prompt>nix-build -A deis.bin
</screen>
or build all outputs with:
<screen>
$ nix-build -A deis.all
<prompt>$ </prompt>nix-build -A deis.all
</screen>
<varname>bin</varname> output will be installed by default with
<varname>nix-env -i</varname> or <varname>systemPackages</varname>.
@ -158,3 +238,4 @@ done
</screen>
</para>
</section>
</section>

10
doc/languages-frameworks/haskell.section.md
View file

@ -55,7 +55,7 @@ package `haskell-pandoc`, for example, installs both a library and an
application. You can install and use Haskell executables just like any other
program in Nixpkgs, but using Haskell libraries for development is a bit
trickier and we'll address that subject in great detail in section [How to
create a development environment].
create a development environment](#how-to-create-a-development-environment).
Attribute paths are deterministic inside of Nixpkgs, but the path necessary to
reach Nixpkgs varies from system to system. We dodged that problem by giving
@ -127,7 +127,7 @@ Also, the attributes `haskell.compiler.ghcXYC` and
A simple development environment consists of a Haskell compiler and one or both
of the tools `cabal-install` and `stack`. We saw in section
[How to install Haskell packages] how you can install those programs into your
[How to install Haskell packages](#how-to-install-haskell-packages) how you can install those programs into your
user profile:
```shell
nix-env -f "<nixpkgs>" -iA haskellPackages.ghc haskellPackages.cabal-install
@ -162,7 +162,7 @@ nix-shell -p haskell.compiler.ghc784
to bring GHC 7.8.4 into `$PATH`. Alternatively, you can use Stack instead of
`nix-shell` directly to select compiler versions and other build tools
per-project. It uses `nix-shell` under the hood when Nix support is turned on.
See [How to build a Haskell project using Stack].
See [How to build a Haskell project using Stack](#how-to-build-a-haskell-project-using-stack).
If you're using `cabal-install`, re-running `cabal configure` inside the spawned
shell switches your build to use that compiler instead. If you're working on
@ -366,7 +366,7 @@ automatically select the right version of GHC and other build tools to build,
test and execute apps in an existing project downloaded from somewhere on the
Internet. Pass the `--nix` flag to any `stack` command to do so, e.g.
```shell
git clone --recursive http://github.com/yesodweb/wai
git clone --recursive https://github.com/yesodweb/wai
cd wai
stack --nix build
```
@ -953,7 +953,7 @@ is essentially a "free software" license (BSD3), according to
paragraph 2 of the LGPL, GHC must be distributed under the terms of the LGPL!
To work around these problems GHC can be build with a slower but LGPL-free
alternative implemention for Integer called
alternative implementation for Integer called
[integer-simple](http://hackage.haskell.org/package/integer-simple).
To get a GHC compiler build with `integer-simple` instead of `integer-gmp` use

33
doc/languages-frameworks/idris.section.md
View file

@ -11,10 +11,21 @@ $ # On non-NixOS
$ nix-env -i nixpkgs.idris
```
This however only provides the `prelude` and `base` libraries. To install additional libraries:
This however only provides the `prelude` and `base` libraries. To install idris with additional libraries, you can use the `idrisPackages.with-packages` function, e.g. in an overlay in `~/.config/nixpkgs/overlays/my-idris.nix`:
```nix
self: super: {
myIdris = with self.idrisPackages; with-packages [ contrib pruviloj ];
}
```
And then:
```
$ nix-env -iE 'pkgs: pkgs.idrisPackages.with-packages (with pkgs.idrisPackages; [ contrib pruviloj ])'
$ # On NixOS
$ nix-env -iA nixos.myIdris
$ # On non-NixOS
$ nix-env -iA nixpkgs.myIdris
```
To see all available Idris packages:
@ -113,3 +124,21 @@ in another file (say `default.nix`) to be able to build it with
```
$ nix-build -A yaml
```
## Passing options to `idris` commands
The `build-idris-package` function provides also optional input values to set additional options for the used `idris` commands.
Specifically, you can set `idrisBuildOptions`, `idrisTestOptions`, `idrisInstallOptions` and `idrisDocOptions` to provide additional options to the `idris` command respectively when building, testing, installing and generating docs for your package.
For example you could set
```
build-idris-package {
idrisBuildOptions = [ "--log" "1" "--verbose" ]
...
}
```
to require verbose output during `idris` build phase.

1
doc/languages-frameworks/index.xml
View file

@ -32,4 +32,5 @@
<xi:include href="titanium.section.xml" />
<xi:include href="vim.section.xml" />
<xi:include href="emscripten.section.xml" />
<xi:include href="crystal.section.xml" />
</chapter>

9
doc/languages-frameworks/java.xml
View file

@ -10,7 +10,7 @@ stdenv.mkDerivation {
name = "...";
src = fetchurl { ... };
buildInputs = [ jdk ant ];
nativeBuildInputs = [ jdk ant ];
buildPhase = "ant";
}
@ -30,7 +30,8 @@ stdenv.mkDerivation {
<filename>foo.jar</filename> in its <filename>share/java</filename>
directory, and another package declares the attribute
<programlisting>
buildInputs = [ jdk libfoo ];
buildInputs = [ libfoo ];
nativeBuildInputs = [ jdk ];
</programlisting>
then <envar>CLASSPATH</envar> will be set to
<filename>/nix/store/...-libfoo/share/java/foo.jar</filename>.
@ -46,7 +47,7 @@ buildInputs = [ jdk libfoo ];
script to run it using the OpenJRE. You can use
<literal>makeWrapper</literal> for this:
<programlisting>
buildInputs = [ makeWrapper ];
nativeBuildInputs = [ makeWrapper ];
installPhase =
''
@ -76,7 +77,7 @@ installPhase =
It is possible to use a different Java compiler than <command>javac</command>
from the OpenJDK. For instance, to use the GNU Java Compiler:
<programlisting>
buildInputs = [ gcj ant ];
nativeBuildInputs = [ gcj ant ];
</programlisting>
Here, Ant will automatically use <command>gij</command> (the GNU Java
Runtime) instead of the OpenJRE.

42
doc/languages-frameworks/ocaml.xml
View file

@ -7,33 +7,32 @@
OCaml libraries should be installed in
<literal>$(out)/lib/ocaml/${ocaml.version}/site-lib/</literal>. Such
directories are automatically added to the <literal>$OCAMLPATH</literal>
environment variable when building another package that depends on them
or when opening a <literal>nix-shell</literal>.
environment variable when building another package that depends on them or
when opening a <literal>nix-shell</literal>.
</para>
<para>
Given that most of the OCaml ecosystem is now built with dune,
nixpkgs includes a convenience build support function called
<literal>buildDunePackage</literal> that will build an OCaml package
using dune, OCaml and findlib and any additional dependencies provided
as <literal>buildInputs</literal> or <literal>propagatedBuildInputs</literal>.
Given that most of the OCaml ecosystem is now built with dune, nixpkgs
includes a convenience build support function called
<literal>buildDunePackage</literal> that will build an OCaml package using
dune, OCaml and findlib and any additional dependencies provided as
<literal>buildInputs</literal> or <literal>propagatedBuildInputs</literal>.
</para>
<para>
Here is a simple package example. It defines an (optional) attribute
<literal>minimumOCamlVersion</literal> that will be used to throw a
descriptive evaluation error if building with an older OCaml is attempted.
It uses the <literal>fetchFromGitHub</literal> fetcher to get its source.
It sets the <literal>doCheck</literal> (optional) attribute to
<literal>true</literal> which means that tests will be run with
<literal>dune runtest -p angstrom</literal> after the build
(<literal>dune build -p angstrom</literal>) is complete.
It uses <literal>alcotest</literal> as a build input (because it is needed
to run the tests) and <literal>bigstringaf</literal> and
<literal>result</literal> as propagated build inputs (thus they will also
be available to libraries depending on this library).
The library will be installed using the <literal>angstrom.install</literal>
file that dune generates.
descriptive evaluation error if building with an older OCaml is attempted. It
uses the <literal>fetchFromGitHub</literal> fetcher to get its source. It
sets the <literal>doCheck</literal> (optional) attribute to
<literal>true</literal> which means that tests will be run with <literal>dune
runtest -p angstrom</literal> after the build (<literal>dune build -p
angstrom</literal>) is complete. It uses <literal>alcotest</literal> as a
build input (because it is needed to run the tests) and
<literal>bigstringaf</literal> and <literal>result</literal> as propagated
build inputs (thus they will also be available to libraries depending on this
library). The library will be installed using the
<literal>angstrom.install</literal> file that dune generates.
</para>
<programlisting>
@ -69,8 +68,8 @@ buildDunePackage rec {
Here is a second example, this time using a source archive generated with
<literal>dune-release</literal>. It is a good idea to use this archive when
it is available as it will usually contain substituted variables such as a
<literal>%%VERSION%%</literal> field. This library does not depend
on any other OCaml library and no tests are run after building it.
<literal>%%VERSION%%</literal> field. This library does not depend on any
other OCaml library and no tests are run after building it.
</para>
<programlisting>
@ -95,5 +94,4 @@ buildDunePackage rec {
};
}
</programlisting>
</section>

41
doc/languages-frameworks/perl.xml
View file

@ -47,13 +47,13 @@ foo = import ../path/to/foo.nix {
in <filename>all-packages.nix</filename>. You can test building a Perl
package as follows:
<screen>
$ nix-build -A perlPackages.ClassC3
<prompt>$ </prompt>nix-build -A perlPackages.ClassC3
</screen>
<varname>buildPerlPackage</varname> adds <literal>perl-</literal> to the
start of the name attribute, so the package above is actually called
<literal>perl-Class-C3-0.21</literal>. So to install it, you can say:
<screen>
$ nix-env -i perl-Class-C3
<prompt>$ </prompt>nix-env -i perl-Class-C3
</screen>
(Of course you can also install using the attribute name: <literal>nix-env -i
-A perlPackages.ClassC3</literal>.)
@ -75,7 +75,8 @@ $ nix-env -i perl-Class-C3
It adds the contents of the <envar>PERL5LIB</envar> environment variable
to <literal>#! .../bin/perl</literal> line of Perl scripts as
<literal>-I<replaceable>dir</replaceable></literal> flags. This ensures
that a script can find its dependencies.
that a script can find its dependencies. (This can cause this shebang line
to become too long for Darwin to handle; see the note below.)
</para>
</listitem>
<listitem>
@ -137,6 +138,36 @@ ClassC3Componentised = buildPerlPackage rec {
</programlisting>
</para>
<para>
On Darwin, if a script has too many
<literal>-I<replaceable>dir</replaceable></literal> flags in its first line
(its “shebang line”), it will not run. This can be worked around by calling
the <literal>shortenPerlShebang</literal> function from the
<literal>postInstall</literal> phase:
<programlisting>
{ stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
ImageExifTool = buildPerlPackage {
pname = "Image-ExifTool";
version = "11.50";
src = fetchurl {
url = "https://www.sno.phy.queensu.ca/~phil/exiftool/Image-ExifTool-11.50.tar.gz";
sha256 = "0d8v48y94z8maxkmw1rv7v9m0jg2dc8xbp581njb6yhr7abwqdv3";
};
buildInputs = stdenv.lib.optional stdenv.isDarwin shortenPerlShebang;
postInstall = stdenv.lib.optional stdenv.isDarwin ''
shortenPerlShebang $out/bin/exiftool
'';
};
</programlisting>
This will remove the <literal>-I</literal> flags from the shebang line,
rewrite them in the <literal>use lib</literal> form, and put them on the next
line instead. This function can be given any number of Perl scripts as
arguments; it will modify them in-place.
</para>
<section xml:id="ssec-generation-from-CPAN">
<title>Generation from CPAN</title>
@ -148,7 +179,7 @@ ClassC3Componentised = buildPerlPackage rec {
</para>
<screen>
$ nix-env -i nix-generate-from-cpan
<prompt>$ </prompt>nix-env -i nix-generate-from-cpan
</screen>
<para>
@ -156,7 +187,7 @@ $ nix-env -i nix-generate-from-cpan
unpacks the corresponding package, and prints a Nix expression on standard
output. For example:
<screen>
$ nix-generate-from-cpan XML::Simple
<prompt>$ </prompt>nix-generate-from-cpan XML::Simple
XMLSimple = buildPerlPackage rec {
name = "XML-Simple-2.22";
src = fetchurl {

100
doc/languages-frameworks/python.section.md
View file

@ -188,7 +188,7 @@ building Python libraries is `buildPythonPackage`. Let's see how we can build th
```nix
{ lib, buildPythonPackage, fetchPypi }:
toolz = buildPythonPackage rec {
buildPythonPackage rec {
pname = "toolz";
version = "0.7.4";
@ -205,7 +205,6 @@ building Python libraries is `buildPythonPackage`. Let's see how we can build th
license = licenses.bsd3;
maintainers = with maintainers; [ fridh ];
};
};
}
```
@ -279,9 +278,9 @@ The following example shows which arguments are given to `buildPythonPackage` in
order to build [`datashape`](https://github.com/blaze/datashape).
```nix
{ # ...
{ lib, buildPythonPackage, fetchPypi, numpy, multipledispatch, dateutil, pytest }:
datashape = buildPythonPackage rec {
buildPythonPackage rec {
pname = "datashape";
version = "0.4.7";
@ -290,8 +289,8 @@ order to build [`datashape`](https://github.com/blaze/datashape).
sha256 = "14b2ef766d4c9652ab813182e866f493475e65e558bed0822e38bf07bba1a278";
};
checkInputs = with self; [ pytest ];
propagatedBuildInputs = with self; [ numpy multipledispatch dateutil ];
checkInputs = [ pytest ];
propagatedBuildInputs = [ numpy multipledispatch dateutil ];
meta = with lib; {
homepage = https://github.com/ContinuumIO/datashape;
@ -299,12 +298,11 @@ order to build [`datashape`](https://github.com/blaze/datashape).
license = licenses.bsd2;
maintainers = with maintainers; [ fridh ];
};
};
}
```
We can see several runtime dependencies, `numpy`, `multipledispatch`, and
`dateutil`. Furthermore, we have one `buildInput`, i.e. `pytest`. `pytest` is a
`dateutil`. Furthermore, we have one `checkInputs`, i.e. `pytest`. `pytest` is a
test runner and is only used during the `checkPhase` and is therefore not added
to `propagatedBuildInputs`.
@ -314,9 +312,9 @@ Python bindings to `libxml2` and `libxslt`. These libraries are only required
when building the bindings and are therefore added as `buildInputs`.
```nix
{ # ...
{ lib, pkgs, buildPythonPackage, fetchPypi }:
lxml = buildPythonPackage rec {
buildPythonPackage rec {
pname = "lxml";
version = "3.4.4";
@ -325,7 +323,7 @@ when building the bindings and are therefore added as `buildInputs`.
sha256 = "16a0fa97hym9ysdk3rmqz32xdjqmy4w34ld3rm3jf5viqjx65lxk";
};
buildInputs = with self; [ pkgs.libxml2 pkgs.libxslt ];
buildInputs = [ pkgs.libxml2 pkgs.libxslt ];
meta = with lib; {
description = "Pythonic binding for the libxml2 and libxslt libraries";
@ -333,7 +331,6 @@ when building the bindings and are therefore added as `buildInputs`.
license = licenses.bsd3;
maintainers = with maintainers; [ sjourdois ];
};
};
}
```
@ -348,9 +345,9 @@ find each of them in a different folder, and therefore we have to set `LDFLAGS`
and `CFLAGS`.
```nix
{ # ...
{ lib, pkgs, buildPythonPackage, fetchPypi, numpy, scipy }:
pyfftw = buildPythonPackage rec {
buildPythonPackage rec {
pname = "pyFFTW";
version = "0.9.2";
@ -361,7 +358,7 @@ and `CFLAGS`.
buildInputs = [ pkgs.fftw pkgs.fftwFloat pkgs.fftwLongDouble];
propagatedBuildInputs = with self; [ numpy scipy ];
propagatedBuildInputs = [ numpy scipy ];
# Tests cannot import pyfftw. pyfftw works fine though.
doCheck = false;
@ -377,7 +374,6 @@ and `CFLAGS`.
license = with licenses; [ bsd2 bsd3 ];
maintainers = with maintainers; [ fridh ];
};
};
}
```
Note also the line `doCheck = false;`, we explicitly disabled running the test-suite.
@ -404,7 +400,7 @@ Indeed, we can just add any package we like to have in our environment to `propa
```nix
with import <nixpkgs> {};
with pkgs.python35Packages;
with python35Packages;
buildPythonPackage rec {
name = "mypackage";
@ -437,7 +433,7 @@ Let's split the package definition from the environment definition.
We first create a function that builds `toolz` in `~/path/to/toolz/release.nix`
```nix
{ lib, pkgs, buildPythonPackage }:
{ lib, buildPythonPackage }:
buildPythonPackage rec {
pname = "toolz";
@ -449,7 +445,7 @@ buildPythonPackage rec {
};
meta = with lib; {
homepage = "http://github.com/pytoolz/toolz/";
homepage = "https://github.com/pytoolz/toolz/";
description = "List processing tools and functional utilities";
license = licenses.bsd3;
maintainers = with maintainers; [ fridh ];
@ -457,18 +453,17 @@ buildPythonPackage rec {
}
```
It takes two arguments, `pkgs` and `buildPythonPackage`.
It takes an argument `buildPythonPackage`.
We now call this function using `callPackage` in the definition of our environment
```nix
with import <nixpkgs> {};
( let
toolz = pkgs.callPackage /path/to/toolz/release.nix {
pkgs = pkgs;
buildPythonPackage = pkgs.python35Packages.buildPythonPackage;
toolz = callPackage /path/to/toolz/release.nix {
buildPythonPackage = python35Packages.buildPythonPackage;
};
in pkgs.python35.withPackages (ps: [ ps.numpy toolz ])
in python35.withPackages (ps: [ ps.numpy toolz ])
).env
```
@ -515,7 +510,7 @@ Each interpreter has the following attributes:
### Building packages and applications
Python libraries and applications that use `setuptools` or
`distutils` are typically build with respectively the `buildPythonPackage` and
`distutils` are typically built with respectively the `buildPythonPackage` and
`buildPythonApplication` functions. These two functions also support installing a `wheel`.
All Python packages reside in `pkgs/top-level/python-packages.nix` and all
@ -566,7 +561,7 @@ buildPythonPackage rec {
'';
checkInputs = [ hypothesis ];
buildInputs = [ setuptools_scm ];
nativeBuildInputs = [ setuptools_scm ];
propagatedBuildInputs = [ attrs py setuptools six pluggy ];
meta = with lib; {
@ -586,11 +581,6 @@ The `buildPythonPackage` mainly does four things:
environment variable and add dependent libraries to script's `sys.path`.
* In the `installCheck` phase, `${python.interpreter} setup.py test` is ran.
As in Perl, dependencies on other Python packages can be specified in the
`buildInputs` and `propagatedBuildInputs` attributes. If something is
exclusively a build-time dependency, use `buildInputs`; if it is (also) a runtime
dependency, use `propagatedBuildInputs`.
By default tests are run because `doCheck = true`. Test dependencies, like
e.g. the test runner, should be added to `checkInputs`.
@ -602,19 +592,28 @@ as the interpreter unless overridden otherwise.
All parameters from `stdenv.mkDerivation` function are still supported. The following are specific to `buildPythonPackage`:
* `catchConflicts ? true`: If `true`, abort package build if a package name appears more than once in dependency tree. Default is `true`.
* `checkInputs ? []`: Dependencies needed for running the `checkPhase`. These are added to `buildInputs` when `doCheck = true`.
* `disabled` ? false: If `true`, package is not build for the particular Python interpreter version.
* `dontWrapPythonPrograms ? false`: Skip wrapping of python programs.
* `installFlags ? []`: A list of strings. Arguments to be passed to `pip install`. To pass options to `python setup.py install`, use `--install-option`. E.g., `installFlags=["--install-option='--cpp_implementation'"].
* `format ? "setuptools"`: Format of the source. Valid options are `"setuptools"`, `"flit"`, `"wheel"`, and `"other"`. `"setuptools"` is for when the source has a `setup.py` and `setuptools` is used to build a wheel, `flit`, in case `flit` should be used to build a wheel, and `wheel` in case a wheel is provided. Use `other` when a custom `buildPhase` and/or `installPhase` is needed.
* `permitUserSite ? false`: Skip setting the `PYTHONNOUSERSITE` environment variable in wrapped programs.
* `installFlags ? []`: A list of strings. Arguments to be passed to `pip install`. To pass options to `python setup.py install`, use `--install-option`. E.g., `installFlags=["--install-option='--cpp_implementation'"]`.
* `format ? "setuptools"`: Format of the source. Valid options are `"setuptools"`, `"pyproject"`, `"flit"`, `"wheel"`, and `"other"`. `"setuptools"` is for when the source has a `setup.py` and `setuptools` is used to build a wheel, `flit`, in case `flit` should be used to build a wheel, and `wheel` in case a wheel is provided. Use `other` when a custom `buildPhase` and/or `installPhase` is needed.
* `makeWrapperArgs ? []`: A list of strings. Arguments to be passed to `makeWrapper`, which wraps generated binaries. By default, the arguments to `makeWrapper` set `PATH` and `PYTHONPATH` environment variables before calling the binary. Additional arguments here can allow a developer to set environment variables which will be available when the binary is run. For example, `makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"]`.
* `namePrefix`: Prepends text to `${name}` parameter. In case of libraries, this defaults to `"python3.5-"` for Python 3.5, etc., and in case of applications to `""`.
* `pythonPath ? []`: List of packages to be added into `$PYTHONPATH`. Packages in `pythonPath` are not propagated (contrary to `propagatedBuildInputs`).
* `preShellHook`: Hook to execute commands before `shellHook`.
* `postShellHook`: Hook to execute commands after `shellHook`.
* `removeBinByteCode ? true`: Remove bytecode from `/bin`. Bytecode is only created when the filenames end with `.py`.
* `setupPyGlobalFlags ? []`: List of flags passed to `setup.py` command.
* `setupPyBuildFlags ? []`: List of flags passed to `setup.py build_ext` command.
The `stdenv.mkDerivation` function accepts various parameters for describing build inputs (see "Specifying dependencies"). The following are of special
interest for Python packages, either because these are primarily used, or because their behaviour is different:
* `nativeBuildInputs ? []`: Build-time only dependencies. Typically executables as well as the items listed in `setup_requires`.
* `buildInputs ? []`: Build and/or run-time dependencies that need to be be compiled for the host machine. Typically non-Python libraries which are being linked.
* `checkInputs ? []`: Dependencies needed for running the `checkPhase`. These are added to `nativeBuildInputs` when `doCheck = true`. Items listed in `tests_require` go here.
* `propagatedBuildInputs ? []`: Aside from propagating dependencies, `buildPythonPackage` also injects code into and wraps executables with the paths included in this list. Items listed in `install_requires` go here.
##### Overriding Python packages
The `buildPythonPackage` function has a `overridePythonAttrs` method that
@ -638,7 +637,7 @@ with import <nixpkgs> {};
};
});
};
in pkgs.python3.override {inherit packageOverrides;};
in pkgs.python3.override {inherit packageOverrides; self = python;};
in python.withPackages(ps: [ps.blaze])).env
```
@ -727,7 +726,7 @@ Saving the following as `default.nix`
with import <nixpkgs> {};
python.buildEnv.override {
extraLibs = [ pkgs.pythonPackages.pyramid ];
extraLibs = [ pythonPackages.pyramid ];
ignoreCollisions = true;
}
```
@ -759,6 +758,7 @@ specified packages in its path.
* `extraLibs`: List of packages installed inside the environment.
* `postBuild`: Shell command executed after the build of environment.
* `ignoreCollisions`: Ignore file collisions inside the environment (default is `false`).
* `permitUserSite`: Skip setting the `PYTHONNOUSERSITE` environment variable in wrapped binaries in the environment.
#### `python.withPackages` function
@ -809,11 +809,12 @@ Given a `default.nix`:
```nix
with import <nixpkgs> {};
buildPythonPackage { name = "myproject";
pythonPackages.buildPythonPackage {
name = "myproject";
buildInputs = with pythonPackages; [ pyramid ];
buildInputs = with pkgs.pythonPackages; [ pyramid ];
src = ./.; }
src = ./.;
}
```
Running `nix-shell` with no arguments should give you
@ -874,7 +875,6 @@ example of such a situation is when `py.test` is used.
'';
}
```
- Unicode issues can typically be fixed by including `glibcLocales` in `buildInputs` and exporting `LC_ALL=en_US.utf-8`.
- Tests that attempt to access `$HOME` can be fixed by using the following work-around before running tests (e.g. `preCheck`): `export HOME=$(mktemp -d)`
## FAQ
@ -1000,10 +1000,13 @@ Create this `default.nix` file, together with a `requirements.txt` and simply ex
```nix
with import <nixpkgs> {};
with pkgs.python27Packages;
with python27Packages;
stdenv.mkDerivation {
name = "impurePythonEnv";
src = null;
buildInputs = [
# these packages are required for virtualenv and pip to work:
#
@ -1023,8 +1026,9 @@ stdenv.mkDerivation {
libxslt
libzip
stdenv
zlib ];
src = null;
zlib
];
shellHook = ''
# set SOURCE_DATE_EPOCH so that we can use python wheels
SOURCE_DATE_EPOCH=$(date +%s)
@ -1123,6 +1127,14 @@ LLVM implementation. To use that one instead, Intel recommends users set it with
Note that `mkl` is only available on `x86_64-{linux,darwin}` platforms;
moreover, Hydra is not building and distributing pre-compiled binaries using it.
### What inputs do `setup_requires`, `install_requires` and `tests_require` map to?
In a `setup.py` or `setup.cfg` it is common to declare dependencies:
* `setup_requires` corresponds to `nativeBuildInputs`
* `install_requires` corresponds to `propagatedBuildInputs`
* `tests_require` corresponds to `checkInputs`
## Contributing
### Contributing guidelines

229
doc/languages-frameworks/qt.xml
View file

@ -4,71 +4,182 @@
<title>Qt</title>
<para>
Qt is a comprehensive desktop and mobile application development toolkit for
C++. Legacy support is available for Qt 3 and Qt 4, but all current
development uses Qt 5. The Qt 5 packages in Nixpkgs are updated frequently to
take advantage of new features, but older versions are typically retained
until their support window ends. The most important consideration in
packaging Qt-based software is ensuring that each package and all its
dependencies use the same version of Qt 5; this consideration motivates most
of the tools described below.
This section describes the differences between Nix expressions for Qt
libraries and applications and Nix expressions for other C++ software. Some
knowledge of the latter is assumed. There are primarily two problems which
the Qt infrastructure is designed to address: ensuring consistent versioning
of all dependencies and finding dependencies at runtime.
</para>
<section xml:id="ssec-qt-libraries">
<title>Packaging Libraries for Nixpkgs</title>
<example xml:id='qt-default-nix'>
<title>Nix expression for a Qt package (<filename>default.nix</filename>)</title>
<programlisting>
{ mkDerivation, lib, qtbase }: <co xml:id='qt-default-nix-co-1' />
mkDerivation { <co xml:id='qt-default-nix-co-2' />
pname = "myapp";
version = "1.0";
buildInputs = [ qtbase ]; <co xml:id='qt-default-nix-co-3' />
}
</programlisting>
</example>
<calloutlist>
<callout arearefs='qt-default-nix-co-1'>
<para>
Import <literal>mkDerivation</literal> and Qt (such as
<literal>qtbase</literal> modules directly. <emphasis>Do not</emphasis>
import Qt package sets; the Qt versions of dependencies may not be
coherent, causing build and runtime failures.
</para>
</callout>
<callout arearefs='qt-default-nix-co-2'>
<para>
Use <literal>mkDerivation</literal> instead of
<literal>stdenv.mkDerivation</literal>. <literal>mkDerivation</literal>
is a wrapper around <literal>stdenv.mkDerivation</literal> which
applies some Qt-specific settings.
This deriver accepts the same arguments as
<literal>stdenv.mkDerivation</literal>; refer to
<xref linkend='chap-stdenv' /> for details.
</para>
<para>
To use another deriver instead of
<literal>stdenv.mkDerivation</literal>, use
<literal>mkDerivationWith</literal>:
<programlisting>
mkDerivationWith myDeriver {
# ...
}
</programlisting>
If you cannot use <literal>mkDerivationWith</literal>, please refer to
<xref linkend='qt-runtime-dependencies' />.
</para>
</callout>
<callout arearefs='qt-default-nix-co-3'>
<para>
<literal>mkDerivation</literal> accepts the same arguments as
<literal>stdenv.mkDerivation</literal>, such as
<literal>buildInputs</literal>.
</para>
</callout>
</calloutlist>
<formalpara xml:id='qt-runtime-dependencies'>
<title>Locating runtime dependencies</title>
<para>
Qt applications need to be wrapped to find runtime dependencies. If you
cannot use <literal>mkDerivation</literal> or
<literal>mkDerivationWith</literal> above, include
<literal>wrapQtAppsHook</literal> in <literal>nativeBuildInputs</literal>:
<programlisting>
stdenv.mkDerivation {
# ...
nativeBuildInputs = [ wrapQtAppsHook ];
}
</programlisting>
</para>
</formalpara>
<para>
Whenever possible, libraries that use Qt 5 should be built with each
available version. Packages providing libraries should be added to the
top-level function <varname>mkLibsForQt5</varname>, which is used to build a
set of libraries for every Qt 5 version. A special
<varname>callPackage</varname> function is used in this scope to ensure that
the entire dependency tree uses the same Qt 5 version. Import dependencies
unqualified, i.e., <literal>qtbase</literal> not
<literal>qt5.qtbase</literal>. <emphasis>Do not</emphasis> import a package
set such as <literal>qt5</literal> or <literal>libsForQt5</literal>.
Entries added to <literal>qtWrapperArgs</literal> are used to modify the
wrappers created by <literal>wrapQtAppsHook</literal>. The entries are
passed as arguments to <xref linkend='fun-wrapProgram' />.
<programlisting>
mkDerivation {
# ...
qtWrapperArgs = [ ''--prefix PATH : /path/to/bin'' ];
}
</programlisting>
</para>
<para>
If a library does not support a particular version of Qt 5, it is best to
mark it as broken by setting its <literal>meta.broken</literal> attribute. A
package may be marked broken for certain versions by testing the
<literal>qtbase.version</literal> attribute, which will always give the
current Qt 5 version.
Set <literal>dontWrapQtApps</literal> to stop applications from being
wrapped automatically. It is required to wrap applications manually with
<literal>wrapQtApp</literal>, using the syntax of
<xref linkend='fun-wrapProgram' />:
<programlisting>
mkDerivation {
# ...
dontWrapQtApps = true;
preFixup = ''
wrapQtApp "$out/bin/myapp" --prefix PATH : /path/to/bin
'';
}
</programlisting>
</para>
</section>
<section xml:id="ssec-qt-applications">
<title>Packaging Applications for Nixpkgs</title>
<para>
Call your application expression using
<literal>libsForQt5.callPackage</literal> instead of
<literal>callPackage</literal>. Import dependencies unqualified, i.e.,
<literal>qtbase</literal> not <literal>qt5.qtbase</literal>. <emphasis>Do
not</emphasis> import a package set such as <literal>qt5</literal> or
<literal>libsForQt5</literal>.
</para>
<para>
Qt 5 maintains strict backward compatibility, so it is generally best to
build an application package against the latest version using the
<varname>libsForQt5</varname> library set. In case a package does not build
with the latest Qt version, it is possible to pick a set pinned to a
particular version, e.g. <varname>libsForQt55</varname> for Qt 5.5, if that
is the latest version the package supports. If a package must be pinned to
an older Qt version, be sure to file a bug upstream; because Qt is strictly
backwards-compatible, any incompatibility is by definition a bug in the
application.
</para>
<para>
When testing applications in Nixpkgs, it is a common practice to build the
package with <literal>nix-build</literal> and run it using the created
symbolic link. This will not work with Qt applications, however, because
they have many hard runtime requirements that can only be guaranteed if the
package is actually installed. To test a Qt application, install it with
<literal>nix-env</literal> or run it inside <literal>nix-shell</literal>.
</para>
</section>
<note>
<para>
<literal>wrapQtAppsHook</literal> ignores files that are non-ELF executables.
This means that scripts won't be automatically wrapped so you'll need to manually
wrap them as previously mentioned. An example of when you'd always need to do this
is with Python applications that use PyQT.
</para>
</note>
<para>
Libraries are built with every available version of Qt. Use the <literal>meta.broken</literal>
attribute to disable the package for unsupported Qt versions:
<programlisting>
mkDerivation {
# ...
# Disable this library with Qt &lt; 5.9.0
meta.broken = builtins.compareVersions qtbase.version "5.9.0" &lt; 0;
}
</programlisting>
</para>
<formalpara>
<title>Adding a library to Nixpkgs</title>
<para>
Add a Qt library to <filename>all-packages.nix</filename> by adding it to the
collection inside <literal>mkLibsForQt5</literal>. This ensures that the
library is built with every available version of Qt as needed.
<example xml:id='qt-library-all-packages-nix'>
<title>Adding a Qt library to <filename>all-packages.nix</filename></title>
<programlisting>
{
# ...
mkLibsForQt5 = self: with self; {
# ...
mylib = callPackage ../path/to/mylib {};
};
# ...
}
</programlisting>
</example>
</para>
</formalpara>
<formalpara>
<title>Adding an application to Nixpkgs</title>
<para>
Add a Qt application to <filename>all-packages.nix</filename> using
<literal>libsForQt5.callPackage</literal> instead of the usual
<literal>callPackage</literal>. The former ensures that all dependencies
are built with the same version of Qt.
<example xml:id='qt-application-all-packages-nix'>
<title>Adding a Qt application to <filename>all-packages.nix</filename></title>
<programlisting>
{
# ...
myapp = libsForQt5.callPackage ../path/to/myapp/ {};
# ...
}
</programlisting>
</example>
</para>
</formalpara>
</section>

6
doc/languages-frameworks/rust.section.md
View file

@ -336,9 +336,9 @@ with import <nixpkgs> {};
let src = fetchFromGitHub {
owner = "mozilla";
repo = "nixpkgs-mozilla";
# commit from: 2018-03-27
rev = "2945b0b6b2fd19e7d23bac695afd65e320efcebe";
sha256 = "034m1dryrzh2lmjvk3c0krgip652dql46w5yfwpvh7gavd3iypyw";
# commit from: 2019-05-15
rev = "9f35c4b09fd44a77227e79ff0c1b4b6a69dff533";
sha256 = "18h0nvh55b5an4gmlgfbvwbyqj91bklf1zymis6lbdh75571qaz0";
};
in
with import "${src.out}/rust-overlay.nix" pkgs pkgs;

78
doc/languages-frameworks/vim.section.md
View file

@ -21,7 +21,7 @@ At the moment we support three different methods for managing plugins:
Adding custom .vimrc lines can be done using the following code:
```
```nix
vim_configurable.customize {
# `name` specifies the name of the executable and package
name = "vim-with-plugins";
@ -32,11 +32,11 @@ vim_configurable.customize {
}
```
This configuration is used when vim is invoked with the command specified as name, in this case `vim-with-plugins`.
This configuration is used when Vim is invoked with the command specified as name, in this case `vim-with-plugins`.
For Neovim the `configure` argument can be overridden to achieve the same:
```
```nix
neovim.override {
configure = {
customRC = ''
@ -46,10 +46,10 @@ neovim.override {
}
```
If you want to use `neovim-qt` as a graphical editor, you can configure it by overriding neovim in an overlay
or passing it an overridden neovimn:
If you want to use `neovim-qt` as a graphical editor, you can configure it by overriding Neovim in an overlay
or passing it an overridden Neovimn:
```
```nix
neovim-qt.override {
neovim = neovim.override {
configure = {
@ -63,15 +63,15 @@ neovim-qt.override {
## Managing plugins with Vim packages
To store you plugins in Vim packages (the native vim plugin manager, see `:help packages`) the following example can be used:
To store you plugins in Vim packages (the native Vim plugin manager, see `:help packages`) the following example can be used:
```
```nix
vim_configurable.customize {
vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
# loaded on launch
start = [ youcompleteme fugitive ];
# manually loadable by calling `:packadd $plugin-name`
# however, if a vim plugin has a dependency that is not explicitly listed in
# however, if a Vim plugin has a dependency that is not explicitly listed in
# opt that dependency will always be added to start to avoid confusion.
opt = [ phpCompletion elm-vim ];
# To automatically load a plugin when opening a filetype, add vimrc lines like:
@ -83,7 +83,7 @@ vim_configurable.customize {
`myVimPackage` is an arbitrary name for the generated package. You can choose any name you like.
For Neovim the syntax is:
```
```nix
neovim.override {
configure = {
customRC = ''
@ -92,7 +92,7 @@ neovim.override {
packages.myVimPackage = with pkgs.vimPlugins; {
# see examples below how to use custom packages
start = [ ];
# If a vim plugin has a dependency that is not explicitly listed in
# If a Vim plugin has a dependency that is not explicitly listed in
# opt that dependency will always be added to start to avoid confusion.
opt = [ ];
};
@ -102,7 +102,7 @@ neovim.override {
The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable:
```
```nix
{
packageOverrides = pkgs: with pkgs; {
myVim = vim_configurable.customize {
@ -126,7 +126,7 @@ After that you can install your special grafted `myVim` or `myNeovim` packages.
To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim
plugins the following example can be used:
```
```nix
vim_configurable.customize {
vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
# loaded on launch
@ -137,7 +137,7 @@ vim_configurable.customize {
For Neovim the syntax is:
```
```nix
neovim.override {
configure = {
customRC = ''
@ -161,21 +161,28 @@ assuming that "using latest version" is ok most of the time.
First create a vim-scripts file having one plugin name per line. Example:
```
"tlib"
{'name': 'vim-addon-sql'}
{'filetype_regex': '\%(vim)$', 'names': ['reload', 'vim-dev-plugin']}
```
Such vim-scripts file can be read by VAM as well like this:
```vim
call vam#Scripts(expand('~/.vim-scripts'), {})
```
Create a default.nix file:
```nix
{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
nixpkgs.vim_configurable.customize { name = "vim"; vimrcConfig.vam.pluginDictionaries = [ "vim-addon-vim2nix" ]; }
```
Create a generate.vim file:
```vim
ActivateAddons vim-addon-vim2nix
let vim_scripts = "vim-scripts"
call nix#ExportPluginsForNix({
@ -184,14 +191,18 @@ Create a generate.vim file:
\ 'try_catch': 0,
\ 'plugin_dictionaries': ["vim-addon-manager"]+map(readfile(vim_scripts), 'eval(v:val)')
\ })
```
Then run
```bash
nix-shell -p vimUtils.vim_with_vim2nix --command "vim -c 'source generate.vim'"
```
You should get a Vim buffer with the nix derivations (output1) and vam.pluginDictionaries (output2).
You can add your vim to your system's configuration file like this and start it by "vim-my":
You can add your Vim to your system's configuration file like this and start it by "vim-my":
```
my-vim =
let plugins = let inherit (vimUtils) buildVimPluginFrom2Nix; in {
copy paste output1 here
@ -207,10 +218,11 @@ You can add your vim to your system's configuration file like this and start it
# vimrcConfig.pathogen.knownPlugins = plugins; # plugins
# vimrcConfig.pathogen.pluginNames = ["tlib"];
};
```
Sample output1:
```
"reload" = buildVimPluginFrom2Nix { # created by nix#NixDerivation
name = "reload";
src = fetchgit {
@ -222,34 +234,44 @@ Sample output1:
};
[...]
```
Sample output2:
```nix
[
''vim-addon-manager''
''tlib''
{ "name" = ''vim-addon-sql''; }
{ "filetype_regex" = ''\%(vim)$$''; "names" = [ ''reload'' ''vim-dev-plugin'' ]; }
]
```
## Adding new plugins to nixpkgs
In `pkgs/misc/vim-plugins/vim-plugin-names` we store the plugin names
for all vim plugins we automatically generate plugins for.
The format of this file `github username/github repository`:
For example https://github.com/scrooloose/nerdtree becomes `scrooloose/nerdtree`.
After adding your plugin to this file run the `./update.py` in the same folder.
This will updated a file called `generated.nix` and make your plugin accessible in the
`vimPlugins` attribute set (`vimPlugins.nerdtree` in our example).
If additional steps to the build process of the plugin are required, add an
override to the `pkgs/misc/vim-plugins/default.nix` in the same directory.
Nix expressions for Vim plugins are stored in [pkgs/misc/vim-plugins](/pkgs/misc/vim-plugins). For the vast majority of plugins, Nix expressions are automatically generated by running [`./update.py`](/pkgs/misc/vim-plugins/update.py). This creates a [generated.nix](/pkgs/misc/vim-plugins/generated.nix) file based on the plugins listed in [vim-plugin-names](/pkgs/misc/vim-plugins/vim-plugin-names). Plugins are listed in alphabetical order in `vim-plugin-names` using the format `[github username]/[repository]`. For example https://github.com/scrooloose/nerdtree becomes `scrooloose/nerdtree`.
Some plugins require overrides in order to function properly. Overrides are placed in [overrides.nix](/pkgs/misc/vim-plugins/overrides.nix). Overrides are most often required when a plugin requires some dependencies, or extra steps are required during the build process. For example `deoplete-fish` requires both `deoplete-nvim` and `vim-fish`, and so the following override was added:
```
deoplete-fish = super.deoplete-fish.overrideAttrs(old: {
dependencies = with super; [ deoplete-nvim vim-fish ];
});
```
Sometimes plugins require an override that must be changed when the plugin is updated. This can cause issues when Vim plugins are auto-updated but the associated override isn't updated. For these plugins, the override should be written so that it specifies all information required to install the plugin, and running `./update.py` doesn't change the derivation for the plugin. Manually updating the override is required to update these types of plugins. An example of such a plugin is `LanguageClient-neovim`.
To add a new plugin:
1. run `./update.py` and create a commit named "vimPlugins: Update",
2. add the new plugin to [vim-plugin-names](/pkgs/misc/vim-plugins/vim-plugin-names) and add overrides if required to [overrides.nix](/pkgs/misc/vim-plugins/overrides.nix),
3. run `./update.py` again and create a commit named "vimPlugins.[name]: init at [version]" (where `name` and `version` can be found in [generated.nix](/pkgs/misc/vim-plugins/generated.nix)), and
4. create a pull request.
## Important repositories
- [vim-pi](https://bitbucket.org/vimcommunity/vim-pi) is a plugin repository
from VAM plugin manager meant to be used by others as well used by
- [vim2nix](http://github.com/MarcWeber/vim-addon-vim2nix) which generates the
- [vim2nix](https://github.com/MarcWeber/vim-addon-vim2nix) which generates the
.nix code

3
doc/manual.xml
View file

@ -1,12 +1,13 @@
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude">
<info>
<title>Nixpkgs Contributors Guide</title>
<title>Nixpkgs Users and Contributors Guide</title>
<subtitle>Version <xi:include href=".version" parse="text" />
</subtitle>
</info>
<xi:include href="introduction.chapter.xml" />
<xi:include href="quick-start.xml" />
<xi:include href="package-specific-user-notes.xml" />
<xi:include href="stdenv.xml" />
<xi:include href="multiple-output.xml" />
<xi:include href="cross-compilation.xml" />

25
doc/meta.xml
View file

@ -30,7 +30,7 @@ meta = with stdenv.lib; {
The meta-attributes of a package can be queried from the command-line using
<command>nix-env</command>:
<screen>
$ nix-env -qa hello --json
<prompt>$ </prompt>nix-env -qa hello --json
{
"hello": {
"meta": {
@ -70,7 +70,7 @@ $ nix-env -qa hello --json
<command>nix-env</command> knows about the <varname>description</varname>
field specifically:
<screen>
$ nix-env -qa hello --description
<prompt>$ </prompt>nix-env -qa hello --description
hello-2.3 A program that produces a familiar, friendly greeting
</screen>
</para>
@ -150,6 +150,19 @@ hello-2.3 A program that produces a familiar, friendly greeting
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>changelog</varname>
</term>
<listitem>
<para>
A link or a list of links to the location of Changelog for a package.
A link may use expansion to refer to the correct changelog version.
Example:
<literal>"https://git.savannah.gnu.org/cgit/hello.git/plain/NEWS?h=v${version}"</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>license</varname>
@ -259,11 +272,9 @@ meta.platforms = stdenv.lib.platforms.linux;
<para>
This attribute is special in that it is not actually under the
<literal>meta</literal> attribute set but rather under the
<literal>passthru</literal> attribute set. This is due to a current
limitation of Nix, and will change as soon as Nixpkgs will be able to
depend on a new enough version of Nix. See
<link xlink:href="https://github.com/NixOS/nix/issues/2532">the relevant
issue</link> for more details.
<literal>passthru</literal> attribute set. This is due to how
<literal>meta</literal> attributes work, and the fact that they
are supposed to contain only metadata, not derivations.
</para>
</warning>
<para>

7
doc/multiple-output.xml
View file

@ -101,6 +101,13 @@
contain <varname>$outputBin</varname> and <varname>$outputLib</varname> are
also added. (See <xref linkend="multiple-output-file-type-groups" />.)
</para>
<para>
In some cases it may be desirable to combine different outputs under a
single store path. A function <literal>symlinkJoin</literal> can be used to
do this. (Note that it may negate some closure size benefits of using a
multiple-output package.)
</para>
</section>
<section xml:id="sec-multiple-outputs-">
<title>Writing a split derivation</title>

455
doc/package-notes.xml
View file

@ -92,9 +92,9 @@ modulesTree = [kernel]
<para>
If needed you can also run <literal>make menuconfig</literal>:
<screen>
$ nix-env -i ncurses
$ export NIX_CFLAGS_LINK=-lncurses
$ make menuconfig ARCH=<replaceable>arch</replaceable></screen>
<prompt>$ </prompt>nix-env -i ncurses
<prompt>$ </prompt>export NIX_CFLAGS_LINK=-lncurses
<prompt>$ </prompt>make menuconfig ARCH=<replaceable>arch</replaceable></screen>
</para>
</listitem>
<listitem>
@ -142,8 +142,8 @@ $ make menuconfig ARCH=<replaceable>arch</replaceable></screen>
<para>
The generator is invoked as follows:
<screen>
$ cd pkgs/servers/x11/xorg
$ cat tarballs-7.5.list extra.list old.list \
<prompt>$ </prompt>cd pkgs/servers/x11/xorg
<prompt>$ </prompt>cat tarballs-7.5.list extra.list old.list \
| perl ./generate-expr-from-tarballs.pl
</screen>
For each of the tarballs in the <filename>.list</filename> files, the script
@ -160,8 +160,8 @@ $ cat tarballs-7.5.list extra.list old.list \
A file like <filename>tarballs-7.5.list</filename> contains all tarballs in
a X.org release. It can be generated like this:
<screen>
$ export i="mirror://xorg/X11R7.4/src/everything/"
$ cat $(PRINT_PATH=1 nix-prefetch-url $i | tail -n 1) \
<prompt>$ </prompt>export i="mirror://xorg/X11R7.4/src/everything/"
<prompt>$ </prompt>cat $(PRINT_PATH=1 nix-prefetch-url $i | tail -n 1) \
| perl -e 'while (&lt;>) { if (/(href|HREF)="([^"]*.bz2)"/) { print "$ENV{'i'}$2\n"; }; }' \
| sort > tarballs-7.4.list
</screen>
@ -210,7 +210,7 @@ $ cat $(PRINT_PATH=1 nix-prefetch-url $i | tail -n 1) \
often available. It is possible to list available Eclipse packages by
issuing the command:
<screen>
$ nix-env -f '&lt;nixpkgs&gt;' -qaP -A eclipses --description
<prompt>$ </prompt>nix-env -f '&lt;nixpkgs&gt;' -qaP -A eclipses --description
</screen>
Once an Eclipse variant is installed it can be run using the
<command>eclipse</command> command, as expected. From within Eclipse it is
@ -250,7 +250,7 @@ packageOverrides = pkgs: {
available for installation using <varname>eclipseWithPlugins</varname> by
running
<screen>
$ nix-env -f '&lt;nixpkgs&gt;' -qaP -A eclipses.plugins --description
<prompt>$ </prompt>nix-env -f '&lt;nixpkgs&gt;' -qaP -A eclipses.plugins --description
</screen>
</para>
@ -307,19 +307,36 @@ packageOverrides = pkgs: {
</screen>
</para>
</section>
<section xml:id="sec-elm">
<title>Elm</title>
<para>
To update Elm compiler, see <filename>nixpkgs/pkgs/development/compilers/elm/README.md</filename>.
To start a development environment do <command>nix-shell -p elmPackages.elm elmPackages.elm-format</command>
</para>
<para>
To package Elm applications, <link xlink:href="https://github.com/hercules-ci/elm2nix#elm2nix">read about elm2nix</link>.
To update Elm compiler, see
<filename>nixpkgs/pkgs/development/compilers/elm/README.md</filename>.
</para>
<para>
To package Elm applications,
<link xlink:href="https://github.com/hercules-ci/elm2nix#elm2nix">read about
elm2nix</link>.
</para>
</section>
<section xml:id="sec-kakoune">
<title>Kakoune</title>
<para>
Kakoune can be built to autoload plugins:
<programlisting>(kakoune.override {
configure = {
plugins = with pkgs.kakounePlugins; [ parinfer-rust ];
};
})</programlisting>
</para>
</section>
<section xml:id="sec-shell-helpers">
<title>Interactive shell helpers</title>
@ -347,312 +364,6 @@ packageOverrides = pkgs: {
</screen>
</para>
</section>
<section xml:id="sec-steam">
<title>Steam</title>
<section xml:id="sec-steam-nix">
<title>Steam in Nix</title>
<para>
Steam is distributed as a <filename>.deb</filename> file, for now only as
an i686 package (the amd64 package only has documentation). When unpacked,
it has a script called <filename>steam</filename> that in ubuntu (their
target distro) would go to <filename>/usr/bin </filename>. When run for the
first time, this script copies some files to the user's home, which include
another script that is the ultimate responsible for launching the steam
binary, which is also in $HOME.
</para>
<para>
Nix problems and constraints:
<itemizedlist>
<listitem>
<para>
We don't have <filename>/bin/bash</filename> and many scripts point
there. Similarly for <filename>/usr/bin/python</filename> .
</para>
</listitem>
<listitem>
<para>
We don't have the dynamic loader in <filename>/lib </filename>.
</para>
</listitem>
<listitem>
<para>
The <filename>steam.sh</filename> script in $HOME can not be patched, as
it is checked and rewritten by steam.
</para>
</listitem>
<listitem>
<para>
The steam binary cannot be patched, it's also checked.
</para>
</listitem>
</itemizedlist>
</para>
<para>
The current approach to deploy Steam in NixOS is composing a FHS-compatible
chroot environment, as documented
<link xlink:href="http://sandervanderburg.blogspot.nl/2013/09/composing-fhs-compatible-chroot.html">here</link>.
This allows us to have binaries in the expected paths without disrupting
the system, and to avoid patching them to work in a non FHS environment.
</para>
</section>
<section xml:id="sec-steam-play">
<title>How to play</title>
<para>
For 64-bit systems it's important to have
<programlisting>hardware.opengl.driSupport32Bit = true;</programlisting>
in your <filename>/etc/nixos/configuration.nix</filename>. You'll also need
<programlisting>hardware.pulseaudio.support32Bit = true;</programlisting>
if you are using PulseAudio - this will enable 32bit ALSA apps integration.
To use the Steam controller or other Steam supported controllers such as
the DualShock 4 or Nintendo Switch Pro, you need to add
<programlisting>hardware.steam-hardware.enable = true;</programlisting>
to your configuration.
</para>
</section>
<section xml:id="sec-steam-troub">
<title>Troubleshooting</title>
<para>
<variablelist>
<varlistentry>
<term>
Steam fails to start. What do I do?
</term>
<listitem>
<para>
Try to run
<programlisting>strace steam</programlisting>
to see what is causing steam to fail.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Using the FOSS Radeon or nouveau (nvidia) drivers
</term>
<listitem>
<itemizedlist>
<listitem>
<para>
The <literal>newStdcpp</literal> parameter was removed since NixOS
17.09 and should not be needed anymore.
</para>
</listitem>
<listitem>
<para>
Steam ships statically linked with a version of libcrypto that
conflics with the one dynamically loaded by radeonsi_dri.so. If you
get the error
<programlisting>steam.sh: line 713: 7842 Segmentation fault (core dumped)</programlisting>
have a look at
<link xlink:href="https://github.com/NixOS/nixpkgs/pull/20269">this
pull request</link>.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>
Java
</term>
<listitem>
<orderedlist>
<listitem>
<para>
There is no java in steam chrootenv by default. If you get a message
like
<programlisting>/home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found</programlisting>
You need to add
<programlisting> steam.override { withJava = true; };</programlisting>
to your configuration.
</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<section xml:id="sec-steam-run">
<title>steam-run</title>
<para>
The FHS-compatible chroot used for steam can also be used to run other
linux games that expect a FHS environment. To do it, add
<programlisting>pkgs.(steam.override {
nativeOnly = true;
newStdcpp = true;
}).run</programlisting>
to your configuration, rebuild, and run the game with
<programlisting>steam-run ./foo</programlisting>
</para>
</section>
</section>
<section xml:id="sec-emacs">
<title>Emacs</title>
<section xml:id="sec-emacs-config">
<title>Configuring Emacs</title>
<para>
The Emacs package comes with some extra helpers to make it easier to
configure. <varname>emacsWithPackages</varname> allows you to manage
packages from ELPA. This means that you will not have to install that
packages from within Emacs. For instance, if you wanted to use
<literal>company</literal>, <literal>counsel</literal>,
<literal>flycheck</literal>, <literal>ivy</literal>,
<literal>magit</literal>, <literal>projectile</literal>, and
<literal>use-package</literal> you could use this as a
<filename>~/.config/nixpkgs/config.nix</filename> override:
</para>
<screen>
{
packageOverrides = pkgs: with pkgs; {
myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
company
counsel
flycheck
ivy
magit
projectile
use-package
]));
}
}
</screen>
<para>
You can install it like any other packages via <command>nix-env -iA
myEmacs</command>. However, this will only install those packages. It will
not <literal>configure</literal> them for us. To do this, we need to
provide a configuration file. Luckily, it is possible to do this from
within Nix! By modifying the above example, we can make Emacs load a custom
config file. The key is to create a package that provide a
<filename>default.el</filename> file in
<filename>/share/emacs/site-start/</filename>. Emacs knows to load this
file automatically when it starts.
</para>
<screen>
{
packageOverrides = pkgs: with pkgs; rec {
myEmacsConfig = writeText "default.el" ''
;; initialize package
(require 'package)
(package-initialize 'noactivate)
(eval-when-compile
(require 'use-package))
;; load some packages
(use-package company
:bind ("&lt;C-tab&gt;" . company-complete)
:diminish company-mode
:commands (company-mode global-company-mode)
:defer 1
:config
(global-company-mode))
(use-package counsel
:commands (counsel-descbinds)
:bind (([remap execute-extended-command] . counsel-M-x)
("C-x C-f" . counsel-find-file)
("C-c g" . counsel-git)
("C-c j" . counsel-git-grep)
("C-c k" . counsel-ag)
("C-x l" . counsel-locate)
("M-y" . counsel-yank-pop)))
(use-package flycheck
:defer 2
:config (global-flycheck-mode))
(use-package ivy
:defer 1
:bind (("C-c C-r" . ivy-resume)
("C-x C-b" . ivy-switch-buffer)
:map ivy-minibuffer-map
("C-j" . ivy-call))
:diminish ivy-mode
:commands ivy-mode
:config
(ivy-mode 1))
(use-package magit
:defer
:if (executable-find "git")
:bind (("C-x g" . magit-status)
("C-x G" . magit-dispatch-popup))
:init
(setq magit-completing-read-function 'ivy-completing-read))
(use-package projectile
:commands projectile-mode
:bind-keymap ("C-c p" . projectile-command-map)
:defer 5
:config
(projectile-global-mode))
'';
myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
(runCommand "default.el" {} ''
mkdir -p $out/share/emacs/site-lisp
cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
'')
company
counsel
flycheck
ivy
magit
projectile
use-package
]));
};
}
</screen>
<para>
This provides a fairly full Emacs start file. It will load in addition to
the user's presonal config. You can always disable it by passing
<command>-q</command> to the Emacs command.
</para>
<para>
Sometimes <varname>emacsWithPackages</varname> is not enough, as this
package set has some priorities imposed on packages (with the lowest
priority assigned to Melpa Unstable, and the highest for packages manually
defined in <filename>pkgs/top-level/emacs-packages.nix</filename>). But you
can't control this priorities when some package is installed as a
dependency. You can override it on per-package-basis, providing all the
required dependencies manually - but it's tedious and there is always a
possibility that an unwanted dependency will sneak in through some other
package. To completely override such a package you can use
<varname>overrideScope'</varname>.
</para>
<screen>
overrides = self: super: rec {
haskell-mode = self.melpaPackages.haskell-mode;
...
};
((emacsPackagesNgGen emacs).overrideScope' overrides).emacsWithPackages (p: with p; [
# here both these package will use haskell-mode of our own choice
ghc-mod
dante
])
</screen>
</section>
</section>
<section xml:id="sec-weechat">
<title>Weechat</title>
@ -757,64 +468,6 @@ stdenv.mkDerivation {
}</programlisting>
</para>
</section>
<section xml:id="sec-citrix">
<title>Citrix Receiver</title>
<para>
The <link xlink:href="https://www.citrix.com/products/receiver/">Citrix
Receiver</link> is a remote desktop viewer which provides access to
<link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link>
installations.
</para>
<section xml:id="sec-citrix-base">
<title>Basic usage</title>
<para>
The tarball archive needs to be downloaded manually as the licenses
agreements of the vendor need to be accepted first. This is available at
the
<link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">download
page at citrix.com</link>. Then run <literal>nix-prefetch-url
file://$PWD/linuxx64-$version.tar.gz</literal>. With the archive available
in the store the package can be built and installed with Nix.
</para>
<para>
<emphasis>Note: it's recommended to install <literal>Citrix
Receiver</literal> using <literal>nix-env -i</literal> or globally to
ensure that the <literal>.desktop</literal> files are installed properly
into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't be possible to
open <literal>.ica</literal> files automatically from the browser to start
a Citrix connection.</emphasis>
</para>
</section>
<section xml:id="sec-citrix-custom-certs">
<title>Custom certificates</title>
<para>
The <literal>Citrix Receiver</literal> in <literal>nixpkgs</literal> trusts
several certificates
<link xlink:href="https://curl.haxx.se/docs/caextract.html">from the
Mozilla database</link> by default. However several companies using Citrix
might require their own corporate certificate. On distros with imperative
packaging these certs can be stored easily in
<link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>,
however this directory is a store path in <literal>nixpkgs</literal>. In
order to work around this issue the package provides a simple mechanism to
add custom certificates without rebuilding the entire package using
<literal>symlinkJoin</literal>:
<programlisting>
<![CDATA[with import <nixpkgs> { config.allowUnfree = true; };
let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in
citrix_receiver.override {
inherit extraCerts;
}]]>
</programlisting>
</para>
</section>
</section>
<section xml:id="sec-ibus-typing-booster">
<title>ibus-engines.typing-booster</title>
@ -853,7 +506,7 @@ citrix_receiver.override {
<para>
The IBus engine is based on <literal>hunspell</literal> to support
completion in many languages. By default the dictionaries
<literal>de-de</literal>, <literal>en-us</literal>,
<literal>de-de</literal>, <literal>en-us</literal>, <literal>fr-moderne</literal>
<literal>es-es</literal>, <literal>it-it</literal>,
<literal>sv-se</literal> and <literal>sv-fi</literal> are in use. To add
another dictionary, the package can be overridden like this:
@ -886,4 +539,52 @@ citrix_receiver.override {
</para>
</section>
</section>
<section xml:id="sec-nginx">
<title>Nginx</title>
<para>
<link xlink:href="https://nginx.org/">Nginx</link> is a
reverse proxy and lightweight webserver.
</para>
<section xml:id="sec-nginx-etag">
<title>ETags on static files served from the Nix store</title>
<para>
HTTP has a couple different mechanisms for caching to prevent
clients from having to download the same content repeatedly
if a resource has not changed since the last time it was requested.
When nginx is used as a server for static files, it implements
the caching mechanism based on the
<link xlink:href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified"><literal>Last-Modified</literal></link>
response header automatically; unfortunately, it works by using
filesystem timestamps to determine the value of the
<literal>Last-Modified</literal> header. This doesn't give the
desired behavior when the file is in the Nix store, because all
file timestamps are set to 0 (for reasons related to build
reproducibility).
</para>
<para>
Fortunately, HTTP supports an alternative (and more effective)
caching mechanism: the
<link xlink:href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag"><literal>ETag</literal></link>
response header. The value of the <literal>ETag</literal> header
specifies some identifier for the particular content that the
server is sending (e.g. a hash). When a client makes a second
request for the same resource, it sends that value back in an
<literal>If-None-Match</literal> header. If the ETag value is
unchanged, then the server does not need to resend the content.
</para>
<para>
As of NixOS 19.09, the nginx package in Nixpkgs is patched such
that when nginx serves a file out of <filename>/nix/store</filename>,
the hash in the store path is used as the <literal>ETag</literal>
header in the HTTP response, thus providing proper caching functionality.
This happens automatically; you do not need to do modify any
configuration to get this behavior.
</para>
</section>
</section>
</chapter>

482
doc/package-specific-user-notes.xml Normal file
View file

@ -0,0 +1,482 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="package-specific-user-notes">
<title>Package-specific usage notes</title>
<para>
These chapters includes some notes
that apply to specific packages and should
answer some of the frequently asked questions
related to Nixpkgs use.
Some useful information related to package use
can be found in <link linkend="chap-package-notes">package-specific development notes</link>.
</para>
<section xml:id="opengl">
<title>OpenGL</title>
<para>
Packages that use OpenGL have NixOS desktop as their primary target. The
current solution for loading the GPU-specific drivers is based on
<literal>libglvnd</literal> and looks for the driver implementation in
<literal>LD_LIBRARY_PATH</literal>. If you are using a non-NixOS
GNU/Linux/X11 desktop with free software video drivers, consider launching
OpenGL-dependent programs from Nixpkgs with Nixpkgs versions of
<literal>libglvnd</literal> and <literal>mesa_drivers</literal> in
<literal>LD_LIBRARY_PATH</literal>. For proprietary video drivers you might
have luck with also adding the corresponding video driver package.
</para>
</section>
<section xml:id="locales">
<title>Locales</title>
<para>
To allow simultaneous use of packages linked against different versions of
<literal>glibc</literal> with different locale archive formats Nixpkgs
patches <literal>glibc</literal> to rely on
<literal>LOCALE_ARCHIVE</literal> environment variable.
</para>
<para>
On non-NixOS distributions this variable is obviously not set. This can
cause regressions in language support or even crashes in some
Nixpkgs-provided programs. The simplest way to mitigate this problem is
exporting the <literal>LOCALE_ARCHIVE</literal> variable pointing to
<literal>${glibcLocales}/lib/locale/locale-archive</literal>. The drawback
(and the reason this is not the default) is the relatively large (a hundred
MiB) size of the full set of locales. It is possible to build a custom set
of locales by overriding parameters <literal>allLocales</literal> and
<literal>locales</literal> of the package.
</para>
</section>
<section xml:id="sec-emacs">
<title>Emacs</title>
<section xml:id="sec-emacs-config">
<title>Configuring Emacs</title>
<para>
The Emacs package comes with some extra helpers to make it easier to
configure. <varname>emacsWithPackages</varname> allows you to manage
packages from ELPA. This means that you will not have to install that
packages from within Emacs. For instance, if you wanted to use
<literal>company</literal>, <literal>counsel</literal>,
<literal>flycheck</literal>, <literal>ivy</literal>,
<literal>magit</literal>, <literal>projectile</literal>, and
<literal>use-package</literal> you could use this as a
<filename>~/.config/nixpkgs/config.nix</filename> override:
</para>
<screen>
{
packageOverrides = pkgs: with pkgs; {
myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
company
counsel
flycheck
ivy
magit
projectile
use-package
]));
}
}
</screen>
<para>
You can install it like any other packages via <command>nix-env -iA
myEmacs</command>. However, this will only install those packages. It will
not <literal>configure</literal> them for us. To do this, we need to
provide a configuration file. Luckily, it is possible to do this from
within Nix! By modifying the above example, we can make Emacs load a custom
config file. The key is to create a package that provide a
<filename>default.el</filename> file in
<filename>/share/emacs/site-start/</filename>. Emacs knows to load this
file automatically when it starts.
</para>
<screen>
{
packageOverrides = pkgs: with pkgs; rec {
myEmacsConfig = writeText "default.el" ''
;; initialize package
(require 'package)
(package-initialize 'noactivate)
(eval-when-compile
(require 'use-package))
;; load some packages
(use-package company
:bind ("&lt;C-tab&gt;" . company-complete)
:diminish company-mode
:commands (company-mode global-company-mode)
:defer 1
:config
(global-company-mode))
(use-package counsel
:commands (counsel-descbinds)
:bind (([remap execute-extended-command] . counsel-M-x)
("C-x C-f" . counsel-find-file)
("C-c g" . counsel-git)
("C-c j" . counsel-git-grep)
("C-c k" . counsel-ag)
("C-x l" . counsel-locate)
("M-y" . counsel-yank-pop)))
(use-package flycheck
:defer 2
:config (global-flycheck-mode))
(use-package ivy
:defer 1
:bind (("C-c C-r" . ivy-resume)
("C-x C-b" . ivy-switch-buffer)
:map ivy-minibuffer-map
("C-j" . ivy-call))
:diminish ivy-mode
:commands ivy-mode
:config
(ivy-mode 1))
(use-package magit
:defer
:if (executable-find "git")
:bind (("C-x g" . magit-status)
("C-x G" . magit-dispatch-popup))
:init
(setq magit-completing-read-function 'ivy-completing-read))
(use-package projectile
:commands projectile-mode
:bind-keymap ("C-c p" . projectile-command-map)
:defer 5
:config
(projectile-global-mode))
'';
myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
(runCommand "default.el" {} ''
mkdir -p $out/share/emacs/site-lisp
cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
'')
company
counsel
flycheck
ivy
magit
projectile
use-package
]));
};
}
</screen>
<para>
This provides a fairly full Emacs start file. It will load in addition to
the user's presonal config. You can always disable it by passing
<command>-q</command> to the Emacs command.
</para>
<para>
Sometimes <varname>emacsWithPackages</varname> is not enough, as this
package set has some priorities imposed on packages (with the lowest
priority assigned to Melpa Unstable, and the highest for packages manually
defined in <filename>pkgs/top-level/emacs-packages.nix</filename>). But you
can't control this priorities when some package is installed as a
dependency. You can override it on per-package-basis, providing all the
required dependencies manually - but it's tedious and there is always a
possibility that an unwanted dependency will sneak in through some other
package. To completely override such a package you can use
<varname>overrideScope'</varname>.
</para>
<screen>
overrides = self: super: rec {
haskell-mode = self.melpaPackages.haskell-mode;
...
};
((emacsPackagesGen emacs).overrideScope' overrides).emacsWithPackages (p: with p; [
# here both these package will use haskell-mode of our own choice
ghc-mod
dante
])
</screen>
</section>
</section>
<section xml:id="dlib">
<title>DLib</title>
<para>
<link xlink:href="http://dlib.net/">DLib</link> is a modern, C++-based toolkit which
provides several machine learning algorithms.
</para>
<section xml:id="compiling-without-avx-support">
<title>Compiling without AVX support</title>
<para>
Especially older CPUs don't support
<link xlink:href="https://en.wikipedia.org/wiki/Advanced_Vector_Extensions">AVX</link>
(<abbrev>Advanced Vector Extensions</abbrev>) instructions that are used by DLib to
optimize their algorithms.
</para>
<para>
On the affected hardware errors like <literal>Illegal instruction</literal> will occur.
In those cases AVX support needs to be disabled:
<programlisting>self: super: {
dlib = super.dlib.override { avxSupport = false; };
}</programlisting>
</para>
</section>
</section>
<section xml:id="unfree-software">
<title>Unfree software</title>
<para>
All users of Nixpkgs are free software users, and many users (and
developers) of Nixpkgs want to limit and tightly control their exposure to
unfree software. At the same time, many users need (or want)
to run some specific
pieces of proprietary software. Nixpkgs includes some expressions for unfree
software packages. By default unfree software cannot be installed and
doesn’t show up in searches. To allow installing unfree software in a
single Nix invocation one can export
<literal>NIXPKGS_ALLOW_UNFREE=1</literal>. For a persistent solution, users
can set <literal>allowUnfree</literal> in the Nixpkgs configuration.
</para>
<para>
Fine-grained control is possible by defining
<literal>allowUnfreePredicate</literal> function in config; it takes the
<literal>mkDerivation</literal> parameter attrset and returns
<literal>true</literal> for unfree packages that should be allowed.
</para>
</section>
<section xml:id="sec-steam">
<title>Steam</title>
<section xml:id="sec-steam-nix">
<title>Steam in Nix</title>
<para>
Steam is distributed as a <filename>.deb</filename> file, for now only as
an i686 package (the amd64 package only has documentation). When unpacked,
it has a script called <filename>steam</filename> that in Ubuntu (their
target distro) would go to <filename>/usr/bin </filename>. When run for the
first time, this script copies some files to the user's home, which include
another script that is the ultimate responsible for launching the steam
binary, which is also in $HOME.
</para>
<para>
Nix problems and constraints:
<itemizedlist>
<listitem>
<para>
We don't have <filename>/bin/bash</filename> and many scripts point
there. Similarly for <filename>/usr/bin/python</filename> .
</para>
</listitem>
<listitem>
<para>
We don't have the dynamic loader in <filename>/lib </filename>.
</para>
</listitem>
<listitem>
<para>
The <filename>steam.sh</filename> script in $HOME can not be patched, as
it is checked and rewritten by steam.
</para>
</listitem>
<listitem>
<para>
The steam binary cannot be patched, it's also checked.
</para>
</listitem>
</itemizedlist>
</para>
<para>
The current approach to deploy Steam in NixOS is composing a FHS-compatible
chroot environment, as documented
<link xlink:href="http://sandervanderburg.blogspot.nl/2013/09/composing-fhs-compatible-chroot.html">here</link>.
This allows us to have binaries in the expected paths without disrupting
the system, and to avoid patching them to work in a non FHS environment.
</para>
</section>
<section xml:id="sec-steam-play">
<title>How to play</title>
<para>
For 64-bit systems it's important to have
<programlisting>hardware.opengl.driSupport32Bit = true;</programlisting>
in your <filename>/etc/nixos/configuration.nix</filename>. You'll also need
<programlisting>hardware.pulseaudio.support32Bit = true;</programlisting>
if you are using PulseAudio - this will enable 32bit ALSA apps integration.
To use the Steam controller or other Steam supported controllers such as
the DualShock 4 or Nintendo Switch Pro, you need to add
<programlisting>hardware.steam-hardware.enable = true;</programlisting>
to your configuration.
</para>
</section>
<section xml:id="sec-steam-troub">
<title>Troubleshooting</title>
<para>
<variablelist>
<varlistentry>
<term>
Steam fails to start. What do I do?
</term>
<listitem>
<para>
Try to run
<programlisting>strace steam</programlisting>
to see what is causing steam to fail.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Using the FOSS Radeon or nouveau (nvidia) drivers
</term>
<listitem>
<itemizedlist>
<listitem>
<para>
The <literal>newStdcpp</literal> parameter was removed since NixOS
17.09 and should not be needed anymore.
</para>
</listitem>
<listitem>
<para>
Steam ships statically linked with a version of libcrypto that
conflics with the one dynamically loaded by radeonsi_dri.so. If you
get the error
<programlisting>steam.sh: line 713: 7842 Segmentation fault (core dumped)</programlisting>
have a look at
<link xlink:href="https://github.com/NixOS/nixpkgs/pull/20269">this
pull request</link>.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>
Java
</term>
<listitem>
<orderedlist>
<listitem>
<para>
There is no java in steam chrootenv by default. If you get a message
like
<programlisting>/home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found</programlisting>
You need to add
<programlisting> steam.override { withJava = true; };</programlisting>
to your configuration.
</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<section xml:id="sec-steam-run">
<title>steam-run</title>
<para>
The FHS-compatible chroot used for steam can also be used to run other
linux games that expect a FHS environment. To do it, add
<programlisting>pkgs.(steam.override {
nativeOnly = true;
newStdcpp = true;
}).run</programlisting>
to your configuration, rebuild, and run the game with
<programlisting>steam-run ./foo</programlisting>
</para>
</section>
</section>
<section xml:id="sec-citrix">
<title>Citrix Receiver &amp; Citrix Workspace App</title>
<para>
<note>
<para>
Please note that the <literal>citrix_receiver</literal> package has been deprecated since its
development was <link xlink:href="https://docs.citrix.com/en-us/citrix-workspace-app.html">discontinued by upstream</link>
and will be replaced by <link xlink:href="https://www.citrix.com/products/workspace-app/">the citrix workspace app</link>.
</para>
</note>
<link xlink:href="https://www.citrix.com/products/receiver/">Citrix Receiver</link> and
<link xlink:href="https://www.citrix.com/products/workspace-app/">Citrix Workspace App</link>
are a remote desktop viewers which provide access to
<link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link>
installations.
</para>
<section xml:id="sec-citrix-base">
<title>Basic usage</title>
<para>
The tarball archive needs to be downloaded manually as the license
agreements of the vendor for
<link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">Citrix Receiver</link>
or <link xlink:href="https://www.citrix.de/downloads/workspace-app/linux/workspace-app-for-linux-latest.html">Citrix Workspace</link>
need to be accepted first.
Then run <command>nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz</command>.
With the archive available
in the store the package can be built and installed with Nix.
</para>
<warning>
<title>Caution with <command>nix-shell</command> installs</title>
<para>
It's recommended to install <literal>Citrix Receiver</literal>
and/or <literal>Citrix Workspace</literal> using
<literal>nix-env -i</literal> or globally to
ensure that the <literal>.desktop</literal> files are installed properly
into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't be possible to
open <literal>.ica</literal> files automatically from the browser to start
a Citrix connection.
</para>
</warning>
</section>
<section xml:id="sec-citrix-custom-certs">
<title>Custom certificates</title>
<para>
The <literal>Citrix Receiver</literal> and <literal>Citrix Workspace App</literal>
in <literal>nixpkgs</literal> trust several certificates
<link xlink:href="https://curl.haxx.se/docs/caextract.html">from the
Mozilla database</link> by default. However several companies using Citrix
might require their own corporate certificate. On distros with imperative
packaging these certs can be stored easily in
<link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>,
however this directory is a store path in <literal>nixpkgs</literal>. In
order to work around this issue the package provides a simple mechanism to
add custom certificates without rebuilding the entire package using
<literal>symlinkJoin</literal>:
<programlisting>
<![CDATA[with import <nixpkgs> { config.allowUnfree = true; };
let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in
citrix_workspace.override { # the same applies for `citrix_receiver` if used.
inherit extraCerts;
}]]>
</programlisting>
</para>
</section>
</section>
</chapter>

4
doc/platform-notes.xml
View file

@ -96,8 +96,8 @@
</programlisting>
<para>
The package <literal>xcbuild</literal> can be used to build projects that
really depend on Xcode. However, this replacement is not 100%
compatible with Xcode and can occasionally cause issues.
really depend on Xcode. However, this replacement is not 100% compatible
with Xcode and can occasionally cause issues.
</para>
</listitem>
</itemizedlist>

28
doc/quick-start.xml
View file

@ -9,8 +9,8 @@
<para>
Checkout the Nixpkgs source tree:
<screen>
$ git clone https://github.com/NixOS/nixpkgs
$ cd nixpkgs</screen>
<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs
<prompt>$ </prompt>cd nixpkgs</screen>
</para>
</listitem>
<listitem>
@ -23,7 +23,7 @@ $ cd nixpkgs</screen>
See <xref linkend="sec-organisation" /> for some hints on the tree
organisation. Create a directory for your package, e.g.
<screen>
$ mkdir pkgs/development/libraries/libfoo</screen>
<prompt>$ </prompt>mkdir pkgs/development/libraries/libfoo</screen>
</para>
</listitem>
<listitem>
@ -34,8 +34,8 @@ $ mkdir pkgs/development/libraries/libfoo</screen>
as arguments, and returns a build of the package in the Nix store. The
expression should usually be called <filename>default.nix</filename>.
<screen>
$ emacs pkgs/development/libraries/libfoo/default.nix
$ git add pkgs/development/libraries/libfoo/default.nix</screen>
<prompt>$ </prompt>emacs pkgs/development/libraries/libfoo/default.nix
<prompt>$ </prompt>git add pkgs/development/libraries/libfoo/default.nix</screen>
</para>
<para>
You can have a look at the existing Nix expressions under
@ -148,8 +148,8 @@ $ git add pkgs/development/libraries/libfoo/default.nix</screen>
<listitem>
<para>
You can use <command>nix-prefetch-url</command>
<replaceable>url</replaceable> to get the
SHA-256 hash of source distributions. There are similar commands as
<replaceable>url</replaceable> to get the SHA-256 hash of source
distributions. There are similar commands as
<command>nix-prefetch-git</command> and
<command>nix-prefetch-hg</command> available in
<literal>nix-prefetch-scripts</literal> package.
@ -180,7 +180,7 @@ $ git add pkgs/development/libraries/libfoo/default.nix</screen>
with some descriptive name for the variable, e.g.
<varname>libfoo</varname>.
<screen>
$ emacs pkgs/top-level/all-packages.nix</screen>
<prompt>$ </prompt>emacs pkgs/top-level/all-packages.nix</screen>
</para>
<para>
The attributes in that file are sorted by category (like “Development /
@ -193,7 +193,7 @@ $ emacs pkgs/top-level/all-packages.nix</screen>
To test whether the package builds, run the following command from the
root of the nixpkgs source tree:
<screen>
$ nix-build -A libfoo</screen>
<prompt>$ </prompt>nix-build -A libfoo</screen>
where <varname>libfoo</varname> should be the variable name defined in the
previous step. You may want to add the flag <option>-K</option> to keep
the temporary build directory in case something fails. If the build
@ -205,13 +205,17 @@ $ nix-build -A libfoo</screen>
<para>
If you want to install the package into your profile (optional), do
<screen>
$ nix-env -f . -iA libfoo</screen>
<prompt>$ </prompt>nix-env -f . -iA libfoo</screen>
</para>
</listitem>
<listitem>
<para>
Optionally commit the new package and open a pull request, or send a patch
to <literal>https://groups.google.com/forum/#!forum/nix-devel</literal>.
Optionally commit the new package and open a pull request <link
xlink:href="https://github.com/NixOS/nixpkgs/pulls">to nixpkgs</link>, or
use <link
xlink:href="https://discourse.nixos.org/t/about-the-patches-category/477">
the Patches category</link> on Discourse for sending a patch without a
GitHub account.
</para>
</listitem>
</orderedlist>

33
doc/reviewing-contributions.xml
View file

@ -24,11 +24,13 @@
<para>
The high change rate of Nixpkgs makes any pull request that remains open for
too long subject to conflicts that will require extra work from the submitter
or the merger. Reviewing pull requests in a timely manner and being responsive
to the comments is the key to avoid this issue. GitHub provides sort filters
that can be used to see the <link
or the merger. Reviewing pull requests in a timely manner and being
responsive to the comments is the key to avoid this issue. GitHub provides
sort filters that can be used to see the
<link
xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc">most
recently</link> and the <link
recently</link> and the
<link
xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc">least
recently</link> updated pull requests. We highly encourage looking at
<link xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+review%3Anone+status%3Asuccess+-label%3A%222.status%3A+work-in-progress%22+no%3Aproject+no%3Aassignee+no%3Amilestone">
@ -151,11 +153,11 @@
nixpkgs-unstable for easier review by running the following commands
from a nixpkgs clone.
<screen>
$ git remote add channels https://github.com/NixOS/nixpkgs-channels.git <co
<prompt>$ </prompt>git remote add channels https://github.com/NixOS/nixpkgs-channels.git <co
xml:id='reviewing-rebase-1' />
$ git fetch channels nixos-unstable <co xml:id='reviewing-rebase-2' />
$ git fetch origin pull/PRNUMBER/head <co xml:id='reviewing-rebase-3' />
$ git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD <co
<prompt>$ </prompt>git fetch channels nixos-unstable <co xml:id='reviewing-rebase-2' />
<prompt>$ </prompt>git fetch origin pull/PRNUMBER/head <co xml:id='reviewing-rebase-3' />
<prompt>$ </prompt>git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD <co
xml:id='reviewing-rebase-4' />
</screen>
<calloutlist>
@ -187,14 +189,15 @@ $ git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD <co
</listitem>
<listitem>
<para>
The <link xlink:href="https://github.com/madjar/nox">nox</link> tool can
be used to review a pull request content in a single command. It doesn't
rebase on a channel branch so it might trigger multiple source builds.
The
<link xlink:href="https://github.com/Mic92/nix-review">nix-review</link>
tool can be used to review a pull request content in a single command.
<varname>PRNUMBER</varname> should be replaced by the number at the end
of the pull request title.
of the pull request title. You can also provide the full github pull
request url.
</para>
<screen>
$ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
<prompt>$ </prompt>nix-shell -p nix-review --run "nix-review pr PRNUMBER"
</screen>
</listitem>
</itemizedlist>
@ -609,8 +612,8 @@ policy.
create an issue or post on
<link
xlink:href="https://discourse.nixos.org">Discourse</link> with
references of packages and modules they maintain so the maintainership can be
taken over by other contributors.
references of packages and modules they maintain so the maintainership can
be taken over by other contributors.
</para>
</section>
</chapter>

537
doc/stdenv.xml
View file

@ -31,9 +31,28 @@ stdenv.mkDerivation {
separate Nix expression from <filename>pkgs/all-packages.nix</filename>, you
need to pass it as a function argument.) Specifying a
<varname>name</varname> and a <varname>src</varname> is the absolute minimum
you need to do. Many packages have dependencies that are not provided in the
standard environment. It’s usually sufficient to specify those
dependencies in the <varname>buildInputs</varname> attribute:
Nix requires. For convenience, you can also use <varname>pname</varname> and
<varname>version</varname> attributes and <literal>mkDerivation</literal>
will automatically set <varname>name</varname> to
<literal>"${pname}-${version}"</literal> by default. Since
<link xlink:href="https://github.com/NixOS/rfcs/pull/35">RFC 0035</link>,
this is preferred for packages in Nixpkgs, as it allows us to reuse the
version easily:
<programlisting>
stdenv.mkDerivation rec {
pname = "libfoo";
version = "1.2.3";
src = fetchurl {
url = "http://example.org/libfoo-source-${version}.tar.bz2";
sha256 = "0x2g1jqygyr5wiwg4ma1nd7w4ydpy82z9gkcv8vh2v8dn3y58v5m";
};
}</programlisting>
</para>
<para>
Many packages have dependencies that are not provided in the standard
environment. It’s usually sufficient to specify those dependencies in the
<varname>buildInputs</varname> attribute:
<programlisting>
stdenv.mkDerivation {
name = "libfoo-1.2.3";
@ -222,24 +241,24 @@ genericBuild
</footnote>
But even if one is not cross compiling, the platforms imply whether or not
the dependency is needed at run-time or build-time, a concept that makes
perfect sense outside of cross compilation. For now, the run-time/build-time
distinction is just a hint for mental clarity, but in the future it perhaps
could be enforced.
perfect sense outside of cross compilation. By default, the
run-time/build-time distinction is just a hint for mental clarity, but with
<varname>strictDeps</varname> set it is mostly enforced even in the native
case.
</para>
<para>
The extension of <envar>PATH</envar> with dependencies, alluded to
above, proceeds according to the relative platforms alone. The
process is carried out only for dependencies whose host platform
matches the new derivation's build platform i.e. dependencies which
run on the platform where the new derivation will be built.
The extension of <envar>PATH</envar> with dependencies, alluded to above,
proceeds according to the relative platforms alone. The process is carried
out only for dependencies whose host platform matches the new derivation's
build platform i.e. dependencies which run on the platform where the new
derivation will be built.
<footnote xml:id="footnote-stdenv-native-dependencies-in-path">
<para>
Currently, this means for native builds all dependencies are put
on the <envar>PATH</envar>. But in the future that may not be the
case for sake of matching cross: the platforms would be assumed
to be unique for native and cross builds alike, so only the
<varname>depsBuild*</varname> and
Currently, this means for native builds all dependencies are put on the
<envar>PATH</envar>. But in the future that may not be the case for sake
of matching cross: the platforms would be assumed to be unique for native
and cross builds alike, so only the <varname>depsBuild*</varname> and
<varname>nativeBuildInputs</varname> would be added to the
<envar>PATH</envar>.
</para>
@ -252,9 +271,10 @@ genericBuild
<para>
The dependency is propagated when it forces some of its other-transitive
(non-immediate) downstream dependencies to also take it on as an immediate
dependency. Nix itself already takes a package's transitive dependencies into
account, but this propagation ensures nixpkgs-specific infrastructure like
setup hooks (mentioned above) also are run as if the propagated dependency.
dependency. Nix itself already takes a package's transitive dependencies
into account, but this propagation ensures nixpkgs-specific infrastructure
like setup hooks (mentioned above) also are run as if the propagated
dependency.
</para>
<para>
@ -270,9 +290,9 @@ genericBuild
described by the current dependency's platform offsets. This results in sort
a transitive closure of the dependency relation, with the offsets being
approximately summed when two dependency links are combined. We also prune
transitive dependencies whose combined offsets go out-of-bounds, which can be
viewed as a filter over that transitive closure removing dependencies that
are blatantly absurd.
transitive dependencies whose combined offsets go out-of-bounds, which can
be viewed as a filter over that transitive closure removing dependencies
that are blatantly absurd.
</para>
<para>
@ -287,8 +307,8 @@ genericBuild
propagation logic.
</para>
</footnote>
They're confusing in very different ways so... hopefully if something doesn't
make sense in one presentation, it will in the other!
They're confusing in very different ways so... hopefully if something
doesn't make sense in one presentation, it will in the other!
<programlisting>
let mapOffset(h, t, i) = i + (if i &lt;= 0 then h else t - 1)
@ -324,31 +344,34 @@ let f(h, h + 1, i) = i + (if i &lt;= 0 then h else (h + 1) - 1)
let f(h, h + 1, i) = i + (if i &lt;= 0 then h else h)
let f(h, h + 1, i) = i + h
</programlisting>
This is where "sum-like" comes in from above: We can just sum all of the host
offsets to get the host offset of the transitive dependency. The target
offset is the transitive dependency is simply the host offset + 1, just as it
was with the dependencies composed to make this transitive one; it can be
This is where "sum-like" comes in from above: We can just sum all of the
host offsets to get the host offset of the transitive dependency. The target
offset is the transitive dependency is simply the host offset + 1, just as
it was with the dependencies composed to make this transitive one; it can be
ignored as it doesn't add any new information.
</para>
<para>
Because of the bounds checks, the uncommon cases are <literal>h = t</literal>
and <literal>h + 2 = t</literal>. In the former case, the motivation for
<function>mapOffset</function> is that since its host and target platforms
are the same, no transitive dependency of it should be able to "discover" an
offset greater than its reduced target offsets.
Because of the bounds checks, the uncommon cases are <literal>h =
t</literal> and <literal>h + 2 = t</literal>. In the former case, the
motivation for <function>mapOffset</function> is that since its host and
target platforms are the same, no transitive dependency of it should be able
to "discover" an offset greater than its reduced target offsets.
<function>mapOffset</function> effectively "squashes" all its transitive
dependencies' offsets so that none will ever be greater than the target
offset of the original <literal>h = t</literal> package. In the other case,
<literal>h + 1</literal> is skipped over between the host and target offsets.
Instead of squashing the offsets, we need to "rip" them apart so no
<literal>h + 1</literal> is skipped over between the host and target
offsets. Instead of squashing the offsets, we need to "rip" them apart so no
transitive dependencies' offset is that one.
</para>
<para>
Overall, the unifying theme here is that propagation shouldn't be introducing
transitive dependencies involving platforms the depending package is unaware
of. The offset bounds checking and definition of
Overall, the unifying theme here is that propagation shouldn't be
introducing transitive dependencies involving platforms the depending
package is unaware of. [One can imagine the dependending package asking for
dependencies with the platforms it knows about; other platforms it doesn't
know how to ask for. The platform description in that scenario is a kind of
unforagable capability.] The offset bounds checking and definition of
<function>mapOffset</function> together ensure that this is the case.
Discovering a new offset is discovering a new platform, and since those
platforms weren't in the derivation "spec" of the needing package, they
@ -381,8 +404,8 @@ let f(h, h + 1, i) = i + h
Since these packages are able to be run at build-time, they are always
added to the <envar>PATH</envar>, as described above. But since these
packages are only guaranteed to be able to run then, they shouldn't
persist as run-time dependencies. This isn't currently enforced, but could
be in the future.
persist as run-time dependencies. This isn't currently enforced, but
could be in the future.
</para>
</listitem>
</varlistentry>
@ -396,10 +419,10 @@ let f(h, h + 1, i) = i + h
platform, and target platform is the new derivation's host platform. This
means a <literal>-1</literal> host offset and <literal>0</literal> target
offset from the new derivation's platforms. These are programs and
libraries used at build-time that, if they are a compiler or similar tool,
produce code to run at run-time—i.e. tools used to build the new
derivation. If the dependency doesn't care about the target platform (i.e.
isn't a compiler or similar tool), put it here, rather than in
libraries used at build-time that, if they are a compiler or similar
tool, produce code to run at run-time—i.e. tools used to build the new
derivation. If the dependency doesn't care about the target platform
(i.e. isn't a compiler or similar tool), put it here, rather than in
<varname>depsBuildBuild</varname> or <varname>depsBuildTarget</varname>.
This could be called <varname>depsBuildHost</varname> but
<varname>nativeBuildInputs</varname> is used for historical continuity.
@ -407,8 +430,9 @@ let f(h, h + 1, i) = i + h
<para>
Since these packages are able to be run at build-time, they are added to
the <envar>PATH</envar>, as described above. But since these packages are
only guaranteed to be able to run then, they shouldn't persist as run-time
dependencies. This isn't currently enforced, but could be in the future.
only guaranteed to be able to run then, they shouldn't persist as
run-time dependencies. This isn't currently enforced, but could be in the
future.
</para>
</listitem>
</varlistentry>
@ -421,33 +445,36 @@ let f(h, h + 1, i) = i + h
A list of dependencies whose host platform is the new derivation's build
platform, and target platform is the new derivation's target platform.
This means a <literal>-1</literal> host offset and <literal>1</literal>
target offset from the new derivation's platforms. These are programs used
at build time that produce code to run with code produced by the depending
package. Most commonly, these are tools used to build the runtime or
standard library that the currently-being-built compiler will inject into
any code it compiles. In many cases, the currently-being-built-compiler is
itself employed for that task, but when that compiler won't run (i.e. its
build and host platform differ) this is not possible. Other times, the
compiler relies on some other tool, like binutils, that is always built
separately so that the dependency is unconditional.
target offset from the new derivation's platforms. These are programs
used at build time that produce code to run with code produced by the
depending package. Most commonly, these are tools used to build the
runtime or standard library that the currently-being-built compiler will
inject into any code it compiles. In many cases, the
currently-being-built-compiler is itself employed for that task, but when
that compiler won't run (i.e. its build and host platform differ) this is
not possible. Other times, the compiler relies on some other tool, like
binutils, that is always built separately so that the dependency is
unconditional.
</para>
<para>
This is a somewhat confusing concept to wrap one’s head around, and for
good reason. As the only dependency type where the platform offsets are
not adjacent integers, it requires thinking of a bootstrapping stage
<emphasis>two</emphasis> away from the current one. It and its use-case go
hand in hand and are both considered poor form: try to not need this sort
of dependency, and try to avoid building standard libraries and runtimes
in the same derivation as the compiler produces code using them. Instead
strive to build those like a normal library, using the newly-built
compiler just as a normal library would. In short, do not use this
attribute unless you are packaging a compiler and are sure it is needed.
<emphasis>two</emphasis> away from the current one. It and its use-case
go hand in hand and are both considered poor form: try to not need this
sort of dependency, and try to avoid building standard libraries and
runtimes in the same derivation as the compiler produces code using them.
Instead strive to build those like a normal library, using the
newly-built compiler just as a normal library would. In short, do not use
this attribute unless you are packaging a compiler and are sure it is
needed.
</para>
<para>
Since these packages are able to run at build time, they are added to the
<envar>PATH</envar>, as described above. But since these packages are only
guaranteed to be able to run then, they shouldn't persist as run-time
dependencies. This isn't currently enforced, but could be in the future.
<envar>PATH</envar>, as described above. But since these packages are
only guaranteed to be able to run then, they shouldn't persist as
run-time dependencies. This isn't currently enforced, but could be in the
future.
</para>
</listitem>
</varlistentry>
@ -462,11 +489,11 @@ let f(h, h + 1, i) = i + h
and <literal>0</literal> target offset from the new derivation's host
platform. These are packages used at run-time to generate code also used
at run-time. In practice, this would usually be tools used by compilers
for macros or a metaprogramming system, or libraries used by the macros or
metaprogramming code itself. It's always preferable to use a
<varname>depsBuildBuild</varname> dependency in the derivation being built
over a <varname>depsHostHost</varname> on the tool doing the building for
this purpose.
for macros or a metaprogramming system, or libraries used by the macros
or metaprogramming code itself. It's always preferable to use a
<varname>depsBuildBuild</varname> dependency in the derivation being
built over a <varname>depsHostHost</varname> on the tool doing the
building for this purpose.
</para>
</listitem>
</varlistentry>
@ -481,8 +508,8 @@ let f(h, h + 1, i) = i + h
<literal>1</literal> target offset from the new derivation's host
platform. This would be called <varname>depsHostTarget</varname> but for
historical continuity. If the dependency doesn't care about the target
platform (i.e. isn't a compiler or similar tool), put it here, rather than
in <varname>depsBuildBuild</varname>.
platform (i.e. isn't a compiler or similar tool), put it here, rather
than in <varname>depsBuildBuild</varname>.
</para>
<para>
These are often programs and libraries used by the new derivation at
@ -664,10 +691,11 @@ passthru = {
<literal>hello.baz.value1</literal>. We don't specify any usage or schema
of <literal>passthru</literal> - it is meant for values that would be
useful outside the derivation in other parts of a Nix expression (e.g. in
other derivations). An example would be to convey some specific dependency
of your derivation which contains a program with plugins support. Later,
others who make derivations with plugins can use passed-through dependency
to ensure that their plugin would be binary-compatible with built program.
other derivations). An example would be to convey some specific
dependency of your derivation which contains a program with plugins
support. Later, others who make derivations with plugins can use
passed-through dependency to ensure that their plugin would be
binary-compatible with built program.
</para>
</listitem>
</varlistentry>
@ -677,9 +705,9 @@ passthru = {
</term>
<listitem>
<para>
A script to be run by <filename>maintainers/scripts/update.nix</filename> when
the package is matched. It needs to be an executable file, either on the file
system:
A script to be run by <filename>maintainers/scripts/update.nix</filename>
when the package is matched. It needs to be an executable file, either on
the file system:
<programlisting>
passthru.updateScript = ./update.sh;
</programlisting>
@ -695,16 +723,21 @@ passthru.updateScript = writeScript "update-zoom-us" ''
update-source-version zoom-us "$version"
'';
</programlisting>
The attribute can also contain a list, a script followed by arguments to be passed to it:
The attribute can also contain a list, a script followed by arguments to
be passed to it:
<programlisting>
passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ];
</programlisting>
Note that the update scripts will be run in parallel by default; you should avoid running <command>git commit</command> or any other commands that cannot handle that.
</para>
<para>
The script will be usually run from the root of the Nixpkgs repository
but you should not rely on that. Also note that the update scripts will
be run in parallel by default; you should avoid running <command>git
commit</command> or any other commands that cannot handle that.
</para>
<para>
For information about how to run the updates, execute
<cmdsynopsis><command>nix-shell</command> <arg>maintainers/scripts/update.nix</arg></cmdsynopsis>.
<command>nix-shell maintainers/scripts/update.nix</command>.
</para>
</listitem>
</varlistentry>
@ -730,7 +763,8 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
latter is convenient from a build script. However, typically one only wants
to <emphasis>add</emphasis> some commands to a phase, e.g. by defining
<literal>postInstall</literal> or <literal>preFixup</literal>, as skipping
some of the default actions may have unexpected consequences.
some of the default actions may have unexpected consequences. The default
script for each phase is defined in the file <filename>pkgs/stdenv/generic/setup.sh</filename>.
</para>
<section xml:id="ssec-controlling-phases">
@ -752,7 +786,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
set, the default value is used, which is <literal>$prePhases
unpackPhase patchPhase $preConfigurePhases configurePhase
$preBuildPhases buildPhase checkPhase $preInstallPhases installPhase
fixupPhase $preDistPhases distPhase $postPhases</literal>.
fixupPhase installCheckPhase $preDistPhases distPhase $postPhases</literal>.
</para>
<para>
Usually, if you just want to add a few phases, it’s more convenient
@ -953,6 +987,16 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>dontUnpack</varname>
</term>
<listitem>
<para>
Set to true to skip the unpack phase.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>dontMakeSourcesWritable</varname>
@ -1075,6 +1119,16 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>dontConfigure</varname>
</term>
<listitem>
<para>
Set to true to skip the configure phase.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>configureFlagsArray</varname>
@ -1178,8 +1232,8 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
By default, when cross compiling, the configure script has
<option>--build=...</option> and <option>--host=...</option> passed.
Packages can instead pass <literal>[ "build" "host" "target" ]</literal>
or a subset to control exactly which platform flags are passed. Compilers
and other tools can use this to also pass the target platform.
or a subset to control exactly which platform flags are passed.
Compilers and other tools can use this to also pass the target platform.
<footnote xml:id="footnote-stdenv-build-time-guessing-impurity">
<para>
Eventually these will be passed building natively as well, to improve
@ -1545,6 +1599,16 @@ installTargets = "install-bin install-doc";</programlisting>
<variablelist>
<title>Variables controlling the fixup phase</title>
<varlistentry>
<term>
<varname>dontFixup</varname>
</term>
<listitem>
<para>
Set to true to skip the fixup phase.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>dontStrip</varname>
@ -1562,7 +1626,7 @@ installTargets = "install-bin install-doc";</programlisting>
</term>
<listitem>
<para>
Like <varname>dontStripHost</varname>, but only affects the
Like <varname>dontStrip</varname>, but only affects the
<command>strip</command> command targetting the package's host platform.
Useful when supporting cross compilation, but otherwise feel free to
ignore.
@ -1575,7 +1639,7 @@ installTargets = "install-bin install-doc";</programlisting>
</term>
<listitem>
<para>
Like <varname>dontStripHost</varname>, but only affects the
Like <varname>dontStrip</varname>, but only affects the
<command>strip</command> command targetting the packages' target
platform. Useful when supporting cross compilation, but otherwise feel
free to ignore.
@ -1694,10 +1758,11 @@ installTargets = "install-bin install-doc";</programlisting>
</term>
<listitem>
<para>
A package can export a <link linkend="ssec-setup-hooks">setup hook</link>
by setting this variable. The setup hook, if defined, is copied to
<filename>$out/nix-support/setup-hook</filename>. Environment variables
are then substituted in it using <function
A package can export a <link linkend="ssec-setup-hooks">setup
hook</link> by setting this variable. The setup hook, if defined, is
copied to <filename>$out/nix-support/setup-hook</filename>. Environment
variables are then substituted in it using
<function
linkend="fun-substituteAll">substituteAll</function>.
</para>
</listitem>
@ -1812,8 +1877,8 @@ set debug-file-directory ~/.nix-profile/lib/debug
<listitem>
<para>
A list of dependencies used by the phase. This gets included in
<varname>nativeBuildInputs</varname> when <varname>doInstallCheck</varname> is
set.
<varname>nativeBuildInputs</varname> when
<varname>doInstallCheck</varname> is set.
</para>
</listitem>
</varlistentry>
@ -2160,10 +2225,11 @@ someVar=$(stripHash $name)
dependency derivation is already built just the same—depending is just
needing something to exist, and needing is idempotent. However, a dependency
specified twice will have its setup hook run twice, and that could easily
change the build environment (though a well-written setup hook will therefore
strive to be idempotent so this is in fact not observable). More broadly,
setup hooks are anti-modular in that multiple dependencies, whether the same
or different, should not interfere and yet their setup hooks may well do so.
change the build environment (though a well-written setup hook will
therefore strive to be idempotent so this is in fact not observable). More
broadly, setup hooks are anti-modular in that multiple dependencies, whether
the same or different, should not interfere and yet their setup hooks may
well do so.
</para>
<para>
@ -2185,11 +2251,12 @@ someVar=$(stripHash $name)
Returning to the C compiler wrapper example, if the wrapper itself is an
<literal>n</literal> dependency, then it only wants to accumulate flags from
<literal>n + 1</literal> dependencies, as only those ones match the
compiler's target platform. The <envar>hostOffset</envar> variable is defined
with the current dependency's host offset <envar>targetOffset</envar> with
its target offset, before its setup hook is sourced. Additionally, since most
environment hooks don't care about the target platform, that means the setup
hook can append to the right bash array by doing something like
compiler's target platform. The <envar>hostOffset</envar> variable is
defined with the current dependency's host offset
<envar>targetOffset</envar> with its target offset, before its setup hook is
sourced. Additionally, since most environment hooks don't care about the
target platform, that means the setup hook can append to the right bash
array by doing something like
<programlisting language="bash">
addEnvHooks "$hostOffset" myBashFunction
</programlisting>
@ -2204,11 +2271,10 @@ addEnvHooks "$hostOffset" myBashFunction
</para>
<para>
First, let’s cover some setup hooks that are part of Nixpkgs
default stdenv. This means that they are run for every package
built using <function>stdenv.mkDerivation</function>. Some of
these are platform specific, so they may run on Linux but not
Darwin or vice-versa.
First, let’s cover some setup hooks that are part of Nixpkgs default
stdenv. This means that they are run for every package built using
<function>stdenv.mkDerivation</function>. Some of these are platform
specific, so they may run on Linux but not Darwin or vice-versa.
<variablelist>
<varlistentry>
<term>
@ -2217,10 +2283,9 @@ addEnvHooks "$hostOffset" myBashFunction
<listitem>
<para>
This setup hook moves any installed documentation to the
<literal>/share</literal> subdirectory directory. This includes
the man, doc and info directories. This is needed for legacy
programs that do not know how to use the
<literal>share</literal> subdirectory.
<literal>/share</literal> subdirectory directory. This includes the man,
doc and info directories. This is needed for legacy programs that do not
know how to use the <literal>share</literal> subdirectory.
</para>
</listitem>
</varlistentry>
@ -2230,9 +2295,9 @@ addEnvHooks "$hostOffset" myBashFunction
</term>
<listitem>
<para>
This setup hook compresses any man pages that have been
installed. The compression is done using the gzip program. This
helps to reduce the installed size of packages.
This setup hook compresses any man pages that have been installed. The
compression is done using the gzip program. This helps to reduce the
installed size of packages.
</para>
</listitem>
</varlistentry>
@ -2242,10 +2307,9 @@ addEnvHooks "$hostOffset" myBashFunction
</term>
<listitem>
<para>
This runs the strip command on installed binaries and
libraries. This removes unnecessary information like debug
symbols when they are not needed. This also helps to reduce the
installed size of packages.
This runs the strip command on installed binaries and libraries. This
removes unnecessary information like debug symbols when they are not
needed. This also helps to reduce the installed size of packages.
</para>
</listitem>
</varlistentry>
@ -2255,13 +2319,12 @@ addEnvHooks "$hostOffset" myBashFunction
</term>
<listitem>
<para>
This setup hook patches installed scripts to use the full path
to the shebang interpreter. A shebang interpreter is the first
commented line of a script telling the operating system which
program will run the script (e.g <literal>#!/bin/bash</literal>). In
Nix, we want an exact path to that interpreter to be used. This
often replaces <literal>/bin/sh</literal> with a path in the
Nix store.
This setup hook patches installed scripts to use the full path to the
shebang interpreter. A shebang interpreter is the first commented line
of a script telling the operating system which program will run the
script (e.g <literal>#!/bin/bash</literal>). In Nix, we want an exact
path to that interpreter to be used. This often replaces
<literal>/bin/sh</literal> with a path in the Nix store.
</para>
</listitem>
</varlistentry>
@ -2271,10 +2334,10 @@ addEnvHooks "$hostOffset" myBashFunction
</term>
<listitem>
<para>
This verifies that no references are left from the install
binaries to the directory used to build those binaries. This
ensures that the binaries do not need things outside the Nix
store. This is currently supported in Linux only.
This verifies that no references are left from the install binaries to
the directory used to build those binaries. This ensures that the
binaries do not need things outside the Nix store. This is currently
supported in Linux only.
</para>
</listitem>
</varlistentry>
@ -2284,12 +2347,12 @@ addEnvHooks "$hostOffset" myBashFunction
</term>
<listitem>
<para>
This setup hook adds configure flags that tell packages to
install files into any one of the proper outputs listed in
<literal>outputs</literal>. This behavior can be turned off by setting
This setup hook adds configure flags that tell packages to install files
into any one of the proper outputs listed in <literal>outputs</literal>.
This behavior can be turned off by setting
<literal>setOutputFlags</literal> to false in the derivation
environment. See <xref linkend="chap-multiple-output"/> for
more information.
environment. See <xref linkend="chap-multiple-output"/> for more
information.
</para>
</listitem>
</varlistentry>
@ -2299,9 +2362,9 @@ addEnvHooks "$hostOffset" myBashFunction
</term>
<listitem>
<para>
This setup hook moves any binaries installed in the sbin
subdirectory into bin. In addition, a link is provided from
sbin to bin for compatibility.
This setup hook moves any binaries installed in the sbin subdirectory
into bin. In addition, a link is provided from sbin to bin for
compatibility.
</para>
</listitem>
</varlistentry>
@ -2311,9 +2374,9 @@ addEnvHooks "$hostOffset" myBashFunction
</term>
<listitem>
<para>
This setup hook moves any libraries installed in the lib64
subdirectory into lib. In addition, a link is provided from
lib64 to lib for compatibility.
This setup hook moves any libraries installed in the lib64 subdirectory
into lib. In addition, a link is provided from lib64 to lib for
compatibility.
</para>
</listitem>
</varlistentry>
@ -2323,8 +2386,8 @@ addEnvHooks "$hostOffset" myBashFunction
</term>
<listitem>
<para>
This sets <literal>SOURCE_DATE_EPOCH</literal> to the
modification time of the most recent file.
This sets <literal>SOURCE_DATE_EPOCH</literal> to the modification time
of the most recent file.
</para>
</listitem>
</varlistentry>
@ -2335,19 +2398,19 @@ addEnvHooks "$hostOffset" myBashFunction
<listitem>
<para>
The Bintools Wrapper wraps the binary utilities for a bunch of
miscellaneous purposes. These are GNU Binutils when targetting Linux, and
a mix of cctools and GNU binutils for Darwin. [The "Bintools" name is
supposed to be a compromise between "Binutils" and "cctools" not denoting
any specific implementation.] Specifically, the underlying bintools
package, and a C standard library (glibc or Darwin's libSystem, just for
the dynamic loader) are all fed in, and dependency finding, hardening
(see below), and purity checks for each are handled by the Bintools
Wrapper. Packages typically depend on CC Wrapper, which in turn (at run
time) depends on the Bintools Wrapper.
miscellaneous purposes. These are GNU Binutils when targetting Linux,
and a mix of cctools and GNU binutils for Darwin. [The "Bintools" name
is supposed to be a compromise between "Binutils" and "cctools" not
denoting any specific implementation.] Specifically, the underlying
bintools package, and a C standard library (glibc or Darwin's libSystem,
just for the dynamic loader) are all fed in, and dependency finding,
hardening (see below), and purity checks for each are handled by the
Bintools Wrapper. Packages typically depend on CC Wrapper, which in turn
(at run time) depends on the Bintools Wrapper.
</para>
<para>
The Bintools Wrapper was only just recently split off from CC Wrapper, so
the division of labor is still being worked out. For example, it
The Bintools Wrapper was only just recently split off from CC Wrapper,
so the division of labor is still being worked out. For example, it
shouldn't care about about the C standard library, but just take a
derivation with the dynamic loader (which happens to be the glibc on
linux). Dependency finding however is a task both wrappers will continue
@ -2357,11 +2420,12 @@ addEnvHooks "$hostOffset" myBashFunction
<varname>nativeBuildInputs</varname>) in environment variables. The
Bintools Wrapper's setup hook causes any <filename>lib</filename> and
<filename>lib64</filename> subdirectories to be added to
<envar>NIX_LDFLAGS</envar>. Since the CC Wrapper and the Bintools Wrapper
use the same strategy, most of the Bintools Wrapper code is sparsely
commented and refers to the CC Wrapper. But the CC Wrapper's code, by
contrast, has quite lengthy comments. The Bintools Wrapper merely cites
those, rather than repeating them, to avoid falling out of sync.
<envar>NIX_LDFLAGS</envar>. Since the CC Wrapper and the Bintools
Wrapper use the same strategy, most of the Bintools Wrapper code is
sparsely commented and refers to the CC Wrapper. But the CC Wrapper's
code, by contrast, has quite lengthy comments. The Bintools Wrapper
merely cites those, rather than repeating them, to avoid falling out of
sync.
</para>
<para>
A final task of the setup hook is defining a number of standard
@ -2370,8 +2434,8 @@ addEnvHooks "$hostOffset" myBashFunction
under the assumption that the Bintools Wrapper's binaries will be on the
path. Firstly, this helps poorly-written packages, e.g. ones that look
for just <command>gcc</command> when <envar>CC</envar> isn't defined yet
<command>clang</command> is to be used. Secondly, this helps packages not
get confused when cross-compiling, in which case multiple Bintools
<command>clang</command> is to be used. Secondly, this helps packages
not get confused when cross-compiling, in which case multiple Bintools
Wrappers may simultaneously be in use.
<footnote xml:id="footnote-stdenv-per-platform-wrapper">
<para>
@ -2387,16 +2451,16 @@ addEnvHooks "$hostOffset" myBashFunction
Wrappers, properly disambiguating them.
</para>
<para>
A problem with this final task is that the Bintools Wrapper is honest and
defines <envar>LD</envar> as <command>ld</command>. Most packages,
A problem with this final task is that the Bintools Wrapper is honest
and defines <envar>LD</envar> as <command>ld</command>. Most packages,
however, firstly use the C compiler for linking, secondly use
<envar>LD</envar> anyways, defining it as the C compiler, and thirdly,
only so define <envar>LD</envar> when it is undefined as a fallback. This
triple-threat means Bintools Wrapper will break those packages, as LD is
already defined as the actual linker which the package won't override yet
doesn't want to use. The workaround is to define, just for the
problematic package, <envar>LD</envar> as the C compiler. A good way to
do this would be <command>preConfigure = "LD=$CC"</command>.
only so define <envar>LD</envar> when it is undefined as a fallback.
This triple-threat means Bintools Wrapper will break those packages, as
LD is already defined as the actual linker which the package won't
override yet doesn't want to use. The workaround is to define, just for
the problematic package, <envar>LD</envar> as the C compiler. A good way
to do this would be <command>preConfigure = "LD=$CC"</command>.
</para>
</listitem>
</varlistentry>
@ -2406,13 +2470,13 @@ addEnvHooks "$hostOffset" myBashFunction
</term>
<listitem>
<para>
The CC Wrapper wraps a C toolchain for a bunch of miscellaneous purposes.
Specifically, a C compiler (GCC or Clang), wrapped binary tools, and a C
standard library (glibc or Darwin's libSystem, just for the dynamic
loader) are all fed in, and dependency finding, hardening (see below),
and purity checks for each are handled by the CC Wrapper. Packages
typically depend on the CC Wrapper, which in turn (at run-time) depends
on the Bintools Wrapper.
The CC Wrapper wraps a C toolchain for a bunch of miscellaneous
purposes. Specifically, a C compiler (GCC or Clang), wrapped binary
tools, and a C standard library (glibc or Darwin's libSystem, just for
the dynamic loader) are all fed in, and dependency finding, hardening
(see below), and purity checks for each are handled by the CC Wrapper.
Packages typically depend on the CC Wrapper, which in turn (at run-time)
depends on the Bintools Wrapper.
</para>
<para>
Dependency finding is undoubtedly the main task of the CC Wrapper. This
@ -2438,10 +2502,9 @@ addEnvHooks "$hostOffset" myBashFunction
</para>
<para>
Here are some more packages that provide a setup hook. Since the
list of hooks is extensible, this is not an exhaustive list the
mechanism is only to be used as a last resort, it might cover most
uses.
Here are some more packages that provide a setup hook. Since the list of
hooks is extensible, this is not an exhaustive list the mechanism is only to
be used as a last resort, it might cover most uses.
<variablelist>
<varlistentry>
<term>
@ -2499,11 +2562,11 @@ addEnvHooks "$hostOffset" myBashFunction
<listitem>
<para>
The <varname>autoreconfHook</varname> derivation adds
<varname>autoreconfPhase</varname>, which runs autoreconf, libtoolize and
automake, essentially preparing the configure script in autotools-based
builds. Most autotools-based packages come with the configure script
pre-generated, but this hook is necessary for a few packages and when you
need to patch the package’s configure scripts.
<varname>autoreconfPhase</varname>, which runs autoreconf, libtoolize
and automake, essentially preparing the configure script in
autotools-based builds. Most autotools-based packages come with the
configure script pre-generated, but this hook is necessary for a few
packages and when you need to patch the package’s configure scripts.
</para>
</listitem>
</varlistentry>
@ -2547,9 +2610,9 @@ addEnvHooks "$hostOffset" myBashFunction
</term>
<listitem>
<para>
Exports <envar>GDK_PIXBUF_MODULE_FILE</envar> environment variable to the
builder. Add librsvg package to <varname>buildInputs</varname> to get svg
support.
Exports <envar>GDK_PIXBUF_MODULE_FILE</envar> environment variable to
the builder. Add librsvg package to <varname>buildInputs</varname> to
get svg support.
</para>
</listitem>
</varlistentry>
@ -2595,14 +2658,13 @@ addEnvHooks "$hostOffset" myBashFunction
<para>
This is useful for programs that use <citerefentry>
<refentrytitle>dlopen</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry> to load libraries at runtime.
<manvolnum>3</manvolnum> </citerefentry> to load libraries at runtime.
</para>
<para>
In certain situations you may want to run the main command
(<command>autoPatchelf</command>) of the setup hook on a file or a set
of directories instead of unconditionally patching all outputs. This
can be done by setting the <envar>dontAutoPatchelf</envar> environment
of directories instead of unconditionally patching all outputs. This can
be done by setting the <envar>dontAutoPatchelf</envar> environment
variable to a non-empty value.
</para>
<para>
@ -2619,29 +2681,37 @@ addEnvHooks "$hostOffset" myBashFunction
<listitem>
<para>
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
<command>cntr</command> command. Upon build error it will print
instructions on how to use <command>cntr</command>. Installing
cntr and running the command will provide shell access to the build
sandbox of failed build. At <filename>/var/lib/cntr</filename> 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. Note that <command>cntr</command> also
needs to be executed on the machine that is doing the build, which might
not be the case when remote builders are enabled.
<command>cntr</command> is only supported on Linux-based platforms. To
use it first add <literal>cntr</literal> to your
<literal>environment.systemPackages</literal> on NixOS or alternatively to
the root user on non-NixOS systems. Then in the package that is supposed
to be inspected, add <literal>breakpointHook</literal> to
<literal>nativeBuildInputs</literal>.
happens. It prevents nix from cleaning up the build environment
immediately and allows the user to attach to a build environment using
the <command>cntr</command> command. Upon build error it will print
instructions on how to use <command>cntr</command>, 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 <filename>/var/lib/cntr</filename> 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. <command>cntr</command> is only supported
on Linux-based platforms. To use it first add <literal>cntr</literal> to
your <literal>environment.systemPackages</literal> on NixOS or
alternatively to the root user on non-NixOS systems. Then in the package
that is supposed to be inspected, add <literal>breakpointHook</literal>
to <literal>nativeBuildInputs</literal>.
<programlisting>
nativeBuildInputs = [ breakpointHook ];
</programlisting>
When a build failure happens there will be an instruction printed that
shows how to attach with <literal>cntr</literal> to the build sandbox.
</para>
<note>
<title>Caution with remote builds</title>
<para>
This won't work with remote builds as the build environment is on
a different machine and can't be accessed by <command>cntr</command>.
Remote builds can be turned off by setting <literal>--option builders ''</literal>
for <command>nix-build</command> or <literal>--builders ''</literal> for
<command>nix build</command>.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
@ -2650,14 +2720,13 @@ addEnvHooks "$hostOffset" myBashFunction
</term>
<listitem>
<para>
A few libraries automatically add to
<literal>NIX_LDFLAGS</literal> 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 <literal>dontAddExtraLibs</literal>.
A few libraries automatically add to <literal>NIX_LDFLAGS</literal>
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
<literal>dontAddExtraLibs</literal>.
</para>
</listitem>
</varlistentry>
@ -2668,15 +2737,15 @@ addEnvHooks "$hostOffset" myBashFunction
<listitem>
<para>
Overrides the default configure phase to run the CMake command. By
default, we use the Make generator of CMake. In
addition, dependencies are added automatically to CMAKE_PREFIX_PATH so
that packages are correctly detected by CMake. Some additional flags
are passed in to give similar behavior to configure-based packages. You
can disable this hook’s behavior by setting configurePhase to a custom
value, or by setting dontUseCmakeConfigure. cmakeFlags controls flags
passed only to CMake. By default, parallel building is enabled as CMake
supports parallel building almost everywhere. When Ninja is also in
use, CMake will detect that and use the ninja generator.
default, we use the Make generator of CMake. In addition, dependencies
are added automatically to CMAKE_PREFIX_PATH so that packages are
correctly detected by CMake. Some additional flags are passed in to give
similar behavior to configure-based packages. You can disable this
hook’s behavior by setting configurePhase to a custom value, or by
setting dontUseCmakeConfigure. cmakeFlags controls flags passed only to
CMake. By default, parallel building is enabled as CMake supports
parallel building almost everywhere. When Ninja is also in use, CMake
will detect that and use the ninja generator.
</para>
</listitem>
</varlistentry>
@ -2689,8 +2758,8 @@ addEnvHooks "$hostOffset" myBashFunction
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.
and configurePhase to a custom value. xcbuildFlags controls flags passed
only to xcbuild.
</para>
</listitem>
</varlistentry>
@ -2703,8 +2772,8 @@ addEnvHooks "$hostOffset" myBashFunction
Overrides the configure phase to run meson to generate Ninja files. You
can disable this behavior by setting configurePhase to a custom value,
or by setting dontUseMesonConfigure. To run these files, you should
accompany meson with ninja. mesonFlags controls only the flags passed
to meson. By default, parallel building is enabled as Meson supports
accompany meson with ninja. mesonFlags controls only the flags passed to
meson. By default, parallel building is enabled as Meson supports
parallel building almost everywhere.
</para>
</listitem>
@ -2740,9 +2809,9 @@ addEnvHooks "$hostOffset" myBashFunction
<listitem>
<para>
Overrides the configure, build, and install phases. This will run the
"waf" script used by many projects. If waf doesn’t exist, it will copy
the version of waf available in Nixpkgs wafFlags can be used to pass
flags to the waf script.
"waf" script used by many projects. If wafPath (default ./waf) doesn’t
exist, it will copy the version of waf available in Nixpkgs. wafFlags can
be used to pass flags to the waf script.
</para>
</listitem>
</varlistentry>

29
doc/submitting-changes.xml
View file

@ -36,8 +36,8 @@
</listitem>
</itemizedlist>
<screen>
$ git checkout 0998212
$ git checkout -b 'fix/pkg-name-update'
<prompt>$ </prompt>git checkout 0998212
<prompt>$ </prompt>git checkout -b 'fix/pkg-name-update'
</screen>
</para>
</listitem>
@ -351,25 +351,24 @@ Additional information.
</section>
<section xml:id="submitting-changes-tested-compilation">
<title>Tested compilation of all pkgs that depend on this change using <command>nox-review</command></title>
<title>Tested compilation of all pkgs that depend on this change using <command>nix-review</command></title>
<para>
If you are updating a package's version, you can use nox to make sure all
packages that depend on the updated package still compile correctly. This
can be done using the nox utility. The <command>nox-review</command>
utility can look for and build all dependencies either based on uncommited
changes with the <literal>wip</literal> option or specifying a github pull
request number.
</para>
<para>
review uncommitted changes:
<screen>nix-shell -p nox --run "nox-review wip"</screen>
If you are updating a package's version, you can use nix-review to make
sure all packages that depend on the updated package still compile
correctly. The <command>nix-review</command> utility can look for and build
all dependencies either based on uncommited changes with the
<literal>wip</literal> option or specifying a github pull request number.
</para>
<para>
review changes from pull request number 12345:
<screen>nix-shell -p nox --run "nox-review pr 12345"</screen>
<screen>nix-shell -p nix-review --run "nix-review pr 12345"</screen>
</para>
<para>
review uncommitted changes:
<screen>nix-shell -p nix-review --run "nix-review wip"</screen>
</para>
</section>

10
lib/default.nix
View file

@ -50,7 +50,7 @@ let
filesystem = callLibs ./filesystem.nix;
# back-compat aliases
platforms = systems.forMeta;
platforms = systems.doubles;
inherit (builtins) add addErrorContext attrNames concatLists
deepSeq elem elemAt filter genericClosure genList getAttr
@ -59,7 +59,7 @@ let
stringLength sub substring tail;
inherit (trivial) id const concat or and bitAnd bitOr bitXor bitNot
boolToString mergeAttrs flip mapNullable inNixShell min max
importJSON warn info nixpkgsVersion version mod compare
importJSON warn info showWarnings nixpkgsVersion version mod compare
splitByAndCompare functionArgs setFunctionArgs isFunction;
inherit (fixedPoints) fix fix' converge extends composeExtensions
makeExtensible makeExtensibleWithCustomName;
@ -71,7 +71,7 @@ let
zipAttrsWithNames zipAttrsWith zipAttrs recursiveUpdateUntil
recursiveUpdate matchAttrs overrideExisting getOutput getBin
getLib getDev chooseDevOutputs zipWithNames zip;
inherit (lists) singleton foldr fold foldl foldl' imap0 imap1
inherit (lists) singleton forEach foldr fold foldl foldl' imap0 imap1
concatMap flatten remove findSingle findFirst any all count
optional optionals toList range partition zipListsWith zipLists
reverseList listDfs toposort sort naturalSort compareLists take
@ -81,7 +81,7 @@ let
intersperse concatStringsSep concatMapStringsSep
concatImapStringsSep makeSearchPath makeSearchPathOutput
makeLibraryPath makeBinPath optionalString
hasPrefix hasSuffix stringToCharacters stringAsChars escape
hasInfix hasPrefix hasSuffix stringToCharacters stringAsChars escape
escapeShellArg escapeShellArgs replaceChars lowerChars
upperChars toLower toUpper addContextFrom splitString
removePrefix removeSuffix versionOlder versionAtLeast getVersion
@ -109,7 +109,7 @@ let
mkFixStrictness mkOrder mkBefore mkAfter mkAliasDefinitions
mkAliasAndWrapDefinitions fixMergeModules mkRemovedOptionModule
mkRenamedOptionModule mkMergedOptionModule mkChangedOptionModule
mkAliasOptionModule mkAliasOptionModuleWithPriority doRename filterModules;
mkAliasOptionModule doRename filterModules;
inherit (options) isOption mkEnableOption mkSinkUndeclaredOptions
mergeDefaultOption mergeOneOption mergeEqualOption getValues
getFiles optionAttrSetToDocList optionAttrSetToDocList'

7
lib/fixed-points.nix
View file

@ -30,9 +30,12 @@ rec {
# nix-repl> converge (x: x / 2) 16
# 0
converge = f: x:
if (f x) == x
let
x' = f x;
in
if x' == x
then x
else converge f (f x);
else converge f x';
# Modify the contents of an explicitly recursive attribute set in a way that
# honors `self`-references. This is accomplished with a function

2
lib/generators.nix
View file

@ -178,7 +178,7 @@ rec {
toPlist = {}: v: let
isFloat = builtins.isFloat or (x: false);
expr = ind: x: with builtins;
if isNull x then "" else
if x == null then "" else
if isBool x then bool ind x else
if isInt x then int ind x else
if isString x then str ind x else

21
lib/licenses.nix
View file

@ -145,6 +145,12 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
free = false;
};
cc-by-nc-30 = spdx {
spdxId = "CC-BY-NC-3.0";
fullName = "Creative Commons Attribution Non Commercial 3.0 Unported";
free = false;
};
cc-by-nc-40 = spdx {
spdxId = "CC-BY-NC-4.0";
fullName = "Creative Commons Attribution Non Commercial 4.0 International";
@ -428,12 +434,12 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
lgpl21 = spdx {
spdxId = "LGPL-2.1-only";
fullName = "GNU Library General Public License v2.1 only";
fullName = "GNU Lesser General Public License v2.1 only";
};
lgpl21Plus = spdx {
spdxId = "LGPL-2.1-or-later";
fullName = "GNU Library General Public License v2.1 or later";
fullName = "GNU Lesser General Public License v2.1 or later";
};
lgpl3 = spdx {
@ -451,9 +457,9 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
fullName = "libpng License";
};
libpng2 = {
fullName = "libpng License v2"; # 1.6.36+
url = "http://www.libpng.org/pub/png/src/libpng-LICENSE.txt";
libpng2 = spdx {
spdxId = "libpng-2.0"; # Used since libpng 1.6.36.
fullName = "PNG Reference Library version 2";
};
libtiff = spdx {
@ -561,6 +567,11 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
fullName = "OpenSSL License";
};
osl2 = spdx {
spdxId = "OSL-2.0";
fullName = "Open Software License 2.0";
};
osl21 = spdx {
spdxId = "OSL-2.1";
fullName = "Open Software License 2.1";

18
lib/lists.nix
View file

@ -7,7 +7,7 @@ let
in
rec {
inherit (builtins) head tail length isList elemAt concatLists filter elem genList;
inherit (builtins) head tail length isList elemAt concatLists filter elem genList map;
/* Create a list consisting of a single element. `singleton x` is
sometimes more convenient with respect to indentation than `[x]`
@ -21,6 +21,19 @@ rec {
*/
singleton = x: [x];
/* Apply the function to each element in the list. Same as `map`, but arguments
flipped.
Type: forEach :: [a] -> (a -> b) -> [b]
Example:
forEach [ 1 2 ] (x:
toString x
)
=> [ "1" "2" ]
*/
forEach = xs: f: map f xs;
/* “right fold” a binary function `op` between successive elements of
`list` with `nul' as the starting value, i.e.,
`foldr op nul [x_1 x_2 ... x_n] == op x_1 (op x_2 ... (op x_n nul))`.
@ -633,8 +646,7 @@ rec {
else
let
x = head list;
xs = unique (drop 1 list);
in [x] ++ remove x xs;
in [x] ++ unique (remove x list);
/* Intersects list 'e' and another list. O(nm) complexity.

48
lib/modules.nix
View file

@ -323,16 +323,14 @@ rec {
else
mergeDefinitions loc opt.type defs';
# Check whether the option is defined, and apply the ‘apply’
# function to the merged value. This allows options to yield a
# value computed from the definitions.
value =
if !res.isDefined then
throw "The option `${showOption loc}' is used but not defined."
else if opt ? apply then
opt.apply res.mergedValue
else
res.mergedValue;
# The value with a check that it is defined
valueDefined = if res.isDefined then res.mergedValue else
throw "The option `${showOption loc}' is used but not defined.";
# Apply the 'apply' function to the merged value. This allows options to
# yield a value computed from the definitions
value = if opt ? apply then opt.apply valueDefined else valueDefined;
in opt //
{ value = builtins.addErrorContext "while evaluating the option `${showOption loc}':" value;
@ -476,8 +474,22 @@ rec {
optionSet to options of type submodule. FIXME: remove
eventually. */
fixupOptionType = loc: opt:
let
options = opt.options or
(throw "Option `${showOption loc'}' has type optionSet but has no option attribute, in ${showFiles opt.declarations}.");
f = tp:
let optionSetIn = type: (tp.name == type) && (tp.functor.wrapped.name == "optionSet");
in
if tp.name == "option set" || tp.name == "submodule" then
throw "The option ${showOption loc} uses submodules without a wrapping type, in ${showFiles opt.declarations}."
else if optionSetIn "attrsOf" then types.attrsOf (types.submodule options)
else if optionSetIn "loaOf" then types.loaOf (types.submodule options)
else if optionSetIn "listOf" then types.listOf (types.submodule options)
else if optionSetIn "nullOr" then types.nullOr (types.submodule options)
else tp;
in
if opt.type.getSubModules or null == null
then opt // { type = opt.type or types.unspecified; }
then opt // { type = f (opt.type or types.unspecified); }
else opt // { type = opt.type.substSubModules opt.options; options = []; };
@ -596,6 +608,9 @@ rec {
forwards any definitions of boot.copyKernels to
boot.loader.grub.copyKernels while printing a warning.
This also copies over the priority from the aliased option to the
non-aliased option.
*/
mkRenamedOptionModule = from: to: doRename {
inherit from to;
@ -690,16 +705,7 @@ rec {
use = id;
};
/* Like ‘mkAliasOptionModule’, but copy over the priority of the option as well. */
mkAliasOptionModuleWithPriority = from: to: doRename {
inherit from to;
visible = true;
warn = false;
use = id;
withPriority = true;
};
doRename = { from, to, visible, warn, use, withPriority ? false }:
doRename = { from, to, visible, warn, use, withPriority ? true }:
{ config, options, ... }:
let
fromOpt = getAttrFromPath from options;

8
lib/options.nix
View file

@ -36,7 +36,7 @@ rec {
example ? null,
# String describing the option.
description ? null,
# Related packages used in the manual (see `genRelatedPackages` in ../nixos/doc/manual/default.nix).
# Related packages used in the manual (see `genRelatedPackages` in ../nixos/lib/make-options-doc/default.nix).
relatedPackages ? null,
# Option type, providing type-checking and value merging.
type ? null,
@ -48,6 +48,8 @@ rec {
visible ? null,
# Whether the option can be set only once
readOnly ? null,
# Deprecated, used by types.optionSet.
options ? null
} @ attrs:
attrs // { _type = "option"; };
@ -99,7 +101,7 @@ rec {
mergeOneOption = loc: defs:
if defs == [] then abort "This case should never happen."
else if length defs != 1 then
throw "The unique option `${showOption loc}' is defined multiple times, in ${showFiles (getFiles defs)}."
throw "The unique option `${showOption loc}' is defined multiple times, in:\n - ${concatStringsSep "\n - " (getFiles defs)}."
else (head defs).value;
/* "Merge" option definitions by checking that they all have the same value. */
@ -141,7 +143,7 @@ rec {
docOption = rec {
loc = opt.loc;
name = showOption opt.loc;
description = opt.description or (throw "Option `${name}' has no description.");
description = opt.description or (lib.warn "Option `${name}' has no description." "This option has no description.");
declarations = filter (x: x != unknownModule) opt.declarations;
internal = opt.internal or false;
visible = opt.visible or true;

16
lib/sources.nix
View file

@ -12,8 +12,8 @@ rec {
# Bring in a path as a source, filtering out all Subversion and CVS
# directories, as well as backup files (*~).
cleanSourceFilter = name: type: let baseName = baseNameOf (toString name); in ! (
# Filter out Subversion and CVS directories.
(type == "directory" && (baseName == ".git" || baseName == ".svn" || baseName == "CVS" || baseName == ".hg")) ||
# Filter out version control software files/directories
(baseName == ".git" || type == "directory" && (baseName == ".svn" || baseName == "CVS" || baseName == ".hg")) ||
# Filter out editor backup / swap files.
lib.hasSuffix "~" baseName ||
builtins.match "^\\.sw[a-z]$" baseName != null ||
@ -53,9 +53,13 @@ rec {
# Filter sources by a list of regular expressions.
#
# E.g. `src = sourceByRegex ./my-subproject [".*\.py$" "^database.sql$"]`
sourceByRegex = src: regexes: cleanSourceWith {
sourceByRegex = src: regexes:
let
isFiltered = src ? _isLibCleanSourceWith;
origSrc = if isFiltered then src.origSrc else src;
in lib.cleanSourceWith {
filter = (path: type:
let relPath = lib.removePrefix (toString src + "/") (toString path);
let relPath = lib.removePrefix (toString origSrc + "/") (toString path);
in lib.any (re: builtins.match re relPath != null) regexes);
inherit src;
};
@ -83,7 +87,7 @@ rec {
# Sometimes git stores the commitId directly in the file but
# sometimes it stores something like: «ref: refs/heads/branch-name»
matchRef = match "^ref: (.*)$" fileContent;
in if isNull matchRef
in if matchRef == null
then fileContent
else readCommitFromFile (lib.head matchRef) path
# Sometimes, the file isn't there at all and has been packed away in the
@ -92,7 +96,7 @@ rec {
then
let fileContent = readFile packedRefsName;
matchRef = match (".*\n([^\n ]*) " + file + "\n.*") fileContent;
in if isNull matchRef
in if matchRef == null
then throw ("Could not find " + file + " in " + packedRefsName)
else lib.head matchRef
else throw ("Not a .git directory: " + path);

2
lib/strings.nix
View file

@ -90,7 +90,7 @@ rec {
/* Same as `concatMapStringsSep`, but the mapping function
additionally receives the position of its argument.
Type: concatMapStringsSep :: string -> (int -> string -> string) -> [string] -> string
Type: concatIMapStringsSep :: string -> (int -> string -> string) -> [string] -> string
Example:
concatImapStringsSep "-" (pos: x: toString (x / pos)) [ 6 6 6 ]

31
lib/systems/default.nix
View file

@ -3,7 +3,6 @@
rec {
doubles = import ./doubles.nix { inherit lib; };
forMeta = import ./for-meta.nix { inherit lib; };
parse = import ./parse.nix { inherit lib; };
inspect = import ./inspect.nix { inherit lib; };
platforms = import ./platforms.nix { inherit lib; };
@ -15,7 +14,9 @@ rec {
# `parsed` is inferred from args, both because there are two options with one
# clearly prefered, and to prevent cycles. A simpler fixed point where the RHS
# always just used `final.*` would fail on both counts.
elaborate = args: let
elaborate = args': let
args = if lib.isString args' then { system = args'; }
else args';
final = {
# Prefer to parse `config` as it is strictly more informative.
parsed = parse.mkSystemFromString (if args ? config then args.config else args.system);
@ -24,15 +25,20 @@ rec {
config = parse.tripleFromSystem final.parsed;
# Just a guess, based on `system`
platform = platforms.selectBySystem final.system;
# Determine whether we are compatible with the provided CPU
isCompatible = platform: parse.isCompatible final.parsed.cpu platform.parsed.cpu;
# Derived meta-data
libc =
/**/ if final.isDarwin then "libSystem"
else if final.isMinGW then "msvcrt"
else if final.isWasi then "wasilibc"
else if final.isMusl then "musl"
else if final.isUClibc then "uclibc"
else if final.isAndroid then "bionic"
else if final.isLinux /* default */ then "glibc"
else if final.isMsp430 then "newlib"
else if final.isAvr then "avrlibc"
else if final.isNetBSD then "nblibc"
# TODO(@Ericson2314) think more about other operating systems
else "native/impure";
extensions = {
@ -58,7 +64,7 @@ rec {
"netbsd" = "NetBSD";
"freebsd" = "FreeBSD";
"openbsd" = "OpenBSD";
"wasm" = "Wasm";
"wasi" = "Wasi";
}.${final.parsed.kernel.name} or null;
# uname -p
@ -68,16 +74,22 @@ rec {
release = null;
};
kernelArch =
if final.isAarch32 then "arm"
else if final.isAarch64 then "arm64"
else if final.isx86_32 then "x86"
else if final.isx86_64 then "ia64"
else final.parsed.cpu.name;
qemuArch =
if final.isArm then "arm"
else if final.isx86_64 then "x86_64"
else if final.isx86 then "i386"
else {
"powerpc" = "ppc";
"powerpcle" = "ppc";
"powerpc64" = "ppc64";
"powerpc64le" = "ppc64";
"mips64" = "mips";
"mipsel64" = "mipsel";
"powerpc64le" = "ppc64le";
}.${final.parsed.cpu.name} or final.parsed.cpu.name;
emulator = pkgs: let
@ -98,13 +110,14 @@ rec {
wine = (pkgs.winePackagesFor wine-name).minimal;
in
if final.parsed.kernel.name == pkgs.stdenv.hostPlatform.parsed.kernel.name &&
(final.parsed.cpu.name == pkgs.stdenv.hostPlatform.parsed.cpu.name ||
(final.isi686 && pkgs.stdenv.hostPlatform.isx86_64))
then pkgs.runtimeShell
pkgs.stdenv.hostPlatform.isCompatible final
then "${pkgs.runtimeShell} -c '\"$@\"' --"
else if final.isWindows
then "${wine}/bin/${wine-name}"
else if final.isLinux && pkgs.stdenv.hostPlatform.isLinux
then "${qemu-user}/bin/qemu-${final.qemuArch}"
else if final.isWasi
then "${pkgs.wasmtime}/bin/wasmtime"
else throw "Don't know how to run ${final.config} executables.";
} // mapAttrs (n: v: v final.parsed) inspect.predicates

18
lib/systems/doubles.nix
View file

@ -13,10 +13,20 @@ let
"i686-cygwin" "i686-freebsd" "i686-linux" "i686-netbsd" "i686-openbsd"
"x86_64-cygwin" "x86_64-darwin" "x86_64-freebsd" "x86_64-linux"
"x86_64-cygwin" "x86_64-freebsd" "x86_64-linux"
"x86_64-netbsd" "x86_64-openbsd" "x86_64-solaris"
"x86_64-darwin" "i686-darwin" "aarch64-darwin" "armv7a-darwin"
"x86_64-windows" "i686-windows"
"wasm64-wasi" "wasm32-wasi"
"powerpc64le-linux"
"riscv32-linux" "riscv64-linux"
"aarch64-none" "avr-none" "arm-none" "i686-none" "x86_64-none" "powerpc-none" "msp430-none" "riscv64-none" "riscv32-none"
];
allParsed = map parse.mkSystemFromString all;
@ -34,6 +44,7 @@ in rec {
i686 = filterDoubles predicates.isi686;
x86_64 = filterDoubles predicates.isx86_64;
mips = filterDoubles predicates.isMips;
riscv = filterDoubles predicates.isRiscV;
cygwin = filterDoubles predicates.isCygwin;
darwin = filterDoubles predicates.isDarwin;
@ -45,7 +56,10 @@ in rec {
netbsd = filterDoubles predicates.isNetBSD;
openbsd = filterDoubles predicates.isOpenBSD;
unix = filterDoubles predicates.isUnix;
wasi = filterDoubles predicates.isWasi;
windows = filterDoubles predicates.isWindows;
mesaPlatforms = ["i686-linux" "x86_64-linux" "x86_64-darwin" "armv5tel-linux" "armv6l-linux" "armv7l-linux" "aarch64-linux" "powerpc64le-linux"];
embedded = filterDoubles predicates.isNone;
mesaPlatforms = ["i686-linux" "x86_64-linux" "x86_64-darwin" "armv5tel-linux" "armv6l-linux" "armv7l-linux" "armv7a-linux" "aarch64-linux" "powerpc64le-linux"];
}

49
lib/systems/examples.nix
View file

@ -44,14 +44,6 @@ rec {
platform = platforms.aarch64-multiplatform;
};
armv5te-android-prebuilt = rec {
config = "armv5tel-unknown-linux-androideabi";
sdkVer = "21";
ndkVer = "18b";
platform = platforms.armv5te-android;
useAndroidPrebuilt = true;
};
armv7a-android-prebuilt = rec {
config = "armv7a-unknown-linux-androideabi";
sdkVer = "24";
@ -96,12 +88,32 @@ rec {
config = "aarch64-unknown-linux-musl";
};
gnu64 = { config = "x86_64-unknown-linux-gnu"; };
gnu32 = { config = "i686-unknown-linux-gnu"; };
musl64 = { config = "x86_64-unknown-linux-musl"; };
musl32 = { config = "i686-unknown-linux-musl"; };
riscv64 = riscv "64";
riscv32 = riscv "32";
riscv64-embedded = {
config = "riscv64-none-elf";
libc = "newlib";
platform = platforms.riscv-multiplatform "64";
};
riscv32-embedded = {
config = "riscv32-none-elf";
libc = "newlib";
platform = platforms.riscv-multiplatform "32";
};
msp430 = {
config = "msp430-elf";
libc = "newlib";
};
avr = {
config = "avr";
};
@ -135,11 +147,6 @@ rec {
libc = "newlib";
};
alpha-embedded = {
config = "alpha-elf";
libc = "newlib";
};
i686-embedded = {
config = "i686-elf";
libc = "newlib";
@ -213,6 +220,22 @@ rec {
platform = {};
};
# BSDs
amd64-netbsd = {
config = "x86_64-unknown-netbsd";
libc = "nblibc";
};
#
# WASM
#
wasi32 = {
config = "wasm32-unknown-wasi";
useLLVM = true;
};
# Ghcjs
ghcjs = {
config = "js-unknown-ghcjs";

37
lib/systems/for-meta.nix
View file

@ -1,37 +0,0 @@
{ lib }:
let
inherit (lib.systems) parse;
inherit (lib.systems.inspect) patterns;
abis = lib.mapAttrs (_: abi: builtins.removeAttrs abi [ "assertions" ]) parse.abis;
in rec {
all = [ {} ]; # `{}` matches anything
none = [];
arm = [ patterns.isAarch32 ];
aarch64 = [ patterns.isAarch64 ];
x86 = [ patterns.isx86 ];
i686 = [ patterns.isi686 ];
x86_64 = [ patterns.isx86_64 ];
mips = [ patterns.isMips ];
riscv = [ patterns.isRiscV ];
cygwin = [ patterns.isCygwin ];
darwin = [ patterns.isDarwin ];
freebsd = [ patterns.isFreeBSD ];
# Should be better, but MinGW is unclear.
gnu = [
{ kernel = parse.kernels.linux; abi = abis.gnu; }
{ kernel = parse.kernels.linux; abi = abis.gnueabi; }
{ kernel = parse.kernels.linux; abi = abis.gnueabihf; }
];
illumos = [ patterns.isSunOS ];
linux = [ patterns.isLinux ];
netbsd = [ patterns.isNetBSD ];
openbsd = [ patterns.isOpenBSD ];
unix = patterns.isUnix; # Actually a list
windows = [ patterns.isWindows ];
inherit (lib.systems.doubles) mesaPlatforms;
}

4
lib/systems/inspect.nix
View file

@ -20,7 +20,9 @@ rec {
isRiscV = { cpu = { family = "riscv"; }; };
isSparc = { cpu = { family = "sparc"; }; };
isWasm = { cpu = { family = "wasm"; }; };
isMsp430 = { cpu = { family = "msp430"; }; };
isAvr = { cpu = { family = "avr"; }; };
isAlpha = { cpu = { family = "alpha"; }; };
is32bit = { cpu = { bits = 32; }; };
is64bit = { cpu = { bits = 64; }; };
@ -41,6 +43,8 @@ rec {
isWindows = { kernel = kernels.windows; };
isCygwin = { kernel = kernels.windows; abi = abis.cygnus; };
isMinGW = { kernel = kernels.windows; abi = abis.gnu; };
isWasi = { kernel = kernels.wasi; };
isNone = { kernel = kernels.none; };
isAndroid = [ { abi = abis.android; } { abi = abis.androideabi; } ];
isMusl = with abis; map (a: { abi = a; }) [ musl musleabi musleabihf ];

121
lib/systems/parse.nix
View file

@ -69,24 +69,24 @@ rec {
cpuTypes = with significantBytes; setTypes types.openCpuType {
arm = { bits = 32; significantByte = littleEndian; family = "arm"; };
armv5tel = { bits = 32; significantByte = littleEndian; family = "arm"; version = "5"; };
armv6m = { bits = 32; significantByte = littleEndian; family = "arm"; version = "6"; };
armv6l = { bits = 32; significantByte = littleEndian; family = "arm"; version = "6"; };
armv7a = { bits = 32; significantByte = littleEndian; family = "arm"; version = "7"; };
armv7r = { bits = 32; significantByte = littleEndian; family = "arm"; version = "7"; };
armv7m = { bits = 32; significantByte = littleEndian; family = "arm"; version = "7"; };
armv7l = { bits = 32; significantByte = littleEndian; family = "arm"; version = "7"; };
armv8a = { bits = 32; significantByte = littleEndian; family = "arm"; version = "8"; };
armv8r = { bits = 32; significantByte = littleEndian; family = "arm"; version = "8"; };
armv8m = { bits = 32; significantByte = littleEndian; family = "arm"; version = "8"; };
aarch64 = { bits = 64; significantByte = littleEndian; family = "arm"; version = "8"; };
aarch64_be = { bits = 64; significantByte = bigEndian; family = "arm"; version = "8"; };
armv5tel = { bits = 32; significantByte = littleEndian; family = "arm"; version = "5"; arch = "armv5t"; };
armv6m = { bits = 32; significantByte = littleEndian; family = "arm"; version = "6"; arch = "armv6-m"; };
armv6l = { bits = 32; significantByte = littleEndian; family = "arm"; version = "6"; arch = "armv6"; };
armv7a = { bits = 32; significantByte = littleEndian; family = "arm"; version = "7"; arch = "armv7-a"; };
armv7r = { bits = 32; significantByte = littleEndian; family = "arm"; version = "7"; arch = "armv7-r"; };
armv7m = { bits = 32; significantByte = littleEndian; family = "arm"; version = "7"; arch = "armv7-m"; };
armv7l = { bits = 32; significantByte = littleEndian; family = "arm"; version = "7"; arch = "armv7"; };
armv8a = { bits = 32; significantByte = littleEndian; family = "arm"; version = "8"; arch = "armv8-a"; };
armv8r = { bits = 32; significantByte = littleEndian; family = "arm"; version = "8"; arch = "armv8-a"; };
armv8m = { bits = 32; significantByte = littleEndian; family = "arm"; version = "8"; arch = "armv8-m"; };
aarch64 = { bits = 64; significantByte = littleEndian; family = "arm"; version = "8"; arch = "armv8-a"; };
aarch64_be = { bits = 64; significantByte = bigEndian; family = "arm"; version = "8"; arch = "armv8-a"; };
i386 = { bits = 32; significantByte = littleEndian; family = "x86"; };
i486 = { bits = 32; significantByte = littleEndian; family = "x86"; };
i586 = { bits = 32; significantByte = littleEndian; family = "x86"; };
i686 = { bits = 32; significantByte = littleEndian; family = "x86"; };
x86_64 = { bits = 64; significantByte = littleEndian; family = "x86"; };
i386 = { bits = 32; significantByte = littleEndian; family = "x86"; arch = "i386"; };
i486 = { bits = 32; significantByte = littleEndian; family = "x86"; arch = "i486"; };
i586 = { bits = 32; significantByte = littleEndian; family = "x86"; arch = "i586"; };
i686 = { bits = 32; significantByte = littleEndian; family = "x86"; arch = "i686"; };
x86_64 = { bits = 64; significantByte = littleEndian; family = "x86"; arch = "x86-64"; };
mips = { bits = 32; significantByte = bigEndian; family = "mips"; };
mipsel = { bits = 32; significantByte = littleEndian; family = "mips"; };
@ -109,11 +109,92 @@ rec {
alpha = { bits = 64; significantByte = littleEndian; family = "alpha"; };
msp430 = { bits = 16; significantByte = littleEndian; family = "msp430"; };
avr = { bits = 8; family = "avr"; };
js = { bits = 32; significantByte = littleEndian; family = "js"; };
};
# Determine where two CPUs are compatible with each other. That is,
# can we run code built for system b on system a? For that to
# happen, then the set of all possible possible programs that system
# b accepts must be a subset of the set of all programs that system
# a accepts. This compatibility relation forms a category where each
# CPU is an object and each arrow from a to b represents
# compatibility. CPUs with multiple modes of Endianness are
# isomorphic while all CPUs are endomorphic because any program
# built for a CPU can run on that CPU.
isCompatible = a: b: with cpuTypes; lib.any lib.id [
# x86
(b == i386 && isCompatible a i486)
(b == i486 && isCompatible a i586)
(b == i586 && isCompatible a i686)
# XXX: Not true in some cases. Like in WSL mode.
(b == i686 && isCompatible a x86_64)
# ARMv4
(b == arm && isCompatible a armv5tel)
# ARMv5
(b == armv5tel && isCompatible a armv6l)
# ARMv6
(b == armv6l && isCompatible a armv6m)
(b == armv6m && isCompatible a armv7l)
# ARMv7
(b == armv7l && isCompatible a armv7a)
(b == armv7l && isCompatible a armv7r)
(b == armv7l && isCompatible a armv7m)
(b == armv7a && isCompatible a armv8a)
(b == armv7r && isCompatible a armv8a)
(b == armv7m && isCompatible a armv8a)
(b == armv7a && isCompatible a armv8r)
(b == armv7r && isCompatible a armv8r)
(b == armv7m && isCompatible a armv8r)
(b == armv7a && isCompatible a armv8m)
(b == armv7r && isCompatible a armv8m)
(b == armv7m && isCompatible a armv8m)
# ARMv8
(b == armv8r && isCompatible a armv8a)
(b == armv8m && isCompatible a armv8a)
# XXX: not always true! Some arm64 cpus don’t support arm32 mode.
(b == aarch64 && a == armv8a)
(b == armv8a && isCompatible a aarch64)
(b == aarch64 && a == aarch64_be)
(b == aarch64_be && isCompatible a aarch64)
# PowerPC
(b == powerpc && isCompatible a powerpc64)
(b == powerpcle && isCompatible a powerpc)
(b == powerpc && a == powerpcle)
(b == powerpc64le && isCompatible a powerpc64)
(b == powerpc64 && a == powerpc64le)
# MIPS
(b == mips && isCompatible a mips64)
(b == mips && a == mipsel)
(b == mipsel && isCompatible a mips)
(b == mips64 && a == mips64el)
(b == mips64el && isCompatible a mips64)
# RISCV
(b == riscv32 && isCompatible a riscv64)
# SPARC
(b == sparc && isCompatible a sparc64)
# WASM
(b == wasm32 && isCompatible a wasm64)
# identity
(b == a)
];
################################################################################
types.openVendor = mkOptionType {
@ -147,6 +228,7 @@ rec {
elf = {};
macho = {};
pe = {};
wasm = {};
unknown = {};
};
@ -189,6 +271,7 @@ rec {
none = { execFormat = unknown; families = { }; };
openbsd = { execFormat = elf; families = { inherit bsd; }; };
solaris = { execFormat = elf; families = { }; };
wasi = { execFormat = wasm; families = { }; };
windows = { execFormat = pe; families = { }; };
ghcjs = { execFormat = unknown; families = { }; };
} // { # aliases
@ -298,6 +381,8 @@ rec {
then { cpu = elemAt l 0; kernel = elemAt l 1; abi = elemAt l 2; }
else if (elemAt l 2 == "mingw32") # autotools breaks on -gnu for window
then { cpu = elemAt l 0; vendor = elemAt l 1; kernel = "windows"; }
else if (elemAt l 2 == "wasi")
then { cpu = elemAt l 0; vendor = elemAt l 1; kernel = "wasi"; }
else if hasPrefix "netbsd" (elemAt l 2)
then { cpu = elemAt l 0; vendor = elemAt l 1; kernel = elemAt l 2; }
else if (elem (elemAt l 2) ["eabi" "eabihf" "elf"])
@ -348,7 +433,7 @@ rec {
mkSystemFromString = s: mkSystemFromSkeleton (mkSkeletonFromList (lib.splitString "-" s));
doubleFromSystem = { cpu, vendor, kernel, abi, ... }:
doubleFromSystem = { cpu, kernel, abi, ... }:
/**/ if abi == abis.cygnus then "${cpu.name}-cygwin"
else if kernel.families ? darwin then "${cpu.name}-darwin"
else "${cpu.name}-${kernel.name}";

11
lib/systems/platforms.nix
View file

@ -253,22 +253,11 @@ rec {
kernelTarget = "zImage";
};
# https://developer.android.com/ndk/guides/abis#armeabi
armv5te-android = {
name = "armeabi";
gcc = {
arch = "armv5te";
float = "soft";
float-abi = "soft";
};
};
# https://developer.android.com/ndk/guides/abis#v7a
armv7a-android = {
name = "armeabi-v7a";
gcc = {
arch = "armv7-a";
float = "hard";
float-abi = "softfp";
fpu = "vfpv3-d16";
};

11
lib/tests/modules.sh
View file

@ -71,6 +71,15 @@ checkConfigError 'The option value .* in .* is not of type.*positive integer.*'
checkConfigOutput "42" config.value ./declare-int-between-value.nix ./define-value-int-positive.nix
checkConfigError 'The option value .* in .* is not of type.*between.*-21 and 43.*inclusive.*' config.value ./declare-int-between-value.nix ./define-value-int-negative.nix
# Check either types
# types.either
checkConfigOutput "42" config.value ./declare-either.nix ./define-value-int-positive.nix
checkConfigOutput "\"24\"" config.value ./declare-either.nix ./define-value-string.nix
# types.oneOf
checkConfigOutput "42" config.value ./declare-oneOf.nix ./define-value-int-positive.nix
checkConfigOutput "[ ]" config.value ./declare-oneOf.nix ./define-value-list.nix
checkConfigOutput "\"24\"" config.value ./declare-oneOf.nix ./define-value-string.nix
# Check mkForce without submodules.
set -- config.enable ./declare-enable.nix ./define-enable.nix
checkConfigOutput "true" "$@"
@ -149,7 +158,7 @@ checkConfigOutput "1 2 3 4 5 6 7 8 9 10" config.result ./loaOf-with-long-list.ni
# Check loaOf with many merges of lists.
checkConfigOutput "1 2 3 4 5 6 7 8 9 10" config.result ./loaOf-with-many-list-merges.nix
# Check mkAliasOptionModuleWithPriority.
# Check mkAliasOptionModule.
checkConfigOutput "true" config.enable ./alias-with-priority.nix
checkConfigOutput "true" config.enableAlias ./alias-with-priority.nix
checkConfigOutput "false" config.enable ./alias-with-priority-can-override.nix

9
lib/tests/modules/alias-with-priority-can-override.nix
View file

@ -1,5 +1,8 @@
# This is a test to show that mkAliasOptionModule sets the priority correctly
# for aliased options.
#
# This test shows that an alias with a high priority is able to override
# a non-aliased option.
{ config, lib, ... }:
@ -32,10 +35,10 @@ with lib;
imports = [
# Create an alias for the "enable" option.
(mkAliasOptionModuleWithPriority [ "enableAlias" ] [ "enable" ])
(mkAliasOptionModule [ "enableAlias" ] [ "enable" ])
# Disable the aliased option, but with a default (low) priority so it
# should be able to be overridden by the next import.
# Disable the aliased option with a high priority so it
# should override the next import.
( { config, lib, ... }:
{
enableAlias = lib.mkForce false;

5
lib/tests/modules/alias-with-priority.nix
View file

@ -1,5 +1,8 @@
# This is a test to show that mkAliasOptionModule sets the priority correctly
# for aliased options.
#
# This test shows that an alias with a low priority is able to be overridden
# with a non-aliased option.
{ config, lib, ... }:
@ -32,7 +35,7 @@ with lib;
imports = [
# Create an alias for the "enable" option.
(mkAliasOptionModuleWithPriority [ "enableAlias" ] [ "enable" ])
(mkAliasOptionModule [ "enableAlias" ] [ "enable" ])
# Disable the aliased option, but with a default (low) priority so it
# should be able to be overridden by the next import.

5
lib/tests/modules/declare-either.nix Normal file
View file

@ -0,0 +1,5 @@
{ lib, ... }: {
options.value = lib.mkOption {
type = lib.types.either lib.types.int lib.types.str;
};
}

9
lib/tests/modules/declare-oneOf.nix Normal file
View file

@ -0,0 +1,9 @@
{ lib, ... }: {
options.value = lib.mkOption {
type = lib.types.oneOf [
lib.types.int
(lib.types.listOf lib.types.int)
lib.types.str
];
};
}

15
lib/tests/release.nix
View file

@ -1,11 +1,9 @@
{ pkgs ? import ((import ../.).cleanSource ../..) {} }:
pkgs.stdenv.mkDerivation {
name = "nixpkgs-lib-tests";
buildInputs = [ pkgs.nix ];
pkgs.runCommandNoCC "nixpkgs-lib-tests" {
buildInputs = [ pkgs.nix (import ./check-eval.nix) ];
NIX_PATH="nixpkgs=${pkgs.path}";
buildCommand = ''
} ''
datadir="${pkgs.nix}/share"
export TEST_ROOT=$(pwd)/test-tmp
export NIX_BUILD_HOOK=
@ -22,10 +20,5 @@ pkgs.stdenv.mkDerivation {
cd ${pkgs.path}/lib/tests
bash ./modules.sh
[[ "$(nix-instantiate --eval --strict misc.nix)" == "[ ]" ]]
[[ "$(nix-instantiate --eval --strict systems.nix)" == "[ ]" ]]
touch $out
'';
}
''

12
lib/tests/systems.nix
View file

@ -12,19 +12,19 @@ let
expected = lib.sort lib.lessThan y;
};
in with lib.systems.doubles; lib.runTests {
testall = mseteq all (linux ++ darwin ++ freebsd ++ openbsd ++ netbsd ++ illumos ++ windows);
testall = mseteq all (linux ++ darwin ++ freebsd ++ openbsd ++ netbsd ++ illumos ++ wasi ++ windows ++ embedded);
testarm = mseteq arm [ "armv5tel-linux" "armv6l-linux" "armv7l-linux" ];
testi686 = mseteq i686 [ "i686-linux" "i686-freebsd" "i686-netbsd" "i686-openbsd" "i686-cygwin" "i686-windows" ];
testarm = mseteq arm [ "armv5tel-linux" "armv6l-linux" "armv7l-linux" "arm-none" "armv7a-darwin" ];
testi686 = mseteq i686 [ "i686-linux" "i686-freebsd" "i686-netbsd" "i686-openbsd" "i686-cygwin" "i686-windows" "i686-none" "i686-darwin" ];
testmips = mseteq mips [ "mipsel-linux" ];
testx86_64 = mseteq x86_64 [ "x86_64-linux" "x86_64-darwin" "x86_64-freebsd" "x86_64-openbsd" "x86_64-netbsd" "x86_64-cygwin" "x86_64-solaris" "x86_64-windows" ];
testx86_64 = mseteq x86_64 [ "x86_64-linux" "x86_64-darwin" "x86_64-freebsd" "x86_64-openbsd" "x86_64-netbsd" "x86_64-cygwin" "x86_64-solaris" "x86_64-windows" "x86_64-none" ];
testcygwin = mseteq cygwin [ "i686-cygwin" "x86_64-cygwin" ];
testdarwin = mseteq darwin [ "x86_64-darwin" ];
testdarwin = mseteq darwin [ "x86_64-darwin" "i686-darwin" "aarch64-darwin" "armv7a-darwin" ];
testfreebsd = mseteq freebsd [ "i686-freebsd" "x86_64-freebsd" ];
testgnu = mseteq gnu (linux /* ++ kfreebsd ++ ... */);
testillumos = mseteq illumos [ "x86_64-solaris" ];
testlinux = mseteq linux [ "i686-linux" "x86_64-linux" "armv5tel-linux" "armv6l-linux" "armv7l-linux" "aarch64-linux" "mipsel-linux" ];
testlinux = mseteq linux [ "aarch64-linux" "armv5tel-linux" "armv6l-linux" "armv7l-linux" "i686-linux" "mipsel-linux" "riscv32-linux" "riscv64-linux" "x86_64-linux" "powerpc64le-linux" ];
testnetbsd = mseteq netbsd [ "i686-netbsd" "x86_64-netbsd" ];
testopenbsd = mseteq openbsd [ "i686-openbsd" "x86_64-openbsd" ];
testwindows = mseteq windows [ "i686-cygwin" "x86_64-cygwin" "i686-windows" "x86_64-windows" ];

7
lib/trivial.nix
View file

@ -112,7 +112,7 @@ rec {
# Function to call
f:
# Argument to check for null before passing it to `f`
a: if isNull a then a else f a;
a: if a == null then a else f a;
# Pull in some builtins not included elsewhere.
inherit (builtins)
@ -134,7 +134,7 @@ rec {
On each release the first letter is bumped and a new animal is chosen
starting with that new letter.
*/
codeName = "Koi";
codeName = "Loris";
/* Returns the current nixpkgs version suffix as string. */
versionSuffix =
@ -259,9 +259,10 @@ rec {
# TODO: figure out a clever way to integrate location information from
# something like __unsafeGetAttrPos.
warn = msg: builtins.trace "WARNING: ${msg}";
warn = msg: builtins.trace "warning: ${msg}";
info = msg: builtins.trace "INFO: ${msg}";
showWarnings = warnings: res: lib.fold (w: x: warn w x) res warnings;
## Function annotations

26
lib/types.nix
View file

@ -111,7 +111,7 @@ rec {
name = "int";
description = "signed integer";
check = isInt;
merge = mergeOneOption;
merge = mergeEqualOption;
};
# Specialized subdomains of int
@ -176,14 +176,14 @@ rec {
name = "float";
description = "floating point number";
check = isFloat;
merge = mergeOneOption;
merge = mergeEqualOption;
};
str = mkOptionType {
name = "str";
description = "string";
check = isString;
merge = mergeOneOption;
merge = mergeEqualOption;
};
strMatching = pattern: mkOptionType {
@ -217,7 +217,8 @@ rec {
# Deprecated; should not be used because it quietly concatenates
# strings, which is usually not what you want.
string = separatedString "";
string = warn "types.string is deprecated because it quietly concatenates strings"
(separatedString "");
attrs = mkOptionType {
name = "attrs";
@ -243,7 +244,7 @@ rec {
name = "path";
# Hacky: there is no ‘isPath’ primop.
check = x: builtins.substring 0 1 (toString x) == "/";
merge = mergeOneOption;
merge = mergeEqualOption;
};
# drop this in the future:
@ -415,7 +416,7 @@ rec {
name = "enum";
description = "one of ${concatMapStringsSep ", " show values}";
check = flip elem values;
merge = mergeOneOption;
merge = mergeEqualOption;
functor = (defaultFunctor name) // { payload = values; binOp = a: b: unique (a ++ b); };
};
@ -443,6 +444,13 @@ rec {
functor = (defaultFunctor name) // { wrapped = [ t1 t2 ]; };
};
# Any of the types in the given list
oneOf = ts:
let
head' = if ts == [] then throw "types.oneOf needs to get at least one type in its argument" else head ts;
tail' = tail ts;
in foldl' either head' tail';
# Either value of type `finalType` or `coercedType`, the latter is
# converted to `finalType` using `coerceFunc`.
coercedTo = coercedType: coerceFunc: finalType:
@ -469,8 +477,10 @@ rec {
# Obsolete alternative to configOf. It takes its option
# declarations from the ‘options’ attribute of containing option
# declaration.
optionSet = builtins.throw "types.optionSet is deprecated; use types.submodule instead" "optionSet";
optionSet = mkOptionType {
name = builtins.trace "types.optionSet is deprecated; use types.submodule instead" "optionSet";
description = "option set";
};
# Augment the given type with an additional type check function.
addCheck = elemType: check: elemType // { check = x: elemType.check x && check x; };

1962
maintainers/maintainer-list.nix
View file

File diff suppressed because it is too large Load diff

9
maintainers/scripts/fetch-kde-qt.sh
View file

@ -14,12 +14,13 @@ fi
tmp=$(mktemp -d)
pushd $tmp >/dev/null
wget -nH -r -c --no-parent "${WGET_ARGS[@]}" >/dev/null
wget -nH -r -c --no-parent "${WGET_ARGS[@]}" -A '*.tar.xz.sha256' -A '*.mirrorlist' >/dev/null
find -type f -name '*.mirrorlist' -delete
csv=$(mktemp)
find . -type f | while read src; do
# Sanitize file name
filename=$(basename "$src" | tr '@' '_')
filename=$(gawk '{ print $2 }' "$src" | tr '@' '_')
nameVersion="${filename%.tar.*}"
name=$(echo "$nameVersion" | sed -e 's,-[[:digit:]].*,,' | sed -e 's,-opensource-src$,,' | sed -e 's,-everywhere-src$,,')
version=$(echo "$nameVersion" | sed -e 's,^\([[:alpha:]][[:alnum:]]*-\)\+,,')
@ -38,8 +39,8 @@ gawk -F , "{ print \$1 }" $csv | sort | uniq | while read name; do
latestVersion=$(echo "$versions" | sort -rV | head -n 1)
src=$(gawk -F , "/^$name,$latestVersion,/ { print \$3 }" $csv)
filename=$(gawk -F , "/^$name,$latestVersion,/ { print \$4 }" $csv)
url="${src:2}"
sha256=$(nix-hash --type sha256 --base32 --flat "$src")
url="$(dirname "${src:2}")/$filename"
sha256=$(gawk '{ print $1 }' "$src")
cat >>"$SRCS" <<EOF
$name = {
version = "$latestVersion";

100
maintainers/scripts/luarocks-packages.csv
View file

@ -1,32 +1,68 @@
ansicolors,
argparse,
basexx,
cqueues
dkjson
fifo
inspect
lgi
lpeg_patterns
lpty
lrexlib-gnu,
lrexlib-posix,
ltermbox,
lua-cmsgpack,
lua_cliargs,
lua-iconv,
lua-term,
luabitop,
luaevent,
luacheck
luaffi,http://luarocks.org/dev,
luuid,
penlight,
say,
luv,
luasystem,
mediator_lua,http://luarocks.org/manifests/teto
mpack,http://luarocks.org/manifests/teto
nvim-client,http://luarocks.org/manifests/teto
busted,http://luarocks.org/manifests/teto
luassert,http://luarocks.org/manifests/teto
coxpcall,https://luarocks.org/manifests/hisham,1.17.0-1
# nix name, luarocks name, server, version,luaversion,maintainers
alt-getopt,,,,,arobyn
ansicolors,,,,,
argparse,,,,,
basexx,,,,,
binaryheap,,,,,vcunat
bit32,,,,lua5_1,lblasc
busted,,,,,
cjson,lua-cjson,,,,
compat53,,,,,vcunat
coxpcall,,,1.17.0-1,,
cqueues,,,,,vcunat
cyrussasl,,,,,vcunat
digestif,,http://luarocks.org/dev,,lua5_3,
dkjson,,,,,
fifo,,,,,
http,,,,,vcunat
inspect,,,,,
ldoc,,,,,
lgi,,,,,
ljsyscall,,,,lua5_1,lblasc
lpeg,,,,,vyp
lpeg_patterns,,,,,
lpeglabel,,,,,
lpty,,,,,
lrexlib-gnu,,,,,
lrexlib-pcre,,,,,vyp
lrexlib-posix,,,,,
ltermbox,,,,,
lua-cmsgpack,,,,,
lua-iconv,,,,,
lua-lsp,,http://luarocks.org/dev,,,
lua-messagepack,,,,,
lua-term,,,,,
lua-toml,,,,,
lua-zlib,,,,,koral
lua_cliargs,,,,,
luabitop,,,,,
luacheck,,,,,
luadbi,,,,,
luadbi-mysql,,,,,
luadbi-postgresql,,,,,
luadbi-sqlite3,,,,,
luaevent,,,,,
luaexpat,,,1.3.0-1,,arobyn flosse
luaffi,,http://luarocks.org/dev,,,
luafilesystem,,,1.7.0-2,,flosse vcunat
luaossl,,,,lua5_1,vcunat
luaposix,,,,,vyp lblasc
luasec,,,,,flosse
luasocket,,,,,
luasql-sqlite3,,,,,vyp
luassert,,,,,
luasystem,,,,,
luazip,,,,,
luuid,,,,,
luv,,,,,
markdown,,,,,
mediator_lua,,,,,
mpack,,,,,
moonscript,,,,,arobyn
nvim-client,,,,,
penlight,,,,,
rapidjson,,,,,
say,,,,,
std__debug,std._debug,,,,
std_normalize,std.normalize,,,,
stdlib,,,,,vyp

1 ansicolors, # nix name luarocks name server version luaversion maintainers
2 argparse, alt-getopt arobyn
3 basexx, ansicolors
4 cqueues argparse
5 dkjson basexx
6 fifo binaryheap vcunat
7 inspect bit32 lua5_1 lblasc
8 lgi busted
9 lpeg_patterns cjson lua-cjson
10 lpty compat53 vcunat
11 lrexlib-gnu, coxpcall 1.17.0-1
12 lrexlib-posix, cqueues vcunat
13 ltermbox, cyrussasl vcunat
14 lua-cmsgpack, digestif http://luarocks.org/dev lua5_3
15 lua_cliargs, dkjson
16 lua-iconv, fifo
17 lua-term, http vcunat
18 luabitop, inspect
19 luaevent, ldoc
20 luacheck lgi
21 luaffi,http://luarocks.org/dev, ljsyscall lua5_1 lblasc
22 luuid, lpeg vyp
23 penlight, lpeg_patterns
24 say, lpeglabel
25 luv, lpty
26 luasystem, lrexlib-gnu
27 mediator_lua,http://luarocks.org/manifests/teto lrexlib-pcre vyp
28 mpack,http://luarocks.org/manifests/teto lrexlib-posix
29 nvim-client,http://luarocks.org/manifests/teto ltermbox
30 busted,http://luarocks.org/manifests/teto lua-cmsgpack
31 luassert,http://luarocks.org/manifests/teto lua-iconv
32 coxpcall,https://luarocks.org/manifests/hisham,1.17.0-1 lua-lsp http://luarocks.org/dev
33 lua-messagepack
34 lua-term
35 lua-toml
36 lua-zlib koral
37 lua_cliargs
38 luabitop
39 luacheck
40 luadbi
41 luadbi-mysql
42 luadbi-postgresql
43 luadbi-sqlite3
44 luaevent
45 luaexpat 1.3.0-1 arobyn flosse
46 luaffi http://luarocks.org/dev
47 luafilesystem 1.7.0-2 flosse vcunat
48 luaossl lua5_1 vcunat
49 luaposix vyp lblasc
50 luasec flosse
51 luasocket
52 luasql-sqlite3 vyp
53 luassert
54 luasystem
55 luazip
56 luuid
57 luv
58 markdown
59 mediator_lua
60 mpack
61 moonscript arobyn
62 nvim-client
63 penlight
64 rapidjson
65 say
66 std__debug std._debug
67 std_normalize std.normalize
68 stdlib vyp

2
maintainers/scripts/nixpkgs-lint.nix
View file

@ -5,7 +5,7 @@ stdenv.mkDerivation {
buildInputs = [ makeWrapper perl perlPackages.XMLSimple ];
unpackPhase = "true";
dontUnpack = true;
buildPhase = "true";
installPhase =

36
maintainers/scripts/update-discord Executable file
View file

@ -0,0 +1,36 @@
#!/usr/bin/env bash
# script to generate `pkgs/networking/instant-messengers/discord/default.nix`
set -e
exec >${1:?usage: $0 <output-file>}
cat <<EOF
{ branch ? "stable", pkgs }:
let
inherit (pkgs) callPackage fetchurl;
in {
EOF
for branch in "" ptb canary; do
url=$(curl -sI "https://discordapp.com/api/download${branch:+/}${branch}?platform=linux&format=tar.gz" | grep -oP 'location: \K\S+')
version=${url##https://dl*.discordapp.net/apps/linux/}
version=${version%%/*.tar.gz}
echo " ${branch:-stable} = callPackage ./base.nix {"
echo " pname = \"discord${branch:+-}${branch}\";"
case $branch in
"") suffix="" ;;
ptb) suffix="PTB" ;;
canary) suffix="Canary" ;;
esac
echo " binaryName = \"Discord${suffix}\";"
echo " desktopName = \"Discord${suffix:+ }${suffix}\";"
echo " version = \"${version}\";"
echo " src = fetchurl {"
echo " url = \"${url}\";"
echo " sha256 = \"$(nix-prefetch-url "$url")\";"
echo " };"
echo " };"
done
echo "}.\${branch}"

91
maintainers/scripts/update-luarocks-packages
View file

@ -1,5 +1,5 @@
#!/usr/bin/env nix-shell
#!nix-shell -p nix-prefetch-scripts luarocks-nix -i bash
#!nix-shell update-luarocks-shell.nix -i bash
# You'll likely want to use
# ``
@ -8,24 +8,22 @@
# to update all libraries in that folder.
# to debug, redirect stderr to stdout with 2>&1
# stop the script upon C-C
set -eu -o pipefail
if [ $# -lt 1 ]; then
print_help
exit 1
fi
CSV_FILE="maintainers/scripts/luarocks-packages.csv"
TMP_FILE="$(mktemp)"
# Set in the update-luarocks-shell.nix
NIXPKGS_PATH="$LUAROCKS_NIXPKGS_PATH"
exit_trap()
{
# 10 is a pretty arbitrary number of simultaneous jobs, but it is generally
# impolite to hit a webserver with *too* many simultaneous connections :)
PARALLEL_JOBS=10
exit_trap() {
local lc="$BASH_COMMAND" rc=$?
test $rc -eq 0 || echo -e "*** error $rc: $lc.\nGenerated temporary file in $TMP_FILE" >&2
}
trap exit_trap EXIT
print_help() {
echo "Usage: $0 <GENERATED_FILE>"
@ -35,6 +33,12 @@ print_help() {
exit 1
}
if [ $# -lt 1 ]; then
print_help
exit 1
fi
trap exit_trap EXIT
while getopts ":hc:" opt; do
case $opt in
@ -61,7 +65,7 @@ nixpkgs$ ${0} ${GENERATED_NIXFILE}
These packages are manually refined in lua-overrides.nix
*/
{ self, lua, stdenv, fetchurl, fetchgit, pkgs, ... } @ args:
{ self, stdenv, fetchurl, fetchgit, pkgs, ... } @ args:
self: super:
with self;
{
@ -72,41 +76,60 @@ FOOTER="
/* GENERATED */
"
function convert_pkg() {
pkg="$1"
server=""
if [ ! -z "$2" ]; then
server=" --server=$2"
nix_pkg_name="$1"
lua_pkg_name="$2"
server="$3"
pkg_version="$4"
lua_version="$5"
maintainers="$6"
if [ "${nix_pkg_name:0:1}" == "#" ]; then
echo "Skipping comment ${*}" >&2
return
fi
if [ -z "$lua_pkg_name" ]; then
echo "Using nix_name as lua_pkg_name for '$nix_pkg_name'" >&2
lua_pkg_name="$nix_pkg_name"
fi
version="${3:-}"
echo "looking at $pkg (version $version) from server [$server]" >&2
cmd="luarocks nix $server $pkg $version"
drv="$($cmd)"
if [ $? -ne 0 ]; then
echo "Failed to convert $pkg" >&2
echo "$drv" >&2
echo "Building expression for $lua_pkg_name (version $pkg_version) from server [$server]" >&2
luarocks_args=(nix)
if [[ -n $server ]]; then
luarocks_args+=("--only-server=$server")
fi
if [[ -n $maintainers ]]; then
luarocks_args+=("--maintainers=$maintainers")
fi
if [[ -n $lua_version ]]; then
lua_drv_path=$(nix-build --no-out-link "$NIXPKGS_PATH" -A "$lua_version")
luarocks_args+=("--lua-dir=$lua_drv_path/bin")
fi
luarocks_args+=("$lua_pkg_name")
if [[ -n $pkg_version ]]; then
luarocks_args+=("$pkg_version")
fi
echo "Running 'luarocks ${luarocks_args[*]}'" >&2
if drv="$nix_pkg_name = $(luarocks "${luarocks_args[@]}")"; then
echo "$drv"
else
echo "$drv" | tee -a "$TMP_FILE"
echo "Failed to convert $nix_pkg_name" >&2
return 1
fi
}
# params needed when called via callPackage
echo "$HEADER" | tee "$TMP_FILE"
# list of packages with format
# name,server,version
while IFS=, read -r pkg_name server version
do
if [ -z "$pkg_name" ]; then
echo "Skipping empty package name" >&2
fi
convert_pkg "$pkg_name" "$server" "$version"
done < "$CSV_FILE"
# Ensure parallel can run our bash function
export -f convert_pkg
export SHELL=bash
# Read each line in the csv file and run convert_pkg for each, in parallel
parallel --group --keep-order --halt now,fail=1 --jobs "$PARALLEL_JOBS" --colsep ',' convert_pkg {} <"$CSV_FILE" | tee -a "$TMP_FILE"
# close the set
echo "$FOOTER" | tee -a "$TMP_FILE"
cp "$TMP_FILE" "$GENERATED_NIXFILE"
# vim: set ts=4 sw=4 ft=sh:

9
maintainers/scripts/update-luarocks-shell.nix Normal file
View file

@ -0,0 +1,9 @@
{ nixpkgs ? import ../.. { }
}:
with nixpkgs;
mkShell {
buildInputs = [
bash luarocks-nix nix-prefetch-scripts parallel
];
LUAROCKS_NIXPKGS_PATH = toString nixpkgs.path;
}

19
maintainers/scripts/update.nix
View file

@ -20,7 +20,9 @@ let
in
[x] ++ nubOn f xs;
pkgs = import ./../../default.nix { };
pkgs = import ./../../default.nix {
overlays = [];
};
packagesWith = cond: return: set:
nubOn (pkg: pkg.updateScript)
@ -67,6 +69,9 @@ let
let
attrSet = pkgs.lib.attrByPath (pkgs.lib.splitString "." path) null pkgs;
in
if attrSet == null then
builtins.throw "Attribute path `${path}` does not exists."
else
packagesWith (name: pkg: builtins.hasAttr "updateScript" pkg)
(name: pkg: pkg)
attrSet;
@ -122,9 +127,17 @@ let
packageData = package: {
name = package.name;
pname = (builtins.parseDrvName package.name).name;
updateScript = pkgs.lib.toList package.updateScript;
updateScript = map builtins.toString (pkgs.lib.toList package.updateScript);
};
packagesJson = pkgs.writeText "packages.json" (builtins.toJSON (map packageData packages));
optionalArgs =
pkgs.lib.optional (max-workers != null) "--max-workers=${max-workers}"
++ pkgs.lib.optional (keep-going == "true") "--keep-going";
args = [ packagesJson ] ++ optionalArgs;
in pkgs.stdenv.mkDerivation {
name = "nixpkgs-update-script";
buildCommand = ''
@ -139,6 +152,6 @@ in pkgs.stdenv.mkDerivation {
'';
shellHook = ''
unset shellHook # do not contaminate nested shells
exec ${pkgs.python3.interpreter} ${./update.py} ${pkgs.writeText "packages.json" (builtins.toJSON (map packageData packages))}${pkgs.lib.optionalString (max-workers != null) " --max-workers=${max-workers}"}${pkgs.lib.optionalString (keep-going == "true") " --keep-going"}
exec ${pkgs.python3.interpreter} ${./update.py} ${builtins.concatStringsSep " " args}
'';
}

7
nixos/doc/manual/Makefile
View file

@ -6,13 +6,14 @@ debug: generated manual-combined.xml
manual-combined.xml: generated *.xml **/*.xml
rm -f ./manual-combined.xml
nix-shell --packages xmloscopy \
nix-shell --pure -Q --packages xmloscopy \
--run "xmloscopy --docbook5 ./manual.xml ./manual-combined.xml"
.PHONY: format
format:
find ../../ -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \
xmlformat --config-file "../xmlformat.conf" -i {}
nix-shell --pure -Q --packages xmlformat \
--run "find ../../ -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \
xmlformat --config-file '../xmlformat.conf' -i {}"
.PHONY: fix-misc-xml
fix-misc-xml:

10
nixos/doc/manual/administration/cleaning-store.xml
View file

@ -11,12 +11,12 @@
Nix’s <emphasis>garbage collector</emphasis> to remove old, unreferenced
packages. This is easy:
<screen>
$ nix-collect-garbage
<prompt>$ </prompt>nix-collect-garbage
</screen>
Alternatively, you can use a systemd unit that does the same in the
background:
<screen>
# systemctl start nix-gc.service
<prompt># </prompt>systemctl start nix-gc.service
</screen>
You can tell NixOS in <filename>configuration.nix</filename> to run this unit
automatically at certain points in time, for instance, every night at 03:15:
@ -31,11 +31,11 @@ $ nix-collect-garbage
configurations. The following command deletes old roots, removing the ability
to roll back to them:
<screen>
$ nix-collect-garbage -d
<prompt>$ </prompt>nix-collect-garbage -d
</screen>
You can also do this for specific profiles, e.g.
<screen>
$ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
<prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
</screen>
Note that NixOS system configurations are stored in the profile
<filename>/nix/var/nix/profiles/system</filename>.
@ -45,7 +45,7 @@ $ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations o
Nix store) is to run Nix’s store optimiser, which seeks out identical files
in the store and replaces them with hard links to a single copy.
<screen>
$ nix-store --optimise
<prompt>$ </prompt>nix-store --optimise
</screen>
Since this command needs to read the entire Nix store, it can take quite a
while to finish.

4
nixos/doc/manual/administration/container-networking.xml
View file

@ -11,10 +11,10 @@
<literal>10.233.0.0/16</literal>. You can get the container’s IPv4 address
as follows:
<screen>
# nixos-container show-ip foo
<prompt># </prompt>nixos-container show-ip foo
10.233.4.2
$ ping -c1 10.233.4.2
<prompt>$ </prompt>ping -c1 10.233.4.2
64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms
</screen>
</para>

2
nixos/doc/manual/administration/control-groups.xml
View file

@ -16,7 +16,7 @@
<literal>systemd</literal> hierarchy, which is what systemd uses to keep
track of the processes belonging to each service or user session:
<screen>
$ systemd-cgls
<prompt>$ </prompt>systemd-cgls
├─user
│ └─eelco
│ └─c1

7
nixos/doc/manual/administration/imperative-containers.xml
View file

@ -29,6 +29,13 @@
<xref linkend="opt-services.openssh.enable"/> = true;
<link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.users.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"];
'
</screen>
By default the next free address in the <literal>10.233.0.0/16</literal> subnet will be chosen
as container IP. This behavior can be altered by setting <literal>--host-address</literal> and
<literal>--local-address</literal>:
<screen>
# nixos-container create test --config-file test-container.nix \
--local-address 10.235.1.2 --host-address 10.235.1.1
</screen>
</para>

6
nixos/doc/manual/administration/logging.xml
View file

@ -11,14 +11,14 @@
The command <literal>journalctl</literal> allows you to see the contents of
the journal. For example,
<screen>
$ journalctl -b
<prompt>$ </prompt>journalctl -b
</screen>
shows all journal entries since the last reboot. (The output of
<command>journalctl</command> is piped into <command>less</command> by
default.) You can use various options and match operators to restrict output
to messages of interest. For instance, to get all messages from PostgreSQL:
<screen>
$ journalctl -u postgresql.service
<prompt>$ </prompt>journalctl -u postgresql.service
-- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. --
...
Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down
@ -29,7 +29,7 @@ Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG: database system is ready to
Or to get all messages since the last reboot that have at least a
“critical” severity level:
<screen>
$ journalctl -b -p crit
<prompt>$ </prompt>journalctl -b -p crit
Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice]
Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1)
</screen>

2
nixos/doc/manual/administration/rollback.xml
View file

@ -33,7 +33,7 @@
where <replaceable>N</replaceable> is the number of the NixOS system
configuration. To get a list of the available configurations, do:
<screen>
$ ls -l /nix/var/nix/profiles/system-*-link
<prompt>$ </prompt>ls -l /nix/var/nix/profiles/system-*-link
<replaceable>...</replaceable>
lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055
</screen>

2
nixos/doc/manual/administration/running.xml
View file

@ -4,7 +4,7 @@
version="5.0"
xml:id="ch-running">
<title>Administration</title>
<partintro>
<partintro xml:id="ch-running-intro">
<para>
This chapter describes various aspects of managing a running NixOS system,
such as how to use the <command>systemd</command> service manager.

4
nixos/doc/manual/administration/service-mgmt.xml
View file

@ -21,7 +21,7 @@
<command>systemd</command>. Without any arguments, it shows the status of
active units:
<screen>
$ systemctl
<prompt>$ </prompt>systemctl
-.mount loaded active mounted /
swapfile.swap loaded active active /swapfile
sshd.service loaded active running SSH Daemon
@ -33,7 +33,7 @@ graphical.target loaded active active Graphical Interface
You can ask for detailed status information about a unit, for instance, the
PostgreSQL database service:
<screen>
$ systemctl status postgresql.service
<prompt>$ </prompt>systemctl status postgresql.service
postgresql.service - PostgreSQL Server
Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service)
Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago

4
nixos/doc/manual/administration/store-corruption.xml
View file

@ -18,7 +18,7 @@
If the corruption is in a path in the closure of the NixOS system
configuration, you can fix it by doing
<screen>
# nixos-rebuild switch --repair
<prompt># </prompt>nixos-rebuild switch --repair
</screen>
This will cause Nix to check every path in the closure, and if its
cryptographic hash differs from the hash recorded in Nix’s database, the
@ -28,7 +28,7 @@
<para>
You can also scan the entire Nix store for corrupt paths:
<screen>
# nix-store --verify --check-contents --repair
<prompt># </prompt>nix-store --verify --check-contents --repair
</screen>
Any corrupt paths will be redownloaded if they’re available in a binary
cache; otherwise, they cannot be repaired.

4
nixos/doc/manual/administration/user-sessions.xml
View file

@ -10,7 +10,7 @@
allows querying and manipulating user sessions. For instance, to list all
user sessions:
<screen>
$ loginctl
<prompt>$ </prompt>loginctl
SESSION UID USER SEAT
c1 500 eelco seat0
c3 0 root seat0
@ -21,7 +21,7 @@ $ loginctl
devices attached to the system; usually, there is only one seat.) To get
information about a session:
<screen>
$ loginctl session-status c3
<prompt>$ </prompt>loginctl session-status c3
c3 - root (0)
Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago
Leader: 2536 (login)

10
nixos/doc/manual/configuration/ad-hoc-packages.xml
View file

@ -9,7 +9,7 @@
With the command <command>nix-env</command>, you can install and uninstall
packages from the command line. For instance, to install Mozilla Thunderbird:
<screen>
$ nix-env -iA nixos.thunderbird</screen>
<prompt>$ </prompt>nix-env -iA nixos.thunderbird</screen>
If you invoke this as root, the package is installed in the Nix profile
<filename>/nix/var/nix/profiles/default</filename> and visible to all users
of the system; otherwise, the package ends up in
@ -25,7 +25,7 @@ $ nix-env -iA nixos.thunderbird</screen>
Packages come from the NixOS channel. You typically upgrade a package by
updating to the latest version of the NixOS channel:
<screen>
$ nix-channel --update nixos
<prompt>$ </prompt>nix-channel --update nixos
</screen>
and then running <literal>nix-env -i</literal> again. Other packages in the
profile are <emphasis>not</emphasis> affected; this is the crucial difference
@ -34,21 +34,21 @@ $ nix-channel --update nixos
their current versions in the NixOS channel. You can however upgrade all
packages for which there is a newer version by doing:
<screen>
$ nix-env -u '*'
<prompt>$ </prompt>nix-env -u '*'
</screen>
</para>
<para>
A package can be uninstalled using the <option>-e</option> flag:
<screen>
$ nix-env -e thunderbird
<prompt>$ </prompt>nix-env -e thunderbird
</screen>
</para>
<para>
Finally, you can roll back an undesirable <command>nix-env</command> action:
<screen>
$ nix-env --rollback
<prompt>$ </prompt>nix-env --rollback
</screen>
</para>

8
nixos/doc/manual/configuration/adding-custom-packages.xml
View file

@ -14,8 +14,8 @@
xlink:href="http://nixos.org/nixpkgs/manual">Nixpkgs
manual</link>. In short, you clone Nixpkgs:
<screen>
$ git clone https://github.com/NixOS/nixpkgs
$ cd nixpkgs
<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs
<prompt>$ </prompt>cd nixpkgs
</screen>
Then you write and test the package as described in the Nixpkgs manual.
Finally, you add it to <literal>environment.systemPackages</literal>, e.g.
@ -65,8 +65,8 @@ stdenv.mkDerivation rec {
</programlisting>
This allows testing the package easily:
<screen>
$ nix-build my-hello.nix
$ ./result/bin/hello
<prompt>$ </prompt>nix-build my-hello.nix
<prompt>$ </prompt>./result/bin/hello
Hello, world!
</screen>
</para>

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