Unverified Commit dbc86c1b authored by Guillaume Girol's avatar Guillaume Girol Committed by GitHub
Browse files

Merge pull request #176595 from symphorien/appimage-run-doc 

nixos/doc: explain how to run appimages
parents 468d2bdc fd3fc309

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

+30 −5
Original line number Diff line number Diff line 
# Adding Custom Packages {#sec-custom-packages}



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

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

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

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

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

In short, you clone Nixpkgs:

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

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

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

using pre-built executables.



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



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

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

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

repository. This is described in detail in the [Nixpkgs

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



```ShellSession

$ git clone https://github.com/NixOS/nixpkgs
@@ -72,3 +79,21 @@ $ nix-build my-hello.nix 
$ ./result/bin/hello

Hello, world!

```



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



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

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

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

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



```nix

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

```



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



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

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

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

is complex and often doing a source build is easier.

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

+77 −39
Original line number Diff line number Diff line
@@ -2,10 +2,20 @@ 
  <title>Adding Custom Packages</title>

  <para>

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

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

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

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

    repository. This is described in detail in the

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

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

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

    software from source is often easier than using pre-built

    executables.

  </para>

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

    <title>Building with Nix</title>

    <para>

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

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

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

      have it accepted into the main Nixpkgs repository. This is

      described in detail in the

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

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

    </para>
@@ -29,8 +39,8 @@ environment.systemPackages = [ pkgs.my-package ]; 
# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs

</programlisting>

    <para>

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

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

      The second possibility is to add the package outside of the

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

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

      Hello</link> package directly in

      <literal>configuration.nix</literal>:
@@ -78,3 +88,31 @@ $ ./result/bin/hello 
Hello, world!

</programlisting>

  </section>

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

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

    <para>

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

      notable exceptions: flatpaks and AppImages. For flatpaks see the

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

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

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

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

    </para>

    <programlisting language="bash">

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

</programlisting>

    <para>

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

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

    </para>

    <para>

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

      package them with Nix and special helpers like

      <literal>autoPatchelfHook</literal> or

      <literal>buildFHSUserEnv</literal>. See the

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

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

      source build is easier.

    </para>

  </section>

</section>