control
Every Click package must include the following control fields:
- Click-Version: the current version number of this specification
The package manager must refuse to process packages where any of these
fields are missing or unparseable. It must refuse to process packages where
Click-Version compares newer than the corresponding version it implements
(according to rules equivalent to “dpkg –compare-versions”). It may refuse
to process packages whose Click-Version field has an older major number than
the version it implements (although future developers are encouraged to
maintain the maximum possible degree of compatibility with packages in the
wild).
Several other fields are copied from the manifest, to ease interoperation
with Debian package manipulation tools. The manifest is the primary
location for these fields, and Click-aware tools must not rely on their
presence in the control file.
All dependency relations are forbidden. Packages implicitly depend on the
entire contents of the Click system framework they declare.
manifest
There must be a “manifest” file in the control area (typically corresponding
to “manifest.json” in source trees), which must be a dictionary represented
as UTF-8-encoded JSON. It must include the following keys:
- name: unique name for the application
- version: version number of the application
- framework: the system framework(s) for which the package was built
- installed-size: the size of the unpacked package in KiB; this should not
be set directly in the source tree, but will be generated automatically
by “click build” using “du -k -s –apparent-size”
The package manager must refuse to process packages where any of these
fields are missing or unparseable. It must refuse to process packages where
the value of “framework” does not declare a framework implemented by the
system on which the package is being installed.
The value of “name” identifies the application, following Debian source
package name rules; every package in the app store has a unique “name”
identifier, and the app store will reject clashes. It is the developer’s
responsibility to choose a unique identifier. The recommended approach is
to follow the Java package name convention, i.e. “com.mydomain.myapp”,
starting with the reverse of an Internet domain name owned by the person or
organisation developing the application; note that it is not necessary for
the application to contain any Java code in order to use this convention.
The value of “version” provides a unique version for the application,
following Debian version numbering rules. See deb-version(5) for full
details.
The syntax of “framework” is formally that of a Debian dependency
relationship field. Currently, only a simple name is permitted, e.g.
“framework”: “ubuntu-sdk-13.10”, or a list of simple names all of which must
be satisfied, e.g. “framework”: “ubuntu-sdk-14.04-qml,
ubuntu-sdk-14.04-webapps”; version relationships and alternative
dependencies are not currently allowed.
The manifest may contain arbitrary additional optional keys; new optional
keys may be defined without changing the version number of this
specification. The following are currently recognised:
- title: short (one-line) synopsis of the application
- description: extended description of the application; may be
multi-paragraph
- maintainer: name and email address of maintainer of the application
- architecture: one of the following:
- “all”, indicating a package containing no compiled code
- a dpkg architecture name (e.g. “armhf”) as a string, indicating a
package that will only run on that architecture
- a list of dpkg architecture names, indicating a package that will run
on any of those architectures
- hooks: see Hooks
- icon: icon to display in interfaces listing click packages; if the name
refers to an existing file when resolved relative to the base directory
of the package, the given file will be used; if not, the algorithm
described in the Icon Theme Specification will be
used to locate the icon
Keys beginning with the two characters “x-” are reserved for local
extensions: this file format will never define such keys to have any
particular meaning.
Keys beginning with an underscore (“_”) are reserved for use as dynamic
properties of installed packages. They must not appear in packages’
manifest files, and attempts to set them there will be ignored. The
following dynamic keys are currently defined:
- _directory: the directory where a package is unpacked
- _removable: 1 if a package is unpacked in a location from which it can be
removed, otherwise 0 (this may be changed to a proper boolean in future;
client code should be careful to permit either)
Maintainer scripts
Maintainer scripts are forbidden, with one exception: see below. (If they
are permitted in future, they will at most be required to consist only of
verified debhelper-generated fragments that can be statically analysed.)
Packages in Click system frameworks are encouraged to provide file triggers
where appropriate (e.g. “interest /usr/share/facility”); these will be
processed as normal for dpkg file triggers.
The exception to maintainer scripts being forbidden is that a Click package
may contain a preinst script with the effect of causing direct calls to dpkg
to refuse to install it. The package manager must enforce the permitted
text of this script.