diff options
author | Graham Christensen <graham@grahamc.com> | 2019-02-23 18:06:31 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-02-23 18:06:31 -0500 |
commit | 695fb802f104ad2fbb39cba383d336d4dd560434 (patch) | |
tree | ac32e0aeda27e5b9b98a021ad40ace5c719658e7 /doc/functions | |
parent | 245c11c6139dfcbc5678e87dd925c866d4bae242 (diff) | |
parent | 58443d8a506a67de76f09e8ca57bc5b010798cbe (diff) |
Merge pull request #54693 from tilpner/appimage-tools
appimageTools: init
Diffstat (limited to 'doc/functions')
-rw-r--r-- | doc/functions/appimagetools.xml | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/doc/functions/appimagetools.xml b/doc/functions/appimagetools.xml new file mode 100644 index 0000000000000..270ab067bc39b --- /dev/null +++ b/doc/functions/appimagetools.xml @@ -0,0 +1,121 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="sec-pkgs-appimageTools"> + <title>pkgs.appimageTools</title> + + <para> + <varname>pkgs.appimageTools</varname> is a set of functions for extracting and wrapping + <link xlink:href="https://appimage.org/">AppImage</link> 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, <literal>pkgs.appimage-run</literal> can be used as well. + </para> + + <warning> + <para> + The <varname>appimageTools</varname> API is unstable and may be subject to + backwards-incompatible changes in the future. + </para> + </warning> + + + <section xml:id="ssec-pkgs-appimageTools-formats"> + <title>AppImage formats</title> + + <para> + There are different formats for AppImages, see + <link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the specification</link> for details. + </para> + + <itemizedlist> + <listitem> + <para> + Type 1 images are ISO 9660 files that are also ELF executables. + </para> + </listitem> + + <listitem> + <para> + Type 2 images are ELF executables with an appended filesystem. + </para> + </listitem> + </itemizedlist> + + <para> + They can be told apart with <command>file -k</command>: + </para> + + <screen> +<prompt>$ </prompt>file -k type1.AppImage +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, +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 + +<prompt>$ </prompt>file -k type2.AppImage +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 + </screen> + + <para> + Note how the type 1 AppImage is described as an <literal>ISO 9660 CD-ROM filesystem</literal>, and the type 2 AppImage is not. + </para> + </section> + + <section xml:id="ssec-pkgs-appimageTools-wrapping"> + <title>Wrapping</title> + + <para> + Depending on the type of AppImage you're wrapping, you'll have to use + <varname>wrapType1</varname> or <varname>wrapType2</varname>. + </para> + + + <programlisting> +appimageTools.wrapType2 { # or wrapType1 + name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' /> + src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' /> + url = https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage; + sha256 = "1blsprpkvm0ws9b96gb36f0rbf8f5jgmw4x6dsb1kswr4ysf591s"; + }; + extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' /> +}</programlisting> + + + <calloutlist> + <callout arearefs='ex-appimageTools-wrapping-1'> + <para> + <varname>name</varname> specifies the name of the resulting image. + </para> + </callout> + <callout arearefs='ex-appimageTools-wrapping-2'> + <para> + <varname>src</varname> specifies the AppImage file to extract. + </para> + </callout> + <callout arearefs='ex-appimageTools-wrapping-2'> + <para> + <varname>extraPkgs</varname> 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: + + <itemizedlist> + <listitem> + <para> + Looking through the extracted AppImage files, reading its scripts and running <command>patchelf</command> and <command>ldd</command> on its executables. + This can also be done in <command>appimage-run</command>, by setting <command>APPIMAGE_DEBUG_EXEC=bash</command>. + </para> + </listitem> + + <listitem> + <para> + Running <command>strace -vfefile</command> on the wrapped executable, looking for libraries that can't be found. + </para> + </listitem> + </itemizedlist> + + </para> + </callout> + </calloutlist> + + </section> +</section> |