commit dbc86c1be8371240455fd4c4e108fcfd9373111d · pyrox.dev/nixpkgs

+30 -5

nixos/doc/manual/configuration/adding-custom-packages.section.md

···

       1
       1
        
       # Adding Custom Packages {#sec-custom-packages}

     

       2
       2
        
       

     

       3
       3
        
       It's possible that a package you need is not available in NixOS. In that

     

       4
       4
       -
       case, you can do two things. First, you can clone the Nixpkgs

     

       5
       5
       -
       repository, add the package to your clone, and (optionally) submit a

     

       6
       6
       -
       patch or pull request to have it accepted into the main Nixpkgs repository.

     

       7
       7
       -
       This is described in detail in the [Nixpkgs manual](https://nixos.org/nixpkgs/manual).

     

       8
       8
       -
       In short, you clone Nixpkgs:

     

       4
       4
       +
       case, you can do two things. Either you can package it with Nix, or you can try

     

       5
       5
       +
       to use prebuilt packages from upstream. Due to the peculiarities of NixOS, it

     

       6
       6
       +
       is important to note that building software from source is often easier than

     

       7
       7
       +
       using pre-built executables.

     

       8
       8
       +
       

     

       9
       9
       +
       ## Building with Nix {#sec-custom-packages-nix}

     

       10
       10
       +
       

     

       11
       11
       +
       This can be done either in-tree or out-of-tree. For an in-tree build, you can

     

       12
       12
       +
       clone the Nixpkgs repository, add the package to your clone, and (optionally)

     

       13
       13
       +
       submit a patch or pull request to have it accepted into the main Nixpkgs

     

       14
       14
       +
       repository. This is described in detail in the [Nixpkgs

     

       15
       15
       +
       manual](https://nixos.org/nixpkgs/manual). In short, you clone Nixpkgs:

     

       9
       16
        
       

     

       10
       17
        
       ```ShellSession

     

       11
       18
        
       $ git clone https://github.com/NixOS/nixpkgs

     
···

       72
       79
        
       $ ./result/bin/hello

     

       73
       80
        
       Hello, world!

     

       74
       81
        
       ```

     

       82
       82
       +
       

     

       83
       83
       +
       ## Using pre-built executables {#sec-custom-packages-prebuilt}

     

       84
       84
       +
       

     

       85
       85
       +
       Most pre-built executables will not work on NixOS. There are two notable

     

       86
       86
       +
       exceptions: flatpaks and AppImages. For flatpaks see the [dedicated

     

       87
       87
       +
       section](#module-services-flatpak). AppImages will not run "as-is" on NixOS.

     

       88
       88
       +
       First you need to install `appimage-run`: add to `/etc/nixos/configuration.nix`

     

       89
       89
       +
       

     

       90
       90
       +
       ```nix

     

       91
       91
       +
       environment.systemPackages = [ pkgs.appimage-run ];

     

       92
       92
       +
       ```

     

       93
       93
       +
       

     

       94
       94
       +
       Then instead of running the AppImage "as-is", run `appimage-run foo.appimage`.

     

       95
       95
       +
       

     

       96
       96
       +
       To make other pre-built executables work on NixOS, you need to package them

     

       97
       97
       +
       with Nix and special helpers like `autoPatchelfHook` or `buildFHSUserEnv`. See

     

       98
       98
       +
       the [Nixpkgs manual](https://nixos.org/nixpkgs/manual) for details. This

     

       99
       99
       +
       is complex and often doing a source build is easier.

+77 -39

nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml

···

       2
       2
        
         <title>Adding Custom Packages</title>

     

       3
       3
        
         <para>

     

       4
       4
        
           It’s possible that a package you need is not available in NixOS. In

     

       5
       5
       -
           that case, you can do two things. First, you can clone the Nixpkgs

     

       6
       6
       -
           repository, add the package to your clone, and (optionally) submit a

     

       7
       7
       -
           patch or pull request to have it accepted into the main Nixpkgs

     

       8
       8
       -
           repository. This is described in detail in the

     

       9
       9
       -
           <link xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs

     

       10
       10
       -
           manual</link>. In short, you clone Nixpkgs:

     

       5
       5
       +
           that case, you can do two things. Either you can package it with

     

       6
       6
       +
           Nix, or you can try to use prebuilt packages from upstream. Due to

     

       7
       7
       +
           the peculiarities of NixOS, it is important to note that building

     

       8
       8
       +
           software from source is often easier than using pre-built

     

       9
       9
       +
           executables.

     

       11
       10
        
         </para>

     

       12
       12
       -
         <programlisting>

     

       11
       11
       +
         <section xml:id="sec-custom-packages-nix">

     

       12
       12
       +
           <title>Building with Nix</title>

     

       13
       13
       +
           <para>

     

       14
       14
       +
             This can be done either in-tree or out-of-tree. For an in-tree

     

       15
       15
       +
             build, you can clone the Nixpkgs repository, add the package to

     

       16
       16
       +
             your clone, and (optionally) submit a patch or pull request to

     

       17
       17
       +
             have it accepted into the main Nixpkgs repository. This is

     

       18
       18
       +
             described in detail in the

     

       19
       19
       +
             <link xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs

     

       20
       20
       +
             manual</link>. In short, you clone Nixpkgs:

     

       21
       21
       +
           </para>

     

       22
       22
       +
           <programlisting>

     

       13
       23
        
       $ git clone https://github.com/NixOS/nixpkgs

     

       14
       24
        
       $ cd nixpkgs

     

       15
       25
        
       </programlisting>

     

       16
       16
       -
         <para>

     

       17
       17
       -
           Then you write and test the package as described in the Nixpkgs

     

       18
       18
       -
           manual. Finally, you add it to

     

       19
       19
       -
           <xref linkend="opt-environment.systemPackages" />, e.g.

     

       20
       20
       -
         </para>

     

       21
       21
       -
         <programlisting language="bash">

     

       26
       26
       +
           <para>

     

       27
       27
       +
             Then you write and test the package as described in the Nixpkgs

     

       28
       28
       +
             manual. Finally, you add it to

     

       29
       29
       +
             <xref linkend="opt-environment.systemPackages" />, e.g.

     

       30
       30
       +
           </para>

     

       31
       31
       +
           <programlisting language="bash">

     

       22
       32
        
       environment.systemPackages = [ pkgs.my-package ];

     

       23
       33
        
       </programlisting>

     

       24
       24
       -
         <para>

     

       25
       25
       -
           and you run <literal>nixos-rebuild</literal>, specifying your own

     

       26
       26
       -
           Nixpkgs tree:

     

       27
       27
       -
         </para>

     

       28
       28
       -
         <programlisting>

     

       34
       34
       +
           <para>

     

       35
       35
       +
             and you run <literal>nixos-rebuild</literal>, specifying your own

     

       36
       36
       +
             Nixpkgs tree:

     

       37
       37
       +
           </para>

     

       38
       38
       +
           <programlisting>

     

       29
       39
        
       # nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs

     

       30
       40
        
       </programlisting>

     

       31
       31
       -
         <para>

     

       32
       32
       -
           The second possibility is to add the package outside of the Nixpkgs

     

       33
       33
       -
           tree. For instance, here is how you specify a build of the

     

       34
       34
       -
           <link xlink:href="https://www.gnu.org/software/hello/">GNU

     

       35
       35
       -
           Hello</link> package directly in

     

       36
       36
       -
           <literal>configuration.nix</literal>:

     

       37
       37
       -
         </para>

     

       38
       38
       -
         <programlisting language="bash">

     

       41
       41
       +
           <para>

     

       42
       42
       +
             The second possibility is to add the package outside of the

     

       43
       43
       +
             Nixpkgs tree. For instance, here is how you specify a build of the

     

       44
       44
       +
             <link xlink:href="https://www.gnu.org/software/hello/">GNU

     

       45
       45
       +
             Hello</link> package directly in

     

       46
       46
       +
             <literal>configuration.nix</literal>:

     

       47
       47
       +
           </para>

     

       48
       48
       +
           <programlisting language="bash">

     

       39
       49
        
       environment.systemPackages =

     

       40
       50
        
         let

     

       41
       51
        
           my-hello = with pkgs; stdenv.mkDerivation rec {

     
···

       48
       58
        
         in

     

       49
       59
        
         [ my-hello ];

     

       50
       60
        
       </programlisting>

     

       51
       51
       -
         <para>

     

       52
       52
       -
           Of course, you can also move the definition of

     

       53
       53
       -
           <literal>my-hello</literal> into a separate Nix expression, e.g.

     

       54
       54
       -
         </para>

     

       55
       55
       -
         <programlisting language="bash">

     

       61
       61
       +
           <para>

     

       62
       62
       +
             Of course, you can also move the definition of

     

       63
       63
       +
             <literal>my-hello</literal> into a separate Nix expression, e.g.

     

       64
       64
       +
           </para>

     

       65
       65
       +
           <programlisting language="bash">

     

       56
       66
        
       environment.systemPackages = [ (import ./my-hello.nix) ];

     

       57
       67
        
       </programlisting>

     

       58
       58
       -
         <para>

     

       59
       59
       -
           where <literal>my-hello.nix</literal> contains:

     

       60
       60
       -
         </para>

     

       61
       61
       -
         <programlisting language="bash">

     

       68
       68
       +
           <para>

     

       69
       69
       +
             where <literal>my-hello.nix</literal> contains:

     

       70
       70
       +
           </para>

     

       71
       71
       +
           <programlisting language="bash">

     

       62
       72
        
       with import &lt;nixpkgs&gt; {}; # bring all of Nixpkgs into scope

     

       63
       73
        
       

     

       64
       74
        
       stdenv.mkDerivation rec {

     
···

       69
       79
        
         };

     

       70
       80
        
       }

     

       71
       81
        
       </programlisting>

     

       72
       72
       -
         <para>

     

       73
       73
       -
           This allows testing the package easily:

     

       74
       74
       -
         </para>

     

       75
       75
       -
         <programlisting>

     

       82
       82
       +
           <para>

     

       83
       83
       +
             This allows testing the package easily:

     

       84
       84
       +
           </para>

     

       85
       85
       +
           <programlisting>

     

       76
       86
        
       $ nix-build my-hello.nix

     

       77
       87
        
       $ ./result/bin/hello

     

       78
       88
        
       Hello, world!

     

       79
       89
        
       </programlisting>

     

       90
       90
       +
         </section>

     

       91
       91
       +
         <section xml:id="sec-custom-packages-prebuilt">

     

       92
       92
       +
           <title>Using pre-built executables</title>

     

       93
       93
       +
           <para>

     

       94
       94
       +
             Most pre-built executables will not work on NixOS. There are two

     

       95
       95
       +
             notable exceptions: flatpaks and AppImages. For flatpaks see the

     

       96
       96
       +
             <link linkend="module-services-flatpak">dedicated section</link>.

     

       97
       97
       +
             AppImages will not run <quote>as-is</quote> on NixOS. First you

     

       98
       98
       +
             need to install <literal>appimage-run</literal>: add to

     

       99
       99
       +
             <literal>/etc/nixos/configuration.nix</literal>

     

       100
       100
       +
           </para>

     

       101
       101
       +
           <programlisting language="bash">

     

       102
       102
       +
       environment.systemPackages = [ pkgs.appimage-run ];

     

       103
       103
       +
       </programlisting>

     

       104
       104
       +
           <para>

     

       105
       105
       +
             Then instead of running the AppImage <quote>as-is</quote>, run

     

       106
       106
       +
             <literal>appimage-run foo.appimage</literal>.

     

       107
       107
       +
           </para>

     

       108
       108
       +
           <para>

     

       109
       109
       +
             To make other pre-built executables work on NixOS, you need to

     

       110
       110
       +
             package them with Nix and special helpers like

     

       111
       111
       +
             <literal>autoPatchelfHook</literal> or

     

       112
       112
       +
             <literal>buildFHSUserEnv</literal>. See the

     

       113
       113
       +
             <link xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs

     

       114
       114
       +
             manual</link> for details. This is complex and often doing a

     

       115
       115
       +
             source build is easier.

     

       116
       116
       +
           </para>

     

       117
       117
       +
         </section>

     

       80
       118
        
       </section>