README.md

   1 # AppImageKit [![Build Status](https://travis-ci.org/AppImage/AppImageKit.svg?branch=appimagetool/master)](https://travis-ci.org/AppImage/AppImageKit) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/ff60338a447941afb17c30f777314bee)](https://www.codacy.com/app/probonopd/AppImageKit?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=AppImage/AppImageKit&amp;utm_campaign=Badge_Grade) [![discourse](https://img.shields.io/badge/forum-discourse-orange.svg)](http://discourse.appimage.org) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/probonopd/AppImageKit?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![irc](https://img.shields.io/badge/IRC-%23AppImage%20on%20freenode-blue.svg)](https://webchat.freenode.net/?channels=AppImage) [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ZT9CL8M5TJU72)
   2
   3 The __AppImage__ format is a format for packaging applications in a way that allows them to
   4 run on a variety of different target systems (base operating systems, distributions) without further modification.
   5
   6 ![appimagekitr](https://user-images.githubusercontent.com/2480569/34471155-5b53131a-ef41-11e7-90a0-8c57b3c21551.png)
   7
   8 Using AppImageKit you can package desktop applications as AppImages that run on common Linux-based operating systems, such as RHEL, CentOS, Ubuntu, Fedora, Debian and derivatives.
   9
  10 Copyright (c) 2004-18 Simon Peter <probono@puredarwin.org> and contributors.
  11
  12 https://en.wikipedia.org/wiki/AppImage
  13
  14 __AppImageKit__  is  a  concrete  implementation  of  the  AppImage  format  and  provides  tools such as `appimagetool` and `appimaged` for conveniently handling AppImages.
  15
  16 `appimagetool` converts an AppDir into a self-mounting filesystem image. `appimaged` is a daemon that handles registering and unregistering AppImages with the system (e.g., menu entries, icons, MIME types, binary delta updates, and such).
  17
  18 Providing an [AppImage](http://appimage.org/) for distributing application has, among others, these advantages:
  19 - Applications packaged as an AppImage can run on many distributions (including Ubuntu, Fedora, openSUSE, CentOS, elementaryOS, Linux Mint, and others)
  20 - One app = one file = super simple for users: just download one AppImage file, [make it executable](http://discourse.appimage.org/t/how-to-make-an-appimage-executable/80), and run
  21 - No unpacking or installation necessary
  22 - No root needed
  23 - No system libraries changed
  24 - Works out of the box, no installation of runtimes needed
  25 - Optional desktop integration with `appimaged`
  26 - Optional binary delta updates, e.g., for continuous builds (only download the binary diff) using AppImageUpdate
  27 - Can optionally GPG2-sign your AppImages (inside the file)
  28 - Works on Live ISOs
  29 - Can use the same AppImages when dual-booting multiple distributions
  30 - Can be listed in the [AppImageHub](https://appimage.github.io/apps) central directory of available AppImages
  31 - Can double as a self-extracting compressed archive with the `--appimage-extract` parameter
  32
  33 [Here is an overview](https://appimage.github.io/apps) of projects that are already distributing upstream-provided, official AppImages.
  34
  35 If you have questions, AppImage developers are on #AppImage on irc.freenode.net.
  36
  37 ## Motivation
  38
  39 Linus addresses some core issues of Linux on the desktop in his [DebConf 14_ QA with Linus Torvalds talk](https://www.youtube.com/watch?v=5PmHRSeA2c8). At 05:40 Linus highlights application packaging:
  40
  41 > I'm talking about actual application writers that want to make a package of their application for Linux. And I've seen this firsthand with the other project I've been involved with, which is my divelog application.
  42
  43 Obviously Linus is talking about [Subsurface](https://subsurface-divelog.org).
  44
  45 > We make binaries for Windows and OS X.
  46
  47 Both bundle not only the application itself, but also the required Qt libraries that the application needs to run. Also included are dependency libraries like `libssh2.1.dylib`and `libzip.2.dylib`.
  48
  49 > We basically don't make binaries for Linux. Why? Because binaries for Linux desktop applications is a major f*ing pain in the ass. Right. You don't make binaries for Linux. You make binaries for Fedora 19, Fedora 20, maybe there's even like RHEL 5 from ten years ago, you make binaries for debian stable.
  50
  51 So why not use the same approach as on Windows and OS X, namely, treat the base operating system as a _platform_ on top of which we tun the application we care about. This means that we have to bundle the application with all their dependencies that are _not_ part of the base operating system. Welcome [application bundles](https://blogs.gnome.org/tvb/2013/12/10/application-bundles-for-glade/).
  52
  53 > Or actually you don't make binaries for debian stable because debian stable has libraries that are so old that anything that was built in the last century doesn't work. But you might make binaries for debian... whatever the codename is for unstable. And even that is a major pain because (...) debian has those rules that you are supposed to use shared libraries. Right.
  54
  55 This is why binaries going into an AppImage should be built against the oldest still-supported LTS or Enterprise distributions.
  56
  57 > And if you don't use shared libraries, getting your package in, like, is just painful.
  58
  59 "Getting your package in" means that the distribution accepts the package as part of the base operating system. For an application, that might not be desired at all. As long as we can package the application in a way that it seamlessly runs on top of the base operating system.
  60
  61 > But using shared libraries is not an option when the libraries are experimental and the libraries are used by two people and one of them is crazy, so every other day some ABI breaks.
  62
  63 One simple way to achieve this is to bundle private copies of the libraries in question with the application that uses them. Preferably in a way that does not interfere with anything else that is running on the base operating system. Note that this does not have to be true for all libraries; core libraries that are matured, have stable interfaces and can reasonably expected to be present in all distributions do not necessarily have to be bundled with the application.
  64
  65 > So you actually want to just compile one binary and have it work. Preferably forever. And preferably across all Linux distributions.
  66
  67 That is actually possible, as long as you stay away from any distribution-specific packaging, and as long as you do not use a too recent build system. The same will probably be true for Windows and OS X - if you compile on OS X 10.11 then I would not expect the resulting build products to run on OS X 10.5.
  68
  69 > And I actually think distributions have done a horribly, horribly bad job.
  70
  71 Distributions are all about building the base operating system. But I don't think distributions are a good way to get applications. Rather, I would prefer to get the latest versions of applications directly from the people who write them. And this is already a reality for software like Google Chrome, Eclipse, Arduino and other applications. Who uses the (mostly outdated and changed) versions that are part of the distributions? Probably most people don't.
  72
  73 > One of the things that I do on the kernel - and I have to fight this every single release and I think it's sad - we have one rule in the kernel, one rule: we don't break userspace. (...) People break userspace, I get really, really angry. (...)
  74
  75 Excellent. Thank you for this policy! This is why I can still run the Mosaic browser from over a decade ago on modern Linux-based operating systems. (I tried and it works.)
  76
  77 > And then all the distributions come in and they screw it all up. Because they break binary compatibility left and right.
  78
  79 Luckily, binaries built on older distributions tend to still work on newer distributions. At least that has been my experience over the last decade with building application bundles using AppImageKit, and before that, klik.
  80
  81 > They update glibc and everything breaks. (...)
  82
  83 There is a [way around this](https://blogs.gnome.org/tvb/2013/12/14/application-bundles-revisited/), although not many people actually care to use the workaround (yet).
  84
  85 > So that's my rant. And that's what I really fundamentally think needs to change for Linux to work on the desktop because you can't have applications writers to do fifteen billion different versions.
  86
  87 AppImage to the rescue!
  88
  89 ## AppImage usage
  90
  91 Running an AppImage mounts the filesystem image and transparently runs the contained application. So the usage of an AppImage normally should equal the usage of the application contained in it. However, there is special functionality, as described here. If an AppImage you have received does not support these options, ask the author of the AppImage to recreate it using the latest `appimagetool` (or `linuxdeployqt`).
  92
  93 ### Command line arguments
  94
  95 If you invoke an AppImage built with a recent version of AppImageKit with one of these special command line arguments, then the AppImage will behave differently:
  96
  97 - `--appimage-help` prints the help options
  98 - `--appimage-offset` prints the offset at which the embedded filesystem image starts, and then exits. This is useful in case you would like to loop-mount the filesystem image using the `mount -o loop,offset=...` command
  99 - `--appimage-extract` extracts the contents from the embedded filesystem image, then exits. This is useful if you are using an AppImage on a system on which FUSE is not available
 100 - `--appimage-mount` mounts the embedded filesystem image and prints the mount point, then waits until it is killed. This is useful if you would like to inspect the contents of an AppImage without executing the contained payload application
 101 - `--appimage-version` prints the version of AppImageKit, then exits. This is useful if you would like to file issues
 102 - `--appimage-updateinformation` prints the update information embedded into the AppImage, then exits. This is useful for debugging binary delta updates
 103 - `--appimage-signature` prints the digital signature embedded into the AppImage, then exits. This is useful for debugging binary delta updates. If you would like to validate the embedded signature, you should use the `validate` command line tool that is part of AppImageKit
 104
 105 ### Special directories
 106
 107 Normally the application contained inside an AppImage will store its configuration files wherever it normally stores them (most frequently somewhere inside `$HOME`). If you invoke an AppImage built with a recent version of AppImageKit and have one of these special directories in place, then the configuration files will be stored alongside the AppImage. This can be useful for portable use cases, e.g., carrying an AppImage on a USB stick, along with its data.
 108
 109 - If there is a directory with the same name as the AppImage plus `.home`, then `$HOME` will automatically be set to it before executing the payload application
 110 - If there is a directory with the same name as the AppImage plus `.config`, then `$XDG_CONFIG_HOME` will automatically be set to it before executing the payload application
 111
 112 ## appimagetool usage
 113
 114 `appimagetool` is used to generate an AppImage from an existing `AppDir`. Higher-level tools such as [`linuxdeployqt`](https://github.com/probonopd/linuxdeployqt) use it internally. A precompiled version can be found on [GitHub Releases](https://github.com/AppImage/AppImageKit/releases).
 115
 116 ```
 117 wget "https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage"
 118 chmod a+x appimagetool-x86_64.AppImage
 119 ```
 120
 121 Usage in a nutshell, assuming that you already have an [AppDir](https://github.com/AppImage/AppImageSpec/blob/master/draft.md#appdir) in place:
 122
 123 ```
 124 ./appimagetool-x86_64.AppImage some.AppDir
 125 ```
 126
 127 Detailed usage:
 128 ```
 129 Usage:
 130   appimagetool [OPTION...] SOURCE [DESTINATION] - Generate, extract, and inspect AppImages
 131
 132 Help Options:
 133   -h, --help                  Show help options
 134
 135 Application Options:
 136   -l, --list                  List files in SOURCE AppImage
 137   -u, --updateinformation     Embed update information STRING; if zsyncmake is installed, generate zsync file
 138   --bintray-user              Bintray user name
 139   --bintray-repo              Bintray repository
 140   --version                   Show version number
 141   -v, --verbose               Produce verbose output
 142   -s, --sign                  Sign with gpg2
 143   -n, --no-appstream          Do not check AppStream metadata
 144 ```
 145
 146 If you want to generate an AppImage manually, you can:
 147
 148 ```
 149 mksquashfs Your.AppDir Your.squashfs -root-owned -noappend
 150 cat runtime >> Your.AppImage
 151 cat Your.squashfs >> Your.AppImage
 152 chmod a+x Your.AppImage
 153 ```
 154
 155 ## appimaged usage
 156
 157 `appimaged` is an optional daemon that watches locations like `~/bin` and `~/Downloads` for AppImages and if it detects some, registers them with the system, so that they show up in the menu, have their icons show up, MIME types associated, etc. It also unregisters AppImages again from the system if they are deleted. If [firejail](https://github.com/netblue30/firejail) is installed, it runs the AppImages with it.
 158
 159 A precompiled version can be found in the last successful Travis CI build, you can get it with:
 160
 161 ```
 162 wget "https://github.com/AppImage/AppImageKit/releases/download/continuous/appimaged-x86_64.AppImage"
 163 chmod a+x appimaged-x86_64.AppImage
 164 ```
 165
 166 Usage in a nutshell:
 167
 168 ```
 169 ./appimaged-x86_64.AppImage --install
 170 ```
 171
 172 Or, if you are on a deb-based system:
 173
 174 ```
 175 wget -c "https://github.com/AppImage/AppImageKit/releases/download/continuous/appimaged_1.0_amd64.deb"
 176 sudo dpkg -i appimaged_*.deb
 177 systemctl --user add-wants default.target appimaged
 178 systemctl --user start appimaged
 179 ```
 180
 181 It will register the AppImages in with your system from the following places:
 182 * $HOME/Downloads (or its localized equivalent, as determined by `G_USER_DIRECTORY_DOWNLOAD` in glib)
 183 * $HOME/.local/bin
 184 * $HOME/bin
 185 * $HOME/Applications
 186 * /Applications
 187 * /isodevice/Applications
 188 * /isofrom/Applications
 189 * /run/archiso/img_dev/Applications
 190 * /lib/live/mount/findiso/Applications
 191 * /opt
 192 * /usr/local/bin
 193
 194 Run `appimaged -v` for increased verbosity.
 195
 196 Detailed usage:
 197 ```
 198 Usage:
 199   appimaged [OPTION...]
 200
 201 Help Options:
 202   -h, --help          Show help options
 203
 204 Application Options:
 205   -v, --verbose       Be verbose
 206   -i, --install       Install this appimaged instance to $HOME
 207   -u, --uninstall     Uninstall an appimaged instance from $HOME
 208   --version           Show version number
 209
 210 ```
 211
 212 __NOTE:__ It may be necessary to restart (or `xkill`) dash, nautilus, to recognize new directories that didn't exist prior to the first run of `appimaged`. Alternatively, it should be sufficient to log out of the session and log in again after having run appimaged once.
 213
 214 If you have `AppImageUpdate` on your `$PATH`, then it can also do this neat trick:
 215
 216 ![screenshot from 2016-10-15 16-37-05](https://cloud.githubusercontent.com/assets/2480569/19410850/0390fe9c-92f6-11e6-9882-3ca6d360a190.jpg)
 217
 218 Download AppImageUpdate from https://github.com/AppImage/AppImageUpdate/releases/tag/continuous and put on your `$PATH`:
 219
 220 ```
 221 sudo mv "Downloads/AppImageUpdate-*.AppImage" /usr/local/bin/AppImageUpdate
 222 chmod a+x /usr/local/bin/AppImageUpdate
 223 ```
 224
 225 ## Building
 226
 227 __NOTE:__ The AppImage project supplies [binaries](https://github.com/AppImage/AppImageKit/releases/tag/continuous) that application developers can use. These binaries are built using the CentOS 6 Docker on Travis CI build system in this repository. As an application developer, you do not have to use the build system. You only have to use the build systems when contributing to AppImageKit, when needing another architecture than `x86_64`, or when trying to reproduce our binaries.
 228
 229 On the oldest still-supported Ubuntu LTS release (at this point, 14.04):
 230
 231 ```
 232 git clone -b appimagetool/master --single-branch --recursive https://github.com/AppImage/AppImageKit
 233 cd AppImageKit/
 234 sudo bash -ex install-build-deps.sh
 235 bash -ex build.sh
 236 ```