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 Copyright (c) 2004-17 Simon Peter <probono@puredarwin.org> and contributors.
   4
   5 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.
   6
   7 The __AppImage__ format is a format for packaging applications in a way that allows them to
   8 run on a variety of different target systems (base operating systems, distributions) without further modification.
   9
  10 https://en.wikipedia.org/wiki/AppImage
  11
  12 __AppImageKit__  is  a  concrete  implementation  of  the  AppImage  format  and  provides  tools such as `appimagetool` and `appimaged` for conveniently handling AppImages.
  13
  14 `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).
  15
  16 ## appimagetool usage
  17
  18 A precompiled version can be found in the last successful Travis CI build, you can get it with:
  19
  20 ```
  21 wget "https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage"
  22 chmod a+x appimagetool-x86_64.AppImage
  23 ```
  24 Usage in a nutshell, assuming that you already have an [AppDir](https://github.com/AppImage/AppImageSpec/blob/master/draft.md#appdir) in place:
  25 ```
  26 ./appimagetool-x86_64.AppImage some.AppDir
  27 ```
  28
  29 Detailed usage:
  30 ```
  31 Usage:
  32   appimagetool [OPTION...] SOURCE [DESTINATION] - Generate, extract, and inspect AppImages
  33
  34 Help Options:
  35   -h, --help                  Show help options
  36
  37 Application Options:
  38   -l, --list                  List files in SOURCE AppImage
  39   -u, --updateinformation     Embed update information STRING; if zsyncmake is installed, generate zsync file
  40   --bintray-user              Bintray user name
  41   --bintray-repo              Bintray repository
  42   --version                   Show version number
  43   -v, --verbose               Produce verbose output
  44   -s, --sign                  Sign with gpg2
  45   -n, --no-appstream          Do not check AppStream metadata
  46 ```
  47
  48 If you want to generate an AppImage manually, you can:
  49
  50 ```
  51 mksquashfs Your.AppDir Your.squashfs -root-owned -noappend
  52 cat runtime >> Your.AppImage
  53 cat Your.squashfs >> Your.AppImage
  54 chmod a+x Your.AppImage
  55 ```
  56
  57 ## AppImage usage
  58
  59 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.
  60
  61 ### Command line arguments
  62
  63 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:
  64
  65 - `--appimage-help` prints the help options
  66 - `--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
  67 - `--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
  68 - `--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
  69 - `--appimage-version` prints the version of AppImageKit, then exits. This is useful if you would like to file issues
  70 - `--appimage-updateinformation` prints the update information embedded into the AppImage, then exits. This is useful for debugging binary delta updates
  71 - `--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
  72
  73 ### Special directories
  74
  75 Normally the application contained inside an AppImage will store its configuration files whereever 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.
  76
  77 - If there is a directory with the same name as the AppImage plus `.home`, then export `$HOME`.
  78 - If there is a directory with the same name as the AppImage plus `.config`, then export `$XDG_CONFIG_HOME`.
  79
  80 ## appimaged usage
  81
  82 `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.
  83
  84 A precompiled version can be found in the last successful Travis CI build, you can get it with:
  85
  86 ```
  87 wget "https://github.com/AppImage/AppImageKit/releases/download/continuous/appimaged-x86_64.AppImage"
  88 chmod a+x appimaged-x86_64.AppImage
  89 ```
  90
  91 Usage in a nutshell:
  92
  93 ```
  94 ./appimaged-x86_64.AppImage --install
  95 ```
  96
  97 Or, if you are on a deb-based system:
  98
  99 ```
 100 wget -c "https://github.com/AppImage/AppImageKit/releases/download/continuous/appimaged_1.0_amd64.deb"
 101 sudo dpkg -i appimaged_*.deb
 102 systemctl --user enable appimaged
 103 systemctl --user start appimaged
 104 ```
 105
 106 It will register the AppImages in with your system from the following places:
 107 * $HOME/Downloads
 108 * $HOME/.local/bin
 109 * $HOME/bin
 110 * /Applications
 111 * /isodevice/Applications
 112 * /isofrom/Applications
 113 * /run/archiso/img_dev/Applications
 114 * /opt
 115 * /usr/local/bin
 116
 117 Run `appimaged -v` for increased verbosity.
 118
 119 Detailed usage:
 120 ```
 121 Usage:
 122   appimaged [OPTION...]
 123
 124 Help Options:
 125   -h, --help          Show help options
 126
 127 Application Options:
 128   -v, --verbose       Be verbose
 129   -i, --install       Install this appimaged instance to $HOME
 130   -u, --uninstall     Uninstall an appimaged instance from $HOME
 131   --version           Show version number
 132
 133 ```
 134
 135 __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.
 136
 137 If you have `AppImageUpdate` on your `$PATH`, then it can also do this neat trick:
 138
 139 ![screenshot from 2016-10-15 16-37-05](https://cloud.githubusercontent.com/assets/2480569/19410850/0390fe9c-92f6-11e6-9882-3ca6d360a190.jpg)
 140
 141 Here is an easy way to get the latest AppImageUpdate onto your `$PATH`:
 142
 143 ```
 144 APP=AppImageUpdate
 145 nodeFileName=$(wget -q "https://bintray.com/package/files/probono/AppImages/$APP?order=desc&sort=fileLastModified&basePath=&tab=files" -O - | grep -e '-x86_64.AppImage">' | cut -d '"' -f 6 | head -n 1)
 146 wget -c "https://bintray.com/$nodeFileName" -O "$APP"
 147 chmod a+x "$APP"
 148 sudo mv "$APP" /usr/local/bin/
 149 ```
 150
 151 ## Building
 152
 153 __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.
 154
 155 On a not too recent Ubuntu:
 156
 157 ```
 158 git clone -b appimagetool/master --single-branch --recursive https://github.com/AppImage/AppImageKit
 159 cd AppImageKit/
 160 sudo bash -ex install-build-deps.sh
 161 bash -ex build.sh
 162 ```