tjh.dev
1<section xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 xml:id="sec-pkgs-appimageTools">
5 <title>pkgs.appimageTools</title>
6
7 <para>
8 <varname>pkgs.appimageTools</varname> is a set of functions for extracting and wrapping
9 <link xlink:href="https://appimage.org/">AppImage</link> files.
10
11 They are meant to be used if traditional packaging from source is infeasible, or it would take too long.
12 To quickly run an AppImage file, <literal>pkgs.appimage-run</literal> can be used as well.
13 </para>
14
15 <warning>
16 <para>
17 The <varname>appimageTools</varname> API is unstable and may be subject to
18 backwards-incompatible changes in the future.
19 </para>
20 </warning>
21
22
23 <section xml:id="ssec-pkgs-appimageTools-formats">
24 <title>AppImage formats</title>
25
26 <para>
27 There are different formats for AppImages, see
28 <link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the specification</link> for details.
29 </para>
30
31 <itemizedlist>
32 <listitem>
33 <para>
34 Type 1 images are ISO 9660 files that are also ELF executables.
35 </para>
36 </listitem>
37
38 <listitem>
39 <para>
40 Type 2 images are ELF executables with an appended filesystem.
41 </para>
42 </listitem>
43 </itemizedlist>
44
45 <para>
46 They can be told apart with <command>file -k</command>:
47 </para>
48
49 <screen>
50<prompt>$ </prompt>file -k type1.AppImage
51type1.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) ISO 9660 CD-ROM filesystem data 'AppImage' (Lepton 3.x), scale 0-0,
52spot 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
53
54<prompt>$ </prompt>file -k type2.AppImage
55type2.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
56 </screen>
57
58 <para>
59 Note how the type 1 AppImage is described as an <literal>ISO 9660 CD-ROM filesystem</literal>, and the type 2 AppImage is not.
60 </para>
61 </section>
62
63 <section xml:id="ssec-pkgs-appimageTools-wrapping">
64 <title>Wrapping</title>
65
66 <para>
67 Depending on the type of AppImage you're wrapping, you'll have to use
68 <varname>wrapType1</varname> or <varname>wrapType2</varname>.
69 </para>
70
71
72 <programlisting>
73appimageTools.wrapType2 { # or wrapType1
74 name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' />
75 src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' />
76 url = https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage;
77 sha256 = "1blsprpkvm0ws9b96gb36f0rbf8f5jgmw4x6dsb1kswr4ysf591s";
78 };
79 extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' />
80}</programlisting>
81
82
83 <calloutlist>
84 <callout arearefs='ex-appimageTools-wrapping-1'>
85 <para>
86 <varname>name</varname> specifies the name of the resulting image.
87 </para>
88 </callout>
89 <callout arearefs='ex-appimageTools-wrapping-2'>
90 <para>
91 <varname>src</varname> specifies the AppImage file to extract.
92 </para>
93 </callout>
94 <callout arearefs='ex-appimageTools-wrapping-2'>
95 <para>
96 <varname>extraPkgs</varname> allows you to pass a function to include additional packages
97 inside the FHS environment your AppImage is going to run in.
98
99 There are a few ways to learn which dependencies an application needs:
100
101 <itemizedlist>
102 <listitem>
103 <para>
104 Looking through the extracted AppImage files, reading its scripts and running <command>patchelf</command> and <command>ldd</command> on its executables.
105 This can also be done in <command>appimage-run</command>, by setting <command>APPIMAGE_DEBUG_EXEC=bash</command>.
106 </para>
107 </listitem>
108
109 <listitem>
110 <para>
111 Running <command>strace -vfefile</command> on the wrapped executable, looking for libraries that can't be found.
112 </para>
113 </listitem>
114 </itemizedlist>
115
116 </para>
117 </callout>
118 </calloutlist>
119
120 </section>
121</section>