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