From 228276fbd0174eb60199b795c369f4363acd6713 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Thu, 22 Apr 2021 23:56:11 +0800 Subject: doc/builders/images/*.xml: Convert to markdown --- doc/builders/images.xml | 4 +- doc/builders/images/appimagetools.section.md | 48 +++++++++++++ doc/builders/images/appimagetools.xml | 102 --------------------------- doc/builders/images/snap/example-firefox.nix | 28 -------- doc/builders/images/snap/example-hello.nix | 12 ---- doc/builders/images/snaptools.section.md | 71 +++++++++++++++++++ doc/builders/images/snaptools.xml | 59 ---------------- 7 files changed, 121 insertions(+), 203 deletions(-) create mode 100644 doc/builders/images/appimagetools.section.md delete mode 100644 doc/builders/images/appimagetools.xml delete mode 100644 doc/builders/images/snap/example-firefox.nix delete mode 100644 doc/builders/images/snap/example-hello.nix create mode 100644 doc/builders/images/snaptools.section.md delete mode 100644 doc/builders/images/snaptools.xml (limited to 'doc') diff --git a/doc/builders/images.xml b/doc/builders/images.xml index d7d250291893a..cd10d69a96dde 100644 --- a/doc/builders/images.xml +++ b/doc/builders/images.xml @@ -5,8 +5,8 @@ This chapter describes tools for creating various types of images. - + - + diff --git a/doc/builders/images/appimagetools.section.md b/doc/builders/images/appimagetools.section.md new file mode 100644 index 0000000000000..7ab4e4e9d855f --- /dev/null +++ b/doc/builders/images/appimagetools.section.md @@ -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. diff --git a/doc/builders/images/appimagetools.xml b/doc/builders/images/appimagetools.xml deleted file mode 100644 index 45c5619abd97d..0000000000000 --- a/doc/builders/images/appimagetools.xml +++ /dev/null @@ -1,102 +0,0 @@ -
- pkgs.appimageTools - - - pkgs.appimageTools is a set of functions for extracting and wrapping AppImage 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. - - - - - The appimageTools API is unstable and may be subject to backwards-incompatible changes in the future. - - - -
- AppImage formats - - - There are different formats for AppImages, see the specification 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: - - - -$ 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 - - - Depending on the type of AppImage you're wrapping, you'll have to use wrapType1 or wrapType2. - - - -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. - - - - - - -
-
diff --git a/doc/builders/images/snap/example-firefox.nix b/doc/builders/images/snap/example-firefox.nix deleted file mode 100644 index d58c98a65a2e7..0000000000000 --- a/doc/builders/images/snap/example-firefox.nix +++ /dev/null @@ -1,28 +0,0 @@ -let - inherit (import { }) 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"; - }; -} diff --git a/doc/builders/images/snap/example-hello.nix b/doc/builders/images/snap/example-hello.nix deleted file mode 100644 index 123da80c54775..0000000000000 --- a/doc/builders/images/snap/example-hello.nix +++ /dev/null @@ -1,12 +0,0 @@ -let - inherit (import { }) 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"; - }; -} diff --git a/doc/builders/images/snaptools.section.md b/doc/builders/images/snaptools.section.md new file mode 100644 index 0000000000000..9e1403b88285a --- /dev/null +++ b/doc/builders/images/snaptools.section.md @@ -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 { }) 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 { }) 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). diff --git a/doc/builders/images/snaptools.xml b/doc/builders/images/snaptools.xml deleted file mode 100644 index bbe2e3f5e14c5..0000000000000 --- a/doc/builders/images/snaptools.xml +++ /dev/null @@ -1,59 +0,0 @@ -
- 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 - - - makeSnap takes a single named argument, meta. This argument mirrors the upstream snap.yaml 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 - - - Making a Hello World Snap - - The following expression packages GNU Hello as a Snapcraft snap. - - - - nix-build this expression and install it with snap install ./result --dangerous. hello will now be the Snapcraft version of the package. - - -
- -
- Build a Hello World Snap - - - Making a Graphical Snap - - 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. - - - - 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. - - -
-
-- cgit 1.4.1