doc/build-helpers/images/appimagetools.section.md

   1 # pkgs.appimageTools {#sec-pkgs-appimageTools}
   2
   3 `pkgs.appimageTools` is a set of functions for extracting and wrapping [AppImage](https://appimage.org/) files.
   4 They are meant to be used if traditional packaging from source is infeasible, or if it would take too long.
   5 To quickly run an AppImage file, `pkgs.appimage-run` can be used as well.
   6
   7 ::: {.warning}
   8 The `appimageTools` API is unstable and may be subject to backwards-incompatible changes in the future.
   9 :::
  10
  11 ## Wrapping {#ssec-pkgs-appimageTools-wrapping}
  12
  13 Use `wrapType2` to wrap any AppImage.
  14 This will create a FHS environment with many packages [expected to exist](https://github.com/AppImage/pkg2appimage/blob/master/excludelist) for the AppImage to work.
  15 `wrapType2` expects an argument with the `src` attribute, and either a `name` attribute or `pname` and `version` attributes.
  16
  17 It will eventually call into [`buildFHSEnv`](#sec-fhs-environments), and any extra attributes in the argument to `wrapType2` will be passed through to it.
  18 This means that you can pass the `extraInstallCommands` attribute, for example, and it will have the same effect as described in [`buildFHSEnv`](#sec-fhs-environments).
  19
  20 ::: {.note}
  21 In the past, `appimageTools` provided both `wrapType1` and `wrapType2`, to be used depending on the type of AppImage that was being wrapped.
  22 However, [those were unified early 2020](https://github.com/NixOS/nixpkgs/pull/81833), meaning that both `wrapType1` and `wrapType2` have the same behaviour now.
  23 :::
  24
  25 :::{.example #ex-wrapping-appimage-from-github}
  26
  27 # Wrapping an AppImage from GitHub
  28
  29 ```nix
  30 { appimageTools, fetchurl }:
  31 let
  32   pname = "nuclear";
  33   version = "0.6.30";
  34
  35   src = fetchurl {
  36     url = "https://github.com/nukeop/nuclear/releases/download/v${version}/${pname}-v${version}.AppImage";
  37     hash = "sha256-he1uGC1M/nFcKpMM9JKY4oeexJcnzV0ZRxhTjtJz6xw=";
  38   };
  39 in
  40 appimageTools.wrapType2 {
  41   inherit pname version src;
  42 }
  43 ```
  44
  45 :::
  46
  47 The argument passed to `wrapType2` can also contain an `extraPkgs` attribute, which allows you to include additional packages inside the FHS environment your AppImage is going to run in.
  48 `extraPkgs` must be a function that returns a list of packages.
  49 There are a few ways to learn which dependencies an application needs:
  50
  51   - Looking through the extracted AppImage files, reading its scripts and running `patchelf` and `ldd` on its executables.
  52     This can also be done in `appimage-run`, by setting `APPIMAGE_DEBUG_EXEC=bash`.
  53   - Running `strace -vfefile` on the wrapped executable, looking for libraries that can't be found.
  54
  55 :::{.example #ex-wrapping-appimage-with-extrapkgs}
  56
  57 # Wrapping an AppImage with extra packages
  58
  59 ```nix
  60 { appimageTools, fetchurl }:
  61 let
  62   pname = "irccloud";
  63   version = "0.16.0";
  64
  65   src = fetchurl {
  66     url = "https://github.com/irccloud/irccloud-desktop/releases/download/v${version}/IRCCloud-${version}-linux-x86_64.AppImage";
  67     sha256 = "sha256-/hMPvYdnVB1XjKgU2v47HnVvW4+uC3rhRjbucqin4iI=";
  68   };
  69 in appimageTools.wrapType2 {
  70   inherit pname version src;
  71   extraPkgs = pkgs: [ pkgs.at-spi2-core ];
  72 }
  73 ```
  74
  75 :::
  76
  77 ## Extracting {#ssec-pkgs-appimageTools-extracting}
  78
  79 Use `extract` if you need to extract the contents of an AppImage.
  80 This is usually used in Nixpkgs to install extra files in addition to [wrapping](#ssec-pkgs-appimageTools-wrapping) the AppImage.
  81 `extract` expects an argument with the `src` attribute, and either a `name` attribute or `pname` and `version` attributes.
  82
  83 ::: {.note}
  84 In the past, `appimageTools` provided both `extractType1` and `extractType2`, to be used depending on the type of AppImage that was being extracted.
  85 However, [those were unified early 2020](https://github.com/NixOS/nixpkgs/pull/81572), meaning that both `extractType1` and `extractType2` have the same behaviour as `extract` now.
  86 :::
  87
  88 :::{.example #ex-extracting-appimage}
  89
  90 # Extracting an AppImage to install extra files
  91
  92 This example was adapted from a real package in Nixpkgs to show how `extract` is usually used in combination with `wrapType2`.
  93 Note how `appimageContents` is used in `extraInstallCommands` to install additional files that were extracted from the AppImage.
  94
  95 ```nix
  96 { appimageTools, fetchurl }:
  97 let
  98   pname = "irccloud";
  99   version = "0.16.0";
 100
 101   src = fetchurl {
 102     url = "https://github.com/irccloud/irccloud-desktop/releases/download/v${version}/IRCCloud-${version}-linux-x86_64.AppImage";
 103     sha256 = "sha256-/hMPvYdnVB1XjKgU2v47HnVvW4+uC3rhRjbucqin4iI=";
 104   };
 105
 106   appimageContents = appimageTools.extract {
 107     inherit pname version src;
 108   };
 109 in appimageTools.wrapType2 {
 110   inherit pname version src;
 111
 112   extraPkgs = pkgs: [ pkgs.at-spi2-core ];
 113
 114   extraInstallCommands = ''
 115     mv $out/bin/${pname}-${version} $out/bin/${pname}
 116     install -m 444 -D ${appimageContents}/irccloud.desktop $out/share/applications/irccloud.desktop
 117     install -m 444 -D ${appimageContents}/usr/share/icons/hicolor/512x512/apps/irccloud.png \
 118       $out/share/icons/hicolor/512x512/apps/irccloud.png
 119     substituteInPlace $out/share/applications/irccloud.desktop \
 120       --replace 'Exec=AppRun' 'Exec=${pname}'
 121   '';
 122 }
 123 ```
 124
 125 :::
 126
 127 The argument passed to `extract` can also contain a `postExtract` attribute, which allows you to execute additional commands after the files are extracted from the AppImage.
 128 `postExtract` must be a string with commands to run.
 129
 130 :::{.example #ex-extracting-appimage-with-postextract}
 131
 132 # Extracting an AppImage to install extra files, using `postExtract`
 133
 134 This is a rewrite of [](#ex-extracting-appimage) to use `postExtract`.
 135
 136 ```nix
 137 { appimageTools, fetchurl }:
 138 let
 139   pname = "irccloud";
 140   version = "0.16.0";
 141
 142   src = fetchurl {
 143     url = "https://github.com/irccloud/irccloud-desktop/releases/download/v${version}/IRCCloud-${version}-linux-x86_64.AppImage";
 144     sha256 = "sha256-/hMPvYdnVB1XjKgU2v47HnVvW4+uC3rhRjbucqin4iI=";
 145   };
 146
 147   appimageContents = appimageTools.extract {
 148     inherit pname version src;
 149     postExtract = ''
 150       substituteInPlace $out/irccloud.desktop --replace 'Exec=AppRun' 'Exec=${pname}'
 151     '';
 152   };
 153 in appimageTools.wrapType2 {
 154   inherit pname version src;
 155
 156   extraPkgs = pkgs: [ pkgs.at-spi2-core ];
 157
 158   extraInstallCommands = ''
 159     mv $out/bin/${pname}-${version} $out/bin/${pname}
 160     install -m 444 -D ${appimageContents}/irccloud.desktop $out/share/applications/irccloud.desktop
 161     install -m 444 -D ${appimageContents}/usr/share/icons/hicolor/512x512/apps/irccloud.png \
 162       $out/share/icons/hicolor/512x512/apps/irccloud.png
 163   '';
 164 }
 165 ```
 166
 167 :::