commit 6ecc641d087df8b8896ebd876bba592e981877c9 · pyrox.dev/nixpkgs

+12 -13

doc/builders/fetchers.chapter.md

···

       20
       20
        
       

     

       21
       21
        
       `fetchpatch` works very similarly to `fetchurl` with the same arguments expected. It expects patch files as a source and performs normalization on them before computing the checksum. For example it will remove comments or other unstable parts that are sometimes added by version control systems and can change over time.

     

       22
       22
        
       

     

       23
       23
       -
       

     

       24
       23
        
       Other fetcher functions allow you to add source code directly from a VCS such as subversion or git. These are mostly straightforward nambes based on the name of the command used with the VCS system. Because they give you a working repository, they act most like `fetchzip`.

     

       25
       24
        
       

     

       26
       26
       -
       ## `fetchsvn`

     

       25
       25
       +
       ## `fetchsvn` {#fetchsvn}

     

       27
       26
        
       

     

       28
       27
        
       Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `sha256`.

     

       29
       28
        
       

     

       30
       30
       -
       ## `fetchgit`

     

       29
       29
       +
       ## `fetchgit` {#fetchgit}

     

       31
       30
        
       

     

       32
       31
        
       Used with Git. Expects `url` to a Git repo, `rev`, and `sha256`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`.

     

       33
       32
        
       

     

       34
       33
        
       Additionally the following optional arguments can be given: `fetchSubmodules = true` makes `fetchgit` also fetch the submodules of a repository. If `deepClone` is set to true, the entire repository is cloned as opposing to just creating a shallow clone. `deepClone = true` also implies `leaveDotGit = true` which means that the `.git` directory of the clone won't be removed after checkout.

     

       35
       34
        
       

     

       36
       36
       -
       ## `fetchfossil`

     

       35
       35
       +
       ## `fetchfossil` {#fetchfossil}

     

       37
       36
        
       

     

       38
       37
        
       Used with Fossil. Expects `url` to a Fossil archive, `rev`, and `sha256`.

     

       39
       38
        
       

     

       40
       40
       -
       ## `fetchcvs`

     

       39
       39
       +
       ## `fetchcvs` {#fetchcvs}

     

       41
       40
        
       

     

       42
       41
        
       Used with CVS. Expects `cvsRoot`, `tag`, and `sha256`.

     

       43
       42
        
       

     

       44
       44
       -
       ## `fetchhg`

     

       43
       43
       +
       ## `fetchhg` {#fetchhg}

     

       45
       44
        
       

     

       46
       45
        
       Used with Mercurial. Expects `url`, `rev`, and `sha256`.

     

       47
       46
        
       

     

       48
       47
        
       A number of fetcher functions wrap part of `fetchurl` and `fetchzip`. They are mainly convenience functions intended for commonly used destinations of source code in Nixpkgs. These wrapper fetchers are listed below.

     

       49
       48
        
       

     

       50
       50
       -
       ## `fetchFromGitHub`

     

       49
       49
       +
       ## `fetchFromGitHub` {#fetchfromgithub}

     

       51
       50
        
       

     

       52
       51
        
       `fetchFromGitHub` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `sha256` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available but `sha256` is currently preferred.

     

       53
       52
        
       

     

       54
       53
        
       `fetchFromGitHub` uses `fetchzip` to download the source archive generated by GitHub for the specified revision. If `leaveDotGit`, `deepClone` or `fetchSubmodules` are set to `true`, `fetchFromGitHub` will use `fetchgit` instead. Refer to its section for documentation of these options.

     

       55
       54
        
       

     

       56
       56
       -
       ## `fetchFromGitLab`

     

       55
       55
       +
       ## `fetchFromGitLab` {#fetchfromgitlab}

     

       57
       56
        
       

     

       58
       57
        
       This is used with GitLab repositories. The arguments expected are very similar to fetchFromGitHub above.

     

       59
       58
        
       

     

       60
       60
       -
       ## `fetchFromGitiles`

     

       59
       59
       +
       ## `fetchFromGitiles` {#fetchfromgitiles}

     

       61
       60
        
       

     

       62
       61
        
       This is used with Gitiles repositories. The arguments expected are similar to fetchgit.

     

       63
       62
        
       

     

       64
       64
       -
       ## `fetchFromBitbucket`

     

       63
       63
       +
       ## `fetchFromBitbucket` {#fetchfrombitbucket}

     

       65
       64
        
       

     

       66
       65
        
       This is used with BitBucket repositories. The arguments expected are very similar to fetchFromGitHub above.

     

       67
       66
        
       

     

       68
       68
       -
       ## `fetchFromSavannah`

     

       67
       67
       +
       ## `fetchFromSavannah` {#fetchfromsavannah}

     

       69
       68
        
       

     

       70
       69
        
       This is used with Savannah repositories. The arguments expected are very similar to fetchFromGitHub above.

     

       71
       70
        
       

     

       72
       72
       -
       ## `fetchFromRepoOrCz`

     

       71
       71
       +
       ## `fetchFromRepoOrCz` {#fetchfromrepoorcz}

     

       73
       72
        
       

     

       74
       73
        
       This is used with repo.or.cz repositories. The arguments expected are very similar to fetchFromGitHub above.

     

       75
       74
        
       

     

       76
       76
       -
       ## `fetchFromSourcehut`

     

       75
       75
       +
       ## `fetchFromSourcehut` {#fetchfromsourcehut}

     

       77
       76
        
       

     

       78
       77
        
       This is used with sourcehut repositories. The arguments expected are very similar to fetchFromGitHub above. Don't forget the tilde (~) in front of the user name!

+1 -1

doc/builders/images/appimagetools.section.md

···

       2
       2
        
       

     

       3
       3
        
       `pkgs.appimageTools` is a set of functions for extracting and wrapping [AppImage](https://appimage.org/) files. They are meant to be used if traditional packaging from source is infeasible, or it would take too long. To quickly run an AppImage file, `pkgs.appimage-run` can be used as well.

     

       4
       4
        
       

     

       5
       5
       -
       ::: warning

     

       5
       5
       +
       ::: {.warning}

     

       6
       6
        
       The `appimageTools` API is unstable and may be subject to backwards-incompatible changes in the future.

     

       7
       7
        
       :::

     

       8
       8

+2 -2

doc/builders/images/dockertools.section.md

···

       1
       1
        
       # pkgs.dockerTools {#sec-pkgs-dockerTools}

     

       2
       2
        
       

     

       3
       3
       -
       `pkgs.dockerTools` is a set of functions for creating and manipulating Docker images according to the [ Docker Image Specification v1.2.0 ](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#docker-image-specification-v120). Docker itself is not used to perform any of the operations done by these functions.

     

       3
       3
       +
       `pkgs.dockerTools` is a set of functions for creating and manipulating Docker images according to the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#docker-image-specification-v120). Docker itself is not used to perform any of the operations done by these functions.

     

       4
       4
        
       

     

       5
       5
        
       ## buildImage {#ssec-pkgs-dockerTools-buildImage}

     

       6
       6
        
       

     
···

       52
       52
        
       

     

       53
       53
        
       > **_NOTE:_** Using this parameter requires the `kvm` device to be available.

     

       54
       54
        
       

     

       55
       55
       -
       - `config` is used to specify the configuration of the containers that will be started off the built image in Docker. The available options are listed in the [ Docker Image Specification v1.2.0 ](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions).

     

       55
       55
       +
       - `config` is used to specify the configuration of the containers that will be started off the built image in Docker. The available options are listed in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions).

     

       56
       56
        
       

     

       57
       57
        
       After the new layer has been created, its closure (to which `contents`, `config` and `runAsRoot` contribute) will be copied in the layer itself. Only new dependencies that are not already in the existing layers will be copied.

     

       58
       58

+2 -2

doc/builders/images/snaptools.section.md

···

       14
       14
        
       

     

       15
       15
        
       The following expression packages GNU Hello as a Snapcraft snap.

     

       16
       16
        
       

     

       17
       17
       -
       ```{#ex-snapTools-buildSnap-hello .nix}

     

       17
       17
       +
       ``` {#ex-snapTools-buildSnap-hello .nix}

     

       18
       18
        
       let

     

       19
       19
        
         inherit (import <nixpkgs> { }) snapTools hello;

     

       20
       20
        
       in snapTools.makeSnap {

     
···

       35
       35
        
       

     

       36
       36
        
       Graphical programs require many more integrations with the host. This example uses Firefox as an example, because it is one of the most complicated programs we could package.

     

       37
       37
        
       

     

       38
       38
       -
       ```{#ex-snapTools-buildSnap-firefox .nix}

     

       38
       38
       +
       ``` {#ex-snapTools-buildSnap-firefox .nix}

     

       39
       39
        
       let

     

       40
       40
        
         inherit (import <nixpkgs> { }) snapTools firefox;

     

       41
       41
        
       in snapTools.makeSnap {

+3 -3

doc/builders/packages/cataclysm-dda.section.md

···

       1
       1
        
       # Cataclysm: Dark Days Ahead {#cataclysm-dark-days-ahead}

     

       2
       2
        
       

     

       3
       3
       -
       ## How to install Cataclysm DDA

     

       3
       3
       +
       ## How to install Cataclysm DDA {#how-to-install-cataclysm-dda}

     

       4
       4
        
       

     

       5
       5
        
       To install the latest stable release of Cataclysm DDA to your profile, execute

     

       6
       6
        
       `nix-env -f "<nixpkgs>" -iA cataclysm-dda`. For the curses build (build

     
···

       34
       34
        
       }

     

       35
       35
        
       ```

     

       36
       36
        
       

     

       37
       37
       -
       ## Important note for overriding packages

     

       37
       37
       +
       ## Important note for overriding packages {#important-note-for-overriding-packages}

     

       38
       38
        
       

     

       39
       39
        
       After applying `overrideAttrs`, you need to fix `passthru.pkgs` and

     

       40
       40
        
       `passthru.withMods` attributes either manually or by using `attachPkgs`:

     
···

       69
       69
        
       goodExample2.withMods (_: [])    # parallel building enabled

     

       70
       70
        
       ```

     

       71
       71
        
       

     

       72
       72
       -
       ## Customizing with mods

     

       72
       72
       +
       ## Customizing with mods {#customizing-with-mods}

     

       73
       73
        
       

     

       74
       74
        
       To install Cataclysm DDA with mods of your choice, you can use `withMods`

     

       75
       75
        
       attribute:

+1 -1

doc/builders/packages/elm.section.md

···

       6
       6
        
       nix-shell -p elmPackages.elm elmPackages.elm-format

     

       7
       7
        
       ```

     

       8
       8
        
       

     

       9
       9
       -
       To update the Elm compiler, see <filename>nixpkgs/pkgs/development/compilers/elm/README.md</filename>.

     

       9
       9
       +
       To update the Elm compiler, see `nixpkgs/pkgs/development/compilers/elm/README.md`.

     

       10
       10
        
       

     

       11
       11
        
       To package Elm applications, [read about elm2nix](https://github.com/hercules-ci/elm2nix#elm2nix).

+1 -1

doc/builders/packages/firefox.section.md

···

       1
       1
        
       # Firefox {#sec-firefox}

     

       2
       2
        
       

     

       3
       3
       -
       ## Build wrapped Firefox with extensions and policies

     

       3
       3
       +
       ## Build wrapped Firefox with extensions and policies {#build-wrapped-firefox-with-extensions-and-policies}

     

       4
       4
        
       

     

       5
       5
        
       The `wrapFirefox` function allows to pass policies, preferences and extension that are available to firefox. With the help of `fetchFirefoxAddon` this allows build a firefox version that already comes with addons pre-installed:

     

       6
       6

+2 -2

doc/builders/packages/opengl.section.md

···

       4
       4
        
       

     

       5
       5
        
       Broadly, we support both GL vendors: Mesa and NVIDIA.

     

       6
       6
        
       

     

       7
       7
       -
       ## NixOS Desktop

     

       7
       7
       +
       ## NixOS Desktop {#nixos-desktop}

     

       8
       8
        
       

     

       9
       9
        
       The NixOS desktop or other non-headless configurations are the primary target for OpenGL libraries and applications. The current solution for discovering which drivers are available is based on [libglvnd](https://gitlab.freedesktop.org/glvnd/libglvnd). `libglvnd` performs "vendor-neutral dispatch", trying a variety of techniques to find the system's GL implementation. In practice, this will be either via standard GLX for X11 users or EGL for Wayland users, and supporting either NVIDIA or Mesa extensions.

     

       10
       10
        
       

     

       11
       11
       -
       ## Nix on GNU/Linux

     

       11
       11
       +
       ## Nix on GNU/Linux {#nix-on-gnulinux}

     

       12
       12
        
       

     

       13
       13
        
       If you are using a non-NixOS GNU/Linux/X11 desktop with free software video drivers, consider launching OpenGL-dependent programs from Nixpkgs with Nixpkgs versions of `libglvnd` and `mesa.drivers` in `LD_LIBRARY_PATH`. For Mesa drivers, the Linux kernel version doesn't have to match nixpkgs.

     

       14
       14

+13 -10

doc/builders/packages/steam.section.md

···

       20
       20
        
       ## Troubleshooting {#sec-steam-troub}

     

       21
       21
        
       

     

       22
       22
        
       - **Steam fails to start. What do I do?**

     

       23
       23
       +
       

     

       23
       24
        
         Try to run

     

       24
       25
        
       

     

       25
       26
        
         ```ShellSession

     
···

       32
       33
        
       

     

       33
       34
        
         - The `newStdcpp` parameter was removed since NixOS 17.09 and should not be needed anymore.

     

       34
       35
        
         - Steam ships statically linked with a version of libcrypto that conflics with the one dynamically loaded by radeonsi_dri.so. If you get the error

     

       36
       36
       +
       

     

       35
       37
        
           ```

     

       36
       38
        
           steam.sh: line 713: 7842 Segmentation fault (core dumped)

     

       37
       39
        
           ```

     

       40
       40
       +
       

     

       38
       41
        
           have a look at [this pull request](https://github.com/NixOS/nixpkgs/pull/20269).

     

       39
       42
        
       

     

       40
       43
        
       - **Java**

     

       41
       44
        
       

     

       42
       45
        
         1. There is no java in steam chrootenv by default. If you get a message like

     

       43
       46
        
       

     

       44
       44
       -
         ```

     

       45
       45
       -
         /home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found

     

       46
       46
       -
         ```

     

       47
       47
       +
           ```

     

       48
       48
       +
           /home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found

     

       49
       49
       +
           ```

     

       47
       50
        
       

     

       48
       48
       -
         You need to add

     

       51
       51
       +
           you need to add

     

       49
       52
        
       

     

       50
       50
       -
         ```nix

     

       51
       51
       -
         steam.override { withJava = true; };

     

       52
       52
       -
         ```

     

       53
       53
       +
           ```nix

     

       54
       54
       +
           steam.override { withJava = true; };

     

       55
       55
       +
           ```

     

       53
       56
        
       

     

       54
       57
        
       ## steam-run {#sec-steam-run}

     

       55
       58
        
       

     
···

       57
       60
        
       

     

       58
       61
        
       ```nix

     

       59
       62
        
       pkgs.steam.override ({

     

       60
       60
       -
                 nativeOnly = true;

     

       61
       61
       -
                 newStdcpp = true;

     

       62
       62
       -
               }).run

     

       63
       63
       +
         nativeOnly = true;

     

       64
       64
       +
         newStdcpp = true;

     

       65
       65
       +
       }).run

     

       63
       66
        
       ```

     

       64
       67
        
       

     

       65
       68
        
       to your configuration, rebuild, and run the game with

+4 -4

doc/builders/packages/xorg.section.md

···

       2
       2
        
       

     

       3
       3
        
       The Nix expressions for the X.org packages reside in `pkgs/servers/x11/xorg/default.nix`. This file is automatically generated from lists of tarballs in an X.org release. As such it should not be modified directly; rather, you should modify the lists, the generator script or the file `pkgs/servers/x11/xorg/overrides.nix`, in which you can override or add to the derivations produced by the generator.

     

       4
       4
        
       

     

       5
       5
       -
       ## Katamari Tarballs

     

       5
       5
       +
       ## Katamari Tarballs {#katamari-tarballs}

     

       6
       6
        
       

     

       7
       7
        
       X.org upstream releases used to include [katamari](https://en.wiktionary.org/wiki/%E3%81%8B%E3%81%9F%E3%81%BE%E3%82%8A) releases, which included a holistic recommended version for each tarball, up until 7.7. To create a list of tarballs in a katamari release:

     

       8
       8
        
       

     
···

       14
       14
        
         | sort > "tarballs-$release.list"

     

       15
       15
        
       ```

     

       16
       16
        
       

     

       17
       17
       -
       ## Individual Tarballs

     

       17
       17
       +
       ## Individual Tarballs {#individual-tarballs}

     

       18
       18
        
       

     

       19
       19
        
       The upstream release process for [X11R7.8](https://x.org/wiki/Releases/7.8/) does not include a planned katamari. Instead, each component of X.org is released as its own tarball. We maintain `pkgs/servers/x11/xorg/tarballs.list` as a list of tarballs for each individual package. This list includes X.org core libraries and protocol descriptions, extra newer X11 interface libraries, like `xorg.libxcb`, and classic utilities which are largely unused but still available if needed, like `xorg.imake`.

     

       20
       20
        
       

     

       21
       21
       -
       ## Generating Nix Expressions

     

       21
       21
       +
       ## Generating Nix Expressions {#generating-nix-expressions}

     

       22
       22
        
       

     

       23
       23
        
       The generator is invoked as follows:

     

       24
       24
        
       

     
···

       29
       29
        
       

     

       30
       30
        
       For each of the tarballs in the `.list` files, the script downloads it, unpacks it, and searches its `configure.ac` and `*.pc.in` files for dependencies. This information is used to generate `default.nix`. The generator caches downloaded tarballs between runs. Pay close attention to the `NOT FOUND: $NAME` messages at the end of the run, since they may indicate missing dependencies. (Some might be optional dependencies, however.)

     

       31
       31
        
       

     

       32
       32
       -
       ## Overriding the Generator

     

       32
       32
       +
       ## Overriding the Generator {#overriding-the-generator}

     

       33
       33
        
       

     

       34
       34
        
       If the expression for a package requires derivation attributes that the generator cannot figure out automatically (say, `patches` or a `postInstall` hook), you should modify `pkgs/servers/x11/xorg/overrides.nix`.

+1 -1

doc/builders/trivial-builders.chapter.md

···

       37
       37
        
       

     

       38
       38
        
       Variant of `runCommand` that forces the derivation to be built locally, it is not substituted. This is intended for very cheap commands (<1s execution time). It saves on the network roundrip and can speed up a build.

     

       39
       39
        
       

     

       40
       40
       -
       ::: note

     

       40
       40
       +
       ::: {.note}

     

       41
       41
        
       This sets [`allowSubstitutes` to `false`](https://nixos.org/nix/manual/#adv-attr-allowSubstitutes), so only use `runCommandLocal` if you are certain the user will always have a builder for the `system` of the derivation. This should be true for most trivial use cases (e.g. just copying some files to a different location or adding symlinks), because there the `system` is usually the same as `builtins.currentSystem`.

     

       42
       42
        
       :::

     

       43
       43

+2 -2

doc/contributing/coding-conventions.chapter.md

···

462
462

463
463

For package updates it is enough to change one symbol to make hash fake. For new packages, you can use `lib.fakeSha256`, `lib.fakeSha512` or any other fake hash.

464
464

465
465
-
This is last resort method when reconstructing source URL is non-trivial and `nix-prefetch-url -A` isn't applicable (for example, [one of `kodi` dependencies](https://github.com/NixOS/nixpkgs/blob/d2ab091dd308b99e4912b805a5eb088dd536adb9/pkgs/applications/video/kodi/default.nix#L73")). The easiest way then would be replace hash with a fake one and rebuild. Nix build will fail and error message will contain desired hash.

465
465
+
This is last resort method when reconstructing source URL is non-trivial and `nix-prefetch-url -A` isn’t applicable (for example, [one of `kodi` dependencies](https://github.com/NixOS/nixpkgs/blob/d2ab091dd308b99e4912b805a5eb088dd536adb9/pkgs/applications/video/kodi/default.nix#L73)). The easiest way then would be replace hash with a fake one and rebuild. Nix build will fail and error message will contain desired hash.

466
466

467
467
-
::: warning

467
467
+
::: {.warning}

468
468

This method has security problems. Check below for details.

469
469

:::

470
470

+1 -1

doc/contributing/contributing-to-documentation.chapter.md

···

       25
       25
        
       

     

       26
       26
        
       ## Syntax {#sec-contributing-markup}

     

       27
       27
        
       

     

       28
       28
       -
       As per [RFC 0062](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.

     

       28
       28
       +
       As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.

     

       29
       29
        
       

     

       30
       30
        
       Additionally, the following syntax extensions are currently used:

     

       31
       31

+4 -1

doc/contributing/reviewing-contributions.chapter.md

···

       1
       1
        
       # Reviewing contributions {#chap-reviewing-contributions}

     

       2
       2
        
       

     

       3
       3
       -
       ::: warning

     

       3
       3
       +
       ::: {.warning}

     

       4
       4
        
       The following section is a draft, and the policy for reviewing is still being discussed in issues such as [#11166](https://github.com/NixOS/nixpkgs/issues/11166) and [#20836](https://github.com/NixOS/nixpkgs/issues/20836).

     

       5
       5
        
       :::

     

       6
       6
        
       

     
···

       35
       35
        
       - Building the package locally.

     

       36
       36
        
         - pull requests are often targeted to the master or staging branch, and building the pull request locally when it is submitted can trigger many source builds.

     

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

     

       38
       38
       +
       

     

       38
       39
        
           ```ShellSession

     

       39
       40
        
           $ git fetch origin nixos-unstable

     

       40
       41
        
           $ git fetch origin pull/PRNUMBER/head

     

       41
       42
        
           $ git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD

     

       42
       43
        
           ```

     

       44
       44
       +
       

     

       43
       45
        
           - The first command fetches the nixos-unstable branch.

     

       44
       46
        
           - The second command fetches 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.

     

       45
       47
        
           - The third command rebases the pull request changes to the nixos-unstable branch.

     

       46
       48
        
         - The [nixpkgs-review](https://github.com/Mic92/nixpkgs-review) tool can be used to review a pull request content in a single command. `PRNUMBER` should be replaced by the number at the end of the pull request title. You can also provide the full github pull request url.

     

       49
       49
       +
       

     

       47
       50
        
           ```ShellSession

     

       48
       51
        
           $ nix-shell -p nixpkgs-review --run "nixpkgs-review pr PRNUMBER"

     

       49
       52
        
           ```

+3 -1

doc/contributing/submitting-changes.chapter.md

···

       71
       71
        
       - If a new version fixing the vulnerability has been released, update the package;

     

       72
       72
        
       - If the security fix comes in the form of a patch and a CVE is available, then add the patch to the Nixpkgs tree, and apply it to the package.

     

       73
       73
        
         The name of the patch should be the CVE identifier, so e.g. `CVE-2019-13636.patch`; If a patch is fetched the name needs to be set as well, e.g.:

     

       74
       74
       +
       

     

       74
       75
        
         ```nix

     

       75
       76
        
         (fetchpatch {

     

       76
       77
        
           name = "CVE-2019-11068.patch";

     
···

       89
       90
        
       

     

       90
       91
        
       Before removing a package, one should try to find a new maintainer or fix smaller issues first.

     

       91
       92
        
       

     

       92
       92
       -
       ### Steps to remove a package from Nixpkgs

     

       93
       93
       +
       ### Steps to remove a package from Nixpkgs {#steps-to-remove-a-package-from-nixpkgs}

     

       93
       94
        
       

     

       94
       95
        
       We use jbidwatcher as an example for a discontinued project here.

     

       95
       96
        
       

     
···

       100
       101
        
       1. Add an alias for the package name in `pkgs/top-level/aliases.nix` (There is also `pkgs/misc/vim-plugins/aliases.nix`. Package sets typically do not have aliases, so we can't add them there.)

     

       101
       102
        
       

     

       102
       103
        
           For example in this case:

     

       104
       104
       +
       

     

       103
       105
        
           ```

     

       104
       106
        
           jbidwatcher = throw "jbidwatcher was discontinued in march 2021"; # added 2021-03-15

     

       105
       107
        
           ```

+21 -14

doc/languages-frameworks/agda.section.md

···

       1
       1
        
       # Agda {#agda}

     

       2
       2
        
       

     

       3
       3
       -
       ## How to use Agda

     

       3
       3
       +
       ## How to use Agda {#how-to-use-agda}

     

       4
       4
        
       

     

       5
       5
        
       Agda is available as the [agda](https://search.nixos.org/packages?channel=unstable&show=agda&from=0&size=30&sort=relevance&query=agda)

     

       6
       6
        
       package.

     
···

       43
       43
        
       ```

     

       44
       44
        
       

     

       45
       45
        
       You can also reference a GitHub repository

     

       46
       46
       +
       

     

       46
       47
        
       ```nix

     

       47
       48
        
       agda.withPackages (p: [

     

       48
       49
        
         (p.standard-library.overrideAttrs (oldAttrs: {

     
···

       59
       60
        
       

     

       60
       61
        
       If you want to use a library not added to Nixpkgs, you can add a

     

       61
       62
        
       dependency to a local library by calling `agdaPackages.mkDerivation`.

     

       63
       63
       +
       

     

       62
       64
        
       ```nix

     

       63
       65
        
       agda.withPackages (p: [

     

       64
       66
        
         (p.mkDerivation {

     
···

       92
       94
        
       Agda will not by default use these libraries. To tell Agda to use a library we have some options:

     

       93
       95
        
       

     

       94
       96
        
       * Call `agda` with the library flag:

     

       95
       95
       -
       ```ShellSession

     

       96
       96
       -
       $ agda -l standard-library -i . MyFile.agda

     

       97
       97
       -
       ```

     

       97
       97
       +
         ```ShellSession

     

       98
       98
       +
         $ agda -l standard-library -i . MyFile.agda

     

       99
       99
       +
         ```

     

       98
       100
        
       * Write a `my-library.agda-lib` file for the project you are working on which may look like:

     

       99
       99
       -
       ```

     

       100
       100
       -
       name: my-library

     

       101
       101
       -
       include: .

     

       102
       102
       -
       depend: standard-library

     

       103
       103
       -
       ```

     

       101
       101
       +
         ```

     

       102
       102
       +
         name: my-library

     

       103
       103
       +
         include: .

     

       104
       104
       +
         depend: standard-library

     

       105
       105
       +
         ```

     

       104
       106
        
       * Create the file `~/.agda/defaults` and add any libraries you want to use by default.

     

       105
       107
        
       

     

       106
       108
        
       More information can be found in the [official Agda documentation on library management](https://agda.readthedocs.io/en/v2.6.1/tools/package-system.html).

     

       107
       109
        
       

     

       108
       108
       -
       ## Compiling Agda

     

       110
       110
       +
       ## Compiling Agda {#compiling-agda}

     

       111
       111
       +
       

     

       109
       112
        
       Agda modules can be compiled using the GHC backend with the `--compile` flag. A version of `ghc` with `ieee754` is made available to the Agda program via the `--with-compiler` flag.

     

       110
       113
        
       This can be overridden by a different version of `ghc` as follows:

     

       111
       114
        
       

     
···

       116
       119
        
       }

     

       117
       120
        
       ```

     

       118
       121
        
       

     

       119
       119
       -
       ## Writing Agda packages

     

       122
       122
       +
       ## Writing Agda packages {#writing-agda-packages}

     

       123
       123
       +
       

     

       120
       124
        
       To write a nix derivation for an Agda library, first check that the library has a `*.agda-lib` file.

     

       121
       125
        
       

     

       122
       126
        
       A derivation can then be written using `agdaPackages.mkDerivation`. This has similar arguments to `stdenv.mkDerivation` with the following additions:

     
···

       140
       144
        
       }

     

       141
       145
        
       ```

     

       142
       146
        
       

     

       143
       143
       -
       ### Building Agda packages

     

       147
       147
       +
       ### Building Agda packages {#building-agda-packages}

     

       148
       148
       +
       

     

       144
       149
        
       The default build phase for `agdaPackages.mkDerivation` simply runs `agda` on the `Everything.agda` file.

     

       145
       150
        
       If something else is needed to build the package (e.g. `make`) then the `buildPhase` should be overridden.

     

       146
       151
        
       Additionally, a `preBuild` or `configurePhase` can be used if there are steps that need to be done prior to checking the `Everything.agda` file.

     

       147
       152
        
       `agda` and the Agda libraries contained in `buildInputs` are made available during the build phase.

     

       148
       153
        
       

     

       149
       149
       -
       ### Installing Agda packages

     

       154
       154
       +
       ### Installing Agda packages {#installing-agda-packages}

     

       155
       155
       +
       

     

       150
       156
        
       The default install phase copies Agda source files, Agda interface files (`*.agdai`) and `*.agda-lib` files to the output directory.

     

       151
       157
        
       This can be overridden.

     

       152
       158
        
       

     

       153
       159
        
       By default, Agda sources are files ending on `.agda`, or literate Agda files ending on `.lagda`, `.lagda.tex`, `.lagda.org`, `.lagda.md`, `.lagda.rst`. The list of recognised Agda source extensions can be extended by setting the `extraExtensions` config variable.

     

       154
       160
        
       

     

       155
       155
       -
       ## Adding Agda packages to Nixpkgs

     

       161
       161
       +
       ## Adding Agda packages to Nixpkgs {#adding-agda-packages-to-nixpkgs}

     

       156
       162
        
       

     

       157
       163
        
       To add an Agda package to `nixpkgs`, the derivation should be written to `pkgs/development/libraries/agda/${library-name}/` and an entry should be added to `pkgs/top-level/agda-packages.nix`. Here it is called in a scope with access to all other Agda libraries, so the top line of the `default.nix` can look like:

     

       158
       164
        
       

     
···

       182
       188
        
         '';

     

       183
       189
        
       }

     

       184
       190
        
       ```

     

       191
       191
       +
       

     

       185
       192
        
       This library has a file called `.agda-lib`, and so we give an empty string to `libraryFile` as nothing precedes `.agda-lib` in the filename. This file contains `name: IAL-1.3`, and so we let `libraryName =  "IAL-1.3"`. This library does not use an `Everything.agda` file and instead has a Makefile, so there is no need to set `everythingFile` and we set a custom `buildPhase`.

     

       186
       193
        
       

     

       187
       194
        
       When writing an Agda package it is essential to make sure that no `.agda-lib` file gets added to the store as a single file (for example by using `writeText`). This causes Agda to think that the nix store is a Agda library and it will attempt to write to it whenever it typechecks something. See [https://github.com/agda/agda/issues/4613](https://github.com/agda/agda/issues/4613).

+17 -16

doc/languages-frameworks/android.section.md

···

       3
       3
        
       The Android build environment provides three major features and a number of

     

       4
       4
        
       supporting features.

     

       5
       5
        
       

     

       6
       6
       -
       Deploying an Android SDK installation with plugins

     

       7
       7
       -
       --------------------------------------------------

     

       6
       6
       +
       ## Deploying an Android SDK installation with plugins {#deploying-an-android-sdk-installation-with-plugins}

     

       7
       7
       +
       

     

       8
       8
        
       The first use case is deploying the SDK with a desired set of plugins or subsets

     

       9
       9
        
       of an SDK.

     

       10
       10
        
       

     
···

       136
       136
        
       androidComposition.platform-tools

     

       137
       137
        
       ```

     

       138
       138
        
       

     

       139
       139
       -
       Using predefined Android package compositions

     

       140
       140
       -
       ---------------------------------------------

     

       139
       139
       +
       ## Using predefined Android package compositions {#using-predefined-android-package-compositions}

     

       140
       140
       +
       

     

       141
       141
        
       In addition to composing an Android package set manually, it is also possible

     

       142
       142
        
       to use a predefined composition that contains all basic packages for a specific

     

       143
       143
        
       Android version, such as version 9.0 (API-level 28).

     
···

       159
       159
        
       androidenv.androidPkgs_9_0.platform-tools

     

       160
       160
        
       ```

     

       161
       161
        
       

     

       162
       162
       -
       Building an Android application

     

       163
       163
       -
       -------------------------------

     

       162
       162
       +
       ## Building an Android application {#building-an-android-application}

     

       163
       163
       +
       

     

       164
       164
        
       In addition to the SDK, it is also possible to build an Ant-based Android

     

       165
       165
        
       project and automatically deploy all the Android plugins that a project

     

       166
       166
        
       requires.

     

       167
       167
       +
       

     

       167
       168
        
       

     

       168
       169
        
       ```nix

     

       169
       170
        
       with import <nixpkgs> {};

     
···

       199
       200
        
       installed on any Android device with a web browser by navigating to the build

     

       200
       201
        
       result page.

     

       201
       202
        
       

     

       202
       202
       -
       Spawning emulator instances

     

       203
       203
       -
       ---------------------------

     

       203
       203
       +
       ## Spawning emulator instances {#spawning-emulator-instances}

     

       204
       204
       +
       

     

       204
       205
        
       For testing purposes, it can also be quite convenient to automatically generate

     

       205
       206
        
       scripts that spawn emulator instances with all desired configuration settings.

     

       206
       207
        
       

     
···

       241
       242
        
       In addition to prebuilt APKs, you can also bind the APK parameter to a

     

       242
       243
        
       `buildApp {}` function invocation shown in the previous example.

     

       243
       244
        
       

     

       244
       244
       -
       Notes on environment variables in Android projects

     

       245
       245
       -
       --------------------------------------------------

     

       245
       245
       +
       ## Notes on environment variables in Android projects {#notes-on-environment-variables-in-android-projects}

     

       246
       246
       +
       

     

       246
       247
        
       * `ANDROID_SDK_ROOT` should point to the Android SDK. In your Nix expressions, this should be

     

       247
       248
        
         `${androidComposition.androidsdk}/libexec/android-sdk`. Note that `ANDROID_HOME` is deprecated,

     

       248
       249
        
         but if you rely on tools that need it, you can export it too.

     
···

       300
       301
        
       sdk.dir and ndk.dir values. This will ensure that the SDK and NDK directories will

     

       301
       302
        
       both be correct when you run Android Studio inside nix-shell.

     

       302
       303
        
       

     

       303
       303
       -
       Notes on improving build.gradle compatibility

     

       304
       304
       -
       ---------------------------------------------

     

       304
       304
       +
       ## Notes on improving build.gradle compatibility {#notes-on-improving-build.gradle-compatibility}

     

       305
       305
       +
       

     

       305
       306
        
       Ensure that your buildToolsVersion and ndkVersion match what is declared in androidenv.

     

       306
       307
        
       If you are using cmake, make sure its declared version is correct too.

     

       307
       308
        
       

     
···

       321
       322
        
       

     

       322
       323
        
       ```

     

       323
       324
        
       

     

       324
       324
       -
       Querying the available versions of each plugin

     

       325
       325
       -
       ----------------------------------------------

     

       325
       325
       +
       ## Querying the available versions of each plugin {#querying-the-available-versions-of-each-plugin}

     

       326
       326
       +
       

     

       326
       327
        
       repo.json provides all the options in one file now.

     

       327
       328
        
       

     

       328
       329
        
       A shell script in the `pkgs/development/mobile/androidenv/` subdirectory can be used to retrieve all

     
···

       334
       335
        
       

     

       335
       336
        
       The above command-line instruction queries all package versions in repo.json.

     

       336
       337
        
       

     

       337
       337
       -
       Updating the generated expressions

     

       338
       338
       -
       ----------------------------------

     

       338
       338
       +
       ## Updating the generated expressions {#updating-the-generated-expressions}

     

       339
       339
       +
       

     

       339
       340
        
       repo.json is generated from XML files that the Android Studio package manager uses.

     

       340
       341
        
       To update the expressions run the `generate.sh` script that is stored in the

     

       341
       342
        
       `pkgs/development/mobile/androidenv/` subdirectory:

+5 -5

doc/languages-frameworks/beam.section.md

···

       4
       4
        
       

     

       5
       5
        
       In this document and related Nix expressions, we use the term, _BEAM_, to describe the environment. BEAM is the name of the Erlang Virtual Machine and, as far as we're concerned, from a packaging perspective, all languages that run on the BEAM are interchangeable. That which varies, like the build system, is transparent to users of any given BEAM package, so we make no distinction.

     

       6
       6
        
       

     

       7
       7
       -
       ## Available versions and deprecations schedule

     

       7
       7
       +
       ## Available versions and deprecations schedule {#available-versions-and-deprecations-schedule}

     

       8
       8
        
       

     

       9
       9
       -
       ### Elixir

     

       9
       9
       +
       ### Elixir {#elixir}

     

       10
       10
        
       

     

       11
       11
        
       nixpkgs follows the [official elixir deprecation schedule](https://hexdocs.pm/elixir/compatibility-and-deprecations.html) and keeps the last 5 released versions of Elixir available.

     

       12
       12
        
       

     
···

       68
       68
        
       

     

       69
       69
        
       `mixRelease` is used to make a release in the mix sense. Dependencies will need to be fetched with `fetchMixDeps` and passed to it.

     

       70
       70
        
       

     

       71
       71
       -
       #### mixRelease - Elixir Phoenix example

     

       71
       71
       +
       #### mixRelease - Elixir Phoenix example {#mixrelease---elixir-phoenix-example}

     

       72
       72
        
       

     

       73
       73
        
       Here is how your `default.nix` file would look.

     

       74
       74
        
       

     
···

       148
       148
        
       - you can now `nix-build .`

     

       149
       149
        
       - To run the release, set the `RELEASE_TMP` environment variable to a directory that your program has write access to. It will be used to store the BEAM settings.

     

       150
       150
        
       

     

       151
       151
       -
       #### Example of creating a service for an Elixir - Phoenix project

     

       151
       151
       +
       #### Example of creating a service for an Elixir - Phoenix project {#example-of-creating-a-service-for-an-elixir---phoenix-project}

     

       152
       152
        
       

     

       153
       153
        
       In order to create a service with your release, you could add a `service.nix`

     

       154
       154
        
       in your project with the following

     
···

       228
       228
        
       }

     

       229
       229
        
       ```

     

       230
       230
        
       

     

       231
       231
       -
       #### Elixir - Phoenix project

     

       231
       231
       +
       #### Elixir - Phoenix project {#elixir---phoenix-project}

     

       232
       232
        
       

     

       233
       233
        
       Here is an example `shell.nix`.

     

       234
       234

+1 -1

doc/languages-frameworks/bower.section.md

···

       149
       149
        
       

     

       150
       150
        
       ## Troubleshooting {#ssec-bower2nix-troubleshooting}

     

       151
       151
        
       

     

       152
       152
       -
       ### ENOCACHE errors from buildBowerComponents

     

       152
       152
       +
       ### ENOCACHE errors from buildBowerComponents {#enocache-errors-from-buildbowercomponents}

     

       153
       153
        
       

     

       154
       154
        
       This means that Bower was looking for a package version which doesn't exist in the generated `bower-packages.nix`.

     

       155
       155

+2 -2

doc/languages-frameworks/coq.section.md

···

       1
       1
        
       # Coq and coq packages {#sec-language-coq}

     

       2
       2
        
       

     

       3
       3
       -
       ## Coq derivation: `coq`

     

       3
       3
       +
       ## Coq derivation: `coq` {#coq-derivation-coq}

     

       4
       4
        
       

     

       5
       5
        
       The Coq derivation is overridable through the `coq.override overrides`, where overrides is an attribute set which contains the arguments to override. We recommend overriding either of the following

     

       6
       6
        
       

     
···

       8
       8
        
       * `customOCamlPackage` (optional, defaults to `null`, which lets Coq choose a version automatically), which can be set to any of the ocaml packages attribute of `ocaml-ng` (such as `ocaml-ng.ocamlPackages_4_10` which is the default for Coq 8.11 for example).

     

       9
       9
        
       * `coq-version` (optional, defaults to the short version e.g. "8.10"), is a version number of the form "x.y" that indicates which Coq's version build behavior to mimic when using a source which is not a release. E.g. `coq.override { version = "d370a9d1328a4e1cdb9d02ee032f605a9d94ec7a"; coq-version = "8.10"; }`.

     

       10
       10
        
       

     

       11
       11
       -
       ## Coq packages attribute sets: `coqPackages`

     

       11
       11
       +
       ## Coq packages attribute sets: `coqPackages` {#coq-packages-attribute-sets-coqpackages}

     

       12
       12
        
       

     

       13
       13
        
       The recommended way of defining a derivation for a Coq library, is to use the `coqPackages.mkCoqDerivation` function, which is essentially a specialization of `mkDerivation` taking into account most of the specifics of Coq libraries. The following attributes are supported:

     

       14
       14

+3 -1

doc/languages-frameworks/crystal.section.md

···

       1
       1
        
       # Crystal {#crystal}

     

       2
       2
        
       

     

       3
       3
       -
       ## Building a Crystal package

     

       3
       3
       +
       ## Building a Crystal package {#building-a-crystal-package}

     

       4
       4
        
       

     

       5
       5
        
       This section uses [Mint](https://github.com/mint-lang/mint) as an example for how to build a Crystal package.

     

       6
       6
        
       

     

       7
       7
        
       If the Crystal project has any dependencies, the first step is to get a `shards.nix` file encoding those. Get a copy of the project and go to its root directory such that its `shard.lock` file is in the current directory, then run `crystal2nix` in it

     

       8
       8
       +
       

     

       8
       9
        
       ```bash

     

       9
       10
        
       $ git clone https://github.com/mint-lang/mint

     

       10
       11
        
       $ cd mint

     
···

       15
       16
        
       This should have generated a `shards.nix` file.

     

       16
       17
        
       

     

       17
       18
        
       Next create a Nix file for your derivation and use `pkgs.crystal.buildCrystalPackage` as follows:

     

       19
       19
       +
       

     

       18
       20
        
       ```nix

     

       19
       21
        
       with import <nixpkgs> {};

     

       20
       22
        
       crystal.buildCrystalPackage rec {

+7 -7

doc/languages-frameworks/dotnet.section.md

···

       1
       1
       -
       # Dotnet

     

       1
       1
       +
       # Dotnet {#dotnet}

     

       2
       2
        
       

     

       3
       3
       -
       ## Local Development Workflow

     

       3
       3
       +
       ## Local Development Workflow {#local-development-workflow}

     

       4
       4
        
       

     

       5
       5
        
       For local development, it's recommended to use nix-shell to create a dotnet environment:

     

       6
       6
        
       

     
···

       16
       16
        
       }

     

       17
       17
        
       ```

     

       18
       18
        
       

     

       19
       19
       -
       ### Using many sdks in a workflow

     

       19
       19
       +
       ### Using many sdks in a workflow {#using-many-sdks-in-a-workflow}

     

       20
       20
        
       

     

       21
       21
        
       It's very likely that more than one sdk will be needed on a given project. Dotnet provides several different frameworks (E.g dotnetcore, aspnetcore, etc.) as well as many versions for a given framework. Normally, dotnet is able to fetch a framework and install it relative to the executable. However, this would mean writing to the nix store in nixpkgs, which is read-only. To support the many-sdk use case, one can compose an environment using `dotnetCorePackages.combinePackages`:

     

       22
       22
        
       

     
···

       37
       37
        
       

     

       38
       38
        
       This will produce a dotnet installation that has the dotnet 3.1, 3.0, and 2.1 sdk. The first sdk listed will have it's cli utility present in the resulting environment. Example info output:

     

       39
       39
        
       

     

       40
       40
       -
       ```ShellSesssion

     

       40
       40
       +
       ```ShellSession

     

       41
       41
        
       $ dotnet --info

     

       42
       42
        
       .NET Core SDK (reflecting any global.json):

     

       43
       43
        
        Version:   3.1.101

     
···

       60
       60
        
         Microsoft.NETCore.App 3.1.1 [/nix/store/iiv98i2jdi226dgh4jzkkj2ww7f8jgpd-dotnet-core-combined/shared/Microsoft.NETCore.App]

     

       61
       61
        
       ```

     

       62
       62
        
       

     

       63
       63
       -
       ## dotnet-sdk vs dotnetCorePackages.sdk

     

       63
       63
       +
       ## dotnet-sdk vs dotnetCorePackages.sdk {#dotnet-sdk-vs-dotnetcorepackages.sdk}

     

       64
       64
        
       

     

       65
       65
        
       The `dotnetCorePackages.sdk_X_Y` is preferred over the old dotnet-sdk as both major and minor version are very important for a dotnet environment. If a given minor version isn't present (or was changed), then this will likely break your ability to build a project.

     

       66
       66
        
       

     

       67
       67
       -
       ## dotnetCorePackages.sdk vs dotnetCorePackages.net vs dotnetCorePackages.netcore vs dotnetCorePackages.aspnetcore

     

       67
       67
       +
       ## dotnetCorePackages.sdk vs dotnetCorePackages.net vs dotnetCorePackages.netcore vs dotnetCorePackages.aspnetcore {#dotnetcorepackages.sdk-vs-dotnetcorepackages.net-vs-dotnetcorepackages.netcore-vs-dotnetcorepackages.aspnetcore}

     

       68
       68
        
       

     

       69
       69
        
       The `dotnetCorePackages.sdk` contains both a runtime and the full sdk of a given version. The `net`, `netcore` and `aspnetcore` packages are meant to serve as minimal runtimes to deploy alongside already built applications. For runtime versions >= .NET 5 `net` is used while `netcore` is used for older .NET Core runtime version.

     

       70
       70
        
       

     

       71
       71
       -
       ## Packaging a Dotnet Application

     

       71
       71
       +
       ## Packaging a Dotnet Application {#packaging-a-dotnet-application}

     

       72
       72
        
       

     

       73
       73
        
       Ideally, we would like to build against the sdk, then only have the dotnet runtime available in the runtime closure.

     

       74
       74

+6 -8

doc/languages-frameworks/emscripten.section.md

···

       27
       27
        
           * dev-shell for zlib implementation hacking:

     

       28
       28
        
               * `nix-shell -A emscriptenPackages.zlib`

     

       29
       29
        
       

     

       30
       30
       -
       

     

       31
       31
       -
       ## Imperative usage

     

       30
       30
       +
       ## Imperative usage {#imperative-usage}

     

       32
       31
        
       

     

       33
       32
        
       A few things to note:

     

       34
       33
        
       

     

       35
       34
        
       * `export EMCC_DEBUG=2` is nice for debugging

     

       36
       35
        
       * `~/.emscripten`, the build artifact cache sometimes creates issues and needs to be removed from time to time

     

       37
       36
        
       

     

       38
       38
       -
       

     

       39
       39
       -
       ## Declarative usage

     

       37
       37
       +
       ## Declarative usage {#declarative-usage}

     

       40
       38
        
       

     

       41
       39
        
       Let's see two different examples from `pkgs/top-level/emscripten-packages.nix`:

     

       42
       40
        
       

     
···

       50
       48
        
       * Use `export EMCC_DEBUG=2` from within a emscriptenPackage's `phase` to get more detailed debug output what is going wrong.

     

       51
       49
        
       * ~/.emscripten cache is requiring us to set `HOME=$TMPDIR` in individual phases. This makes compilation slower but also makes it more deterministic.

     

       52
       50
        
       

     

       53
       53
       -
       ### Usage 1: pkgs.zlib.override

     

       51
       51
       +
       ### Usage 1: pkgs.zlib.override {#usage-1-pkgs.zlib.override}

     

       54
       52
        
       

     

       55
       53
        
       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...

     

       56
       54
        
       

     
···

       110
       108
        
             '';

     

       111
       109
        
           });

     

       112
       110
        
       

     

       113
       113
       -
       ### Usage 2: pkgs.buildEmscriptenPackage

     

       111
       111
       +
       ### Usage 2: pkgs.buildEmscriptenPackage {#usage-2-pkgs.buildemscriptenpackage}

     

       114
       112
        
       

     

       115
       113
        
       This `xmlmirror` example features a emscriptenPackage which is defined completely from this context and no `pkgs.zlib.override` is used.

     

       116
       114
        
       

     
···

       165
       163
        
             '';

     

       166
       164
        
           };

     

       167
       165
        
       

     

       168
       168
       -
       ### Declarative debugging

     

       166
       166
       +
       ### Declarative debugging {#declarative-debugging}

     

       169
       167
        
       

     

       170
       168
        
       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.

     

       171
       169
        
       

     
···

       177
       175
        
       6. `buildPhase`

     

       178
       176
        
       7. ... happy hacking...

     

       179
       177
        
       

     

       180
       180
       -
       ## Summary

     

       178
       178
       +
       ## Summary {#summary}

     

       181
       179
        
       

     

       182
       180
        
       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.

     

       183
       181

+1 -1

doc/languages-frameworks/gnome.section.md

···

       84
       84
        
       

     

       85
       85
        
       - []{#ssec-gnome-hooks-gobject-introspection} `gobject-introspection` setup hook populates `GI_TYPELIB_PATH` variable with `lib/girepository-1.0` directories of dependencies, which is then added to wrapper by `wrapGAppsHook`. It also adds `share` directories of dependencies to `XDG_DATA_DIRS`, which is intended to promote GIR files but it also [pollutes the closures](https://github.com/NixOS/nixpkgs/issues/32790) of packages using `wrapGAppsHook`.

     

       86
       86
        
       

     

       87
       87
       -
         ::: warning

     

       87
       87
       +
         ::: {.warning}

     

       88
       88
        
         The setup hook [currently](https://github.com/NixOS/nixpkgs/issues/56943) does not work in expressions with `strictDeps` enabled, like Python packages. In those cases, you will need to disable it with `strictDeps = false;`.

     

       89
       89
        
         :::

     

       90
       90

+2 -2

doc/languages-frameworks/go.section.md

···

       44
       44
        
       

     

       45
       45
        
       The function `buildGoPackage` builds legacy Go programs, not supporting Go modules.

     

       46
       46
        
       

     

       47
       47
       -
       ### Example for `buildGoPackage`

     

       47
       47
       +
       ### Example for `buildGoPackage` {#example-for-buildgopackage}

     

       48
       48
        
       

     

       49
       49
        
       In the following is an example expression using buildGoPackage, the following arguments are of special significance to the function:

     

       50
       50
        
       

     
···

       140
       140
        
       

     

       141
       141
        
       ### `subPackages` {#var-go-subPackages}

     

       142
       142
        
       

     

       143
       143
       -
       Limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built.

     

       143
       143
       +
       Limits the builder from building child packages that have not been listed. If `subPackages` is not specified, all child packages will be built.

+14 -12

doc/languages-frameworks/idris.section.md

···

       1
       1
        
       # Idris {#idris}

     

       2
       2
        
       

     

       3
       3
       -
       ## Installing Idris

     

       3
       3
       +
       ## Installing Idris {#installing-idris}

     

       4
       4
        
       

     

       5
       5
        
       The easiest way to get a working idris version is to install the `idris` attribute:

     

       6
       6
        
       

     

       7
       7
       -
       ```ShellSesssion

     

       7
       7
       +
       ```ShellSession

     

       8
       8
        
       $ # On NixOS

     

       9
       9
        
       $ nix-env -i nixos.idris

     

       10
       10
        
       $ # On non-NixOS

     
···

       21
       21
        
       

     

       22
       22
        
       And then:

     

       23
       23
        
       

     

       24
       24
       -
       ```ShellSesssion

     

       24
       24
       +
       ```ShellSession

     

       25
       25
        
       $ # On NixOS

     

       26
       26
        
       $ nix-env -iA nixos.myIdris

     

       27
       27
        
       $ # On non-NixOS

     
···

       29
       29
        
       ```

     

       30
       30
        
       

     

       31
       31
        
       To see all available Idris packages:

     

       32
       32
       -
       ```ShellSesssion

     

       32
       32
       +
       

     

       33
       33
       +
       ```ShellSession

     

       33
       34
        
       $ # On NixOS

     

       34
       35
        
       $ nix-env -qaPA nixos.idrisPackages

     

       35
       36
        
       $ # On non-NixOS

     
···

       37
       38
        
       ```

     

       38
       39
        
       

     

       39
       40
        
       Similarly, entering a `nix-shell`:

     

       40
       40
       -
       ```ShellSesssion

     

       41
       41
       +
       

     

       42
       42
       +
       ```ShellSession

     

       41
       43
        
       $ nix-shell -p 'idrisPackages.with-packages (with idrisPackages; [ contrib pruviloj ])'

     

       42
       44
        
       ```

     

       43
       45
        
       

     

       44
       44
       -
       ## Starting Idris with library support

     

       46
       46
       +
       ## Starting Idris with library support {#starting-idris-with-library-support}

     

       45
       47
        
       

     

       46
       48
        
       To have access to these libraries in idris, call it with an argument `-p <library name>` for each library:

     

       47
       49
        
       

     

       48
       48
       -
       ```ShellSesssion

     

       50
       50
       +
       ```ShellSession

     

       49
       51
        
       $ nix-shell -p 'idrisPackages.with-packages (with idrisPackages; [ contrib pruviloj ])'

     

       50
       52
        
       [nix-shell:~]$ idris -p contrib -p pruviloj

     

       51
       53
        
       ```

     

       52
       54
        
       

     

       53
       55
        
       A listing of all available packages the Idris binary has access to is available via `--listlibs`:

     

       54
       56
        
       

     

       55
       55
       -
       ```ShellSesssion

     

       57
       57
       +
       ```ShellSession

     

       56
       58
        
       $ idris --listlibs

     

       57
       59
        
       00prelude-idx.ibc

     

       58
       60
        
       pruviloj

     
···

       64
       66
        
       00contrib-idx.ibc

     

       65
       67
        
       ```

     

       66
       68
        
       

     

       67
       67
       -
       ## Building an Idris project with Nix

     

       69
       69
       +
       ## Building an Idris project with Nix {#building-an-idris-project-with-nix}

     

       68
       70
        
       

     

       69
       71
        
       As an example of how a Nix expression for an Idris package can be created, here is the one for `idrisPackages.yaml`:

     

       70
       72
        
       

     
···

       105
       107
        
       

     

       106
       108
        
       Assuming this file is saved as `yaml.nix`, it's buildable using

     

       107
       109
        
       

     

       108
       108
       -
       ```ShellSesssion

     

       110
       110
       +
       ```ShellSession

     

       109
       111
        
       $ nix-build -E '(import <nixpkgs> {}).idrisPackages.callPackage ./yaml.nix {}'

     

       110
       112
        
       ```

     

       111
       113
        
       

     
···

       121
       123
        
       

     

       122
       124
        
       in another file (say `default.nix`) to be able to build it with

     

       123
       125
        
       

     

       124
       124
       -
       ```ShellSesssion

     

       126
       126
       +
       ```ShellSession

     

       125
       127
        
       $ nix-build -A yaml

     

       126
       128
        
       ```

     

       127
       129
        
       

     

       128
       128
       -
       ## Passing options to `idris` commands

     

       130
       130
       +
       ## Passing options to `idris` commands {#passing-options-to-idris-commands}

     

       129
       131
        
       

     

       130
       132
        
       The `build-idris-package` function provides also optional input values to set additional options for the used `idris` commands.

     

       131
       133

+9 -8

doc/languages-frameworks/ios.section.md

···

       20
       20
        
       

     

       21
       21
        
       The Xcode build environment implements a number of features.

     

       22
       22
        
       

     

       23
       23
       -
       Deploying a proxy component wrapper exposing Xcode

     

       24
       24
       -
       --------------------------------------------------

     

       23
       23
       +
       ## Deploying a proxy component wrapper exposing Xcode {#deploying-a-proxy-component-wrapper-exposing-xcode}

     

       24
       24
       +
       

     

       25
       25
        
       The first use case is deploying a Nix package that provides symlinks to the Xcode

     

       26
       26
        
       installation on the host system. This package can be used as a build input to

     

       27
       27
        
       any build function implemented in the Nix expression language that requires

     
···

       55
       55
        
       lrwxr-xr-x  1 sander  staff  14  1 jan  1970 xcrun -> /usr/bin/xcrun

     

       56
       56
        
       ```

     

       57
       57
        
       

     

       58
       58
       -
       Building an iOS application

     

       59
       59
       -
       ---------------------------

     

       58
       58
       +
       ## Building an iOS application {#building-an-ios-application}

     

       59
       59
       +
       

     

       60
       60
        
       We can build an iOS app executable for the simulator, or an IPA/xcarchive file

     

       61
       61
        
       for release purposes, e.g. ad-hoc, enterprise or store installations, by

     

       62
       62
        
       executing the `xcodeenv.buildApp {}` function:

     
···

       99
       99
        
       ```

     

       100
       100
        
       

     

       101
       101
        
       The above function takes a variety of parameters:

     

       102
       102
       +
       

     

       102
       103
        
       * The `name` and `src` parameters are mandatory and specify the name of the app

     

       103
       104
        
         and the location where the source code resides

     

       104
       105
        
       * `sdkVersion` specifies which version of the iOS SDK to use.

     
···

       151
       152
        
       `xcodeBaseDir` parameter can be overridden to refer to a different Xcode

     

       152
       153
        
       version.

     

       153
       154
        
       

     

       154
       154
       -
       Spawning simulator instances

     

       155
       155
       -
       ----------------------------

     

       155
       155
       +
       ## Spawning simulator instances {#spawning-simulator-instances}

     

       156
       156
       +
       

     

       156
       157
        
       In addition to building iOS apps, we can also automatically spawn simulator

     

       157
       158
        
       instances:

     

       158
       159
        
       

     
···

       213
       214
        
       By providing the result of an `xcode.buildApp {}` function and configuring the

     

       214
       215
        
       app bundle id, the app gets deployed automatically and started.

     

       215
       216
        
       

     

       216
       216
       -
       Troubleshooting

     

       217
       217
       -
       ---------------

     

       217
       217
       +
       ## Troubleshooting {#troubleshooting}

     

       218
       218
       +
       

     

       218
       219
        
       In some rare cases, it may happen that after a failure, changes are not picked

     

       219
       220
        
       up. Most likely, this is caused by a derived data cache that Xcode maintains.

     

       220
       221
        
       To wipe it you can run:

+33 -23

doc/languages-frameworks/lua.section.md

···

       1
       1
       -
       # User's Guide to Lua Infrastructure {#users-guide-to-lua-infrastructure}

     

       1
       1
       +
       # User’s Guide to Lua Infrastructure {#users-guide-to-lua-infrastructure}

     

       2
       2
        
       

     

       3
       3
       -
       ## Using Lua

     

       3
       3
       +
       ## Using Lua {#using-lua}

     

       4
       4
        
       

     

       5
       5
       -
       ### Overview of Lua

     

       5
       5
       +
       ### Overview of Lua {#overview-of-lua}

     

       6
       6
        
       

     

       7
       7
        
       Several versions of the Lua interpreter are available: luajit, lua 5.1, 5.2, 5.3.

     

       8
       8
        
       The attribute `lua` refers to the default interpreter, it is also possible to refer to specific versions, e.g. `lua5_2` refers to Lua 5.2.

     
···

       17
       17
        
       `luaPackages` refers to `lua5_1.pkgs` and `lua52Packages` to

     

       18
       18
        
       `lua5_2.pkgs`.

     

       19
       19
        
       

     

       20
       20
       -
       ### Installing Lua and packages

     

       20
       20
       +
       ### Installing Lua and packages {#installing-lua-and-packages}

     

       21
       21
        
       

     

       22
       22
       -
       #### Lua environment defined in separate `.nix` file

     

       22
       22
       +
       #### Lua environment defined in separate `.nix` file {#lua-environment-defined-in-separate-.nix-file}

     

       23
       23
        
       

     

       24
       24
        
       Create a file, e.g. `build.nix`, with the following expression

     

       25
       25
       +
       

     

       25
       26
        
       ```nix

     

       26
       27
        
       with import <nixpkgs> {};

     

       27
       28
        
       

     

       28
       29
        
       lua5_2.withPackages (ps: with ps; [ busted luafilesystem ])

     

       29
       30
        
       ```

     

       31
       31
       +
       

     

       30
       32
        
       and install it in your profile with

     

       33
       33
       +
       

     

       31
       34
        
       ```shell

     

       32
       35
        
       nix-env -if build.nix

     

       33
       36
        
       ```

     

       34
       37
        
       Now you can use the Lua interpreter, as well as the extra packages (`busted`,

     

       35
       38
        
       `luafilesystem`) that you added to the environment.

     

       36
       39
        
       

     

       37
       37
       -
       #### Lua environment defined in `~/.config/nixpkgs/config.nix`

     

       40
       40
       +
       #### Lua environment defined in `~/.config/nixpkgs/config.nix` {#lua-environment-defined-in-.confignixpkgsconfig.nix}

     

       38
       41
        
       

     

       39
       42
        
       If you prefer to, you could also add the environment as a package override to the Nixpkgs set, e.g.

     

       40
       43
        
       using `config.nix`,

     

       44
       44
       +
       

     

       41
       45
        
       ```nix

     

       42
       46
        
       { # ...

     

       43
       47
        
       

     
···

       46
       50
        
         };

     

       47
       51
        
       }

     

       48
       52
        
       ```

     

       53
       53
       +
       

     

       49
       54
        
       and install it in your profile with

     

       55
       55
       +
       

     

       50
       56
        
       ```shell

     

       51
       57
        
       nix-env -iA nixpkgs.myLuaEnv

     

       52
       58
        
       ```

     

       53
       59
        
       The environment is installed by referring to the attribute, and considering

     

       54
       60
        
       the `nixpkgs` channel was used.

     

       55
       61
        
       

     

       56
       56
       -
       #### Lua environment defined in `/etc/nixos/configuration.nix`

     

       62
       62
       +
       #### Lua environment defined in `/etc/nixos/configuration.nix` {#lua-environment-defined-in-etcnixosconfiguration.nix}

     

       57
       63
        
       

     

       58
       64
        
       For the sake of completeness, here's another example how to install the environment system-wide.

     

       59
       65
        
       

     
···

       66
       72
        
       }

     

       67
       73
        
       ```

     

       68
       74
        
       

     

       69
       69
       -
       ### How to override a Lua package using overlays?

     

       75
       75
       +
       ### How to override a Lua package using overlays? {#how-to-override-a-lua-package-using-overlays}

     

       70
       76
        
       

     

       71
       77
        
       Use the following overlay template:

     

       72
       78
        
       

     
···

       87
       93
        
       }

     

       88
       94
        
       ```

     

       89
       95
        
       

     

       90
       90
       -
       ### Temporary Lua environment with `nix-shell`

     

       96
       96
       +
       ### Temporary Lua environment with `nix-shell` {#temporary-lua-environment-with-nix-shell}

     

       91
       97
        
       

     

       92
       98
        
       

     

       93
       99
        
       There are two methods for loading a shell with Lua packages. The first and recommended method

     

       94
       100
        
       is to create an environment with `lua.buildEnv` or `lua.withPackages` and load that. E.g.

     

       101
       101
       +
       

     

       95
       102
        
       ```sh

     

       96
       103
        
       $ nix-shell -p 'lua.withPackages(ps: with ps; [ busted luafilesystem ])'

     

       97
       104
        
       ```

     

       105
       105
       +
       

     

       98
       106
        
       opens a shell from which you can launch the interpreter

     

       107
       107
       +
       

     

       99
       108
        
       ```sh

     

       100
       109
        
       [nix-shell:~] lua

     

       101
       110
        
       ```

     

       111
       111
       +
       

     

       102
       112
        
       The other method, which is not recommended, does not create an environment and requires you to list the packages directly,

     

       103
       113
        
       

     

       104
       114
        
       ```sh

     
···

       108
       118
        
       The Lua interpreter has the attribute `pkgs` which contains all Lua libraries for that specific interpreter.

     

       109
       119
        
       

     

       110
       120
        
       

     

       111
       111
       -
       ## Developing with Lua

     

       121
       121
       +
       ## Developing with Lua {#developing-with-lua}

     

       112
       122
        
       

     

       113
       123
        
       Now that you know how to get a working Lua environment with Nix, it is time

     

       114
       124
        
       to go forward and start actually developing with Lua. There are two ways to

     
···

       116
       126
        
       of by the luarocks2nix converter or the packaging has to be done manually.

     

       117
       127
        
       Let's present the luarocks way first and the manual one in a second time.

     

       118
       128
        
       

     

       119
       119
       -
       ### Packaging a library on luarocks

     

       129
       129
       +
       ### Packaging a library on luarocks {#packaging-a-library-on-luarocks}

     

       120
       130
        
       

     

       121
       131
        
       [Luarocks.org](www.luarocks.org) is the main repository of lua packages.

     

       122
       132
        
       The site proposes two types of packages, the rockspec and the src.rock

     
···

       135
       145
        
       Nix rely on luarocks to install lua packages, basically it runs:

     

       136
       146
        
       `luarocks make --deps-mode=none --tree $out`

     

       137
       147
        
       

     

       138
       138
       -
       #### Packaging a library manually

     

       148
       148
       +
       #### Packaging a library manually {#packaging-a-library-manually}

     

       139
       149
        
       

     

       140
       150
        
       You can develop your package as you usually would, just don't forget to wrap it

     

       141
       151
        
       within a `toLuaModule` call, for instance

     

       152
       152
       +
       

     

       142
       153
        
       ```nix

     

       143
       154
        
       mynewlib = toLuaModule ( stdenv.mkDerivation { ... });

     

       144
       155
        
       ```

     
···

       146
       157
        
       There is also the `buildLuaPackage` function that can be used when lua modules

     

       147
       158
        
       are not packaged for luarocks. You can see a few examples at `pkgs/top-level/lua-packages.nix`.

     

       148
       159
        
       

     

       149
       149
       -
       ## Lua Reference

     

       160
       160
       +
       ## Lua Reference {#lua-reference}

     

       150
       161
        
       

     

       151
       151
       -
       ### Lua interpreters

     

       162
       162
       +
       ### Lua interpreters {#lua-interpreters}

     

       152
       163
        
       

     

       153
       164
        
       Versions 5.1, 5.2 and 5.3 of the lua interpreter are available as

     

       154
       165
        
       respectively `lua5_1`, `lua5_2` and `lua5_3`. Luajit is available too.

     

       155
       166
        
       The Nix expressions for the interpreters can be found in `pkgs/development/interpreters/lua-5`.

     

       156
       167
        
       

     

       157
       157
       -
       

     

       158
       158
       -
       #### Attributes on lua interpreters packages

     

       168
       168
       +
       #### Attributes on lua interpreters packages {#attributes-on-lua-interpreters-packages}

     

       159
       169
        
       

     

       160
       170
        
       Each interpreter has the following attributes:

     

       161
       171
        
       

     
···

       164
       174
        
       - `withPackages`. Simpler interface to `buildEnv`.

     

       165
       175
        
       - `pkgs`. Set of Lua packages for that specific interpreter. The package set can be modified by overriding the interpreter and passing `packageOverrides`.

     

       166
       176
        
       

     

       167
       167
       -
       

     

       168
       168
       -
       #### `buildLuarocksPackage` function

     

       177
       177
       +
       #### `buildLuarocksPackage` function {#buildluarockspackage-function}

     

       169
       178
        
       

     

       170
       179
        
       The `buildLuarocksPackage` function is implemented in `pkgs/development/interpreters/lua-5/build-lua-package.nix`

     

       171
       180
        
       The following is an example:

     
···

       205
       214
        
       

     

       206
       215
        
       By default `meta.platforms` is set to the same value as the interpreter unless overridden otherwise.

     

       207
       216
        
       

     

       208
       208
       -
       #### `buildLuaApplication` function

     

       217
       217
       +
       #### `buildLuaApplication` function {#buildluaapplication-function}

     

       209
       218
        
       

     

       210
       219
        
       The `buildLuaApplication` function is practically the same as `buildLuaPackage`.

     

       211
       220
        
       The difference is that `buildLuaPackage` by default prefixes the names of the packages with the version of the interpreter.

     

       212
       221
        
       Because with an application we're not interested in multiple version the prefix is dropped.

     

       213
       222
        
       

     

       214
       214
       -
       #### lua.withPackages function

     

       223
       223
       +
       #### lua.withPackages function {#lua.withpackages-function}

     

       215
       224
        
       

     

       216
       225
        
       The `lua.withPackages` takes a function as an argument that is passed the set of lua packages and returns the list of packages to be included in the environment.

     

       217
       226
        
       Using the `withPackages` function, the previous example for the luafilesystem environment can be written like this:

     

       227
       227
       +
       

     

       218
       228
        
       ```nix

     

       219
       229
        
       with import <nixpkgs> {};

     

       220
       230
        
       

     
···

       223
       233
        
       

     

       224
       234
        
       `withPackages` passes the correct package set for the specific interpreter version as an argument to the function. In the above example, `ps` equals `luaPackages`.

     

       225
       235
        
       But you can also easily switch to using `lua5_2`:

     

       236
       236
       +
       

     

       226
       237
        
       ```nix

     

       227
       238
        
       with import <nixpkgs> {};

     

       228
       239
        
       

     
···

       231
       242
        
       

     

       232
       243
        
       Now, `ps` is set to `lua52Packages`, matching the version of the interpreter.

     

       233
       244
        
       

     

       234
       234
       -
       

     

       235
       235
       -
       ### Possible Todos

     

       245
       245
       +
       ### Possible Todos {#possible-todos}

     

       236
       246
        
       

     

       237
       247
        
       * export/use version specific variables such as `LUA_PATH_5_2`/`LUAROCKS_CONFIG_5_2`

     

       238
       248
        
       * let luarocks check for dependencies via exporting the different rocktrees in temporary config

     

       239
       249
        
       

     

       240
       240
       -
       ### Lua Contributing guidelines

     

       250
       250
       +
       ### Lua Contributing guidelines {#lua-contributing-guidelines}

     

       241
       251
        
       

     

       242
       252
        
       Following rules should be respected:

     

       243
       253

+10 -7

doc/languages-frameworks/maven.section.md

···

       43
       43
        
       

     

       44
       44
        
       You find this demo project at https://github.com/fzakaria/nixos-maven-example

     

       45
       45
        
       

     

       46
       46
       -
       ## Solving for dependencies

     

       46
       46
       +
       ## Solving for dependencies {#solving-for-dependencies}

     

       47
       47
        
       

     

       48
       48
       -
       ### buildMaven with NixOS/mvn2nix-maven-plugin

     

       48
       48
       +
       ### buildMaven with NixOS/mvn2nix-maven-plugin {#buildmaven-with-nixosmvn2nix-maven-plugin}

     

       49
       49
        
       

     

       50
       50
        
       > ⚠️ Although `buildMaven` is the "blessed" way within nixpkgs, as of 2020, it hasn't seen much activity in quite a while.

     

       51
       51
        
       

     
···

       82
       82
        
           A simple derivation that runs through `mvn compile` & `mvn package` to build the JAR. You may use this as inspiration for more complicated derivations.

     

       83
       83
        
       

     

       84
       84
        
       Here is an [example](https://github.com/fzakaria/nixos-maven-example/blob/main/build-maven-repository.nix) of building the Maven repository

     

       85
       85
       +
       

     

       85
       86
        
       ```nix

     

       86
       87
        
       { pkgs ? import <nixpkgs> { } }:

     

       87
       88
        
       with pkgs;

     
···

       103
       104
        
       │       └── 4.1.3

     

       104
       105
        
       │           ├── avalon-framework-4.1.3.jar -> /nix/store/iv5fp3955w3nq28ff9xfz86wvxbiw6n9-avalon-framework-4.1.3.jar

     

       105
       106
        
       ```

     

       106
       106
       -
       ### Double Invocation

     

       107
       107
       +
       

     

       108
       108
       +
       ### Double Invocation {#double-invocation}

     

       107
       109
        
       

     

       108
       110
        
       > ⚠️ This pattern is the simplest but may cause unnecessary rebuilds due to the output hash changing.

     

       109
       111
        
       

     
···

       163
       165
        
       

     

       164
       166
        
       If your package uses _SNAPSHOT_ dependencies or _version ranges_; there is a strong likelihood that over-time your output hash will change since the resolved dependencies may change. Hence this method is less recommended then using `buildMaven`.

     

       165
       167
        
       

     

       166
       166
       -
       ## Building a JAR

     

       168
       168
       +
       ## Building a JAR {#building-a-jar}

     

       167
       169
        
       

     

       168
       170
        
       Regardless of which strategy is chosen above, the step to build the derivation is the same.

     

       169
       171
        
       

     
···

       201
       203
        
       2 directories, 1 file

     

       202
       204
        
       ```

     

       203
       205
        
       

     

       204
       204
       -
       ## Runnable JAR

     

       206
       206
       +
       ## Runnable JAR {#runnable-jar}

     

       205
       207
        
       

     

       206
       208
        
       The previous example builds a `jar` file but that's not a file one can run.

     

       207
       209
        
       

     
···

       213
       215
        
       

     

       214
       216
        
       The following two methods are more suited to Nix then building an [UberJar](https://imagej.net/Uber-JAR) which may be the more traditional approach.

     

       215
       217
        
       

     

       216
       216
       -
       ### CLASSPATH

     

       218
       218
       +
       ### CLASSPATH {#classpath}

     

       217
       219
        
       

     

       218
       220
        
       > This is ideal if you are providing a derivation for _nixpkgs_ and don't want to patch the project's `pom.xml`.

     

       219
       221
        
       

     
···

       252
       254
        
       }

     

       253
       255
        
       ```

     

       254
       256
        
       

     

       255
       255
       -
       ### MANIFEST file via Maven Plugin

     

       257
       257
       +
       ### MANIFEST file via Maven Plugin {#manifest-file-via-maven-plugin}

     

       256
       258
        
       

     

       257
       259
        
       > This is ideal if you are the project owner and want to change your `pom.xml` to set the CLASSPATH within it.

     

       258
       260
        
       

     

       259
       261
        
       Augment the `pom.xml` to create a JAR with the following manifest:

     

       262
       262
       +
       

     

       260
       263
        
       ```xml

     

       261
       264
        
       <build>

     

       262
       265
        
         <plugins>

+64 -57

doc/languages-frameworks/python.section.md

···

       1
       1
        
       # Python {#python}

     

       2
       2
        
       

     

       3
       3
       -
       ## User Guide

     

       3
       3
       +
       ## User Guide {#user-guide}

     

       4
       4
        
       

     

       5
       5
       -
       ### Using Python

     

       5
       5
       +
       ### Using Python {#using-python}

     

       6
       6
        
       

     

       7
       7
       -
       #### Overview

     

       7
       7
       +
       #### Overview {#overview}

     

       8
       8
        
       

     

       9
       9
        
       Several versions of the Python interpreter are available on Nix, as well as a

     

       10
       10
        
       high amount of packages. The attribute `python3` refers to the default

     
···

       31
       31
        
       `pythonPackages` refers to `python.pkgs` and `python38Packages` to

     

       32
       32
        
       `python38.pkgs`.

     

       33
       33
        
       

     

       34
       34
       -
       #### Installing Python and packages

     

       34
       34
       +
       #### Installing Python and packages {#installing-python-and-packages}

     

       35
       35
        
       

     

       36
       36
        
       The Nix and NixOS manuals explain how packages are generally installed. In the

     

       37
       37
        
       case of Python and Nix, it is important to make a distinction between whether the

     
···

       62
       62
        
       of development: individual projects create their own Python environments without

     

       63
       63
        
       impacting the global environment or each other.

     

       64
       64
        
       

     

       65
       65
       -
       #### Ad-hoc temporary Python environment with `nix-shell`

     

       65
       65
       +
       #### Ad-hoc temporary Python environment with `nix-shell` {#ad-hoc-temporary-python-environment-with-nix-shell}

     

       66
       66
        
       

     

       67
       67
        
       The simplest way to start playing with the way nix wraps and sets up Python

     

       68
       68
        
       environments is with `nix-shell` at the cmdline. These environments create a

     
···

       131
       131
        
       interpreter and dependencies work in Nix and NixOS, but to do some actual

     

       132
       132
        
       development, we'll want to make it a bit more persistent.

     

       133
       133
        
       

     

       134
       134
       -
       ##### Running Python scripts and using `nix-shell` as shebang

     

       134
       134
       +
       ##### Running Python scripts and using `nix-shell` as shebang {#running-python-scripts-and-using-nix-shell-as-shebang}

     

       135
       135
        
       

     

       136
       136
        
       Sometimes, we have a script whose header looks like this:

     

       137
       137
        
       

     
···

       146
       146
        
       Executing this script requires a `python3` that has `numpy`. Using what we learned

     

       147
       147
        
       in the previous section, we could startup a shell and just run it like so:

     

       148
       148
        
       

     

       149
       149
       -
       ```ShellSesssion

     

       149
       149
       +
       ```ShellSession

     

       150
       150
        
       $ nix-shell -p 'python38.withPackages(ps: with ps; [ numpy ])' --run 'python3 foo.py'

     

       151
       151
        
       The dot product of [1 2] and [3 4] is: 11

     

       152
       152
        
       ```

     
···

       203
       203
        
       This is also a great way to ensure the script executes identically on different

     

       204
       204
        
       servers.

     

       205
       205
        
       

     

       206
       206
       -
       ##### Load environment from `.nix` expression

     

       206
       206
       +
       ##### Load environment from `.nix` expression {#load-environment-from-.nix-expression}

     

       207
       207
        
       

     

       208
       208
        
       We've now seen how to create an ad-hoc temporary shell session, and how to

     

       209
       209
        
       create a single script with Python dependencies, but in the course of normal

     
···

       262
       262
        
       like `libffi` the `openssl` in scope. This is generic and can span any number of

     

       263
       263
        
       tools or languages across the Nixpkgs ecosystem.

     

       264
       264
        
       

     

       265
       265
       -
       ##### Installing environments globally on the system

     

       265
       265
       +
       ##### Installing environments globally on the system {#installing-environments-globally-on-the-system}

     

       266
       266
        
       

     

       267
       267
        
       Up to now, we've been creating environments scoped to an ad-hoc shell session,

     

       268
       268
        
       or a single script, or a single project. This is generally advisable, as it

     
···

       315
       315
        
       atomically *uninstall* all other imperatively installed packages and replace

     

       316
       316
        
       your profile with just `myEnv` by using the `--replace` flag.

     

       317
       317
        
       

     

       318
       318
       -
       ##### Environment defined in `/etc/nixos/configuration.nix`

     

       318
       318
       +
       ##### Environment defined in `/etc/nixos/configuration.nix` {#environment-defined-in-etcnixosconfiguration.nix}

     

       319
       319
        
       

     

       320
       320
        
       For the sake of completeness, here's how to install the environment system-wide

     

       321
       321
        
       on NixOS.

     
···

       329
       329
        
       }

     

       330
       330
        
       ```

     

       331
       331
        
       

     

       332
       332
       -
       ### Developing with Python

     

       332
       332
       +
       ### Developing with Python {#developing-with-python}

     

       333
       333
        
       

     

       334
       334
        
       Above, we were mostly just focused on use cases and what to do to get started

     

       335
       335
        
       creating working Python environments in nix.

     
···

       338
       338
        
       back and take a deeper look at how Python packages are packaged on Nix. Then,

     

       339
       339
        
       we will look at how you can use development mode with your code.

     

       340
       340
        
       

     

       341
       341
       -
       #### Python library packages in Nixpkgs

     

       341
       341
       +
       #### Python library packages in Nixpkgs {#python-library-packages-in-nixpkgs}

     

       342
       342
        
       

     

       343
       343
        
       With Nix all packages are built by functions. The main function in Nix for

     

       344
       344
        
       building Python libraries is `buildPythonPackage`. Let's see how we can build the

     
···

       425
       425
        
       `toolz` from the Nixpkgs package set this time, but instead took our own version

     

       426
       426
        
       that we introduced with the `let` expression.

     

       427
       427
        
       

     

       428
       428
       -
       #### Handling dependencies

     

       428
       428
       +
       #### Handling dependencies {#handling-dependencies}

     

       429
       429
        
       

     

       430
       430
        
       Our example, `toolz`, does not have any dependencies on other Python packages or

     

       431
       431
        
       system libraries. According to the manual, `buildPythonPackage` uses the

     
···

       537
       537
        
         };

     

       538
       538
        
       }

     

       539
       539
        
       ```

     

       540
       540
       +
       

     

       540
       541
        
       Note also the line `doCheck = false;`, we explicitly disabled running the test-suite.

     

       541
       542
        
       

     

       542
       542
       -
       #### Testing Python Packages

     

       543
       543
       +
       #### Testing Python Packages {#testing-python-packages}

     

       543
       544
        
       

     

       544
       545
        
       It is highly encouraged to have testing as part of the package build. This

     

       545
       546
        
       helps to avoid situations where the package was able to build and install,

     
···

       559
       560
        
       as many tests should be enabled as possible. Failing tests can still be

     

       560
       561
        
       a good indication that the package is not in a valid state.

     

       561
       562
        
       

     

       562
       562
       -
       #### Using pytest

     

       563
       563
       +
       #### Using pytest {#using-pytest}

     

       563
       564
        
       

     

       564
       565
        
       Pytest is the most common test runner for python repositories. A trivial

     

       565
       566
        
       test run would be:

     

       567
       567
       +
       

     

       566
       568
        
       ```

     

       567
       569
        
         checkInputs = [ pytest ];

     

       568
       570
        
         checkPhase = "pytest";

     
···

       572
       574
        
       sandbox, and will generally need many tests to be disabled.

     

       573
       575
        
       

     

       574
       576
        
       To filter tests using pytest, one can do the following:

     

       577
       577
       +
       

     

       575
       578
        
       ```

     

       576
       579
        
         checkInputs = [ pytest ];

     

       577
       580
        
         # avoid tests which need additional data or touch network

     
···

       587
       590
        
       

     

       588
       591
        
       `-k` is used to define a predicate for test names. In this example, we are

     

       589
       592
        
       filtering out tests which contain `download` or `update` in their test case name.

     

       590
       590
       -
       Only one `-k` argument is allows, and thus a long predicate should be concatenated

     

       591
       591
       -
       with "\" and wrapped to the next line.

     

       593
       593
       +
       Only one `-k` argument is allowed, and thus a long predicate should be concatenated

     

       594
       594
       +
       with “\\” and wrapped to the next line.

     

       592
       595
        
       

     

       593
       593
       -
       *NOTE:* In pytest==6.0.1, the use of "\" to continue a line (e.g. `-k 'not download \'`) has

     

       596
       596
       +
       *NOTE:* In pytest==6.0.1, the use of “\\” to continue a line (e.g. `-k 'not download \'`) has

     

       594
       597
        
       been removed, in this case, it's recommended to use `pytestCheckHook`.

     

       595
       598
        
       

     

       596
       596
       -
       #### Using pytestCheckHook

     

       599
       599
       +
       #### Using pytestCheckHook {#using-pytestcheckhook}

     

       597
       600
        
       

     

       598
       601
        
       `pytestCheckHook` is a convenient hook which will substitute the setuptools

     

       599
       602
        
       `test` command for a checkPhase which runs `pytest`. This is also beneficial

     

       600
       603
        
       when a package may need many items disabled to run the test suite.

     

       601
       604
        
       

     

       602
       605
        
       Using the example above, the analagous pytestCheckHook usage would be:

     

       606
       606
       +
       

     

       603
       607
        
       ```

     

       604
       608
        
         checkInputs = [ pytestCheckHook ];

     

       605
       609
        
       

     
···

       637
       641
        
       would be much harder to read. This also enables us to comment on why specific tests

     

       638
       642
        
       are disabled.

     

       639
       643
        
       

     

       640
       640
       -
       #### Using pythonImportsCheck

     

       644
       644
       +
       #### Using pythonImportsCheck {#using-pythonimportscheck}

     

       641
       645
        
       

     

       642
       646
        
       Although unit tests are highly prefered to validate correctness of a package, not

     

       643
       647
        
       all packages have test suites that can be ran easily, and some have none at all.

     
···

       659
       663
        
       This can also be useful in verifying that the package doesn't assume commonly

     

       660
       664
        
       present packages (e.g. `setuptools`)

     

       661
       665
        
       

     

       662
       662
       -
       ### Develop local package

     

       666
       666
       +
       ### Develop local package {#develop-local-package}

     

       663
       667
        
       

     

       664
       668
        
       As a Python developer you're likely aware of [development mode](http://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode)

     

       665
       669
        
       (`python setup.py develop`); instead of installing the package this command

     
···

       694
       698
        
       It is important to note that due to how development mode is implemented on Nix

     

       695
       699
        
       it is not possible to have multiple packages simultaneously in development mode.

     

       696
       700
        
       

     

       697
       697
       -
       ### Organising your packages

     

       701
       701
       +
       ### Organising your packages {#organising-your-packages}

     

       698
       702
        
       

     

       699
       703
        
       So far we discussed how you can use Python on Nix, and how you can develop with

     

       700
       704
        
       it. We've looked at how you write expressions to package Python packages, and we

     
···

       706
       710
        
       duplication we now look at how you can maintain a repository with your

     

       707
       711
        
       own packages. The important functions here are `import` and `callPackage`.

     

       708
       712
        
       

     

       709
       709
       -
       ### Including a derivation using `callPackage`

     

       713
       713
       +
       ### Including a derivation using `callPackage` {#including-a-derivation-using-callpackage}

     

       710
       714
        
       

     

       711
       715
        
       Earlier we created a Python environment using `withPackages`, and included the

     

       712
       716
        
       `toolz` package via a `let` expression.

     
···

       756
       760
        
       example we use `buildPythonPackage` that is part of the set `python38Packages`,

     

       757
       761
        
       and in this case the `python38` interpreter is automatically used.

     

       758
       762
        
       

     

       759
       759
       -
       ## Reference

     

       763
       763
       +
       ## Reference {#reference}

     

       760
       764
        
       

     

       761
       761
       -
       ### Interpreters

     

       765
       765
       +
       ### Interpreters {#interpreters}

     

       762
       766
        
       

     

       763
       767
        
       Versions 2.7, 3.6, 3.7, 3.8 and 3.9 of the CPython interpreter are available as

     

       764
       768
        
       respectively `python27`, `python36`, `python37`, `python38` and `python39`. The

     
···

       773
       777
        
       `out/{python.sitePackages}` to `$PYTHONPATH` if such directory

     

       774
       778
        
       exists.

     

       775
       779
        
       

     

       776
       776
       -
       #### Missing `tkinter` module standard library

     

       780
       780
       +
       #### Missing `tkinter` module standard library {#missing-tkinter-module-standard-library}

     

       777
       781
        
       

     

       778
       782
        
       To reduce closure size the `Tkinter`/`tkinter` is available as a separate package, `pythonPackages.tkinter`.

     

       779
       783
        
       

     

       780
       780
       -
       #### Attributes on interpreters packages

     

       784
       784
       +
       #### Attributes on interpreters packages {#attributes-on-interpreters-packages}

     

       781
       785
        
       

     

       782
       786
        
       Each interpreter has the following attributes:

     

       783
       787
        
       

     
···

       789
       793
        
       - `executable`. Name of the interpreter executable, e.g. `python3.8`.

     

       790
       794
        
       - `pkgs`. Set of Python packages for that specific interpreter. The package set can be modified by overriding the interpreter and passing `packageOverrides`.

     

       791
       795
        
       

     

       792
       792
       -
       ### Optimizations

     

       796
       796
       +
       ### Optimizations {#optimizations}

     

       793
       797
        
       

     

       794
       798
        
       The Python interpreters are by default not build with optimizations enabled, because

     

       795
       799
        
       the builds are in that case not reproducible. To enable optimizations, override the

     
···

       806
       810
        
       in mypython

     

       807
       811
        
       ```

     

       808
       812
        
       

     

       809
       809
       -
       ### Building packages and applications

     

       813
       813
       +
       ### Building packages and applications {#building-packages-and-applications}

     

       810
       814
        
       

     

       811
       815
        
       Python libraries and applications that use `setuptools` or

     

       812
       816
        
       `distutils` are typically built with respectively the `buildPythonPackage` and

     
···

       838
       842
        
       * `pkgs.python3Packages` pointing to `pkgs.python38Packages`

     

       839
       843
        
       * `pkgs.pythonPackages` pointing to `pkgs.python2Packages`

     

       840
       844
        
       

     

       841
       841
       -
       #### `buildPythonPackage` function

     

       845
       845
       +
       #### `buildPythonPackage` function {#buildpythonpackage-function}

     

       842
       846
        
       

     

       843
       847
        
       The `buildPythonPackage` function is implemented in

     

       844
       848
        
       `pkgs/development/interpreters/python/mk-python-derivation`

     
···

       890
       894
        
       By default `meta.platforms` is set to the same value

     

       891
       895
        
       as the interpreter unless overridden otherwise.

     

       892
       896
        
       

     

       893
       893
       -
       ##### `buildPythonPackage` parameters

     

       897
       897
       +
       ##### `buildPythonPackage` parameters {#buildpythonpackage-parameters}

     

       894
       898
        
       

     

       895
       899
        
       All parameters from `stdenv.mkDerivation` function are still supported. The

     

       896
       900
        
       following are specific to `buildPythonPackage`:

     
···

       946
       950
        
         `buildPythonPackage` also injects code into and wraps executables with the

     

       947
       951
        
         paths included in this list. Items listed in `install_requires` go here.

     

       948
       952
        
       

     

       949
       949
       -
       ##### Overriding Python packages

     

       953
       953
       +
       ##### Overriding Python packages {#overriding-python-packages}

     

       950
       954
        
       

     

       951
       955
        
       The `buildPythonPackage` function has a `overridePythonAttrs` method that can be

     

       952
       956
        
       used to override the package. In the following example we create an environment

     
···

       974
       978
        
       in python.withPackages(ps: [ps.blaze])).env

     

       975
       979
        
       ```

     

       976
       980
        
       

     

       977
       977
       -
       #### `buildPythonApplication` function

     

       981
       981
       +
       #### `buildPythonApplication` function {#buildpythonapplication-function}

     

       978
       982
        
       

     

       979
       983
        
       The `buildPythonApplication` function is practically the same as

     

       980
       984
        
       `buildPythonPackage`. The main purpose of this function is to build a Python

     
···

       1019
       1023
        
       Since the package is an application, a consumer doesn't need to care about

     

       1020
       1024
        
       Python versions or modules, which is why they don't go in `pythonPackages`.

     

       1021
       1025
        
       

     

       1022
       1022
       -
       #### `toPythonApplication` function

     

       1026
       1026
       +
       #### `toPythonApplication` function {#topythonapplication-function}

     

       1023
       1027
        
       

     

       1024
       1028
        
       A distinction is made between applications and libraries, however, sometimes a

     

       1025
       1029
        
       package is used as both. In this case the package is added as a library to

     
···

       1031
       1035
        
       `python-packages.nix`. A reference shall be created from `all-packages.nix` to

     

       1032
       1036
        
       the attribute in `python-packages.nix`, and the `toPythonApplication` shall be

     

       1033
       1037
        
       applied to the reference:

     

       1038
       1038
       +
       

     

       1034
       1039
        
       ```nix

     

       1035
       1040
        
       youtube-dl = with pythonPackages; toPythonApplication youtube-dl;

     

       1036
       1041
        
       ```

     

       1037
       1042
        
       

     

       1038
       1038
       -
       #### `toPythonModule` function

     

       1043
       1043
       +
       #### `toPythonModule` function {#topythonmodule-function}

     

       1039
       1044
        
       

     

       1040
       1045
        
       In some cases, such as bindings, a package is created using

     

       1041
       1046
        
       `stdenv.mkDerivation` and added as attribute in `all-packages.nix`. The Python

     
···

       1052
       1057
        
       

     

       1053
       1058
        
       Do pay attention to passing in the right Python version!

     

       1054
       1059
        
       

     

       1055
       1055
       -
       #### `python.buildEnv` function

     

       1060
       1060
       +
       #### `python.buildEnv` function {#python.buildenv-function}

     

       1056
       1061
        
       

     

       1057
       1062
        
       Python environments can be created using the low-level `pkgs.buildEnv` function.

     

       1058
       1063
        
       This example shows how to create an environment that has the Pyramid Web Framework.

     
···

       1090
       1095
        
       will drop you into a shell where Python will have the

     

       1091
       1096
        
       specified packages in its path.

     

       1092
       1097
        
       

     

       1098
       1098
       +
       ##### `python.buildEnv` arguments {#python.buildenv-arguments}

     

       1093
       1099
        
       

     

       1094
       1094
       -
       ##### `python.buildEnv` arguments

     

       1095
       1100
        
       

     

       1096
       1101
        
       * `extraLibs`: List of packages installed inside the environment.

     

       1097
       1102
        
       * `postBuild`: Shell command executed after the build of environment.

     
···

       1099
       1104
        
       * `permitUserSite`: Skip setting the `PYTHONNOUSERSITE` environment variable in

     

       1100
       1105
        
         wrapped binaries in the environment.

     

       1101
       1106
        
       

     

       1102
       1102
       -
       #### `python.withPackages` function

     

       1107
       1107
       +
       #### `python.withPackages` function {#python.withpackages-function}

     

       1103
       1108
        
       

     

       1104
       1109
        
       The `python.withPackages` function provides a simpler interface to the `python.buildEnv` functionality.

     

       1105
       1110
        
       It takes a function as an argument that is passed the set of python packages and returns the list

     
···

       1141
       1146
        
       Python 2 namespace packages may provide `__init__.py` that collide. In that case

     

       1142
       1147
        
       `python.buildEnv` should be used with `ignoreCollisions = true`.

     

       1143
       1148
        
       

     

       1144
       1144
       -
       #### Setup hooks

     

       1149
       1149
       +
       #### Setup hooks {#setup-hooks}

     

       1145
       1150
        
       

     

       1146
       1151
        
       The following are setup hooks specifically for Python packages. Most of these

     

       1147
       1152
        
       are used in `buildPythonPackage`.

     
···

       1166
       1171
        
       - `wheelUnpackHook` to move a wheel to the correct folder so it can be installed

     

       1167
       1172
        
         with the `pipInstallHook`.

     

       1168
       1173
        
       

     

       1169
       1169
       -
       ### Development mode

     

       1174
       1174
       +
       ### Development mode {#development-mode}

     

       1170
       1175
        
       

     

       1171
       1176
        
       Development or editable mode is supported. To develop Python packages

     

       1172
       1177
        
       `buildPythonPackage` has additional logic inside `shellPhase` to run `pip

     
···

       1175
       1180
        
       Warning: `shellPhase` is executed only if `setup.py` exists.

     

       1176
       1181
        
       

     

       1177
       1182
        
       Given a `default.nix`:

     

       1183
       1183
       +
       

     

       1178
       1184
        
       ```nix

     

       1179
       1185
        
       with import <nixpkgs> {};

     

       1180
       1186
        
       

     
···

       1197
       1203
        
       

     

       1198
       1204
        
       Note: There is a boolean value `lib.inNixShell` set to `true` if nix-shell is invoked.

     

       1199
       1205
        
       

     

       1200
       1200
       -
       ### Tools

     

       1206
       1206
       +
       ### Tools {#tools}

     

       1201
       1207
        
       

     

       1202
       1208
        
       Packages inside nixpkgs are written by hand. However many tools exist in

     

       1203
       1209
        
       community to help save time. No tool is preferred at the moment.

     
···

       1209
       1215
        
       - [nixpkgs-pytools](https://github.com/nix-community/nixpkgs-pytools)

     

       1210
       1216
        
       - [poetry2nix](https://github.com/nix-community/poetry2nix)

     

       1211
       1217
        
       

     

       1212
       1212
       -
       ### Deterministic builds

     

       1218
       1218
       +
       ### Deterministic builds {#deterministic-builds}

     

       1213
       1219
        
       

     

       1214
       1220
        
       The Python interpreters are now built deterministically. Minor modifications had

     

       1215
       1221
        
       to be made to the interpreters in order to generate deterministic bytecode. This

     
···

       1221
       1227
        
       and [PYTHONHASHSEED=0](https://docs.python.org/3.8/using/cmdline.html#envvar-PYTHONHASHSEED).

     

       1222
       1228
        
       Both are also exported in `nix-shell`.

     

       1223
       1229
        
       

     

       1224
       1224
       -
       ### Automatic tests

     

       1230
       1230
       +
       ### Automatic tests {#automatic-tests}

     

       1225
       1231
        
       

     

       1226
       1232
        
       It is recommended to test packages as part of the build process.

     

       1227
       1233
        
       Source distributions (`sdist`) often include test files, but not always.

     
···

       1230
       1236
        
       `checkPhase`, but often it is necessary to pass a custom `checkPhase`. An

     

       1231
       1237
        
       example of such a situation is when `py.test` is used.

     

       1232
       1238
        
       

     

       1233
       1233
       -
       #### Common issues

     

       1239
       1239
       +
       #### Common issues {#common-issues}

     

       1234
       1240
        
       

     

       1235
       1241
        
       * Non-working tests can often be deselected. By default `buildPythonPackage`

     

       1236
       1242
        
         runs `python setup.py test`. Most Python modules follows the standard test

     
···

       1247
       1253
        
           '';

     

       1248
       1254
        
         }

     

       1249
       1255
        
         ```

     

       1256
       1256
       +
       

     

       1250
       1257
        
       * Tests that attempt to access `$HOME` can be fixed by using the following

     

       1251
       1258
        
         work-around before running tests (e.g. `preCheck`): `export HOME=$(mktemp -d)`

     

       1252
       1259
        
       

     

       1253
       1253
       -
       ## FAQ

     

       1260
       1260
       +
       ## FAQ {#faq}

     

       1254
       1261
        
       

     

       1255
       1255
       -
       ### How to solve circular dependencies?

     

       1262
       1262
       +
       ### How to solve circular dependencies? {#how-to-solve-circular-dependencies}

     

       1256
       1263
        
       

     

       1257
       1264
        
       Consider the packages `A` and `B` that depend on each other. When packaging `B`,

     

       1258
       1265
        
       a solution is to override package `A` not to depend on `B` as an input. The same

     

       1259
       1266
        
       should also be done when packaging `A`.

     

       1260
       1267
        
       

     

       1261
       1261
       -
       ### How to override a Python package?

     

       1268
       1268
       +
       ### How to override a Python package? {#how-to-override-a-python-package}

     

       1262
       1269
        
       

     

       1263
       1270
        
       We can override the interpreter and pass `packageOverrides`. In the following

     

       1264
       1271
        
       example we rename the `pandas` package and build it.

     
···

       1316
       1323
        
       in newpkgs.inkscape

     

       1317
       1324
        
       ```

     

       1318
       1325
        
       

     

       1319
       1319
       -
       ### `python setup.py bdist_wheel` cannot create .whl

     

       1326
       1326
       +
       ### `python setup.py bdist_wheel` cannot create .whl {#python-setup.py-bdist_wheel-cannot-create-.whl}

     

       1320
       1327
        
       

     

       1321
       1328
        
       Executing `python setup.py bdist_wheel` in a `nix-shell `fails with

     

       1322
       1329
        
       ```

     
···

       1349
       1356
        
       nix-shell --run "unset SOURCE_DATE_EPOCH; python3 setup.py bdist_wheel"

     

       1350
       1357
        
       ```

     

       1351
       1358
        
       

     

       1352
       1352
       -
       ### `install_data` / `data_files` problems

     

       1359
       1359
       +
       ### `install_data` / `data_files` problems {#install_data-data_files-problems}

     

       1353
       1360
        
       

     

       1354
       1361
        
       If you get the following error:

     

       1355
       1362
        
       

     
···

       1369
       1376
        
       sed -i '/ = data\_files/d' setup.py

     

       1370
       1377
        
       ```

     

       1371
       1378
        
       

     

       1372
       1372
       -
       ###  Rationale of non-existent global site-packages

     

       1379
       1379
       +
       ### Rationale of non-existent global site-packages {#rationale-of-non-existent-global-site-packages}

     

       1373
       1380
        
       

     

       1374
       1381
        
       On most operating systems a global `site-packages` is maintained. This however

     

       1375
       1382
        
       becomes problematic if you want to run multiple Python versions or have multiple

     
···

       1384
       1391
        
       method is to use `nix-shell`, either with or without the `python.buildEnv`

     

       1385
       1392
        
       function.

     

       1386
       1393
        
       

     

       1387
       1387
       -
       ### How to consume Python modules using pip in a virtual environment like I am used to on other Operating Systems?

     

       1394
       1394
       +
       ### How to consume Python modules using pip in a virtual environment like I am used to on other Operating Systems? {#how-to-consume-python-modules-using-pip-in-a-virtual-environment-like-i-am-used-to-on-other-operating-systems}

     

       1388
       1395
        
       

     

       1389
       1396
        
       While this approach is not very idiomatic from Nix perspective, it can still be

     

       1390
       1397
        
       useful when dealing with pre-existing projects or in situations where it's not

     
···

       1497
       1504
        
       requirements.txt. However these will be cached locally within the `virtualenv`

     

       1498
       1505
        
       folder and not downloaded again.

     

       1499
       1506
        
       

     

       1500
       1500
       -
       ### How to override a Python package from `configuration.nix`?

     

       1507
       1507
       +
       ### How to override a Python package from `configuration.nix`? {#how-to-override-a-python-package-from-configuration.nix}

     

       1501
       1508
        
       

     

       1502
       1509
        
       If you need to change a package's attribute(s) from `configuration.nix` you could do:

     

       1503
       1510
        
       

     
···

       1535
       1542
        
         }

     

       1536
       1543
        
       ```

     

       1537
       1544
        
       

     

       1538
       1538
       -
       ### How to override a Python package using overlays?

     

       1545
       1545
       +
       ### How to override a Python package using overlays? {#how-to-override-a-python-package-using-overlays}

     

       1539
       1546
        
       

     

       1540
       1547
        
       Use the following overlay template:

     

       1541
       1548
        
       

     
···

       1556
       1563
        
       }

     

       1557
       1564
        
       ```

     

       1558
       1565
        
       

     

       1559
       1559
       -
       ### How to use Intel's MKL with numpy and scipy?

     

       1566
       1566
       +
       ### How to use Intel’s MKL with numpy and scipy? {#how-to-use-intels-mkl-with-numpy-and-scipy}

     

       1560
       1567
        
       

     

       1561
       1568
        
       MKL can be configured using an overlay. See the section "[Using overlays to

     

       1562
       1569
        
       configure alternatives](#sec-overlays-alternatives-blas-lapack)".

     

       1563
       1570
        
       

     

       1564
       1564
       -
       ### What inputs do `setup_requires`, `install_requires` and `tests_require` map to?

     

       1571
       1571
       +
       ### What inputs do `setup_requires`, `install_requires` and `tests_require` map to? {#what-inputs-do-setup_requires-install_requires-and-tests_require-map-to}

     

       1565
       1572
        
       

     

       1566
       1573
        
       In a `setup.py` or `setup.cfg` it is common to declare dependencies:

     

       1567
       1574
        
       

     
···

       1569
       1576
        
       * `install_requires` corresponds to `propagatedBuildInputs`

     

       1570
       1577
        
       * `tests_require` corresponds to `checkInputs`

     

       1571
       1578
        
       

     

       1572
       1572
       -
       ## Contributing

     

       1579
       1579
       +
       ## Contributing {#contributing}

     

       1573
       1580
        
       

     

       1574
       1574
       -
       ### Contributing guidelines

     

       1581
       1581
       +
       ### Contributing guidelines {#contributing-guidelines}

     

       1575
       1582
        
       

     

       1576
       1583
        
       The following rules are desired to be respected:

     

       1577
       1584

+8 -3

doc/languages-frameworks/qt.section.md

···

       90
       90
        
       }

     

       91
       91
        
       ```

     

       92
       92
        
       

     

       93
       93
       -
       ::: note

     

       93
       93
       +
       ::: {.note}

     

       94
       94
        
       `wrapQtAppsHook` ignores files that are non-ELF executables.

     

       95
       95
        
       This means that scripts won't be automatically wrapped so you'll need to manually wrap them as previously mentioned.

     

       96
       96
        
       An example of when you'd always need to do this is with Python applications that use PyQt.

     

       97
       97
        
       :::

     

       98
       98
        
       

     

       99
       99
       -
       ## Adding a library to Nixpkgs

     

       99
       99
       +
       ## Adding a library to Nixpkgs {#adding-a-library-to-nixpkgs}

     

       100
       100
       +
       

     

       100
       101
        
       Add Qt libraries to `qt5-packages.nix` to make them available for every

     

       101
       102
        
       supported Qt version.

     

       102
       103
        
       

     

       103
       104
        
       ### Example adding a Qt library {#qt-library-all-packages-nix}

     

       104
       105
        
       

     

       105
       106
        
       The following represents the contents of `qt5-packages.nix`.

     

       107
       107
       +
       

     

       106
       108
        
       ```nix

     

       107
       109
        
       {

     

       108
       110
        
         # ...

     
···

       126
       128
        
       }

     

       127
       129
        
       ```

     

       128
       130
        
       

     

       129
       129
       -
       ## Adding an application to Nixpkgs

     

       131
       131
       +
       ## Adding an application to Nixpkgs {#adding-an-application-to-nixpkgs}

     

       132
       132
       +
       

     

       130
       133
        
       Add Qt applications to `qt5-packages.nix`. Add an alias to `all-packages.nix`

     

       131
       134
        
       to select the Qt 5 version used for the application.

     

       132
       135
        
       

     

       133
       136
        
       ### Example adding a Qt application {#qt-application-all-packages-nix}

     

       134
       137
        
       

     

       135
       138
        
       The following represents the contents of `qt5-packages.nix`.

     

       139
       139
       +
       

     

       136
       140
        
       ```nix

     

       137
       141
        
       {

     

       138
       142
        
         # ...

     
···

       144
       148
        
       ```

     

       145
       149
        
       

     

       146
       150
        
       The following represents the contents of `all-packages.nix`.

     

       151
       151
       +
       

     

       147
       152
        
       ```nix

     

       148
       153
        
       {

     

       149
       154
        
         # ...

+5 -5

doc/languages-frameworks/r.section.md

···

       1
       1
        
       # R {#r}

     

       2
       2
        
       

     

       3
       3
       -
       ## Installation

     

       3
       3
       +
       ## Installation {#installation}

     

       4
       4
        
       

     

       5
       5
        
       Define an environment for R that contains all the libraries that you'd like to

     

       6
       6
        
       use by adding the following snippet to your $HOME/.config/nixpkgs/config.nix file:

     
···

       31
       31
        
       However, if you'd like to add a file to your project source to make the

     

       32
       32
        
       environment available for other contributors, you can create a `default.nix`

     

       33
       33
        
       file like so:

     

       34
       34
       +
       

     

       34
       35
        
       ```nix

     

       35
       36
        
       with import <nixpkgs> {};

     

       36
       37
        
       {

     
···

       50
       51
        
       and then run `nix-shell .` to be dropped into a shell with those packages

     

       51
       52
        
       available.

     

       52
       53
        
       

     

       53
       53
       -
       ## RStudio

     

       54
       54
       +
       ## RStudio {#rstudio}

     

       54
       55
        
       

     

       55
       56
        
       RStudio uses a standard set of packages and ignores any custom R

     

       56
       57
        
       environments or installed packages you may have.  To create a custom

     
···

       93
       94
        
       one above. If you need additional packages just add them to the list and

     

       94
       95
        
       re-enter the shell.

     

       95
       96
        
       

     

       96
       96
       -
       ## Updating the package set

     

       97
       97
       +
       ## Updating the package set {#updating-the-package-set}

     

       97
       98
        
       

     

       98
       99
        
       ```bash

     

       99
       100
        
       nix-shell generate-shell.nix

     
···

       113
       114
        
       

     

       114
       115
        
       `generate-r-packages.R <repo>` reads  `<repo>-packages.nix`, therefor the renaming.

     

       115
       116
        
       

     

       116
       116
       -
       

     

       117
       117
       -
       ## Testing if the Nix-expression could be evaluated

     

       117
       117
       +
       ## Testing if the Nix-expression could be evaluated {#testing-if-the-nix-expression-could-be-evaluated}

     

       118
       118
        
       

     

       119
       119
        
       ```bash

     

       120
       120
        
       nix-build test-evaluation.nix --dry-run

+11 -11

doc/languages-frameworks/ruby.section.md

···

       1
       1
        
       # Ruby {#sec-language-ruby}

     

       2
       2
        
       

     

       3
       3
       -
       ## Using Ruby

     

       3
       3
       +
       ## Using Ruby {#using-ruby}

     

       4
       4
        
       

     

       5
       5
        
       Several versions of Ruby interpreters are available on Nix, as well as over 250 gems and many applications written in Ruby. The attribute `ruby` refers to the default Ruby interpreter, which is currently MRI 2.6. It's also possible to refer to specific versions, e.g. `ruby_2_y`, `jruby`, or `mruby`.

     

       6
       6
        
       

     
···

       12
       12
        
       

     

       13
       13
        
       Since not all gems have executables like `nokogiri`, it's usually more convenient to use the `withPackages` function like this: `ruby.withPackages (p: with p; [ nokogiri ])`. This will also make sure that the Ruby in your environment will be able to find the gem and it can be used in your Ruby code (for example via `ruby` or `irb` executables) via `require "nokogiri"` as usual.

     

       14
       14
        
       

     

       15
       15
       -
       ### Temporary Ruby environment with `nix-shell`

     

       15
       15
       +
       ### Temporary Ruby environment with `nix-shell` {#temporary-ruby-environment-with-nix-shell}

     

       16
       16
        
       

     

       17
       17
        
       Rather than having a single Ruby environment shared by all Ruby development projects on a system, Nix allows you to create separate environments per project. `nix-shell` gives you the possibility to temporarily load another environment akin to a combined `chruby` or `rvm` and `bundle exec`.

     

       18
       18
        
       

     
···

       30
       30
        
       

     

       31
       31
        
       Again, it's possible to launch the interpreter from the shell. The Ruby interpreter has the attribute `gems` which contains all Ruby gems for that specific interpreter.

     

       32
       32
        
       

     

       33
       33
       -
       #### Load Ruby environment from `.nix` expression

     

       33
       33
       +
       #### Load Ruby environment from `.nix` expression {#load-ruby-environment-from-.nix-expression}

     

       34
       34
        
       

     

       35
       35
        
       As explained in the Nix manual, `nix-shell` can also load an expression from a `.nix` file. Say we want to have Ruby 2.6, `nokogori`, and `pry`. Consider a `shell.nix` file with:

     

       36
       36
        
       

     
···

       45
       45
        
       2. Then we create a Ruby environment with the `withPackages` function.

     

       46
       46
        
       3. The `withPackages` function expects us to provide a function as an argument that takes the set of all ruby gems and returns a list of packages to include in the environment. Here, we select the packages `nokogiri` and `pry` from the package set.

     

       47
       47
        
       

     

       48
       48
       -
       #### Execute command with `--run`

     

       48
       48
       +
       #### Execute command with `--run` {#execute-command-with---run}

     

       49
       49
        
       

     

       50
       50
        
       A convenient flag for `nix-shell` is `--run`. It executes a command in the `nix-shell`. We can e.g. directly open a `pry` REPL:

     

       51
       51
        
       

     
···

       65
       65
        
       $ nix-shell -p "ruby.withPackages (ps: with ps; [ nokogiri pry ])" --run "ruby example.rb"

     

       66
       66
        
       ```

     

       67
       67
        
       

     

       68
       68
       -
       #### Using `nix-shell` as shebang

     

       68
       68
       +
       #### Using `nix-shell` as shebang {#using-nix-shell-as-shebang}

     

       69
       69
        
       

     

       70
       70
        
       In fact, for the last 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 `./example.rb`, and it will run with all dependencies.

     

       71
       71
        
       

     
···

       80
       80
        
       puts Nokogiri::HTML(body).at('h1').text

     

       81
       81
        
       ```

     

       82
       82
        
       

     

       83
       83
       -
       ## Developing with Ruby

     

       83
       83
       +
       ## Developing with Ruby {#developing-with-ruby}

     

       84
       84
        
       

     

       85
       85
       -
       ### Using an existing Gemfile

     

       85
       85
       +
       ### Using an existing Gemfile {#using-an-existing-gemfile}

     

       86
       86
        
       

     

       87
       87
        
       In most cases, you'll already have a `Gemfile.lock` listing all your dependencies. This can be used to generate a `gemset.nix` which is used to fetch the gems and combine them into a single environment. The reason why you need to have a separate file for this, is that Nix requires you to have a checksum for each input to your build. Since the `Gemfile.lock` that `bundler` generates doesn't provide us with checksums, we have to first download each gem, calculate its SHA256, and store it in this separate file.

     

       88
       88
        
       

     
···

       120
       120
        
       mkShell { buildInputs = [ gems (lowPrio gems.wrappedRuby) ]; }

     

       121
       121
        
       ```

     

       122
       122
        
       

     

       123
       123
       -
       ### Gem-specific configurations and workarounds

     

       123
       123
       +
       ### Gem-specific configurations and workarounds {#gem-specific-configurations-and-workarounds}

     

       124
       124
        
       

     

       125
       125
        
       In some cases, especially if the gem has native extensions, you might need to modify the way the gem is built.

     

       126
       126
        
       

     
···

       201
       201
        
       

     

       202
       202
        
       Of course for this use-case one could also use overlays since the configuration for `pg` depends on the `postgresql` alias, but for demonstration purposes this has to suffice.

     

       203
       203
        
       

     

       204
       204
       -
       ### Adding a gem to the default gemset

     

       204
       204
       +
       ### Adding a gem to the default gemset {#adding-a-gem-to-the-default-gemset}

     

       205
       205
        
       

     

       206
       206
        
       Now that you know how to get a working Ruby environment with Nix, it's time to go forward and start actually developing with Ruby. We will first have a look at how Ruby gems are packaged on Nix. Then, we will look at how you can use development mode with your code.

     

       207
       207
        
       

     
···

       215
       215
        
       NIX_PATH=nixpkgs=$PWD nix-shell -p "ruby.withPackages (ps: with ps; [ name-of-your-gem ])"

     

       216
       216
        
       ```

     

       217
       217
        
       

     

       218
       218
       -
       ### Packaging applications

     

       218
       218
       +
       ### Packaging applications {#packaging-applications}

     

       219
       219
        
       

     

       220
       220
        
       A common task is to add a ruby executable to nixpkgs, popular examples would be `chef`, `jekyll`, or `sass`. A good way to do that is to use the `bundlerApp` function, that allows you to make a package that only exposes the listed executables, otherwise the package may cause conflicts through common paths like `bin/rake` or `bin/bundler` that aren't meant to be used.

     

       221
       221
        
       

     
···

       243
       243
        
       

     

       244
       244
        
       All that's left to do is to generate the corresponding `Gemfile.lock` and `gemset.nix` as described above in the `Using an existing Gemfile` section.

     

       245
       245
        
       

     

       246
       246
       -
       #### Packaging executables that require wrapping

     

       246
       246
       +
       #### Packaging executables that require wrapping {#packaging-executables-that-require-wrapping}

     

       247
       247
        
       

     

       248
       248
        
       Sometimes your app will depend on other executables at runtime, and tries to find it through the `PATH` environment variable.

     

       249
       249

+59 -43

doc/languages-frameworks/rust.section.md

···

       15
       15
        
       use either `rustup` from nixpkgs (which will manage the rust installation in your home directory),

     

       16
       16
        
       or use Mozilla's [Rust nightlies overlay](#using-the-rust-nightlies-overlay).

     

       17
       17
        
       

     

       18
       18
       -
       ## Compiling Rust applications with Cargo

     

       18
       18
       +
       ## Compiling Rust applications with Cargo {#compiling-rust-applications-with-cargo}

     

       19
       19
        
       

     

       20
       20
        
       Rust applications are packaged by using the `buildRustPackage` helper from `rustPlatform`:

     

       21
       21
        
       

     
···

       107
       107
        
       }

     

       108
       108
        
       ```

     

       109
       109
        
       

     

       110
       110
       -
       ### Importing a `Cargo.lock` file

     

       110
       110
       +
       ### Importing a `Cargo.lock` file {#importing-a-cargo.lock-file}

     

       111
       111
        
       

     

       112
       112
        
       Using `cargoSha256` or `cargoHash` is tedious when using

     

       113
       113
        
       `buildRustPackage` within a project, since it requires that the hash

     
···

       156
       156
        
       `lib.fakeHash` as a stub hash. Building the package (and thus the

     

       157
       157
        
       vendored dependencies) will then inform you of the correct hash.

     

       158
       158
        
       

     

       159
       159
       -
       ### Cross compilation

     

       159
       159
       +
       ### Cross compilation {#cross-compilation}

     

       160
       160
        
       

     

       161
       161
        
       By default, Rust packages are compiled for the host platform, just like any

     

       162
       162
        
       other package is.  The `--target` passed to rust tools is computed from this.

     
···

       168
       168
        
          name will be used instead.

     

       169
       169
        
       

     

       170
       170
        
          For example:

     

       171
       171
       +
       

     

       171
       172
        
          ```nix

     

       172
       173
        
          import <nixpkgs> {

     

       173
       174
        
            crossSystem = (import <nixpkgs/lib>).systems.examples.armhf-embedded // {

     
···

       175
       176
        
            };

     

       176
       177
        
          }

     

       177
       178
        
          ```

     

       179
       179
       +
       

     

       178
       180
        
          will result in:

     

       181
       181
       +
       

     

       179
       182
        
          ```shell

     

       180
       183
        
          --target thumbv7em-none-eabi

     

       181
       184
        
          ```

     
···

       188
       191
        
          will be used instead.

     

       189
       192
        
       

     

       190
       193
        
          For example:

     

       194
       194
       +
       

     

       191
       195
        
          ```nix

     

       192
       196
        
          import <nixpkgs> {

     

       193
       197
        
            crossSystem = (import <nixpkgs/lib>).systems.examples.armhf-embedded // {

     
···

       196
       200
        
            };

     

       197
       201
        
          }

     

       198
       202
        
          ```

     

       203
       203
       +
       

     

       199
       204
        
          will result in:

     

       205
       205
       +
       

     

       200
       206
        
          ```shell

     

       201
       207
        
          --target /nix/store/asdfasdfsadf-thumb-crazy.json # contains {"foo":"","bar":""}

     

       202
       208
        
          ```

     
···

       220
       226
        
       Note that currently custom targets aren't compiled with `std`, so `cargo test`

     

       221
       227
        
       will fail. This can be ignored by adding `doCheck = false;` to your derivation.

     

       222
       228
        
       

     

       223
       223
       -
       ### Running package tests

     

       229
       229
       +
       ### Running package tests {#running-package-tests}

     

       224
       230
        
       

     

       225
       231
        
       When using `buildRustPackage`, the `checkPhase` is enabled by default and runs

     

       226
       232
        
       `cargo test` on the package to build. To make sure that we don't compile the

     
···

       248
       254
        
       binary itself, as stated

     

       249
       255
        
       (here)[https://doc.rust-lang.org/cargo/commands/cargo-test.html].

     

       250
       256
        
       

     

       251
       251
       -
       #### Tests relying on the structure of the `target/` directory

     

       257
       257
       +
       #### Tests relying on the structure of the `target/` directory {#tests-relying-on-the-structure-of-the-target-directory}

     

       252
       258
        
       

     

       253
       259
        
       Some tests may rely on the structure of the `target/` directory. Those tests

     

       254
       260
        
       are likely to fail because we use `cargo --target` during the build. This means that

     
···

       258
       264
        
       

     

       259
       265
        
       This can only be worked around by patching the affected tests accordingly.

     

       260
       266
        
       

     

       261
       261
       -
       #### Disabling package-tests

     

       267
       267
       +
       #### Disabling package-tests {#disabling-package-tests}

     

       262
       268
        
       

     

       263
       269
        
       In some instances, it may be necessary to disable testing altogether (with `doCheck = false;`):

     

       264
       270
        
       

     
···

       272
       278
        
       However, please check if it's possible to disable a problematic subset of the

     

       273
       279
        
       test suite and leave a comment explaining your reasoning.

     

       274
       280
        
       

     

       275
       275
       -
       #### Setting `test-threads`

     

       281
       281
       +
       #### Setting `test-threads` {#setting-test-threads}

     

       276
       282
        
       

     

       277
       283
        
       `buildRustPackage` will use parallel test threads by default,

     

       278
       284
        
       sometimes it may be necessary to disable this so the tests run consecutively.

     
···

       284
       290
        
       }

     

       285
       291
        
       ```

     

       286
       292
        
       

     

       287
       287
       -
       ### Building a package in `debug` mode

     

       293
       293
       +
       ### Building a package in `debug` mode {#building-a-package-in-debug-mode}

     

       288
       294
        
       

     

       289
       295
        
       By default, `buildRustPackage` will use `release` mode for builds. If a package

     

       290
       296
        
       should be built in `debug` mode, it can be configured like so:

     
···

       298
       304
        
       

     

       299
       305
        
       In this scenario, the `checkPhase` will be ran in `debug` mode as well.

     

       300
       306
        
       

     

       301
       301
       -
       ### Custom `build`/`install`-procedures

     

       307
       307
       +
       ### Custom `build`/`install`-procedures {#custom-buildinstall-procedures}

     

       302
       308
        
       

     

       303
       309
        
       Some packages may use custom scripts for building/installing, e.g. with a `Makefile`.

     

       304
       310
        
       In these cases, it's recommended to override the `buildPhase`/`installPhase`/`checkPhase`.

     

       305
       311
        
       

     

       306
       312
        
       Otherwise, some steps may fail because of the modified directory structure of `target/`.

     

       307
       313
        
       

     

       308
       308
       -
       ### Building a crate with an absent or out-of-date Cargo.lock file

     

       314
       314
       +
       ### Building a crate with an absent or out-of-date Cargo.lock file {#building-a-crate-with-an-absent-or-out-of-date-cargo.lock-file}

     

       309
       315
        
       

     

       310
       316
        
       `buildRustPackage` needs a `Cargo.lock` file to get all dependencies in the

     

       311
       317
        
       source code in a reproducible way. If it is missing or out-of-date one can use

     
···

       321
       327
        
       }

     

       322
       328
        
       ```

     

       323
       329
        
       

     

       324
       324
       -
       ## Compiling non-Rust packages that include Rust code

     

       330
       330
       +
       ## Compiling non-Rust packages that include Rust code {#compiling-non-rust-packages-that-include-rust-code}

     

       325
       331
        
       

     

       326
       332
        
       Several non-Rust packages incorporate Rust code for performance- or

     

       327
       333
        
       security-sensitive parts. `rustPlatform` exposes several functions and

     

       328
       334
        
       hooks that can be used to integrate Cargo in non-Rust packages.

     

       329
       335
        
       

     

       330
       330
       -
       ### Vendoring of dependencies

     

       336
       336
       +
       ### Vendoring of dependencies {#vendoring-of-dependencies}

     

       331
       337
        
       

     

       332
       338
        
       Since network access is not allowed in sandboxed builds, Rust crate

     

       333
       339
        
       dependencies need to be retrieved using a fetcher. `rustPlatform`

     
···

       387
       393
        
       `lib.fakeHash` as a stub hash. Building `cargoDeps` will then inform

     

       388
       394
        
       you of the correct hash.

     

       389
       395
        
       

     

       390
       390
       -
       ### Hooks

     

       396
       396
       +
       ### Hooks {#hooks}

     

       391
       397
        
       

     

       392
       398
        
       `rustPlatform` provides the following hooks to automate Cargo builds:

     

       393
       399
        
       

     
···

       416
       422
        
       * `cargoInstallHook`: install binaries and static/shared libraries

     

       417
       423
        
         that were built using `cargoBuildHook`.

     

       418
       424
        
       

     

       419
       419
       -
       ### Examples

     

       425
       425
       +
       ### Examples {#examples}

     

       420
       426
        
       

     

       421
       421
       -
       #### Python package using `setuptools-rust`

     

       427
       427
       +
       #### Python package using `setuptools-rust` {#python-package-using-setuptools-rust}

     

       422
       428
        
       

     

       423
       429
        
       For Python packages using `setuptools-rust`, you can use

     

       424
       430
        
       `fetchCargoTarball` and `cargoSetupHook` to retrieve and set up Cargo

     
···

       504
       510
        
       }

     

       505
       511
        
       ```

     

       506
       512
        
       

     

       507
       507
       -
       #### Python package using `maturin`

     

       513
       513
       +
       #### Python package using `maturin` {#python-package-using-maturin}

     

       508
       514
        
       

     

       509
       515
        
       Python packages that use [Maturin](https://github.com/PyO3/maturin)

     

       510
       516
        
       can be built with `fetchCargoTarball`, `cargoSetupHook`, and

     
···

       545
       551
        
       }

     

       546
       552
        
       ```

     

       547
       553
        
       

     

       548
       548
       -
       ## Compiling Rust crates using Nix instead of Cargo

     

       554
       554
       +
       ## Compiling Rust crates using Nix instead of Cargo {#compiling-rust-crates-using-nix-instead-of-cargo}

     

       549
       555
        
       

     

       550
       550
       -
       ### Simple operation

     

       556
       556
       +
       ### Simple operation {#simple-operation}

     

       551
       557
        
       

     

       552
       558
        
       When run, `cargo build` produces a file called `Cargo.lock`,

     

       553
       559
        
       containing pinned versions of all dependencies. Nixpkgs contains a

     
···

       558
       564
        
       and can be used to compile a crate and all its dependencies. Here is

     

       559
       565
        
       an example for a minimal `hello` crate:

     

       560
       566
        
       

     

       561
       561
       -
       

     

       562
       562
       -
           $ cargo new hello

     

       563
       563
       -
           $ cd hello

     

       564
       564
       -
           $ cargo build

     

       567
       567
       +
       ```ShellSession

     

       568
       568
       +
       $ cargo new hello

     

       569
       569
       +
       $ cd hello

     

       570
       570
       +
       $ cargo build

     

       565
       571
        
            Compiling hello v0.1.0 (file:///tmp/hello)

     

       566
       566
       -
             Finished dev [unoptimized + debuginfo] target(s) in 0.20 secs

     

       567
       567
       -
           $ carnix -o hello.nix --src ./. Cargo.lock --standalone

     

       568
       568
       -
           $ nix-build hello.nix -A hello_0_1_0

     

       572
       572
       +
            Finished dev [unoptimized + debuginfo] target(s) in 0.20 secs

     

       573
       573
       +
       $ carnix -o hello.nix --src ./. Cargo.lock --standalone

     

       574
       574
       +
       $ nix-build hello.nix -A hello_0_1_0

     

       575
       575
       +
       ```

     

       569
       576
        
       

     

       570
       577
        
       Now, the file produced by the call to `carnix`, called `hello.nix`, looks like:

     

       571
       578
        
       

     
···

       644
       651
        
       will fetch it from [crates.io](https://crates.io). A `sha256`

     

       645
       652
        
       attribute is still needed for Nix purity.

     

       646
       653
        
       

     

       647
       647
       -
       ### Handling external dependencies

     

       654
       654
       +
       ### Handling external dependencies {#handling-external-dependencies}

     

       648
       655
        
       

     

       649
       656
        
       Some crates require external libraries. For crates from

     

       650
       657
        
       [crates.io](https://crates.io), such libraries can be specified in

     
···

       703
       710
        
       }

     

       704
       711
        
       ```

     

       705
       712
        
       

     

       706
       706
       -
       ### Options and phases configuration

     

       713
       713
       +
       ### Options and phases configuration {#options-and-phases-configuration}

     

       707
       714
        
       

     

       708
       715
        
       Actually, the overrides introduced in the previous section are more

     

       709
       716
        
       general. A number of other parameters can be overridden:

     
···

       750
       757
        
         };

     

       751
       758
        
         ```

     

       752
       759
        
       

     

       753
       753
       -
       ### Features

     

       760
       760
       +
       ### Features {#features}

     

       754
       761
        
       

     

       755
       762
        
       One can also supply features switches. For example, if we want to

     

       756
       763
        
       compile `diesel_cli` only with the `postgres` feature, and no default

     
···

       765
       772
        
       

     

       766
       773
        
       Where `diesel.nix` is the file generated by Carnix, as explained above.

     

       767
       774
        
       

     

       775
       775
       +
       ## Setting Up `nix-shell` {#setting-up-nix-shell}

     

       768
       776
        
       

     

       769
       769
       -
       ## Setting Up `nix-shell`

     

       770
       777
        
       Oftentimes you want to develop code from within `nix-shell`. Unfortunately

     

       771
       778
        
       `buildRustCrate` does not support common `nix-shell` operations directly

     

       772
       779
        
       (see [this issue](https://github.com/NixOS/nixpkgs/issues/37945))

     

       773
       780
        
       so we will use `stdenv.mkDerivation` instead.

     

       774
       781
        
       

     

       775
       782
        
       Using the example `hello` project above, we want to do the following:

     

       783
       783
       +
       

     

       776
       784
        
       - Have access to `cargo` and `rustc`

     

       777
       785
        
       - Have the `openssl` library available to a crate through it's _normal_

     

       778
       786
        
         compilation mechanism (`pkg-config`).

     
···

       801
       809
        
       ```

     

       802
       810
        
       

     

       803
       811
        
       You should now be able to run the following:

     

       804
       804
       -
       ```ShellSesssion

     

       812
       812
       +
       

     

       813
       813
       +
       ```ShellSession

     

       805
       814
        
       $ nix-shell --pure

     

       806
       815
        
       $ cargo build

     

       807
       816
        
       $ cargo test

     

       808
       817
        
       ```

     

       809
       818
        
       

     

       810
       810
       -
       ### Controlling Rust Version Inside `nix-shell`

     

       819
       819
       +
       ### Controlling Rust Version Inside `nix-shell` {#controlling-rust-version-inside-nix-shell}

     

       820
       820
       +
       

     

       811
       821
        
       To control your rust version (i.e. use nightly) from within `shell.nix` (or

     

       812
       822
        
       other nix expressions) you can use the following `shell.nix`

     

       813
       823
        
       

     
···

       839
       849
        
       ```

     

       840
       850
        
       

     

       841
       851
        
       Now run:

     

       852
       852
       +
       

     

       842
       853
        
       ```ShellSession

     

       843
       854
        
       $ rustc --version

     

       844
       855
        
       rustc 1.26.0-nightly (188e693b3 2018-03-26)

     
···

       846
       857
        
       

     

       847
       858
        
       To see that you are using nightly.

     

       848
       859
        
       

     

       849
       849
       -
       

     

       850
       850
       -
       ## Using the Rust nightlies overlay

     

       860
       860
       +
       ## Using the Rust nightlies overlay {#using-the-rust-nightlies-overlay}

     

       851
       861
        
       

     

       852
       862
        
       Mozilla provides an overlay for nixpkgs to bring a nightly version of Rust into scope.

     

       853
       863
        
       This overlay can _also_ be used to install recent unstable or stable versions

     

       854
       864
        
       of Rust, if desired.

     

       855
       865
        
       

     

       856
       856
       -
       ### Rust overlay installation

     

       866
       866
       +
       ### Rust overlay installation {#rust-overlay-installation}

     

       857
       867
        
       

     

       858
       868
        
       You can use this overlay by either changing your local nixpkgs configuration,

     

       859
       869
        
       or by adding the overlay declaratively in a nix expression,  e.g. in `configuration.nix`.

     

       860
       860
       -
       For more information see [#sec-overlays-install](the manual on installing overlays).

     

       870
       870
       +
       For more information see [the manual on installing overlays](#sec-overlays-install).

     

       861
       871
        
       

     

       862
       862
       -
       #### Imperative rust overlay installation

     

       872
       872
       +
       #### Imperative rust overlay installation {#imperative-rust-overlay-installation}

     

       863
       873
        
       

     

       864
       874
        
       Clone [nixpkgs-mozilla](https://github.com/mozilla/nixpkgs-mozilla),

     

       865
       875
        
       and create a symbolic link to the file

     

       866
       876
        
       [rust-overlay.nix](https://github.com/mozilla/nixpkgs-mozilla/blob/master/rust-overlay.nix)

     

       867
       877
        
       in the `~/.config/nixpkgs/overlays` directory.

     

       868
       878
        
       

     

       869
       869
       -
           $ git clone https://github.com/mozilla/nixpkgs-mozilla.git

     

       870
       870
       -
           $ mkdir -p ~/.config/nixpkgs/overlays

     

       871
       871
       -
           $ ln -s $(pwd)/nixpkgs-mozilla/rust-overlay.nix ~/.config/nixpkgs/overlays/rust-overlay.nix

     

       879
       879
       +
       ```ShellSession

     

       880
       880
       +
       $ git clone https://github.com/mozilla/nixpkgs-mozilla.git

     

       881
       881
       +
       $ mkdir -p ~/.config/nixpkgs/overlays

     

       882
       882
       +
       $ ln -s $(pwd)/nixpkgs-mozilla/rust-overlay.nix ~/.config/nixpkgs/overlays/rust-overlay.nix

     

       883
       883
       +
       ```

     

       872
       884
        
       

     

       873
       873
       -
       ### Declarative rust overlay installation

     

       885
       885
       +
       ### Declarative rust overlay installation {#declarative-rust-overlay-installation}

     

       874
       886
        
       

     

       875
       887
        
       Add the following to your `configuration.nix`, `home-configuration.nix`, `shell.nix`, or similar:

     

       876
       888
        
       

     
···

       886
       898
        
       

     

       887
       899
        
       Note that this will fetch the latest overlay version when rebuilding your system.

     

       888
       900
        
       

     

       889
       889
       -
       ### Rust overlay usage

     

       901
       901
       +
       ### Rust overlay usage {#rust-overlay-usage}

     

       890
       902
        
       

     

       891
       903
        
       The overlay contains attribute sets corresponding to different versions of the rust toolchain, such as:

     

       892
       904
        
       

     
···

       900
       912
        
       

     

       901
       913
        
       Imperatively, the latest stable version can be installed with the following command:

     

       902
       914
        
       

     

       903
       903
       -
           $ nix-env -Ai nixpkgs.latest.rustChannels.stable.rust

     

       915
       915
       +
       ```ShellSession

     

       916
       916
       +
       $ nix-env -Ai nixpkgs.latest.rustChannels.stable.rust

     

       917
       917
       +
       ```

     

       904
       918
        
       

     

       905
       919
        
       Or using the attribute with nix-shell:

     

       906
       920
        
       

     

       907
       907
       -
           $ nix-shell -p nixpkgs.latest.rustChannels.stable.rust

     

       921
       921
       +
       ```ShellSession

     

       922
       922
       +
       $ nix-shell -p nixpkgs.latest.rustChannels.stable.rust

     

       923
       923
       +
       ```

     

       908
       924
        
       

     

       909
       925
        
       Substitute the `nixpkgs` prefix with `nixos` on NixOS.

     

       910
       926
        
       To install the beta or nightly channel, "stable" should be substituted by

doc/languages-frameworks/texlive.section.md

···

       5
       5
        
       ## User's guide {#sec-language-texlive-user-guide}

     

       6
       6
        
       

     

       7
       7
        
       - For basic usage just pull `texlive.combined.scheme-basic` for an environment with basic LaTeX support.

     

       8
       8
       +
       

     

       8
       9
        
       - It typically won't work to use separately installed packages together. Instead, you can build a custom set of packages like this:

     

       9
       10
        
       

     

       10
       11
        
         ```nix

     
···

       14
       15
        
         ```

     

       15
       16
        
       

     

       16
       17
        
       - There are all the schemes, collections and a few thousand packages, as defined upstream (perhaps with tiny differences).

     

       18
       18
       +
       

     

       17
       19
        
       - By default you only get executables and files needed during runtime, and a little documentation for the core packages. To change that, you need to add `pkgFilter` function to `combine`.

     

       18
       20
        
       

     

       19
       21
        
         ```nix

+4 -4

doc/languages-frameworks/titanium.section.md

···

       9
       9
        
       Not all Titanium features supported -- currently, it can only be used to build

     

       10
       10
        
       Android and iOS apps.

     

       11
       11
        
       

     

       12
       12
       -
       Building a Titanium app

     

       13
       13
       -
       -----------------------

     

       12
       12
       +
       ## Building a Titanium app {#building-a-titanium-app}

     

       13
       13
       +
       

     

       14
       14
        
       We can build a Titanium app from source for Android or iOS and for debugging or

     

       15
       15
        
       release purposes by invoking the `titaniumenv.buildApp {}` function:

     

       16
       16
        
       

     
···

       103
       103
        
       path of the PHP script (`installURL`) (that is included with the iOS build

     

       104
       104
        
       environment) to enable wireless ad-hoc installations.

     

       105
       105
        
       

     

       106
       106
       -
       Emulating or simulating the app

     

       107
       107
       -
       -------------------------------

     

       106
       106
       +
       ## Emulating or simulating the app {#emulating-or-simulating-the-app}

     

       107
       107
       +
       

     

       108
       108
        
       It is also possible to simulate the correspond iOS simulator build by using

     

       109
       109
        
       `xcodeenv.simulateApp {}` and emulate an Android APK by using

     

       110
       110
        
       `androidenv.emulateApp {}`.

+10 -10

doc/languages-frameworks/vim.section.md

···

       12
       12
        
       - Pathogen

     

       13
       13
        
       - vim-plug

     

       14
       14
        
       

     

       15
       15
       -
       ## Custom configuration

     

       15
       15
       +
       ## Custom configuration {#custom-configuration}

     

       16
       16
        
       

     

       17
       17
        
       Adding custom .vimrc lines can be done using the following code:

     

       18
       18
        
       

     
···

       56
       56
        
       }

     

       57
       57
        
       ```

     

       58
       58
        
       

     

       59
       59
       -
       ## Managing plugins with Vim packages

     

       59
       59
       +
       ## Managing plugins with Vim packages {#managing-plugins-with-vim-packages}

     

       60
       60
        
       

     

       61
       61
        
       To store you plugins in Vim packages (the native Vim plugin manager, see `:help packages`) the following example can be used:

     

       62
       62
        
       

     
···

       116
       116
        
       

     

       117
       117
        
       After that you can install your special grafted `myVim` or `myNeovim` packages.

     

       118
       118
        
       

     

       119
       119
       -
       ### What if your favourite Vim plugin isn't already packaged?

     

       119
       119
       +
       ### What if your favourite Vim plugin isn’t already packaged? {#what-if-your-favourite-vim-plugin-isnt-already-packaged}

     

       120
       120
        
       

     

       121
       121
        
       If one of your favourite plugins isn't packaged, you can package it yourself:

     

       122
       122
        
       

     
···

       154
       154
        
       }

     

       155
       155
        
       ```

     

       156
       156
        
       

     

       157
       157
       -
       ## Managing plugins with vim-plug

     

       157
       157
       +
       ## Managing plugins with vim-plug {#managing-plugins-with-vim-plug}

     

       158
       158
        
       

     

       159
       159
        
       To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim

     

       160
       160
        
       plugins the following example can be used:

     
···

       183
       183
        
       }

     

       184
       184
        
       ```

     

       185
       185
        
       

     

       186
       186
       -
       ## Managing plugins with VAM

     

       186
       186
       +
       ## Managing plugins with VAM {#managing-plugins-with-vam}

     

       187
       187
        
       

     

       188
       188
       -
       ### Handling dependencies of Vim plugins

     

       188
       188
       +
       ### Handling dependencies of Vim plugins {#handling-dependencies-of-vim-plugins}

     

       189
       189
        
       

     

       190
       190
        
       VAM introduced .json files supporting dependencies without versioning

     

       191
       191
        
       assuming that "using latest version" is ok most of the time.

     

       192
       192
        
       

     

       193
       193
       -
       ### Example

     

       193
       193
       +
       ### Example {#example}

     

       194
       194
        
       

     

       195
       195
        
       First create a vim-scripts file having one plugin name per line. Example:

     

       196
       196
        
       

     
···

       280
       280
        
       ]

     

       281
       281
        
       ```

     

       282
       282
        
       

     

       283
       283
       -
       ## Adding new plugins to nixpkgs

     

       283
       283
       +
       ## Adding new plugins to nixpkgs {#adding-new-plugins-to-nixpkgs}

     

       284
       284
        
       

     

       285
       285
        
       Nix expressions for Vim plugins are stored in [pkgs/misc/vim-plugins](/pkgs/misc/vim-plugins). For the vast majority of plugins, Nix expressions are automatically generated by running [`./update.py`](/pkgs/misc/vim-plugins/update.py). This creates a [generated.nix](/pkgs/misc/vim-plugins/generated.nix) file based on the plugins listed in [vim-plugin-names](/pkgs/misc/vim-plugins/vim-plugin-names). Plugins are listed in alphabetical order in `vim-plugin-names` using the format `[github username]/[repository]`. For example https://github.com/scrooloose/nerdtree becomes `scrooloose/nerdtree`.

     

       286
       286
        
       

     
···

       298
       298
        
       

     

       299
       299
        
       Finally, there are some plugins that are also packaged in nodePackages because they have Javascript-related build steps, such as running webpack. Those plugins are not listed in `vim-plugin-names` or managed by `update.py` at all, and are included separately in `overrides.nix`. Currently, all these plugins are related to the `coc.nvim` ecosystem of Language Server Protocol integration with vim/neovim.

     

       300
       300
        
       

     

       301
       301
       -
       ## Updating plugins in nixpkgs

     

       301
       301
       +
       ## Updating plugins in nixpkgs {#updating-plugins-in-nixpkgs}

     

       302
       302
        
       

     

       303
       303
        
       Run the update script with a GitHub API token that has at least `public_repo` access. Running the script without the token is likely to result in rate-limiting (429 errors). For steps on creating an API token, please refer to [GitHub's token documentation](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token).

     

       304
       304
        
       

     
···

       312
       312
        
       ./pkgs/misc/vim-plugins/update.py --proc 1

     

       313
       313
        
       ```

     

       314
       314
        
       

     

       315
       315
       -
       ## Important repositories

     

       315
       315
       +
       ## Important repositories {#important-repositories}

     

       316
       316
        
       

     

       317
       317
        
       - [vim-pi](https://bitbucket.org/vimcommunity/vim-pi) is a plugin repository

     

       318
       318
        
         from VAM plugin manager meant to be used by others as well used by

+1 -1

doc/preface.chapter.md

···

       12
       12
        
       expression language, then you are kindly referred to the [Nix manual](https://nixos.org/nix/manual/).

     

       13
       13
        
       The NixOS distribution is documented in the [NixOS manual](https://nixos.org/nixos/manual/).

     

       14
       14
        
       

     

       15
       15
       -
       ## Overview of Nixpkgs

     

       15
       15
       +
       ## Overview of Nixpkgs {#overview-of-nixpkgs}

     

       16
       16
        
       

     

       17
       17
        
       Nix expressions describe how to build packages from source and are collected in

     

       18
       18
        
       the [nixpkgs repository](https://github.com/NixOS/nixpkgs). Also included in the

+17 -14

doc/stdenv/cross-compilation.chapter.md

···

       6
       6
        
       

     

       7
       7
        
       This chapter will be organized in three parts. First, it will describe the basics of how to package software in a way that supports cross-compilation. Second, it will describe how to use Nixpkgs when cross-compiling. Third, it will describe the internal infrastructure supporting cross-compilation.

     

       8
       8
        
       

     

       9
       9
       -
       

     

       10
       9
        
       ## Packaging in a cross-friendly manner {#sec-cross-packaging}

     

       11
       10
        
       

     

       12
       11
        
       ### Platform parameters {#ssec-cross-platform-parameters}

     
···

       65
       64
        
       

     

       66
       65
        
       ### Theory of dependency categorization {#ssec-cross-dependency-categorization}

     

       67
       66
        
       

     

       68
       68
       -
       ::: note

     

       67
       67
       +
       ::: {.note}

     

       69
       68
        
       This is a rather philosophical description that isn't very Nixpkgs-specific. For an overview of all the relevant attributes given to `mkDerivation`, see <xref linkend="ssec-stdenv-dependencies"/>. For a description of how everything is implemented, see <xref linkend="ssec-cross-dependency-implementation"/>.

     

       70
       69
        
       :::

     

       71
       70
        
       

     
···

       81
       80
        
       

     

       82
       81
        
       Putting this all together, that means we have dependencies in the form "host → target", in at most the following six combinations:

     

       83
       82
        
       

     

       83
       83
       +
       #### Possible dependency types {#possible-dependency-types}

     

       84
       84
        
       

     

       85
       85
       -
       #### Possible dependency types

     

       86
       86
       -
       | Dependency's host platform | Dependency's target platform |

     

       87
       87
       -
       | --                         | --                           |

     

       85
       85
       +
       | Dependency’s host platform | Dependency’s target platform |

     

       86
       86
       +
       |----------------------------|------------------------------|

     

       88
       87
        
       | build                      | build                        |

     

       89
       88
        
       | build                      | host                         |

     

       90
       89
        
       | build                      | target                       |

     
···

       113
       112
        
       $ nix-build '<nixpkgs>' -A pkgsCross.raspberryPi.hello

     

       114
       113
        
       ```

     

       115
       114
        
       

     

       116
       116
       -
       #### What if my package's build system needs to build a C program to be run under the build environment? {#cross-qa-build-c-program-in-build-environment}

     

       115
       115
       +
       #### What if my package’s build system needs to build a C program to be run under the build environment? {#cross-qa-build-c-program-in-build-environment}

     

       116
       116
       +
       

     

       117
       117
        
       Add the following to your `mkDerivation` invocation.

     

       118
       118
       +
       

     

       118
       119
        
       ```nix

     

       119
       120
        
       depsBuildBuild = [ buildPackages.stdenv.cc ];

     

       120
       121
        
       ```

     

       121
       122
        
       

     

       122
       122
       -
       ####  My package's testsuite needs to run host platform code. {#cross-testsuite-runs-host-code}

     

       123
       123
       +
       #### My package’s testsuite needs to run host platform code. {#cross-testsuite-runs-host-code}

     

       123
       124
        
       

     

       124
       125
        
       Add the following to your `mkDerivation` invocation.

     

       126
       126
       +
       

     

       125
       127
        
       ```nix

     

       126
       128
        
       doCheck = stdenv.hostPlatform == stdenv.buildPlatform;

     

       127
       129
        
       ```

     
···

       134
       136
        
       $ nix-build '<nixpkgs>' --arg crossSystem '(import <nixpkgs/lib>).systems.examples.fooBarBaz' -A whatever

     

       135
       137
        
       ```

     

       136
       138
        
       

     

       137
       137
       -
       ::: note

     

       139
       139
       +
       ::: {.note}

     

       138
       140
        
       Eventually we would like to make these platform examples an unnecessary convenience so that

     

       139
       141
        
       

     

       140
       142
        
       ```ShellSession

     
···

       146
       148
        
       

     

       147
       149
        
       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. Additionally, `libc` will be inferred from `parse`. Finally, `localSystem.system` is also _impurely_ inferred based on the platform evaluation occurs. This means it is often not necessary to pass `localSystem` at all, as in the command-line example in the previous paragraph.

     

       148
       150
        
       

     

       149
       149
       -
       ::: note

     

       151
       151
       +
       ::: {.note}

     

       150
       152
        
       Many sources (manual, wiki, etc) probably mention passing `system`, `platform`, along with the optional `crossSystem` to Nixpkgs: `import <nixpkgs> { system = ..; platform = ..; crossSystem = ..; }`. Passing those two instead of `localSystem` is still supported for compatibility, but is discouraged. Indeed, much of the inference we do for these parameters is motivated by compatibility as much as convenience.

     

       151
       153
        
       :::

     

       152
       154
        
       

     
···

       178
       180
        
       

     

       179
       181
        
       In each stage, `pkgsBuildHost` refers to the previous stage, `pkgsBuildBuild` refers to the one before that, and `pkgsHostTarget` refers to the current one, and `pkgsTargetTarget` refers to the next one. When there is no previous or next stage, they instead refer to the current stage. Note how all the invariants regarding the mapping between dependency and depending packages' build host and target platforms are preserved. `pkgsBuildTarget` and `pkgsHostHost` are more complex in that the stage fitting the requirements isn't always a fixed chain of "prevs" and "nexts" away (modulo the "saturating" self-references at the ends). We just special case each instead. All the primary edges are implemented is in `pkgs/stdenv/booter.nix`, and secondarily aliases in `pkgs/top-level/stage.nix`.

     

       180
       182
        
       

     

       181
       181
       -
       ::: note

     

       183
       183
       +
       ::: {.note}

     

       182
       184
        
       The native stages are bootstrapped in legacy ways that predate the current cross implementation. This is why the bootstrapping stages leading up to the final stages are ignored in the previous paragraph.

     

       183
       185
        
       :::

     

       184
       186
        
       

     
···

       186
       188
        
       ```

     

       187
       189
        
       (native, native, native, foreign, foreign)

     

       188
       190
        
       ```

     

       191
       191
       +
       

     

       189
       192
        
       If one imagines the saturating self references at the end being replaced with infinite stages, and then overlays those platform triples, one ends up with the infinite tuple:

     

       190
       193
        
       ```

     

       191
       194
        
       (native..., native, native, native, foreign, foreign, foreign...)

     
···

       193
       196
        
       One can then imagine any sequence of platforms such that there are bootstrap stages with their 3 platforms determined by "sliding a window" that is the 3 tuple through the sequence. This was the original model for bootstrapping. Without a target platform (assume a better world where all compilers are multi-target and all standard libraries are built in their own derivation), this is sufficient. Conversely if one wishes to cross compile "faster", with a "Canadian Cross" bootstrapping stage where `build != host != target`, more bootstrapping stages are needed since no sliding window provides the pesky `pkgsBuildTarget` package set since it skips the Canadian cross stage's "host".

     

       194
       197
        
       

     

       195
       198
        
       

     

       196
       196
       -
       ::: note

     

       197
       197
       -
       It is much better to refer to `buildPackages` than `targetPackages`, or more broadly package sets that do not mention "target". There are three reasons for this.

     

       199
       199
       +
       ::: {.note}

     

       200
       200
       +
       It is much better to refer to `buildPackages` than `targetPackages`, or more broadly package sets that do not mention “target”. There are three reasons for this.

     

       198
       201
        
       

     

       199
       202
        
       First, it is because bootstrapping stages do not have a unique `targetPackages`. For example a `(x86-linux, x86-linux, arm-linux)` and `(x86-linux, x86-linux, x86-windows)` package set both have a `(x86-linux, x86-linux, x86-linux)` package set. Because there is no canonical `targetPackages` for such a native (`build == host == target`) package set, we set their `targetPackages`

     

       200
       203
        
       

     
···

       203
       206
        
       Thirdly, it is because everything target-mentioning only exists to accommodate compilers with lousy build systems that insist on the compiler itself and standard library being built together. Of course that is bad because bigger derivations means longer rebuilds. It is also problematic because it tends to make the standard libraries less like other libraries than they could be, complicating code and build systems alike. Because of the other problems, and because of these innate disadvantages, compilers ought to be packaged another way where possible.

     

       204
       207
        
       :::

     

       205
       208
        
       

     

       206
       206
       -
       ::: note

     

       207
       207
       -
       If one explores Nixpkgs, they will see derivations with names like `gccCross`. Such `*Cross` derivations is a holdover from before we properly distinguished between the host and target platforms—the derivation with "Cross" in the name covered the `build = host != target` case, while the other covered the `host = target`, with build platform the same or not based on whether one was using its `.nativeDrv` or `.crossDrv`. This ugliness will disappear soon.

     

       209
       209
       +
       ::: {.note}

     

       210
       210
       +
       If one explores Nixpkgs, they will see derivations with names like `gccCross`. Such `*Cross` derivations is a holdover from before we properly distinguished between the host and target platforms—the derivation with “Cross” in the name covered the `build = host != target` case, while the other covered the `host = target`, with build platform the same or not based on whether one was using its `.nativeDrv` or `.crossDrv`. This ugliness will disappear soon.

     

       208
       211
        
       :::

+5 -5

doc/stdenv/meta.chapter.md

···

       130
       130
        
       

     

       131
       131
        
       ### `tests` {#var-meta-tests}

     

       132
       132
        
       

     

       133
       133
       -
       ::: warning

     

       133
       133
       +
       ::: {.warning}

     

       134
       134
        
       This attribute is special in that it is not actually under the `meta` attribute set but rather under the `passthru` attribute set. This is due to how `meta` attributes work, and the fact that they are supposed to contain only metadata, not derivations.

     

       135
       135
        
       :::

     

       136
       136
        
       

     
···

       175
       175
        
       

     

       176
       176
        
       Although it’s typically better to indicate the specific license, a few generic options are available:

     

       177
       177
        
       

     

       178
       178
       -
       ### `lib.licenses.free`, `"free"`

     

       178
       178
       +
       ### `lib.licenses.free`, `"free"` {#lib.licenses.free-free}

     

       179
       179
        
       

     

       180
       180
        
       Catch-all for free software licenses not listed above.

     

       181
       181
        
       

     

       182
       182
       -
       ### `lib.licenses.unfreeRedistributable`, `"unfree-redistributable"`

     

       182
       182
       +
       ### `lib.licenses.unfreeRedistributable`, `"unfree-redistributable"` {#lib.licenses.unfreeredistributable-unfree-redistributable}

     

       183
       183
        
       

     

       184
       184
        
       Unfree package that can be redistributed in binary form. That is, it’s legal to redistribute the *output* of the derivation. This means that the package can be included in the Nixpkgs channel.

     

       185
       185
        
       

     

       186
       186
        
       Sometimes proprietary software can only be redistributed unmodified. Make sure the builder doesn’t actually modify the original binaries; otherwise we’re breaking the license. For instance, the NVIDIA X11 drivers can be redistributed unmodified, but our builder applies `patchelf` to make them work. Thus, its license is `"unfree"` and it cannot be included in the Nixpkgs channel.

     

       187
       187
        
       

     

       188
       188
       -
       ### `lib.licenses.unfree`, `"unfree"`

     

       188
       188
       +
       ### `lib.licenses.unfree`, `"unfree"` {#lib.licenses.unfree-unfree}

     

       189
       189
        
       

     

       190
       190
        
       Unfree package that cannot be redistributed. You can build it yourself, but you cannot redistribute the output of the derivation. Thus it cannot be included in the Nixpkgs channel.

     

       191
       191
        
       

     

       192
       192
       -
       ### `lib.licenses.unfreeRedistributableFirmware`, `"unfree-redistributable-firmware"`

     

       192
       192
       +
       ### `lib.licenses.unfreeRedistributableFirmware`, `"unfree-redistributable-firmware"` {#lib.licenses.unfreeredistributablefirmware-unfree-redistributable-firmware}

     

       193
       193
        
       

     

       194
       194
        
       This package supplies unfree, redistributable firmware. This is a separate value from `unfree-redistributable` because not everybody cares whether firmware is free.

+11 -11

doc/stdenv/multiple-output.chapter.md

···

       6
       6
        
       

     

       7
       7
        
       The main motivation is to save disk space by reducing runtime closure sizes; consequently also sizes of substituted binaries get reduced. Splitting can be used to have more granular runtime dependencies, for example the typical reduction is to split away development-only files, as those are typically not needed during runtime. As a result, closure sizes of many packages can get reduced to a half or even much less.

     

       8
       8
        
       

     

       9
       9
       -
       ::: note

     

       9
       9
       +
       ::: {.note}

     

       10
       10
        
       The reduction effects could be instead achieved by building the parts in completely separate derivations. That would often additionally reduce build-time closures, but it tends to be much harder to write such derivations, as build systems typically assume all parts are being built at once. This compromise approach of single source package producing multiple binary packages is also utilized often by rpm and deb.

     

       11
       11
        
       :::

     

       12
       12
        
       

     
···

       28
       28
        
       

     

       29
       29
        
       `nix-env` lacks an easy way to select the outputs to install. When installing a package, `nix-env` always installs the outputs listed in `meta.outputsToInstall`, even when the user explicitly selects an output.

     

       30
       30
        
       

     

       31
       31
       -
       ::: warning

     

       31
       31
       +
       ::: {.warning}

     

       32
       32
        
       `nix-env` silenty disregards the outputs selected by the user, and instead installs the outputs from `meta.outputsToInstall`. For example,

     

       33
       33
        
       

     

       34
       34
        
       ```ShellSession

     
···

       69
       69
        
       

     

       70
       70
        
       Often such a single line is enough. For each output an equally named environment variable is passed to the builder and contains the path in nix store for that output. Typically you also want to have the main `out` output, as it catches any files that didn’t get elsewhere.

     

       71
       71
        
       

     

       72
       72
       -
       ::: note

     

       72
       72
       +
       ::: {.note}

     

       73
       73
        
       There is a special handling of the `debug` output, described at <xref linkend="stdenv-separateDebugInfo" />.

     

       74
       74
        
       :::

     

       75
       75
        
       

     
···

       85
       85
        
       

     

       86
       86
        
       The support code currently recognizes some particular kinds of outputs and either instructs the build system of the package to put files into their desired outputs or it moves the files during the fixup phase. Each group of file types has an `outputFoo` variable specifying the output name where they should go. If that variable isn’t defined by the derivation writer, it is guessed – a default output name is defined, falling back to other possibilities if the output isn’t defined.

     

       87
       87
        
       

     

       88
       88
       -
       #### ` $outputDev`

     

       88
       88
       +
       #### `$outputDev` {#outputdev}

     

       89
       89
        
       

     

       90
       90
        
       is for development-only files. These include C(++) headers (`include/`), pkg-config (`lib/pkgconfig/`), cmake (`lib/cmake/`) and aclocal files (`share/aclocal/`). They go to `dev` or `out` by default.

     

       91
       91
        
       

     

       92
       92
       -
       #### ` $outputBin`

     

       92
       92
       +
       #### `$outputBin` {#outputbin}

     

       93
       93
        
       

     

       94
       94
        
       is meant for user-facing binaries, typically residing in `bin/`. They go to `bin` or `out` by default.

     

       95
       95
        
       

     

       96
       96
       -
       #### ` $outputLib`

     

       96
       96
       +
       #### `$outputLib` {#outputlib}

     

       97
       97
        
       

     

       98
       98
        
       is meant for libraries, typically residing in `lib/` and `libexec/`. They go to `lib` or `out` by default.

     

       99
       99
        
       

     

       100
       100
       -
       #### ` $outputDoc`

     

       100
       100
       +
       #### `$outputDoc` {#outputdoc}

     

       101
       101
        
       

     

       102
       102
        
       is for user documentation, typically residing in `share/doc/`. It goes to `doc` or `out` by default.

     

       103
       103
        
       

     

       104
       104
       -
       #### ` $outputDevdoc`

     

       104
       104
       +
       #### `$outputDevdoc` {#outputdevdoc}

     

       105
       105
        
       

     

       106
       106
        
       is for _developer_ documentation. Currently we count gtk-doc and devhelp books, typically residing in `share/gtk-doc/` and `share/devhelp/`, 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.

     

       107
       107
        
       

     

       108
       108
       -
       #### ` $outputMan`

     

       108
       108
       +
       #### `$outputMan` {#outputman}

     

       109
       109
        
       

     

       110
       110
        
       is for man pages (except for section 3), typically residing in `share/man/man[0-9]/`. They go to `man` or `$outputBin` by default.

     

       111
       111
        
       

     

       112
       112
       -
       #### ` $outputDevman`

     

       112
       112
       +
       #### `$outputDevman` {#outputdevman}

     

       113
       113
        
       

     

       114
       114
        
       is for section 3 man pages, typically residing in `share/man/man[0-9]/`. They go to `devman` or `$outputMan` by default.

     

       115
       115
        
       

     

       116
       116
       -
       #### ` $outputInfo`

     

       116
       116
       +
       #### `$outputInfo` {#outputinfo}

     

       117
       117
        
       

     

       118
       118
        
       is for info pages, typically residing in `share/info/`. They go to `info` or `$outputBin` by default.

     

       119
       119

+67 -65

doc/stdenv/stdenv.chapter.md

···

       175
       175
        
       

     

       176
       176
        
       Overall, the unifying theme here is that propagation shouldn’t be introducing transitive dependencies involving platforms the depending package is unaware of. \[One can imagine the dependending package asking for dependencies with the platforms it knows about; other platforms it doesn’t know how to ask for. The platform description in that scenario is a kind of unforagable capability.\] The offset bounds checking and definition of `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.

     

       177
       177
        
       

     

       178
       178
       -
       ### Variables specifying dependencies

     

       178
       178
       +
       ### Variables specifying dependencies {#variables-specifying-dependencies}

     

       179
       179
       +
       

     

       179
       180
        
       #### `depsBuildBuild` {#var-stdenv-depsBuildBuild}

     

       180
       181
        
       

     

       181
       182
        
       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. These are programs and libraries used at build time that produce programs and 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 `nativeBuildInputs` instead. The most common use of 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.

     
···

       236
       237
        
       

     

       237
       238
        
       ## Attributes {#ssec-stdenv-attributes}

     

       238
       239
        
       

     

       239
       239
       -
       ### Variables affecting `stdenv` initialisation

     

       240
       240
       +
       ### Variables affecting `stdenv` initialisation {#variables-affecting-stdenv-initialisation}

     

       240
       241
        
       

     

       241
       242
        
       #### `NIX_DEBUG` {#var-stdenv-NIX_DEBUG}

     

       242
       243
        
       

     

       243
       244
        
       A natural number indicating how much information to log. If set to 1 or higher, `stdenv` will print moderate debugging information during the build. In particular, the `gcc` and `ld` wrapper scripts will print out the complete command line passed to the wrapped tools. If set to 6 or higher, the `stdenv` setup script will be run with `set -x` tracing. If set to 7 or higher, the `gcc` and `ld` wrapper scripts will also be run with `set -x` tracing.

     

       244
       245
        
       

     

       245
       245
       -
       ### Attributes affecting build properties

     

       246
       246
       +
       ### Attributes affecting build properties {#attributes-affecting-build-properties}

     

       246
       247
        
       

     

       247
       248
        
       #### `enableParallelBuilding` {#var-stdenv-enableParallelBuilding}

     

       248
       249
        
       

     
···

       250
       251
        
       

     

       251
       252
        
       Unless set to `false`, some build systems with good support for parallel building including `cmake`, `meson`, and `qmake` will set it to `true`.

     

       252
       253
        
       

     

       253
       253
       -
       ### Special variables

     

       254
       254
       +
       ### Special variables {#special-variables}

     

       254
       255
        
       

     

       255
       256
        
       #### `passthru` {#var-stdenv-passthru}

     

       256
       257
        
       

     
···

       298
       299
        
       

     

       299
       300
        
       The script will be run with `UPDATE_NIX_ATTR_PATH` environment variable set to the attribute path it is supposed to update.

     

       300
       301
        
       

     

       301
       301
       -
       ::: note

     

       302
       302
       +
       ::: {.note}

     

       302
       303
        
       The script will be usually run from the root of the Nixpkgs repository but you should not rely on that. Also note that the update scripts will be run in parallel by default; you should avoid running `git commit` or any other commands that cannot handle that.

     

       303
       304
        
       :::

     

       304
       305
        
       

     
···

       314
       315
        
       

     

       315
       316
        
       There are a number of variables that control what phases are executed and in what order:

     

       316
       317
        
       

     

       317
       317
       -
       #### Variables affecting phase control

     

       318
       318
       +
       #### Variables affecting phase control {#variables-affecting-phase-control}

     

       318
       319
        
       

     

       319
       320
        
       ##### `phases` {#var-stdenv-phases}

     

       320
       321
        
       

     
···

       354
       355
        
       

     

       355
       356
        
       The unpack phase is responsible for unpacking the source code of the package. The default implementation of `unpackPhase` unpacks the source files listed in the `src` environment variable to the current directory. It supports the following files by default:

     

       356
       357
        
       

     

       357
       357
       -
       #### Tar files

     

       358
       358
       +
       #### Tar files {#tar-files}

     

       358
       359
        
       

     

       359
       360
        
       These can optionally be compressed using `gzip` (`.tar.gz`, `.tgz` or `.tar.Z`), `bzip2` (`.tar.bz2`, `.tbz2` or `.tbz`) or `xz` (`.tar.xz`, `.tar.lzma` or `.txz`).

     

       360
       361
        
       

     

       361
       361
       -
       #### Zip files

     

       362
       362
       +
       #### Zip files {#zip-files}

     

       362
       363
        
       

     

       363
       364
        
       Zip files are unpacked using `unzip`. However, `unzip` is not in the standard environment, so you should add it to `nativeBuildInputs` yourself.

     

       364
       365
        
       

     

       365
       365
       -
       #### Directories in the Nix store

     

       366
       366
       +
       #### Directories in the Nix store {#directories-in-the-nix-store}

     

       366
       367
        
       

     

       367
       368
        
       These are simply copied to the current directory. The hash part of the file name is stripped, e.g. `/nix/store/1wydxgby13cz...-my-sources` would be copied to `my-sources`.

     

       368
       369
        
       

     

       369
       370
        
       Additional file types can be supported by setting the `unpackCmd` variable (see below).

     

       370
       371
        
       

     

       371
       371
       -
       #### Variables controlling the unpack phase

     

       372
       372
       +
       #### Variables controlling the unpack phase {#variables-controlling-the-unpack-phase}

     

       373
       373
       +
       

     

       372
       374
        
       ##### `srcs` / `src` {#var-stdenv-src}

     

       373
       375
        
       

     

       374
       376
        
       The list of source files or directories to be unpacked or copied. One of these must be set.

     
···

       405
       407
        
       

     

       406
       408
        
       The patch phase applies the list of patches defined in the `patches` variable.

     

       407
       409
        
       

     

       408
       408
       -
       #### Variables controlling the patch phase

     

       410
       410
       +
       #### Variables controlling the patch phase {#variables-controlling-the-patch-phase}

     

       409
       411
        
       

     

       410
       412
        
       ##### `dontPatch` {#var-stdenv-dontPatch}

     

       411
       413
        
       

     
···

       431
       433
        
       

     

       432
       434
        
       The configure phase prepares the source tree for building. The default `configurePhase` runs `./configure` (typically an Autoconf-generated script) if it exists.

     

       433
       435
        
       

     

       434
       434
       -
       #### Variables controlling the configure phase

     

       436
       436
       +
       #### Variables controlling the configure phase {#variables-controlling-the-configure-phase}

     

       435
       437
        
       

     

       436
       438
        
       ##### `configureScript` {#var-stdenv-configureScript}

     

       437
       439
        
       

     
···

       491
       493
        
       

     

       492
       494
        
       The build phase is responsible for actually building the package (e.g. compiling it). The default `buildPhase` simply calls `make` if a file named `Makefile`, `makefile` or `GNUmakefile` exists in the current directory (or the `makefile` is explicitly set); otherwise it does nothing.

     

       493
       495
        
       

     

       494
       494
       -
       #### Variables controlling the build phase

     

       496
       496
       +
       #### Variables controlling the build phase {#variables-controlling-the-build-phase}

     

       495
       497
        
       

     

       496
       498
        
       ##### `dontBuild` {#var-stdenv-dontBuild}

     

       497
       499
        
       

     
···

       509
       511
        
       makeFlags = [ "PREFIX=$(out)" ];

     

       510
       512
        
       ```

     

       511
       513
        
       

     

       512
       512
       -
       ::: note

     

       514
       514
       +
       ::: {.note}

     

       513
       515
        
       The flags are quoted in bash, but environment variables can be specified by using the make syntax.

     

       514
       516
        
       :::

     

       515
       517
        
       

     
···

       545
       547
        
       

     

       546
       548
        
       The check phase checks whether the package was built correctly by running its test suite. The default `checkPhase` calls `make check`, but only if the `doCheck` variable is enabled.

     

       547
       549
        
       

     

       548
       548
       -
       #### Variables controlling the check phase

     

       550
       550
       +
       #### Variables controlling the check phase {#variables-controlling-the-check-phase}

     

       549
       551
        
       

     

       550
       552
        
       ##### `doCheck` {#var-stdenv-doCheck}

     

       551
       553
        
       

     
···

       557
       559
        
       

     

       558
       560
        
       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.

     

       559
       561
        
       

     

       560
       560
       -
       ##### `makeFlags` / `makeFlagsArray` / `makefile`

     

       562
       562
       +
       ##### `makeFlags` / `makeFlagsArray` / `makefile` {#makeflags-makeflagsarray-makefile}

     

       561
       563
        
       

     

       562
       564
        
       See the [build phase](#var-stdenv-makeFlags) for details.

     

       563
       565
        
       

     
···

       585
       587
        
       

     

       586
       588
        
       The install phase is responsible for installing the package in the Nix store under `out`. The default `installPhase` creates the directory `$out` and calls `make install`.

     

       587
       589
        
       

     

       588
       588
       -
       #### Variables controlling the install phase

     

       590
       590
       +
       #### Variables controlling the install phase {#variables-controlling-the-install-phase}

     

       589
       591
        
       

     

       590
       592
        
       ##### `dontInstall` {#var-stdenv-dontInstall}

     

       591
       593
        
       

     

       592
       594
        
       Set to true to skip the install phase.

     

       593
       595
        
       

     

       594
       594
       -
       ##### `makeFlags` / `makeFlagsArray` / `makefile`

     

       596
       596
       +
       ##### `makeFlags` / `makeFlagsArray` / `makefile` {#makeflags-makeflagsarray-makefile-1}

     

       595
       597
        
       

     

       596
       598
        
       See the [build phase](#var-stdenv-makeFlags) for details.

     

       597
       599
        
       

     
···

       624
       626
        
       - On Linux, it applies the `patchelf` command to ELF executables and libraries to remove unused directories from the `RPATH` in order to prevent unnecessary runtime dependencies.

     

       625
       627
        
       - It rewrites the interpreter paths of shell scripts to paths found in `PATH`. E.g., `/usr/bin/perl` will be rewritten to `/nix/store/some-perl/bin/perl` found in `PATH`.

     

       626
       628
        
       

     

       627
       627
       -
       #### Variables controlling the fixup phase

     

       629
       629
       +
       #### Variables controlling the fixup phase {#variables-controlling-the-fixup-phase}

     

       628
       630
        
       

     

       629
       631
        
       ##### `dontFixup` {#var-stdenv-dontFixup}

     

       630
       632
        
       

     
···

       706
       708
        
       

     

       707
       709
        
       The installCheck phase checks whether the package was installed correctly by running its test suite against the installed directories. The default `installCheck` calls `make installcheck`.

     

       708
       710
        
       

     

       709
       709
       -
       #### Variables controlling the installCheck phase

     

       711
       711
       +
       #### Variables controlling the installCheck phase {#variables-controlling-the-installcheck-phase}

     

       710
       712
        
       

     

       711
       713
        
       ##### `doInstallCheck` {#var-stdenv-doInstallCheck}

     

       712
       714
        
       

     
···

       742
       744
        
       

     

       743
       745
        
       The distribution phase is intended to produce a source distribution of the package. The default `distPhase` first calls `make dist`, then it copies the resulting source tarballs to `$out/tarballs/`. This phase is only executed if the attribute `doDist` is set.

     

       744
       746
        
       

     

       745
       745
       -
       #### Variables controlling the distribution phase

     

       747
       747
       +
       #### Variables controlling the distribution phase {#variables-controlling-the-distribution-phase}

     

       746
       748
        
       

     

       747
       749
        
       ##### `distTarget` {#var-stdenv-distTarget}

     

       748
       750
        
       

     
···

       879
       881
        
       

     

       880
       882
        
       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 the wrapper 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 its setup hook is sourced. Additionally, since most environment hooks don’t care about the target platform, that means the setup hook can append to the right bash array by doing something like

     

       881
       883
        
       

     

       882
       882
       -
       ```{.bash}

     

       884
       884
       +
       ```bash

     

       883
       885
        
       addEnvHooks "$hostOffset" myBashFunction

     

       884
       886
        
       ```

     

       885
       887
        
       

     
···

       887
       889
        
       

     

       888
       890
        
       First, let’s cover some setup hooks that are part of Nixpkgs default stdenv. This means that they are run for every package built using `stdenv.mkDerivation`. Some of these are platform specific, so they may run on Linux but not Darwin or vice-versa.

     

       889
       891
        
       

     

       890
       890
       -
       ### `move-docs.sh`

     

       892
       892
       +
       ### `move-docs.sh` {#move-docs.sh}

     

       891
       893
        
       

     

       892
       894
        
       This setup hook moves any installed documentation to the `/share` subdirectory directory. This includes the man, doc and info directories. This is needed for legacy programs that do not know how to use the `share` subdirectory.

     

       893
       895
        
       

     

       894
       894
       -
       ### `compress-man-pages.sh`

     

       896
       896
       +
       ### `compress-man-pages.sh` {#compress-man-pages.sh}

     

       895
       897
        
       

     

       896
       898
        
       This setup hook compresses any man pages that have been installed. The compression is done using the gzip program. This helps to reduce the installed size of packages.

     

       897
       899
        
       

     

       898
       898
       -
       ### `strip.sh`

     

       900
       900
       +
       ### `strip.sh` {#strip.sh}

     

       899
       901
        
       

     

       900
       902
        
       This runs the strip command on installed binaries and libraries. This removes unnecessary information like debug symbols when they are not needed. This also helps to reduce the installed size of packages.

     

       901
       903
        
       

     

       902
       902
       -
       ### `patch-shebangs.sh`

     

       904
       904
       +
       ### `patch-shebangs.sh` {#patch-shebangs.sh}

     

       903
       905
        
       

     

       904
       906
        
       This setup hook patches installed scripts to use the full path to the shebang interpreter. A shebang interpreter is the first commented line of a script telling the operating system which program will run the script (e.g `#!/bin/bash`). In Nix, we want an exact path to that interpreter to be used. This often replaces `/bin/sh` with a path in the Nix store.

     

       905
       907
        
       

     

       906
       906
       -
       ### `audit-tmpdir.sh`

     

       908
       908
       +
       ### `audit-tmpdir.sh` {#audit-tmpdir.sh}

     

       907
       909
        
       

     

       908
       910
        
       This verifies that no references are left from the install binaries to the directory used to build those binaries. This ensures that the binaries do not need things outside the Nix store. This is currently supported in Linux only.

     

       909
       911
        
       

     

       910
       910
       -
       ### `multiple-outputs.sh`

     

       912
       912
       +
       ### `multiple-outputs.sh` {#multiple-outputs.sh}

     

       911
       913
        
       

     

       912
       914
        
       This setup hook adds configure flags that tell packages to install files into any one of the proper outputs listed in `outputs`. This behavior can be turned off by setting `setOutputFlags` to false in the derivation environment. See <xref linkend="chap-multiple-output" /> for more information.

     

       913
       915
        
       

     

       914
       914
       -
       ### `move-sbin.sh`

     

       916
       916
       +
       ### `move-sbin.sh` {#move-sbin.sh}

     

       915
       917
        
       

     

       916
       918
        
       This setup hook moves any binaries installed in the `sbin/` subdirectory into `bin/`. In addition, a link is provided from `sbin/` to `bin/` for compatibility.

     

       917
       919
        
       

     

       918
       918
       -
       ### `move-lib64.sh`

     

       920
       920
       +
       ### `move-lib64.sh` {#move-lib64.sh}

     

       919
       921
        
       

     

       920
       922
        
       This setup hook moves any libraries installed in the `lib64/` subdirectory into `lib/`. In addition, a link is provided from `lib64/` to `lib/` for compatibility.

     

       921
       923
        
       

     

       922
       922
       -
       ### `move-systemd-user-units.sh`

     

       924
       924
       +
       ### `move-systemd-user-units.sh` {#move-systemd-user-units.sh}

     

       923
       925
        
       

     

       924
       926
        
       This setup hook moves any systemd user units installed in the `lib/` subdirectory into `share/`. In addition, a link is provided from `share/` to `lib/` for compatibility. This is needed for systemd to find user services when installed into the user profile.

     

       925
       927
        
       

     

       926
       926
       -
       ### `set-source-date-epoch-to-latest.sh`

     

       928
       928
       +
       ### `set-source-date-epoch-to-latest.sh` {#set-source-date-epoch-to-latest.sh}

     

       927
       929
        
       

     

       928
       930
        
       This sets `SOURCE_DATE_EPOCH` to the modification time of the most recent file.

     

       929
       931
        
       

     

       930
       930
       -
       ### Bintools Wrapper

     

       932
       932
       +
       ### Bintools Wrapper {#bintools-wrapper}

     

       931
       933
        
       

     

       932
       934
        
       The Bintools Wrapper wraps the binary utilities for a bunch of miscellaneous purposes. These are GNU Binutils when targetting Linux, and a mix of cctools and GNU binutils for Darwin. \[The “Bintools” name is supposed to be a compromise between “Binutils” and “cctools” not denoting any specific implementation.\] Specifically, the underlying bintools package, and a C standard library (glibc or Darwin’s libSystem, just for the dynamic loader) are all fed in, and dependency finding, hardening (see below), and purity checks for each are handled by the Bintools Wrapper. Packages typically depend on CC Wrapper, which in turn (at run time) depends on the Bintools Wrapper.

     

       933
       935
        
       

     
···

       937
       939
        
       

     

       938
       940
        
       A problem with this final task is that the 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 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"`.

     

       939
       941
        
       

     

       940
       940
       -
       ### CC Wrapper

     

       942
       942
       +
       ### CC Wrapper {#cc-wrapper}

     

       941
       943
        
       

     

       942
       944
        
       The CC Wrapper wraps a C toolchain for a bunch of miscellaneous purposes. Specifically, a C compiler (GCC or Clang), wrapped binary tools, and a C standard library (glibc or Darwin’s libSystem, just for the dynamic loader) are all fed in, and dependency finding, hardening (see below), and purity checks for each are handled by the CC Wrapper. Packages typically depend on the CC Wrapper, which in turn (at run-time) depends on the Bintools Wrapper.

     

       943
       945
        
       

     
···

       971
       973
        
       

     

       972
       974
        
       Adds every file named `catalog.xml` found under the `xml/dtd` and `xml/xsl` subdirectories of each build input to the `XML_CATALOG_FILES` environment variable.

     

       973
       975
        
       

     

       974
       974
       -
       ### teTeX / TeX Live

     

       976
       976
       +
       ### teTeX / TeX Live {#tetex-tex-live}

     

       975
       977
        
       

     

       976
       978
        
       Adds the `share/texmf-nix` subdirectory of each build input to the `TEXINPUTS` environment variable.

     

       977
       979
        
       

     

       978
       978
       -
       ### Qt 4

     

       980
       980
       +
       ### Qt 4 {#qt-4}

     

       979
       981
        
       

     

       980
       982
        
       Sets the `QTDIR` environment variable to Qt’s path.

     

       981
       983
        
       

     
···

       983
       985
        
       

     

       984
       986
        
       Exports `GDK_PIXBUF_MODULE_FILE` environment variable to the builder. Add librsvg package to `buildInputs` to get svg support. See also the [setup hook description in GNOME platform docs](#ssec-gnome-hooks-gdk-pixbuf).

     

       985
       987
        
       

     

       986
       986
       -
       ### GHC

     

       988
       988
       +
       ### GHC {#ghc}

     

       987
       989
        
       

     

       988
       990
        
       Creates a temporary package database and registers every Haskell build input in it (TODO: how?).

     

       989
       991
        
       

     

       990
       990
       -
       ### GNOME platform

     

       992
       992
       +
       ### GNOME platform {#gnome-platform}

     

       991
       993
        
       

     

       992
       994
        
       Hooks related to GNOME platform and related libraries like GLib, GTK and GStreamer are described in <xref linkend="sec-language-gnome" />.

     

       993
       995
        
       

     
···

       1003
       1005
        
       

     

       1004
       1006
        
       The `autoPatchelf` command also recognizes a `--no-recurse` command line flag, which prevents it from recursing into subdirectories.

     

       1005
       1007
        
       

     

       1006
       1006
       -
       ### breakpointHook

     

       1008
       1008
       +
       ### breakpointHook {#breakpointhook}

     

       1007
       1009
        
       

     

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

     

       1009
       1011
        
       

     
···

       1013
       1015
        
       

     

       1014
       1016
        
       When a build failure happens there will be an instruction printed that shows how to attach with `cntr` to the build sandbox.

     

       1015
       1017
        
       

     

       1016
       1016
       -
       ::: note

     

       1017
       1017
       -
       ::: title

     

       1018
       1018
       +
       ::: {.note}

     

       1019
       1019
       +
       ::: {.title}

     

       1018
       1020
        
       Caution with remote builds

     

       1019
       1021
        
       :::

     

       1020
       1022
        
       

     

       1021
       1023
        
       This won’t work with remote builds as the build environment is on a different machine and can’t be accessed by `cntr`. Remote builds can be turned off by setting `--option builders ''` for `nix-build` or `--builders ''` for `nix build`.

     

       1022
       1024
        
       :::

     

       1023
       1025
        
       

     

       1024
       1024
       -
       ### installShellFiles

     

       1026
       1026
       +
       ### installShellFiles {#installshellfiles}

     

       1025
       1027
        
       

     

       1026
       1028
        
       This hook helps with installing manpages and shell completion files. It exposes 2 shell functions `installManPage` and `installShellCompletion` that can be used from your `postInstall` hook.

     

       1027
       1029
        
       

     
···

       1047
       1049
        
       '';

     

       1048
       1050
        
       ```

     

       1049
       1051
        
       

     

       1050
       1050
       -
       ### libiconv, libintl

     

       1052
       1052
       +
       ### libiconv, libintl {#libiconv-libintl}

     

       1051
       1053
        
       

     

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

     

       1053
       1055
        
       

     

       1054
       1054
       -
       ### validatePkgConfig

     

       1056
       1056
       +
       ### validatePkgConfig {#validatepkgconfig}

     

       1055
       1057
        
       

     

       1056
       1058
        
       The `validatePkgConfig` hook validates all pkg-config (`.pc`) files in a package. This helps catching some common errors in pkg-config files, such as undefined variables.

     

       1057
       1059
        
       

     

       1058
       1058
       -
       ### cmake

     

       1060
       1060
       +
       ### cmake {#cmake}

     

       1059
       1061
        
       

     

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

     

       1061
       1063
        
       

     

       1062
       1062
       -
       ### xcbuildHook

     

       1064
       1064
       +
       ### xcbuildHook {#xcbuildhook}

     

       1063
       1065
        
       

     

       1064
       1066
        
       Overrides the build and install phases to run the "xcbuild" command. This hook is needed when a project only comes with build files for the XCode build system. You can disable this behavior by setting buildPhase and configurePhase to a custom value. xcbuildFlags controls flags passed only to xcbuild.

     

       1065
       1067
        
       

     

       1066
       1066
       -
       ### Meson

     

       1068
       1068
       +
       ### Meson {#meson}

     

       1067
       1069
        
       

     

       1068
       1070
        
       Overrides the configure phase to run meson to generate Ninja files. To run these files, you should accompany Meson with ninja. By default, `enableParallelBuilding` is enabled as Meson supports parallel building almost everywhere.

     

       1069
       1071
        
       

     

       1070
       1070
       -
       #### Variables controlling Meson

     

       1072
       1072
       +
       #### Variables controlling Meson {#variables-controlling-meson}

     

       1071
       1073
        
       

     

       1072
       1072
       -
       ##### `mesonFlags`

     

       1074
       1074
       +
       ##### `mesonFlags` {#mesonflags}

     

       1073
       1075
        
       

     

       1074
       1076
        
       Controls the flags passed to meson.

     

       1075
       1077
        
       

     

       1076
       1076
       -
       ##### `mesonBuildType`

     

       1078
       1078
       +
       ##### `mesonBuildType` {#mesonbuildtype}

     

       1077
       1079
        
       

     

       1078
       1080
        
       Which [`--buildtype`](https://mesonbuild.com/Builtin-options.html#core-options) to pass to Meson. We default to `plain`.

     

       1079
       1081
        
       

     

       1080
       1080
       -
       ##### `mesonAutoFeatures`

     

       1082
       1082
       +
       ##### `mesonAutoFeatures` {#mesonautofeatures}

     

       1081
       1083
        
       

     

       1082
       1084
        
       What value to set [`-Dauto_features=`](https://mesonbuild.com/Builtin-options.html#core-options) to. We default to `enabled`.

     

       1083
       1085
        
       

     

       1084
       1084
       -
       ##### `mesonWrapMode`

     

       1086
       1086
       +
       ##### `mesonWrapMode` {#mesonwrapmode}

     

       1085
       1087
        
       

     

       1086
       1088
        
       What value to set [`-Dwrap_mode=`](https://mesonbuild.com/Builtin-options.html#core-options) to. We default to `nodownload` as we disallow network access.

     

       1087
       1089
        
       

     

       1088
       1088
       -
       ##### `dontUseMesonConfigure`

     

       1090
       1090
       +
       ##### `dontUseMesonConfigure` {#dontusemesonconfigure}

     

       1089
       1091
        
       

     

       1090
       1092
        
       Disables using Meson’s `configurePhase`.

     

       1091
       1093
        
       

     

       1092
       1092
       -
       ### ninja

     

       1094
       1094
       +
       ### ninja {#ninja}

     

       1093
       1095
        
       

     

       1094
       1096
        
       Overrides the build, install, and check phase to run ninja instead of make. You can disable this behavior with the `dontUseNinjaBuild`, `dontUseNinjaInstall`, and `dontUseNinjaCheck`, respectively. Parallel building is enabled by default in Ninja.

     

       1095
       1097
        
       

     

       1096
       1096
       -
       ### unzip

     

       1098
       1098
       +
       ### unzip {#unzip}

     

       1097
       1099
        
       

     

       1098
       1100
        
       This setup hook will allow you to unzip .zip files specified in `$src`. There are many similar packages like `unrar`, `undmg`, etc.

     

       1099
       1101
        
       

     

       1100
       1100
       -
       ### wafHook

     

       1102
       1102
       +
       ### wafHook {#wafhook}

     

       1101
       1103
        
       

     

       1102
       1104
        
       Overrides the configure, build, and install phases. This will run the “waf” script used by many projects. If `wafPath` (default `./waf`) doesn’t exist, it will copy the version of waf available in Nixpkgs. `wafFlags` can be used to pass flags to the waf script.

     

       1103
       1105
        
       

     

       1104
       1104
       -
       ### scons

     

       1106
       1106
       +
       ### scons {#scons}

     

       1105
       1107
        
       

     

       1106
       1108
        
       Overrides the build, install, and check phases. This uses the scons build system as a replacement for make. scons does not provide a configure phase, so everything is managed at build and install time.

     

       1107
       1109
        
       

     
···

       1119
       1121
        
       

     

       1120
       1122
        
       The following flags are enabled by default and might require disabling with `hardeningDisable` if the program to package is incompatible.

     

       1121
       1123
        
       

     

       1122
       1122
       -
       ### `format`

     

       1124
       1124
       +
       ### `format` {#format}

     

       1123
       1125
        
       

     

       1124
       1126
        
       Adds the `-Wformat -Wformat-security -Werror=format-security` compiler options. At present, this warns about calls to `printf` and `scanf` functions where the format string is not a string literal and there are no format arguments, as in `printf(foo);`. This may be a security hole if the format string came from untrusted input and contains `%n`.

     

       1125
       1127
        
       

     
···

       1132
       1134
        
       cc1plus: some warnings being treated as errors

     

       1133
       1135
        
       ```

     

       1134
       1136
        
       

     

       1135
       1135
       -
       ### `stackprotector`

     

       1137
       1137
       +
       ### `stackprotector` {#stackprotector}

     

       1136
       1138
        
       

     

       1137
       1139
        
       Adds the `-fstack-protector-strong --param ssp-buffer-size=4` compiler options. This adds safety checks against stack overwrites rendering many potential code injection attacks into aborting situations. In the best case this turns code injection vulnerabilities into denial of service or into non-issues (depending on the application).

     

       1138
       1140
        
       

     
···

       1143
       1145
        
       /tmp/nix-build-ipxe-20141124-5cbdc41.drv-0/ipxe-5cbdc41/src/arch/i386/firmware/pcbios/bios_console.c:86: undefined reference to `__stack_chk_fail'

     

       1144
       1146
        
       ```

     

       1145
       1147
        
       

     

       1146
       1146
       -
       ### `fortify`

     

       1148
       1148
       +
       ### `fortify` {#fortify}

     

       1147
       1149
        
       

     

       1148
       1150
        
       Adds the `-O2 -D_FORTIFY_SOURCE=2` compiler options. During code generation the compiler knows a great deal of information about buffer sizes (where possible), and attempts to replace insecure unlimited length buffer function calls with length-limited ones. This is especially useful for old, crufty code. Additionally, format strings in writable memory that contain `%n` are blocked. If an application depends on such a format string, it will need to be worked around.

     

       1149
       1151
        
       

     
···

       1164
       1166
        
       fcntl2.h:50:4: error: call to '__open_missing_mode' declared with attribute error: open with O_CREAT or O_TMPFILE in second argument needs 3 arguments

     

       1165
       1167
        
       ```

     

       1166
       1168
        
       

     

       1167
       1167
       -
       ### `pic`

     

       1169
       1169
       +
       ### `pic` {#pic}

     

       1168
       1170
        
       

     

       1169
       1171
        
       Adds the `-fPIC` compiler options. This options adds support for position independent code in shared libraries and thus making ASLR possible.

     

       1170
       1172
        
       

     
···

       1177
       1179
        
       ccbLfRgg.s:33: Error: missing or invalid displacement expression `private_key_len@GOTOFF'

     

       1178
       1180
        
       ```

     

       1179
       1181
        
       

     

       1180
       1180
       -
       ### `strictoverflow`

     

       1182
       1182
       +
       ### `strictoverflow` {#strictoverflow}

     

       1181
       1183
        
       

     

       1182
       1184
        
       Signed integer overflow is undefined behaviour according to the C standard. If it happens, it is an error in the program as it should check for overflow before it can happen, not afterwards. GCC provides built-in functions to perform arithmetic with overflow checking, which are correct and faster than any custom implementation. As a workaround, the option `-fno-strict-overflow` makes gcc behave as if signed integer overflows were defined.

     

       1183
       1185
        
       

     

       1184
       1186
        
       This flag should not trigger any build or runtime errors.

     

       1185
       1187
        
       

     

       1186
       1186
       -
       ### `relro`

     

       1188
       1188
       +
       ### `relro` {#relro}

     

       1187
       1189
        
       

     

       1188
       1190
        
       Adds the `-z relro` linker option. During program load, several ELF memory sections need to be written to by the linker, but can be turned read-only before turning over control to the program. This prevents some GOT (and .dtors) overwrite attacks, but at least the part of the GOT used by the dynamic linker (.got.plt) is still vulnerable.

     

       1189
       1191
        
       

     

       1190
       1192
        
       This flag can break dynamic shared object loading. For instance, the module systems of Xorg and OpenCV are incompatible with this flag. In almost all cases the `bindnow` flag must also be disabled and incompatible programs typically fail with similar errors at runtime.

     

       1191
       1193
        
       

     

       1192
       1192
       -
       ### `bindnow`

     

       1194
       1194
       +
       ### `bindnow` {#bindnow}

     

       1193
       1195
        
       

     

       1194
       1196
        
       Adds the `-z bindnow` linker option. During program load, all dynamic symbols are resolved, allowing for the complete GOT to be marked read-only (due to `relro`). This prevents GOT overwrite attacks. For very large applications, this can incur some performance loss during initial load while symbols are resolved, but this shouldn’t be an issue for daemons.

     

       1195
       1197
        
       

     
···

       1201
       1203
        
       

     

       1202
       1204
        
       The following flags are disabled by default and should be enabled with `hardeningEnable` for packages that take untrusted input like network services.

     

       1203
       1205
        
       

     

       1204
       1204
       -
       ### `pie`

     

       1206
       1206
       +
       ### `pie` {#pie}

     

       1205
       1207
        
       

     

       1206
       1208
        
       Adds the `-fPIE` compiler and `-pie` linker options. Position Independent Executables are needed to take advantage of Address Space Layout Randomization, supported by modern kernel versions. While ASLR can already be enforced for data areas in the stack and heap (brk and mmap), the code areas must be compiled as position-independent. Shared libraries already do this with the `pic` flag, so they gain ASLR automatically, but binary .text regions need to be build with `pie` to gain ASLR. When this happens, ROP attacks are much harder since there are no static locations to bounce off of during a memory corruption attack.

     

       1207
       1209

+1 -1

doc/using/overlays.chapter.md

···

       63
       63
        
       

     

       64
       64
        
       The value returned by this function should be a set similar to `pkgs/top-level/all-packages.nix`, containing overridden and/or new packages.

     

       65
       65
        
       

     

       66
       66
       -
       Overlays are similar to other methods for customizing Nixpkgs, in particular the `packageOverrides` attribute described in <xref linkend="sec-modify-via-packageOverrides"/>. Indeed, `packageOverrides` acts as an overlay with only the `super` argument. It is therefore appropriate for basic use, but overlays are more powerful and easier to distribute.

     

       66
       66
       +
       Overlays are similar to other methods for customizing Nixpkgs, in particular the `packageOverrides` attribute described in<xref linkend="sec-modify-via-packageOverrides"/>. Indeed, `packageOverrides` acts as an overlay with only the `super` argument. It is therefore appropriate for basic use, but overlays are more powerful and easier to distribute.

     

       67
       67
        
       

     

       68
       68
        
       ## Using overlays to configure alternatives {#sec-overlays-alternatives}

     

       69
       69

+6 -6

doc/using/overrides.chapter.md

···

       48
       48
        
       

     

       49
       49
        
       The argument `oldAttrs` is conventionally used to refer to the attr set originally passed to `stdenv.mkDerivation`.

     

       50
       50
        
       

     

       51
       51
       -
       ::: note

     

       52
       52
       -
       Note that `separateDebugInfo` is processed only by the `stdenv.mkDerivation` function, not the generated, raw Nix derivation.  Thus, using `overrideDerivation` will not work in this case, as it overrides only the attributes of the final derivation. It is for this reason that `overrideAttrs` should be preferred in (almost) all cases to `overrideDerivation`, i.e. to allow using `stdenv.mkDerivation` to process input arguments, as well as the fact that it is easier to use (you can use the same attribute names you see in your Nix code, instead of the ones generated (e.g. `buildInputs` vs `nativeBuildInputs`), and it involves less typing).

     

       51
       51
       +
       ::: {.note}

     

       52
       52
       +
       Note that `separateDebugInfo` is processed only by the `stdenv.mkDerivation` function, not the generated, raw Nix derivation. Thus, using `overrideDerivation` will not work in this case, as it overrides only the attributes of the final derivation. It is for this reason that `overrideAttrs` should be preferred in (almost) all cases to `overrideDerivation`, i.e. to allow using `stdenv.mkDerivation` to process input arguments, as well as the fact that it is easier to use (you can use the same attribute names you see in your Nix code, instead of the ones generated (e.g. `buildInputs` vs `nativeBuildInputs`), and it involves less typing).

     

       53
       53
        
       :::

     

       54
       54
        
       

     

       55
       55
        
       ## &lt;pkg&gt;.overrideDerivation {#sec-pkg-overrideDerivation}

     

       56
       56
        
       

     

       57
       57
       -
       ::: warning

     

       57
       57
       +
       ::: {.warning}

     

       58
       58
        
       You should prefer `overrideAttrs` in almost all cases, see its documentation for the reasons why. `overrideDerivation` is not deprecated and will continue to work, but is less nice to use and does not have as many abilities as `overrideAttrs`.

     

       59
       59
        
       :::

     

       60
       60
        
       

     

       61
       61
       -
       ::: warning

     

       61
       61
       +
       ::: {.warning}

     

       62
       62
        
       Do not use this function in Nixpkgs as it evaluates a Derivation before modifying it, which breaks package abstraction and removes error-checking of function arguments. In addition, this evaluation-per-function application incurs a performance penalty, which can become a problem if many overrides are used. It is only intended for ad-hoc customisation, such as in `~/.config/nixpkgs/config.nix`.

     

       63
       63
        
       :::

     

       64
       64
        
       

     
···

       81
       81
        
       

     

       82
       82
        
       The argument `oldAttrs` is used to refer to the attribute set of the original derivation.

     

       83
       83
        
       

     

       84
       84
       -
       ::: note

     

       85
       85
       -
       A package's attributes are evaluated *before* being modified by the `overrideDerivation` function. For example, the `name` attribute reference in `url = "mirror://gnu/hello/${name}.tar.gz";` is filled-in *before* the `overrideDerivation` function modifies the attribute set.  This means that overriding the `name` attribute, in this example, *will not* change the value of the `url` attribute. Instead, we need to override both the `name` *and* `url` attributes.

     

       84
       84
       +
       ::: {.note}

     

       85
       85
       +
       A package's attributes are evaluated *before* being modified by the `overrideDerivation` function. For example, the `name` attribute reference in `url = "mirror://gnu/hello/${name}.tar.gz";` is filled-in *before* the `overrideDerivation` function modifies the attribute set. This means that overriding the `name` attribute, in this example, *will not* change the value of the `url` attribute. Instead, we need to override both the `name` *and* `url` attributes.

     

       86
       86
        
       :::

     

       87
       87
        
       

     

       88
       88
        
       ## lib.makeOverridable {#sec-lib-makeOverridable}