===== IPK 1.1 Specification =====

FIXME This specifications are @work! Some information might change due the development process
or might just be outdated and wrong.

==== General ====

=== Format ===

An IPK setup-package is a [[http://en.wikipedia.org/wiki/Tar_%28file_format%29 | TAR-Archive]],
containing a [[http://en.wikipedia.org/wiki/Xz | XZ-Compressed]] data and control tarball.
An IPK-Package has the file extension .ipk (= **I**nstallation **p**ac**k**age), which was choosen because it is
simple and easy to remember. Unfortunately the Opkg and Ipkg package manager for Linux cellphones uses the same extension,
(and IPK was an image-format for Nintendo® games), but because Listaller setups are targeted to Linux desktops and not to
cellphones, this should not leat to much confusion.
Most of the IPK packages are named in the following pattern: InstallAppname-version_architecture.ipk
E.g if the name of the application is "//Sample//" the version is "//1.0//" and the architecture is "//i386//" the package should
be named //InstallSample-10_i386.ipk// or //Sample-10_i386.ipk//

=== Structure ===

The IPK archive contains the following files and folders at toplevel:

^ Name                ^ Required? ^ Function                                                    ^
| data.tar.xz         | yes       | Contains the files which have to be installed.              |
| control.tar.xz      | yes       | Archive with configuration files of this package, the main config file as well as e.g. Licenses, scripts, descriptions, file-info etc. |
| _signature          | no        | A GPG ASC signature of this package. (Only exists if the package is signed)   |


Listaller will detect automatically if a package is signed and check if the signature on the IPK package is valid.

==== The control files ====

All files configuring the behavior of an IPK package or providing additional information about it are stored
in the //control.tar.xz// archive.

On toplevel, each control archive has to contain an //arcinfo.pin// document, describing all basic stuff of the package.

=== Arcinfo.pin ===

The //arcinfo.pin// file contains the same information as the definition part in an IPS-script.
The package builder has changed file paths and removed some unnecessary elements, everything else is the same.
An //arcinfo.pin// file may look like this:
<code ips>
IPK-Standard-Version: 1.0
 
include:"/stuff/locale/setup-es.mo"
 
Type: linstall 
Name: Foobar
Version: 1.0-a
License: include:"/stuff/COPYING"
Description: include:"/stuff/desc.txt"
Icon: /stuff/foobar-icon.png
SDesc: A new foo-ish bar
SDesc[de]: Einen neue foo-bar
Group: Development
Author: Foobar Project
Vendor: Foobar Publishing
Maintainer: Pete Foo (petefoo@example.org)
Disallow: ioNothing
Profile[0]: Standard
AppCMD: $INST/foo/foobar
Architecture: i386
DSupport: Ubuntu,openSUSE
Dependencies:
 $LIB/libc6.so
 $LIB/library2.so
 $LIB/libnagra.so.4
</code>
The format of an IPS definition section is described in the IPS specifications.
The following elements are IPK-specific or have different values:

  * License, Description, Wizimage, Icon: The value has changed, it points now to a file in the IPK package. / is the package root. Licenses are usually saved in /stuff
  * Include commands have also changed values.
  * The !-Files part is missing.

=== File information ===

The information about installed files is saved in a plain text file named //fileinfo.id// which
is stored in the //control// archive. The content of the fileinfo file has the following structure:
<code ips>
>Destination_dir
Internal path to file
MD5-hash
Internal path to file
MD5-hash
...
</code>
A fileinfo-file can look like this: (extract)
<code ips>
>$INST/Songbird
/data/Songbird/LICENSE.html
9b5151a0cfec60dbc0c3d548cfa3e713
/data/Songbird/README.txt
a92100275b9f71115dbe82a18af61392
/data/Songbird/TRADEMARK.txt
c82c36a2843c9ad08c42d7170a9c12d1
/data/Songbird/songbird
77e7be1db488bf3c4b5e8abd52d6eb23
/data/Songbird/application.ini
ff85febb38852501439ea623725241c0
>$INST/Songbird/jsmodules
/data/Songbird/jsmodules/sbLibraryUtils.jsm
418a7400354cd1176264b5ec79f29be2
</code>
The variables (indicated by the //$// sign) are resolved to absolute paths
following the [[Global Variables | Variable Definitions]].

==== Data archive ====

The data archive //data.tar.xz// contains all data a package wants to install. The directories in which
files have to be installed are defined by the //fileinfo.id// file in the control archive.
Usually, the data is stored in a structure somehow matching the destination of the new files.
E.g. if files go to //$INST/App/test//, they are located in the ///INST/App/test// directory of the
data archive. The structure of files can be freely defined, it is only controlled by the //fileinfo.id//
file. The structure mentioned above is recommended, but it is not forced. The IPK package builder of Listaller,
**libuild** will create IPK packages matching this structure.

TODO: Add information how multiarch-IPKs are structured & handled.
