diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 000000000000..4862e0eab93c
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,16 @@
+**/deps.nix linguist-generated
+**/node-packages.nix linguist-generated
+
+pkgs/applications/editors/emacs-modes/*-generated.nix linguist-generated
+pkgs/development/r-modules/*-packages.nix linguist-generated
+pkgs/development/haskell-modules/hackage-packages.nix linguist-generated
+pkgs/development/beam-modules/hex-packages.nix linguist-generated
+
+doc/** linguist-documentation
+doc/default.nix linguist-documentation=false
+
+nixos/doc/** linguist-documentation
+nixos/doc/default.nix linguist-documentation=false
+
+nixos/modules/module-list.nix merge=union
+# pkgs/top-level/all-packages.nix merge=union
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 9e89cc78954f..4e508d739e6a 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -10,18 +10,20 @@
# This file
/.github/CODEOWNERS @edolstra
-# Boostraping and core infra
-/pkgs/stdenv @edolstra
-/pkgs/build-support/cc-wrapper @edolstra
-
# Libraries
/lib @edolstra @nbp
+/lib/systems @nbp @ericson2314
+/lib/generators.nix @edolstra @nbp @Profpatsch
# Nixpkgs Internals
-/default.nix @nbp
-/pkgs/top-level/default.nix @nbp
-/pkgs/top-level/impure.nix @nbp
-/pkgs/top-level/stage.nix @nbp
+/default.nix @nbp
+/pkgs/top-level/default.nix @nbp @Ericson2314
+/pkgs/top-level/impure.nix @nbp @Ericson2314
+/pkgs/top-level/stage.nix @nbp @Ericson2314
+/pkgs/stdenv
+/pkgs/build-support/cc-wrapper @Ericson2314 @orivej
+/pkgs/build-support/bintools-wrapper @Ericson2314 @orivej
+/pkgs/build-support/setup-hooks @Ericson2314
# NixOS Internals
/nixos/default.nix @nbp
@@ -62,6 +64,9 @@
/pkgs/development/interpreters/ruby @zimbatm
/pkgs/development/ruby-modules @zimbatm
+# Rust
+/pkgs/development/compilers/rust @Mic92 @LnL7
+
# Darwin-related
/pkgs/stdenv/darwin @NixOS/darwin-maintainers
/pkgs/os-specific/darwin @NixOS/darwin-maintainers
@@ -82,4 +87,10 @@
/pkgs/applications/editors/eclipse @rycee
# https://github.com/NixOS/nixpkgs/issues/31401
-/lib/maintainers.nix @ghost
+/lib/licenses.nix @ghost
+
+# Qt / KDE
+/pkgs/applications/kde @ttuegel
+/pkgs/desktops/plasma-5 @ttuegel
+/pkgs/development/libraries/kde-frameworks @ttuegel
+/pkgs/development/libraries/qt-5 @ttuegel
diff --git a/.version b/.version
index a88d2ca32319..770bde1f44b3 100644
--- a/.version
+++ b/.version
@@ -1 +1 @@
-18.03
+18.09
diff --git a/COPYING b/COPYING
index afc460fff5cb..198597a1b410 100644
--- a/COPYING
+++ b/COPYING
@@ -1,4 +1,4 @@
-Copyright (c) 2003-2017 Eelco Dolstra and the Nixpkgs/NixOS contributors
+Copyright (c) 2003-2018 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
diff --git a/README.md b/README.md
index 64cfb25eac34..9714bbd1ab30 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,9 @@
-[](https://nixos.org/nixos)
+[](https://nixos.org/nixos)
-[![Build Status](https://travis-ci.org/NixOS/nixpkgs.svg?branch=master)](https://travis-ci.org/NixOS/nixpkgs)
[![Code Triagers Badge](https://www.codetriage.com/nixos/nixpkgs/badges/users.svg)](https://www.codetriage.com/nixos/nixpkgs)
Nixpkgs is a collection of packages for the [Nix](https://nixos.org/nix/) package
-manager. It is periodically built and tested by the [hydra](http://hydra.nixos.org/)
+manager. It is periodically built and tested by the [Hydra](https://hydra.nixos.org/)
build daemon as so-called channels. To get channel information via git, add
[nixpkgs-channels](https://github.com/NixOS/nixpkgs-channels.git) as a remote:
@@ -13,17 +12,17 @@ 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-17.09` for the latest
+custom changes on top of one of the channels, e.g. `nixos-18.03` for the latest
release and `nixos-unstable` for the latest successful build of master:
```
% git remote update channels
-% git rebase channels/nixos-17.09
+% git rebase channels/nixos-18.03
```
For pull-requests, please rebase onto nixpkgs `master`.
-[NixOS](https://nixos.org/nixos/) linux distribution source code is located inside
+[NixOS](https://nixos.org/nixos/) Linux distribution source code is located inside
`nixos/` folder.
* [NixOS installation instructions](https://nixos.org/nixos/manual/#ch-installation)
@@ -32,9 +31,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 17.09 release](https://hydra.nixos.org/jobset/nixos/release-17.09)
+* [Continuous package builds for 18.03 release](https://hydra.nixos.org/jobset/nixos/release-18.03)
* [Tests for unstable/master](https://hydra.nixos.org/job/nixos/trunk-combined/tested#tabs-constituents)
-* [Tests for 17.09 release](https://hydra.nixos.org/job/nixos/release-17.09/tested#tabs-constituents)
+* [Tests for 18.03 release](https://hydra.nixos.org/job/nixos/release-18.03/tested#tabs-constituents)
Communication:
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 000000000000..d0ba103fa9f1
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,6 @@
+*.chapter.xml
+*.section.xml
+.version
+out
+manual-full.xml
+highlightjs
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 000000000000..0ddae8631f3c
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,90 @@
+MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./*.md ./**/*.md)))
+
+.PHONY: all
+all: validate out/html/index.html out/epub/manual.epub
+
+.PHONY: debug
+debug:
+ nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"
+
+.PHONY: clean
+clean:
+ rm -f ${MD_TARGETS} .version manual-full.xml
+ rm -rf ./out/ ./highlightjs
+
+.PHONY: validate
+validate: manual-full.xml
+ jing "$$RNG" manual-full.xml
+
+out/html/index.html: manual-full.xml style.css highlightjs
+ mkdir -p out/html
+ xsltproc ${xsltFlags} \
+ --nonet --xinclude \
+ --output $@ \
+ "$$XSL/docbook/xhtml/docbook.xsl" \
+ ./manual-full.xml
+
+ mkdir -p out/html/highlightjs/
+ cp -r highlightjs out/html/
+
+ cp ./overrides.css out/html/
+ cp ./style.css out/html/style.css
+
+ mkdir -p out/html/images/callouts
+ cp "$$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 \
+ --output out/epub/scratch/ \
+ "$$XSL/docbook/epub/docbook.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/
+ 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:
+ 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/
+
+
+manual-full.xml: ${MD_TARGETS} .version *.xml
+ xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
+
+.version:
+ nix-instantiate --eval \
+ -E '(import ../lib).nixpkgsVersion' > .version
+
+%.section.xml: %.section.md
+ pandoc $^ -w docbook+smart \
+ -f markdown+smart \
+ | sed -e 's|||' \
+ -e 's|||' \
+ -e '1s| id=| xml:id=|' \
+ -e '1s|\(<[^ ]* \)|\1xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" |' \
+ | cat > $@
+
+%.chapter.xml: %.chapter.md
+ pandoc $^ -w docbook+smart \
+ --top-level-division=chapter \
+ -f markdown+smart \
+ | sed -e 's|||' \
+ -e 's|||' \
+ -e '1s| id=| xml:id=|' \
+ -e '1s|\(<[^ ]* \)|\1|' \
+ | cat > $@
diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml
index 765fc56c3bb3..d556c7ebe1ed 100644
--- a/doc/coding-conventions.xml
+++ b/doc/coding-conventions.xml
@@ -18,9 +18,9 @@
tab settings so it’s asking for trouble.
Use lowerCamelCase for variable
- names, not UpperCamelCase. TODO: naming of
- attributes in
- all-packages.nix?
+ names, not UpperCamelCase. Note, this rule does
+ not apply to package attribute names, which instead follow the rules
+ in .
Function calls with attribute set arguments are
written as
@@ -220,9 +220,10 @@ args.stdenv.mkDerivation (args // {
The variable name used for the instantiated package
in all-packages.nix, and when passing it as a
- dependency to other functions. This is what Nix expression authors
- see. It can also be used when installing using nix-env
- -iA.
+ dependency to other functions. Typically this is called the
+ package attribute name. This is what Nix
+ expression authors see. It can also be used when installing using
+ nix-env -iA.The filename for (the directory containing) the Nix
expression.
@@ -259,12 +260,12 @@ bound to the variable name e2fsprogs in
Also append "unstable" to the name - e.g.,
"pkgname-unstable-2014-09-23".
- Dashes in the package name should be preserved
- in new variable names, rather than converted to underscores
- (which was convention up to around 2013 and most names
- still have underscores instead of dashes) — e.g.,
- http-parser instead of
- http_parser.
+ Dashes in the package name should be preserved in
+ new variable names, rather than converted to underscores or camel
+ cased — e.g., http-parser instead of
+ http_parser or httpParser. The
+ hyphenated style is preferred in all three package
+ names.If there are multiple versions of a package, this
should be reflected in the variable names in
diff --git a/doc/configuration.xml b/doc/configuration.xml
index 55c5ea809d35..5370265c53ad 100644
--- a/doc/configuration.xml
+++ b/doc/configuration.xml
@@ -14,6 +14,8 @@ true:
its meta.broken set to
true.
+ The package isn't intended to run on the given system, as none of its meta.platforms match the given system.
+
The package's meta.license is set
to a license which is considered to be unfree.
@@ -88,6 +90,42 @@ distributing the software.
+
+ Installing packages on unsupported systems
+
+
+
+ There are also two ways to try compiling a package which has been marked as unsuported for the given system.
+
+
+
+
+ For allowing the build of a broken package once, you can use an environment variable for a single invocation of the nix tools:
+
+ $ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1
+
+
+
+
+ For permanently allowing broken packages to be built, you may add allowUnsupportedSystem = true; to your user's configuration file, like this:
+
+
+{
+ allowUnsupportedSystem = true;
+}
+
+
+
+
+
+
+ The difference between an a package being unsupported on some system and being broken is admittedly a bit fuzzy.
+ If a program ought to work on a certain platform, but doesn't, the platform should be included in meta.platforms, but marked as broken with e.g. meta.broken = !hostPlatform.isWindows.
+ Of course, this begs the question of what "ought" means exactly.
+ That is left to the package maintainer.
+
+
+
Installing unfree packages
@@ -397,7 +435,7 @@ fi
-
+
GNU info setup
diff --git a/doc/contributing.xml b/doc/contributing.xml
index a83059aa36e6..7aa0df271ff4 100644
--- a/doc/contributing.xml
+++ b/doc/contributing.xml
@@ -6,12 +6,27 @@
The DocBook sources of the Nixpkgs manual are in the doc
-subdirectory of the Nixpkgs repository. If you make modifications to
-the manual, it's important to build it before committing. You can do that as follows:
+subdirectory of the Nixpkgs repository.
+
+You can quickly check your edits with make:
-$ cd /path/to/nixpkgs
-$ nix-build doc
+ $ cd /path/to/nixpkgs/doc
+ $ nix-shell
+ [nix-shell]$ make
+
+
+If you experience problems, run make debug
+to help understand the docbook errors.
+
+After making modifications to the manual, it's important to
+build it before committing. You can do that as follows:
+
+
+ $ cd /path/to/nixpkgs/doc
+ $ nix-shell
+ [nix-shell]$ make clean
+ [nix-shell]$ nix-build .
If the build succeeds, the manual will be in
diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml
index 4b35b72feae0..10e4706b0590 100644
--- a/doc/cross-compilation.xml
+++ b/doc/cross-compilation.xml
@@ -61,7 +61,7 @@
The "target platform" attribute is, unlike the other two attributes, not actually fundamental to the process of building software.
- Instead, it is only relevant for compatability with building certain specific compilers and build tools.
+ Instead, it is only relevant for compatibility with building certain specific compilers and build tools.
It can be safely ignored for all other packages.
@@ -162,7 +162,7 @@
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 runnign on a single host platform.
+ The package dependency exists while both packages are running on a single host platform.
A build time dependency, however, implies a shift in platforms between the depending package and the depended-on package.
@@ -187,7 +187,7 @@
How does this work in practice? Nixpkgs is now structured so that build-time dependencies are taken from buildPackages, whereas run-time dependencies are taken from the top level attribute set.
For example, buildPackages.gcc should be used at build time, while gcc should be used at run time.
Now, for most of Nixpkgs's history, there was no buildPackages, and most packages have not been refactored to use it explicitly.
- Instead, one can use the four attributes used for specifying dependencies as documented in .
+ Instead, one can use the six (gasp) attributes used for specifying dependencies as documented in .
We "splice" together the run-time and build-time package sets with callPackage, and then mkDerivation 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 buildPackages needed.
@@ -200,6 +200,45 @@
+
+ Cross packagaing cookbook
+
+ Some frequently problems when packaging for cross compilation are good to just spell and answer.
+ Ideally the information above is exhaustive, so this section cannot provide any new information,
+ but its 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!
+
+
+
+
+ What if my package's build system needs to build a C program to be run under the build environment?
+
+
+ depsBuildBuild = [ buildPackages.stdenv.cc ];
+ Add it to your mkDerivation invocation.
+
+
+
+
+ My package fails to find ar.
+
+
+ Many packages assume that an unprefixed ar is available, but Nix doesn't provide one.
+ It only provides a prefixed one, just as it only does for all the other binutils programs.
+ It may be necessary to patch the package to fix the build system to use a prefixed `ar`.
+
+
+
+
+ My package's testsuite needs to run host platform code.
+
+
+ doCheck = stdenv.hostPlatform != stdenv.buildPlatfrom;
+ Add it to your mkDerivation invocation.
+
+
+
+
@@ -214,8 +253,19 @@
or also with crossSystem, in which case packages run on the latter, but all building happens on the former.
Both parameters take the same schema as the 3 (build, host, and target) platforms defined in the previous section.
As mentioned above, lib.systems.examples has some platforms which are used as arguments for these parameters in practice.
- You can use them programmatically, or on the command line like nix-build <nixpkgs> --arg crossSystem '(import <nixpkgs/lib>).systems.examples.fooBarBaz'.
+ You can use them programmatically, or on the command line:
+nix-build <nixpkgs> --arg crossSystem '(import <nixpkgs/lib>).systems.examples.fooBarBaz' -A whatever
+
+
+ Eventually we would like to make these platform examples an unnecessary convenience so that
+nix-build <nixpkgs> --arg crossSystem.config '<arch>-<os>-<vendor>-<abi>' -A whatever
+ works in the vast majority of cases.
+ The problem today is dependencies on other sorts of configuration which aren't given proper defaults.
+ We rely on the examples to crudely to set those configuration parameters in some vaguely sane manner on the users behalf.
+ Issue #34274 tracks this inconvenience along with its root cause in crufty configuration options.
+
+
While one is free to pass both parameters in full, there's a lot of logic to fill in missing fields.
As discussed in the previous section, only one of system, config, and parsed is needed to infer the other two.
diff --git a/doc/default.nix b/doc/default.nix
index cfd51fba257e..8abde58bb114 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -7,107 +7,41 @@ in
pkgs.stdenv.mkDerivation {
name = "nixpkgs-manual";
+ buildInputs = with pkgs; [ pandoc libxml2 libxslt zip jing ];
- buildInputs = with pkgs; [ pandoc libxml2 libxslt zip ];
+ src = ./.;
- xsltFlags = ''
- --param section.autolabel 1
- --param section.label.includes.component.label 1
- --param html.stylesheet 'style.css'
- --param xref.with.number.and.title 1
- --param toc.section.depth 3
- --param admon.style '''
- --param callout.graphics.extension '.gif'
+ # 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.docbook5_xsl}/xml/xsl";
+ RNG = "${pkgs.docbook5}/xml/rng/docbook/docbook.rng";
+ 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 = ''
+ echo ${lib.nixpkgsVersion} > .version
'';
+ installPhase = ''
+ dest="$out/share/doc/nixpkgs"
+ mkdir -p "$(dirname "$dest")"
+ mv out/html "$dest"
+ mv "$dest/index.html" "$dest/manual.html"
- buildCommand = let toDocbook = { useChapters ? false, inputFile, outputFile }:
- let
- extraHeader = ''xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" '';
- in ''
- {
- pandoc '${inputFile}' -w docbook ${lib.optionalString useChapters "--top-level-division=chapter"} \
- --smart \
- | sed -e 's|||' \
- -e 's|||' \
- -e '1s| id=| xml:id=|' \
- -e '1s|\(<[^ ]* \)|\1${extraHeader}|'
- } > '${outputFile}'
- '';
- in
+ mv out/epub/manual.epub "$dest/nixpkgs-manual.epub"
- ''
- ln -s '${sources}/'*.xml .
- mkdir ./languages-frameworks
- cp -s '${sources-langs}'/* ./languages-frameworks
- ''
- + toDocbook {
- inputFile = ./introduction.md;
- outputFile = "introduction.xml";
- useChapters = true;
- }
- + toDocbook {
- inputFile = ./languages-frameworks/python.md;
- outputFile = "./languages-frameworks/python.xml";
- }
- + toDocbook {
- inputFile = ./languages-frameworks/haskell.md;
- outputFile = "./languages-frameworks/haskell.xml";
- }
- + toDocbook {
- inputFile = ../pkgs/development/idris-modules/README.md;
- outputFile = "languages-frameworks/idris.xml";
- }
- + toDocbook {
- inputFile = ../pkgs/development/node-packages/README.md;
- outputFile = "languages-frameworks/node.xml";
- }
- + toDocbook {
- inputFile = ../pkgs/development/r-modules/README.md;
- outputFile = "languages-frameworks/r.xml";
- }
- + toDocbook {
- inputFile = ./languages-frameworks/rust.md;
- outputFile = "./languages-frameworks/rust.xml";
- }
- + toDocbook {
- inputFile = ./languages-frameworks/vim.md;
- outputFile = "./languages-frameworks/vim.xml";
- }
- + ''
- echo ${lib.nixpkgsVersion} > .version
-
- # validate against relaxng schema
- xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
- ${pkgs.jing}/bin/jing ${pkgs.docbook5}/xml/rng/docbook/docbook.rng manual-full.xml
-
- dst=$out/share/doc/nixpkgs
- mkdir -p $dst
- xsltproc $xsltFlags --nonet --xinclude \
- --output $dst/manual.html \
- ${pkgs.docbook5_xsl}/xml/xsl/docbook/xhtml/docbook.xsl \
- ./manual.xml
-
- cp ${./style.css} $dst/style.css
-
- mkdir -p $dst/images/callouts
- cp "${pkgs.docbook5_xsl}/xml/xsl/docbook/images/callouts/"*.gif $dst/images/callouts/
-
- mkdir -p $out/nix-support
- echo "doc manual $dst manual.html" >> $out/nix-support/hydra-build-products
-
- xsltproc $xsltFlags --nonet --xinclude \
- --output $dst/epub/ \
- ${pkgs.docbook5_xsl}/xml/xsl/docbook/epub/docbook.xsl \
- ./manual.xml
-
- cp -r $dst/images $dst/epub/OEBPS
- echo "application/epub+zip" > mimetype
- manual="$dst/nixpkgs-manual.epub"
- zip -0Xq "$manual" mimetype
- cd $dst/epub && zip -Xr9D "$manual" *
- rm -rf $dst/epub
+ mkdir -p $out/nix-support/
+ echo "doc manual $dest manual.html" >> $out/nix-support/hydra-build-products
'';
}
diff --git a/doc/functions.xml b/doc/functions.xml
index 52bdf13eba9b..f790512e7db1 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -221,16 +221,69 @@
All generators follow a similar call interface: generatorName
- configFunctions data, where configFunctions is a
- set of user-defined functions that format variable parts of the content.
+ configFunctions data, where configFunctions is
+ an attrset of user-defined functions that format nested parts of the
+ content.
They each have common defaults, so often they do not need to be set
manually. An example is mkSectionName ? (name: libStr.escape [ "[" "]"
- ] name) from the INI generator. It gets the name
- of a section and returns a sanitized name. The default
+ ] name) from the INI generator. It receives the
+ name of a section and sanitizes it. The default
mkSectionName escapes [ and
] with a backslash.
+
+ Generators can be fine-tuned to produce exactly the file format required
+ by your application/service. One example is an INI-file format which uses
+ : as separator, the strings
+ "yes"/"no" as boolean values
+ and requires all string values to be quoted:
+
+
+
+with lib;
+let
+ customToINI = generators.toINI {
+ # specifies how to format a key/value pair
+ mkKeyValue = generators.mkKeyValueDefault {
+ # specifies the generated string for a subset of nix values
+ mkValueString = v:
+ if v == true then ''"yes"''
+ else if v == false then ''"no"''
+ else if isString v then ''"${v}"''
+ # and delegats all other values to the default generator
+ else generators.mkValueStringDefault {} v;
+ } ":";
+ };
+
+# the INI file can now be given as plain old nix values
+in customToINI {
+ main = {
+ pushinfo = true;
+ autopush = false;
+ host = "localhost";
+ port = 42;
+ };
+ mergetool = {
+ merge = "diff3";
+ };
+}
+
+
+ This will produce the following INI file as nix string:
+
+
+[main]
+autopush:"no"
+host:"localhost"
+port:42
+pushinfo:"yes"
+str\:ange:"very::strange"
+
+[mergetool]
+merge:"diff3"
+
+
Nix store paths can be converted to strings by enclosing a
derivation attribute like so: "${drv}".
diff --git a/doc/introduction.md b/doc/introduction.chapter.md
similarity index 100%
rename from doc/introduction.md
rename to doc/introduction.chapter.md
diff --git a/doc/languages-frameworks/coq.xml b/doc/languages-frameworks/coq.xml
index d16c9f3dc87f..0ce1abd6194c 100644
--- a/doc/languages-frameworks/coq.xml
+++ b/doc/languages-frameworks/coq.xml
@@ -11,31 +11,53 @@
in the Coq derivation.
- Some libraries require OCaml and sometimes also Camlp5. The exact
- versions that were used to build Coq are saved in the
+ Some libraries require OCaml and sometimes also Camlp5 or findlib.
+ The exact versions that were used to build Coq are saved in the
coq.ocaml and coq.camlp5
- attributes.
+ and coq.findlib attributes.
+
+
+ Coq libraries may be compatible with some specific versions of Coq only.
+ The compatibleCoqVersions attribute is used to
+ precisely select those versions of Coq that are compatible with this
+ derivation.
Here is a simple package example. It is a pure Coq library, thus it
- only depends on Coq. Its makefile has been
- generated using coq_makefile so we only have to
+ depends on Coq. It builds on the Mathematical Components library, thus it
+ also takes mathcomp as buildInputs.
+ Its Makefile has been generated using
+ coq_makefile so we only have to
set the $COQLIB variable at install time.
-{stdenv, fetchurl, coq}:
-stdenv.mkDerivation {
- src = fetchurl {
- url = http://coq.inria.fr/pylons/contribs/files/Karatsuba/v8.4/Karatsuba.tar.gz;
- sha256 = "0ymfpv4v49k4fm63nq6gcl1hbnnxrvjjp7yzc4973n49b853c5b1";
+{ stdenv, fetchFromGitHub, coq, mathcomp }:
+
+stdenv.mkDerivation rec {
+ name = "coq${coq.coq-version}-multinomials-${version}";
+ version = "1.0";
+ src = fetchFromGitHub {
+ owner = "math-comp";
+ repo = "multinomials";
+ rev = version;
+ sha256 = "1qmbxp1h81cy3imh627pznmng0kvv37k4hrwi2faa101s6bcx55m";
};
- name = "coq-karatsuba";
-
buildInputs = [ coq ];
+ propagatedBuildInputs = [ mathcomp ];
installFlags = "COQLIB=$(out)/lib/coq/${coq.coq-version}/";
+
+ meta = {
+ description = "A Coq/SSReflect Library for Monoidal Rings and Multinomials";
+ inherit (src.meta) homepage;
+ license = stdenv.lib.licenses.cecill-b;
+ inherit (coq.meta) platforms;
+ };
+
+ passthru = {
+ compatibleCoqVersions = v: builtins.elem v [ "8.5" "8.6" "8.7" ];
+ };
}
-
diff --git a/doc/languages-frameworks/emscripten.section.md b/doc/languages-frameworks/emscripten.section.md
new file mode 100644
index 000000000000..24c49ec1409c
--- /dev/null
+++ b/doc/languages-frameworks/emscripten.section.md
@@ -0,0 +1,185 @@
+# User's Guide to Emscripten in Nixpkgs
+
+[Emscripten](https://github.com/kripken/emscripten): An LLVM-to-JavaScript Compiler
+
+This section of the manual covers how to use `emscripten` in nixpkgs.
+
+Minimal requirements:
+
+* nix
+* nixpkgs
+
+Modes of use of `emscripten`:
+
+* **Imperative usage** (on the command line):
+
+ If you want to work with `emcc`, `emconfigure` and `emmake` as you are used to from Ubuntu and similar distributions you can use these commands:
+
+ * `nix-env -i emscripten`
+ * `nix-shell -p emscripten`
+
+* **Declarative usage**:
+
+ This mode is far more power full since this makes use of `nix` for dependency management of emscripten libraries and targets by using the `mkDerivation` which is implemented by `pkgs.emscriptenStdenv` and `pkgs.buildEmscriptenPackage`. The source for the packages is in `pkgs/top-level/emscripten-packages.nix` and the abstraction behind it in `pkgs/development/em-modules/generic/default.nix`.
+ * build and install all packages:
+ * `nix-env -iA emscriptenPackages`
+
+ * dev-shell for zlib implementation hacking:
+ * `nix-shell -A emscriptenPackages.zlib`
+
+
+## Imperative usage
+
+A few things to note:
+
+* `export EMCC_DEBUG=2` is nice for debugging
+* `~/.emscripten`, the build artifact cache sometimes creates issues and needs to be removed from time to time
+
+
+## Declarative usage
+
+Let's see two different examples from `pkgs/top-level/emscripten-packages.nix`:
+
+* `pkgs.zlib.override`
+* `pkgs.buildEmscriptenPackage`
+
+Both are interesting concepts.
+
+A special requirement of the `pkgs.buildEmscriptenPackage` is the `doCheck = true` is a default meaning that each emscriptenPackage requires a `checkPhase` implemented.
+
+* Use `export EMCC_DEBUG=2` from within a emscriptenPackage's `phase` to get more detailed debug output what is going wrong.
+* ~/.emscripten cache is requiring us to set `HOME=$TMPDIR` in individual phases. This makes compilation slower but also makes it more deterministic.
+
+### Usage 1: pkgs.zlib.override
+
+This example uses `zlib` from nixpkgs but instead of compiling **C** to **ELF** it compiles **C** to **JS** since we were using `pkgs.zlib.override` and changed stdenv to `pkgs.emscriptenStdenv`. A few adaptions and hacks were set in place to make it working. One advantage is that when `pkgs.zlib` is updated, it will automatically update this package as well. However, this can also be the downside...
+
+See the `zlib` example:
+
+ zlib = (pkgs.zlib.override {
+ stdenv = pkgs.emscriptenStdenv;
+ }).overrideDerivation
+ (old: rec {
+ buildInputs = old.buildInputs ++ [ pkgconfig ];
+ # we need to reset this setting!
+ NIX_CFLAGS_COMPILE="";
+ configurePhase = ''
+ # FIXME: Some tests require writing at $HOME
+ HOME=$TMPDIR
+ runHook preConfigure
+
+ #export EMCC_DEBUG=2
+ emconfigure ./configure --prefix=$out --shared
+
+ runHook postConfigure
+ '';
+ dontStrip = true;
+ outputs = [ "out" ];
+ buildPhase = ''
+ emmake make
+ '';
+ installPhase = ''
+ emmake make install
+ '';
+ checkPhase = ''
+ echo "================= testing zlib using node ================="
+
+ echo "Compiling a custom test"
+ set -x
+ emcc -O2 -s EMULATE_FUNCTION_POINTER_CASTS=1 test/example.c -DZ_SOLO \
+ libz.so.${old.version} -I . -o example.js
+
+ echo "Using node to execute the test"
+ ${pkgs.nodejs}/bin/node ./example.js
+
+ set +x
+ if [ $? -ne 0 ]; then
+ echo "test failed for some reason"
+ exit 1;
+ else
+ echo "it seems to work! very good."
+ fi
+ echo "================= /testing zlib using node ================="
+ '';
+
+ postPatch = pkgs.stdenv.lib.optionalString pkgs.stdenv.isDarwin ''
+ substituteInPlace configure \
+ --replace '/usr/bin/libtool' 'ar' \
+ --replace 'AR="libtool"' 'AR="ar"' \
+ --replace 'ARFLAGS="-o"' 'ARFLAGS="-r"'
+ '';
+ });
+
+### Usage 2: pkgs.buildEmscriptenPackage
+
+This `xmlmirror` example features a emscriptenPackage which is defined completely from this context and no `pkgs.zlib.override` is used.
+
+ xmlmirror = pkgs.buildEmscriptenPackage rec {
+ name = "xmlmirror";
+
+ buildInputs = [ pkgconfig autoconf automake libtool gnumake libxml2 nodejs openjdk json_c ];
+ nativeBuildInputs = [ pkgconfig zlib ];
+
+ src = pkgs.fetchgit {
+ url = "https://gitlab.com/odfplugfest/xmlmirror.git";
+ rev = "4fd7e86f7c9526b8f4c1733e5c8b45175860a8fd";
+ sha256 = "1jasdqnbdnb83wbcnyrp32f36w3xwhwp0wq8lwwmhqagxrij1r4b";
+ };
+
+ configurePhase = ''
+ rm -f fastXmlLint.js*
+ # a fix for ERROR:root:For asm.js, TOTAL_MEMORY must be a multiple of 16MB, was 234217728
+ # https://gitlab.com/odfplugfest/xmlmirror/issues/8
+ sed -e "s/TOTAL_MEMORY=234217728/TOTAL_MEMORY=268435456/g" -i Makefile.emEnv
+ # https://github.com/kripken/emscripten/issues/6344
+ # https://gitlab.com/odfplugfest/xmlmirror/issues/9
+ sed -e "s/\$(JSONC_LDFLAGS) \$(ZLIB_LDFLAGS) \$(LIBXML20_LDFLAGS)/\$(JSONC_LDFLAGS) \$(LIBXML20_LDFLAGS) \$(ZLIB_LDFLAGS) /g" -i Makefile.emEnv
+ # https://gitlab.com/odfplugfest/xmlmirror/issues/11
+ sed -e "s/-o fastXmlLint.js/-s EXTRA_EXPORTED_RUNTIME_METHODS='[\"ccall\", \"cwrap\"]' -o fastXmlLint.js/g" -i Makefile.emEnv
+ '';
+
+ buildPhase = ''
+ HOME=$TMPDIR
+ make -f Makefile.emEnv
+ '';
+
+ outputs = [ "out" "doc" ];
+
+ installPhase = ''
+ mkdir -p $out/share
+ mkdir -p $doc/share/${name}
+
+ cp Demo* $out/share
+ cp -R codemirror-5.12 $out/share
+ cp fastXmlLint.js* $out/share
+ cp *.xsd $out/share
+ cp *.js $out/share
+ cp *.xhtml $out/share
+ cp *.html $out/share
+ cp *.json $out/share
+ cp *.rng $out/share
+ cp README.md $doc/share/${name}
+ '';
+ checkPhase = ''
+
+ '';
+ };
+
+### Declarative debugging
+
+Use `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz` and from there you can go trough the individual steps. This makes it easy to build a good `unit test` or list the files of the project.
+
+1. `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz`
+2. `cd /tmp/`
+3. `unpackPhase`
+4. cd libz-1.2.3
+5. `configurePhase`
+6. `buildPhase`
+7. ... happy hacking...
+
+## Summary
+
+Using this toolchain makes it easy to leverage `nix` from NixOS, MacOSX or even Windows (WSL+ubuntu+nix). This toolchain is reproducible, behaves like the rest of the packages from nixpkgs and contains a set of well working examples to learn and adapt from.
+
+If in trouble, ask the maintainers.
+
diff --git a/doc/languages-frameworks/haskell.md b/doc/languages-frameworks/haskell.md
deleted file mode 100644
index da3fd770ce72..000000000000
--- a/doc/languages-frameworks/haskell.md
+++ /dev/null
@@ -1,959 +0,0 @@
----
-title: User's Guide for Haskell in Nixpkgs
-author: Peter Simons
-date: 2015-06-01
----
-# User's Guide to the Haskell Infrastructure
-
-
-## How to install Haskell packages
-
-Nixpkgs distributes build instructions for all Haskell packages registered on
-[Hackage](http://hackage.haskell.org/), but strangely enough normal Nix package
-lookups don't seem to discover any of them, except for the default version of ghc, cabal-install, and stack:
-```
-$ nix-env -i alex
-error: selector ‘alex’ matches no derivations
-$ nix-env -qa ghc
-ghc-7.10.2
-```
-
-The Haskell package set is not registered in the top-level namespace because it
-is *huge*. If all Haskell packages were visible to these commands, then
-name-based search/install operations would be much slower than they are now. We
-avoided that by keeping all Haskell-related packages in a separate attribute
-set called `haskellPackages`, which the following command will list:
-```
-$ nix-env -f "" -qaP -A haskellPackages
-haskellPackages.a50 a50-0.5
-haskellPackages.abacate haskell-abacate-0.0.0.0
-haskellPackages.abcBridge haskell-abcBridge-0.12
-haskellPackages.afv afv-0.1.1
-haskellPackages.alex alex-3.1.4
-haskellPackages.Allure Allure-0.4.101.1
-haskellPackages.alms alms-0.6.7
-[... some 8000 entries omitted ...]
-```
-
-To install any of those packages into your profile, refer to them by their
-attribute path (first column):
-```shell
-nix-env -f "" -iA haskellPackages.Allure ...
-```
-
-The attribute path of any Haskell packages corresponds to the name of that
-particular package on Hackage: the package `cabal-install` has the attribute
-`haskellPackages.cabal-install`, and so on. (Actually, this convention causes
-trouble with packages like `3dmodels` and `4Blocks`, because these names are
-invalid identifiers in the Nix language. The issue of how to deal with these
-rare corner cases is currently unresolved.)
-
-Haskell packages who's Nix name (second column) begins with a `haskell-` prefix
-are packages that provide a library whereas packages without that prefix
-provide just executables. Libraries may provide executables too, though: the
-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].
-
-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
-`nix-env` an explicit `-f ""` parameter, but if you call `nix-env`
-without that flag, then chances are the invocation fails:
-```
-$ nix-env -iA haskellPackages.cabal-install
-error: attribute ‘haskellPackages’ in selection path
- ‘haskellPackages.cabal-install’ not found
-```
-
-On NixOS, for example, Nixpkgs does *not* exist in the top-level namespace by
-default. To figure out the proper attribute path, it's easiest to query for the
-path of a well-known Nixpkgs package, i.e.:
-```
-$ nix-env -qaP coreutils
-nixos.coreutils coreutils-8.23
-```
-
-If your system responds like that (most NixOS installations will), then the
-attribute path to `haskellPackages` is `nixos.haskellPackages`. Thus, if you
-want to use `nix-env` without giving an explicit `-f` flag, then that's the way
-to do it:
-```shell
-nix-env -qaP -A nixos.haskellPackages
-nix-env -iA nixos.haskellPackages.cabal-install
-```
-
-Our current default compiler is GHC 7.10.x and the `haskellPackages` set
-contains packages built with that particular version. Nixpkgs contains the
-latest major release of every GHC since 6.10.4, however, and there is a whole
-family of package sets available that defines Hackage packages built with each
-of those compilers, too:
-```shell
-nix-env -f "" -qaP -A haskell.packages.ghc6123
-nix-env -f "" -qaP -A haskell.packages.ghc763
-```
-
-The name `haskellPackages` is really just a synonym for
-`haskell.packages.ghc7102`, because we prefer that package set internally and
-recommend it to our users as their default choice, but ultimately you are free
-to compile your Haskell packages with any GHC version you please. The following
-command displays the complete list of available compilers:
-```
-$ nix-env -f "" -qaP -A haskell.compiler
-haskell.compiler.ghc6104 ghc-6.10.4
-haskell.compiler.ghc6123 ghc-6.12.3
-haskell.compiler.ghc704 ghc-7.0.4
-haskell.compiler.ghc722 ghc-7.2.2
-haskell.compiler.ghc742 ghc-7.4.2
-haskell.compiler.ghc763 ghc-7.6.3
-haskell.compiler.ghc784 ghc-7.8.4
-haskell.compiler.ghc7102 ghc-7.10.2
-haskell.compiler.ghcHEAD ghc-7.11.20150402
-haskell.compiler.ghcNokinds ghc-nokinds-7.11.20150704
-haskell.compiler.ghcjs ghcjs-0.1.0
-haskell.compiler.jhc jhc-0.8.2
-haskell.compiler.uhc uhc-1.1.9.0
-```
-
-We have no package sets for `jhc` or `uhc` yet, unfortunately, but for every
-version of GHC listed above, there exists a package set based on that compiler.
-Also, the attributes `haskell.compiler.ghcXYC` and
-`haskell.packages.ghcXYC.ghc` are synonymous for the sake of convenience.
-
-## How to create a development environment
-
-### How to install a compiler
-
-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
-user profile:
-```shell
-nix-env -f "" -iA haskellPackages.ghc haskellPackages.cabal-install
-```
-
-Instead of the default package set `haskellPackages`, you can also use the more
-precise name `haskell.compiler.ghc7102`, which has the advantage that it refers
-to the same GHC version regardless of what Nixpkgs considers "default" at any
-given time.
-
-Once you've made those tools available in `$PATH`, it's possible to build
-Hackage packages the same way people without access to Nix do it all the time:
-```shell
-cabal get lens-4.11 && cd lens-4.11
-cabal install -j --dependencies-only
-cabal configure
-cabal build
-```
-
-If you enjoy working with Cabal sandboxes, then that's entirely possible too:
-just execute the command
-```shell
-cabal sandbox init
-```
-before installing the required dependencies.
-
-The `nix-shell` utility makes it easy to switch to a different compiler
-version; just enter the Nix shell environment with the command
-```shell
-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].
-
-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
-a project that doesn't depend on any additional system libraries outside of GHC,
-then it's even sufficient to just run the `cabal configure` command inside of
-the shell:
-```shell
-nix-shell -p haskell.compiler.ghc784 --command "cabal configure"
-```
-
-Afterwards, all other commands like `cabal build` work just fine in any shell
-environment, because the configure phase recorded the absolute paths to all
-required tools like GHC in its build configuration inside of the `dist/`
-directory. Please note, however, that `nix-collect-garbage` can break such an
-environment because the Nix store paths created by `nix-shell` aren't "alive"
-anymore once `nix-shell` has terminated. If you find that your Haskell builds
-no longer work after garbage collection, then you'll have to re-run `cabal
-configure` inside of a new `nix-shell` environment.
-
-### How to install a compiler with libraries
-
-GHC expects to find all installed libraries inside of its own `lib` directory.
-This approach works fine on traditional Unix systems, but it doesn't work for
-Nix, because GHC's store path is immutable once it's built. We cannot install
-additional libraries into that location. As a consequence, our copies of GHC
-don't know any packages except their own core libraries, like `base`,
-`containers`, `Cabal`, etc.
-
-We can register additional libraries to GHC, however, using a special build
-function called `ghcWithPackages`. That function expects one argument: a
-function that maps from an attribute set of Haskell packages to a list of
-packages, which determines the libraries known to that particular version of
-GHC. For example, the Nix expression `ghcWithPackages (pkgs: [pkgs.mtl])`
-generates a copy of GHC that has the `mtl` library registered in addition to
-its normal core packages:
-```
-$ nix-shell -p "haskellPackages.ghcWithPackages (pkgs: [pkgs.mtl])"
-
-[nix-shell:~]$ ghc-pkg list mtl
-/nix/store/zy79...-ghc-7.10.2/lib/ghc-7.10.2/package.conf.d:
- mtl-2.2.1
-```
-
-This function allows users to define their own development environment by means
-of an override. After adding the following snippet to `~/.config/nixpkgs/config.nix`,
-```nix
-{
- packageOverrides = super: let self = super.pkgs; in
- {
- myHaskellEnv = self.haskell.packages.ghc7102.ghcWithPackages
- (haskellPackages: with haskellPackages; [
- # libraries
- arrows async cgi criterion
- # tools
- cabal-install haskintex
- ]);
- };
-}
-```
-it's possible to install that compiler with `nix-env -f "" -iA
-myHaskellEnv`. If you'd like to switch that development environment to a
-different version of GHC, just replace the `ghc7102` bit in the previous
-definition with the appropriate name. Of course, it's also possible to define
-any number of these development environments! (You can't install two of them
-into the same profile at the same time, though, because that would result in
-file conflicts.)
-
-The generated `ghc` program is a wrapper script that re-directs the real
-GHC executable to use a new `lib` directory --- one that we specifically
-constructed to contain all those packages the user requested:
-```
-$ cat $(type -p ghc)
-#! /nix/store/xlxj...-bash-4.3-p33/bin/bash -e
-export NIX_GHC=/nix/store/19sm...-ghc-7.10.2/bin/ghc
-export NIX_GHCPKG=/nix/store/19sm...-ghc-7.10.2/bin/ghc-pkg
-export NIX_GHC_DOCDIR=/nix/store/19sm...-ghc-7.10.2/share/doc/ghc/html
-export NIX_GHC_LIBDIR=/nix/store/19sm...-ghc-7.10.2/lib/ghc-7.10.2
-exec /nix/store/j50p...-ghc-7.10.2/bin/ghc "-B$NIX_GHC_LIBDIR" "$@"
-```
-
-The variables `$NIX_GHC`, `$NIX_GHCPKG`, etc. point to the *new* store path
-`ghcWithPackages` constructed specifically for this environment. The last line
-of the wrapper script then executes the real `ghc`, but passes the path to the
-new `lib` directory using GHC's `-B` flag.
-
-The purpose of those environment variables is to work around an impurity in the
-popular [ghc-paths](http://hackage.haskell.org/package/ghc-paths) library. That
-library promises to give its users access to GHC's installation paths. Only,
-the library can't possible know that path when it's compiled, because the path
-GHC considers its own is determined only much later, when the user configures
-it through `ghcWithPackages`. So we [patched
-ghc-paths](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/patches/ghc-paths-nix.patch)
-to return the paths found in those environment variables at run-time rather
-than trying to guess them at compile-time.
-
-To make sure that mechanism works properly all the time, we recommend that you
-set those variables to meaningful values in your shell environment, too, i.e.
-by adding the following code to your `~/.bashrc`:
-```bash
-if type >/dev/null 2>&1 -p ghc; then
- eval "$(egrep ^export "$(type -p ghc)")"
-fi
-```
-
-If you are certain that you'll use only one GHC environment which is located in
-your user profile, then you can use the following code, too, which has the
-advantage that it doesn't contain any paths from the Nix store, i.e. those
-settings always remain valid even if a `nix-env -u` operation updates the GHC
-environment in your profile:
-```bash
-if [ -e ~/.nix-profile/bin/ghc ]; then
- export NIX_GHC="$HOME/.nix-profile/bin/ghc"
- export NIX_GHCPKG="$HOME/.nix-profile/bin/ghc-pkg"
- export NIX_GHC_DOCDIR="$HOME/.nix-profile/share/doc/ghc/html"
- export NIX_GHC_LIBDIR="$HOME/.nix-profile/lib/ghc-$($NIX_GHC --numeric-version)"
-fi
-```
-
-### How to install a compiler with libraries, hoogle and documentation indexes
-
-If you plan to use your environment for interactive programming, not just
-compiling random Haskell code, you might want to replace `ghcWithPackages` in
-all the listings above with `ghcWithHoogle`.
-
-This environment generator not only produces an environment with GHC and all
-the specified libraries, but also generates a `hoogle` and `haddock` indexes
-for all the packages, and provides a wrapper script around `hoogle` binary that
-uses all those things. A precise name for this thing would be
-"`ghcWithPackagesAndHoogleAndDocumentationIndexes`", which is, regrettably, too
-long and scary.
-
-For example, installing the following environment
-```nix
-{
- packageOverrides = super: let self = super.pkgs; in
- {
- myHaskellEnv = self.haskellPackages.ghcWithHoogle
- (haskellPackages: with haskellPackages; [
- # libraries
- arrows async cgi criterion
- # tools
- cabal-install haskintex
- ]);
- };
-}
-```
-allows one to browse module documentation index [not too dissimilar to
-this](https://downloads.haskell.org/~ghc/latest/docs/html/libraries/index.html)
-for all the specified packages and their dependencies by directing a browser of
-choice to `~/.nix-profiles/share/doc/hoogle/index.html` (or
-`/run/current-system/sw/share/doc/hoogle/index.html` in case you put it in
-`environment.systemPackages` in NixOS).
-
-After you've marveled enough at that try adding the following to your
-`~/.ghc/ghci.conf`
-```
-:def hoogle \s -> return $ ":! hoogle search -cl --count=15 \"" ++ s ++ "\""
-:def doc \s -> return $ ":! hoogle search -cl --info \"" ++ s ++ "\""
-```
-and test it by typing into `ghci`:
-```
-:hoogle a -> a
-:doc a -> a
-```
-
-Be sure to note the links to `haddock` files in the output. With any modern and
-properly configured terminal emulator you can just click those links to
-navigate there.
-
-Finally, you can run
-```shell
-hoogle server -p 8080
-```
-and navigate to http://localhost:8080/ for your own local
-[Hoogle](https://www.haskell.org/hoogle/). Note, however, that Firefox and
-possibly other browsers disallow navigation from `http:` to `file:` URIs for
-security reasons, which might be quite an inconvenience. See [this
-page](http://kb.mozillazine.org/Links_to_local_pages_do_not_work) for
-workarounds.
-
-### How to build a Haskell project using Stack
-
-[Stack](http://haskellstack.org) is a popular build tool for Haskell projects.
-It has first-class support for Nix. Stack can optionally use Nix to
-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
-cd wai
-stack --nix build
-```
-
-If you want `stack` to use Nix by default, you can add a `nix` section to the
-`stack.yaml` file, as explained in the [Stack documentation][stack-nix-doc]. For
-example:
-```yaml
-nix:
- enable: true
- packages: [pkgconfig zeromq zlib]
-```
-
-The example configuration snippet above tells Stack to create an ad hoc
-environment for `nix-shell` as in the below section, in which the `pkgconfig`,
-`zeromq` and `zlib` packages from Nixpkgs are available. All `stack` commands
-will implicitly be executed inside this ad hoc environment.
-
-Some projects have more sophisticated needs. For examples, some ad hoc
-environments might need to expose Nixpkgs packages compiled in a certain way, or
-with extra environment variables. In these cases, you'll need a `shell` field
-instead of `packages`:
-```yaml
-nix:
- enable: true
- shell-file: shell.nix
-```
-
-For more on how to write a `shell.nix` file see the below section. You'll need
-to express a derivation. Note that Nixpkgs ships with a convenience wrapper
-function around `mkDerivation` called `haskell.lib.buildStackProject` to help you
-create this derivation in exactly the way Stack expects. All of the same inputs
-as `mkDerivation` can be provided. For example, to build a Stack project that
-including packages that link against a version of the R library compiled with
-special options turned on:
-```nix
-with (import { });
-
-let R = pkgs.R.override { enableStrictBarrier = true; };
-in
-haskell.lib.buildStackProject {
- name = "HaskellR";
- buildInputs = [ R zeromq zlib ];
-}
-```
-
-You can select a particular GHC version to compile with by setting the
-`ghc` attribute as an argument to `buildStackProject`. Better yet, let
-Stack choose what GHC version it wants based on the snapshot specified
-in `stack.yaml` (only works with Stack >= 1.1.3):
-```nix
-{nixpkgs ? import { }, ghc ? nixpkgs.ghc}:
-
-with nixpkgs;
-
-let R = pkgs.R.override { enableStrictBarrier = true; };
-in
-haskell.lib.buildStackProject {
- name = "HaskellR";
- buildInputs = [ R zeromq zlib ];
- inherit ghc;
-}
-```
-
-[stack-nix-doc]: http://docs.haskellstack.org/en/stable/nix_integration.html
-
-### How to create ad hoc environments for `nix-shell`
-
-The easiest way to create an ad hoc development environment is to run
-`nix-shell` with the appropriate GHC environment given on the command-line:
-```shell
-nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [mtl pandoc])"
-```
-
-For more sophisticated use-cases, however, it's more convenient to save the
-desired configuration in a file called `shell.nix` that looks like this:
-```nix
-{ nixpkgs ? import {}, compiler ? "ghc7102" }:
-let
- inherit (nixpkgs) pkgs;
- ghc = pkgs.haskell.packages.${compiler}.ghcWithPackages (ps: with ps; [
- monad-par mtl
- ]);
-in
-pkgs.stdenv.mkDerivation {
- name = "my-haskell-env-0";
- buildInputs = [ ghc ];
- shellHook = "eval $(egrep ^export ${ghc}/bin/ghc)";
-}
-```
-
-Now run `nix-shell` --- or even `nix-shell --pure` --- to enter a shell
-environment that has the appropriate compiler in `$PATH`. If you use `--pure`,
-then add all other packages that your development environment needs into the
-`buildInputs` attribute. If you'd like to switch to a different compiler
-version, then pass an appropriate `compiler` argument to the expression, i.e.
-`nix-shell --argstr compiler ghc784`.
-
-If you need such an environment because you'd like to compile a Hackage package
-outside of Nix --- i.e. because you're hacking on the latest version from Git
----, then the package set provides suitable nix-shell environments for you
-already! Every Haskell package has an `env` attribute that provides a shell
-environment suitable for compiling that particular package. If you'd like to
-hack the `lens` library, for example, then you just have to check out the
-source code and enter the appropriate environment:
-```
-$ cabal get lens-4.11 && cd lens-4.11
-Downloading lens-4.11...
-Unpacking to lens-4.11/
-
-$ nix-shell "" -A haskellPackages.lens.env
-[nix-shell:/tmp/lens-4.11]$
-```
-
-At point, you can run `cabal configure`, `cabal build`, and all the other
-development commands. Note that you need `cabal-install` installed in your
-`$PATH` already to use it here --- the `nix-shell` environment does not provide
-it.
-
-## How to create Nix builds for your own private Haskell packages
-
-If your own Haskell packages have build instructions for Cabal, then you can
-convert those automatically into build instructions for Nix using the
-`cabal2nix` utility, which you can install into your profile by running
-`nix-env -i cabal2nix`.
-
-### How to build a stand-alone project
-
-For example, let's assume that you're working on a private project called
-`foo`. To generate a Nix build expression for it, change into the project's
-top-level directory and run the command:
-```shell
-cabal2nix . > foo.nix
-```
-Then write the following snippet into a file called `default.nix`:
-```nix
-{ nixpkgs ? import {}, compiler ? "ghc7102" }:
-nixpkgs.pkgs.haskell.packages.${compiler}.callPackage ./foo.nix { }
-```
-
-Finally, store the following code in a file called `shell.nix`:
-```nix
-{ nixpkgs ? import {}, compiler ? "ghc7102" }:
-(import ./default.nix { inherit nixpkgs compiler; }).env
-```
-
-At this point, you can run `nix-build` to have Nix compile your project and
-install it into a Nix store path. The local directory will contain a symlink
-called `result` after `nix-build` returns that points into that location. Of
-course, passing the flag `--argstr compiler ghc763` allows switching the build
-to any version of GHC currently supported.
-
-Furthermore, you can call `nix-shell` to enter an interactive development
-environment in which you can use `cabal configure` and `cabal build` to develop
-your code. That environment will automatically contain a proper GHC derivation
-with all the required libraries registered as well as all the system-level
-libraries your package might need.
-
-If your package does not depend on any system-level libraries, then it's
-sufficient to run
-```shell
-nix-shell --command "cabal configure"
-```
-once to set up your build. `cabal-install` determines the absolute paths to all
-resources required for the build and writes them into a config file in the
-`dist/` directory. Once that's done, you can run `cabal build` and any other
-command for that project even outside of the `nix-shell` environment. This
-feature is particularly nice for those of us who like to edit their code with
-an IDE, like Emacs' `haskell-mode`, because it's not necessary to start Emacs
-inside of nix-shell just to make it find out the necessary settings for
-building the project; `cabal-install` has already done that for us.
-
-If you want to do some quick-and-dirty hacking and don't want to bother setting
-up a `default.nix` and `shell.nix` file manually, then you can use the
-`--shell` flag offered by `cabal2nix` to have it generate a stand-alone
-`nix-shell` environment for you. With that feature, running
-```shell
-cabal2nix --shell . > shell.nix
-nix-shell --command "cabal configure"
-```
-is usually enough to set up a build environment for any given Haskell package.
-You can even use that generated file to run `nix-build`, too:
-```shell
-nix-build shell.nix
-```
-
-### How to build projects that depend on each other
-
-If you have multiple private Haskell packages that depend on each other, then
-you'll have to register those packages in the Nixpkgs set to make them visible
-for the dependency resolution performed by `callPackage`. First of all, change
-into each of your projects top-level directories and generate a `default.nix`
-file with `cabal2nix`:
-```shell
-cd ~/src/foo && cabal2nix . > default.nix
-cd ~/src/bar && cabal2nix . > default.nix
-```
-Then edit your `~/.config/nixpkgs/config.nix` file to register those builds in the
-default Haskell package set:
-```nix
-{
- packageOverrides = super: let self = super.pkgs; in
- {
- haskellPackages = super.haskellPackages.override {
- overrides = self: super: {
- foo = self.callPackage ../src/foo {};
- bar = self.callPackage ../src/bar {};
- };
- };
- };
-}
-```
-Once that's accomplished, `nix-env -f "" -qA haskellPackages` will
-show your packages like any other package from Hackage, and you can build them
-```shell
-nix-build "" -A haskellPackages.foo
-```
-or enter an interactive shell environment suitable for building them:
-```shell
-nix-shell "" -A haskellPackages.bar.env
-```
-
-## Miscellaneous Topics
-
-### How to build with profiling enabled
-
-Every Haskell package set takes a function called `overrides` that you can use
-to manipulate the package as much as you please. One useful application of this
-feature is to replace the default `mkDerivation` function with one that enables
-library profiling for all packages. To accomplish that, add configure the
-following snippet in your `~/.config/nixpkgs/config.nix` file:
-```nix
-{
- packageOverrides = super: let self = super.pkgs; in
- {
- profiledHaskellPackages = self.haskellPackages.override {
- overrides = self: super: {
- mkDerivation = args: super.mkDerivation (args // {
- enableLibraryProfiling = true;
- });
- };
- };
- };
-}
-```
-Then, replace instances of `haskellPackages` in the `cabal2nix`-generated
-`default.nix` or `shell.nix` files with `profiledHaskellPackages`.
-
-### How to override package versions in a compiler-specific package set
-
-Nixpkgs provides the latest version of
-[`ghc-events`](http://hackage.haskell.org/package/ghc-events), which is 0.4.4.0
-at the time of this writing. This is fine for users of GHC 7.10.x, but GHC
-7.8.4 cannot compile that binary. Now, one way to solve that problem is to
-register an older version of `ghc-events` in the 7.8.x-specific package set.
-The first step is to generate Nix build instructions with `cabal2nix`:
-```shell
-cabal2nix cabal://ghc-events-0.4.3.0 > ~/.nixpkgs/ghc-events-0.4.3.0.nix
-```
-Then add the override in `~/.config/nixpkgs/config.nix`:
-```nix
-{
- packageOverrides = super: let self = super.pkgs; in
- {
- haskell = super.haskell // {
- packages = super.haskell.packages // {
- ghc784 = super.haskell.packages.ghc784.override {
- overrides = self: super: {
- ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
- };
- };
- };
- };
- };
-}
-```
-
-This code is a little crazy, no doubt, but it's necessary because the intuitive
-version
-```nix
-{ # ...
-
- haskell.packages.ghc784 = super.haskell.packages.ghc784.override {
- overrides = self: super: {
- ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
- };
- };
-}
-```
-doesn't do what we want it to: that code replaces the `haskell` package set in
-Nixpkgs with one that contains only one entry,`packages`, which contains only
-one entry `ghc784`. This override loses the `haskell.compiler` set, and it
-loses the `haskell.packages.ghcXYZ` sets for all compilers but GHC 7.8.4. To
-avoid that problem, we have to perform the convoluted little dance from above,
-iterating over each step in hierarchy.
-
-Once it's accomplished, however, we can install a variant of `ghc-events`
-that's compiled with GHC 7.8.4:
-```shell
-nix-env -f "" -iA haskell.packages.ghc784.ghc-events
-```
-Unfortunately, it turns out that this build fails again while executing the
-test suite! Apparently, the release archive on Hackage is missing some data
-files that the test suite requires, so we cannot run it. We accomplish that by
-re-generating the Nix expression with the `--no-check` flag:
-```shell
-cabal2nix --no-check cabal://ghc-events-0.4.3.0 > ~/.nixpkgs/ghc-events-0.4.3.0.nix
-```
-Now the builds succeeds.
-
-Of course, in the concrete example of `ghc-events` this whole exercise is not
-an ideal solution, because `ghc-events` can analyze the output emitted by any
-version of GHC later than 6.12 regardless of the compiler version that was used
-to build the `ghc-events` executable, so strictly speaking there's no reason to
-prefer one built with GHC 7.8.x in the first place. However, for users who
-cannot use GHC 7.10.x at all for some reason, the approach of downgrading to an
-older version might be useful.
-
-### How to recover from GHC's infamous non-deterministic library ID bug
-
-GHC and distributed build farms don't get along well:
-
- - https://ghc.haskell.org/trac/ghc/ticket/4012
-
-When you see an error like this one
-```
-package foo-0.7.1.0 is broken due to missing package
-text-1.2.0.4-98506efb1b9ada233bb5c2b2db516d91
-```
-then you have to download and re-install `foo` and all its dependents from
-scratch:
-```shell
-nix-store -q --referrers /nix/store/*-haskell-text-1.2.0.4 \
- | xargs -L 1 nix-store --repair-path
-```
-
-If you're using additional Hydra servers other than `hydra.nixos.org`, then it
-might be necessary to purge the local caches that store data from those
-machines to disable these binary channels for the duration of the previous
-command, i.e. by running:
-```shell
-rm /nix/var/nix/binary-cache-v3.sqlite
-rm /nix/var/nix/manifests/*
-rm /nix/var/nix/channel-cache/*
-```
-
-### Builds on Darwin fail with `math.h` not found
-
-Users of GHC on Darwin have occasionally reported that builds fail, because the
-compiler complains about a missing include file:
-```
-fatal error: 'math.h' file not found
-```
-The issue has been discussed at length in [ticket
-6390](https://github.com/NixOS/nixpkgs/issues/6390), and so far no good
-solution has been proposed. As a work-around, users who run into this problem
-can configure the environment variables
-```shell
-export NIX_CFLAGS_COMPILE="-idirafter /usr/include"
-export NIX_CFLAGS_LINK="-L/usr/lib"
-```
-in their `~/.bashrc` file to avoid the compiler error.
-
-### Builds using Stack complain about missing system libraries
-
-```
--- While building package zlib-0.5.4.2 using:
- runhaskell -package=Cabal-1.22.4.0 -clear-package-db [... lots of flags ...]
-Process exited with code: ExitFailure 1
-Logs have been written to: /home/foo/src/stack-ide/.stack-work/logs/zlib-0.5.4.2.log
-
-Configuring zlib-0.5.4.2...
-Setup.hs: Missing dependency on a foreign library:
-* Missing (or bad) header file: zlib.h
-This problem can usually be solved by installing the system package that
-provides this library (you may need the "-dev" version). If the library is
-already installed but in a non-standard location then you can use the flags
---extra-include-dirs= and --extra-lib-dirs= to specify where it is.
-If the header file does exist, it may contain errors that are caught by the C
-compiler at the preprocessing stage. In this case you can re-run configure
-with the verbosity flag -v3 to see the error messages.
-```
-
-When you run the build inside of the nix-shell environment, the system
-is configured to find `libz.so` without any special flags -- the compiler
-and linker "just know" how to find it. Consequently, Cabal won't record
-any search paths for `libz.so` in the package description, which means
-that the package works fine inside of nix-shell, but once you leave the
-shell the shared object can no longer be found. That issue is by no
-means specific to Stack: you'll have that problem with any other
-Haskell package that's built inside of nix-shell but run outside of that
-environment.
-
-You can remedy this issue in several ways. The easiest is to add a `nix` section
-to the `stack.yaml` like the following:
-```yaml
-nix:
- enable: true
- packages: [ zlib ]
-```
-
-Stack's Nix support knows to add `${zlib.out}/lib` and `${zlib.dev}/include`
-as an `--extra-lib-dirs` and `extra-include-dirs`, respectively.
-Alternatively, you can achieve the same effect by hand. First of all, run
-```
-$ nix-build --no-out-link "" -A zlib
-/nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8
-```
-to find out the store path of the system's zlib library. Now, you can
-
- 1. add that path (plus a "/lib" suffix) to your `$LD_LIBRARY_PATH`
- environment variable to make sure your system linker finds `libz.so`
- automatically. It's no pretty solution, but it will work.
-
- 2. As a variant of (1), you can also install any number of system
- libraries into your user's profile (or some other profile) and point
- `$LD_LIBRARY_PATH` to that profile instead, so that you don't have to
- list dozens of those store paths all over the place.
-
- 3. The solution I prefer is to call stack with an appropriate
- --extra-lib-dirs flag like so:
- ```shell
- stack --extra-lib-dirs=/nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8/lib build
- ```
-
- Typically, you'll need `--extra-include-dirs` as well. It's possible
- to add those flag to the project's `stack.yaml` or your user's
- global `~/.stack/global/stack.yaml` file so that you don't have to
- specify them manually every time. But again, you're likely better off
- using Stack's Nix support instead.
-
- The same thing applies to `cabal configure`, of course, if you're
- building with `cabal-install` instead of Stack.
-
-### Creating statically linked binaries
-
-There are two levels of static linking. The first option is to configure the
-build with the Cabal flag `--disable-executable-dynamic`. In Nix expressions,
-this can be achieved by setting the attribute:
-```
-enableSharedExecutables = false;
-```
-That gives you a binary with statically linked Haskell libraries and
-dynamically linked system libraries.
-
-To link both Haskell libraries and system libraries statically, the additional
-flags `--ghc-option=-optl=-static --ghc-option=-optl=-pthread` need to be used.
-In Nix, this is accomplished with:
-```
-configureFlags = [ "--ghc-option=-optl=-static" "--ghc-option=-optl=-pthread" ];
-```
-
-It's important to realize, however, that most system libraries in Nix are
-built as shared libraries only, i.e. there is just no static library
-available that Cabal could link!
-
-### Building GHC with integer-simple
-
-By default GHC implements the Integer type using the
-[GNU Multiple Precision Arithmetic (GMP) library](https://gmplib.org/).
-The implementation can be found in the
-[integer-gmp](http://hackage.haskell.org/package/integer-gmp) package.
-
-A potential problem with this is that GMP is licensed under the
-[GNU Lesser General Public License (LGPL)](http://www.gnu.org/copyleft/lesser.html),
-a kind of "copyleft" license. According to the terms of the LGPL, paragraph 5,
-you may distribute a program that is designed to be compiled and dynamically
-linked with the library under the terms of your choice (i.e., commercially) but
-if your program incorporates portions of the library, if it is linked
-statically, then your program is a "derivative"--a "work based on the
-library"--and according to paragraph 2, section c, you "must cause the whole of
-the work to be licensed" under the terms of the LGPL (including for free).
-
-The LGPL licensing for GMP is a problem for the overall licensing of binary
-programs compiled with GHC because most distributions (and builds) of GHC use
-static libraries. (Dynamic libraries are currently distributed only for macOS.)
-The LGPL licensing situation may be worse: even though
-[The Glasgow Haskell Compiler License](https://www.haskell.org/ghc/license)
-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
-[integer-simple](http://hackage.haskell.org/package/integer-simple).
-
-To get a GHC compiler build with `integer-simple` instead of `integer-gmp` use
-the attribute: `haskell.compiler.integer-simple."${ghcVersion}"`.
-For example:
-```
-$ nix-build -E '(import {}).haskell.compiler.integer-simple.ghc802'
-...
-$ result/bin/ghc-pkg list | grep integer
- integer-simple-0.1.1.1
-```
-The following command displays the complete list of GHC compilers build with `integer-simple`:
-```
-$ nix-env -f "" -qaP -A haskell.compiler.integer-simple
-haskell.compiler.integer-simple.ghc7102 ghc-7.10.2
-haskell.compiler.integer-simple.ghc7103 ghc-7.10.3
-haskell.compiler.integer-simple.ghc722 ghc-7.2.2
-haskell.compiler.integer-simple.ghc742 ghc-7.4.2
-haskell.compiler.integer-simple.ghc783 ghc-7.8.3
-haskell.compiler.integer-simple.ghc784 ghc-7.8.4
-haskell.compiler.integer-simple.ghc801 ghc-8.0.1
-haskell.compiler.integer-simple.ghc802 ghc-8.0.2
-haskell.compiler.integer-simple.ghcHEAD ghc-8.1.20170106
-```
-
-To get a package set supporting `integer-simple` use the attribute:
-`haskell.packages.integer-simple."${ghcVersion}"`. For example
-use the following to get the `scientific` package build with `integer-simple`:
-```shell
-nix-build -A haskell.packages.integer-simple.ghc802.scientific
-```
-
-### Quality assurance
-
-The `haskell.lib` library includes a number of functions for checking for
-various imperfections in Haskell packages. It's useful to apply these functions
-to your own Haskell packages and integrate that in a Continuous Integration
-server like [hydra](https://nixos.org/hydra/) to assure your packages maintain a
-minimum level of quality. This section discusses some of these functions.
-
-#### failOnAllWarnings
-
-Applying `haskell.lib.failOnAllWarnings` to a Haskell package enables the
-`-Wall` and `-Werror` GHC options to turn all warnings into build failures.
-
-#### buildStrictly
-
-Applying `haskell.lib.buildStrictly` to a Haskell package calls
-`failOnAllWarnings` on the given package to turn all warnings into build
-failures. Additionally the source of your package is gotten from first invoking
-`cabal sdist` to ensure all needed files are listed in the Cabal file.
-
-#### checkUnusedPackages
-
-Applying `haskell.lib.checkUnusedPackages` to a Haskell package invokes
-the [packunused](http://hackage.haskell.org/package/packunused) tool on the
-package. `packunused` complains when it finds packages listed as build-depends
-in the Cabal file which are redundant. For example:
-
-```
-$ nix-build -E 'let pkgs = import {}; in pkgs.haskell.lib.checkUnusedPackages {} pkgs.haskellPackages.scientific'
-these derivations will be built:
- /nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv
-...
-detected package components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- - library
- - testsuite(s): test-scientific
- - benchmark(s): bench-scientific*
-
-(component names suffixed with '*' are not configured to be built)
-
-library
-~~~~~~~
-
-The following package dependencies seem redundant:
-
- - ghc-prim-0.5.0.0
-
-testsuite(test-scientific)
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-no redundant packages dependencies found
-
-builder for ‘/nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv’ failed with exit code 1
-error: build of ‘/nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv’ failed
-```
-
-As you can see, `packunused` finds out that although the testsuite component has
-no redundant dependencies the library component of `scientific-0.3.5.1` depends
-on `ghc-prim` which is unused in the library.
-
-## Other resources
-
- - The Youtube video [Nix Loves Haskell](https://www.youtube.com/watch?v=BsBhi_r-OeE)
- provides an introduction into Haskell NG aimed at beginners. The slides are
- available at http://cryp.to/nixos-meetup-3-slides.pdf and also -- in a form
- ready for cut & paste -- at
- https://github.com/NixOS/cabal2nix/blob/master/doc/nixos-meetup-3-slides.md.
-
- - Another Youtube video is [Escaping Cabal Hell with Nix](https://www.youtube.com/watch?v=mQd3s57n_2Y),
- which discusses the subject of Haskell development with Nix but also provides
- a basic introduction to Nix as well, i.e. it's suitable for viewers with
- almost no prior Nix experience.
-
- - Oliver Charles wrote a very nice [Tutorial how to develop Haskell packages with Nix](http://wiki.ocharles.org.uk/Nix).
-
- - The *Journey into the Haskell NG infrastructure* series of postings
- describe the new Haskell infrastructure in great detail:
-
- - [Part 1](https://nixos.org/nix-dev/2015-January/015591.html)
- explains the differences between the old and the new code and gives
- instructions how to migrate to the new setup.
-
- - [Part 2](https://nixos.org/nix-dev/2015-January/015608.html)
- looks in-depth at how to tweak and configure your setup by means of
- overrides.
-
- - [Part 3](https://nixos.org/nix-dev/2015-April/016912.html)
- describes the infrastructure that keeps the Haskell package set in Nixpkgs
- up-to-date.
diff --git a/doc/languages-frameworks/haskell.section.md b/doc/languages-frameworks/haskell.section.md
new file mode 100644
index 000000000000..1623e0d276f2
--- /dev/null
+++ b/doc/languages-frameworks/haskell.section.md
@@ -0,0 +1,953 @@
+---
+title: User's Guide for Haskell in Nixpkgs
+author: Peter Simons
+date: 2015-06-01
+---
+# User's Guide to the Haskell Infrastructure
+
+
+## How to install Haskell packages
+
+Nixpkgs distributes build instructions for all Haskell packages registered on
+[Hackage](http://hackage.haskell.org/), but strangely enough normal Nix package
+lookups don't seem to discover any of them, except for the default version of ghc, cabal-install, and stack:
+```
+$ nix-env -i alex
+error: selector ‘alex’ matches no derivations
+$ nix-env -qa ghc
+ghc-7.10.2
+```
+
+The Haskell package set is not registered in the top-level namespace because it
+is *huge*. If all Haskell packages were visible to these commands, then
+name-based search/install operations would be much slower than they are now. We
+avoided that by keeping all Haskell-related packages in a separate attribute
+set called `haskellPackages`, which the following command will list:
+```
+$ nix-env -f "" -qaP -A haskellPackages
+haskellPackages.a50 a50-0.5
+haskellPackages.abacate haskell-abacate-0.0.0.0
+haskellPackages.abcBridge haskell-abcBridge-0.12
+haskellPackages.afv afv-0.1.1
+haskellPackages.alex alex-3.1.4
+haskellPackages.Allure Allure-0.4.101.1
+haskellPackages.alms alms-0.6.7
+[... some 8000 entries omitted ...]
+```
+
+To install any of those packages into your profile, refer to them by their
+attribute path (first column):
+```shell
+nix-env -f "" -iA haskellPackages.Allure ...
+```
+
+The attribute path of any Haskell packages corresponds to the name of that
+particular package on Hackage: the package `cabal-install` has the attribute
+`haskellPackages.cabal-install`, and so on. (Actually, this convention causes
+trouble with packages like `3dmodels` and `4Blocks`, because these names are
+invalid identifiers in the Nix language. The issue of how to deal with these
+rare corner cases is currently unresolved.)
+
+Haskell packages whose Nix name (second column) begins with a `haskell-` prefix
+are packages that provide a library whereas packages without that prefix
+provide just executables. Libraries may provide executables too, though: the
+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].
+
+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
+`nix-env` an explicit `-f ""` parameter, but if you call `nix-env`
+without that flag, then chances are the invocation fails:
+```
+$ nix-env -iA haskellPackages.cabal-install
+error: attribute ‘haskellPackages’ in selection path
+ ‘haskellPackages.cabal-install’ not found
+```
+
+On NixOS, for example, Nixpkgs does *not* exist in the top-level namespace by
+default. To figure out the proper attribute path, it's easiest to query for the
+path of a well-known Nixpkgs package, i.e.:
+```
+$ nix-env -qaP coreutils
+nixos.coreutils coreutils-8.23
+```
+
+If your system responds like that (most NixOS installations will), then the
+attribute path to `haskellPackages` is `nixos.haskellPackages`. Thus, if you
+want to use `nix-env` without giving an explicit `-f` flag, then that's the way
+to do it:
+```shell
+nix-env -qaP -A nixos.haskellPackages
+nix-env -iA nixos.haskellPackages.cabal-install
+```
+
+Our current default compiler is GHC 7.10.x and the `haskellPackages` set
+contains packages built with that particular version. Nixpkgs contains the
+latest major release of every GHC since 6.10.4, however, and there is a whole
+family of package sets available that defines Hackage packages built with each
+of those compilers, too:
+```shell
+nix-env -f "" -qaP -A haskell.packages.ghc6123
+nix-env -f "" -qaP -A haskell.packages.ghc763
+```
+
+The name `haskellPackages` is really just a synonym for
+`haskell.packages.ghc7102`, because we prefer that package set internally and
+recommend it to our users as their default choice, but ultimately you are free
+to compile your Haskell packages with any GHC version you please. The following
+command displays the complete list of available compilers:
+```
+$ nix-env -f "" -qaP -A haskell.compiler
+haskell.compiler.ghc6104 ghc-6.10.4
+haskell.compiler.ghc6123 ghc-6.12.3
+haskell.compiler.ghc704 ghc-7.0.4
+haskell.compiler.ghc722 ghc-7.2.2
+haskell.compiler.ghc742 ghc-7.4.2
+haskell.compiler.ghc763 ghc-7.6.3
+haskell.compiler.ghc784 ghc-7.8.4
+haskell.compiler.ghc7102 ghc-7.10.2
+haskell.compiler.ghcHEAD ghc-7.11.20150402
+haskell.compiler.ghcNokinds ghc-nokinds-7.11.20150704
+haskell.compiler.ghcjs ghcjs-0.1.0
+haskell.compiler.jhc jhc-0.8.2
+haskell.compiler.uhc uhc-1.1.9.0
+```
+
+We have no package sets for `jhc` or `uhc` yet, unfortunately, but for every
+version of GHC listed above, there exists a package set based on that compiler.
+Also, the attributes `haskell.compiler.ghcXYC` and
+`haskell.packages.ghcXYC.ghc` are synonymous for the sake of convenience.
+
+## How to create a development environment
+
+### How to install a compiler
+
+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
+user profile:
+```shell
+nix-env -f "" -iA haskellPackages.ghc haskellPackages.cabal-install
+```
+
+Instead of the default package set `haskellPackages`, you can also use the more
+precise name `haskell.compiler.ghc7102`, which has the advantage that it refers
+to the same GHC version regardless of what Nixpkgs considers "default" at any
+given time.
+
+Once you've made those tools available in `$PATH`, it's possible to build
+Hackage packages the same way people without access to Nix do it all the time:
+```shell
+cabal get lens-4.11 && cd lens-4.11
+cabal install -j --dependencies-only
+cabal configure
+cabal build
+```
+
+If you enjoy working with Cabal sandboxes, then that's entirely possible too:
+just execute the command
+```shell
+cabal sandbox init
+```
+before installing the required dependencies.
+
+The `nix-shell` utility makes it easy to switch to a different compiler
+version; just enter the Nix shell environment with the command
+```shell
+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].
+
+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
+a project that doesn't depend on any additional system libraries outside of GHC,
+then it's even sufficient to just run the `cabal configure` command inside of
+the shell:
+```shell
+nix-shell -p haskell.compiler.ghc784 --command "cabal configure"
+```
+
+Afterwards, all other commands like `cabal build` work just fine in any shell
+environment, because the configure phase recorded the absolute paths to all
+required tools like GHC in its build configuration inside of the `dist/`
+directory. Please note, however, that `nix-collect-garbage` can break such an
+environment because the Nix store paths created by `nix-shell` aren't "alive"
+anymore once `nix-shell` has terminated. If you find that your Haskell builds
+no longer work after garbage collection, then you'll have to re-run `cabal
+configure` inside of a new `nix-shell` environment.
+
+### How to install a compiler with libraries
+
+GHC expects to find all installed libraries inside of its own `lib` directory.
+This approach works fine on traditional Unix systems, but it doesn't work for
+Nix, because GHC's store path is immutable once it's built. We cannot install
+additional libraries into that location. As a consequence, our copies of GHC
+don't know any packages except their own core libraries, like `base`,
+`containers`, `Cabal`, etc.
+
+We can register additional libraries to GHC, however, using a special build
+function called `ghcWithPackages`. That function expects one argument: a
+function that maps from an attribute set of Haskell packages to a list of
+packages, which determines the libraries known to that particular version of
+GHC. For example, the Nix expression `ghcWithPackages (pkgs: [pkgs.mtl])`
+generates a copy of GHC that has the `mtl` library registered in addition to
+its normal core packages:
+```
+$ nix-shell -p "haskellPackages.ghcWithPackages (pkgs: [pkgs.mtl])"
+
+[nix-shell:~]$ ghc-pkg list mtl
+/nix/store/zy79...-ghc-7.10.2/lib/ghc-7.10.2/package.conf.d:
+ mtl-2.2.1
+```
+
+This function allows users to define their own development environment by means
+of an override. After adding the following snippet to `~/.config/nixpkgs/config.nix`,
+```nix
+{
+ packageOverrides = super: let self = super.pkgs; in
+ {
+ myHaskellEnv = self.haskell.packages.ghc7102.ghcWithPackages
+ (haskellPackages: with haskellPackages; [
+ # libraries
+ arrows async cgi criterion
+ # tools
+ cabal-install haskintex
+ ]);
+ };
+}
+```
+it's possible to install that compiler with `nix-env -f "" -iA
+myHaskellEnv`. If you'd like to switch that development environment to a
+different version of GHC, just replace the `ghc7102` bit in the previous
+definition with the appropriate name. Of course, it's also possible to define
+any number of these development environments! (You can't install two of them
+into the same profile at the same time, though, because that would result in
+file conflicts.)
+
+The generated `ghc` program is a wrapper script that re-directs the real
+GHC executable to use a new `lib` directory --- one that we specifically
+constructed to contain all those packages the user requested:
+```
+$ cat $(type -p ghc)
+#! /nix/store/xlxj...-bash-4.3-p33/bin/bash -e
+export NIX_GHC=/nix/store/19sm...-ghc-7.10.2/bin/ghc
+export NIX_GHCPKG=/nix/store/19sm...-ghc-7.10.2/bin/ghc-pkg
+export NIX_GHC_DOCDIR=/nix/store/19sm...-ghc-7.10.2/share/doc/ghc/html
+export NIX_GHC_LIBDIR=/nix/store/19sm...-ghc-7.10.2/lib/ghc-7.10.2
+exec /nix/store/j50p...-ghc-7.10.2/bin/ghc "-B$NIX_GHC_LIBDIR" "$@"
+```
+
+The variables `$NIX_GHC`, `$NIX_GHCPKG`, etc. point to the *new* store path
+`ghcWithPackages` constructed specifically for this environment. The last line
+of the wrapper script then executes the real `ghc`, but passes the path to the
+new `lib` directory using GHC's `-B` flag.
+
+The purpose of those environment variables is to work around an impurity in the
+popular [ghc-paths](http://hackage.haskell.org/package/ghc-paths) library. That
+library promises to give its users access to GHC's installation paths. Only,
+the library can't possible know that path when it's compiled, because the path
+GHC considers its own is determined only much later, when the user configures
+it through `ghcWithPackages`. So we [patched
+ghc-paths](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/patches/ghc-paths-nix.patch)
+to return the paths found in those environment variables at run-time rather
+than trying to guess them at compile-time.
+
+To make sure that mechanism works properly all the time, we recommend that you
+set those variables to meaningful values in your shell environment, too, i.e.
+by adding the following code to your `~/.bashrc`:
+```bash
+if type >/dev/null 2>&1 -p ghc; then
+ eval "$(egrep ^export "$(type -p ghc)")"
+fi
+```
+
+If you are certain that you'll use only one GHC environment which is located in
+your user profile, then you can use the following code, too, which has the
+advantage that it doesn't contain any paths from the Nix store, i.e. those
+settings always remain valid even if a `nix-env -u` operation updates the GHC
+environment in your profile:
+```bash
+if [ -e ~/.nix-profile/bin/ghc ]; then
+ export NIX_GHC="$HOME/.nix-profile/bin/ghc"
+ export NIX_GHCPKG="$HOME/.nix-profile/bin/ghc-pkg"
+ export NIX_GHC_DOCDIR="$HOME/.nix-profile/share/doc/ghc/html"
+ export NIX_GHC_LIBDIR="$HOME/.nix-profile/lib/ghc-$($NIX_GHC --numeric-version)"
+fi
+```
+
+### How to install a compiler with libraries, hoogle and documentation indexes
+
+If you plan to use your environment for interactive programming, not just
+compiling random Haskell code, you might want to replace `ghcWithPackages` in
+all the listings above with `ghcWithHoogle`.
+
+This environment generator not only produces an environment with GHC and all
+the specified libraries, but also generates a `hoogle` and `haddock` indexes
+for all the packages, and provides a wrapper script around `hoogle` binary that
+uses all those things. A precise name for this thing would be
+"`ghcWithPackagesAndHoogleAndDocumentationIndexes`", which is, regrettably, too
+long and scary.
+
+For example, installing the following environment
+```nix
+{
+ packageOverrides = super: let self = super.pkgs; in
+ {
+ myHaskellEnv = self.haskellPackages.ghcWithHoogle
+ (haskellPackages: with haskellPackages; [
+ # libraries
+ arrows async cgi criterion
+ # tools
+ cabal-install haskintex
+ ]);
+ };
+}
+```
+allows one to browse module documentation index [not too dissimilar to
+this](https://downloads.haskell.org/~ghc/latest/docs/html/libraries/index.html)
+for all the specified packages and their dependencies by directing a browser of
+choice to `~/.nix-profiles/share/doc/hoogle/index.html` (or
+`/run/current-system/sw/share/doc/hoogle/index.html` in case you put it in
+`environment.systemPackages` in NixOS).
+
+After you've marveled enough at that try adding the following to your
+`~/.ghc/ghci.conf`
+```
+:def hoogle \s -> return $ ":! hoogle search -cl --count=15 \"" ++ s ++ "\""
+:def doc \s -> return $ ":! hoogle search -cl --info \"" ++ s ++ "\""
+```
+and test it by typing into `ghci`:
+```
+:hoogle a -> a
+:doc a -> a
+```
+
+Be sure to note the links to `haddock` files in the output. With any modern and
+properly configured terminal emulator you can just click those links to
+navigate there.
+
+Finally, you can run
+```shell
+hoogle server -p 8080 --local
+```
+and navigate to http://localhost:8080/ for your own local
+[Hoogle](https://www.haskell.org/hoogle/).
+
+### How to build a Haskell project using Stack
+
+[Stack](http://haskellstack.org) is a popular build tool for Haskell projects.
+It has first-class support for Nix. Stack can optionally use Nix to
+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
+cd wai
+stack --nix build
+```
+
+If you want `stack` to use Nix by default, you can add a `nix` section to the
+`stack.yaml` file, as explained in the [Stack documentation][stack-nix-doc]. For
+example:
+```yaml
+nix:
+ enable: true
+ packages: [pkgconfig zeromq zlib]
+```
+
+The example configuration snippet above tells Stack to create an ad hoc
+environment for `nix-shell` as in the below section, in which the `pkgconfig`,
+`zeromq` and `zlib` packages from Nixpkgs are available. All `stack` commands
+will implicitly be executed inside this ad hoc environment.
+
+Some projects have more sophisticated needs. For examples, some ad hoc
+environments might need to expose Nixpkgs packages compiled in a certain way, or
+with extra environment variables. In these cases, you'll need a `shell` field
+instead of `packages`:
+```yaml
+nix:
+ enable: true
+ shell-file: shell.nix
+```
+
+For more on how to write a `shell.nix` file see the below section. You'll need
+to express a derivation. Note that Nixpkgs ships with a convenience wrapper
+function around `mkDerivation` called `haskell.lib.buildStackProject` to help you
+create this derivation in exactly the way Stack expects. All of the same inputs
+as `mkDerivation` can be provided. For example, to build a Stack project that
+including packages that link against a version of the R library compiled with
+special options turned on:
+```nix
+with (import { });
+
+let R = pkgs.R.override { enableStrictBarrier = true; };
+in
+haskell.lib.buildStackProject {
+ name = "HaskellR";
+ buildInputs = [ R zeromq zlib ];
+}
+```
+
+You can select a particular GHC version to compile with by setting the
+`ghc` attribute as an argument to `buildStackProject`. Better yet, let
+Stack choose what GHC version it wants based on the snapshot specified
+in `stack.yaml` (only works with Stack >= 1.1.3):
+```nix
+{nixpkgs ? import { }, ghc ? nixpkgs.ghc}:
+
+with nixpkgs;
+
+let R = pkgs.R.override { enableStrictBarrier = true; };
+in
+haskell.lib.buildStackProject {
+ name = "HaskellR";
+ buildInputs = [ R zeromq zlib ];
+ inherit ghc;
+}
+```
+
+[stack-nix-doc]: http://docs.haskellstack.org/en/stable/nix_integration.html
+
+### How to create ad hoc environments for `nix-shell`
+
+The easiest way to create an ad hoc development environment is to run
+`nix-shell` with the appropriate GHC environment given on the command-line:
+```shell
+nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [mtl pandoc])"
+```
+
+For more sophisticated use-cases, however, it's more convenient to save the
+desired configuration in a file called `shell.nix` that looks like this:
+```nix
+{ nixpkgs ? import {}, compiler ? "ghc7102" }:
+let
+ inherit (nixpkgs) pkgs;
+ ghc = pkgs.haskell.packages.${compiler}.ghcWithPackages (ps: with ps; [
+ monad-par mtl
+ ]);
+in
+pkgs.stdenv.mkDerivation {
+ name = "my-haskell-env-0";
+ buildInputs = [ ghc ];
+ shellHook = "eval $(egrep ^export ${ghc}/bin/ghc)";
+}
+```
+
+Now run `nix-shell` --- or even `nix-shell --pure` --- to enter a shell
+environment that has the appropriate compiler in `$PATH`. If you use `--pure`,
+then add all other packages that your development environment needs into the
+`buildInputs` attribute. If you'd like to switch to a different compiler
+version, then pass an appropriate `compiler` argument to the expression, i.e.
+`nix-shell --argstr compiler ghc784`.
+
+If you need such an environment because you'd like to compile a Hackage package
+outside of Nix --- i.e. because you're hacking on the latest version from Git
+---, then the package set provides suitable nix-shell environments for you
+already! Every Haskell package has an `env` attribute that provides a shell
+environment suitable for compiling that particular package. If you'd like to
+hack the `lens` library, for example, then you just have to check out the
+source code and enter the appropriate environment:
+```
+$ cabal get lens-4.11 && cd lens-4.11
+Downloading lens-4.11...
+Unpacking to lens-4.11/
+
+$ nix-shell "" -A haskellPackages.lens.env
+[nix-shell:/tmp/lens-4.11]$
+```
+
+At point, you can run `cabal configure`, `cabal build`, and all the other
+development commands. Note that you need `cabal-install` installed in your
+`$PATH` already to use it here --- the `nix-shell` environment does not provide
+it.
+
+## How to create Nix builds for your own private Haskell packages
+
+If your own Haskell packages have build instructions for Cabal, then you can
+convert those automatically into build instructions for Nix using the
+`cabal2nix` utility, which you can install into your profile by running
+`nix-env -i cabal2nix`.
+
+### How to build a stand-alone project
+
+For example, let's assume that you're working on a private project called
+`foo`. To generate a Nix build expression for it, change into the project's
+top-level directory and run the command:
+```shell
+cabal2nix . > foo.nix
+```
+Then write the following snippet into a file called `default.nix`:
+```nix
+{ nixpkgs ? import {}, compiler ? "ghc7102" }:
+nixpkgs.pkgs.haskell.packages.${compiler}.callPackage ./foo.nix { }
+```
+
+Finally, store the following code in a file called `shell.nix`:
+```nix
+{ nixpkgs ? import {}, compiler ? "ghc7102" }:
+(import ./default.nix { inherit nixpkgs compiler; }).env
+```
+
+At this point, you can run `nix-build` to have Nix compile your project and
+install it into a Nix store path. The local directory will contain a symlink
+called `result` after `nix-build` returns that points into that location. Of
+course, passing the flag `--argstr compiler ghc763` allows switching the build
+to any version of GHC currently supported.
+
+Furthermore, you can call `nix-shell` to enter an interactive development
+environment in which you can use `cabal configure` and `cabal build` to develop
+your code. That environment will automatically contain a proper GHC derivation
+with all the required libraries registered as well as all the system-level
+libraries your package might need.
+
+If your package does not depend on any system-level libraries, then it's
+sufficient to run
+```shell
+nix-shell --command "cabal configure"
+```
+once to set up your build. `cabal-install` determines the absolute paths to all
+resources required for the build and writes them into a config file in the
+`dist/` directory. Once that's done, you can run `cabal build` and any other
+command for that project even outside of the `nix-shell` environment. This
+feature is particularly nice for those of us who like to edit their code with
+an IDE, like Emacs' `haskell-mode`, because it's not necessary to start Emacs
+inside of nix-shell just to make it find out the necessary settings for
+building the project; `cabal-install` has already done that for us.
+
+If you want to do some quick-and-dirty hacking and don't want to bother setting
+up a `default.nix` and `shell.nix` file manually, then you can use the
+`--shell` flag offered by `cabal2nix` to have it generate a stand-alone
+`nix-shell` environment for you. With that feature, running
+```shell
+cabal2nix --shell . > shell.nix
+nix-shell --command "cabal configure"
+```
+is usually enough to set up a build environment for any given Haskell package.
+You can even use that generated file to run `nix-build`, too:
+```shell
+nix-build shell.nix
+```
+
+### How to build projects that depend on each other
+
+If you have multiple private Haskell packages that depend on each other, then
+you'll have to register those packages in the Nixpkgs set to make them visible
+for the dependency resolution performed by `callPackage`. First of all, change
+into each of your projects top-level directories and generate a `default.nix`
+file with `cabal2nix`:
+```shell
+cd ~/src/foo && cabal2nix . > default.nix
+cd ~/src/bar && cabal2nix . > default.nix
+```
+Then edit your `~/.config/nixpkgs/config.nix` file to register those builds in the
+default Haskell package set:
+```nix
+{
+ packageOverrides = super: let self = super.pkgs; in
+ {
+ haskellPackages = super.haskellPackages.override {
+ overrides = self: super: {
+ foo = self.callPackage ../src/foo {};
+ bar = self.callPackage ../src/bar {};
+ };
+ };
+ };
+}
+```
+Once that's accomplished, `nix-env -f "" -qA haskellPackages` will
+show your packages like any other package from Hackage, and you can build them
+```shell
+nix-build "" -A haskellPackages.foo
+```
+or enter an interactive shell environment suitable for building them:
+```shell
+nix-shell "" -A haskellPackages.bar.env
+```
+
+## Miscellaneous Topics
+
+### How to build with profiling enabled
+
+Every Haskell package set takes a function called `overrides` that you can use
+to manipulate the package as much as you please. One useful application of this
+feature is to replace the default `mkDerivation` function with one that enables
+library profiling for all packages. To accomplish that add the following
+snippet to your `~/.config/nixpkgs/config.nix` file:
+```nix
+{
+ packageOverrides = super: let self = super.pkgs; in
+ {
+ profiledHaskellPackages = self.haskellPackages.override {
+ overrides = self: super: {
+ mkDerivation = args: super.mkDerivation (args // {
+ enableLibraryProfiling = true;
+ });
+ };
+ };
+ };
+}
+```
+Then, replace instances of `haskellPackages` in the `cabal2nix`-generated
+`default.nix` or `shell.nix` files with `profiledHaskellPackages`.
+
+### How to override package versions in a compiler-specific package set
+
+Nixpkgs provides the latest version of
+[`ghc-events`](http://hackage.haskell.org/package/ghc-events), which is 0.4.4.0
+at the time of this writing. This is fine for users of GHC 7.10.x, but GHC
+7.8.4 cannot compile that binary. Now, one way to solve that problem is to
+register an older version of `ghc-events` in the 7.8.x-specific package set.
+The first step is to generate Nix build instructions with `cabal2nix`:
+```shell
+cabal2nix cabal://ghc-events-0.4.3.0 > ~/.nixpkgs/ghc-events-0.4.3.0.nix
+```
+Then add the override in `~/.config/nixpkgs/config.nix`:
+```nix
+{
+ packageOverrides = super: let self = super.pkgs; in
+ {
+ haskell = super.haskell // {
+ packages = super.haskell.packages // {
+ ghc784 = super.haskell.packages.ghc784.override {
+ overrides = self: super: {
+ ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
+ };
+ };
+ };
+ };
+ };
+}
+```
+
+This code is a little crazy, no doubt, but it's necessary because the intuitive
+version
+```nix
+{ # ...
+
+ haskell.packages.ghc784 = super.haskell.packages.ghc784.override {
+ overrides = self: super: {
+ ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
+ };
+ };
+}
+```
+doesn't do what we want it to: that code replaces the `haskell` package set in
+Nixpkgs with one that contains only one entry,`packages`, which contains only
+one entry `ghc784`. This override loses the `haskell.compiler` set, and it
+loses the `haskell.packages.ghcXYZ` sets for all compilers but GHC 7.8.4. To
+avoid that problem, we have to perform the convoluted little dance from above,
+iterating over each step in hierarchy.
+
+Once it's accomplished, however, we can install a variant of `ghc-events`
+that's compiled with GHC 7.8.4:
+```shell
+nix-env -f "" -iA haskell.packages.ghc784.ghc-events
+```
+Unfortunately, it turns out that this build fails again while executing the
+test suite! Apparently, the release archive on Hackage is missing some data
+files that the test suite requires, so we cannot run it. We accomplish that by
+re-generating the Nix expression with the `--no-check` flag:
+```shell
+cabal2nix --no-check cabal://ghc-events-0.4.3.0 > ~/.nixpkgs/ghc-events-0.4.3.0.nix
+```
+Now the builds succeeds.
+
+Of course, in the concrete example of `ghc-events` this whole exercise is not
+an ideal solution, because `ghc-events` can analyze the output emitted by any
+version of GHC later than 6.12 regardless of the compiler version that was used
+to build the `ghc-events` executable, so strictly speaking there's no reason to
+prefer one built with GHC 7.8.x in the first place. However, for users who
+cannot use GHC 7.10.x at all for some reason, the approach of downgrading to an
+older version might be useful.
+
+### How to recover from GHC's infamous non-deterministic library ID bug
+
+GHC and distributed build farms don't get along well:
+
+ - https://ghc.haskell.org/trac/ghc/ticket/4012
+
+When you see an error like this one
+```
+package foo-0.7.1.0 is broken due to missing package
+text-1.2.0.4-98506efb1b9ada233bb5c2b2db516d91
+```
+then you have to download and re-install `foo` and all its dependents from
+scratch:
+```shell
+nix-store -q --referrers /nix/store/*-haskell-text-1.2.0.4 \
+ | xargs -L 1 nix-store --repair-path
+```
+
+If you're using additional Hydra servers other than `hydra.nixos.org`, then it
+might be necessary to purge the local caches that store data from those
+machines to disable these binary channels for the duration of the previous
+command, i.e. by running:
+```shell
+rm ~/.cache/nix/binary-cache*.sqlite
+```
+
+### Builds on Darwin fail with `math.h` not found
+
+Users of GHC on Darwin have occasionally reported that builds fail, because the
+compiler complains about a missing include file:
+```
+fatal error: 'math.h' file not found
+```
+The issue has been discussed at length in [ticket
+6390](https://github.com/NixOS/nixpkgs/issues/6390), and so far no good
+solution has been proposed. As a work-around, users who run into this problem
+can configure the environment variables
+```shell
+export NIX_CFLAGS_COMPILE="-idirafter /usr/include"
+export NIX_CFLAGS_LINK="-L/usr/lib"
+```
+in their `~/.bashrc` file to avoid the compiler error.
+
+### Builds using Stack complain about missing system libraries
+
+```
+-- While building package zlib-0.5.4.2 using:
+ runhaskell -package=Cabal-1.22.4.0 -clear-package-db [... lots of flags ...]
+Process exited with code: ExitFailure 1
+Logs have been written to: /home/foo/src/stack-ide/.stack-work/logs/zlib-0.5.4.2.log
+
+Configuring zlib-0.5.4.2...
+Setup.hs: Missing dependency on a foreign library:
+* Missing (or bad) header file: zlib.h
+This problem can usually be solved by installing the system package that
+provides this library (you may need the "-dev" version). If the library is
+already installed but in a non-standard location then you can use the flags
+--extra-include-dirs= and --extra-lib-dirs= to specify where it is.
+If the header file does exist, it may contain errors that are caught by the C
+compiler at the preprocessing stage. In this case you can re-run configure
+with the verbosity flag -v3 to see the error messages.
+```
+
+When you run the build inside of the nix-shell environment, the system
+is configured to find `libz.so` without any special flags -- the compiler
+and linker "just know" how to find it. Consequently, Cabal won't record
+any search paths for `libz.so` in the package description, which means
+that the package works fine inside of nix-shell, but once you leave the
+shell the shared object can no longer be found. That issue is by no
+means specific to Stack: you'll have that problem with any other
+Haskell package that's built inside of nix-shell but run outside of that
+environment.
+
+You can remedy this issue in several ways. The easiest is to add a `nix` section
+to the `stack.yaml` like the following:
+```yaml
+nix:
+ enable: true
+ packages: [ zlib ]
+```
+
+Stack's Nix support knows to add `${zlib.out}/lib` and `${zlib.dev}/include`
+as an `--extra-lib-dirs` and `extra-include-dirs`, respectively.
+Alternatively, you can achieve the same effect by hand. First of all, run
+```
+$ nix-build --no-out-link "" -A zlib
+/nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8
+```
+to find out the store path of the system's zlib library. Now, you can
+
+ 1. add that path (plus a "/lib" suffix) to your `$LD_LIBRARY_PATH`
+ environment variable to make sure your system linker finds `libz.so`
+ automatically. It's no pretty solution, but it will work.
+
+ 2. As a variant of (1), you can also install any number of system
+ libraries into your user's profile (or some other profile) and point
+ `$LD_LIBRARY_PATH` to that profile instead, so that you don't have to
+ list dozens of those store paths all over the place.
+
+ 3. The solution I prefer is to call stack with an appropriate
+ --extra-lib-dirs flag like so:
+ ```shell
+ stack --extra-lib-dirs=/nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8/lib build
+ ```
+
+Typically, you'll need `--extra-include-dirs` as well. It's possible
+to add those flag to the project's `stack.yaml` or your user's
+global `~/.stack/global/stack.yaml` file so that you don't have to
+specify them manually every time. But again, you're likely better off
+using Stack's Nix support instead.
+
+The same thing applies to `cabal configure`, of course, if you're
+building with `cabal-install` instead of Stack.
+
+### Creating statically linked binaries
+
+There are two levels of static linking. The first option is to configure the
+build with the Cabal flag `--disable-executable-dynamic`. In Nix expressions,
+this can be achieved by setting the attribute:
+```
+enableSharedExecutables = false;
+```
+That gives you a binary with statically linked Haskell libraries and
+dynamically linked system libraries.
+
+To link both Haskell libraries and system libraries statically, the additional
+flags `--ghc-option=-optl=-static --ghc-option=-optl=-pthread` need to be used.
+In Nix, this is accomplished with:
+```
+configureFlags = [ "--ghc-option=-optl=-static" "--ghc-option=-optl=-pthread" ];
+```
+
+It's important to realize, however, that most system libraries in Nix are
+built as shared libraries only, i.e. there is just no static library
+available that Cabal could link!
+
+### Building GHC with integer-simple
+
+By default GHC implements the Integer type using the
+[GNU Multiple Precision Arithmetic (GMP) library](https://gmplib.org/).
+The implementation can be found in the
+[integer-gmp](http://hackage.haskell.org/package/integer-gmp) package.
+
+A potential problem with this is that GMP is licensed under the
+[GNU Lesser General Public License (LGPL)](http://www.gnu.org/copyleft/lesser.html),
+a kind of "copyleft" license. According to the terms of the LGPL, paragraph 5,
+you may distribute a program that is designed to be compiled and dynamically
+linked with the library under the terms of your choice (i.e., commercially) but
+if your program incorporates portions of the library, if it is linked
+statically, then your program is a "derivative"--a "work based on the
+library"--and according to paragraph 2, section c, you "must cause the whole of
+the work to be licensed" under the terms of the LGPL (including for free).
+
+The LGPL licensing for GMP is a problem for the overall licensing of binary
+programs compiled with GHC because most distributions (and builds) of GHC use
+static libraries. (Dynamic libraries are currently distributed only for macOS.)
+The LGPL licensing situation may be worse: even though
+[The Glasgow Haskell Compiler License](https://www.haskell.org/ghc/license)
+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
+[integer-simple](http://hackage.haskell.org/package/integer-simple).
+
+To get a GHC compiler build with `integer-simple` instead of `integer-gmp` use
+the attribute: `haskell.compiler.integer-simple."${ghcVersion}"`.
+For example:
+```
+$ nix-build -E '(import {}).haskell.compiler.integer-simple.ghc802'
+...
+$ result/bin/ghc-pkg list | grep integer
+ integer-simple-0.1.1.1
+```
+The following command displays the complete list of GHC compilers build with `integer-simple`:
+```
+$ nix-env -f "" -qaP -A haskell.compiler.integer-simple
+haskell.compiler.integer-simple.ghc7102 ghc-7.10.2
+haskell.compiler.integer-simple.ghc7103 ghc-7.10.3
+haskell.compiler.integer-simple.ghc722 ghc-7.2.2
+haskell.compiler.integer-simple.ghc742 ghc-7.4.2
+haskell.compiler.integer-simple.ghc783 ghc-7.8.3
+haskell.compiler.integer-simple.ghc784 ghc-7.8.4
+haskell.compiler.integer-simple.ghc801 ghc-8.0.1
+haskell.compiler.integer-simple.ghc802 ghc-8.0.2
+haskell.compiler.integer-simple.ghcHEAD ghc-8.1.20170106
+```
+
+To get a package set supporting `integer-simple` use the attribute:
+`haskell.packages.integer-simple."${ghcVersion}"`. For example
+use the following to get the `scientific` package build with `integer-simple`:
+```shell
+nix-build -A haskell.packages.integer-simple.ghc802.scientific
+```
+
+### Quality assurance
+
+The `haskell.lib` library includes a number of functions for checking for
+various imperfections in Haskell packages. It's useful to apply these functions
+to your own Haskell packages and integrate that in a Continuous Integration
+server like [hydra](https://nixos.org/hydra/) to assure your packages maintain a
+minimum level of quality. This section discusses some of these functions.
+
+#### failOnAllWarnings
+
+Applying `haskell.lib.failOnAllWarnings` to a Haskell package enables the
+`-Wall` and `-Werror` GHC options to turn all warnings into build failures.
+
+#### buildStrictly
+
+Applying `haskell.lib.buildStrictly` to a Haskell package calls
+`failOnAllWarnings` on the given package to turn all warnings into build
+failures. Additionally the source of your package is gotten from first invoking
+`cabal sdist` to ensure all needed files are listed in the Cabal file.
+
+#### checkUnusedPackages
+
+Applying `haskell.lib.checkUnusedPackages` to a Haskell package invokes
+the [packunused](http://hackage.haskell.org/package/packunused) tool on the
+package. `packunused` complains when it finds packages listed as build-depends
+in the Cabal file which are redundant. For example:
+
+```
+$ nix-build -E 'let pkgs = import {}; in pkgs.haskell.lib.checkUnusedPackages {} pkgs.haskellPackages.scientific'
+these derivations will be built:
+ /nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv
+...
+detected package components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ - library
+ - testsuite(s): test-scientific
+ - benchmark(s): bench-scientific*
+
+(component names suffixed with '*' are not configured to be built)
+
+library
+~~~~~~~
+
+The following package dependencies seem redundant:
+
+ - ghc-prim-0.5.0.0
+
+testsuite(test-scientific)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+no redundant packages dependencies found
+
+builder for ‘/nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv’ failed with exit code 1
+error: build of ‘/nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv’ failed
+```
+
+As you can see, `packunused` finds out that although the testsuite component has
+no redundant dependencies the library component of `scientific-0.3.5.1` depends
+on `ghc-prim` which is unused in the library.
+
+## Other resources
+
+ - The Youtube video [Nix Loves Haskell](https://www.youtube.com/watch?v=BsBhi_r-OeE)
+ provides an introduction into Haskell NG aimed at beginners. The slides are
+ available at http://cryp.to/nixos-meetup-3-slides.pdf and also -- in a form
+ ready for cut & paste -- at
+ https://github.com/NixOS/cabal2nix/blob/master/doc/nixos-meetup-3-slides.md.
+
+ - Another Youtube video is [Escaping Cabal Hell with Nix](https://www.youtube.com/watch?v=mQd3s57n_2Y),
+ which discusses the subject of Haskell development with Nix but also provides
+ a basic introduction to Nix as well, i.e. it's suitable for viewers with
+ almost no prior Nix experience.
+
+ - Oliver Charles wrote a very nice [Tutorial how to develop Haskell packages with Nix](http://wiki.ocharles.org.uk/Nix).
+
+ - The *Journey into the Haskell NG infrastructure* series of postings
+ describe the new Haskell infrastructure in great detail:
+
+ - [Part 1](https://nixos.org/nix-dev/2015-January/015591.html)
+ explains the differences between the old and the new code and gives
+ instructions how to migrate to the new setup.
+
+ - [Part 2](https://nixos.org/nix-dev/2015-January/015608.html)
+ looks in-depth at how to tweak and configure your setup by means of
+ overrides.
+
+ - [Part 3](https://nixos.org/nix-dev/2015-April/016912.html)
+ describes the infrastructure that keeps the Haskell package set in Nixpkgs
+ up-to-date.
diff --git a/doc/languages-frameworks/idris.section.md b/doc/languages-frameworks/idris.section.md
new file mode 100644
index 000000000000..005ed3602851
--- /dev/null
+++ b/doc/languages-frameworks/idris.section.md
@@ -0,0 +1,39 @@
+Idris packages
+==============
+
+This directory contains build rules for idris packages. In addition,
+it contains several functions to build and compose those packages.
+Everything is exposed to the user via the `idrisPackages` attribute.
+
+callPackage
+------------
+
+This is like the normal nixpkgs callPackage function, specialized to
+idris packages.
+
+builtins
+---------
+
+This is a list of all of the libraries that come packaged with Idris
+itself.
+
+build-idris-package
+--------------------
+
+A function to build an idris package. Its sole argument is a set like
+you might pass to `stdenv.mkDerivation`, except `build-idris-package`
+sets several attributes for you. See `build-idris-package.nix` for
+details.
+
+build-builtin-package
+----------------------
+
+A version of `build-idris-package` specialized to builtin libraries.
+Mostly for internal use.
+
+with-packages
+-------------
+
+Bundle idris together with a list of packages. Because idris currently
+only supports a single directory in its library path, you must include
+all desired libraries here, including `prelude` and `base`.
\ No newline at end of file
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index fc15d847d15f..a1c265f67484 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -17,19 +17,20 @@ such as Perl or Haskell. These are described in this chapter.
-
-
+
+
-
+
-
+
-
+
-
+
-
+
+
diff --git a/doc/languages-frameworks/java.xml b/doc/languages-frameworks/java.xml
index 2d40a254cedf..2507cc2c469a 100644
--- a/doc/languages-frameworks/java.xml
+++ b/doc/languages-frameworks/java.xml
@@ -62,16 +62,7 @@ depending on the JDK at runtime.
It is possible to use a different Java compiler than
javac from the OpenJDK. For instance, to use the
-Eclipse Java Compiler:
-
-
-buildInputs = [ jre ant ecj ];
-
-
-(Note that here you don’t need the full JDK as an input, but just the
-JRE.) The ECJ has a stdenv setup hook that sets some environment
-variables to cause Ant to use ECJ, but this doesn’t work with all Ant
-files. Similarly, you can use the GNU Java Compiler:
+GNU Java Compiler:
buildInputs = [ gcj ant ];
diff --git a/doc/languages-frameworks/node.section.md b/doc/languages-frameworks/node.section.md
new file mode 100644
index 000000000000..17a203ed12be
--- /dev/null
+++ b/doc/languages-frameworks/node.section.md
@@ -0,0 +1,51 @@
+Node.js packages
+================
+The `pkgs/development/node-packages` folder contains a generated collection of
+[NPM packages](https://npmjs.com/) that can be installed with the Nix package
+manager.
+
+As a rule of thumb, the package set should only provide *end user* software
+packages, such as command-line utilities. Libraries should only be added to the
+package set if there is a non-NPM package that requires it.
+
+When it is desired to use NPM libraries in a development project, use the
+`node2nix` generator directly on the `package.json` configuration file of the
+project.
+
+The package set also provides support for multiple Node.js versions. The policy
+is that a new package should be added to the collection for the latest stable LTS
+release (which is currently 6.x), unless there is an explicit reason to support
+a different release.
+
+If your package uses native addons, you need to examine what kind of native
+build system it uses. Here are some examples:
+
+* `node-gyp`
+* `node-gyp-builder`
+* `node-pre-gyp`
+
+After you have identified the correct system, you need to override your package
+expression while adding in build system as a build input. For example, `dat`
+requires `node-gyp-build`, so we override its expression in `default-v6.nix`:
+
+```nix
+dat = nodePackages.dat.override (oldAttrs: {
+ buildInputs = oldAttrs.buildInputs ++ [ nodePackages.node-gyp-build ];
+});
+```
+
+To add a package from NPM to nixpkgs:
+
+ 1. Modify `pkgs/development/node-packages/node-packages-v6.json` to add, update
+ or remove package entries. (Or `pkgs/development/node-packages/node-packages-v4.json`
+ for packages depending on Node.js 4.x)
+ 2. Run the script: `(cd pkgs/development/node-packages && ./generate.sh)`.
+ 3. Build your new package to test your changes:
+ `cd /path/to/nixpkgs && nix-build -A nodePackages.`.
+ To build against a specific Node.js version (e.g. 4.x):
+ `nix-build -A nodePackages_4_x.`
+ 4. Add and commit all modified and generated files.
+
+For more information about the generation process, consult the
+[README.md](https://github.com/svanderburg/node2nix) file of the `node2nix`
+tool.
diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml
index dfb463b99912..149fcb275a09 100644
--- a/doc/languages-frameworks/perl.xml
+++ b/doc/languages-frameworks/perl.xml
@@ -177,5 +177,19 @@ you need it.
+Cross-compiling modules
+
+Nixpkgs has experimental support for cross-compiling Perl
+modules. In many cases, it will just work out of the box, even for
+modules with native extensions. Sometimes, however, the Makefile.PL
+for a module may (indirectly) import a native module. In that case,
+you will need to make a stub for that module that will satisfy the
+Makefile.PL and install it into
+lib/perl5/site_perl/cross_perl/${perl.version}.
+See the postInstall for DBI for
+an example.
+
+
+
diff --git a/doc/languages-frameworks/python.md b/doc/languages-frameworks/python.md
deleted file mode 100644
index 9172d7122139..000000000000
--- a/doc/languages-frameworks/python.md
+++ /dev/null
@@ -1,1020 +0,0 @@
-# Python
-
-## User Guide
-
-### Using Python
-
-#### Overview
-
-Several versions of the Python interpreter are available on Nix, as well as a
-high amount of packages. The attribute `python` refers to the default
-interpreter, which is currently CPython 2.7. It is also possible to refer to
-specific versions, e.g. `python35` refers to CPython 3.5, and `pypy` refers to
-the default PyPy interpreter.
-
-Python is used a lot, and in different ways. This affects also how it is
-packaged. In the case of Python on Nix, an important distinction is made between
-whether the package is considered primarily an application, or whether it should
-be used as a library, i.e., of primary interest are the modules in
-`site-packages` that should be importable.
-
-In the Nixpkgs tree Python applications can be found throughout, depending on
-what they do, and are called from the main package set. Python libraries,
-however, are in separate sets, with one set per interpreter version.
-
-The interpreters have several common attributes. One of these attributes is
-`pkgs`, which is a package set of Python libraries for this specific
-interpreter. E.g., the `toolz` package corresponding to the default interpreter
-is `python.pkgs.toolz`, and the CPython 3.5 version is `python35.pkgs.toolz`.
-The main package set contains aliases to these package sets, e.g.
-`pythonPackages` refers to `python.pkgs` and `python35Packages` to
-`python35.pkgs`.
-
-#### Installing Python and packages
-
-The Nix and NixOS manuals explain how packages are generally installed. In the
-case of Python and Nix, it is important to make a distinction between whether the
-package is considered an application or a library.
-
-Applications on Nix are typically installed into your user
-profile imperatively using `nix-env -i`, and on NixOS declaratively by adding the
-package name to `environment.systemPackages` in `/etc/nixos/configuration.nix`.
-Dependencies such as libraries are automatically installed and should not be
-installed explicitly.
-
-The same goes for Python applications and libraries. Python applications can be
-installed in your profile. But Python libraries you would like to use for
-development cannot be installed, at least not individually, because they won't
-be able to find each other resulting in import errors. Instead, it is possible
-to create an environment with `python.buildEnv` or `python.withPackages` where
-the interpreter and other executables are able to find each other and all of the
-modules.
-
-In the following examples we create an environment with Python 3.5, `numpy` and
-`toolz`. As you may imagine, there is one limitation here, and that's that
-you can install only one environment at a time. You will notice the complaints
-about collisions when you try to install a second environment.
-
-##### Environment defined in separate `.nix` file
-
-Create a file, e.g. `build.nix`, with the following expression
-```nix
-with import {};
-
-python35.withPackages (ps: with ps; [ numpy toolz ])
-```
-and install it in your profile with
-```shell
-nix-env -if build.nix
-```
-Now you can use the Python interpreter, as well as the extra packages (`numpy`,
-`toolz`) that you added to the environment.
-
-##### Environment defined in `~/.config/nixpkgs/config.nix`
-
-If you prefer to, you could also add the environment as a package override to the Nixpkgs set, e.g.
-using `config.nix`,
-```nix
-{ # ...
-
- packageOverrides = pkgs: with pkgs; {
- myEnv = python35.withPackages (ps: with ps; [ numpy toolz ]);
- };
-}
-```
-and install it in your profile with
-```shell
-nix-env -iA nixpkgs.myEnv
-```
-The environment is is installed by referring to the attribute, and considering
-the `nixpkgs` channel was used.
-
-##### Environment defined in `/etc/nixos/configuration.nix`
-
-For the sake of completeness, here's another example how to install the environment system-wide.
-
-```nix
-{ # ...
-
- environment.systemPackages = with pkgs; [
- (python35.withPackages(ps: with ps; [ numpy toolz ]))
- ];
-}
-```
-
-#### Temporary Python environment with `nix-shell`
-
-The examples in the previous section showed how to install a Python environment
-into a profile. For development you may need to use multiple environments.
-`nix-shell` gives the possibility to temporarily load another environment, akin
-to `virtualenv`.
-
-There are two methods for loading a shell with Python packages. The first and recommended method
-is to create an environment with `python.buildEnv` or `python.withPackages` and load that. E.g.
-```sh
-$ nix-shell -p 'python35.withPackages(ps: with ps; [ numpy toolz ])'
-```
-opens a shell from which you can launch the interpreter
-```sh
-[nix-shell:~] python3
-```
-The other method, which is not recommended, does not create an environment and requires you to list the packages directly,
-
-```sh
-$ nix-shell -p python35.pkgs.numpy python35.pkgs.toolz
-```
-Again, it is possible to launch the interpreter from the shell.
-The Python interpreter has the attribute `pkgs` which contains all Python libraries for that specific interpreter.
-
-##### Load environment from `.nix` expression
-As explained in the Nix manual, `nix-shell` can also load an
-expression from a `.nix` file. Say we want to have Python 3.5, `numpy`
-and `toolz`, like before, in an environment. Consider a `shell.nix` file
-with
-```nix
-with import {};
-
-python35.withPackages (ps: [ps.numpy ps.toolz])
-```
-Executing `nix-shell` gives you again a Nix shell from which you can run Python.
-
-What's happening here?
-
-1. We begin with importing the Nix Packages collections. `import ` imports the `` function, `{}` calls it and the `with` statement brings all attributes of `nixpkgs` in the local scope. These attributes form the main package set.
-2. Then we create a Python 3.5 environment with the `withPackages` function.
-3. The `withPackages` function expects us to provide a function as an argument that takes the set of all python packages and returns a list of packages to include in the environment. Here, we select the packages `numpy` and `toolz` from the package set.
-
-##### Execute command with `--run`
-A convenient option with `nix-shell` is the `--run`
-option, with which you can execute a command in the `nix-shell`. We can
-e.g. directly open a Python shell
-```sh
-$ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3"
-```
-or run a script
-```sh
-$ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3 myscript.py"
-```
-
-##### `nix-shell` as shebang
-In fact, for the second use case, there is a more convenient method. You can
-add a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) to your script
-specifying which dependencies `nix-shell` needs. With the following shebang, you
-can just execute `./myscript.py`, and it will make available all dependencies and
-run the script in the `python3` shell.
-
-```py
-#! /usr/bin/env nix-shell
-#! nix-shell -i python3 -p "python3.withPackages(ps: [ps.numpy])"
-
-import numpy
-
-print(numpy.__version__)
-```
-
-### Developing with Python
-
-Now that you know how to get a working Python environment with Nix, it is time
-to go forward and start actually developing with Python. We will first have a
-look at how Python packages are packaged on Nix. Then, we will look at how you
-can use development mode with your code.
-
-#### Packaging a library
-
-With Nix all packages are built by functions. The main function in Nix for
-building Python libraries is `buildPythonPackage`. Let's see how we can build the
-`toolz` package.
-
-```nix
-{ # ...
-
- toolz = buildPythonPackage rec {
- pname = "toolz";
- version = "0.7.4";
- name = "${pname}-${version}";
-
- src = fetchPypi {
- inherit pname version;
- sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
- };
-
- doCheck = false;
-
- meta = {
- homepage = "http://github.com/pytoolz/toolz/";
- description = "List processing tools and functional utilities";
- license = licenses.bsd3;
- maintainers = with maintainers; [ fridh ];
- };
- };
-}
-```
-
-What happens here? The function `buildPythonPackage` is called and as argument
-it accepts a set. In this case the set is a recursive set, `rec`. One of the
-arguments is the name of the package, which consists of a basename (generally
-following the name on PyPi) and a version. Another argument, `src` specifies the
-source, which in this case is fetched from PyPI using the helper function
-`fetchPypi`. The argument `doCheck` is used to set whether tests should be run
-when building the package. Furthermore, we specify some (optional) meta
-information. The output of the function is a derivation.
-
-An expression for `toolz` can be found in the Nixpkgs repository. As explained
-in the introduction of this Python section, a derivation of `toolz` is available
-for each interpreter version, e.g. `python35.pkgs.toolz` refers to the `toolz`
-derivation corresponding to the CPython 3.5 interpreter.
-The above example works when you're directly working on
-`pkgs/top-level/python-packages.nix` in the Nixpkgs repository. Often though,
-you will want to test a Nix expression outside of the Nixpkgs tree.
-
-The following expression creates a derivation for the `toolz` package,
-and adds it along with a `numpy` package to a Python environment.
-
-```nix
-with import {};
-
-( let
- my_toolz = python35.pkgs.buildPythonPackage rec {
- pname = "toolz";
- version = "0.7.4";
- name = "${pname}-${version}";
-
- src = python35.pkgs.fetchPypi {
- inherit pname version;
- sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
- };
-
- doCheck = false;
-
- meta = {
- homepage = "http://github.com/pytoolz/toolz/";
- description = "List processing tools and functional utilities";
- };
- };
-
- in python35.withPackages (ps: [ps.numpy my_toolz])
-).env
-```
-Executing `nix-shell` will result in an environment in which you can use
-Python 3.5 and the `toolz` package. As you can see we had to explicitly mention
-for which Python version we want to build a package.
-
-So, what did we do here? Well, we took the Nix expression that we used earlier
-to build a Python environment, and said that we wanted to include our own
-version of `toolz`, named `my_toolz`. To introduce our own package in the scope
-of `withPackages` we used a `let` expression. You can see that we used
-`ps.numpy` to select numpy from the nixpkgs package set (`ps`). We did not take
-`toolz` from the Nixpkgs package set this time, but instead took our own version
-that we introduced with the `let` expression.
-
-#### Handling dependencies
-
-Our example, `toolz`, does not have any dependencies on other Python
-packages or system libraries. According to the manual, `buildPythonPackage`
-uses the arguments `buildInputs` and `propagatedBuildInputs` to specify dependencies. If something is
-exclusively a build-time dependency, then the dependency should be included as a
-`buildInput`, but if it is (also) a runtime dependency, then it should be added
-to `propagatedBuildInputs`. Test dependencies are considered build-time dependencies.
-
-The following example shows which arguments are given to `buildPythonPackage` in
-order to build [`datashape`](https://github.com/blaze/datashape).
-
-```nix
-{ # ...
-
- datashape = buildPythonPackage rec {
- name = "datashape-${version}";
- version = "0.4.7";
-
- src = pkgs.fetchurl {
- url = "mirror://pypi/D/DataShape/${name}.tar.gz";
- sha256 = "14b2ef766d4c9652ab813182e866f493475e65e558bed0822e38bf07bba1a278";
- };
-
- buildInputs = with self; [ pytest ];
- propagatedBuildInputs = with self; [ numpy multipledispatch dateutil ];
-
- meta = {
- homepage = https://github.com/ContinuumIO/datashape;
- description = "A data description language";
- 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
-test runner and is only used during the `checkPhase` and is therefore not added
-to `propagatedBuildInputs`.
-
-In the previous case we had only dependencies on other Python packages to consider.
-Occasionally you have also system libraries to consider. E.g., `lxml` provides
-Python bindings to `libxml2` and `libxslt`. These libraries are only required
-when building the bindings and are therefore added as `buildInputs`.
-
-```nix
-{ # ...
-
- lxml = buildPythonPackage rec {
- name = "lxml-3.4.4";
-
- src = pkgs.fetchurl {
- url = "mirror://pypi/l/lxml/${name}.tar.gz";
- sha256 = "16a0fa97hym9ysdk3rmqz32xdjqmy4w34ld3rm3jf5viqjx65lxk";
- };
-
- buildInputs = with self; [ pkgs.libxml2 pkgs.libxslt ];
-
- meta = {
- description = "Pythonic binding for the libxml2 and libxslt libraries";
- homepage = http://lxml.de;
- license = licenses.bsd3;
- maintainers = with maintainers; [ sjourdois ];
- };
- };
-}
-```
-
-In this example `lxml` and Nix are able to work out exactly where the relevant
-files of the dependencies are. This is not always the case.
-
-The example below shows bindings to The Fastest Fourier Transform in the West, commonly known as
-FFTW. On Nix we have separate packages of FFTW for the different types of floats
-(`"single"`, `"double"`, `"long-double"`). The bindings need all three types,
-and therefore we add all three as `buildInputs`. The bindings don't expect to
-find each of them in a different folder, and therefore we have to set `LDFLAGS`
-and `CFLAGS`.
-
-```nix
-{ # ...
-
- pyfftw = buildPythonPackage rec {
- name = "pyfftw-${version}";
- version = "0.9.2";
-
- src = pkgs.fetchurl {
- url = "mirror://pypi/p/pyFFTW/pyFFTW-${version}.tar.gz";
- sha256 = "f6bbb6afa93085409ab24885a1a3cdb8909f095a142f4d49e346f2bd1b789074";
- };
-
- buildInputs = [ pkgs.fftw pkgs.fftwFloat pkgs.fftwLongDouble];
-
- propagatedBuildInputs = with self; [ numpy scipy ];
-
- # Tests cannot import pyfftw. pyfftw works fine though.
- doCheck = false;
-
- preConfigure = ''
- export LDFLAGS="-L${pkgs.fftw.dev}/lib -L${pkgs.fftwFloat.out}/lib -L${pkgs.fftwLongDouble.out}/lib"
- export CFLAGS="-I${pkgs.fftw.dev}/include -I${pkgs.fftwFloat.dev}/include -I${pkgs.fftwLongDouble.dev}/include"
- '';
-
- meta = {
- description = "A pythonic wrapper around FFTW, the FFT library, presenting a unified interface for all the supported transforms";
- homepage = http://hgomersall.github.com/pyFFTW/;
- license = with licenses; [ bsd2 bsd3 ];
- maintainer = with maintainers; [ fridh ];
- };
- };
-}
-```
-Note also the line `doCheck = false;`, we explicitly disabled running the test-suite.
-
-
-#### Develop local package
-
-As a Python developer you're likely aware of [development mode](http://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode) (`python setup.py develop`);
-instead of installing the package this command creates a special link to the project code.
-That way, you can run updated code without having to reinstall after each and every change you make.
-Development mode is also available. Let's see how you can use it.
-
-In the previous Nix expression the source was fetched from an url. We can also refer to a local source instead using
-`src = ./path/to/source/tree;`
-
-If we create a `shell.nix` file which calls `buildPythonPackage`, and if `src`
-is a local source, and if the local source has a `setup.py`, then development
-mode is activated.
-
-In the following example we create a simple environment that
-has a Python 3.5 version of our package in it, as well as its dependencies and
-other packages we like to have in the environment, all specified with `propagatedBuildInputs`.
-Indeed, we can just add any package we like to have in our environment to `propagatedBuildInputs`.
-
-```nix
-with import {};
-with pkgs.python35Packages;
-
-buildPythonPackage rec {
- name = "mypackage";
- src = ./path/to/package/source;
- propagatedBuildInputs = [ pytest numpy pkgs.libsndfile ];
-}
-```
-
-It is important to note that due to how development mode is implemented on Nix it is not possible to have multiple packages simultaneously in development mode.
-
-
-### Organising your packages
-
-So far we discussed how you can use Python on Nix, and how you can develop with
-it. We've looked at how you write expressions to package Python packages, and we
-looked at how you can create environments in which specified packages are
-available.
-
-At some point you'll likely have multiple packages which you would
-like to be able to use in different projects. In order to minimise unnecessary
-duplication we now look at how you can maintain yourself a repository with your
-own packages. The important functions here are `import` and `callPackage`.
-
-### Including a derivation using `callPackage`
-
-Earlier we created a Python environment using `withPackages`, and included the
-`toolz` package via a `let` expression.
-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
-{ pkgs, buildPythonPackage }:
-
-buildPythonPackage rec {
- name = "toolz-${version}";
- version = "0.7.4";
-
- src = pkgs.fetchurl {
- url = "mirror://pypi/t/toolz/toolz-${version}.tar.gz";
- sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
- };
-
- meta = {
- homepage = "http://github.com/pytoolz/toolz/";
- description = "List processing tools and functional utilities";
- license = licenses.bsd3;
- maintainers = with maintainers; [ fridh ];
- };
-}
-```
-
-It takes two arguments, `pkgs` and `buildPythonPackage`.
-We now call this function using `callPackage` in the definition of our environment
-
-```nix
-with import {};
-
-( let
- toolz = pkgs.callPackage /path/to/toolz/release.nix {
- pkgs = pkgs;
- buildPythonPackage = pkgs.python35Packages.buildPythonPackage;
- };
- in pkgs.python35.withPackages (ps: [ ps.numpy toolz ])
-).env
-```
-
-Important to remember is that the Python version for which the package is made
-depends on the `python` derivation that is passed to `buildPythonPackage`. Nix
-tries to automatically pass arguments when possible, which is why generally you
-don't explicitly define which `python` derivation should be used. In the above
-example we use `buildPythonPackage` that is part of the set `python35Packages`,
-and in this case the `python35` interpreter is automatically used.
-
-
-
-## Reference
-
-### Interpreters
-
-Versions 2.7, 3.3, 3.4, 3.5 and 3.6 of the CPython interpreter are available as
-respectively `python27`, `python34`, `python35` and `python36`. The PyPy interpreter
-is available as `pypy`. The aliases `python2` and `python3` correspond to respectively `python27` and
-`python35`. The default interpreter, `python`, maps to `python2`.
-The Nix expressions for the interpreters can be found in
-`pkgs/development/interpreters/python`.
-
-All packages depending on any Python interpreter get appended
-`out/{python.sitePackages}` to `$PYTHONPATH` if such directory
-exists.
-
-#### Missing `tkinter` module standard library
-
-To reduce closure size the `Tkinter`/`tkinter` is available as a separate package, `pythonPackages.tkinter`.
-
-#### Attributes on interpreters packages
-
-Each interpreter has the following attributes:
-
-- `libPrefix`. Name of the folder in `${python}/lib/` for corresponding interpreter.
-- `interpreter`. Alias for `${python}/bin/${executable}`.
-- `buildEnv`. Function to build python interpreter environments with extra packages bundled together. See section *python.buildEnv function* for usage and documentation.
-- `withPackages`. Simpler interface to `buildEnv`. See section *python.withPackages function* for usage and documentation.
-- `sitePackages`. Alias for `lib/${libPrefix}/site-packages`.
-- `executable`. Name of the interpreter executable, e.g. `python3.4`.
-- `pkgs`. Set of Python packages for that specific interpreter. The package set can be modified by overriding the interpreter and passing `packageOverrides`.
-
-### Building packages and applications
-
-Python libraries and applications that use `setuptools` or
-`distutils` are typically build 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
-applications elsewhere. In case a package is used as both a library and an application,
-then the package should be in `pkgs/top-level/python-packages.nix` since only those packages are made
-available for all interpreter versions. The preferred location for library expressions is in
-`pkgs/development/python-modules`. It is important that these packages are
-called from `pkgs/top-level/python-packages.nix` and not elsewhere, to guarantee
-the right version of the package is built.
-
-Based on the packages defined in `pkgs/top-level/python-packages.nix` an
-attribute set is created for each available Python interpreter. The available
-sets are
-
-* `pkgs.python27Packages`
-* `pkgs.python34Packages`
-* `pkgs.python35Packages`
-* `pkgs.python36Packages`
-* `pkgs.pypyPackages`
-
-and the aliases
-
-* `pkgs.python2Packages` pointing to `pkgs.python27Packages`
-* `pkgs.python3Packages` pointing to `pkgs.python36Packages`
-* `pkgs.pythonPackages` pointing to `pkgs.python2Packages`
-
-#### `buildPythonPackage` function
-
-The `buildPythonPackage` function is implemented in
-`pkgs/development/interpreters/python/build-python-package.nix`
-
-The following is an example:
-```nix
-{ # ...
-
- twisted = buildPythonPackage {
- name = "twisted-8.1.0";
-
- src = pkgs.fetchurl {
- url = http://tmrc.mit.edu/mirror/twisted/Twisted/8.1/Twisted-8.1.0.tar.bz2;
- sha256 = "0q25zbr4xzknaghha72mq57kh53qw1bf8csgp63pm9sfi72qhirl";
- };
-
- propagatedBuildInputs = [ self.ZopeInterface ];
-
- meta = {
- homepage = http://twistedmatrix.com/;
- description = "Twisted, an event-driven networking engine written in Python";
- license = stdenv.lib.licenses.mit;
- };
- };
-}
-```
-
-The `buildPythonPackage` mainly does four things:
-
-* In the `buildPhase`, it calls `${python.interpreter} setup.py bdist_wheel` to
- build a wheel binary zipfile.
-* In the `installPhase`, it installs the wheel file using `pip install *.whl`.
-* In the `postFixup` phase, the `wrapPythonPrograms` bash function is called to
- wrap all programs in the `$out/bin/*` directory to include `$PATH`
- 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’s (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 `buildInputs`.
-
-By default `meta.platforms` is set to the same value
-as the interpreter unless overridden otherwise.
-
-##### `buildPythonPackage` parameters
-
-All parameters from `mkDerivation` function are still supported.
-
-* `namePrefix`: Prepended text to `${name}` parameter. Defaults to `"python3.3-"` for Python 3.3, etc. Set it to `""` if you're packaging an application or a command line tool.
-* `disabled`: If `true`, package is not build for particular python interpreter version. Grep around `pkgs/top-level/python-packages.nix` for examples.
-* `setupPyBuildFlags`: List of flags passed to `setup.py build_ext` command.
-* `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`.
-* `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"]`.
-* `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`: Format of the source. Valid options are `setuptools` (default), `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. In case you need to provide your own `buildPhase` and `installPhase` you can use `other`.
-* `catchConflicts` 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`.
-
-##### Overriding Python packages
-
-The `buildPythonPackage` function has a `overridePythonAttrs` method that
-can be used to override the package. In the following example we create an
-environment where we have the `blaze` package using an older version of `pandas`.
-We override first the Python interpreter and pass
-`packageOverrides` which contains the overrides for packages in the package set.
-
-```nix
-with import {};
-
-(let
- python = let
- packageOverrides = self: super: {
- pandas = super.pandas.overridePythonAttrs(old: rec {
- version = "0.19.1";
- name = "pandas-${version}";
- src = super.fetchPypi {
- pname = "pandas";
- inherit version;
- sha256 = "08blshqj9zj1wyjhhw3kl2vas75vhhicvv72flvf1z3jvapgw295";
- };
- });
- };
- in pkgs.python3.override {inherit packageOverrides;};
-
-in python.withPackages(ps: [ps.blaze])).env
-```
-
-#### `buildPythonApplication` function
-
-The `buildPythonApplication` function is practically the same as `buildPythonPackage`.
-The difference is that `buildPythonPackage` by default prefixes the names of the packages with the version of the interpreter.
-Because with an application we're not interested in multiple version the prefix is dropped.
-
-#### python.buildEnv function
-
-Python environments can be created using the low-level `pkgs.buildEnv` function.
-This example shows how to create an environment that has the Pyramid Web Framework.
-Saving the following as `default.nix`
-```nix
-with import {};
-
-python.buildEnv.override {
- extraLibs = [ pkgs.pythonPackages.pyramid ];
- ignoreCollisions = true;
-}
-```
-
-and running `nix-build` will create
-```
-/nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env
-```
-
-with wrapped binaries in `bin/`.
-
-You can also use the `env` attribute to create local environments with needed
-packages installed. This is somewhat comparable to `virtualenv`. For example,
-running `nix-shell` with the following `shell.nix`
-```nix
-with import {};
-
-(python3.buildEnv.override {
- extraLibs = with python3Packages; [ numpy requests ];
-}).env
-```
-
-will drop you into a shell where Python will have the
-specified packages in its path.
-
-
-##### `python.buildEnv` arguments
-
-* `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`).
-
-#### python.withPackages function
-
-The `python.withPackages` function provides a simpler interface to the `python.buildEnv` functionality.
-It takes a function as an argument that is passed the set of python packages and returns the list
-of the packages to be included in the environment. Using the `withPackages` function, the previous
-example for the Pyramid Web Framework environment can be written like this:
-```nix
-with import {};
-
-python.withPackages (ps: [ps.pyramid])
-```
-
-`withPackages` passes the correct package set for the specific interpreter version as an
-argument to the function. In the above example, `ps` equals `pythonPackages`.
-But you can also easily switch to using python3:
-```nix
-with import {};
-
-python3.withPackages (ps: [ps.pyramid])
-```
-
-Now, `ps` is set to `python3Packages`, matching the version of the interpreter.
-
-As `python.withPackages` simply uses `python.buildEnv` under the hood, it also supports the `env`
-attribute. The `shell.nix` file from the previous section can thus be also written like this:
-```nix
-with import {};
-
-(python36.withPackages (ps: [ps.numpy ps.requests])).env
-```
-
-In contrast to `python.buildEnv`, `python.withPackages` does not support the more advanced options
-such as `ignoreCollisions = true` or `postBuild`. If you need them, you have to use `python.buildEnv`.
-
-Python 2 namespace packages may provide `__init__.py` that collide. In that case `python.buildEnv`
-should be used with `ignoreCollisions = true`.
-
-### Development mode
-
-Development or editable mode is supported. To develop Python packages
-`buildPythonPackage` has additional logic inside `shellPhase` to run `pip
-install -e . --prefix $TMPDIR/`for the package.
-
-Warning: `shellPhase` is executed only if `setup.py` exists.
-
-Given a `default.nix`:
-```nix
-with import {};
-
-buildPythonPackage { name = "myproject";
-
-buildInputs = with pkgs.pythonPackages; [ pyramid ];
-
-src = ./.; }
-```
-
-Running `nix-shell` with no arguments should give you
-the environment in which the package would be built with
-`nix-build`.
-
-Shortcut to setup environments with C headers/libraries and python packages:
-```shell
-nix-shell -p pythonPackages.pyramid zlib libjpeg git
-```
-
-Note: There is a boolean value `lib.inNixShell` set to `true` if nix-shell is invoked.
-
-### Tools
-
-Packages inside nixpkgs are written by hand. However many tools exist in
-community to help save time. No tool is preferred at the moment.
-
-- [python2nix](https://github.com/proger/python2nix) by Vladimir Kirillov
-- [pypi2nix](https://github.com/garbas/pypi2nix) by Rok Garbas
-- [pypi2nix](https://github.com/offlinehacker/pypi2nix) by Jaka Hudoklin
-
-### Deterministic builds
-
-Python 2.7, 3.5 and 3.6 are now built deterministically and 3.4 mostly.
-Minor modifications had to be made to the interpreters in order to generate
-deterministic bytecode. This has security implications and is relevant for
-those using Python in a `nix-shell`.
-
-When the environment variable `DETERMINISTIC_BUILD` is set, all bytecode will have timestamp 1.
-The `buildPythonPackage` function sets `DETERMINISTIC_BUILD=1` and
-[PYTHONHASHSEED=0](https://docs.python.org/3.5/using/cmdline.html#envvar-PYTHONHASHSEED).
-Both are also exported in `nix-shell`.
-
-
-### Automatic tests
-
-It is recommended to test packages as part of the build process.
-Source distributions (`sdist`) often include test files, but not always.
-
-By default the command `python setup.py test` is run as part of the
-`checkPhase`, but often it is necessary to pass a custom `checkPhase`. An
-example of such a situation is when `py.test` is used.
-
-#### Common issues
-
-- Non-working tests can often be deselected. By default `buildPythonPackage` runs `python setup.py test`.
- Most python modules follows the standard test protocol where the pytest runner can be used instead.
- `py.test` supports a `-k` parameter to ignore test methods or classes:
-
- ```nix
- buildPythonPackage {
- # ...
- # assumes the tests are located in tests
- checkInputs = [ pytest ];
- checkPhase = ''
- py.test -k 'not function_name and not other_function' tests
- '';
- }
- ```
-- 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
-
-### How to solve circular dependencies?
-
-Consider the packages `A` and `B` that depend on each other. When packaging `B`,
-a solution is to override package `A` not to depend on `B` as an input. The same
-should also be done when packaging `A`.
-
-### How to override a Python package?
-
-We can override the interpreter and pass `packageOverrides`.
-In the following example we rename the `pandas` package and build it.
-```nix
-with import {};
-
-(let
- python = let
- packageOverrides = self: super: {
- pandas = super.pandas.overridePythonAttrs(old: {name="foo";});
- };
- in pkgs.python35.override {inherit packageOverrides;};
-
-in python.withPackages(ps: [ps.pandas])).env
-```
-Using `nix-build` on this expression will build an environment that contains the
-package `pandas` but with the new name `foo`.
-
-All packages in the package set will use the renamed package.
-A typical use case is to switch to another version of a certain package.
-For example, in the Nixpkgs repository we have multiple versions of `django` and `scipy`.
-In the following example we use a different version of `scipy` and create an environment that uses it.
-All packages in the Python package set will now use the updated `scipy` version.
-
-```nix
-with import {};
-
-( let
- packageOverrides = self: super: {
- scipy = super.scipy_0_17;
- };
- in (pkgs.python35.override {inherit packageOverrides;}).withPackages (ps: [ps.blaze])
-).env
-```
-The requested package `blaze` depends on `pandas` which itself depends on `scipy`.
-
-If you want the whole of Nixpkgs to use your modifications, then you can use `overlays`
-as explained in this manual. In the following example we build a `inkscape` using a different version of `numpy`.
-```nix
-let
- pkgs = import {};
- newpkgs = import pkgs.path { overlays = [ (pkgsself: pkgssuper: {
- python27 = let
- packageOverrides = self: super: {
- numpy = super.numpy_1_10;
- };
- in pkgssuper.python27.override {inherit packageOverrides;};
- } ) ]; };
-in newpkgs.inkscape
-```
-
-### `python setup.py bdist_wheel` cannot create .whl
-
-Executing `python setup.py bdist_wheel` in a `nix-shell `fails with
-```
-ValueError: ZIP does not support timestamps before 1980
-```
-This is because files are included that depend on items in the Nix store which have a timestamp of, that is, it corresponds to January the 1st, 1970 at 00:00:00. And as the error informs you, ZIP does not support that.
-The command `bdist_wheel` takes into account `SOURCE_DATE_EPOCH`, and `nix-shell` sets this to 1. By setting it to a value corresponding to 1980 or later, or by unsetting it, it is possible to build wheels.
-
-Use 1980 as timestamp:
-```shell
-nix-shell --run "SOURCE_DATE_EPOCH=315532800 python3 setup.py bdist_wheel"
-```
-or the current time:
-```shell
-nix-shell --run "SOURCE_DATE_EPOCH=$(date +%s) python3 setup.py bdist_wheel"
-```
-or unset:
-```shell
-nix-shell --run "unset SOURCE_DATE_EPOCH; python3 setup.py bdist_wheel"
-```
-
-### `install_data` / `data_files` problems
-
-If you get the following error:
-```
-could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc':
-Permission denied
-```
-This is a [known bug](https://github.com/pypa/setuptools/issues/130) in `setuptools`.
-Setuptools `install_data` does not respect `--prefix`. An example of such package using the feature is `pkgs/tools/X11/xpra/default.nix`.
-As workaround install it as an extra `preInstall` step:
-```shell
-${python.interpreter} setup.py install_data --install-dir=$out --root=$out
-sed -i '/ = data\_files/d' setup.py
-```
-
-### Rationale of non-existent global site-packages
-
-On most operating systems a global `site-packages` is maintained. This however
-becomes problematic if you want to run multiple Python versions or have multiple
-versions of certain libraries for your projects. Generally, you would solve such
-issues by creating virtual environments using `virtualenv`.
-
-On Nix each package has an isolated dependency tree which, in the case of
-Python, guarantees the right versions of the interpreter and libraries or
-packages are available. There is therefore no need to maintain a global `site-packages`.
-
-If you want to create a Python environment for development, then the recommended
-method is to use `nix-shell`, either with or without the `python.buildEnv`
-function.
-
-### How to consume python modules using pip in a virtualenv like I am used to on other Operating Systems ?
-
-This is an example of a `default.nix` for a `nix-shell`, which allows to consume a `virtualenv` environment,
-and install python modules through `pip` the traditional way.
-
-Create this `default.nix` file, together with a `requirements.txt` and simply execute `nix-shell`.
-
-```nix
-with import {};
-with pkgs.python27Packages;
-
-stdenv.mkDerivation {
- name = "impurePythonEnv";
- buildInputs = [
- # these packages are required for virtualenv and pip to work:
- #
- python27Full
- python27Packages.virtualenv
- python27Packages.pip
- # the following packages are related to the dependencies of your python
- # project.
- # In this particular example the python modules listed in the
- # requirements.tx require the following packages to be installed locally
- # in order to compile any binary extensions they may require.
- #
- taglib
- openssl
- git
- libxml2
- libxslt
- libzip
- stdenv
- zlib ];
- src = null;
- shellHook = ''
- # set SOURCE_DATE_EPOCH so that we can use python wheels
- SOURCE_DATE_EPOCH=$(date +%s)
- virtualenv --no-setuptools venv
- export PATH=$PWD/venv/bin:$PATH
- pip install -r requirements.txt
- '';
-}
-```
-
-Note that the `pip install` is an imperative action. So every time `nix-shell`
-is executed it will attempt to download the python modules listed in
-requirements.txt. However these will be cached locally within the `virtualenv`
-folder and not downloaded again.
-
-### How to override a Python package from `configuration.nix`?
-
-If you need to change a package's attribute(s) from `configuration.nix` you could do:
-
-```nix
- nixpkgs.config.packageOverrides = superP: {
- pythonPackages = superP.pythonPackages.override {
- overrides = self: super: {
- bepasty-server = super.bepasty-server.overrideAttrs ( oldAttrs: {
- src = pkgs.fetchgit {
- url = "https://github.com/bepasty/bepasty-server";
- sha256 = "9ziqshmsf0rjvdhhca55sm0x8jz76fsf2q4rwh4m6lpcf8wr0nps";
- rev = "e2516e8cf4f2afb5185337073607eb9e84a61d2d";
- };
- });
- };
- };
- };
-```
-
-If you are using the `bepasty-server` package somewhere, for example in `systemPackages` or indirectly from `services.bepasty`, then a `nixos-rebuild switch` will rebuild the system but with the `bepasty-server` package using a different `src` attribute. This way one can modify `python` based software/libraries easily. Using `self` and `super` one can also alter dependencies (`buildInputs`) between the old state (`self`) and new state (`super`).
-
-### How to override a Python package using overlays?
-
-To alter a python package using overlays, you would use the following approach:
-
-```nix
-self: super:
-rec {
- python = super.python.override {
- packageOverrides = python-self: python-super: {
- bepasty-server = python-super.bepasty-server.overrideAttrs ( oldAttrs: {
- src = self.pkgs.fetchgit {
- url = "https://github.com/bepasty/bepasty-server";
- sha256 = "9ziqshmsf0rjvdhhca55sm0x8jz76fsf2q4rwh4m6lpcf8wr0nps";
- rev = "e2516e8cf4f2afb5185337073607eb9e84a61d2d";
- };
- });
- };
- };
- pythonPackages = python.pkgs;
-}
-```
-
-## Contributing
-
-### Contributing guidelines
-
-Following rules are desired to be respected:
-
-* Python libraries are called from `python-packages.nix` and packaged with `buildPythonPackage`. The expression of a library should be in `pkgs/development/python-modules//default.nix`. Libraries in `pkgs/top-level/python-packages.nix` are sorted quasi-alphabetically to avoid merge conflicts.
-* Python applications live outside of `python-packages.nix` and are packaged with `buildPythonApplication`.
-* Make sure libraries build for all Python interpreters.
-* By default we enable tests. Make sure the tests are found and, in the case of libraries, are passing for all interpreters. If certain tests fail they can be disabled individually. Try to avoid disabling the tests altogether. In any case, when you disable tests, leave a comment explaining why.
-* Commit names of Python libraries should reflect that they are Python libraries, so write for example `pythonPackages.numpy: 1.11 -> 1.12`.
-
diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md
new file mode 100644
index 000000000000..23ceb82eb31e
--- /dev/null
+++ b/doc/languages-frameworks/python.section.md
@@ -0,0 +1,1026 @@
+# Python
+
+## User Guide
+
+### Using Python
+
+#### Overview
+
+Several versions of the Python interpreter are available on Nix, as well as a
+high amount of packages. The attribute `python` refers to the default
+interpreter, which is currently CPython 2.7. It is also possible to refer to
+specific versions, e.g. `python35` refers to CPython 3.5, and `pypy` refers to
+the default PyPy interpreter.
+
+Python is used a lot, and in different ways. This affects also how it is
+packaged. In the case of Python on Nix, an important distinction is made between
+whether the package is considered primarily an application, or whether it should
+be used as a library, i.e., of primary interest are the modules in
+`site-packages` that should be importable.
+
+In the Nixpkgs tree Python applications can be found throughout, depending on
+what they do, and are called from the main package set. Python libraries,
+however, are in separate sets, with one set per interpreter version.
+
+The interpreters have several common attributes. One of these attributes is
+`pkgs`, which is a package set of Python libraries for this specific
+interpreter. E.g., the `toolz` package corresponding to the default interpreter
+is `python.pkgs.toolz`, and the CPython 3.5 version is `python35.pkgs.toolz`.
+The main package set contains aliases to these package sets, e.g.
+`pythonPackages` refers to `python.pkgs` and `python35Packages` to
+`python35.pkgs`.
+
+#### Installing Python and packages
+
+The Nix and NixOS manuals explain how packages are generally installed. In the
+case of Python and Nix, it is important to make a distinction between whether the
+package is considered an application or a library.
+
+Applications on Nix are typically installed into your user
+profile imperatively using `nix-env -i`, and on NixOS declaratively by adding the
+package name to `environment.systemPackages` in `/etc/nixos/configuration.nix`.
+Dependencies such as libraries are automatically installed and should not be
+installed explicitly.
+
+The same goes for Python applications and libraries. Python applications can be
+installed in your profile. But Python libraries you would like to use for
+development cannot be installed, at least not individually, because they won't
+be able to find each other resulting in import errors. Instead, it is possible
+to create an environment with `python.buildEnv` or `python.withPackages` where
+the interpreter and other executables are able to find each other and all of the
+modules.
+
+In the following examples we create an environment with Python 3.5, `numpy` and
+`toolz`. As you may imagine, there is one limitation here, and that's that
+you can install only one environment at a time. You will notice the complaints
+about collisions when you try to install a second environment.
+
+##### Environment defined in separate `.nix` file
+
+Create a file, e.g. `build.nix`, with the following expression
+```nix
+with import {};
+
+python35.withPackages (ps: with ps; [ numpy toolz ])
+```
+and install it in your profile with
+```shell
+nix-env -if build.nix
+```
+Now you can use the Python interpreter, as well as the extra packages (`numpy`,
+`toolz`) that you added to the environment.
+
+##### Environment defined in `~/.config/nixpkgs/config.nix`
+
+If you prefer to, you could also add the environment as a package override to the Nixpkgs set, e.g.
+using `config.nix`,
+```nix
+{ # ...
+
+ packageOverrides = pkgs: with pkgs; {
+ myEnv = python35.withPackages (ps: with ps; [ numpy toolz ]);
+ };
+}
+```
+and install it in your profile with
+```shell
+nix-env -iA nixpkgs.myEnv
+```
+The environment is is installed by referring to the attribute, and considering
+the `nixpkgs` channel was used.
+
+##### Environment defined in `/etc/nixos/configuration.nix`
+
+For the sake of completeness, here's another example how to install the environment system-wide.
+
+```nix
+{ # ...
+
+ environment.systemPackages = with pkgs; [
+ (python35.withPackages(ps: with ps; [ numpy toolz ]))
+ ];
+}
+```
+
+#### Temporary Python environment with `nix-shell`
+
+The examples in the previous section showed how to install a Python environment
+into a profile. For development you may need to use multiple environments.
+`nix-shell` gives the possibility to temporarily load another environment, akin
+to `virtualenv`.
+
+There are two methods for loading a shell with Python packages. The first and recommended method
+is to create an environment with `python.buildEnv` or `python.withPackages` and load that. E.g.
+```sh
+$ nix-shell -p 'python35.withPackages(ps: with ps; [ numpy toolz ])'
+```
+opens a shell from which you can launch the interpreter
+```sh
+[nix-shell:~] python3
+```
+The other method, which is not recommended, does not create an environment and requires you to list the packages directly,
+
+```sh
+$ nix-shell -p python35.pkgs.numpy python35.pkgs.toolz
+```
+Again, it is possible to launch the interpreter from the shell.
+The Python interpreter has the attribute `pkgs` which contains all Python libraries for that specific interpreter.
+
+##### Load environment from `.nix` expression
+As explained in the Nix manual, `nix-shell` can also load an
+expression from a `.nix` file. Say we want to have Python 3.5, `numpy`
+and `toolz`, like before, in an environment. Consider a `shell.nix` file
+with
+```nix
+with import {};
+
+(python35.withPackages (ps: [ps.numpy ps.toolz])).env
+```
+Executing `nix-shell` gives you again a Nix shell from which you can run Python.
+
+What's happening here?
+
+1. We begin with importing the Nix Packages collections. `import ` imports the `` function, `{}` calls it and the `with` statement brings all attributes of `nixpkgs` in the local scope. These attributes form the main package set.
+2. Then we create a Python 3.5 environment with the `withPackages` function.
+3. The `withPackages` function expects us to provide a function as an argument that takes the set of all python packages and returns a list of packages to include in the environment. Here, we select the packages `numpy` and `toolz` from the package set.
+
+##### Execute command with `--run`
+A convenient option with `nix-shell` is the `--run`
+option, with which you can execute a command in the `nix-shell`. We can
+e.g. directly open a Python shell
+```sh
+$ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3"
+```
+or run a script
+```sh
+$ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3 myscript.py"
+```
+
+##### `nix-shell` as shebang
+In fact, for the second use case, there is a more convenient method. You can
+add a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) to your script
+specifying which dependencies `nix-shell` needs. With the following shebang, you
+can just execute `./myscript.py`, and it will make available all dependencies and
+run the script in the `python3` shell.
+
+```py
+#! /usr/bin/env nix-shell
+#! nix-shell -i python3 -p "python3.withPackages(ps: [ps.numpy])"
+
+import numpy
+
+print(numpy.__version__)
+```
+
+### Developing with Python
+
+Now that you know how to get a working Python environment with Nix, it is time
+to go forward and start actually developing with Python. We will first have a
+look at how Python packages are packaged on Nix. Then, we will look at how you
+can use development mode with your code.
+
+#### Packaging a library
+
+With Nix all packages are built by functions. The main function in Nix for
+building Python libraries is `buildPythonPackage`. Let's see how we can build the
+`toolz` package.
+
+```nix
+{ # ...
+
+ toolz = buildPythonPackage rec {
+ pname = "toolz";
+ version = "0.7.4";
+
+ src = fetchPypi {
+ inherit pname version;
+ sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
+ };
+
+ doCheck = false;
+
+ meta = {
+ homepage = "http://github.com/pytoolz/toolz/";
+ description = "List processing tools and functional utilities";
+ license = licenses.bsd3;
+ maintainers = with maintainers; [ fridh ];
+ };
+ };
+}
+```
+
+What happens here? The function `buildPythonPackage` is called and as argument
+it accepts a set. In this case the set is a recursive set, `rec`. One of the
+arguments is the name of the package, which consists of a basename (generally
+following the name on PyPi) and a version. Another argument, `src` specifies the
+source, which in this case is fetched from PyPI using the helper function
+`fetchPypi`. The argument `doCheck` is used to set whether tests should be run
+when building the package. Furthermore, we specify some (optional) meta
+information. The output of the function is a derivation.
+
+An expression for `toolz` can be found in the Nixpkgs repository. As explained
+in the introduction of this Python section, a derivation of `toolz` is available
+for each interpreter version, e.g. `python35.pkgs.toolz` refers to the `toolz`
+derivation corresponding to the CPython 3.5 interpreter.
+The above example works when you're directly working on
+`pkgs/top-level/python-packages.nix` in the Nixpkgs repository. Often though,
+you will want to test a Nix expression outside of the Nixpkgs tree.
+
+The following expression creates a derivation for the `toolz` package,
+and adds it along with a `numpy` package to a Python environment.
+
+```nix
+with import {};
+
+( let
+ my_toolz = python35.pkgs.buildPythonPackage rec {
+ pname = "toolz";
+ version = "0.7.4";
+
+ src = python35.pkgs.fetchPypi {
+ inherit pname version;
+ sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
+ };
+
+ doCheck = false;
+
+ meta = {
+ homepage = "http://github.com/pytoolz/toolz/";
+ description = "List processing tools and functional utilities";
+ };
+ };
+
+ in python35.withPackages (ps: [ps.numpy my_toolz])
+).env
+```
+Executing `nix-shell` will result in an environment in which you can use
+Python 3.5 and the `toolz` package. As you can see we had to explicitly mention
+for which Python version we want to build a package.
+
+So, what did we do here? Well, we took the Nix expression that we used earlier
+to build a Python environment, and said that we wanted to include our own
+version of `toolz`, named `my_toolz`. To introduce our own package in the scope
+of `withPackages` we used a `let` expression. You can see that we used
+`ps.numpy` to select numpy from the nixpkgs package set (`ps`). We did not take
+`toolz` from the Nixpkgs package set this time, but instead took our own version
+that we introduced with the `let` expression.
+
+#### Handling dependencies
+
+Our example, `toolz`, does not have any dependencies on other Python
+packages or system libraries. According to the manual, `buildPythonPackage`
+uses the arguments `buildInputs` and `propagatedBuildInputs` to specify dependencies. If something is
+exclusively a build-time dependency, then the dependency should be included as a
+`buildInput`, but if it is (also) a runtime dependency, then it should be added
+to `propagatedBuildInputs`. Test dependencies are considered build-time dependencies.
+
+The following example shows which arguments are given to `buildPythonPackage` in
+order to build [`datashape`](https://github.com/blaze/datashape).
+
+```nix
+{ # ...
+
+ datashape = buildPythonPackage rec {
+ pname = "datashape";
+ version = "0.4.7";
+
+ src = fetchPypi {
+ inherit pname version;
+ sha256 = "14b2ef766d4c9652ab813182e866f493475e65e558bed0822e38bf07bba1a278";
+ };
+
+ checkInputs = with self; [ pytest ];
+ propagatedBuildInputs = with self; [ numpy multipledispatch dateutil ];
+
+ meta = {
+ homepage = https://github.com/ContinuumIO/datashape;
+ description = "A data description language";
+ 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
+test runner and is only used during the `checkPhase` and is therefore not added
+to `propagatedBuildInputs`.
+
+In the previous case we had only dependencies on other Python packages to consider.
+Occasionally you have also system libraries to consider. E.g., `lxml` provides
+Python bindings to `libxml2` and `libxslt`. These libraries are only required
+when building the bindings and are therefore added as `buildInputs`.
+
+```nix
+{ # ...
+
+ lxml = buildPythonPackage rec {
+ pname = "lxml";
+ version = "3.4.4";
+
+ src = fetchPypi {
+ inherit pname version;
+ sha256 = "16a0fa97hym9ysdk3rmqz32xdjqmy4w34ld3rm3jf5viqjx65lxk";
+ };
+
+ buildInputs = with self; [ pkgs.libxml2 pkgs.libxslt ];
+
+ meta = {
+ description = "Pythonic binding for the libxml2 and libxslt libraries";
+ homepage = http://lxml.de;
+ license = licenses.bsd3;
+ maintainers = with maintainers; [ sjourdois ];
+ };
+ };
+}
+```
+
+In this example `lxml` and Nix are able to work out exactly where the relevant
+files of the dependencies are. This is not always the case.
+
+The example below shows bindings to The Fastest Fourier Transform in the West, commonly known as
+FFTW. On Nix we have separate packages of FFTW for the different types of floats
+(`"single"`, `"double"`, `"long-double"`). The bindings need all three types,
+and therefore we add all three as `buildInputs`. The bindings don't expect to
+find each of them in a different folder, and therefore we have to set `LDFLAGS`
+and `CFLAGS`.
+
+```nix
+{ # ...
+
+ pyfftw = buildPythonPackage rec {
+ pname = "pyFFTW";
+ version = "0.9.2";
+
+ src = fetchPypi {
+ inherit pname version;
+ sha256 = "f6bbb6afa93085409ab24885a1a3cdb8909f095a142f4d49e346f2bd1b789074";
+ };
+
+ buildInputs = [ pkgs.fftw pkgs.fftwFloat pkgs.fftwLongDouble];
+
+ propagatedBuildInputs = with self; [ numpy scipy ];
+
+ # Tests cannot import pyfftw. pyfftw works fine though.
+ doCheck = false;
+
+ preConfigure = ''
+ export LDFLAGS="-L${pkgs.fftw.dev}/lib -L${pkgs.fftwFloat.out}/lib -L${pkgs.fftwLongDouble.out}/lib"
+ export CFLAGS="-I${pkgs.fftw.dev}/include -I${pkgs.fftwFloat.dev}/include -I${pkgs.fftwLongDouble.dev}/include"
+ '';
+
+ meta = {
+ description = "A pythonic wrapper around FFTW, the FFT library, presenting a unified interface for all the supported transforms";
+ homepage = http://hgomersall.github.com/pyFFTW/;
+ license = with licenses; [ bsd2 bsd3 ];
+ maintainers = with maintainers; [ fridh ];
+ };
+ };
+}
+```
+Note also the line `doCheck = false;`, we explicitly disabled running the test-suite.
+
+
+#### Develop local package
+
+As a Python developer you're likely aware of [development mode](http://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode) (`python setup.py develop`);
+instead of installing the package this command creates a special link to the project code.
+That way, you can run updated code without having to reinstall after each and every change you make.
+Development mode is also available. Let's see how you can use it.
+
+In the previous Nix expression the source was fetched from an url. We can also refer to a local source instead using
+`src = ./path/to/source/tree;`
+
+If we create a `shell.nix` file which calls `buildPythonPackage`, and if `src`
+is a local source, and if the local source has a `setup.py`, then development
+mode is activated.
+
+In the following example we create a simple environment that
+has a Python 3.5 version of our package in it, as well as its dependencies and
+other packages we like to have in the environment, all specified with `propagatedBuildInputs`.
+Indeed, we can just add any package we like to have in our environment to `propagatedBuildInputs`.
+
+```nix
+with import {};
+with pkgs.python35Packages;
+
+buildPythonPackage rec {
+ name = "mypackage";
+ src = ./path/to/package/source;
+ propagatedBuildInputs = [ pytest numpy pkgs.libsndfile ];
+}
+```
+
+It is important to note that due to how development mode is implemented on Nix it is not possible to have multiple packages simultaneously in development mode.
+
+
+### Organising your packages
+
+So far we discussed how you can use Python on Nix, and how you can develop with
+it. We've looked at how you write expressions to package Python packages, and we
+looked at how you can create environments in which specified packages are
+available.
+
+At some point you'll likely have multiple packages which you would
+like to be able to use in different projects. In order to minimise unnecessary
+duplication we now look at how you can maintain yourself a repository with your
+own packages. The important functions here are `import` and `callPackage`.
+
+### Including a derivation using `callPackage`
+
+Earlier we created a Python environment using `withPackages`, and included the
+`toolz` package via a `let` expression.
+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
+{ pkgs, buildPythonPackage }:
+
+buildPythonPackage rec {
+ pname = "toolz";
+ version = "0.7.4";
+
+ src = fetchPypi {
+ inherit pname version;
+ sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
+ };
+
+ meta = {
+ homepage = "http://github.com/pytoolz/toolz/";
+ description = "List processing tools and functional utilities";
+ license = licenses.bsd3;
+ maintainers = with maintainers; [ fridh ];
+ };
+}
+```
+
+It takes two arguments, `pkgs` and `buildPythonPackage`.
+We now call this function using `callPackage` in the definition of our environment
+
+```nix
+with import {};
+
+( let
+ toolz = pkgs.callPackage /path/to/toolz/release.nix {
+ pkgs = pkgs;
+ buildPythonPackage = pkgs.python35Packages.buildPythonPackage;
+ };
+ in pkgs.python35.withPackages (ps: [ ps.numpy toolz ])
+).env
+```
+
+Important to remember is that the Python version for which the package is made
+depends on the `python` derivation that is passed to `buildPythonPackage`. Nix
+tries to automatically pass arguments when possible, which is why generally you
+don't explicitly define which `python` derivation should be used. In the above
+example we use `buildPythonPackage` that is part of the set `python35Packages`,
+and in this case the `python35` interpreter is automatically used.
+
+
+
+## Reference
+
+### Interpreters
+
+Versions 2.7, 3.3, 3.4, 3.5 and 3.6 of the CPython interpreter are available as
+respectively `python27`, `python34`, `python35` and `python36`. The PyPy interpreter
+is available as `pypy`. The aliases `python2` and `python3` correspond to respectively `python27` and
+`python35`. The default interpreter, `python`, maps to `python2`.
+The Nix expressions for the interpreters can be found in
+`pkgs/development/interpreters/python`.
+
+All packages depending on any Python interpreter get appended
+`out/{python.sitePackages}` to `$PYTHONPATH` if such directory
+exists.
+
+#### Missing `tkinter` module standard library
+
+To reduce closure size the `Tkinter`/`tkinter` is available as a separate package, `pythonPackages.tkinter`.
+
+#### Attributes on interpreters packages
+
+Each interpreter has the following attributes:
+
+- `libPrefix`. Name of the folder in `${python}/lib/` for corresponding interpreter.
+- `interpreter`. Alias for `${python}/bin/${executable}`.
+- `buildEnv`. Function to build python interpreter environments with extra packages bundled together. See section *python.buildEnv function* for usage and documentation.
+- `withPackages`. Simpler interface to `buildEnv`. See section *python.withPackages function* for usage and documentation.
+- `sitePackages`. Alias for `lib/${libPrefix}/site-packages`.
+- `executable`. Name of the interpreter executable, e.g. `python3.4`.
+- `pkgs`. Set of Python packages for that specific interpreter. The package set can be modified by overriding the interpreter and passing `packageOverrides`.
+
+### Building packages and applications
+
+Python libraries and applications that use `setuptools` or
+`distutils` are typically build 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
+applications elsewhere. In case a package is used as both a library and an application,
+then the package should be in `pkgs/top-level/python-packages.nix` since only those packages are made
+available for all interpreter versions. The preferred location for library expressions is in
+`pkgs/development/python-modules`. It is important that these packages are
+called from `pkgs/top-level/python-packages.nix` and not elsewhere, to guarantee
+the right version of the package is built.
+
+Based on the packages defined in `pkgs/top-level/python-packages.nix` an
+attribute set is created for each available Python interpreter. The available
+sets are
+
+* `pkgs.python27Packages`
+* `pkgs.python34Packages`
+* `pkgs.python35Packages`
+* `pkgs.python36Packages`
+* `pkgs.pypyPackages`
+
+and the aliases
+
+* `pkgs.python2Packages` pointing to `pkgs.python27Packages`
+* `pkgs.python3Packages` pointing to `pkgs.python36Packages`
+* `pkgs.pythonPackages` pointing to `pkgs.python2Packages`
+
+#### `buildPythonPackage` function
+
+The `buildPythonPackage` function is implemented in
+`pkgs/development/interpreters/python/build-python-package.nix`
+
+The following is an example:
+```nix
+
+buildPythonPackage rec {
+ version = "3.3.1";
+ pname = "pytest";
+
+ preCheck = ''
+ # don't test bash builtins
+ rm testing/test_argcomplete.py
+ '';
+
+ src = fetchPypi {
+ inherit pname version;
+ sha256 = "cf8436dc59d8695346fcd3ab296de46425ecab00d64096cebe79fb51ecb2eb93";
+ };
+
+ checkInputs = [ hypothesis ];
+ buildInputs = [ setuptools_scm ];
+ propagatedBuildInputs = [ attrs py setuptools six pluggy ];
+
+ meta = with stdenv.lib; {
+ maintainers = with maintainers; [ domenkozar lovek323 madjar lsix ];
+ description = "Framework for writing tests";
+ };
+}
+
+```
+
+The `buildPythonPackage` mainly does four things:
+
+* In the `buildPhase`, it calls `${python.interpreter} setup.py bdist_wheel` to
+ build a wheel binary zipfile.
+* In the `installPhase`, it installs the wheel file using `pip install *.whl`.
+* In the `postFixup` phase, the `wrapPythonPrograms` bash function is called to
+ wrap all programs in the `$out/bin/*` directory to include `$PATH`
+ 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’s (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 `buildInputs`.
+
+By default `meta.platforms` is set to the same value
+as the interpreter unless overridden otherwise.
+
+##### `buildPythonPackage` parameters
+
+All parameters from `mkDerivation` function are still supported.
+
+* `namePrefix`: Prepended text to `${name}` parameter. Defaults to `"python3.3-"` for Python 3.3, etc. Set it to `""` if you're packaging an application or a command line tool.
+* `disabled`: If `true`, package is not build for particular python interpreter version. Grep around `pkgs/top-level/python-packages.nix` for examples.
+* `setupPyBuildFlags`: List of flags passed to `setup.py build_ext` command.
+* `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`.
+* `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"]`.
+* `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`: Format of the source. Valid options are `setuptools` (default), `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. In case you need to provide your own `buildPhase` and `installPhase` you can use `other`.
+* `catchConflicts` 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`.
+
+##### Overriding Python packages
+
+The `buildPythonPackage` function has a `overridePythonAttrs` method that
+can be used to override the package. In the following example we create an
+environment where we have the `blaze` package using an older version of `pandas`.
+We override first the Python interpreter and pass
+`packageOverrides` which contains the overrides for packages in the package set.
+
+```nix
+with import {};
+
+(let
+ python = let
+ packageOverrides = self: super: {
+ pandas = super.pandas.overridePythonAttrs(old: rec {
+ version = "0.19.1";
+ src = super.fetchPypi {
+ pname = "pandas";
+ inherit version;
+ sha256 = "08blshqj9zj1wyjhhw3kl2vas75vhhicvv72flvf1z3jvapgw295";
+ };
+ });
+ };
+ in pkgs.python3.override {inherit packageOverrides;};
+
+in python.withPackages(ps: [ps.blaze])).env
+```
+
+#### `buildPythonApplication` function
+
+The `buildPythonApplication` function is practically the same as `buildPythonPackage`.
+The difference is that `buildPythonPackage` by default prefixes the names of the packages with the version of the interpreter.
+Because with an application we're not interested in multiple version the prefix is dropped.
+
+#### python.buildEnv function
+
+Python environments can be created using the low-level `pkgs.buildEnv` function.
+This example shows how to create an environment that has the Pyramid Web Framework.
+Saving the following as `default.nix`
+```nix
+with import {};
+
+python.buildEnv.override {
+ extraLibs = [ pkgs.pythonPackages.pyramid ];
+ ignoreCollisions = true;
+}
+```
+
+and running `nix-build` will create
+```
+/nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env
+```
+
+with wrapped binaries in `bin/`.
+
+You can also use the `env` attribute to create local environments with needed
+packages installed. This is somewhat comparable to `virtualenv`. For example,
+running `nix-shell` with the following `shell.nix`
+```nix
+with import {};
+
+(python3.buildEnv.override {
+ extraLibs = with python3Packages; [ numpy requests ];
+}).env
+```
+
+will drop you into a shell where Python will have the
+specified packages in its path.
+
+
+##### `python.buildEnv` arguments
+
+* `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`).
+
+#### python.withPackages function
+
+The `python.withPackages` function provides a simpler interface to the `python.buildEnv` functionality.
+It takes a function as an argument that is passed the set of python packages and returns the list
+of the packages to be included in the environment. Using the `withPackages` function, the previous
+example for the Pyramid Web Framework environment can be written like this:
+```nix
+with import {};
+
+python.withPackages (ps: [ps.pyramid])
+```
+
+`withPackages` passes the correct package set for the specific interpreter version as an
+argument to the function. In the above example, `ps` equals `pythonPackages`.
+But you can also easily switch to using python3:
+```nix
+with import {};
+
+python3.withPackages (ps: [ps.pyramid])
+```
+
+Now, `ps` is set to `python3Packages`, matching the version of the interpreter.
+
+As `python.withPackages` simply uses `python.buildEnv` under the hood, it also supports the `env`
+attribute. The `shell.nix` file from the previous section can thus be also written like this:
+```nix
+with import {};
+
+(python36.withPackages (ps: [ps.numpy ps.requests])).env
+```
+
+In contrast to `python.buildEnv`, `python.withPackages` does not support the more advanced options
+such as `ignoreCollisions = true` or `postBuild`. If you need them, you have to use `python.buildEnv`.
+
+Python 2 namespace packages may provide `__init__.py` that collide. In that case `python.buildEnv`
+should be used with `ignoreCollisions = true`.
+
+### Development mode
+
+Development or editable mode is supported. To develop Python packages
+`buildPythonPackage` has additional logic inside `shellPhase` to run `pip
+install -e . --prefix $TMPDIR/`for the package.
+
+Warning: `shellPhase` is executed only if `setup.py` exists.
+
+Given a `default.nix`:
+```nix
+with import {};
+
+buildPythonPackage { name = "myproject";
+
+buildInputs = with pkgs.pythonPackages; [ pyramid ];
+
+src = ./.; }
+```
+
+Running `nix-shell` with no arguments should give you
+the environment in which the package would be built with
+`nix-build`.
+
+Shortcut to setup environments with C headers/libraries and python packages:
+```shell
+nix-shell -p pythonPackages.pyramid zlib libjpeg git
+```
+
+Note: There is a boolean value `lib.inNixShell` set to `true` if nix-shell is invoked.
+
+### Tools
+
+Packages inside nixpkgs are written by hand. However many tools exist in
+community to help save time. No tool is preferred at the moment.
+
+- [python2nix](https://github.com/proger/python2nix) by Vladimir Kirillov
+- [pypi2nix](https://github.com/garbas/pypi2nix) by Rok Garbas
+- [pypi2nix](https://github.com/offlinehacker/pypi2nix) by Jaka Hudoklin
+
+### Deterministic builds
+
+Python 2.7, 3.5 and 3.6 are now built deterministically and 3.4 mostly.
+Minor modifications had to be made to the interpreters in order to generate
+deterministic bytecode. This has security implications and is relevant for
+those using Python in a `nix-shell`.
+
+When the environment variable `DETERMINISTIC_BUILD` is set, all bytecode will have timestamp 1.
+The `buildPythonPackage` function sets `DETERMINISTIC_BUILD=1` and
+[PYTHONHASHSEED=0](https://docs.python.org/3.5/using/cmdline.html#envvar-PYTHONHASHSEED).
+Both are also exported in `nix-shell`.
+
+
+### Automatic tests
+
+It is recommended to test packages as part of the build process.
+Source distributions (`sdist`) often include test files, but not always.
+
+By default the command `python setup.py test` is run as part of the
+`checkPhase`, but often it is necessary to pass a custom `checkPhase`. An
+example of such a situation is when `py.test` is used.
+
+#### Common issues
+
+- Non-working tests can often be deselected. By default `buildPythonPackage` runs `python setup.py test`.
+ Most python modules follows the standard test protocol where the pytest runner can be used instead.
+ `py.test` supports a `-k` parameter to ignore test methods or classes:
+
+ ```nix
+ buildPythonPackage {
+ # ...
+ # assumes the tests are located in tests
+ checkInputs = [ pytest ];
+ checkPhase = ''
+ py.test -k 'not function_name and not other_function' tests
+ '';
+ }
+ ```
+- 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
+
+### How to solve circular dependencies?
+
+Consider the packages `A` and `B` that depend on each other. When packaging `B`,
+a solution is to override package `A` not to depend on `B` as an input. The same
+should also be done when packaging `A`.
+
+### How to override a Python package?
+
+We can override the interpreter and pass `packageOverrides`.
+In the following example we rename the `pandas` package and build it.
+```nix
+with import {};
+
+(let
+ python = let
+ packageOverrides = self: super: {
+ pandas = super.pandas.overridePythonAttrs(old: {name="foo";});
+ };
+ in pkgs.python35.override {inherit packageOverrides;};
+
+in python.withPackages(ps: [ps.pandas])).env
+```
+Using `nix-build` on this expression will build an environment that contains the
+package `pandas` but with the new name `foo`.
+
+All packages in the package set will use the renamed package.
+A typical use case is to switch to another version of a certain package.
+For example, in the Nixpkgs repository we have multiple versions of `django` and `scipy`.
+In the following example we use a different version of `scipy` and create an environment that uses it.
+All packages in the Python package set will now use the updated `scipy` version.
+
+```nix
+with import {};
+
+( let
+ packageOverrides = self: super: {
+ scipy = super.scipy_0_17;
+ };
+ in (pkgs.python35.override {inherit packageOverrides;}).withPackages (ps: [ps.blaze])
+).env
+```
+The requested package `blaze` depends on `pandas` which itself depends on `scipy`.
+
+If you want the whole of Nixpkgs to use your modifications, then you can use `overlays`
+as explained in this manual. In the following example we build a `inkscape` using a different version of `numpy`.
+```nix
+let
+ pkgs = import {};
+ newpkgs = import pkgs.path { overlays = [ (pkgsself: pkgssuper: {
+ python27 = let
+ packageOverrides = self: super: {
+ numpy = super.numpy_1_10;
+ };
+ in pkgssuper.python27.override {inherit packageOverrides;};
+ } ) ]; };
+in newpkgs.inkscape
+```
+
+### `python setup.py bdist_wheel` cannot create .whl
+
+Executing `python setup.py bdist_wheel` in a `nix-shell `fails with
+```
+ValueError: ZIP does not support timestamps before 1980
+```
+
+This is because files from the Nix store (which have a timestamp of the UNIX epoch of January 1, 1970) are included in the .ZIP, but .ZIP archives follow the DOS convention of counting timestamps from 1980.
+
+The command `bdist_wheel` reads the `SOURCE_DATE_EPOCH` environment variable, which `nix-shell` sets to 1. Unsetting this variable or giving it a value corresponding to 1980 or later enables building wheels.
+
+Use 1980 as timestamp:
+```shell
+nix-shell --run "SOURCE_DATE_EPOCH=315532800 python3 setup.py bdist_wheel"
+```
+or the current time:
+```shell
+nix-shell --run "SOURCE_DATE_EPOCH=$(date +%s) python3 setup.py bdist_wheel"
+```
+or unset `SOURCE_DATE_EPOCH`:
+```shell
+nix-shell --run "unset SOURCE_DATE_EPOCH; python3 setup.py bdist_wheel"
+```
+
+### `install_data` / `data_files` problems
+
+If you get the following error:
+```
+could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc':
+Permission denied
+```
+This is a [known bug](https://github.com/pypa/setuptools/issues/130) in `setuptools`.
+Setuptools `install_data` does not respect `--prefix`. An example of such package using the feature is `pkgs/tools/X11/xpra/default.nix`.
+As workaround install it as an extra `preInstall` step:
+```shell
+${python.interpreter} setup.py install_data --install-dir=$out --root=$out
+sed -i '/ = data\_files/d' setup.py
+```
+
+### Rationale of non-existent global site-packages
+
+On most operating systems a global `site-packages` is maintained. This however
+becomes problematic if you want to run multiple Python versions or have multiple
+versions of certain libraries for your projects. Generally, you would solve such
+issues by creating virtual environments using `virtualenv`.
+
+On Nix each package has an isolated dependency tree which, in the case of
+Python, guarantees the right versions of the interpreter and libraries or
+packages are available. There is therefore no need to maintain a global `site-packages`.
+
+If you want to create a Python environment for development, then the recommended
+method is to use `nix-shell`, either with or without the `python.buildEnv`
+function.
+
+### How to consume python modules using pip in a virtualenv like I am used to on other Operating Systems ?
+
+This is an example of a `default.nix` for a `nix-shell`, which allows to consume a `virtualenv` environment,
+and install python modules through `pip` the traditional way.
+
+Create this `default.nix` file, together with a `requirements.txt` and simply execute `nix-shell`.
+
+```nix
+with import {};
+with pkgs.python27Packages;
+
+stdenv.mkDerivation {
+ name = "impurePythonEnv";
+ buildInputs = [
+ # these packages are required for virtualenv and pip to work:
+ #
+ python27Full
+ python27Packages.virtualenv
+ python27Packages.pip
+ # the following packages are related to the dependencies of your python
+ # project.
+ # In this particular example the python modules listed in the
+ # requirements.tx require the following packages to be installed locally
+ # in order to compile any binary extensions they may require.
+ #
+ taglib
+ openssl
+ git
+ libxml2
+ libxslt
+ libzip
+ stdenv
+ zlib ];
+ src = null;
+ shellHook = ''
+ # set SOURCE_DATE_EPOCH so that we can use python wheels
+ SOURCE_DATE_EPOCH=$(date +%s)
+ virtualenv --no-setuptools venv
+ export PATH=$PWD/venv/bin:$PATH
+ pip install -r requirements.txt
+ '';
+}
+```
+
+Note that the `pip install` is an imperative action. So every time `nix-shell`
+is executed it will attempt to download the python modules listed in
+requirements.txt. However these will be cached locally within the `virtualenv`
+folder and not downloaded again.
+
+### How to override a Python package from `configuration.nix`?
+
+If you need to change a package's attribute(s) from `configuration.nix` you could do:
+
+```nix
+ nixpkgs.config.packageOverrides = superP: {
+ pythonPackages = superP.pythonPackages.override {
+ overrides = self: super: {
+ bepasty-server = super.bepasty-server.overrideAttrs ( oldAttrs: {
+ src = pkgs.fetchgit {
+ url = "https://github.com/bepasty/bepasty-server";
+ sha256 = "9ziqshmsf0rjvdhhca55sm0x8jz76fsf2q4rwh4m6lpcf8wr0nps";
+ rev = "e2516e8cf4f2afb5185337073607eb9e84a61d2d";
+ };
+ });
+ };
+ };
+ };
+```
+
+If you are using the `bepasty-server` package somewhere, for example in `systemPackages` or indirectly from `services.bepasty`, then a `nixos-rebuild switch` will rebuild the system but with the `bepasty-server` package using a different `src` attribute. This way one can modify `python` based software/libraries easily. Using `self` and `super` one can also alter dependencies (`buildInputs`) between the old state (`self`) and new state (`super`).
+
+### How to override a Python package using overlays?
+
+To alter a python package using overlays, you would use the following approach:
+
+```nix
+self: super:
+rec {
+ python = super.python.override {
+ packageOverrides = python-self: python-super: {
+ bepasty-server = python-super.bepasty-server.overrideAttrs ( oldAttrs: {
+ src = self.pkgs.fetchgit {
+ url = "https://github.com/bepasty/bepasty-server";
+ sha256 = "9ziqshmsf0rjvdhhca55sm0x8jz76fsf2q4rwh4m6lpcf8wr0nps";
+ rev = "e2516e8cf4f2afb5185337073607eb9e84a61d2d";
+ };
+ });
+ };
+ };
+ pythonPackages = python.pkgs;
+}
+```
+
+## Contributing
+
+### Contributing guidelines
+
+Following rules are desired to be respected:
+
+* Python libraries are called from `python-packages.nix` and packaged with `buildPythonPackage`. The expression of a library should be in `pkgs/development/python-modules//default.nix`. Libraries in `pkgs/top-level/python-packages.nix` are sorted quasi-alphabetically to avoid merge conflicts.
+* Python applications live outside of `python-packages.nix` and are packaged with `buildPythonApplication`.
+* Make sure libraries build for all Python interpreters.
+* By default we enable tests. Make sure the tests are found and, in the case of libraries, are passing for all interpreters. If certain tests fail they can be disabled individually. Try to avoid disabling the tests altogether. In any case, when you disable tests, leave a comment explaining why.
+* Commit names of Python libraries should reflect that they are Python libraries, so write for example `pythonPackages.numpy: 1.11 -> 1.12`.
+
diff --git a/doc/languages-frameworks/r.section.md b/doc/languages-frameworks/r.section.md
new file mode 100644
index 000000000000..c8f02bd14780
--- /dev/null
+++ b/doc/languages-frameworks/r.section.md
@@ -0,0 +1,120 @@
+R packages
+==========
+
+## Installation
+
+Define an environment for R that contains all the libraries that you'd like to
+use by adding the following snippet to your $HOME/.config/nixpkgs/config.nix file:
+
+```nix
+{
+ packageOverrides = super: let self = super.pkgs; in
+ {
+
+ rEnv = super.rWrapper.override {
+ packages = with self.rPackages; [
+ devtools
+ ggplot2
+ reshape2
+ yaml
+ optparse
+ ];
+ };
+ };
+}
+```
+
+Then you can use `nix-env -f "" -iA rEnv` to install it into your user
+profile. The set of available libraries can be discovered by running the
+command `nix-env -f "" -qaP -A rPackages`. The first column from that
+output is the name that has to be passed to rWrapper in the code snipped above.
+
+However, if you'd like to add a file to your project source to make the
+environment available for other contributors, you can create a `default.nix`
+file like so:
+```nix
+let
+ pkgs = import {};
+ stdenv = pkgs.stdenv;
+in with pkgs; {
+ myProject = stdenv.mkDerivation {
+ name = "myProject";
+ version = "1";
+ src = if pkgs.lib.inNixShell then null else nix;
+
+ buildInputs = with rPackages; [
+ R
+ ggplot2
+ knitr
+ ];
+ };
+}
+```
+and then run `nix-shell .` to be dropped into a shell with those packages
+available.
+
+## RStudio
+
+RStudio uses a standard set of packages and ignores any custom R
+environments or installed packages you may have. To create a custom
+environment, see `rstudioWrapper`, which functions similarly to
+`rWrapper`:
+
+```nix
+{
+ packageOverrides = super: let self = super.pkgs; in
+ {
+
+ rstudioEnv = super.rstudioWrapper.override {
+ packages = with self.rPackages; [
+ dplyr
+ ggplot2
+ reshape2
+ ];
+ };
+ };
+}
+```
+
+Then like above, `nix-env -f "" -iA rstudioEnv` will install
+this into your user profile.
+
+Alternatively, you can create a self-contained `shell.nix` without the need to
+modify any configuration files:
+
+```nix
+{ pkgs ? import {}
+}:
+
+pkgs.rstudioWrapper.override {
+ packages = with pkgs.rPackages; [ dplyr ggplot2 reshape2 ];
+}
+
+```
+
+Executing `nix-shell` will then drop you into an environment equivalent to the
+one above. If you need additional packages just add them to the list and
+re-enter the shell.
+
+## Updating the package set
+
+```bash
+nix-shell generate-shell.nix
+
+Rscript generate-r-packages.R cran > cran-packages.nix.new
+mv cran-packages.nix.new cran-packages.nix
+
+Rscript generate-r-packages.R bioc > bioc-packages.nix.new
+mv bioc-packages.nix.new bioc-packages.nix
+```
+
+`generate-r-packages.R ` reads `-packages.nix`, therefor the renaming.
+
+
+## Testing if the Nix-expression could be evaluated
+
+```bash
+nix-build test-evaluation.nix --dry-run
+```
+
+If this exits fine, the expression is ok. If not, you have to edit `default.nix`
diff --git a/doc/languages-frameworks/rust.md b/doc/languages-frameworks/rust.md
deleted file mode 100644
index 7c6955af812b..000000000000
--- a/doc/languages-frameworks/rust.md
+++ /dev/null
@@ -1,88 +0,0 @@
----
-title: Rust
-author: Matthias Beyer
-date: 2017-03-05
----
-
-# User's Guide to the Rust Infrastructure
-
-To install the rust compiler and cargo put
-
-```
-rust
-```
-
-into the `environment.systemPackages` or bring them into
-scope with `nix-shell -p rust`.
-
-For daily builds (beta and nightly) use either rustup from
-nixpkgs or use the [Rust nightlies
-overlay](#using-the-rust-nightlies-overlay).
-
-## Packaging Rust applications
-
-Rust applications are packaged by using the `buildRustPackage` helper from `rustPlatform`:
-
-```
-rustPlatform.buildRustPackage rec {
- name = "ripgrep-${version}";
- version = "0.4.0";
-
- src = fetchFromGitHub {
- owner = "BurntSushi";
- repo = "ripgrep";
- rev = "${version}";
- sha256 = "0y5d1n6hkw85jb3rblcxqas2fp82h3nghssa4xqrhqnz25l799pj";
- };
-
- cargoSha256 = "0q68qyl2h6i0qsz82z840myxlnjay8p1w5z7hfyr8fqp7wgwa9cx";
-
- meta = with stdenv.lib; {
- description = "A fast line-oriented regex search tool, similar to ag and ack";
- homepage = https://github.com/BurntSushi/ripgrep;
- license = licenses.unlicense;
- maintainers = [ maintainers.tailhook ];
- platforms = platforms.all;
- };
-}
-```
-
-`buildRustPackage` requires a `cargoSha256` attribute which is computed over
-all crate sources of this package. Currently it is obtained by inserting a
-fake checksum into the expression and building the package once. The correct
-checksum can be then take from the failed build.
-
-To install crates with nix there is also an experimental project called
-[nixcrates](https://github.com/fractalide/nixcrates).
-
-## Using the Rust nightlies overlay
-
-Mozilla provides an overlay for nixpkgs to bring a nightly version of Rust into scope.
-This overlay can _also_ be used to install recent unstable or stable versions
-of Rust, if desired.
-
-To use this overlay, clone
-[nixpkgs-mozilla](https://github.com/mozilla/nixpkgs-mozilla),
-and create a symbolic link to the file
-[rust-overlay.nix](https://github.com/mozilla/nixpkgs-mozilla/blob/master/rust-overlay.nix)
-in the `~/.config/nixpkgs/overlays` directory.
-
- $ git clone https://github.com/mozilla/nixpkgs-mozilla.git
- $ mkdir -p ~/.config/nixpkgs/overlays
- $ ln -s $(pwd)/nixpkgs-mozilla/rust-overlay.nix ~/.config/nixpkgs/overlays/rust-overlay.nix
-
-The latest version can be installed with the following command:
-
- $ nix-env -Ai nixos.latest.rustChannels.stable.rust
-
-Or using the attribute with nix-shell:
-
- $ nix-shell -p nixos.latest.rustChannels.stable.rust
-
-To install the beta or nightly channel, "stable" should be substituted by
-"nightly" or "beta", or
-use the function provided by this overlay to pull a version based on a
-build date.
-
-The overlay automatically updates itself as it uses the same source as
-[rustup](https://www.rustup.rs/).
diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md
new file mode 100644
index 000000000000..b77c41e9b229
--- /dev/null
+++ b/doc/languages-frameworks/rust.section.md
@@ -0,0 +1,393 @@
+---
+title: Rust
+author: Matthias Beyer
+date: 2017-03-05
+---
+
+# User's Guide to the Rust Infrastructure
+
+To install the rust compiler and cargo put
+
+```
+rustc
+cargo
+```
+
+into the `environment.systemPackages` or bring them into
+scope with `nix-shell -p rustc cargo`.
+
+> If you are using NixOS and you want to use rust without a nix expression you
+> probably want to add the following in your `configuration.nix` to build
+> crates with C dependencies.
+>
+> environment.systemPackages = [binutils gcc gnumake openssl pkgconfig]
+
+For daily builds (beta and nightly) use either rustup from
+nixpkgs or use the [Rust nightlies
+overlay](#using-the-rust-nightlies-overlay).
+
+## Compiling Rust applications with Cargo
+
+Rust applications are packaged by using the `buildRustPackage` helper from `rustPlatform`:
+
+```
+rustPlatform.buildRustPackage rec {
+ name = "ripgrep-${version}";
+ version = "0.4.0";
+
+ src = fetchFromGitHub {
+ owner = "BurntSushi";
+ repo = "ripgrep";
+ rev = "${version}";
+ sha256 = "0y5d1n6hkw85jb3rblcxqas2fp82h3nghssa4xqrhqnz25l799pj";
+ };
+
+ cargoSha256 = "0q68qyl2h6i0qsz82z840myxlnjay8p1w5z7hfyr8fqp7wgwa9cx";
+
+ meta = with stdenv.lib; {
+ description = "A fast line-oriented regex search tool, similar to ag and ack";
+ homepage = https://github.com/BurntSushi/ripgrep;
+ license = licenses.unlicense;
+ maintainers = [ maintainers.tailhook ];
+ platforms = platforms.all;
+ };
+}
+```
+
+`buildRustPackage` requires a `cargoSha256` attribute which is computed over
+all crate sources of this package. Currently it is obtained by inserting a
+fake checksum into the expression and building the package once. The correct
+checksum can be then take from the failed build.
+
+To install crates with nix there is also an experimental project called
+[nixcrates](https://github.com/fractalide/nixcrates).
+
+## Compiling Rust crates using Nix instead of Cargo
+
+### Simple operation
+
+When run, `cargo build` produces a file called `Cargo.lock`,
+containing pinned versions of all dependencies. Nixpkgs contains a
+tool called `carnix` (`nix-env -iA nixos.carnix`), which can be used
+to turn a `Cargo.lock` into a Nix expression.
+
+That Nix expression calls `rustc` directly (hence bypassing Cargo),
+and can be used to compile a crate and all its dependencies. Here is
+an example for a minimal `hello` crate:
+
+
+ $ cargo new hello
+ $ cd hello
+ $ cargo build
+ Compiling hello v0.1.0 (file:///tmp/hello)
+ Finished dev [unoptimized + debuginfo] target(s) in 0.20 secs
+ $ carnix -o hello.nix --src ./. Cargo.lock --standalone
+ $ nix-build hello.nix -A hello_0_1_0
+
+Now, the file produced by the call to `carnix`, called `hello.nix`, looks like:
+
+```
+# Generated by carnix 0.6.5: carnix -o hello.nix --src ./. Cargo.lock --standalone
+{ lib, buildPlatform, buildRustCrate, fetchgit }:
+let kernel = buildPlatform.parsed.kernel.name;
+ # ... (content skipped)
+in
+rec {
+ hello = f: hello_0_1_0 { features = hello_0_1_0_features { hello_0_1_0 = f; }; };
+ hello_0_1_0_ = { dependencies?[], buildDependencies?[], features?[] }: buildRustCrate {
+ crateName = "hello";
+ version = "0.1.0";
+ authors = [ "pe@pijul.org " ];
+ src = ./.;
+ inherit dependencies buildDependencies features;
+ };
+ hello_0_1_0 = { features?(hello_0_1_0_features {}) }: hello_0_1_0_ {};
+ hello_0_1_0_features = f: updateFeatures f (rec {
+ hello_0_1_0.default = (f.hello_0_1_0.default or true);
+ }) [ ];
+}
+```
+
+In particular, note that the argument given as `--src` is copied
+verbatim to the source. If we look at a more complicated
+dependencies, for instance by adding a single line `libc="*"` to our
+`Cargo.toml`, we first need to run `cargo build` to update the
+`Cargo.lock`. Then, `carnix` needs to be run again, and produces the
+following nix file:
+
+```
+# Generated by carnix 0.6.5: carnix -o hello.nix --src ./. Cargo.lock --standalone
+{ lib, buildPlatform, buildRustCrate, fetchgit }:
+let kernel = buildPlatform.parsed.kernel.name;
+ # ... (content skipped)
+in
+rec {
+ hello = f: hello_0_1_0 { features = hello_0_1_0_features { hello_0_1_0 = f; }; };
+ hello_0_1_0_ = { dependencies?[], buildDependencies?[], features?[] }: buildRustCrate {
+ crateName = "hello";
+ version = "0.1.0";
+ authors = [ "pe@pijul.org " ];
+ src = ./.;
+ inherit dependencies buildDependencies features;
+ };
+ libc_0_2_36_ = { dependencies?[], buildDependencies?[], features?[] }: buildRustCrate {
+ crateName = "libc";
+ version = "0.2.36";
+ authors = [ "The Rust Project Developers" ];
+ sha256 = "01633h4yfqm0s302fm0dlba469bx8y6cs4nqc8bqrmjqxfxn515l";
+ inherit dependencies buildDependencies features;
+ };
+ hello_0_1_0 = { features?(hello_0_1_0_features {}) }: hello_0_1_0_ {
+ dependencies = mapFeatures features ([ libc_0_2_36 ]);
+ };
+ hello_0_1_0_features = f: updateFeatures f (rec {
+ hello_0_1_0.default = (f.hello_0_1_0.default or true);
+ libc_0_2_36.default = true;
+ }) [ libc_0_2_36_features ];
+ libc_0_2_36 = { features?(libc_0_2_36_features {}) }: libc_0_2_36_ {
+ features = mkFeatures (features.libc_0_2_36 or {});
+ };
+ libc_0_2_36_features = f: updateFeatures f (rec {
+ libc_0_2_36.default = (f.libc_0_2_36.default or true);
+ libc_0_2_36.use_std =
+ (f.libc_0_2_36.use_std or false) ||
+ (f.libc_0_2_36.default or false) ||
+ (libc_0_2_36.default or false);
+ }) [];
+}
+```
+
+Here, the `libc` crate has no `src` attribute, so `buildRustCrate`
+will fetch it from [crates.io](https://crates.io). A `sha256`
+attribute is still needed for Nix purity.
+
+### Handling external dependencies
+
+Some crates require external libraries. For crates from
+[crates.io](https://crates.io), such libraries can be specified in
+`defaultCrateOverrides` package in nixpkgs itself.
+
+Starting from that file, one can add more overrides, to add features
+or build inputs by overriding the hello crate in a seperate file.
+
+```
+with import {};
+((import ./hello.nix).hello {}).override {
+ crateOverrides = defaultCrateOverrides // {
+ hello = attrs: { buildInputs = [ openssl ]; };
+ };
+}
+```
+
+Here, `crateOverrides` is expected to be a attribute set, where the
+key is the crate name without version number and the value a function.
+The function gets all attributes passed to `buildRustCrate` as first
+argument and returns a set that contains all attribute that should be
+overwritten.
+
+For more complicated cases, such as when parts of the crate's
+derivation depend on the the crate's version, the `attrs` argument of
+the override above can be read, as in the following example, which
+patches the derivation:
+
+```
+with import {};
+((import ./hello.nix).hello {}).override {
+ crateOverrides = defaultCrateOverrides // {
+ hello = attrs: lib.optionalAttrs (lib.versionAtLeast attrs.version "1.0") {
+ postPatch = ''
+ substituteInPlace lib/zoneinfo.rs \
+ --replace "/usr/share/zoneinfo" "${tzdata}/share/zoneinfo"
+ '';
+ };
+ };
+}
+```
+
+Another situation is when we want to override a nested
+dependency. This actually works in the exact same way, since the
+`crateOverrides` parameter is forwarded to the crate's
+dependencies. For instance, to override the build inputs for crate
+`libc` in the example above, where `libc` is a dependency of the main
+crate, we could do:
+
+```
+with import {};
+((import hello.nix).hello {}).override {
+ crateOverrides = defaultCrateOverrides // {
+ libc = attrs: { buildInputs = []; };
+ };
+}
+```
+
+### Options and phases configuration
+
+Actually, the overrides introduced in the previous section are more
+general. A number of other parameters can be overridden:
+
+- The version of rustc used to compile the crate:
+
+ ```
+ (hello {}).override { rust = pkgs.rust; };
+ ```
+
+- Whether to build in release mode or debug mode (release mode by
+ default):
+
+ ```
+ (hello {}).override { release = false; };
+ ```
+
+- Whether to print the commands sent to rustc when building
+ (equivalent to `--verbose` in cargo:
+
+ ```
+ (hello {}).override { verbose = false; };
+ ```
+
+- Extra arguments to be passed to `rustc`:
+
+ ```
+ (hello {}).override { extraRustcOpts = "-Z debuginfo=2"; };
+ ```
+
+- Phases, just like in any other derivation, can be specified using
+ the following attributes: `preUnpack`, `postUnpack`, `prePatch`,
+ `patches`, `postPatch`, `preConfigure` (in the case of a Rust crate,
+ this is run before calling the "build" script), `postConfigure`
+ (after the "build" script),`preBuild`, `postBuild`, `preInstall` and
+ `postInstall`. As an example, here is how to create a new module
+ before running the build script:
+
+ ```
+ (hello {}).override {
+ preConfigure = ''
+ echo "pub const PATH=\"${hi.out}\";" >> src/path.rs"
+ '';
+ };
+ ```
+
+### Features
+
+One can also supply features switches. For example, if we want to
+compile `diesel_cli` only with the `postgres` feature, and no default
+features, we would write:
+
+```
+(callPackage ./diesel.nix {}).diesel {
+ default = false;
+ postgres = true;
+}
+```
+
+Where `diesel.nix` is the file generated by Carnix, as explained above.
+
+
+## Setting Up `nix-shell`
+Oftentimes you want to develop code from within `nix-shell`. Unfortunately
+`buildRustCrate` does not support common `nix-shell` operations directly
+(see [this issue](https://github.com/NixOS/nixpkgs/issues/37945))
+so we will use `stdenv.mkDerivation` instead.
+
+Using the example `hello` project above, we want to do the following:
+- Have access to `cargo` and `rustc`
+- Have the `openssl` library available to a crate through it's _normal_
+ compilation mechanism (`pkg-config`).
+
+A typical `shell.nix` might look like:
+
+```
+with import {};
+
+stdenv.mkDerivation {
+ name = "rust-env";
+ buildInputs = [
+ rustc cargo
+
+ # Example Additional Dependencies
+ pkgconfig openssl
+ ];
+
+ # Set Environment Variables
+ RUST_BACKTRACE = 1;
+}
+```
+
+You should now be able to run the following:
+```
+$ nix-shell --pure
+$ cargo build
+$ cargo test
+```
+
+### Controlling Rust Version Inside `nix-shell`
+To control your rust version (i.e. use nightly) from within `shell.nix` (or
+other nix expressions) you can use the following `shell.nix`
+
+```
+# Latest Nightly
+with import {};
+let src = fetchFromGitHub {
+ owner = "mozilla";
+ repo = "nixpkgs-mozilla";
+ # commit from: 2018-03-27
+ rev = "2945b0b6b2fd19e7d23bac695afd65e320efcebe";
+ sha256 = "034m1dryrzh2lmjvk3c0krgip652dql46w5yfwpvh7gavd3iypyw";
+ };
+in
+with import "${src.out}/rust-overlay.nix" pkgs pkgs;
+stdenv.mkDerivation {
+ name = "rust-env";
+ buildInputs = [
+ # Note: to use use stable, just replace `nightly` with `stable`
+ latest.rustChannels.nightly.rust
+
+ # Add some extra dependencies from `pkgs`
+ pkgconfig openssl
+ ];
+
+ # Set Environment Variables
+ RUST_BACKTRACE = 1;
+}
+```
+
+Now run:
+```
+$ rustc --version
+rustc 1.26.0-nightly (188e693b3 2018-03-26)
+```
+
+To see that you are using nightly.
+
+
+## Using the Rust nightlies overlay
+
+Mozilla provides an overlay for nixpkgs to bring a nightly version of Rust into scope.
+This overlay can _also_ be used to install recent unstable or stable versions
+of Rust, if desired.
+
+To use this overlay, clone
+[nixpkgs-mozilla](https://github.com/mozilla/nixpkgs-mozilla),
+and create a symbolic link to the file
+[rust-overlay.nix](https://github.com/mozilla/nixpkgs-mozilla/blob/master/rust-overlay.nix)
+in the `~/.config/nixpkgs/overlays` directory.
+
+ $ git clone https://github.com/mozilla/nixpkgs-mozilla.git
+ $ mkdir -p ~/.config/nixpkgs/overlays
+ $ ln -s $(pwd)/nixpkgs-mozilla/rust-overlay.nix ~/.config/nixpkgs/overlays/rust-overlay.nix
+
+The latest version can be installed with the following command:
+
+ $ nix-env -Ai nixos.latest.rustChannels.stable.rust
+
+Or using the attribute with nix-shell:
+
+ $ nix-shell -p nixos.latest.rustChannels.stable.rust
+
+To install the beta or nightly channel, "stable" should be substituted by
+"nightly" or "beta", or
+use the function provided by this overlay to pull a version based on a
+build date.
+
+The overlay automatically updates itself as it uses the same source as
+[rustup](https://www.rustup.rs/).
diff --git a/doc/languages-frameworks/texlive.xml b/doc/languages-frameworks/texlive.xml
index fdee1e405ecc..4515e17ec09e 100644
--- a/doc/languages-frameworks/texlive.xml
+++ b/doc/languages-frameworks/texlive.xml
@@ -39,6 +39,9 @@ nix-repl> :l <nixpkgs>
nix-repl> texlive.collection-<TAB>
+
+ Note that the wrapper assumes that the result has a chance to be useful. For example, the core executables should be present, as well as some core data files. The supported way of ensuring this is by including some scheme, for example scheme-basic, into the combination.
+
diff --git a/doc/languages-frameworks/vim.md b/doc/languages-frameworks/vim.section.md
similarity index 100%
rename from doc/languages-frameworks/vim.md
rename to doc/languages-frameworks/vim.section.md
diff --git a/doc/manual.xml b/doc/manual.xml
index eb0a24789d44..385079eb5785 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -9,7 +9,7 @@
-
+
diff --git a/doc/meta.xml b/doc/meta.xml
index 0f9dccfb91b5..5dbe810810d1 100644
--- a/doc/meta.xml
+++ b/doc/meta.xml
@@ -53,7 +53,7 @@ $ nix-env -qa hello --json
"x86_64-linux",
"armv5tel-linux",
"armv7l-linux",
- "mips64el-linux",
+ "mips32-linux",
"x86_64-darwin",
"i686-cygwin",
"i686-freebsd",
@@ -174,7 +174,7 @@ meta-attributes
maintainers of this Nix expression. If
you would like to be a maintainer of a package, you may want to add
yourself to nixpkgs/lib/maintainers.nix
+ xlink:href="https://github.com/NixOS/nixpkgs/blob/master/maintainers/maintainer-list.nix">nixpkgs/maintainers/maintainer-list.nix
and write something like [ stdenv.lib.maintainers.alice
stdenv.lib.maintainers.bob ].
diff --git a/doc/multiple-output.xml b/doc/multiple-output.xml
index a2acc91e55a2..2f23da8df01e 100644
--- a/doc/multiple-output.xml
+++ b/doc/multiple-output.xml
@@ -68,7 +68,7 @@
$outputDevdoc
- is for developer documentation. Currently we count gtk-doc in there. It goes to devdoc or is removed (!) by default. This is because e.g. gtk-doc tends to be rather large and completely unused by nixpkgs users.
+ is for developer documentation. Currently we count gtk-doc and devhelp books in there. It goes to devdoc or is removed (!) by default. This is because e.g. gtk-doc tends to be rather large and completely unused by nixpkgs users.
diff --git a/doc/overrides.css b/doc/overrides.css
new file mode 100644
index 000000000000..4c7d4a31be2d
--- /dev/null
+++ b/doc/overrides.css
@@ -0,0 +1,9 @@
+.docbook .xref img[src^=images\/callouts\/],
+.screen img,
+.programlisting img {
+ width: 1em;
+}
+
+.calloutlist img {
+ width: 1.5em;
+}
diff --git a/doc/package-notes.xml b/doc/package-notes.xml
index 184bee089ae3..1fccfd5d329d 100644
--- a/doc/package-notes.xml
+++ b/doc/package-notes.xml
@@ -660,6 +660,32 @@ cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
passing -q to the Emacs command.
+
+ Sometimes emacsWithPackages 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
+ pkgs/top-level/emacs-packages.nix). 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 overrideScope.
+
+
+
+overrides = super: self: 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
+])
+
+
@@ -667,11 +693,13 @@ cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
Weechat
-Weechat can currently be configured to include your choice of plugins.
-To make use of this functionality, install an expression that overrides its configuration such as
+Weechat can be configured to include your choice of plugins, reducing its
+closure size from the default configuration which includes all available
+plugins. To make use of this functionality, install an expression that
+overrides its configuration such as
weechat.override {configure = {availablePlugins, ...}: {
- plugins = with availablePlugins; [ python perl ];
- }
+ plugins = with availablePlugins; [ python perl ];
+ }
}
@@ -685,7 +713,7 @@ the inotify.py script in weechat-scripts requires
D-Bus or libnotify, and the fish.py script requires
pycrypto. To use these scripts, use the python
plugin's withPackages attribute:
-weechat.override {configure = {availablePlugins, ...}: {
+weechat.override { configure = {availablePlugins, ...}: {
plugins = with availablePlugins; [
(python.withPackages (ps: with ps; [ pycrypto python-dbus ]))
];
@@ -693,5 +721,15 @@ plugin's withPackages attribute:
}
+
+In order to also keep all default plugins installed, it is possible to use
+the following method:
+weechat.override { configure = { availablePlugins, ... }: {
+ plugins = builtins.attrValues (availablePlugins // {
+ python = availablePlugins.python.withPackages (ps: with ps; [ pycrypto python-dbus ]);
+ });
+}; }
+
+
diff --git a/doc/reviewing-contributions.xml b/doc/reviewing-contributions.xml
index 0813e0968e86..d6f33ccd1cdb 100644
--- a/doc/reviewing-contributions.xml
+++ b/doc/reviewing-contributions.xml
@@ -7,123 +7,123 @@
Reviewing contributions
- The following section is a draft and reviewing policy is still being
+ The following section is a draft and reviewing policy is still being
discussed.
-The nixpkgs projects receives a fairly high number of contributions via
- GitHub pull-requests. Reviewing and approving these is an important task and a
+The nixpkgs projects receives a fairly high number of contributions via
+ GitHub pull-requests. Reviewing and approving these is an important task and a
way to contribute to the project.
-The high change rate of nixpkgs make any pull request that is open for
- long enough 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 these. GitHub provides sort
- filters that can be used to see the most
- recently and the least
+The high change rate of nixpkgs make any pull request that is open for
+ long enough 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 these. GitHub provides sort
+ filters that can be used to see the most
+ recently and the least
recently updated pull-requests.
-When reviewing a pull request, please always be nice and polite.
- Controversial changes can lead to controversial opinions, but it is important
+When reviewing a pull request, please always be nice and polite.
+ Controversial changes can lead to controversial opinions, but it is important
to respect every community members and their work.
-GitHub provides reactions, they are a simple and quick way to provide
- feedback to pull-requests or any comments. The thumb-down reaction should be
- used with care and if possible accompanied with some explanations so the
+GitHub provides reactions, they are a simple and quick way to provide
+ feedback to pull-requests or any comments. The thumb-down reaction should be
+ used with care and if possible accompanied with some explanations so the
submitter has directions to improve his contribution.
-Pull-requests reviews should include a list of what has been reviewed in a
- comment, so other reviewers and mergers can know the state of the
+Pull-requests reviews should include a list of what has been reviewed in a
+ comment, so other reviewers and mergers can know the state of the
review.
-All the review template samples provided in this section are generic and
- meant as examples. Their usage is optional and the reviewer is free to adapt
+All the review template samples provided in this section are generic and
+ meant as examples. Their usage is optional and the reviewer is free to adapt
them to his liking.Package updates
-A package update is the most trivial and common type of pull-request.
- These pull-requests mainly consist in updating the version part of the package
+A package update is the most trivial and common type of pull-request.
+ These pull-requests mainly consist in updating the version part of the package
name and the source hash.
-It can happen that non trivial updates include patches or more complex
+It can happen that non trivial updates include patches or more complex
changes.Reviewing process:
- Add labels to the pull-request. (Requires commit
+ Add labels to the pull-request. (Requires commit
rights)
- 8.has: package (update) and any topic
+ 8.has: package (update) and any topic
label that fit the updated package.
- Ensure that the package versioning is fitting the
+ Ensure that the package versioning is fitting the
guidelines.
- Ensure that the commit text is fitting the
+ Ensure that the commit text is fitting the
guidelines.Ensure that the package maintainers are notified.
- mention-bot usually notify GitHub users based on the
- submitted changes, but it can happen that it misses some of the
+ mention-bot usually notify GitHub users based on the
+ submitted changes, but it can happen that it misses some of the
package maintainers.
- Ensure that the meta field contains correct
+ Ensure that the meta field contains correct
information.
- License can change with version updates, so it should be
+ License can change with version updates, so it should be
checked to be fitting upstream license.
- If the package has no maintainer, a maintainer must be
- set. This can be the update submitter or a community member that
+ If the package has no maintainer, a maintainer must be
+ set. This can be the update submitter or a community member that
accepts to take maintainership of the package.Ensure that the code contains no typos.Building the package locally.
- Pull-requests are often targeted to the master or staging
- branch so building the pull-request locally as it is submitted can
+ Pull-requests are often targeted to the master or staging
+ branch so building the pull-request locally as it is submitted can
trigger a large amount of source builds.
- It is possible to rebase the changes on nixos-unstable or
- nixpkgs-unstable for easier review by running the following commands
+ It is possible to rebase the changes on nixos-unstable or
+ nixpkgs-unstable for easier review by running the following commands
from a nixpkgs clone.
-$ git remote add channels https://github.com/NixOS/nixpkgs-channels.git
$ git fetch channels nixos-unstable
$ git fetch origin pull/PRNUMBER/head
-$ git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD
- This should be done only once to be able to fetch channel
+ This should be done only once to be able to fetch channel
branches from the nixpkgs-channels repository.Fetching the nixos-unstable branch.
- Fetching the pull-request changes, PRNUMBER
- is the number at the end of the pull-request title and
- BASEBRANCH the base branch of the
+ Fetching the pull-request changes, PRNUMBER
+ is the number at the end of the pull-request title and
+ BASEBRANCH the base branch of the
pull-request.
-
- Rebasing the pull-request changes to the nixos-unstable
+
+ Rebasing the pull-request changes to the nixos-unstable
branch.
- The nox
- 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. PRNUMBER should be replaced by the
+ The nox
+ 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. PRNUMBER should be replaced by the
number at the end of the pull-request title.
$ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
@@ -153,42 +153,42 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
New packages
-New packages are a common type of pull-requests. These pull requests
+New packages are a common type of pull-requests. These pull requests
consists in adding a new nix-expression for a package.Reviewing process:
- Add labels to the pull-request. (Requires commit
+ Add labels to the pull-request. (Requires commit
rights)
- 8.has: package (new) and any topic
+ 8.has: package (new) and any topic
label that fit the new package.
- Ensure that the package versioning is fitting the
+ Ensure that the package versioning is fitting the
guidelines.
- Ensure that the commit name is fitting the
+ Ensure that the commit name is fitting the
guidelines.
- Ensure that the meta field contains correct
+ Ensure that the meta field contains correct
information.
- License must be checked to be fitting upstream
+ License must be checked to be fitting upstream
license.
- Platforms should be set or the package will not get binary
+ Platforms should be set or the package will not get binary
substitutes.
- A maintainer must be set, this can be the package
- submitter or a community member that accepts to take maintainership of
+ A maintainer must be set, this can be the package
+ submitter or a community member that accepts to take maintainership of
the package.Ensure that the code contains no typos.Ensure the package source.
- Mirrors urls should be used when
+ Mirrors urls should be used when
available.
- The most appropriate function should be used (e.g.
- packages from GitHub should use
+ The most appropriate function should be used (e.g.
+ packages from GitHub should use
fetchFromGitHub).
@@ -223,49 +223,49 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
Module updates
-Module updates are submissions changing modules in some ways. These often
+Module updates are submissions changing modules in some ways. These often
contains changes to the options or introduce new options.Reviewing process
- Add labels to the pull-request. (Requires commit
+ Add labels to the pull-request. (Requires commit
rights)
- 8.has: module (update) and any topic
+ 8.has: module (update) and any topic
label that fit the module.Ensure that the module maintainers are notified.
- Mention-bot notify GitHub users based on the submitted
- changes, but it can happen that it miss some of the package
+ Mention-bot notify GitHub users based on the submitted
+ changes, but it can happen that it miss some of the package
maintainers.
- Ensure that the module tests, if any, are
+ Ensure that the module tests, if any, are
succeeding.Ensure that the introduced options are correct.
- Type should be appropriate (string related types differs
- in their merging capabilities, optionSet and
+ Type should be appropriate (string related types differs
+ in their merging capabilities, optionSet and
string types are deprecated).
- Description, default and example should be
+ Description, default and example should be
provided.Ensure that option changes are backward compatible.
- mkRenamedOptionModule and
- mkAliasOptionModule functions provide way to make
+ mkRenamedOptionModule and
+ mkAliasOptionModule functions provide way to make
option changes backward compatible.
- Ensure that removed options are declared with
+ Ensure that removed options are declared with
mkRemovedOptionModule
- Ensure that changes that are not backward compatible are
+ Ensure that changes that are not backward compatible are
mentioned in release notes.
- Ensure that documentations affected by the change is
+ Ensure that documentations affected by the change is
updated.
@@ -294,37 +294,37 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
New modules submissions introduce a new module to NixOS.
- Add labels to the pull-request. (Requires commit
+ Add labels to the pull-request. (Requires commit
rights)
- 8.has: module (new) and any topic label
+ 8.has: module (new) and any topic label
that fit the module.
- Ensure that the module tests, if any, are
+ Ensure that the module tests, if any, are
succeeding.Ensure that the introduced options are correct.
- Type should be appropriate (string related types differs
- in their merging capabilities, optionSet and
+ Type should be appropriate (string related types differs
+ in their merging capabilities, optionSet and
string types are deprecated).
- Description, default and example should be
+ Description, default and example should be
provided.
- Ensure that module meta field is
+ Ensure that module meta field is
present
- Maintainers should be declared in
+ Maintainers should be declared in
meta.maintainers.
- Module documentation should be declared with
+ Module documentation should be declared with
meta.doc.
- Ensure that the module respect other modules
+ Ensure that the module respect other modules
functionality.
- For example, enabling a module should not open firewall
+ For example, enabling a module should not open firewall
ports by default.
@@ -340,7 +340,7 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
- [ ] options have default
- [ ] options have example
- [ ] options have descriptions
-- [ ] No unneeded package is added to system.environmentPackages
+- [ ] No unneeded package is added to environment.systemPackages
- [ ] meta.maintainers is set
- [ ] module documentation is declared in meta.doc
@@ -355,22 +355,22 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
Other type of submissions requires different reviewing steps.
-If you consider having enough knowledge and experience in a topic and
- would like to be a long-term reviewer for related submissions, please contact
- the current reviewers for that topic. They will give you information about the
+If you consider having enough knowledge and experience in a topic and
+ would like to be a long-term reviewer for related submissions, please contact
+ the current reviewers for that topic. They will give you information about the
reviewing process.
-The main reviewers for a topic can be hard to find as there is no list, but
-checking past pull-requests to see who reviewed or git-blaming the code to see
+The main reviewers for a topic can be hard to find as there is no list, but
+checking past pull-requests to see who reviewed or git-blaming the code to see
who committed to that topic can give some hints.
-Container system, boot system and library changes are some examples of the
+Container system, boot system and library changes are some examples of the
pull requests fitting this category.Merging pull-requests
-It is possible for community members that have enough knowledge and
+It is possible for community members that have enough knowledge and
experience on a special topic to contribute by merging pull requests.TODO: add the procedure to request merging rights.
@@ -380,13 +380,13 @@ The following paragraph about how to deal with unactive contributors is just a
proposition and should be modified to what the community agrees to be the right
policy.
-Please note that contributors with commit rights unactive for more than
+Please note that contributors with commit rights unactive for more than
three months will have their commit rights revoked.
-->
-In a case a contributor leaves definitively the Nix community, he should
- create an issue or notify the mailing list with references of packages and
- modules he maintains so the maintainership can be taken over by other
+In a case a contributor leaves definitively the Nix community, he should
+ create an issue or notify the mailing list with references of packages and
+ modules he maintains so the maintainership can be taken over by other
contributors.
diff --git a/doc/shell.nix b/doc/shell.nix
new file mode 100644
index 000000000000..22590142ee1a
--- /dev/null
+++ b/doc/shell.nix
@@ -0,0 +1,4 @@
+{ pkgs ? import ../. {} }:
+(import ./default.nix).overrideAttrs (x: {
+ buildInputs = x.buildInputs ++ [ pkgs.xmloscopy ];
+})
diff --git a/doc/shell.section.md b/doc/shell.section.md
new file mode 100644
index 000000000000..cb8832a814fc
--- /dev/null
+++ b/doc/shell.section.md
@@ -0,0 +1,22 @@
+---
+title: pkgs.mkShell
+author: zimbatm
+date: 2017-10-30
+---
+
+# mkShell
+
+pkgs.mkShell is a special kind of derivation that is only useful when using
+it combined with nix-shell. It will in fact fail to instantiate when invoked
+with nix-build.
+
+## Usage
+
+```nix
+{ pkgs ? import {} }:
+pkgs.mkShell {
+ # this will make all the build inputs from hello and gnutar available to the shell environment
+ inputsFrom = with pkgs; [ hello gnutar ];
+ buildInputs = [ pkgs.gnumake ];
+}
+```
diff --git a/doc/stdenv.xml b/doc/stdenv.xml
index 46b562a794f0..2a3316b8d018 100644
--- a/doc/stdenv.xml
+++ b/doc/stdenv.xml
@@ -179,6 +179,269 @@ genericBuild
+Specifying dependencies
+
+
+ As described in the Nix manual, almost any *.drv store path in a derivation's attribute set will induce a dependency on that derivation.
+ mkDerivation, however, takes a few attributes intended to, between them, include all the dependencies of a package.
+ This is done both for structure and consistency, but also so that certain other setup can take place.
+ For example, certain dependencies need their bin directories added to the PATH.
+ That is built-in, but other setup is done via a pluggable mechanism that works in conjunction with these dependency attributes.
+ See for details.
+
+
+ Dependencies can be broken down along three axes: their host and target platforms relative to the new derivation's, and whether they are propagated.
+ The platform distinctions are motivated by cross compilation; see for exactly what each platform means.
+
+ The build platform is ignored because it is a mere implementation detail of the package satisfying the dependency:
+ As a general programming principle, dependencies are always specified as interfaces, not concrete implementation.
+
+ 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.
+
+
+ The extension of PATH 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. which run on the platform where the new derivation will be built.
+
+ Currently, that means for native builds all dependencies are put on the PATH.
+ 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 depsBuild* and nativeBuildDependencies dependencies would affect the PATH.
+
+ For each dependency dep of those dependencies, dep/bin, if present, is added to the PATH environment variable.
+
+
+ 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.
+
+
+ It is important to note dependencies are not necessary propagated as the same sort of dependency that they were before, but rather as the corresponding sort so that the platform rules still line up.
+ The exact rules for dependency propagation can be given by assigning each sort of dependency two integers based one how it's host and target platforms are offset from the depending derivation's platforms.
+ Those offsets are given are given below in the descriptions of each dependency list attribute.
+ Algorithmically, we traverse propagated inputs, accumulating every propagated dep's propagated deps and adjusting them to account for the "shift in perspective" described by the current dep'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 deps whose combined offsets go out-of-bounds, which can be viewed as a filter over that transitive closure removing dependencies that are blatantly absurd.
+
+
+ We can define the process precisely with Natural Deduction using the inference rules.
+ This probably seems a bit obtuse, but so is the bash code that actually implements it!
+
+ The findInputs function, currently residing in pkgs/stdenv/generic/setup.sh, implements the propagation logic.
+
+ They're confusing in very different ways so...hopefully if something doesn't make sense in one presentation, it does in the other!
+
+let mapOffset(h, t, i) = i + (if i <= 0 then h else t - 1)
+
+propagated-dep(h0, t0, A, B)
+propagated-dep(h1, t1, B, C)
+h0 + h1 in {-1, 0, 1}
+h0 + t1 in {-1, 0, 1}
+-------------------------------------- Transitive property
+propagated-dep(mapOffset(h0, t0, h1),
+ mapOffset(h0, t0, t1),
+ A, C)
+
+let mapOffset(h, t, i) = i + (if i <= 0 then h else t - 1)
+
+dep(h0, _, A, B)
+propagated-dep(h1, t1, B, C)
+h0 + h1 in {-1, 0, 1}
+h0 + t1 in {-1, 0, -1}
+-------------------------------------- Take immediate deps' propagated deps
+propagated-dep(mapOffset(h0, t0, h1),
+ mapOffset(h0, t0, t1),
+ A, C)
+
+propagated-dep(h, t, A, B)
+-------------------------------------- Propagated deps count as deps
+dep(h, t, A, B)
+ Some explanation of this monstrosity is in order.
+ In the common case, the target offset of a dependency is the successor to the target offset: t = h + 1.
+ That means that:
+
+let f(h, t, i) = i + (if i <= 0 then h else t - 1)
+let f(h, h + 1, i) = i + (if i <= 0 then h else (h + 1) - 1)
+let f(h, h + 1, i) = i + (if i <= 0 then h else h)
+let f(h, h + 1, i) = i + h
+
+ This is where the "sum-like" comes from above:
+ We can just sum all the host offset to get the host offset of the transitive dependency.
+ The target offset is the transitive dep 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.
+
+
+ Because of the bounds checks, the uncommon cases are h = t and h + 2 = t.
+ In the former case, the motivation for mapOffset is that since its host and target platforms are the same, no transitive dep of it should be able to "discover" an offset greater than its reduced target offsets.
+ mapOffset effectively "squashes" all its transitive dependencies' offsets so that none will ever be greater than the target offset of the original h = t package.
+ In the other case, h + 1 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.
+
+
+Overall, the unifying theme here is that propagation shouldn't be introducing transitive dependencies involving platforms the needing package is unaware of.
+The offset bounds checking and definition of mapOffset 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 cannot be relevant.
+From a capability perspective, we can imagine that the host and target platforms of a package are the capabilities a package requires, and the depending package must provide the capability to the dependency.
+
+
+
+ Variables specifying dependencies
+
+
+ depsBuildBuild
+
+
+ A list of dependencies whose host and target platforms are the new derivation's build platform.
+ This means a -1 host and -1 target offset from the new derivation's platforms.
+ They are programs/libraries used at build time that furthermore produce programs/libraries also used at build time.
+ If the dependency doesn't care about the target platform (i.e. isn't a compiler or similar tool), put it in nativeBuildInputsinstead.
+ The most common use for this buildPackages.stdenv.cc, the default C compiler for this role.
+ That example crops up more than one might think in old commonly used C libraries.
+
+
+ Since these packages are able to be run at build time, that are always added to the PATH, 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.
+
+
+
+
+
+ nativeBuildInputs
+
+
+ A list of dependencies whose host platform is the new derivation's build platform, and target platform is the new derivation's host platform.
+ This means a -1 host offset and 0 target offset from the new derivation's platforms.
+ They are programs/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 depsBuildBuild or depsBuildTarget.
+ This would be called depsBuildHost but for historical continuity.
+
+
+ Since these packages are able to be run at build time, that are added to the PATH, as described above.
+ But since these packages only are 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.
+
+
+
+
+
+ depsBuildTarget
+
+
+ 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 -1 host offset and 1 target offset from the new derivation's platforms.
+ They are programs used at build time that produce code to run at run with code produced by the depending package.
+ Most commonly, these would tools used to build the runtime or standard library 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 the dependency is unconditional.
+
+
+ This is a somewhat confusing dependency to wrap ones head around, and for good reason.
+ As the only one where the platform offsets are not adjacent integers, it requires thinking of a bootstrapping stage two away from the current one.
+ It and it's use-case go hand in hand and are both considered poor form:
+ try not to need this sort dependency, and try not avoid building standard libraries / 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.
+
+
+ Since these packages are able to be run at build time, that are added to the PATH, as described above.
+ But since these packages only are 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.
+
+
+
+
+
+ depsHostHost
+
+ A list of dependencies whose host and target platforms match the new derivation's host platform.
+ This means a both 0 host offset and 0 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, that would usually be tools used by compilers for metaprogramming/macro systems, or libraries used by the macros/metaprogramming code itself.
+ It's always preferable to use a depsBuildBuild dependency in the derivation being built than a depsHostHost on the tool doing the building for this purpose.
+
+
+
+
+ buildInputs
+
+
+ A list of dependencies whose host platform and target platform match the new derivation's.
+ This means a 0 host offset and 1 target offset from the new derivation's host platform.
+ This would be called depsHostTarget 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 depsBuildBuild.
+
+
+ These often are programs/libraries used by the new derivation at run-time, but that isn't always the case.
+ For example, the machine code in a statically linked library is only used at run time, but the derivation containing the library is only needed at build time.
+ Even in the dynamic case, the library may also be needed at build time to appease the linker.
+
+
+
+
+
+ depsTargetTarget
+
+ A list of dependencies whose host platform matches the new derivation's target platform.
+ This means a 1 offset from the new derivation's platforms.
+ These are packages that run on the target platform, e.g. the standard library or run-time deps of standard library that a compiler insists on knowing about.
+ It's poor form in almost all cases for a package to depend on another from a future stage [future stage corresponding to positive offset].
+ Do not use this attribute unless you are packaging a compiler and are sure it is needed.
+
+
+
+
+ depsBuildBuildPropagated
+
+ The propagated equivalent of depsBuildBuild.
+ This perhaps never ought to be used, but it is included for consistency [see below for the others].
+
+
+
+
+ propagatedNativeBuildInputs
+
+ The propagated equivalent of nativeBuildInputs.
+ This would be called depsBuildHostPropagated but for historical continuity.
+ For example, if package Y has propagatedNativeBuildInputs = [X], and package Z has buildInputs = [Y], then package Z will be built as if it included package X in its nativeBuildInputs.
+ If instead, package Z has nativeBuildInputs = [Y], then Z will be built as if it included X in the depsBuildBuild of package Z, because of the sum of the two -1 host offsets.
+
+
+
+
+ depsBuildTargetPropagated
+
+ The propagated equivalent of depsBuildTarget.
+ This is prefixed for the same reason of alerting potential users.
+
+
+
+
+ depsHostHostPropagated
+
+ The propagated equivalent of depsHostHost.
+
+
+
+
+ propagatedBuildInputs
+
+ The propagated equivalent of buildInputs.
+ This would be called depsHostTargetPropagated but for historical continuity.
+
+
+
+
+ depsTargetTarget
+
+ The propagated equivalent of depsTargetTarget.
+ This is prefixed for the same reason of alerting potential users.
+
+
+
+
+
+
+
+
Attributes
@@ -198,63 +461,22 @@ genericBuild
-
- Variables specifying dependencies
-
-
- nativeBuildInputs
-
- A list of dependencies used by the new derivation at build-time.
- I.e. these dependencies should not make it into the package's runtime-closure, though this is currently not checked.
- For each dependency dir, the directory dir/bin, if it exists, is added to the PATH environment variable.
- Other environment variables are also set up via a pluggable mechanism.
- For instance, if buildInputs contains Perl, then the lib/site_perl subdirectory of each input is added to the PERL5LIB environment variable.
- See for details.
-
-
-
-
- buildInputs
-
- A list of dependencies used by the new derivation at run-time.
- Currently, the build-time environment is modified in the exact same way as with nativeBuildInputs.
- This is problematic in that when cross-compiling, foreign executables can clobber native ones on the PATH.
- Even more confusing is static-linking.
- A statically-linked library should be listed here because ultimately that generated machine code will be used at run-time, even though a derivation containing the object files or static archives will only be used at build-time.
- A less confusing solution to this would be nice.
-
-
-
-
-
- propagatedNativeBuildInputs
-
- Like nativeBuildInputs, but these dependencies are propagated:
- that is, the dependencies listed here are added to the nativeBuildInputs of any package that uses this package as a dependency.
- So if package Y has propagatedNativeBuildInputs = [X], and package Z has nativeBuildInputs = [Y],
- then package X will appear in Z’s build environment automatically.
-
-
-
-
- propagatedBuildInputs
-
- Like buildInputs, but propagated just like propagatedNativeBuildInputs.
- This inherits buildInputs's flaws of clobbering native executables when cross-compiling and being confusing for static linking.
-
-
-
-
-
Variables affecting build propertiesenableParallelBuilding
- If set, stdenv will pass specific
- flags to make and other build tools to enable
- parallel building with up to build-cores
- workers.
+
+ If set to true, stdenv will
+ pass specific flags to make and other build tools to
+ enable parallel building with up to build-cores
+ workers.
+
+ Unless set to false, some build systems with good
+ support for parallel building including cmake,
+ meson, and qmake will set it to
+ true.
+
@@ -649,7 +871,7 @@ script) if it exists.
By default, when cross compiling, the configure script has and passed.
Packages can instead pass [ "build" "host" "target" ] or a subset to control exactly which platform flags are passed.
Compilers and other tools should use this to also pass the target platform, for example.
- Note eventually these will be passed when in native builds too, to improve determinism: build-time guessing, as is done today, is a risk of impurity.
+ Eventually these will be passed when in native builds too, to improve determinism: build-time guessing, as is done today, is a risk of impurity.
@@ -773,13 +995,14 @@ but only if the doCheck variable is enabled.
doCheck
- If set to a non-empty string, the check phase is
- executed, otherwise it is skipped (default). Thus you should set
-
-
-doCheck = true;
-
- in the derivation to enable checks.
+
+ Controls whether the check phase is executed.
+ By default it is skipped, but if doCheck is set to true, the check phase is usually executed.
+ Thus you should set doCheck = true; in the derivation to enable checks.
+ The exception is cross compilation.
+ Cross compiled builds never run tests, no matter how doCheck is set,
+ as the newly-built program won't run on the platform used to build it.
+
@@ -916,6 +1139,20 @@ following:
If set, libraries and executables are not
stripped. By default, they are.
+
+ dontStripHost
+
+ Like dontStripHost, but only affects the strip command targetting the package's host platform.
+ Useful when supporting cross compilation, but otherwise feel free to ignore.
+
+
+
+ dontStripTarget
+
+ Like dontStripHost, but only affects the strip command targetting the packages' target platform.
+ Useful when supporting cross compilation, but otherwise feel free to ignore.
+
+ dontMoveSbin
@@ -1044,12 +1281,14 @@ installcheck.
doInstallCheck
- If set to a non-empty string, the installCheck phase is
- executed, otherwise it is skipped (default). Thus you should set
-
- doInstallCheck = true;
-
- in the derivation to enable install checks.
+
+ Controls whether the installCheck phase is executed.
+ By default it is skipped, but if doInstallCheck is set to true, the installCheck phase is usually executed.
+ Thus you should set doInstallCheck = true; in the derivation to enable install checks.
+ The exception is cross compilation.
+ Cross compiled builds never run tests, no matter how doInstallCheck is set,
+ as the newly-built program won't run on the platform used to build it.
+
@@ -1346,46 +1585,127 @@ someVar=$(stripHash $name)
Package setup hooks
-The following packages provide a setup hook:
-
+
+ Nix itself considers a build-time dependency merely something that should previously be built and accessible at build time—packages themselves are on their own to perform any additional setup.
+ In most cases, that is fine, and the downstream derivation can deal with it's own dependencies.
+ But for a few common tasks, that would result in almost every package doing the same sort of setup work---depending not on the package itself, but entirely on which dependencies were used.
+
+
+ In order to alleviate this burden, the setup hook>mechanism was written, where any package can include a shell script that [by convention rather than enforcement by Nix], any downstream reverse-dependency will source as part of its build process.
+ That allows the downstream dependency to merely specify its dependencies, and lets those dependencies effectively initialize themselves.
+ No boilerplate mirroring the list of dependencies is needed.
+
+
+ The Setup hook mechanism is a bit of a sledgehammer though: a powerful feature with a broad and indiscriminate area of effect.
+ The combination of its power and implicit use may be expedient, but isn't without costs.
+ Nix itself is unchanged, but the spirit of adding dependencies being effect-free is violated even if the letter isn't.
+ For example, if a derivation path is mentioned more than once, Nix itself doesn't care and simply makes sure the 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.
+
+
+ The most typical use of the setup hook is actually to add other hooks which are then run (i.e. after all the setup hooks) on each dependency.
+ For example, the C compiler wrapper's setup hook feeds itself flags for each dependency that contains relevant libaries and headers.
+ This is done by defining a bash function, and appending its name to one of
+ envBuildBuildHooks`,
+ envBuildHostHooks`,
+ envBuildTargetHooks`,
+ envHostHostHooks`,
+ envHostTargetHooks`, or
+ envTargetTargetHooks`.
+ These 6 bash variables correspond to the 6 sorts of dependencies by platform (there's 12 total but we ignore the propagated/non-propagated axis).
+
+
+ Packages adding a hook should not hard code a specific hook, but rather choose a variable relative to how they are included.
+ Returning to the C compiler wrapper example, if it itself is an n dependency, then it only wants to accumulate flags from n + 1 dependencies, as only those ones match the compiler's target platform.
+ The hostOffset variable is defined with the current dependency's host offset targetOffset with its target offset, before it's 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
+
+addEnvHooks "$hostOffset" myBashFunction
+
+
+
+ The existence of setups hooks has long been documented and packages inside Nixpkgs are free to use these mechanism.
+ Other packages, however, should not rely on these mechanisms not changing between Nixpkgs versions.
+ Because of the existing issues with this system, there's little benefit from mandating it be stable for any period of time.
+
+
+ Here are some packages that provide a setup hook.
+ Since the mechanism is modular, this probably isn't an exhaustive list.
+ Then again, since the mechanism is only to be used as a last resort, it might be.
- CC Wrapper
+ Bintools Wrapper
- CC Wrapper wraps a C toolchain for a bunch of miscellaneous purposes.
- Specifically, a C compiler (GCC or Clang), Binutils (or the CCTools + binutils mashup when targetting Darwin), and a C standard library (glibc or Darwin's libSystem) are all fed in, and dependency finding, hardening (see below), and purity checks for each are handled by CC Wrapper.
- Packages typically depend on only CC Wrapper, instead of those 3 inputs directly.
+ 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 Bintools Wrapper.
+ Packages typically depend on CC Wrapper, which in turn (at run time) depends on Bintools Wrapper.
- Dependency finding is undoubtedly the main task of CC wrapper.
+ 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 to need to share, and probably the most important to understand.
It is currently accomplished by collecting directories of host-platform dependencies (i.e. buildInputs and nativeBuildInputs) in environment variables.
- CC wrapper's setup hook causes any include subdirectory of such a dependency to be added to NIX_CFLAGS_COMPILE, and any lib and lib64 subdirectories to NIX_LDFLAGS.
- The setup hook itself contains some lengthy comments describing the exact convoluted mechanism by which this is accomplished.
+ Bintools Wrapper's setup hook causes any lib and lib64 subdirectories to be added to NIX_LDFLAGS.
+ Since CC Wrapper and Bintools Wrapper use the same strategy, most of the Bintools Wrapper code is sparsely commented and refers to CC Wrapper.
+ But CC Wrapper's code, by contrast, has quite lengthy comments.
+ Bintools Wrapper merely cites those, rather than repeating them, to avoid falling out of sync.
A final task of the setup hook is defining a number of standard environment variables to tell build systems which executables full-fill which purpose.
- They are defined to just be the base name of the tools, under the assumption that CC Wrapper's binaries will be on the path.
+ They are defined to just be the base name of the tools, under the assumption that Bintools Wrapper's binaries will be on the path.
Firstly, this helps poorly-written packages, e.g. ones that look for just gcc when CC isn't defined yet clang is to be used.
- Secondly, this helps packages not get confused when cross-compiling, in which case multiple CC wrappers may be simultaneous in use (targeting different platforms).
- BUILD_- and TARGET_-prefixed versions of the normal environment variable are defined for the additional CC Wrappers, properly disambiguating them.
+ Secondly, this helps packages not get confused when cross-compiling, in which case multiple Bintools Wrappers may simultaneously be in use.
+
+ Each wrapper targets a single platform, so if binaries for multiple platforms are needed, the underlying binaries must be wrapped multiple times.
+ As this is a property of the wrapper itself, the multiple wrappings are needed whether or not the same underlying binaries can target multiple platforms.
+
+ BUILD_- and TARGET_-prefixed versions of the normal environment variable are defined for the additional Bintools Wrappers, properly disambiguating them.
- A problem with this final task is that CC Wrapper is honest and defines LD as ld.
+ A problem with this final task is that Bintools Wrapper is honest and defines LD as ld.
Most packages, however, firstly use the C compiler for linking, secondly use LD anyways, defining it as the C compiler, and thirdly, only so define LD when it is undefined as a fallback.
- This triple-threat means CC Wrapper will break those packages, as LD is already defined as the actually linker which the package won't override yet doesn't want to use.
+ 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, LD as the C compiler.
A good way to do this would be preConfigure = "LD=$CC".
+
+ CC Wrapper
+
+
+ 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 CC Wrapper.
+ Packages typically depend on CC Wrapper, which in turn (at run time) depends on Bintools Wrapper.
+
+
+ Dependency finding is undoubtedly the main task of CC Wrapper.
+ This works just like Bintools Wrapper, except that any include subdirectory of any relevant dependency is added to NIX_CFLAGS_COMPILE.
+ The setup hook itself contains some lengthy comments describing the exact convoluted mechanism by which this is accomplished.
+
+
+ CC Wrapper also like Bintools Wrapper defines standard environment variables with the names of the tools it wraps, for the same reasons described above.
+ Importantly, while it includes a cc symlink to the c compiler for portability, the CC will be defined using the compiler's "real name" (i.e. gcc or clang).
+ This helps lousy build systems that inspect on the name of the compiler rather than run it.
+
+
+
+
Perl
- Adds the lib/site_perl subdirectory
- of each build input to the PERL5LIB
- environment variable.
+
+
+ Adds the lib/site_perl subdirectory of each build input to the PERL5LIB environment variable.
+ For instance, if buildInputs contains Perl, then the lib/site_perl subdirectory of each input is added to the PERL5LIB environment variable.
+
+
@@ -1482,6 +1802,20 @@ someVar=$(stripHash $name)
disabled or patched to work with PaX.
+
+ autoPatchelfHook
+ This is a special setup hook which helps in packaging
+ proprietary software in that it automatically tries to find missing shared
+ library dependencies of ELF files. All packages within the
+ runtimeDependencies environment variable are unconditionally
+ added to executables, which is useful for programs that use
+
+ dlopen
+ 3
+
+ to load libraries at runtime.
+
+
diff --git a/doc/style.css b/doc/style.css
index ac76a64bbb21..0db907815b6b 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -29,8 +29,8 @@ h2 /* chapters, appendices, subtitle */
}
/* Extra space between chapters, appendices. */
-div.chapter > div.titlepage h2, div.appendix > div.titlepage h2
-{
+div.chapter > div.titlepage h2, div.appendix > div.titlepage h2
+{
margin-top: 1.5em;
}
@@ -104,7 +104,7 @@ pre.screen, pre.programlisting
padding: 3px 3px;
margin-left: 1.5em;
margin-right: 1.5em;
- color: #600000;
+
background: #f4f4f8;
font-family: monospace;
border-radius: 0.4em;
@@ -118,7 +118,6 @@ div.example pre.programlisting
margin: 0 0 0 0;
}
-
/***************************************************************************
Notes, warnings etc:
***************************************************************************/
@@ -172,7 +171,7 @@ div.navfooter *
/***************************************************************************
- Links colors and highlighting:
+ Links colors and highlighting:
***************************************************************************/
a { text-decoration: none; }
@@ -209,7 +208,7 @@ tt, code
.term
{
font-weight: bold;
-
+
}
div.variablelist dd p, div.glosslist dd p
@@ -249,7 +248,24 @@ table
box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
}
+table.simplelist
+{
+ text-align: left;
+ color: #005aa0;
+ border: 0;
+ padding: 5px;
+ background: #fffff5;
+ font-weight: normal;
+ font-style: italic;
+ box-shadow: none;
+ margin-bottom: 1em;
+}
+
+div.navheader table, div.navfooter table {
+ box-shadow: none;
+}
+
div.affiliation
{
font-style: italic;
-}
\ No newline at end of file
+}
diff --git a/doc/submitting-changes.xml b/doc/submitting-changes.xml
index f65b2898262e..d3cf221c9b69 100644
--- a/doc/submitting-changes.xml
+++ b/doc/submitting-changes.xml
@@ -317,11 +317,11 @@ Additional information.
review uncommitted changes:
- nix-shell -p nox --run nox-review wip
+ nix-shell -p nox --run "nox-review wip"
review changes from pull request number 12345:
- nix-shell -p nox --run nox-review pr 12345
+ nix-shell -p nox --run "nox-review pr 12345"
diff --git a/lib/customisation.nix b/lib/customisation.nix
index 483ef6fd4866..d942f54ee798 100644
--- a/lib/customisation.nix
+++ b/lib/customisation.nix
@@ -1,7 +1,7 @@
{ lib }:
let
- inherit (builtins) attrNames isFunction;
+ inherit (builtins) attrNames;
in
@@ -36,7 +36,7 @@ rec {
overrideDerivation = drv: f:
let
newDrv = derivation (drv.drvAttrs // (f drv));
- in addPassthru newDrv (
+ in lib.flip (extendDerivation true) newDrv (
{ meta = drv.meta or {};
passthru = if drv ? passthru then drv.passthru else {};
}
@@ -72,7 +72,7 @@ rec {
makeOverridable = f: origArgs:
let
ff = f origArgs;
- overrideWith = newArgs: origArgs // (if builtins.isFunction newArgs then newArgs origArgs else newArgs);
+ overrideWith = newArgs: origArgs // (if lib.isFunction newArgs then newArgs origArgs else newArgs);
in
if builtins.isAttrs ff then (ff // {
override = newArgs: makeOverridable f (overrideWith newArgs);
@@ -81,7 +81,7 @@ rec {
${if ff ? overrideAttrs then "overrideAttrs" else null} = fdrv:
makeOverridable (args: (f args).overrideAttrs fdrv) origArgs;
})
- else if builtins.isFunction ff then {
+ else if lib.isFunction ff then {
override = newArgs: makeOverridable f (overrideWith newArgs);
__functor = self: ff;
overrideDerivation = throw "overrideDerivation not yet supported for functors";
@@ -112,8 +112,8 @@ rec {
*/
callPackageWith = autoArgs: fn: args:
let
- f = if builtins.isFunction fn then fn else import fn;
- auto = builtins.intersectAttrs (builtins.functionArgs f) autoArgs;
+ f = if lib.isFunction fn then fn else import fn;
+ auto = builtins.intersectAttrs (lib.functionArgs f) autoArgs;
in makeOverridable f (auto // args);
@@ -122,8 +122,8 @@ rec {
individual attributes. */
callPackagesWith = autoArgs: fn: args:
let
- f = if builtins.isFunction fn then fn else import fn;
- auto = builtins.intersectAttrs (builtins.functionArgs f) autoArgs;
+ f = if lib.isFunction fn then fn else import fn;
+ auto = builtins.intersectAttrs (lib.functionArgs f) autoArgs;
origArgs = auto // args;
pkgs = f origArgs;
mkAttrOverridable = name: pkg: makeOverridable (newArgs: (f newArgs).${name}) origArgs;
@@ -131,8 +131,8 @@ rec {
/* Add attributes to each output of a derivation without changing
- the derivation itself. */
- addPassthru = drv: passthru:
+ the derivation itself and check a given condition when evaluating. */
+ extendDerivation = condition: passthru: drv:
let
outputs = drv.outputs or [ "out" ];
@@ -142,13 +142,18 @@ rec {
outputToAttrListElement = outputName:
{ name = outputName;
value = commonAttrs // {
- inherit (drv.${outputName}) outPath drvPath type outputName;
+ inherit (drv.${outputName}) type outputName;
+ drvPath = assert condition; drv.${outputName}.drvPath;
+ outPath = assert condition; drv.${outputName}.outPath;
};
};
outputsList = map outputToAttrListElement outputs;
- in commonAttrs // { outputUnspecified = true; };
-
+ in commonAttrs // {
+ outputUnspecified = true;
+ drvPath = assert condition; drv.drvPath;
+ outPath = assert condition; drv.outPath;
+ };
/* Strip a derivation of all non-essential attributes, returning
only those needed by hydra-eval-jobs. Also strictly evaluate the
diff --git a/lib/debug.nix b/lib/debug.nix
index 646ef220ad0a..d163e60b6957 100644
--- a/lib/debug.nix
+++ b/lib/debug.nix
@@ -2,10 +2,10 @@
let
-inherit (builtins) trace attrNamesToStr isAttrs isFunction isList isInt
+inherit (builtins) trace attrNamesToStr isAttrs isList isInt
isString isBool head substring attrNames;
-inherit (lib) all id mapAttrsFlatten elem;
+inherit (lib) all id mapAttrsFlatten elem isFunction;
in
diff --git a/lib/default.nix b/lib/default.nix
index 3e30ec515fcb..c292ed33e1da 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -5,9 +5,11 @@
*/
let
- callLibs = file: import file { inherit lib; };
+ inherit (import ./fixed-points.nix {}) makeExtensible;
- lib = rec {
+ lib = makeExtensible (self: let
+ callLibs = file: import file { lib = self; };
+ in with self; {
# often used, or depending on very little
trivial = callLibs ./trivial.nix;
@@ -21,10 +23,10 @@ let
# packaging
customisation = callLibs ./customisation.nix;
- maintainers = callLibs ./maintainers.nix;
+ maintainers = import ../maintainers/maintainer-list.nix;
meta = callLibs ./meta.nix;
sources = callLibs ./sources.nix;
-
+ versions = callLibs ./versions.nix;
# module system
modules = callLibs ./modules.nix;
@@ -41,23 +43,23 @@ let
generators = callLibs ./generators.nix;
misc = callLibs ./deprecated.nix;
# domain-specific
- sandbox = callLibs ./sandbox.nix;
fetchers = callLibs ./fetchers.nix;
# Eval-time filesystem handling
filesystem = callLibs ./filesystem.nix;
# back-compat aliases
- platforms = systems.doubles;
+ platforms = systems.forMeta;
inherit (builtins) add addErrorContext attrNames
concatLists deepSeq elem elemAt filter genericClosure genList
- getAttr hasAttr head isAttrs isBool isFunction isInt isList
+ getAttr hasAttr head isAttrs isBool isInt isList
isString length lessThan listToAttrs pathExists readFile
replaceStrings seq stringLength sub substring tail;
inherit (trivial) id const concat or and boolToString mergeAttrs
flip mapNullable inNixShell min max importJSON warn info
- nixpkgsVersion mod;
+ nixpkgsVersion mod compare splitByAndCompare
+ functionArgs setFunctionArgs isFunction;
inherit (fixedPoints) fix fix' extends composeExtensions
makeExtensible makeExtensibleWithCustomName;
@@ -72,8 +74,8 @@ let
inherit (lists) singleton 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 take drop sublist last init
- crossLists unique intersectLists subtractLists
+ reverseList listDfs toposort sort naturalSort compareLists take drop sublist
+ last init crossLists unique intersectLists subtractLists
mutuallyExclusive;
inherit (strings) concatStrings concatMapStrings concatImapStrings
intersperse concatStringsSep concatMapStringsSep
@@ -88,13 +90,14 @@ let
inherit (stringsWithDeps) textClosureList textClosureMap
noDepEntry fullDepEntry packEntry stringAfter;
inherit (customisation) overrideDerivation makeOverridable
- callPackageWith callPackagesWith addPassthru hydraJob makeScope;
+ callPackageWith callPackagesWith extendDerivation
+ hydraJob makeScope;
inherit (meta) addMetaAttrs dontDistribute setName updateName
appendToName mapDerivationAttrset lowPrio lowPrioSet hiPrio
hiPrioSet;
inherit (sources) pathType pathIsDirectory cleanSourceFilter
cleanSource sourceByRegex sourceFilesBySuffices
- commitIdFromGitRepo;
+ commitIdFromGitRepo cleanSourceWith pathHasContext canCleanSource;
inherit (modules) evalModules closeModules unifyModuleSyntax
applyIfFunction unpackSubmodule packSubmodule mergeModules
mergeModules' mergeOptionDecls evalOptionValue mergeDefinitions
@@ -127,5 +130,5 @@ let
mergeAttrsNoOverride mergeAttrByFunc mergeAttrsByFuncDefaults
mergeAttrsByFuncDefaultsClean mergeAttrBy
prepareDerivationArgs nixType imap overridableDelayableArgs;
- };
+ });
in lib
diff --git a/lib/deprecated.nix b/lib/deprecated.nix
index 2a0f5a55bf14..34cf336d1f42 100644
--- a/lib/deprecated.nix
+++ b/lib/deprecated.nix
@@ -1,6 +1,6 @@
{ lib }:
let
- inherit (builtins) isFunction head tail isList isAttrs isInt attrNames;
+ inherit (builtins) head tail isList isAttrs isInt attrNames;
in
@@ -53,7 +53,7 @@ rec {
f: # the function applied to the arguments
initial: # you pass attrs, the functions below are passing a function taking the fix argument
let
- takeFixed = if isFunction initial then initial else (fixed : initial); # transform initial to an expression always taking the fixed argument
+ takeFixed = if lib.isFunction initial then initial else (fixed : initial); # transform initial to an expression always taking the fixed argument
tidy = args:
let # apply all functions given in "applyPreTidy" in sequence
applyPreTidyFun = fold ( n: a: x: n ( a x ) ) lib.id (maybeAttr "applyPreTidy" [] args);
@@ -63,7 +63,7 @@ rec {
let args = takeFixed fixed;
mergeFun = args.${n};
in if isAttrs x then (mergeFun args x)
- else assert isFunction x;
+ else assert lib.isFunction x;
mergeFun args (x ( args // { inherit fixed; }));
in overridableDelayableArgs f newArgs;
in
@@ -374,7 +374,7 @@ rec {
if isAttrs x then
if x ? outPath then "derivation"
else "attrs"
- else if isFunction x then "function"
+ else if lib.isFunction x then "function"
else if isList x then "list"
else if x == true then "bool"
else if x == false then "bool"
diff --git a/lib/generators.nix b/lib/generators.nix
index 5f9da234f447..d1a8f6bf8dcd 100644
--- a/lib/generators.nix
+++ b/lib/generators.nix
@@ -4,6 +4,12 @@
* They all follow a similar interface:
* generator { config-attrs } data
*
+ * `config-attrs` are “holes” in the generators
+ * with sensible default implementations that
+ * can be overwritten. The default implementations
+ * are mostly generators themselves, called with
+ * their respective default values; they can be reused.
+ *
* Tests can be found in ./tests.nix
* Documentation in the manual, #sec-generators
*/
@@ -14,19 +20,54 @@ let
libAttr = lib.attrsets;
flipMapAttrs = flip libAttr.mapAttrs;
+
+ inherit (lib) isFunction;
in
rec {
+ ## -- HELPER FUNCTIONS & DEFAULTS --
+
+ /* Convert a value to a sensible default string representation.
+ * The builtin `toString` function has some strange defaults,
+ * suitable for bash scripts but not much else.
+ */
+ mkValueStringDefault = {}: v: with builtins;
+ let err = t: v: abort
+ ("generators.mkValueStringDefault: " +
+ "${t} not supported: ${toPretty {} v}");
+ in if isInt v then toString v
+ # we default to not quoting strings
+ else if isString v then v
+ # isString returns "1", which is not a good default
+ else if true == v then "true"
+ # here it returns to "", which is even less of a good default
+ else if false == v then "false"
+ else if null == v then "null"
+ # if you have lists you probably want to replace this
+ else if isList v then err "lists" v
+ # same as for lists, might want to replace
+ else if isAttrs v then err "attrsets" v
+ else if isFunction v then err "functions" v
+ else err "this value is" (toString v);
+
+
/* Generate a line of key k and value v, separated by
* character sep. If sep appears in k, it is escaped.
* Helper for synaxes with different separators.
*
- * mkKeyValueDefault ":" "f:oo" "bar"
+ * mkValueString specifies how values should be formatted.
+ *
+ * mkKeyValueDefault {} ":" "f:oo" "bar"
* > "f\:oo:bar"
*/
- mkKeyValueDefault = sep: k: v:
- "${libStr.escape [sep] k}${sep}${toString v}";
+ mkKeyValueDefault = {
+ mkValueString ? mkValueStringDefault {}
+ }: sep: k: v:
+ "${libStr.escape [sep] k}${sep}${mkValueString v}";
+
+
+ ## -- FILE FORMAT GENERATORS --
/* Generate a key-value-style config file from an attrset.
@@ -34,7 +75,7 @@ rec {
* mkKeyValue is the same as in toINI.
*/
toKeyValue = {
- mkKeyValue ? mkKeyValueDefault "="
+ mkKeyValue ? mkKeyValueDefault {} "="
}: attrs:
let mkLine = k: v: mkKeyValue k v + "\n";
in libStr.concatStrings (libAttr.mapAttrsToList mkLine attrs);
@@ -64,7 +105,7 @@ rec {
# apply transformations (e.g. escapes) to section names
mkSectionName ? (name: libStr.escape [ "[" "]" ] name),
# format a setting line from key and value
- mkKeyValue ? mkKeyValueDefault "="
+ mkKeyValue ? mkKeyValueDefault {} "="
}: attrsOfAttrs:
let
# map function to string for each key val
@@ -92,6 +133,7 @@ rec {
*/
toYAML = {}@args: toJSON args;
+
/* Pretty print a value, akin to `builtins.trace`.
* Should probably be a builtin as well.
*/
@@ -102,11 +144,12 @@ rec {
allowPrettyValues ? false
}@args: v: with builtins;
if isInt v then toString v
- else if isBool v then (if v == true then "true" else "false")
- else if isString v then "\"" + v + "\""
+ else if isString v then ''"${libStr.escape [''"''] v}"''
+ else if true == v then "true"
+ else if false == v then "false"
else if null == v then "null"
else if isFunction v then
- let fna = functionArgs v;
+ let fna = lib.functionArgs v;
showFnas = concatStringsSep "," (libAttr.mapAttrsToList
(name: hasDefVal: if hasDefVal then "(${name})" else name)
fna);
@@ -126,6 +169,6 @@ rec {
(name: value:
"${toPretty args name} = ${toPretty args value};") v)
+ " }"
- else "toPretty: should never happen (v = ${v})";
+ else abort "generators.toPretty: should never happen (v = ${v})";
}
diff --git a/lib/licenses.nix b/lib/licenses.nix
index cbd737dc57f1..767fd89b948c 100644
--- a/lib/licenses.nix
+++ b/lib/licenses.nix
@@ -2,7 +2,7 @@
let
spdx = lic: lic // {
- url = "http://spdx.org/licenses/${lic.spdxId}";
+ url = "http://spdx.org/licenses/${lic.spdxId}.html";
};
in
@@ -15,7 +15,12 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
afl21 = spdx {
spdxId = "AFL-2.1";
- fullName = "Academic Free License";
+ fullName = "Academic Free License v2.1";
+ };
+
+ afl3 = spdx {
+ spdxId = "AFL-3.0";
+ fullName = "Academic Free License v3.0";
};
agpl3 = spdx {
@@ -74,6 +79,11 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
fullName = ''Beerware License'';
};
+ bsd0 = spdx {
+ spdxId = "0BSD";
+ fullName = "BSD Zero Clause License";
+ };
+
bsd2 = spdx {
spdxId = "BSD-2-Clause";
fullName = ''BSD 2-clause "Simplified" License'';
@@ -89,6 +99,11 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
fullName = ''BSD 4-clause "Original" or "Old" License'';
};
+ clArtistic = spdx {
+ spdxId = "ClArtistic";
+ fullName = "Clarified Artistic License";
+ };
+
cc0 = spdx {
spdxId = "CC0-1.0";
fullName = "Creative Commons Zero v1.0 Universal";
@@ -164,6 +179,11 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
fullName = "CeCILL-C Free Software License Agreement";
};
+ cpal10 = spdx {
+ spdxId = "CPAL-1.0";
+ fullName = "Common Public Attribution License 1.0";
+ };
+
cpl10 = spdx {
spdxId = "CPL-1.0";
fullName = "Common Public License 1.0";
@@ -195,6 +215,11 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
fullName = "Eclipse Public License 1.0";
};
+ epl20 = spdx {
+ spdxId = "EPL-2.0";
+ fullName = "Eclipse Public License 2.0";
+ };
+
epson = {
fullName = "Seiko Epson Corporation Software License Agreement for Linux";
url = https://download.ebz.epson.net/dsc/du/02/eula/global/LINUX_EN.html;
@@ -259,7 +284,7 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
gpl2Oss = {
fullName = "GNU General Public License version 2 only (with OSI approved licenses linking exception)";
- url = http://www.mysql.com/about/legal/licensing/foss-exception;
+ url = https://www.mysql.com/about/legal/licensing/foss-exception;
};
gpl2Plus = spdx {
@@ -304,6 +329,12 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
free = false;
};
+ inria-icesl = {
+ fullName = "INRIA Non-Commercial License Agreement for IceSL";
+ url = "http://shapeforge.loria.fr/icesl/EULA_IceSL_binary.pdf";
+ free = false;
+ };
+
ipa = spdx {
spdxId = "IPA";
fullName = "IPA Font License";
@@ -426,6 +457,11 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
fullName = "Notion modified LGPL";
};
+ nposl3 = spdx {
+ spdxId = "NPOSL-3.0";
+ fullName = "Non-Profit Open Software License 3.0";
+ };
+
ofl = spdx {
spdxId = "OFL-1.1";
fullName = "SIL Open Font License 1.1";
@@ -441,6 +477,16 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
fullName = "OpenSSL License";
};
+ osl21 = spdx {
+ spdxId = "OSL-2.1";
+ fullName = "Open Software License 2.1";
+ };
+
+ osl3 = spdx {
+ spdxId = "OSL-3.0";
+ fullName = "Open Software License 3.0";
+ };
+
php301 = spdx {
spdxId = "PHP-3.01";
fullName = "PHP License v3.01";
@@ -451,6 +497,12 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
fullName = "PostgreSQL License";
};
+ postman = {
+ fullName = "Postman EULA";
+ url = https://www.getpostman.com/licenses/postman_base_app;
+ free = false;
+ };
+
psfl = spdx {
spdxId = "Python-2.0";
fullName = "Python Software Foundation License version 2";
@@ -538,6 +590,11 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
fullName = "Vovida Software License v1.0";
};
+ watcom = spdx {
+ spdxId = "Watcom-1.0";
+ fullName = "Sybase Open Watcom Public License 1.0";
+ };
+
w3c = spdx {
spdxId = "W3C";
fullName = "W3C Software Notice and License";
@@ -572,5 +629,4 @@ lib.mapAttrs (n: v: v // { shortName = n; }) rec {
spdxId = "ZPL-2.1";
fullName = "Zope Public License 2.1";
};
-
}
diff --git a/lib/lists.nix b/lib/lists.nix
index 8f67c6bb0ca3..5ec97f5a07f3 100644
--- a/lib/lists.nix
+++ b/lib/lists.nix
@@ -1,7 +1,9 @@
# General list operations.
{ lib }:
with lib.trivial;
-
+let
+ inherit (lib.strings) toInt;
+in
rec {
inherit (builtins) head tail length isList elemAt concatLists filter elem genList;
@@ -385,6 +387,49 @@ rec {
if len < 2 then list
else (sort strictLess pivot.left) ++ [ first ] ++ (sort strictLess pivot.right));
+ /* Compare two lists element-by-element.
+
+ Example:
+ compareLists compare [] []
+ => 0
+ compareLists compare [] [ "a" ]
+ => -1
+ compareLists compare [ "a" ] []
+ => 1
+ compareLists compare [ "a" "b" ] [ "a" "c" ]
+ => 1
+ */
+ compareLists = cmp: a: b:
+ if a == []
+ then if b == []
+ then 0
+ else -1
+ else if b == []
+ then 1
+ else let rel = cmp (head a) (head b); in
+ if rel == 0
+ then compareLists cmp (tail a) (tail b)
+ else rel;
+
+ /* Sort list using "Natural sorting".
+ Numeric portions of strings are sorted in numeric order.
+
+ Example:
+ naturalSort ["disk11" "disk8" "disk100" "disk9"]
+ => ["disk8" "disk9" "disk11" "disk100"]
+ naturalSort ["10.46.133.149" "10.5.16.62" "10.54.16.25"]
+ => ["10.5.16.62" "10.46.133.149" "10.54.16.25"]
+ naturalSort ["v0.2" "v0.15" "v0.0.9"]
+ => [ "v0.0.9" "v0.2" "v0.15" ]
+ */
+ naturalSort = lst:
+ let
+ vectorise = s: map (x: if isList x then toInt (head x) else x) (builtins.split "(0|[1-9][0-9]*)" s);
+ prepared = map (x: [ (vectorise x) x ]) lst; # remember vectorised version for O(n) regex splits
+ less = a: b: (compareLists compare (head a) (head b)) < 0;
+ in
+ map (x: elemAt x 1) (sort less prepared);
+
/* Return the first (at most) N elements of a list.
Example:
@@ -440,8 +485,12 @@ rec {
init = list: assert list != []; take (length list - 1) list;
- /* FIXME(zimbatm) Not used anywhere
- */
+ /* return the image of the cross product of some lists by a function
+
+ Example:
+ crossLists (x:y: "${toString x}${toString y}") [[1 2] [3 4]]
+ => [ "13" "14" "23" "24" ]
+ */
crossLists = f: foldl (fs: args: concatMap (f: map f args) fs) [f];
diff --git a/lib/maintainers.nix b/lib/maintainers.nix
deleted file mode 100644
index f050904896fc..000000000000
--- a/lib/maintainers.nix
+++ /dev/null
@@ -1,723 +0,0 @@
-{ ...}:
-/* List of NixOS maintainers. The format is:
-
- handle = "Real Name ";
-
- where is preferred to be your GitHub username (so it's easy
- to ping a package @), and is your real name, not
- a pseudonym. Please keep the list alphabetically sorted. */
-{
- a1russell = "Adam Russell ";
- aaronschif = "Aaron Schif ";
- abaldeau = "Andreas Baldeau ";
- abbradar = "Nikolay Amiantov ";
- abigailbuccaneer = "Abigail Bunyan ";
- aboseley = "Adam Boseley ";
- abuibrahim = "Ruslan Babayev ";
- acowley = "Anthony Cowley ";
- adelbertc = "Adelbert Chang ";
- adev = "Adrien Devresse ";
- adisbladis = "Adam Hose ";
- Adjective-Object = "Maxwell Huang-Hobbs ";
- adnelson = "Allen Nelson ";
- adolfogc = "Adolfo E. García Castro ";
- aespinosa = "Allan Espinosa ";
- aflatter = "Alexander Flatter ";
- afldcr = "James Alexander Feldman-Crough ";
- aforemny = "Alexander Foremny ";
- afranchuk = "Alex Franchuk ";
- aherrmann = "Andreas Herrmann ";
- ahmedtd = "Taahir Ahmed ";
- ak = "Alexander Kjeldaas ";
- akaWolf = "Artjom Vejsel ";
- akc = "Anders Claesson ";
- alexvorobiev = "Alex Vorobiev ";
- dezgeg = "Tuomas Tynkkynen ";
- dfordivam = "Divam ";
- dfoxfranke = "Daniel Fox Franke ";
- dgonyeo = "Derek Gonyeo ";
- dipinhora = "Dipin Hora ";
- disassembler = "Samuel Leathers ";
- dizfer = "David Izquierdo ";
- dmalikov = "Dmitry Malikov ";
- DmitryTsygankov = "Dmitry Tsygankov ";
- dmjio = "David Johnson ";
- dochang = "Desmond O. Chang ";
- domenkozar = "Domen Kozar ";
- dotlambda = "Robert Schütz ";
- doublec = "Chris Double ";
- dpaetzel = "David Pätzel ";
- dpflug = "David Pflug ";
- drets = "Dmytro Rets ";
- drewkett = "Andrew Burkett ";
- dsferruzza = "David Sferruzza ";
- dtzWill = "Will Dietz ";
- dupgit = "Olivier Delhomme ";
- dywedir = "Vladyslav M. ";
- e-user = "Alexander Kahl ";
- earldouglas = "James Earl Douglas ";
- ebzzry = "Rommel Martinez ";
- edanaher = "Evan Danaher ";
- edef = "edef ";
- ederoyd46 = "Matthew Brown ";
- eduarrrd = "Eduard Bachmakov ";
- edwtjo = "Edward Tjörnhammar ";
- eelco = "Eelco Dolstra ";
- ehegnes = "Eric Hegnes ";
- ehmry = "Emery Hemingway ";
- eikek = "Eike Kettner ";
- ekleog = "Leo Gaspard ";
- elasticdog = "Aaron Bull Schaefer ";
- eleanor = "Dejan Lukan ";
- elijahcaine = "Elijah Caine ";
- elitak = "Eric Litak ";
- ellis = "Ellis Whitehead ";
- eperuffo = "Emanuele Peruffo ";
- epitrochoid = "Mabry Cervin ";
- eqyiel = "Ruben Maher ";
- ericbmerritt = "Eric Merritt ";
- ericsagnes = "Eric Sagnes ";
- erictapen = "Justin Humm ";
- erikryb = "Erik Rybakken ";
- ertes = "Ertugrul Söylemez ";
- ethercrow = "Dmitry Ivanov ";
- etu = "Elis Hirwing ";
- exi = "Reno Reckling ";
- exlevan = "Alexey Levan ";
- expipiplus1 = "Joe Hermaszewski ";
- fadenb = "Tristan Helmich ";
- falsifian = "James Cook ";
- fare = "Francois-Rene Rideau ";
- fgaz = "Francesco Gazzetta ";
- FireyFly = "Jonas Höglund ";
- flokli = "Florian Klink ";
- florianjacob = "Florian Jacob ";
- flosse = "Markus Kohlhase ";
- fluffynukeit = "Daniel Austin ";
- fmthoma = "Franz Thoma ";
- forkk = "Andrew Okin ";
- fornever = "Friedrich von Never ";
- fpletz = "Franz Pletz ";
- fps = "Florian Paul Schmidt ";
- fridh = "Frederik Rietdijk ";
- frlan = "Frank Lanitz ";
- fro_ozen = "fro_ozen ";
- ftrvxmtrx = "Siarhei Zirukin ";
- funfunctor = "Edward O'Callaghan ";
- fuuzetsu = "Mateusz Kowalczyk ";
- fuzzy-id = "Thomas Bach ";
- fxfactorial = "Edgar Aroutiounian ";
- gabesoft = "Gabriel Adomnicai ";
- gal_bolle = "Florent Becker ";
- garbas = "Rok Garbas ";
- garrison = "Jim Garrison ";
- gavin = "Gavin Rogers ";
- gebner = "Gabriel Ebner ";
- geistesk = "Alvar Penning ";
- georgewhewell = "George Whewell ";
- gilligan = "Tobias Pflug ";
- giogadi = "Luis G. Torres ";
- gleber = "Gleb Peregud ";
- glenns = "Glenn Searby ";
- globin = "Robin Gloster ";
- gnidorah = "Alex Ivanov ";
- goibhniu = "Cillian de Róiste ";
- Gonzih = "Max Gonzih ";
- goodrone = "Andrew Trachenko ";
- gpyh = "Yacine Hmito ";
- grahamc = "Graham Christensen ";
- grburst = "Julius Elias ";
- gridaphobe = "Eric Seidel ";
- guibert = "David Guibert ";
- guibou = "Guillaume Bouchard ";
- guillaumekoenig = "Guillaume Koenig ";
- guyonvarch = "Joris Guyonvarch ";
- hakuch = "Jesse Haber-Kucharsky ";
- hamhut1066 = "Hamish Hutchings ";
- havvy = "Ryan Scheel ";
- hbunke = "Hendrik Bunke ";
- hce = "Hans-Christian Esperer ";
- hectorj = "Hector Jusforgues ";
- hedning = "Tor Hedin Brønner ";
- heel = "Sergii Paryzhskyi ";
- henrytill = "Henry Till ";
- hhm = "hhm ";
- hinton = "Tom Hinton ";
- hodapp = "Chris Hodapp ";
- hrdinka = "Christoph Hrdinka ";
- htr = "Hugo Tavares Reis ";
- iand675 = "Ian Duncan ";
- ianwookim = "Ian-Woo Kim ";
- iblech = "Ingo Blechschmidt ";
- igsha = "Igor Sharonov ";
- ikervagyok = "Balázs Lengyel ";
- infinisil = "Silvan Mosberger ";
- ironpinguin = "Michele Catalano ";
- ivan-tkatchev = "Ivan Tkatchev ";
- ixmatus = "Parnell Springmeyer ";
- j-keck = "Jürgen Keck