pyrox.dev
doc: update the appimageTools section content and examples (#276029)
The following changes are made:
- Document how `wrapType2` and `wrapType1` are the same thing.
- Expand on how `wrapType2` works and additional arguments it uses.
- Document `extract` and show how it's used in combination with
`wrapType2`.
- Provide full working examples using the new admonition syntax.
authored by Daniel Sidhion and committed by GitHub e525be5a 173bc992
+144
-25
doc/build-helpers/images/appimagetools.section.md
+144
-25
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. They are meant to be used if traditional packaging from source is infeasible, or it would take too long. To quickly run an AppImage file, `pkgs.appimage-run` can be used as well.
4
5
::: {.warning}
6
The `appimageTools` API is unstable and may be subject to backwards-incompatible changes in the future.
7
:::
8
9
-
## AppImage formats {#ssec-pkgs-appimageTools-formats}
10
11
-
There are different formats for AppImages, see [the specification](https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format) for details.
12
13
-
- Type 1 images are ISO 9660 files that are also ELF executables.
14
-
- Type 2 images are ELF executables with an appended filesystem.
15
16
-
They can be told apart with `file -k`:
17
18
-
```ShellSession
19
-
$ file -k type1.AppImage
20
-
type1.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) ISO 9660 CD-ROM filesystem data 'AppImage' (Lepton 3.x), scale 0-0,
21
-
spot sensor temperature 0.000000, unit celsius, color scheme 0, calibration: offset 0.000000, slope 0.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=d629f6099d2344ad82818172add1d38c5e11bc6d, stripped\012- data
22
23
-
$ file -k type2.AppImage
24
-
type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x), scale 232-60668, spot sensor temperature -4.187500, color scheme 15, show scale bar, calibration: offset -0.000000, slope 0.000000 (Lepton 2.x), scale 4111-45000, spot sensor temperature 412442.250000, color scheme 3, minimum point enabled, calibration: offset -75402534979642766821519867692934234112.000000, slope 5815371847733706829839455140374904832.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=79dcc4e55a61c293c5e19edbd8d65b202842579f, stripped\012- data
25
```
26
27
-
Note how the type 1 AppImage is described as an `ISO 9660 CD-ROM filesystem`, and the type 2 AppImage is not.
28
29
-
## Wrapping {#ssec-pkgs-appimageTools-wrapping}
30
31
-
Depending on the type of AppImage you're wrapping, you'll have to use `wrapType1` or `wrapType2`.
32
33
```nix
34
-
appimageTools.wrapType2 { # or wrapType1
35
-
name = "patchwork";
36
src = fetchurl {
37
-
url = "https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage";
38
-
hash = "sha256-OqTitCeZ6xmWbqYTXp8sDrmVgTNjPZNW0hzUPW++mq4=";
39
};
40
-
extraPkgs = pkgs: with pkgs; [ ];
41
}
42
```
43
44
-
- `name` specifies the name of the resulting image.
45
-
- `src` specifies the AppImage file to extract.
46
-
- `extraPkgs` allows you to pass a function to include additional packages inside the FHS environment your AppImage is going to run in. There are a few ways to learn which dependencies an application needs:
47
-
- Looking through the extracted AppImage files, reading its scripts and running `patchelf` and `ldd` on its executables. This can also be done in `appimage-run`, by setting `APPIMAGE_DEBUG_EXEC=bash`.
48
-
- Running `strace -vfefile` on the wrapped executable, looking for libraries that can't be found.
···
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
+
:::