<?xml version='1.0' encoding='utf-8'?>
<html lang="en">
<h2>Feed file format specification</h2>
<p>
This document is a formal description of the XML feed file format. An interface describes a program,
library or other component. A feed provides a list of known implementations of the interface (versions of the program)
and details about how to get them, how to check that they are authentic, how to run them and what other components
they depend on.
</p>
<p>
This class diagram shows how the different concepts are related. Each feed file contributes information to this model:
</p>
<p class='uml'>
<img src='UML/zero-install-feed-classes.png' width='705' height='378' alt='Class diagram for feed files'/>
</p>
<p>
Each <k>Feed</k> lists a number of <k>Implementations</k> (versions). An <k>Identity</k>
is a way to recognise an Implementation (e.g. a cryptographic digest). A
<k>Retrieval method</k> is a way to get an Implementation (e.g. by downloading
from an FTP site). A <k>Command</k> says how to run an Implementation as a
program.A <k>Dependency</k> indicates that one component depends on another
(e.g. Gimp requires the GTK library). A <k>Binding</k> says how to let the
program locate the Implementations when run. A <k>Constraint</k> limits the
choice of a dependency (e.g. Gimp requires a version of GTK >= 2.6).
</p>
<p>
Note on terminology: originally the word 'interface' was used to mean both 'interface' and 'feed', so don't
be confused if you see it used this way.
</p>
<ul>
<li><a href='http://0install.de/schema/injector/interface/schema.xsd'>XSD schema</a></li>
</ul>
<p>
Changes to this document (and to the rest of the web-site) are <a href='https://sourceforge.net/p/zero-install/code/commit_browser'>tracked using Git</a>.
</p>
<h2>Contents</h2>
<toc level='h2'/>
<h2 id='intro'>Introduction</h2>
<p>
Feed files are introduced in the <a href='injector-packagers.html'>packager's guide</a>.
They have the following syntax (? follows optional items, * means zero-or-more, order of elements
is not important, and extension elements can appear anywhere as long as they use a different
namespace):
</p>
<pre>
<?xml version='1.0'?>
<interface xmlns='http://zero-install.sourceforge.net/2004/injector/interface'
min-injector-version='...' ?
uri='...' ? >
<name>...</name>
<summary>...</summary>
<description>...</description> ?
<homepage>...</homepage> ?
<category type='...' ? >...</category> *
<needs-terminal/> ?
<icon type='...' href='...'/> *
<feed src='...' langs='...' ? arch='...' ?/> *
<feed-for interface='...'/> *
<replaced-by interface='...'/> ?
[group] *
[implementation] *
[entry-point] *
</interface>
</pre>
<dl>
<dt>min-injector-version</dt>
<dd>This attribute gives the oldest version of 0install that can read this file. Older versions will
tell the user to upgrade if they are asked to read the file. Versions prior to 0.20 do not perform this check, however.
If the attribute is not present, the file can be read by all versions.
</dd>
<dt>uri</dt>
<dd>This attribute is only needed for remote feeds (fetched via HTTP). The value must exactly match the expected
URL, to prevent an attacker replacing one correctly-signed feed with another (e.g., returning a feed for the
<b>shred</b> program when the user asked for the <b>backup</b> program).
</dd>
<dt><name></dt> <dd>a short name to identify the interface (e.g. "Foo")</dd>
<dt><summary></dt> <dd>a short one-line description; the first word should
not be upper-case unless it is a proper noun (e.g. "cures all ills")</dd>
<dt><description></dt> <dd>a full description, which can be several paragraphs long (optional since 0.32, but recommended)</dd>
<dt><homepage></dt> <dd>the URL of a web-page describing this interface in more detail</dd>
<dt><category></dt> <dd>a classification for the interface. If no type is given, then the category is one of the
'Main' categories defined by the <a href='http://standards.freedesktop.org/menu-spec/latest/apa.html'>freedesktop.org menu specification</a>. Otherwise, it is a URI giving the namespace for the category.</dd>
<dt><needs-terminal></dt> <dd>if present, this element indicates that the program requires a terminal in order to run. Graphical launchers should therefore run this program in a suitable terminal emulator.</dd>
<dt><icon></dt> <dd>an icon to use for the program; this is used by programs such as
<a href="http://rox.sourceforge.net/desktop/AddApp">AddApp</a>.</dd>
<dt><feed></dt> <dd>the linked feed contains more implementations of this feed's interface. The "langs" and "arch" attributes, if present, indicate that all implementations will fall within
these limits (e.g. arch='*-src' means that there is no point fetching this feed
unless you are looking for source code). See the <implementation> element
for a description of the values of these attributes.</dd>
<dt><feed-for></dt> <dd>the implementations in this feed are implementations of the given interface. This is used when adding an optional extra feed to an interface with "0install add-feed" (e.g. a <a href='local-feeds.html'>local feed</a> for a development version).</dd>
<dt id='replaced-by'><replaced-by></dt> <dd>this feed's interface (the one in the root element's <b>uri</b> attribute) has been replaced by the given interface. Any references to the old URI should be updated to use the new one.</dd>
</dl>
<h2 id='groups'>Groups</h2>
<p>
A group has this syntax:
</p>
<pre>
<group
version='...' ?
released='...' ?
main='...' ?
self-test='...' ?
doc-dir='...' ?
license='...' ?
released='...' ?
stability='...' ?
langs='...' ?
arch='...' ? >
[requires] *
[group] *
[command] *
[binding] *
[implementation] *
[package-implementation] *
</group>
</pre>
<p>
All attributes of the group are inherited by any child groups and implementations as defaults, but
can be overridden there. All dependencies ("requires"), bindings and commands are inherited (sub-groups may add more
dependencies and bindings to the list, but cannot remove anything).
</p>
<h2 id='implementations'>Implementations</h2>
<p>
An implementation has this syntax (an unspecified argument is inherited from
the closest ancestor <group> which defines it):
</p>
<pre>
<implementation
[all <group> attributes]
id='...'
local-path='...' ? >
<manifest-digest [digest] * /> *
[command] *
[retrieval-method] *
[binding] *
[requires] *
</implementation>
</pre>
<p class='uml'>
<img src='UML/zero-install-id.png' width='405' height='205' alt='Identity classes'/>
</p>
<dl>
<dt>id</dt>
<dd>A unique identifier for this implementation. For example, when the user marks a particular
version as buggy this identifier is used to keep track of it, and saving and restoring selections
uses it. However, see the important historical note below.</dd>
<dt>local-path</dt>
<dd>
If the feed file is a local file (the interface 'uri' starts with <b>/</b>)
then the <b>local-path</b> attribute <i>may</i> contain the pathname of a local
directory (either an absolute path or a path relative to the directory
containing the feed file). See the historical note below.</dd>
<dt>version</dt>
<dd>The version number. See the version numbers section below for more details.</dd>
<dt>main (deprecated)</dt>
<dd>The relative path of an executable inside the implementation that should be executed by default
when the interface is run. If an implementation has no <b>main</b> setting, then it cannot be executed
without specifying one manually (with <b>0launch --main=MAIN</b>). This typically means that the interface
is for a library. Note: <b>main</b> is being replaced by the <command> element.</dd>
<dt>self-test (deprecated)</dt>
<dd>The relative path of an executable inside the implementation that can be executed to test the program.
The program must be non-interactive (e.g. it can't open any windows or prompt for input).
It should return with an exit status of zero if the tests pass. Any other status indicates failure. Note: <b>self-test</b> is being replaced by the <command> element.
</dd>
<dt>doc-dir</dt>
<dd>The relative path of a directory inside the implementation that contains the package's documentation.
This is the directory that would end up inside <b>/usr/share/doc</b> on a traditional Linux system.</dd>
<dt>released</dt>
<dd>The date this implementation was made available, in the format YYYY-MM-DD. For development versions checked
out from version control this attribute should not be present.</dd>
<dt>stability</dt>
<dd>The default stability rating for this implementation. If not present, <b>testing</b> is used.
See the stability section below for more details.</dd>
<dt>langs</dt>
<dd>The natural language(s) which this package supports, as a space-separated
list of languages codes (in the same format as used by the $LANG environment
variable). For example, the value "en_GB fr" would be used for a package
supporting British English and French. Supported since 0.48. Note that versions before 0.54
require the region separator to be '_' (underscore), while later versions also allow the use of '-'
for consistency with the xml:lang format.</dd>
<dt>arch</dt>
<dd>For platform-specific binaries, the platform for which this implementation was compiled, in the form <b>os-cpu</b>.
0install knows that certain platforms are backwards-compatible with others, so binaries with <b>arch="Linux-i486"</b>
will still be available on <i>Linux-i686</i> machines, for example. Either the <i>os</i> or <i>cpu</i> part may be <b>*</b>,
which will make it available on any OS or CPU. If missing, the default is <b>*-*</b>. See also: <a href='#archs'>Valid architecture names</a>.</dd>
<dt>license</dt>
<dd>License terms. This is typically a <a href='http://catb.org/~esr/trove/'>Trove</a> category. See <a href='http://pypi.python.org/pypi?%3Aaction=list_classifiers'>the PyPI list</a> for some examples (the leading "License :: " is not included).</dd>
</dl>
<p>
The <b>manifest-digest</b> element is used to give digests of the .manifest file
using various hashing algorithms (but see the historical note below). Having multiple
algorithms allows a smooth upgrade to newer digest algorithms without breaking old
clients. Each non-namespaced attribute gives a digest, with the attribute
name being the algorithm. For example:
</p>
<pre>
<manifest-digest sha256="4f078f9080bd9b3b87e8360f014268886ec653ed077bb3cb6725185c0a07473a"/>
</pre>
<p>
For non-local implementations (those without a local-path attribute), the
<implementation> element contains a set of <i>retrieval methods</i>, each
of which gives a different way of getting the implementation (i.e. of getting a
directory structure whose digest matches the ones given).
</p>
<p>
Currently, 0install always chooses the first of the methods it understands,
but in future it may use other strategies (such as choosing the closest mirror,
or letting the user select one manually). It may also use other methods which
aren't listed, such as searching for the implementation on a peer-to-peer
network.
</p>
<p>Unrecognised elements inside an implementation are ignored.</p>
<h3>Historical note about id</h3>
<p>
0launch >= 0.45 generally treats the ID as a simple identifier, and gets the local path (if any)
from the local-path attribute and the digests from the <manifest-digest>.
</p>
<p>
0launch < 0.45 ignores the local-path attribute and the <manifest-digest> element.
If the ID starts with '.' or '/' then the ID is also the local path; otherwise, it is the
single manifest digest.
</p>
<p>
For backwards compatibility, 0launch >= 0.45 will treat an ID starting with '.' or '/' as a
local path if no local-path attribute is present, and it will treat it as an additional
digest if it contains an '=' character.
</p>
<p>
Therefore, if you want to generate feeds compatible with past and future versions:
</p>
<ul>
<li>If you have a digest, set the ID to "sha1new=..." and put the sha256 digest in the
<manifest-digest>.</li>
<li>If you have a local implementation then set both id and local-path to the pathname.</li>
</ul>
<h2 id='commands'>Commands</h2>
<p>
The <b>main</b> attribute above provides a simple way to say how to run this implementation. The
<command> element (supported since 0.51, released Dec 2010) provides a more flexible alternative.
</p>
<pre>
<command
name='...'
path='...' ? >
[binding] *
[requires] *
[runner] ?
<arg> ... </arg> *
<for-each item-from='...' separator='...'? > ... </for-each> *
</command>
</pre>
<dl>
<dt>name</dt>
<dd>By default, 0launch executes the "run" command, but the <b>--command</b> option can be used to specify a different one.
<a href='0test.html'>0test</a> runs the "test" command (replacing the old <b>self-test</b> attribute) and <a href='0compile.html'>0compile</a> runs the "compile" command (replacing the <b>compile:command</b> attribute).</dd>
<dt>path</dt>
<dd>The relative path of the executable within the implementation (optional if <runner> is used).</dd>
</dl>
<p>
Additional arguments can be passed using the <arg> element. Within an argument, "${name}" is expanded to the value of the corresponding environment variable. These arguments are passed to the program before any arguments specified by the user.
</p>
<p>
If an environment variable should be expanded to multiple arguments, use <for-each>. The variable in the 'item-from' attribute is split using the given separator (which defaults to the OS path separator, ":" on POSIX and ";" on Windows) and the arguments inside the element are added for each item. The current item is available as "${item}". If the variable given in 'item-from' is not set or is empty, no arguments are added. See below for an example. Versions of 0install before 1.15 ignore <for-each> elements and their contents.
</p>
<p>
Command-specific dependencies can be specified for a command by nesting <requires> elements. For example, an interpreter might only depend on libreadline when
used interactively, but not when used as a library, or the "test" command might depend on a test framework.
</p>
<p>
Command-specific bindings (0launch >= 1.3) create a binding from the implementation to itself. For example, the "test" command may want to make the "run" command available in $PATH using <executable-in-path>.
</p>
<p>
The <runner> element introduces a special kind of dependency: the program that is used to run this one. For example, a Python
program might specify Python as its runner. <runner> is a subclass of
<requires> and accepts the same attributes and child elements. In addition, you can specify arguments to pass to the runner by nesting them inside the <runner> element.
These arguments are passed before the path of the executable given by the 'path' attribute.
</p>
<p>For example:</p>
<pre>
<command name='run' path="causeway.e-swt">
<runner interface='http://repo.roscidus.com/e/e-core'>
<arg>-cpa</arg>
<arg>$SWT_JAR</arg>
<for-each item-from="EXTRA_E_OPTIONS" separator=" ">
<arg>${item}</arg>
</for-each>
</runner>
</command>
</pre>
<p>
In this case, 0install will run the equivalent of <b>/path/to/e-interpreter -cpa /path/to/swt.jar $EXTRA_E_OPTIONS /path/to/causeway.e-swt</b>.
</p>
<h2 id='package-implementation'>Package implementations</h2>
<p>
This element names a distribution-provided package which, if present, is a valid
implementation of this interface. The syntax is:
</p>
<pre>
<package-implementation
package='...'
distributions='...' ?
main='...' ? >
[command] *
[requires] *
</package-implementation>
</pre>
<p>
If the named package is available then it will be considered as a possible implementation
of the interface. If <b>main</b> is given then it must be an absolute path.
</p>
<p>
If the <b>distributions</b> attribute is present then it is a space-separated list of distribution names
where this element applies. 0launch >= 0.45 ranks the <package-implementation> elements according
to how well they match the host distribution and then only uses the best match (or matches, if several get
the same score). See <a href='distribution-integration.html'>Distribution integration</a> for a list of
supported distributions.
</p>
<p>
Earlier versions of 0launch ignore the <b>distributions</b> attribute and process all of the elements.
</p>
<p>
Note that, unlike a normal implementation, a distribution package does not resolve to a directory.
Any bindings inside <requires> elements for the interface will be ignored; it is assumed that
the requiring component knows how to use the packaged version without further help. Therefore, adding
distribution packages to your interface considerably weakens the guarantees you are making about what
the requester may get.
</p>
<p>
Package implementations still inherit attributes and dependencies from their parent group. The
<b>doc-dir</b> and <b>license</b> attributes may be given, but <b>version</b> and <b>released</b>
are read from the native packaging system.
</p>
<p>
Support for distribution packages was added in version 0.28 of 0install. Earlier versions ignore
this element.
</p>
<h2 id='retrieval-methods'>Retrieval methods</h2>
<p>
A retrieval method is a way of getting an implementation.
</p>
<p class='uml'>
<img src='UML/zero-install-retr.png' width='485' height='415' alt='Retrieval method classes'/>
</p>
<p>
The most common retrieval method is the <archive> element:
</p>
<pre id='retrievalmethods'>
<archive
href='...'
size='...'
extract='...' ?
dest='...' ?
type='...' ?
start-offset='...' ? />
</pre>
<p>
This states that an archive may be downloaded from the address given in the <b>href</b> attribute. The archive must
have the given <b>size</b> or it will be rejected. When unpacked (either the subdirectory named in the <b>extract</b>
attribute, or the whole archive if it is not present), the resulting tree will generate a manifest with the secure hash
value given as the implementation's <b>id</b>. If <b>dest</b> is given (0install >= 2.1), then the archive is unpacked
to the specified subdirectory. It is an error to specify a target outside of the implementation directory (e.g.
"../foo" or attempting to follow a symlink that points out of the implementation).
</p>
<p>
The type of the archive is given as a MIME type in the <b>type</b> attribute
(since <b>0launch</b> version 0.21). If missing, the type is guessed from the extension on the
<b>href</b> attribute (all versions). Known types and extensions (case insensitive) are:
</p>
<ul>
<li>application/x-rpm (.rpm) - not supported by Windows version</li>
<li>application/x-deb (.deb) - not supported by Windows version</li>
<li>application/x-tar (.tar)</li>
<li>application/x-bzip-compressed-tar (.tar.bz2)</li>
<li>application/x-lzma-compressed-tar (.tar.lzma)</li>
<li>application/x-compressed-tar (.tar.gz or .tgz)</li>
<li>application/zip (.zip)</li>
<li>application/vnd.ms-cab-compressed (.cab)</li>
<li>application/x-xz-compressed-tar (.tar.xz) - since version 0.43, not supported by Windows version</li>
<li>application/x-ruby-gem (.gem) - since version 1.0-rc1, not supported by Windows version</li>
<li>application/x-7z-compressed (.7z) - Windows version only</li>
<li>application/x-msi (.msi) - Windows version only</li>
</ul>
<p>
The <b>start-offset</b> attribute (since version 0.21) gives the number of
bytes at the beginning of the file which should be ignored. This is useful for
some self-extracting archives which are made up of a shell script followed by a
normal archive in a single file. If missing, it defaults to 0. The value in the
<b>size</b> attribute does not include the skipped bytes.
</p>
<p>
You can also fetch individual files (0install >= 2.1). This is useful for e.g. jar files, which are typically not unpacked:
</p>
<pre id='file'>
<file
href='...'
size='...'
dest='...' />
</pre>
<p>
The file is downloaded from <b>href</b>, must be of the given <b>size</b>, and is placed within the implementation directory as <b>dest</b>.
</p>
<h3 id='recipe'>Recipes</h3>
<p>
An implementation can also be created by following a <recipe>:
</p>
<pre>
<recipe>
( <archive ...> | <file ...> | <rename ...> | <remove ...> | <copy-from ...> ) +
</recipe>
</pre>
<p>
In this case, each child element of the recipe represents a step. To get an implementation by following a recipe,
a new empty directory is created and then all of the steps are performed in sequence. The resulting directory
must have the digest given in the implementation's <manifest-digest>. A recipe containing only a single archive is equivalent
to just specifying the archive on its own.
If a recipe contains an unrecognised element then the whole recipe must be ignored.
</p>
<dl>
<dt><archive ...></dt>
<dd>Causes the named archive to be fetched and unpacked over the top of whatever is currently in the temporary directory. It supports the same attributes as when used outside of a recipe.</dd>
<dt><file ...></dt>
<dd>Causes the named file to be fetched and saved over the top of whatever is currently in the temporary directory (0install >= 2.1). It supports the same attributes as when used outside of a recipe.</dd>
<dt><rename source='...' dest='...'></dt>
<dd>Renames or moves a file or directory (0install >= 1.10). It is an error if the source or destination are outside the implementation.</dd>
<dt><remove path='...'></dt>
<dd>Delete the file or directory from the implementation (0install >= 2.1). It is an error if the path is outside the implementation.</dd>
<dt><copy-from id='...' source='...' ? dest='...' ?></dt>
<dd>Copies files or directories from another implementation, e.g., for applying an update to a previous version (0install >= 2.13). The specified id must exactly match the id attribute of another implementation specified elsewhere in the same feed. You can specify the source and destination file or directory to be copied relative to the implementation root. Leave them unset to copy the entire implementation.</dd>
</dl>
<p>
Note: A recipe is generally only useful for patching existing archives without having to host the complete result
yourself. Normally, if your program requires files from several different packages then it is better to use the
<requires> element instead. This allows libraries to be shared between different programs, and lets the user
choose the versions and upgrade them individually.
</p>
<h2 id='dependencies'>Dependencies</h2>
<p>
A <requires> element means that every implementation within the same group (including nested
sub-groups) requires an implementation of the specified interface when run. 0install will choose a
suitable implementation, downloading one if required.
</p>
<pre>
<requires
interface='...'
importance='...' ?
version='...' ?
os='...' ?
distribution='...' ?
source='true|false' ?
use='...' ? >
[ constraints ] *
[ bindings ] *
</requires>
</pre>
<p>
The constraint elements (if any) limit the set of acceptable versions. The bindings specify how
0install should make its choice known (typically, by setting environment variables).
</p>
<p>
The <b>use</b> attribute can be used to indicate that this dependency is only needed in some cases. By default, 0launch >= 0.43
will skip any <requires> element with this attribute set. Earlier versions process all <requires> elements
whether this attribute is present or not. <a href='0test.html'>0test</a> >= 0.2 will process dependencies where <b>use="testing"</b>, in
addition to the program's normal dependencies. This attribute is deprecated - it's usually better to use a <command> for this.
</p>
<p>
The <b>importance</b> attribute (0install >= 1.1) can be either
"<b>essential</b>" (the default; a version of this dependency must be selected)
or "<b>recommended</b>" (no version is also an option, although selecting a
version is preferable to not selecting one).
</p>
<p>
The <b>version</b> attribute (0install >= 1.13) provides a quick way to specify the permitted versions. See the <a href='#constraints'>Constraints</a> section below.
</p>
<p>
The <b>distribution</b> attribute (0install >= 1.15) can be used to require the selected implementation to be from the given distribution. For example, a Python library available through MacPorts can only be used with a version of Python which is also from MacPorts. The value of this attribute is a space-separated list of distribution names. In addition to the <a href='distribution-integration.html'>official list of distribution names</a>, the special value "0install" may be used to require an implementation provided by 0instal (i.e. one not provided by a <package-implementation>).
</p>
<p>
The <b>os</b> attribute (0install >= 1.12) can be used to indicate that the dependency only applies to the given OS (e.g. <b>os="Windows"</b> for
dependencies only needed on Windows systems).
</p>
<p>
The <b>source</b> attribute (0install >= 2.8) can be used to indicate that a source implementation is needed rather than a binary. This may be useful if you want to get e.g. header files from a source package. Note that if you select both source and binary implementations of an interface, 0install does not automatically force them to be the same version.
</p>
<p>
A <restricts> element (0install >= 1.10) can be used to apply constraints without creating a dependency:
</p>
<pre>
<restricts
interface='...'
version='...' ?
os='...' ?
distribution='...' ? >
[ constraints ] *
</restricts>
</pre>
<p>
Internally, <restricts> behaves much like <requires importance='recommended'>, except that it doesn't try to cause the interface to be selected at all.
</p>
<h2 id='constraints'>Constraints</h2>
<p>
Constraints appear inside <requires>, <restricts> and <runner> elements. They restrict the set of versions from which
0install may choose an implementation.
</p>
<pre>
<version
not-before='...' ?
before='...' ? >
</pre>
<dl>
<dt>not-before</dt>
<dd>This is the lowest-numbered version that can be chosen.</dd>
<dt>before</dt>
<dd>This version and all later versions are unsuitable.</dd>
</dl>
<p>For example, <b><version not-before='2.4' before='2.6'></b> allows any of these
versions: 2.4, 2.4.0, and 2.4.8. It will not select 2.3.9 or 2.6.
</p>
<p>
Since 0install 1.13, it is also possible to use a <b>version</b> attribute on the dependency directly. This provides a shorter and more flexible way to specify versions.
The attribute's value is a list of ranges, separated by "|", any of which may match.
For example:
</p>
<pre>
<restricts interface='http://repo.roscidus.com/python/python'
version='2.6..!3 | 3.2.2..'/>
</pre>
<p>
This allows Python versions 2.6, 2.7 and 3.3, but not 2.5 or 3.
</p>
<p>
Each range is in the form "START..!END". The range matches versions where START <= VERSION < END. The start or end may be omitted. A single version number may be used instead of a range to match only that version, or !VERSION to match everything except that version.
</p>
<p>
Note: to support older versions of 0install, it is preferable to use the <version> element instead where possible.
</p>
<h2 id='bindings'>Bindings</h2>
<p>
Bindings specify how the chosen implementation is made known to the running program. Bindings
can appear in a <requires> element, in which case they tell a component how to find its
dependency, or in an <implementation> (or group), where they tell a component how to find
itself.
</p>
<p class='uml'>
<img src='UML/zero-install-binding.png' width='565' height='225' alt='Binding classes'/>
</p>
<h3 id='environment'>Environment bindings</h3>
<pre>
<environment
name='...'
(insert='...' | value='...')
mode='prepend|append|replace' ?
separator='...' ?
default='...' ? /> *
</pre>
<p>
Details of the chosen implementation are passed to the program by setting environment variables,
as specified by the <environment> elements (typically, there will be exactly one of these in each
<requires> element). Each environment element gives the name of the variable and the relative path
of the item within the implementation to insert into the variable's value.
</p>
<p>
Usually, the (badly-named) <b>insert</b> attribute is used, which adds a path to a file or directory inside the
implementation to the environment variable. For example, <environment
name='PATH' insert='bin'/> would perform something similar to the bash shell
statement <b>export PATH=/path/to/impl/bin:$PATH</b>.
</p>
<p>
Alternatively, you can use the <b>value</b> attribute to use a literal string. For example,
<environment name='GRAPHICAL_MODE' value='TRUE' mode='replace'/>. This requires 0launch >= 0.52.
</p>
<p>
If <b>mode</b> is <b>prepend</b> (or not set), then the absolute path of the
item is prepended to the current value of the variable. The default separator character
is the colon character on POSIX systems, and semi-colon on Windows. This can be overridden
using <b>separator</b> (0install >= 1.1). If the environment variable is not currently
set then the path is prepended to the value of the default attribute. If no
default value is given either then the default for that environment variable is
used, or the environment variable's value is set to the absolute path directly
if there is no default.
</p>
<p>
If <b>mode</b> is <b>append</b> then the same thing happens, except that the new
value is added at the end instead of the beginning. If the mode is <b>replace</b> then
the old value is overwritten, and the <b>default</b> attribute is ignored.
</p>
<p>
The following environment variables have known defaults and therefore the <b>default</b> attribute is not
needed with them:
</p>
<dl>
<dt>PATH</dt><dd>/bin:/usr/bin</dd>
<dt>XDG_CONFIG_DIRS</dt><dd>/etc/xdg</dd>
<dt>XDG_DATA_DIRS</dt><dd>/usr/local/share:/usr/share</dd>
</dl>
<h3 id='executable'>Executable bindings</h3>
<p>
These both require 0install >= 1.2.
</p>
<pre>
<executable-in-var
name='...'
command='...' ? />
<executable-in-path
name='...'
command='...' ? />
</pre>
<p>
These are used when the program needs to run another program. <b>command</b> says which of the program's commands to use; the default is "run".
</p>
<p>
<executable-in-var> stores the path of the selected executable
in the named environment variable. For example, if a program uses <b>$MAKE</b> to run make, you can provide the required command
like this:
</p>
<pre>
<requires interface="http://repo.roscidus.com/devel/make">
<executable-in-var name='MAKE'/>
</requires>
</pre>
<p>
<executable-in-path> works in a similar way, except that it adds a directory containing the executable to $PATH. For example,
if the program instead just runs the <b>make</b> command, you would use:
</p>
<pre>
<requires interface="http://repo.roscidus.com/devel/make">
<executable-in-path name='make'/>
</requires>
</pre>
<p>
It is preferable to use <executable-in-var> where possible, to avoid making $PATH very long.
</p>
<p>
Implementation note: On POSIX systems, 0install will create a shell script under ~/.cache/0install.net/injector/executables and pass the path of this script.
</p>
<h3 id='generic-bindings'>Generic bindings</h3>
<p>
Custom bindings can be specified using the <binding> element (0install >= 2.1). 0install will not know how to run a program using custom bindings itself, but it will include them in any selections documents it creates, which can then be executed by your custom code. The syntax is:
</p>
<pre>
<binding
path='...' ?
command='...' ?
... >
...
</binding>
</pre>
<p>
If <b>command</b> is given, then 0install will select the given <command> within the implementation (which may cause additional dependencies and bindings to be selected). Otherwise, no command is selected.
</p>
<p>
Any additional attributes and child elements are not processed, but are just passed through. If your binding needs a path within the selected implemention, it is suggested that the <b>path</b> attribute be used for this. Other attributes and child elements should be namespaced to avoid collisions.
</p>
<p>
For example, the <a href='ebox.html'>EBox</a> application launcher allows each code module to specify its dependencies, which are then available in the module's scope as <i>getters</i>. The ebox-edit application depends on the help library like this:
</p>
<pre>
<requires interface="http://0install.net/tests/ebox-help.xml">
<binding e:getter='help'/>
</requires>
</pre>
<h2 id='versions'>Versions</h2>
<p>
A version number string has the following form:
</p>
<pre>
Version := DottedList ("-" Modifier? DottedList?)*
DottedList := (Integer ("." Integer)*)
Modifier := "pre" | "rc" | "post"
</pre>
<p>
Numerically, the modifiers come in the order "-pre" (pre-release), "-rc" (release candidate),
"-" (no modifier name), "-post" (post-release or patch level). Versions are ordered like this:
</p>
<ul>
<li>0.1</li>
<li>1</li>
<li>1.0</li>
<li>1.1</li>
<li>1.2-pre</li>
<li>1.2-pre1</li>
<li>1.2-rc1</li>
<li>1.2</li>
<li>1.2-0</li>
<li>1.2-post</li>
<li>1.2-post1-pre</li>
<li>1.2-post1</li>
<li>1.2.1-pre</li>
<li>1.2.1.4</li>
<li>1.2.2</li>
<li>1.2.10</li>
<li>3</li>
</ul>
<p>
0install doesn't care about anything other than the sort order (i.e., whether
one version comes before or after another). It is expected that an
implementation can be safely replaced by one with a later version number, but
not necessarily with an earlier one. So, if an application works with version
"1.2.1" of a library then it should also work with version "1.2.2" or "1.3" or
even "5.7", but not "1.2.0". This is a little different to some other systems,
where numbers in different places have different meanings.
</p>
<p>
For example, if the latest version of a library you use is version 5.1, then
you shouldn't add the restriction <b>before='5.2'</b>, because when 5.2 comes
out it should still work with your program. Of course, this might not always work,
and hopefully the problem will be reported while the new library version is marked
as testing (before most users hit the problem). Once you know that 5.2 is a problem,
you can add the <b>before='5.2'</b> restriction to the implementation then.
</p>
<p>
Incompatible changes (where a newer version cannot be used in place of an older
version) to an interface should be handled by creating a new interface URI. Eg:
</p>
<ul>
<li>http://gtk.org/2005/interfaces/GTK-1.2.x (contains 1.2.0, 1.2.1, 1.2.2, ...)</li>
<li>http://gtk.org/2005/interfaces/GTK-2.x (contains 2.0.0, 2.0.1, 2.2.0, 2.4.0, 2.4.1, ...)</li>
</ul>
<p>
Note that version numbers containing dash characters were not supported before version 0.24 of
0install and so a <b>version-modifier</b> attribute was added to allow new-style versions to be added without breaking older versions. This should no longer be used.
</p>
<p>
The integers in version numbers must be representable as 64-bit signed integers.
</p>
<h2 id='stability'>Stability</h2>
<p>
The feed file also gives a stability rating for each implementation. The following
levels are allowed (must be lowercase in the feed files):
</p>
<ul>
<li>stable</li>
<li>testing</li>
<li>developer</li>
<li>buggy</li>
<li>insecure</li>
</ul>
<p>
Stability ratings are expected to change over time. When any new release is
made, its stability should be set to <b>testing</b>. Users who have selected
<b>Help test new versions</b> will then start using it. Other users will
continue with the previous stable release. After a while (days, weeks or
months, depending on the project) with no serious problems found, the
implementation's stability can be changed to <b>stable</b> so that everyone
will use it.
</p>
<p>
If problems are found, it can instead be marked as <b>buggy</b>, or <b>insecure</b>. 0install
won't select either by default, but it is useful to users to see the reason (users may opt to
continue using a buggy version if it seems to work for them, but they should never use an insecure
one). <b>developer</b> is like a more extreme version of <b>testing</b>, where the program is
expected to have bugs.
</p>
<h4>When to use 'buggy'</h4>
<p>
Don't mark old releases as <b>buggy</b> every time you do a new release, just
because a few bugs have been fixed. People who have selected <b>Network
use: Full</b> will automatically upgrade to the new version anyway, so marking an older
version as buggy only affects people who have explicitly stated that they <b>don't</b>
want to use the latest version, but would prefer to use an older release to
save network use.
</p>
<h2 id='entry-points'>Entry points</h2>
<p>(only used on the Windows version currently)</p>
<p>
Entry points allow you to associate additional information with <command> names, such as user-friendly names and descriptions. Entry points are used by the Zero Install GUI to help the user choose a command and by the desktop integration system to generate appropriate menu entries for commands. An entry point is not necessary for a command to work but it makes it more discoverable to end-users.
</p>
<p>
Entry points are top-level elements and, unlike commands, are not associated with any specific implementation or group. One entry point represents all commands in all implementations that carry the same name. An entry point has this syntax:
</p>
<pre>
<entry-point
command='...'
binary-name='...' ? >
<needs-terminal/> ?
<name>...</name> ?
<summary>...</summary> ?
<description>...</description> ?
<icon type='...' href='...'/> *
</group>
</pre>
<dt>command</dt>
<dd>the name of the command this entry point represents</dd>
<dt>binary-name</dt>
<dd>the canonical name of the binary supplying the command (without file extensions); this is used to suggest suitable alias names.</dd>
<dt><needs-terminal></dt>
<dd>if present, this element indicates that the command represented by this entry point requires a terminal in order to run.</dd>
<dt><name></dt>
<dd>user-friendly name for the command. If not present, the value of the <b>command</b> attribute is used instead.</dd>
<dt><summary></dt>
<dd>a short one-line description; the first word should not be upper-case unless it is a proper noun (e.g. "cures all ills")</dd>
<dt><description></dt>
<dd>a full description, which can be several paragraphs long</dd>
<dt><icon></dt>
<dd>an icon to represent the command; this is used when creating menu entries.</dd>
<h2 id='metadata'>Metadata</h2>
<p>
All elements can contain extension elements, provided they are not in the Zero
Install namespace used by the elements defined here. 0install does not
currently make use of these elements itself, but other programs may find them
useful. In future, some of these may be used (for example, the GUI may display
the license terms).
</p>
<p>
The use of <a href='http://dublincore.org'>Dublin Core</a> is suggested for the following concepts, which
have the following meanings when found as a direct child of a <group> or <implementation> element:
</p>
<dl>
<dt>dc:creator</dt>
<dd>The primary author of the program.</dd>
<dt>dc:publisher</dt>
<dd>The person who created this implementation. For a binary, this is the person who
compiled it.</dd>
</dl>
<p>
Other Dublin Core terms that may be useful include contributor,
dateCopyrighted, language, rights and rightsHolder.
</p>
<p>
These terms are not required as they are duplicated by the core Zero Install terms: identifier (id),
available (released) and requires (requires).
</p>
<p>
The source element may be used in future to record the source used to build this implementation.
</p>
<h2 id='signatures'>Digital signatures</h2>
<p>
When a feed is downloaded from the web, it must contain a digital signature.
A feed is signed by appending an XML comment block of the form:</p>
<pre><![CDATA[
<!-- Base64 Signature
iD8DBQBEXM/qrgeCgFmlPMERArNSAKDBuNz5SQMZ8rwJmW2fhNHJwor6KwCgwx7XEfY+6gUC90rJ
b5eCY+I8HNA=
-->]]></pre>
<p>
This block <b>must</b> go at the end of the file, and contains a Base64-encoded version of
the file that would be created by using <b>gpg --detach-sign</b> on the original feed.
The signature block must start on a new line, may not contain anything except valid base64
characters, and nothing may follow the signature block. XML signature blocks are supported
from version 0.18 of 0install and may be generated easily using the
<a href='0publish.html'>0publish</a> command.
</p>
<p>
Local interfaces are plain XML, although having an XML signature block is no problem as it
will be ignored as a normal XML comment.
</p>
<h2 id='arch-names'>Valid architecture names</h2>
<p id='archs'>The <b>arch</b> attribute is a value in the form "OS-CPU". The values come from the <b>uname</b> system call, but
there is some normalisation (e.g. because Windows doesn't report the same CPU names as Linux). Valid values for OS include:</p>
<ul>
<li>*</li>
<li>Cygwin (a Unix-compatibility layer for Windows)</li>
<li>Darwin (MacOSX, without the proprietary bits)</li>
<li>FreeBSD</li>
<li>Linux</li>
<li>MacOSX</li>
<li>Windows</li>
</ul>
Valid values for CPU include:
<ul>
<li>*</li>
<li>src</li>
<li>i386</li>
<li>i486</li>
<li>i586</li>
<li>i686</li>
<li>ppc</li>
<li>ppc64</li>
<li>x86_64</li>
<li>armv6l</li>
<li>armv7l</li>
</ul>
<h2 id='if-0install-version'>The if-0install-version attribute</h2>
<p>
To make it possible to use newer features in a feed without breaking older versions of 0install, the <b>if-0install-version</b> attribute may
be placed on any element to indicate that the element should only be processed by the specified versions of 0install. For example:
</p>
<pre>
<group>
<new-element if-0install-version='1.14..'/>
<fallback if-0install-version='..!1.14'/>
</group>
</pre>
<p>
In this example, 0install 1.14 and later will see <new-element>, while older versions see <fallback>. The syntax is as described in <a href='#constraints'>Constraints</a>.</p>
<p>However, 0install versions before 1.13 ignore this attribute and process all elements.
</p>
<h2 id='future'>Future plans</h2>
<ul>
<li>The extra meta-data elements need to be better specified.</li>
<li>As well as before and not-before, we should support after and not-after.</li>
<li>It should be possible to give a delta (binary patch) against a previous version, to make upgrading
quicker.</li>
<li>It should be possible to scope bindings. For example, when a DTP package requires a clipart package, the
clipart package should not be allowed to affect the DTP package's environment.</li>
</ul>
</html>
