5,705
edits
Changes
Sugar Network/Recipe Specification (view source)
Revision as of 13:05, 6 June 2010
, 13:05, 6 June 2010no edit summary
</noinclude>
</noinclude>
== Service.info file ==
The ''service.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> [, ...]
=== [Service] ===
This is required section. It describes the main service feed - service.xml (service can contain optional sub feeds, see below).
'''inherit'''
Include options from another section.
inherit = <section-name>
'''uid'''
The identity of this service, this field defines the name of feed's root directory on the server http://services.sugarlabs.org/ as well. Only lower alphabetic, numeric, "_" or "-" symbols are allowed.
uid = <service-id>
'''name'''
Service name in free form, equals to uid by default.
name = <service-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'''
Service license. Short licence names from [http://fedoraproject.org/wiki/Licensing Fedora naming scheme] are welcome.
license = <licence-name>
'''homepage'''
Packaged project home page.
homepage = <url>
'''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|slots]] of using side:
slots[<dependency>] = <dependency-version>, <dependency-verison> [, ...]
'''binding'''
What environment variables, 0install should export to process which uses this service.
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'''
Files to include to implementations.
include = <glob-mask> [, ...]
A glob-mask could be two types:
* mask doesn't contain '/' symbol, will be applied only to file names (not names of sub-directories within parent directory)
* mask contains '/' symbol, will be applied to the full file path (relative to the root) thus could affect several files
By default all files will be included.
'''exclude'''
Files to exclude from implementations. Uses the same format like ''include'' parameter.
exclude = <glob-mask> [, ...]
'''langs'''
A special form of ''include''/''exclude'' options that are intended to create separate, per locale, implementations.
langs = <lang-name> [, ...]
include[<lang-name>] = <glob-mask> [, ...]
exclude[<lang-name>] = <glob-mask> [, ...]
If language is mentioned in ''langs'' list but doesn't have ''include''/''exclude'' options, regular rule is assumed i.e. include all files by default.
'''prefix'''
Specify path from ''DISTDIR'' for ''include''/''exclude'' options.
prefix = <path>
'''arch'''
Makes sense only for binary services 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 [[Documentation Team/Services/Wrap native packages HOWTO|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.
== 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-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:
[[Service:]<component-name>]
...
The final ''[Service]'' implementation will contain tarball per component. All these tarballs will be unpacked to the same root directory.
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
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
== Predefined options ==
Useful options that could be used in service.info file.
* ''CFLAGS'' default flags for gcc C compiler
* ''CXXFLAGS'' default flags for gcc C++ compiler
In sections that contain ''langs'' option:
* ''LANG'' current language while building per language implementation