Autopackage Packagers Guide

Autopackage abstracts interfaces behind interface version numbers. These take the form of two integers written as A.B, and they work similar to the libtool versions many of us are used to. The A number is the major number and is incremented when a breaking change is made to an interface (a function is removed, renamed etc). When A is incremented, B is set back to zero. B is the minor number and is incremented when an interface is added. This is in contrast to the software version , which is pretty much freeform and is usually set to the version number chosen by the software authors.

The mapping from the state of the system to an interface version (or set of interface versions) is determined by the skeleton file which encapsulates that dependency. Skeleton files contain a small amount of metadata about a dependency, and they are used by packages to make dependency detection and resolution automatic. Typically for each dependency a package has, there must be a corresponding skeleton file - if one doesn't exist, it should be created and then let the maintainers of the software it represents know of its existence. Don't worry though, creating skeleton files is very easy.

Autopackage comes with a collection of useful skeleton files for common dependencies that can be used immediately in your own packages. If a skeleton is created, please forward the skeleton to us so that it can be in the next release.

Autopackage is designed to be a decentralized system. For this reason, it leverages off of the DNS network to uniquely identify things. The basic unit of currency is called a root name , and looks a bit like this: @foobar.org/frob:2000:3 . Root names have several components:

Packages (but not skeletons) can optionally have a short name . Short names are more convenient to use than root names, and are more familiar to Linux users. They look like "frozen-bubble", "libxml" or "gnome-panel". Typically, these are the names users will use from the command line. Try and keep them unique if possible, but it's not a disaster if there are conflicts.

Finally, packages and skeletons should be given a display name . This is a human readable string, that can be optionally localized. It will be used in user interfaces where possible, and should take the form of "Product-Name Purpose", for instance "Sound Juicer CD Ripper", "Mozilla Web Browser", or "GNU Emacs Text Editor".

This is a specfile for the GnuTLS library. It's fairly typical. Examine it for a while, it is straight forward to understand.

                    
[Meta]
RootName: @gnutls.org/gnutls:$SOFTWAREVERSION
ShortName: gnutls
SoftwareVersion: @VERSION@
DisplayName: GNU Transport Layer Security
Summary: Provides support for the TLS/SSL protocols
Maintainer: Nikos Mavroyanopoulos <nmav@hellug.gr>
Packager: Mike Hearn <mike@theoretic.com>
InterfaceVersion: 10.3
Language: de es fr
DisplayName[de]: Gnu Transport-Schicht-Sicherheit
Summary[de]: Gibt Unterstützung für die TLS/SSL Protokolle.
DisplayName[es]: Seguridad De la Capa De Transporte del Gnu
Summary[es]: Proporciona la ayuda para los protocolos de TLS/SSL.
DisplayName[fr]: Gnu Transport-Schicht-Sicherheit
Summary[fr]: Fournit l'appui pour les protocoles de TLS/SSL.

[Description]
This is a TLS (Transport Layer Security) 1.0 and SSL (Secure Sockets Layer) 3.0
implementation for the GNU project.

[BuildPrepare]
prepareBuild --with-included-libtasn1 --disable-openpgp-authentication

[BuildUnprepare]
unprepareBuild

[Globals]
export sover="10.3.8"

[Imports]
import <<EOF
lib/libgnutls.so.$sover
lib/libgnutls-extra.so.$sover
EOF

[Prepare]
require @gnupg.org/libgcrypt 7.1
require @gnupg.org/libgpg-error 0.0

[Install]
installLib libgnutls.so.$sover libgnutls-extra.so.$sover

[Uninstall]
uninstallFromLog

This section consists of a number of keys, of the form "Key: Value". Most of these should be obvious from the discussion of basic concepts - this is where short name , software version , interface version (optional), display name and so on are defined. Translated versions can be provided of DisplayName and Summary by appending [langcode] to the key names. The 'Scripting Key' variables are in addition to the common variables listed in the scripting variables section.

Some variables can be used as values of these keys. The $SOFTWAREVERSION is embedded into the root name - recall that root names can have the software version as a component.

This section should contain an English description of the package (in non technical terms please if at all possible). Non-English versions should go into the Description:xx sections, where xx is the language code. A good description will provide a brief overview of the purpose of the software and it's capabilities.

This section contains a bash script that will be used to prepare (build/compile) the sources for import. Import is the process whereby the files are selected and placed into the package archive. Preparation gives the chance to do things like run configure scripts, Makefiles and other such things if the project requires them.

If your project is using GNU autoconf/automake, calling prepareBuild() function will usually do the trick nicely. It simply reconfigures the tree to a temporary prefix, then does the make, make install cycle. Please note that your software must be relocatable; refer to paragraph 3 for more information.

This section is optional but recommended. A warning will be displayed if it is missed.

This section is run after Imports and allows for any tidying up. This section is optional. Use the unprepareBuild() function to reset the source tree back to its original configuration, assuming prepareBuild() was used.

This script is used to select files that you want to put inside the package. You use the import command to import files in your package.

The import command is invoked like this:

echo (filenames...) | import

import reads filenames from STDIN. Each file must be seperated by a newline. The command also accepts wildcards, so you can also type:

echo '*' | import

The current working directory is the build root directory ( $build_root ). If you used prepareBuild , then all built files are automatically installed to this build root (by using 'make install'), so the only thing you have to do is to call echo '*' | import .

If you're not using prepareBuild , then there are two things you can do:

The prep script is the first part of any package. It is responsible for "preparing" the package, which basically means ensuring all the dependencies are present, making any decisions about what to install or not install, and so on. No installation of any files occur here.

Dependencies are best handled with the require function, although they don't have to be if your needs are quite specialist:

require @gnome.org/libxml 2.0

In this case, that's all we have to do. The correct skeleton file will automatically be selected and copied into the package by the makepackage script. Later, when this line of script is run, the require function will run the script associated with the skeleton file and handle the error if the dependency fails. If the check passes, the script will continue.

There are several different ways of expressing dependencies. Require is the most common but there is also recommend . Recommending a dependency means autopackage will check for it, and try to install it if it's missing, but if it can't this will not cause the function to fail. Instead, the dependency will be listed in the summary screen to inform the users that if they had this library, new functionality would be available. An easy way to make something recommended rather than required is to use dlopen, and an easy way to use dlopen is to use relaytool.

You can also use the requireAtLeast and requireExact functions if you rely on implementation details of a dependency (for instance, maybe you need a bugfix). These only work if SOFTWARE_VERSIONS is set though, and not all skeletons set this. So check before using them. Both of these functions have recommend equivalents.

The install section is the meat of your package. It consists of a series of calls to the autopackage API, in order to affect the users system in some fashion.

In theory you can do anything you like in these scripts, including using regular shell commands like "cp" or "mv". In practice, where autopackage provides a replacement command, you should use that. For instance, use copyFiles instead of cp. The builtin versions have advantages over the raw shell commands, for instance using copyFiles will register the files in the log so they will be automatically uninstalled, and they will appear in the file list. Whilst copyFiles and copyFile are very generic, for some types of file there are more specific functions available. Here is a short list:

In the install section, like in the Prepare section, any command that fails will abort the install. That doesn't apply inside if statements of course.

This is usually easy - just a call to uninstallFromLog will suffice, as this runs the uninstall script that was generated automatically by the installer functions, and will automatically remove any files copied/any directories created etc. If any actions was done without using the autopackage APIs, now is a good time to undo them. Remember - forgive the user . They may well have screwed around with the install, so if custom actions are included, check that they make sense (IE the file exists before trying to delete it).

The following is an alphabetical list of variables that are available for all scripting use. The variables are in addition to the 'Scripting Key' variables listed with the Standard Meta keys.