pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-custom-packages">
2 <title>Adding Custom Packages</title>
3 <para>
4 It’s possible that a package you need is not available in NixOS. In
5 that case, you can do two things. Either you can package it with
6 Nix, or you can try to use prebuilt packages from upstream. Due to
7 the peculiarities of NixOS, it is important to note that building
8 software from source is often easier than using pre-built
9 executables.
10 </para>
11 <section xml:id="sec-custom-packages-nix">
12 <title>Building with Nix</title>
13 <para>
14 This can be done either in-tree or out-of-tree. For an in-tree
15 build, you can clone the Nixpkgs repository, add the package to
16 your clone, and (optionally) submit a patch or pull request to
17 have it accepted into the main Nixpkgs repository. This is
18 described in detail in the
19 <link xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs
20 manual</link>. In short, you clone Nixpkgs:
21 </para>
22 <programlisting>
23$ git clone https://github.com/NixOS/nixpkgs
24$ cd nixpkgs
25</programlisting>
26 <para>
27 Then you write and test the package as described in the Nixpkgs
28 manual. Finally, you add it to
29 <xref linkend="opt-environment.systemPackages" />, e.g.
30 </para>
31 <programlisting language="bash">
32environment.systemPackages = [ pkgs.my-package ];
33</programlisting>
34 <para>
35 and you run <literal>nixos-rebuild</literal>, specifying your own
36 Nixpkgs tree:
37 </para>
38 <programlisting>
39# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs
40</programlisting>
41 <para>
42 The second possibility is to add the package outside of the
43 Nixpkgs tree. For instance, here is how you specify a build of the
44 <link xlink:href="https://www.gnu.org/software/hello/">GNU
45 Hello</link> package directly in
46 <literal>configuration.nix</literal>:
47 </para>
48 <programlisting language="bash">
49environment.systemPackages =
50 let
51 my-hello = with pkgs; stdenv.mkDerivation rec {
52 name = "hello-2.8";
53 src = fetchurl {
54 url = "mirror://gnu/hello/${name}.tar.gz";
55 sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
56 };
57 };
58 in
59 [ my-hello ];
60</programlisting>
61 <para>
62 Of course, you can also move the definition of
63 <literal>my-hello</literal> into a separate Nix expression, e.g.
64 </para>
65 <programlisting language="bash">
66environment.systemPackages = [ (import ./my-hello.nix) ];
67</programlisting>
68 <para>
69 where <literal>my-hello.nix</literal> contains:
70 </para>
71 <programlisting language="bash">
72with import <nixpkgs> {}; # bring all of Nixpkgs into scope
73
74stdenv.mkDerivation rec {
75 name = "hello-2.8";
76 src = fetchurl {
77 url = "mirror://gnu/hello/${name}.tar.gz";
78 sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
79 };
80}
81</programlisting>
82 <para>
83 This allows testing the package easily:
84 </para>
85 <programlisting>
86$ nix-build my-hello.nix
87$ ./result/bin/hello
88Hello, world!
89</programlisting>
90 </section>
91 <section xml:id="sec-custom-packages-prebuilt">
92 <title>Using pre-built executables</title>
93 <para>
94 Most pre-built executables will not work on NixOS. There are two
95 notable exceptions: flatpaks and AppImages. For flatpaks see the
96 <link linkend="module-services-flatpak">dedicated section</link>.
97 AppImages will not run <quote>as-is</quote> on NixOS. First you
98 need to install <literal>appimage-run</literal>: add to
99 <literal>/etc/nixos/configuration.nix</literal>
100 </para>
101 <programlisting language="bash">
102environment.systemPackages = [ pkgs.appimage-run ];
103</programlisting>
104 <para>
105 Then instead of running the AppImage <quote>as-is</quote>, run
106 <literal>appimage-run foo.appimage</literal>.
107 </para>
108 <para>
109 To make other pre-built executables work on NixOS, you need to
110 package them with Nix and special helpers like
111 <literal>autoPatchelfHook</literal> or
112 <literal>buildFHSUserEnv</literal>. See the
113 <link xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs
114 manual</link> for details. This is complex and often doing a
115 source build is easier.
116 </para>
117 </section>
118</section>