parent
9e400a8b93
commit
228276fbd0
@ -0,0 +1,48 @@ |
||||
# pkgs.appimageTools {#sec-pkgs-appimageTools} |
||||
|
||||
`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. |
||||
|
||||
::: warning |
||||
The `appimageTools` API is unstable and may be subject to backwards-incompatible changes in the future. |
||||
::: |
||||
|
||||
## AppImage formats {#ssec-pkgs-appimageTools-formats} |
||||
|
||||
There are different formats for AppImages, see [the specification](https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format) for details. |
||||
|
||||
- Type 1 images are ISO 9660 files that are also ELF executables. |
||||
- Type 2 images are ELF executables with an appended filesystem. |
||||
|
||||
They can be told apart with `file -k`: |
||||
|
||||
```ShellSession |
||||
$ 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 |
||||
|
||||
$ 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 |
||||
``` |
||||
|
||||
Note how the type 1 AppImage is described as an `ISO 9660 CD-ROM filesystem`, and the type 2 AppImage is not. |
||||
|
||||
## Wrapping {#ssec-pkgs-appimageTools-wrapping} |
||||
|
||||
Depending on the type of AppImage you're wrapping, you'll have to use `wrapType1` or `wrapType2`. |
||||
|
||||
```nix |
||||
appimageTools.wrapType2 { # or wrapType1 |
||||
name = "patchwork"; |
||||
src = fetchurl { |
||||
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; [ ]; |
||||
} |
||||
``` |
||||
|
||||
- `name` specifies the name of the resulting image. |
||||
- `src` specifies the AppImage file to extract. |
||||
- `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: |
||||
- 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`. |
||||
- Running `strace -vfefile` on the wrapped executable, looking for libraries that can't be found. |
@ -1,102 +0,0 @@ |
||||
<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-3'> |
||||
<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> |
@ -1,28 +0,0 @@ |
||||
let |
||||
inherit (import <nixpkgs> { }) snapTools firefox; |
||||
in snapTools.makeSnap { |
||||
meta = { |
||||
name = "nix-example-firefox"; |
||||
summary = firefox.meta.description; |
||||
architectures = [ "amd64" ]; |
||||
apps.nix-example-firefox = { |
||||
command = "${firefox}/bin/firefox"; |
||||
plugs = [ |
||||
"pulseaudio" |
||||
"camera" |
||||
"browser-support" |
||||
"avahi-observe" |
||||
"cups-control" |
||||
"desktop" |
||||
"desktop-legacy" |
||||
"gsettings" |
||||
"home" |
||||
"network" |
||||
"mount-observe" |
||||
"removable-media" |
||||
"x11" |
||||
]; |
||||
}; |
||||
confinement = "strict"; |
||||
}; |
||||
} |
@ -1,12 +0,0 @@ |
||||
let |
||||
inherit (import <nixpkgs> { }) snapTools hello; |
||||
in snapTools.makeSnap { |
||||
meta = { |
||||
name = "hello"; |
||||
summary = hello.meta.description; |
||||
description = hello.meta.longDescription; |
||||
architectures = [ "amd64" ]; |
||||
confinement = "strict"; |
||||
apps.hello.command = "${hello}/bin/hello"; |
||||
}; |
||||
} |
@ -0,0 +1,71 @@ |
||||
# pkgs.snapTools {#sec-pkgs-snapTools} |
||||
|
||||
`pkgs.snapTools` is a set of functions for creating Snapcraft images. Snap and Snapcraft is not used to perform these operations. |
||||
|
||||
## The makeSnap Function {#ssec-pkgs-snapTools-makeSnap-signature} |
||||
|
||||
`makeSnap` takes a single named argument, `meta`. This argument mirrors [the upstream `snap.yaml` format](https://docs.snapcraft.io/snap-format) exactly. |
||||
|
||||
The `base` should not be specified, as `makeSnap` will force set it. |
||||
|
||||
Currently, `makeSnap` does not support creating GUI stubs. |
||||
|
||||
## Build a Hello World Snap {#ssec-pkgs-snapTools-build-a-snap-hello} |
||||
|
||||
The following expression packages GNU Hello as a Snapcraft snap. |
||||
|
||||
```{#ex-snapTools-buildSnap-hello .nix} |
||||
let |
||||
inherit (import <nixpkgs> { }) snapTools hello; |
||||
in snapTools.makeSnap { |
||||
meta = { |
||||
name = "hello"; |
||||
summary = hello.meta.description; |
||||
description = hello.meta.longDescription; |
||||
architectures = [ "amd64" ]; |
||||
confinement = "strict"; |
||||
apps.hello.command = "${hello}/bin/hello"; |
||||
}; |
||||
} |
||||
``` |
||||
|
||||
`nix-build` this expression and install it with `snap install ./result --dangerous`. `hello` will now be the Snapcraft version of the package. |
||||
|
||||
## Build a Graphical Snap {#ssec-pkgs-snapTools-build-a-snap-firefox} |
||||
|
||||
Graphical programs require many more integrations with the host. This example uses Firefox as an example, because it is one of the most complicated programs we could package. |
||||
|
||||
```{#ex-snapTools-buildSnap-firefox .nix} |
||||
let |
||||
inherit (import <nixpkgs> { }) snapTools firefox; |
||||
in snapTools.makeSnap { |
||||
meta = { |
||||
name = "nix-example-firefox"; |
||||
summary = firefox.meta.description; |
||||
architectures = [ "amd64" ]; |
||||
apps.nix-example-firefox = { |
||||
command = "${firefox}/bin/firefox"; |
||||
plugs = [ |
||||
"pulseaudio" |
||||
"camera" |
||||
"browser-support" |
||||
"avahi-observe" |
||||
"cups-control" |
||||
"desktop" |
||||
"desktop-legacy" |
||||
"gsettings" |
||||
"home" |
||||
"network" |
||||
"mount-observe" |
||||
"removable-media" |
||||
"x11" |
||||
]; |
||||
}; |
||||
confinement = "strict"; |
||||
}; |
||||
} |
||||
``` |
||||
|
||||
`nix-build` this expression and install it with `snap install ./result --dangerous`. `nix-example-firefox` will now be the Snapcraft version of the Firefox package. |
||||
|
||||
The specific meaning behind plugs can be looked up in the [Snapcraft interface documentation](https://docs.snapcraft.io/supported-interfaces). |
@ -1,59 +0,0 @@ |
||||
<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-snapTools"> |
||||
<title>pkgs.snapTools</title> |
||||
|
||||
<para> |
||||
<varname>pkgs.snapTools</varname> is a set of functions for creating Snapcraft images. Snap and Snapcraft is not used to perform these operations. |
||||
</para> |
||||
|
||||
<section xml:id="ssec-pkgs-snapTools-makeSnap-signature"> |
||||
<title>The makeSnap Function</title> |
||||
|
||||
<para> |
||||
<function>makeSnap</function> takes a single named argument, <parameter>meta</parameter>. This argument mirrors <link xlink:href="https://docs.snapcraft.io/snap-format">the upstream <filename>snap.yaml</filename> format</link> exactly. |
||||
</para> |
||||
|
||||
<para> |
||||
The <parameter>base</parameter> should not be specified, as <function>makeSnap</function> will force set it. |
||||
</para> |
||||
|
||||
<para> |
||||
Currently, <function>makeSnap</function> does not support creating GUI stubs. |
||||
</para> |
||||
</section> |
||||
|
||||
<section xml:id="ssec-pkgs-snapTools-build-a-snap-hello"> |
||||
<title>Build a Hello World Snap</title> |
||||
|
||||
<example xml:id="ex-snapTools-buildSnap-hello"> |
||||
<title>Making a Hello World Snap</title> |
||||
<para> |
||||
The following expression packages GNU Hello as a Snapcraft snap. |
||||
</para> |
||||
<programlisting><xi:include href="./snap/example-hello.nix" parse="text" /></programlisting> |
||||
<para> |
||||
<command>nix-build</command> this expression and install it with <command>snap install ./result --dangerous</command>. <command>hello</command> will now be the Snapcraft version of the package. |
||||
</para> |
||||
</example> |
||||
</section> |
||||
|
||||
<section xml:id="ssec-pkgs-snapTools-build-a-snap-firefox"> |
||||
<title>Build a Hello World Snap</title> |
||||
|
||||
<example xml:id="ex-snapTools-buildSnap-firefox"> |
||||
<title>Making a Graphical Snap</title> |
||||
<para> |
||||
Graphical programs require many more integrations with the host. This example uses Firefox as an example, because it is one of the most complicated programs we could package. |
||||
</para> |
||||
<programlisting><xi:include href="./snap/example-firefox.nix" parse="text" /></programlisting> |
||||
<para> |
||||
<command>nix-build</command> this expression and install it with <command>snap install ./result --dangerous</command>. <command>nix-example-firefox</command> will now be the Snapcraft version of the Firefox package. |
||||
</para> |
||||
<para> |
||||
The specific meaning behind plugs can be looked up in the <link xlink:href="https://docs.snapcraft.io/supported-interfaces">Snapcraft interface documentation</link>. |
||||
</para> |
||||
</example> |
||||
</section> |
||||
</section> |
Loading…
Reference in new issue