The specfile format

Spec files resemble the Windows INI file format of yore, now used also in .desktop files. Typically each section is denoted with a header that looks like this: [Section-Name] . Specfiles usually have a .apspec extension, and are placed in a subdirectory of the projects source tree called autopackage . This directory contains one spec file for each package, in contrast to RPM which allows creation of multiple packages from the same spec. By convention, the primary package has a filename of default.apspec , and the makeinstaller program will use this if no specfile is specified. Use the autopackage directory to store other useful things, for instance patches.

Warning

Applying patches to the source tree is an indication that something is wrong. Typically the person who should be making an autopackage should be the maintainer of the software themselves, so external patches are not relevant. This is the best arrangement because that way users are guaranteed that source code releases are accompanied by binary releases - there is no need for them to hang around waiting for somebody to rebuild the package for them.

Note

If using GNU autoconf, then call the specfile something.apspec.in and makeinstaller will automatically run config.status to update the real specfile.

A quick example

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

Meta

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 nameand 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.

Table 2.1. Standard Meta Keys

Meta Key Scripting Key Description Value Type REQ? Example
AutopackageTarget $AUTOPACKAGETARGET

Minimum targetted API version of autopackage for which the generated package requires.

numeric Yes 1.0
CPUArchitectures $CPUARCHITECTURES

The CPU architectures to be generated from the source.

string Yes x86
DisplayName[xx] $DISPLAYNAME

"Product-Name Purpose" of the package, for instance "Sound Juicer CD Ripper", "Mozilla Web Browser", or "GNU Emacs Text Editor".

Substitute a particular language code for [xx] like "DisplayName[fr]" or "DisplayName[de]". English text should not have any language declaration.

string Yes

DisplayName: Autopackage GTK+ Graphical User Interface

DisplayName[fr]: Autopackage GTK+ Frontend Graphique

InterfaceVersion $INTERFACEVERSION

Abstraction of the interface the package exposes represented as "A.B". Not useful for, say, applications or themes that do not expose an interface.

numeric No 1.0
License $LICENSE

License of the package.

string No

GNU General Public License, Version 2

GNU Lesser General Public License, Version 2.1

Apache License, Version 2.0

Public Domain

Maintainer $MAINTAINER

The name and email of the software's author or a group.

string Yes

Joe Developer <joe@developer.net>

The FooBar Development Team <development@foobar.org>

Packager $PACKAGER

Name of the person who created this package. Usually equal to the value of the Maintainer key.

string Yes Joe Packager <joe@packager.net>
PackageVersion $PACKAGEVERSION

Version of the package.

numeric No 1
RootInstallOnly $ROOTINSTALLONLY

Forces package installation to the global database which makes it available system-wide. Requires user to have super user (root) password.

boolean No Yes
RootName $ROOTNAME

Identifier for the package which is composed of package owner, software version and package release version.

string Yes @foobar.org/frob:2000:3
ShortName $SHORTNAME

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.

string Yes autopackage-gtk
SoftwareVersion $SOFTWAREVERSION

Version of the software usually set by the software authors.

numeric Yes 2.6
Summary[xx] $SUMMARY

A short, one-line description of the package.

Substitute a particular language code for [xx] like "Summary[fr]" or "Summary[de]". English text should not have any language declaration.

string Yes

Summary: A graphical (GTK+) frontend for installing Autopackage packages.

Summary[fr]: Un frontend (GTK+) graphique pour installer des paquets d'Autopackage.

URL $URL

Home location that relates to the package.

string No http://organization.org/application-page.html

Description

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.

BuildPrepare

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.

BuildUnprepare

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.

Imports

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:

  1. Invoke a build system command similar to 'make install'. Make sure the files are installed to $build_root . After that, you can simple call echo '*' | import .
  2. The files that are built during the build process are probably in the source directory. You can manually import files from that directory. The location of the source directory is specified in $source_dir .

    For example, your project is based on a simple make-based build system. Make compiles superpig.c to the binary superpig . Your source directory also has wai.png , a data file used by superpig . You write this in your specfile:

                            
    import <<EOF
    $source_dir/superpig
    $source_dir/wai.png
    EOF
    

Prepare

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 (which might involve user interaction), 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 makeinstaller 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.

Note

The prep and install scripts run in +e mode, which means that any line which returns a non-zero exit code will terminate the script . If running a command might fail but the script should carry on regardless, stick || true on the end of it.

Uninstall

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).