Sugar Network/Recipe Specification

0sugar.info file

The 0sugar.info specification file is an analog of scenario files in regular GNU/Linux distributions, like .spec files in RPM.

[DEFAULT]

Common options. Options from this section will be accessible from all other sections.

import

Import another spec file.

 import = <filename> [, ...]

[Package]

This is required section. It describes the main package.

inherit

Include options from another section.

 inherit = <section-name>

uid

The identity of this package, this field, for example, defines the name of 0install feed. Only lower alphabetic, numeric, "_" or "-" symbols are allowed.

 uid = <package-id>

name

Package name in free form, equals to uid by default.

 name = <package-name>

summary

Short descriptive line

 summary = <one-line-description>

description

Long descriptive text. To wrap long text, all lines after second, should start with spaces. This field is equal to summary by default.

description = <multy-line-description>

licence

License. Short licence names from Fedora naming scheme are welcome.

 license = <licence-name>

homepage

Packaged project home page.

 homepage = <url>

version

Current version of package.

stability

Stability level of current version. Values could be:

• insecure
• buggy
• developer
• testing
• stable

requires

List of dependencies that should exist before using this one. Option accepts also full 0install urls (could be useful to include non 0sugar dependencies).

 requires = <dependency> [(>=|<|=) <version>] [, ...]

slots

To specify dependency slots on using side:

 slots[<dependency>] = <dependency-version>, <dependency-verison> [, ...]

binding

What environment variables, 0install should export to process which uses this package.

 binding = [prepend|append|replace] <variable-name> [<insert-text-to-prepand-variable-value>] [, ...]

main

For applications, path to exec file from root directory that will be executed from 0launch command.

 main = <relative-path-to-exec-file>

exec

Instead of using execution program from main option, 0sugar can bundle a script to run arbitrary shell command:

 exec = <shell-command>

Also, 0sugar can bundle arbitrary shell scripts:

 exec[<script-name>] = <shell-command>

Last form could be useful when such scripts make sense only in 0install distribution e.g. to pass a path to already bundled command instead of using this command directly:

 binding = replace VALADIR, PATH
 exec[valac] = exec "$VALADIR"/bin/valac --vapidir "$VALADIR"/share/vala/vapi "$@"

include

Glob pattern for files to include to implementations.

include = <glob-pattern> [, ...]

By default all files will be included.

exclude

Glob pattern for files to exclude from implementations.

exclude = <glob-pattern> [, ...]

langs

A special form of include/exclude options that are intended to create separate, per locale, implementations.

 langs = <lang-name> [, ...]
 include[<lang-name>] = <glob-pattern> [, ...]
 exclude[<lang-name>] = <glob-pattern> [, ...]

If language is mentioned in langs list but doesn't have include[]/exclude[] options, include/exclude will be used.

prefix

Specify path from DISTDIR for include/exclude options.

 prefix = <path>

arch

Makes sense only for binary packages and can contain:

• * for noarch (by default)
• build for binaries to use current architecture

packaged

If service could be installed from native packaging system, use this option to let 0install know what packages names are on particular GNU/Linux distribution.

 packaged = <distro-name> <package-name> [, ...]

There are basic distro names

• rpm for all rpm based distros
• debian for deb based distros
• gentoo for ebuild based distros
• slack Slackware
• ports FreeBSD Ports

and also exact disto names to be more explicit

• fedora
• suse
• mandriva
• archlinux
• altlinux

See for more information in Wrap native packages HOWTO.

[Buid]

How to build binaries. If service contains binary implementations, this section should present to describe building process.

requires

What services should present before building this one from sources.

 <service-name> [(>=|<|=) <version>] [, ...]

exec

Command how to build binaries.

 exec = <shell-command>

Its value is a shell command, executed inside the build directory $BUILDDIR. It must compile the source in $SRCDIR, putting the final result (ready for distribution) in $DISTDIR. If this command starts to get complicated, you should move it to a script (either inside the main source archive or in a separate dependency) and just set this attribute to the command to run the script.

NOTE This command will be executed not only in service developer environment but also on user side if proper binary wasn't found, so do not use here any development related commands like autogen.sh

[Maintain]

Various service maintaining related settings.

source

Web link to the sources tarball, if parameter is absent, exec from this section will be used to generate tarball

 source = <web-url>

version

Optional version of the service, if it's absent, version should be passed via --relese 0sugar argument or will be parsed from source tarball filename.

 version = <version>

requires

What services should present before invoking 0sugar dist command i.e. only in maintainer environment not even while building service from sources on user side.

 requires = <dependency> [(>=|<|=) <version>] [, ...]

patch

Patch downloaded tarball, makes sense only if source parameter exists. Option exec should present as well to make new tarball.

 patch = <path-to-patch> [patch-level] [, ...]

exec

Command how to bundle service.

 exec = <shell-command>

Shell command, executed from service root directory. If this command starts to get complicated, you should move it to a script and just set this attribute to the command to run the script. By default 0sugar just bundle entirely service directory excluding temporary files. If source parameter exists in this section, command will be executed within extracted directory of downloaded tarball.

Glob patterns

A pattern could be two types:

• doesn't contain / symbol, will be applied only to file names (not names of sub-directories within parent directory)
• contains / symbol, will be applied to the full file path (relative to the root) thus could affect several directory levels

Only these pattern symbols are allowed:

• * matches everything except directory separator
• ? matches any single character except directory separator
• ** matches everything including directory separator

Sub services

By default service has only one feed - service.xml which will be composed using [Service] section. But service can have additional feeds as well, in that case service.info should contain additional sections (per sub feed) in form:

 [Service/<sub-name>]

Format of sub sections is identical to [Service] section. Sub feeds could make sense e.g. for having non-arch data feeds and pure binary feeds (to make per architecture implementations) or to have packaged option for runtime packages (Service) and for *dev* packages (Service/devel).

There is no need in keeping all [Service] options in every sub section, in that case it will be more useful to move common options to [DEFAULT] section.

Other services can mention sub feeds by format:

<service-name>/<sub-service-name>

Recipes

In some cases e.g. to save storage space or bandwidth, it is useful to split packaged application into several parts when some parts will be common. Most usual is having any-arch data and binaries sub-services i.e. the final service will depend on data sub-service (one implementation per application release) and sub-service with binaries (implementations per arch per application release). But it's not possible to use sub-services all time. Application could assume that data is placed to particular relative path from launched binaries, and if there is no way to set data locatation via environment bindings, sub-services are useless and recipes will help.

Use recipe option to declare service a recipe:

 [Service]
 recipe = <component-name> [, ...]

and declare sections that contain components:

 [<component-name>]
 ...

Only followed options make sense for component sections and cannot be used in recipe section, other options recipe component section will inherit from recipe section:

• langs
• arch
• include
• exclude
• main
• exec
• slots

The same component could a part of different recipes. In that case, different (sub)service implementations will contain the same component tarball.

The final [Service] implementation will contain tarball per component. All these tarballs will be unpacked to the same root directory. For example having followed lines and invoking 0sugar build on two platforms - x86 and x86_64 platforms, two (per arch) implementations will be created and they will use three tarballs - x86 and x86_64 tarballs from [binary] section and one common for both implementations [data] tarball.

[Service]
recipe = data, binary

[data]
include = share/*

[binary]
include = bin/*, lib/*
main = bin/launch
arch = build

Slots

Slots make sense only for binary services when they could be built against several compatibility ranges of their dependencies and these dependencies could be installed from native packages.

Assume that service requires cairo and source code uses cairo feature that appeared only in v1.8 but source code can fallback to previous cairo verisons too. If cairo can be installed from 0install feeds, there is no need in slots since service can declare "cairo >= 1.8" dependency and such cairo will be installed from 0install feeds. But if cairo could be installed from native packages there are no chances to know in advance what cairo version will present and service should have two implementations, one for cairo < 1.8 and one for cairo >= 1.8. In this case, slots will be useful.

To declare slots for used dependency, slots and appropriate requires options should be placed to [Service] section that uses dependency:

 requires = <dependency>
 slots[<dependency>] = <versions-range>

Option slots will declare compatibility ranges for particular dependency. Only one, closed from both sides, range could be used. For example in cairo case, it could be:

 1.0, 1.8, 2.0

1.0 (it could be 0.0 as well) version restrict ranges from the left and 2.0 (most likely v2.0 will be not backwards compatibility with v1.x) from the right, so only two ranges could be chosen, 1.0 >= x < 1.8, 1.8 >= x < 2.0. While building binaries for 0sugar build command, 0sugar will detect what current cairo version is (service is building/linking against), and will choose proper slot or fail otherwise.

Predefined options

In sections that contain langs option:

• LANG current language while building per language implementation

Also while 0sugar build command invocation, 0sugar exports environment variables that could be used in exec options for example to implement conditional build.

• ZSUGAR_<argument-in-upper-case> map 0sugar long command line arguments
• SECTION_<section-name-in-upper-case> for every spec file section that will be processed