README.md

   1 AppImageKit [![Build Status](https://travis-ci.org/probonopd/AppImageKit.svg?branch=master)](https://travis-ci.org/probonopd/AppImageKit)
   2 ===========
   3
   4 ![screenshot](https://cloud.githubusercontent.com/assets/2480569/3711041/71fdb282-14bb-11e4-9b3e-19d8c603a4fe.png)
   5
   6 Copyright (c) 2004-15 Simon Peter <probono@puredarwin.org>
   7 All rights reserved.
   8 Redistribution of this document is permitted only in unchanged form.
   9 Version 2015-01-18
  10
  11 Building
  12 --------
  13
  14 Use an old system for building (at least 2-3 years old) to ensure the binaries run on older systems too.
  15
  16 ```bash
  17 sudo apt-get update ; sudo apt-get -y install libfuse-dev libglib2.0-dev cmake git libc6-dev binutils fuse # debian, Ubuntu
  18 yum install git cmake binutils fuse glibc-devel glib2-devel fuse-devel gcc zlib-devel libpng12 # Fedora, RHEL, CentOS
  19 git clone https://github.com/probonopd/AppImageKit.git
  20 cd AppImageKit
  21 cmake .
  22 make
  23 ```
  24
  25 Once you have built AppImageKit, try making an AppImage, e.g., of Leafpad:
  26
  27     export APP=leafpad && ./apt-appdir/apt-appdir $APP && ./AppImageAssistant $APP.AppDir $APP.AppImage && ./$APP.AppImage
  28
  29 (This is just a proof-of-concept, of in reality you should use AppDirAssistant to create proper AppDirs)
  30
  31 TODO
  32 ----
  33
  34 * Include AppDirAssistant tool
  35 * Update http://www.portablelinuxapps.org/docs/1.0/ to remove all references to elficon; include changelog section
  36
  37 Changelog
  38 ---------
  39
  40 -11
  41 * Builds on x86-64
  42 * Follow http://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html (Version 0.8.0 introduced new location for the thumbnails)
  43 * Remove elficon as no one uses it; use thumbnails instead
  44 * Include AppImageExtract tool
  45 * Update AppImageAssistant.AppDir so that it runs on latest Ubuntu
  46 * Use AppDir suffix
  47 * Factor out dependency binaries to be bundled into ./bundled-dependencies-i386
  48
  49 -9
  50 * Runtime extracts .DirIcon to $HOME/.thumbnails/normal/
  51 * When called with "--icon", only extracts the icon, prints a message and exits
  52 * Runtime sets environment variables APPIMAGE, APPDIR that the "inside" app may use
  53 * AppRun appends to environment variables XDG_DATA_DIRS, QT_PLUGIN_PATH, PERLLIB
  54
  55 AppImage format definition
  56 --------------------------
  57
  58 The AppImage format has the following properties:
  59 * The AppImage is an ISO9660 file
  60 * The contents of the ISO9660 file can be compressed with zf
  61 * In the first 32k of the ISO9660 file, an ELF executable is embedded
  62   which mounts the AppImage, executes the application from the
  63   mounted AppImage, and afterwards unmounts the AppImage again
  64 * The ISO9660 file contains an AppDir as per the ROX AppDir specification
  65 * The AppDir contains one desktop file as per the freedesktop.org specification
  66
  67 ```
  68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  69 +                                                                                  +
  70 +   ISO9660                                                                        +
  71 +                                                                                  +
  72 +   ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++   +
  73 +   +                              +                                           +   +
  74 +   +                              +                AppDir                     +   +
  75 +   +                              +                 |_ .DirIcon               +   +
  76 +   +                              +                 |_ appname.desktop        +   +
  77 +   +             ELF              +                 |_ AppRun                 +   +
  78 +   +                              +             (   |_ usr/                   +   +
  79 +   +                              +                     |_ bin/               +   +
  80 +   +                              +                     |_ lib/               +   +
  81 +   +                              +                     |_ share/  )          +   +
  82 +   +                              +                                           +   +
  83 +   ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++   +
  84 +                                                                                  +
  85 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  86 ```
  87
  88 Creating portable AppImages
  89 ===========================
  90
  91 For an AppImage to run on most systems, the following conditions need to be met:
  92 1. The AppImage needs to include all libraries and other dependencies that are not part of all of the base systems that the AppImage is intended to run on
  93 2. The binaries contained in the AppImage need to be compiled on a system not newer than the oldest base system that the AppImage is intended to run on
  94 3. The AppImage should actually be tested on the base systems that it is intended to run on
  95
  96 Libraries and other dependencies
  97 --------------------------------
  98
  99 Binaries compiled on old enough base system
 100 --------------------------------------------
 101
 102 The ingredients used in your AppImage should not be built on a more recent base system than the oldest base system your AppImage is intended to run on. Some core libaries, such as glibc, tend to break compatibility with older base systems quite frequently, which means that binaries will run on newer, but not on older base systems than the one the binaries were compiled on.
 103
 104 If you run into errors like this
 105
 106     failed to initialize: /lib/tls/i686/cmov/libc.so.6: version `GLIBC_2.11' not found
 107
 108 then the binary is compiled on a newer system than the one you are trying to run it on. You should use a binary that has been compiled on an older system. Unfortunately, the complication is that distributions usually compile the latest versions of applications only on the latest systems, which means that you will have a hard time finding binaries of bleeding-edge softwares that run on older systems.
 109
 110 Testing
 111 -------
 112
 113 To ensure that the AppImage runs on the intended base systems, it should be thoroughly tested on each of them. The following testing procedure is both efficient and effective: Get the previous version of Ubuntu, Fedora, and openSUSE Live CDs and test your AppImage there. Using the three largest distributions increases the chances that your AppImage will run on other distributions as well. Using the previous (current minus one) version ensures that your end users who might not have upgraded to the latest version yet can still run your AppImage. Using Live CDs has the advantage that unlike installed systems, you always have a system that is in a factory-fresh condition that can be easily reproduced. Most developers just test their software on their main working systems, which tend to be heavily customized through the installation of additional packages. By testing on Live CDs, you can be sure that end users will get the best experience possible.
 114
 115 I use ISOs of Live CDs, loop-mount them, chroot into them, and run the AppImage there. This way, I need approximately 700 MB per supported base system (distribution) and can easily upgrade to never versions by just exchanging one ISO file. The following script automates this for Ubuntu-like (Casper-based) and Fedora-like (Dract-based) Live ISOs:
 116
 117     sudo ./AppImageAssistant.AppDir/testappimage /path/to/elementary-0.2-20110926.iso ./AppImageAssistant.AppImage
 118
 119 Support
 120 -------
 121
 122 I support open source projects that wish to distribute their software as an AppImage. For closed source applications, I offer AppImage packaging and testing as a service.