commit 90bf25d0377046e006d41971795e04d7530e22c1 · pyrox.dev/nixpkgs

+1 -75

doc/contributing/quick-start.chapter.md

···

       1
       1
        
       # Quick Start to Adding a Package {#chap-quick-start}

     

       2
       2
        
       

     

       3
       3
       -
       To add a package to Nixpkgs:

     

       4
       4
       -
       

     

       5
       5
       -
       1. Checkout the Nixpkgs source tree:

     

       6
       6
       -
       

     

       7
       7
       -
          ```ShellSession

     

       8
       8
       -
          $ git clone https://github.com/NixOS/nixpkgs

     

       9
       9
       -
          $ cd nixpkgs

     

       10
       10
       -
          ```

     

       11
       11
       -
       

     

       12
       12
       -
       2. Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into `pkgs/development/libraries/pkgname`, while a web browser goes into `pkgs/applications/networking/browsers/pkgname`. See [](#sec-organisation) for some hints on the tree organisation. Create a directory for your package, e.g.

     

       13
       13
       -
       

     

       14
       14
       -
          ```ShellSession

     

       15
       15
       -
          $ mkdir pkgs/development/libraries/libfoo

     

       16
       16
       -
          ```

     

       17
       17
       -
       

     

       18
       18
       -
       3. In the package directory, create a Nix expression — a piece of code that describes how to build the package. In this case, it should be a _function_ that is called with the package dependencies as arguments, and returns a build of the package in the Nix store. The expression should usually be called `default.nix`.

     

       19
       19
       -
       

     

       20
       20
       -
          ```ShellSession

     

       21
       21
       -
          $ emacs pkgs/development/libraries/libfoo/default.nix

     

       22
       22
       -
          $ git add pkgs/development/libraries/libfoo/default.nix

     

       23
       23
       -
          ```

     

       24
       24
       -
       

     

       25
       25
       -
          You can have a look at the existing Nix expressions under `pkgs/` to see how it’s done. Here are some good ones:

     

       26
       26
       -
       

     

       27
       27
       -
          - GNU Hello: [`pkgs/applications/misc/hello/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hello/default.nix). Trivial package, which specifies some `meta` attributes which is good practice.

     

       28
       28
       -
       

     

       29
       29
       -
          - GNU cpio: [`pkgs/tools/archivers/cpio/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/archivers/cpio/default.nix). Also a simple package. The generic builder in `stdenv` does everything for you. It has no dependencies beyond `stdenv`.

     

       30
       30
       -
       

     

       31
       31
       -
          - GNU Multiple Precision arithmetic library (GMP): [`pkgs/development/libraries/gmp/5.1.x.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/gmp/5.1.x.nix). Also done by the generic builder, but has a dependency on `m4`.

     

       32
       32
       -
       

     

       33
       33
       -
          - Pan, a GTK-based newsreader: [`pkgs/applications/networking/newsreaders/pan/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/newsreaders/pan/default.nix). Has an optional dependency on `gtkspell`, which is only built if `spellCheck` is `true`.

     

       34
       34
       -
       

     

       35
       35
       -
          - Apache HTTPD: [`pkgs/servers/http/apache-httpd/2.4.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/http/apache-httpd/2.4.nix). A bunch of optional features, variable substitutions in the configure flags, a post-install hook, and miscellaneous hackery.

     

       36
       36
       -
       

     

       37
       37
       -
          - buildMozillaMach: [`pkgs/applications/networking/browser/firefox/common.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/browsers/firefox/common.nix). A reusable build function for Firefox, Thunderbird and Librewolf.

     

       38
       38
       -
       

     

       39
       39
       -
          - JDiskReport, a Java utility: [`pkgs/tools/misc/jdiskreport/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/default.nix). Nixpkgs doesn’t have a decent `stdenv` for Java yet so this is pretty ad-hoc.

     

       40
       40
       -
       

     

       41
       41
       -
          - XML::Simple, a Perl module: [`pkgs/top-level/perl-packages.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix) (search for the `XMLSimple` attribute). Most Perl modules are so simple to build that they are defined directly in `perl-packages.nix`; no need to make a separate file for them.

     

       42
       42
       -
       

     

       43
       43
       -
          - Adobe Reader: [`pkgs/applications/misc/adobe-reader/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/default.nix). Shows how binary-only packages can be supported. In particular the [builder](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/builder.sh) uses `patchelf` to set the RUNPATH and ELF interpreter of the executables so that the right libraries are found at runtime.

     

       44
       44
       -
       

     

       45
       45
       -
          Some notes:

     

       46
       46
       -
       

     

       47
       47
       -
          - All [`meta`](#chap-meta) attributes are optional, but it’s still a good idea to provide at least the `description`, `homepage` and [`license`](#sec-meta-license).

     

       48
       48
       -
       

     

       49
       49
       -
          - You can use `nix-prefetch-url url` to get the SHA-256 hash of source distributions. There are similar commands as `nix-prefetch-git` and `nix-prefetch-hg` available in `nix-prefetch-scripts` package.

     

       50
       50
       -
       

     

       51
       51
       -
          - A list of schemes for `mirror://` URLs can be found in [`pkgs/build-support/fetchurl/mirrors.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/fetchurl/mirrors.nix).

     

       52
       52
       -
       

     

       53
       53
       -
          The exact syntax and semantics of the Nix expression language, including the built-in function, are described in the Nix manual in the [chapter on writing Nix expressions](https://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions).

     

       54
       54
       -
       

     

       55
       55
       -
       4. Add a call to the function defined in the previous step to [`pkgs/top-level/all-packages.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix) with some descriptive name for the variable, e.g. `libfoo`.

     

       56
       56
       -
       

     

       57
       57
       -
          ```ShellSession

     

       58
       58
       -
          $ emacs pkgs/top-level/all-packages.nix

     

       59
       59
       -
          ```

     

       60
       60
       -
       

     

       61
       61
       -
          The attributes in that file are sorted by category (like “Development / Libraries”) that more-or-less correspond to the directory structure of Nixpkgs, and then by attribute name.

     

       62
       62
       -
       

     

       63
       63
       -
       5. To test whether the package builds, run the following command from the root of the nixpkgs source tree:

     

       64
       64
       -
       

     

       65
       65
       -
          ```ShellSession

     

       66
       66
       -
          $ nix-build -A libfoo

     

       67
       67
       -
          ```

     

       68
       68
       -
       

     

       69
       69
       -
          where `libfoo` should be the variable name defined in the previous step. You may want to add the flag `-K` to keep the temporary build directory in case something fails. If the build succeeds, a symlink `./result` to the package in the Nix store is created.

     

       70
       70
       -
       

     

       71
       71
       -
       6. If you want to install the package into your profile (optional), do

     

       72
       72
       -
       

     

       73
       73
       -
          ```ShellSession

     

       74
       74
       -
          $ nix-env -f . -iA libfoo

     

       75
       75
       -
          ```

     

       76
       76
       -
       

     

       77
       77
       -
       7. Optionally commit the new package and open a pull request [to nixpkgs](https://github.com/NixOS/nixpkgs/pulls), or use [the Patches category](https://discourse.nixos.org/t/about-the-patches-category/477) on Discourse for sending a patch without a GitHub account.

     

       3
       3
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

+78

pkgs/README.md

···

       1
       1
        
       # Contributing to Nixpkgs packages

     

       2
       2
        
       

     

       3
       3
       +
       ## Quick Start to Adding a Package {#chap-quick-start}

     

       4
       4
       +
       

     

       5
       5
       +
       To add a package to Nixpkgs:

     

       6
       6
       +
       

     

       7
       7
       +
       1. Checkout the Nixpkgs source tree:

     

       8
       8
       +
       

     

       9
       9
       +
          ```ShellSession

     

       10
       10
       +
          $ git clone https://github.com/NixOS/nixpkgs

     

       11
       11
       +
          $ cd nixpkgs

     

       12
       12
       +
          ```

     

       13
       13
       +
       

     

       14
       14
       +
       2. Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into `pkgs/development/libraries/pkgname`, while a web browser goes into `pkgs/applications/networking/browsers/pkgname`. See [](#sec-organisation) for some hints on the tree organisation. Create a directory for your package, e.g.

     

       15
       15
       +
       

     

       16
       16
       +
          ```ShellSession

     

       17
       17
       +
          $ mkdir pkgs/development/libraries/libfoo

     

       18
       18
       +
          ```

     

       19
       19
       +
       

     

       20
       20
       +
       3. In the package directory, create a Nix expression — a piece of code that describes how to build the package. In this case, it should be a _function_ that is called with the package dependencies as arguments, and returns a build of the package in the Nix store. The expression should usually be called `default.nix`.

     

       21
       21
       +
       

     

       22
       22
       +
          ```ShellSession

     

       23
       23
       +
          $ emacs pkgs/development/libraries/libfoo/default.nix

     

       24
       24
       +
          $ git add pkgs/development/libraries/libfoo/default.nix

     

       25
       25
       +
          ```

     

       26
       26
       +
       

     

       27
       27
       +
          You can have a look at the existing Nix expressions under `pkgs/` to see how it’s done. Here are some good ones:

     

       28
       28
       +
       

     

       29
       29
       +
          - GNU Hello: [`pkgs/applications/misc/hello/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hello/default.nix). Trivial package, which specifies some `meta` attributes which is good practice.

     

       30
       30
       +
       

     

       31
       31
       +
          - GNU cpio: [`pkgs/tools/archivers/cpio/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/archivers/cpio/default.nix). Also a simple package. The generic builder in `stdenv` does everything for you. It has no dependencies beyond `stdenv`.

     

       32
       32
       +
       

     

       33
       33
       +
          - GNU Multiple Precision arithmetic library (GMP): [`pkgs/development/libraries/gmp/5.1.x.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/gmp/5.1.x.nix). Also done by the generic builder, but has a dependency on `m4`.

     

       34
       34
       +
       

     

       35
       35
       +
          - Pan, a GTK-based newsreader: [`pkgs/applications/networking/newsreaders/pan/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/newsreaders/pan/default.nix). Has an optional dependency on `gtkspell`, which is only built if `spellCheck` is `true`.

     

       36
       36
       +
       

     

       37
       37
       +
          - Apache HTTPD: [`pkgs/servers/http/apache-httpd/2.4.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/http/apache-httpd/2.4.nix). A bunch of optional features, variable substitutions in the configure flags, a post-install hook, and miscellaneous hackery.

     

       38
       38
       +
       

     

       39
       39
       +
          - buildMozillaMach: [`pkgs/applications/networking/browser/firefox/common.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/browsers/firefox/common.nix). A reusable build function for Firefox, Thunderbird and Librewolf.

     

       40
       40
       +
       

     

       41
       41
       +
          - JDiskReport, a Java utility: [`pkgs/tools/misc/jdiskreport/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/default.nix). Nixpkgs doesn’t have a decent `stdenv` for Java yet so this is pretty ad-hoc.

     

       42
       42
       +
       

     

       43
       43
       +
          - XML::Simple, a Perl module: [`pkgs/top-level/perl-packages.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix) (search for the `XMLSimple` attribute). Most Perl modules are so simple to build that they are defined directly in `perl-packages.nix`; no need to make a separate file for them.

     

       44
       44
       +
       

     

       45
       45
       +
          - Adobe Reader: [`pkgs/applications/misc/adobe-reader/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/default.nix). Shows how binary-only packages can be supported. In particular the [builder](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/builder.sh) uses `patchelf` to set the RUNPATH and ELF interpreter of the executables so that the right libraries are found at runtime.

     

       46
       46
       +
       

     

       47
       47
       +
          Some notes:

     

       48
       48
       +
       

     

       49
       49
       +
          - All [`meta`](#chap-meta) attributes are optional, but it’s still a good idea to provide at least the `description`, `homepage` and [`license`](#sec-meta-license).

     

       50
       50
       +
       

     

       51
       51
       +
          - You can use `nix-prefetch-url url` to get the SHA-256 hash of source distributions. There are similar commands as `nix-prefetch-git` and `nix-prefetch-hg` available in `nix-prefetch-scripts` package.

     

       52
       52
       +
       

     

       53
       53
       +
          - A list of schemes for `mirror://` URLs can be found in [`pkgs/build-support/fetchurl/mirrors.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/fetchurl/mirrors.nix).

     

       54
       54
       +
       

     

       55
       55
       +
          The exact syntax and semantics of the Nix expression language, including the built-in function, are described in the Nix manual in the [chapter on writing Nix expressions](https://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions).

     

       56
       56
       +
       

     

       57
       57
       +
       4. Add a call to the function defined in the previous step to [`pkgs/top-level/all-packages.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix) with some descriptive name for the variable, e.g. `libfoo`.

     

       58
       58
       +
       

     

       59
       59
       +
          ```ShellSession

     

       60
       60
       +
          $ emacs pkgs/top-level/all-packages.nix

     

       61
       61
       +
          ```

     

       62
       62
       +
       

     

       63
       63
       +
          The attributes in that file are sorted by category (like “Development / Libraries”) that more-or-less correspond to the directory structure of Nixpkgs, and then by attribute name.

     

       64
       64
       +
       

     

       65
       65
       +
       5. To test whether the package builds, run the following command from the root of the nixpkgs source tree:

     

       66
       66
       +
       

     

       67
       67
       +
          ```ShellSession

     

       68
       68
       +
          $ nix-build -A libfoo

     

       69
       69
       +
          ```

     

       70
       70
       +
       

     

       71
       71
       +
          where `libfoo` should be the variable name defined in the previous step. You may want to add the flag `-K` to keep the temporary build directory in case something fails. If the build succeeds, a symlink `./result` to the package in the Nix store is created.

     

       72
       72
       +
       

     

       73
       73
       +
       6. If you want to install the package into your profile (optional), do

     

       74
       74
       +
       

     

       75
       75
       +
          ```ShellSession

     

       76
       76
       +
          $ nix-env -f . -iA libfoo

     

       77
       77
       +
          ```

     

       78
       78
       +
       

     

       79
       79
       +
       7. Optionally commit the new package and open a pull request [to nixpkgs](https://github.com/NixOS/nixpkgs/pulls), or use [the Patches category](https://discourse.nixos.org/t/about-the-patches-category/477) on Discourse for sending a patch without a GitHub account.

     

       80
       80
       +
       

     

       3
       81
        
       ## Hierarchy {#sec-hierarchy}

     

       4
       82
        
       

     

       5
       83
        
       Each package should be stored in its own directory somewhere in the `pkgs/` tree, i.e. in `pkgs/category/subcategory/.../pkgname`. Below are some rules for picking the right category for a package. Many packages fall under several categories; what matters is the _primary_ purpose of a package. For example, the `libxml2` package builds both a library and some tools; but it’s a library foremost, so it goes under `pkgs/development/libraries`.