Sugar Network/Recipe Specification

From Sugar Labs
Jump to navigation Jump to search


0sugar.info file

The 0sugar.info specification file is an analog of scenario files in regular GNU/Linux distributions, like .spec files in RPM. It is corner stone of Zero Sugar workflows, everything is depending on 0sugar.info spec file.

For activities, activity.info deprecated spec file name is supported.

[DEFAULT]

Common options. Options from this section will be accessible from all other sections. It could be useful to store options that are common for all sections. 

import = <filename> [; ...]

Import another spec file. Makes sense only within [DEFAULT] section itself.

Common options

Options that are common for all sections except [DEFAULT]. 

inherit = <section-name>

Include options from another section.

[Package]

This is required section (but could be replaced by [Activity]). It describes the main package. 

slug = <package-slug>

The string used as identifier in cases like 0isntall feed urls or native package names. Only lower alphabetic, numeric, "_", "+" or "-" symbols are allowed. 

name = <package-name>

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

summary = <one-line-description>

Short descriptive line. 

description = <multi-line-description>

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

license = <licence-name>

Package license. Short licence names from Fedora naming scheme are welcome. 

homepage = <url>

Packaged project home page. 

icon = <icon-file-name>

Relative (from Zero Sugar based project) path to icon file. 

category = <category> [; ...]

A classification for the package using values defined by freedesktop.org menu specification. 

version = <version-number>

Current version of the package using 0install version format. 

stability = <stability-level>

Stability level of current version. Values conform to 0install stability levels and could be:

  • insecure
  • buggy
  • developer
  • testing
  • stable
requires = <dependency> [(=|>=|<) <version>] [; ...]

List of dependencies that should exist before using the package. Dependency names could be:

  • name of other package within Zero Sugar
  • regular 0install feed url
slots[<dependency>] = <first-dependency-version> [; ...], <last-dependency-verison>

To specify dependency slots.. 

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

What environment variables, 0install should export to process which uses this package. Makes sense only for various activity dependencies (like libraries), not for activity itself. 

main = <path-to-exec-file>

For applications, relative (from Zero Sugar based project) path to exec file. Doesn't make sense for packages like libraries. 

exec = <shell-command>

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

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

Also, 0sugar can bundle arbitrary shell scripts. It could be useful for 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> [; ...]

Glob pattern for files to include to package. By default, all files are assumed. 

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

Glob pattern for files to exclude from package. In additional, various temporary files will be excluded like .bak or .pyc. 

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

A special form of include/exclude options that are intended to create separate, per locale, (sub)packages. If language is mentioned in langs list but doesn't have include[]/exclude[] options, include/exclude will be used (in that case, using special LANG variable makes sense). 

prefix = <path>

Could be used in conjunction with include/exclude to specify new root path within directory created by install command. 

arch = <arch>

Makes sense only for binary (sub)packages and can contain:

  • * for noarch (by default)
  • build for binaries to use current architecture
packaged = <distro-name> <package-name> [; ...]

If package could be installed from official GNU/Linux distributions repository (i.e. not from packages generated from 0sugar.info spec file on OBS), use this option to let 0install know what packages names are on particular GNU/Linux distribution.

Distribution names could be:

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

[Activity]

This section should present only for activities (or for applications that could be used also as activities e.g. GCompris is regular application but could be launched in sugar mode).

Section uses the same options [Package] has with additions: 

activity_version

Option is deprecated, version should be instead instead. 

bundle_id = <bundle-id>

See activity.info file specification. Option will be deprecated after implementing 0sugar in glucose and switching to identifying activities by urls (like 0install feeds). 

icon = <icon-file-name-wo-suffix>

Behaviour from activity.info is supported (value should not have ".svg" suffix and icon file could be found only in activity subdirectory) but deprecated. Regular icon behaviour from [Package] section should be used instead. 

exec = <shell-command>

Sugar will pass additional command line arguments to this command. 

mime_types = <mime-type> [; ...]

List of mime types supported by the activity. It's used when opening a file from the web or to present to the user a list of activities which can open a certain journal object. 

tags = <tag> [; ...]

Tags give more context in which to place the activity. This is used to allow users to find activities more easily in the journal, the home view, etc.

[Source]

Section makes sense only while packaging 3rd party application. 

source = <url>

Url to download sources tarball. 

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

Patch downloaded tarball.

[Buid]

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

requires = <dependency-name> [(=|>=|<) <version>] [; ...]

What packages should present before building this one from sources. Similar to requires option from [Package]. 

build = <shell-command>

How to build binaries.

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

install = <shell-command>

How to install package.

[Maintain]

Various options that make sense only on package developer side. 

exec = <shell-command>

How to bundle package. By default 0sugar just bundles entirely root directory excluding temporary files. 

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

What packages should present before invoking exec command. For example if exec command generates .c files from .vala, vala dependency should be mentioned in requires option.

Glob patterns

A pattern could be two types:

  • doesn't contain / or ** substrings, will be applied only to file names (not names of sub-directories within parent directory)
  • contains / or ** substring, 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 packages

By default package 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

  • BUILDDIR where build happens
  • SRCDIR path to directory with sources; for custom (via 0compile) build, BUILDDIR and SRCDIR are different, while building on OBS, the same
  • DISTDIR temporary path to place installed files before bundling them
  • PREFIX prefix path for installed files e.g. /usr
  • DATADIR data files directory e.g. /usr/share
  • DOCDIR doc files directory e.g. /usr/share/doc
  • BINDIR bin files directory e.g. /usr/bin
  • INCLUDEDIR include files directory e.g. /usr/include
  • LIBDIR lib files directory e.g. /usr/lib
  • PYTHON_SITEDIR python files directory e.g. /usr/lib/python2.6/site-packages
  • CFLAGS default gcc CFLAGS
  • CXXFLAGS default gcc CXXFLAGS

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
Retrieved from "https://wiki.sugarlabs.org/index.php?title=Sugar_Network/Recipe_Specification&oldid=53958"