Difference between revisions of "Sugar Network/Recipe Specification"

Revision as of 09:12, 24 December 2010

The recipe specification file is an analog of scenario files in regular GNU/Linux distributions, like .spec files in RPM. It is the cornerstone of Doers environment, everything on Sugar project level depends on the recipe file. For activities, activity.info, an inherited recipe file name, is supported.

Recipe structure

Recipe file is an ini format configuration file that might consist of several sections:

Component sections:
- Main component section,
- Optional extra component sections.
Optional auxiliary sections:
- [Build],
- [Source].
Optional [DEFAULT] section with common options that are accessible from all other sections.

Recipe components

The sweet distribution contains one or several tarballs. Each tarball is being described by component section.

Main component

This is a required section with the name:

[type]

Regardless of the type, it contains followed options:

sweet = <identifier>

Required. An identifier of the package. Only lower alphabetic, numeric, "+", "-" or "." symbols are allowed. The sweet identifier should be at least two characters long and start with an alphanumeric character.

sweet is used in several cases:

in 0isntall feed url - http://sweets.sugarlabs.org/sweet,
in native package names generated from the recipe.

Important note: The sweet is not intended to be unique. That means that there may be several implementations for the same sweet in the field. They might be different versions of the package from the same developer, or even separate implementations from other developers.

name = <package-name>

Optional. Package name, in free form text. (It is equal to the sweet, by default.)

summary = <one-line-description>

Required. Short descriptive line.

description = <multi-line-description>

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

license = <license-name>

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

homepage = <url>

Required. Packaged project home page.

icon = <icon-file-name>

Optional. Path to package icon file starting from the path where the recipe file is located.

category = <category> [; ...]

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

version = <version-number>

Required. Current version of the package using 0install version format. If the age option was set, versioning is a bit different.

stability = <stability-level>

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

insecure
buggy
developer
testing
stable

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

Optional. List of dependencies that should exist in run-time before using the package. Note that requires from [Build] section are not auto included to this list (e.g., like RPM does).

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

Optional. Glob pattern for files to include to the package. Path related patterns will be processed starting from %(DISTDIR)s/%(PREFIX)s directory. By default, all files are assumed.

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

Optional. Like include option but for excluding files from the 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> [; ...]

Optional. 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).

arch = <arch>

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

all for noarch (by default)
any for binaries to use the current architecture

Extra components

The sweet distribution might be split into several tarballs that can be composed in different ways when the same sweet release contains several implementations with different tarballs compositions. Each component section (including main one) describes one of these tarballs.

Possible use cases:

To save storage space or bandwidth when some tarballs will contain any-arch data that are common for all platforms and another tarball will contain binaries for a particular platform.
TODO.

Extra component sections should be named:

[type/name]

Component types

Depending on purpose, component sections might be one of followed types.

[Activity]

This component section type should be present only in activities.

activity_version = <version>

Required. Option is deprecated, use version instead, but should be still present to not fail in current sugar. It will be useful to use expansion like %(version)s for this option.

bundle_id = <bundle-id>

Required. See activity.info file specification. Option is deprecated, use sweet instead, but should be still present to not fail in current sugar.

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

Required. 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 [Component] section should be used instead.

exec = <shell-command>

Required. Sugar will pass additional command line arguments to this command.

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

Optional. 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> [; ...]

Optional. Tags give more context in which to group the activity. This is used to allow users to find activities more easily in the Journal, the Home view, etc.

[Application]

Application to run out of Sugar Shell.

exec = <shell-command>

Required. The relative path of an executable command inside the implementation that should be executed by default when the package is run. Command can have optional arguments.

[Library]

age = <age-number>

Simple number that will be used as a major number for version, see versioning scheme for details.

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

The environment variables 0install should export to the process that uses this package. This makes sense only for multiple-activity-serving dependencies (like libraries), not for the activity itself.

Auxiliary sections

Sections that don't describe recipe components.

[Build]

This section is required if package needs additional work to prepare ready-to-use installation. To prepare valid Zero packages, it is important to use predefined constants for options that contain shell commands. All shell commands will be executed from %(BUILDDIR)s directory.

NOTE The commands in this section will be executed, not only in the developer's environment, but also in the user's, if a proper binary wasn't found; so move all development-related commands, like autogen.sh, to the [Source] section.

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

What dependencies should be present before building the package from sources. Note that requires from [Component] sections are not auto included to build-time dependencies.

configure = <shell-command>

Shell command to configure sources before building, e.g., invoking the configure script in auto-tools-based projects. If the source code does not require a configuration stage, this option could be omited.

make = <shell-command>

Shell command to make binaries from sources. If the source code does not require a making stage, this option could be omitted.

install = <shell-command>

Shell command to place files that are ready for distribution into the %(DESTDIR)s directory. If install is missing, the entire %(BUILDDIR)s (excepting temporary files) will be copied.

The rest of options make sense only while local building.

cleanup = <shell-command>

Make %(BUILDDIR)s ready to start new, clean, build. For example, for autotools based projects, it could be make distclean; ./autogen.sh.

implement = <shell-command>

An analog of install command that will be used, if present, instead of install while building the package in the local environment.

[Source]

How to create sources tarball. Options make sense only in the package-developer's environment.

url = <url>

While packaging 3rd-party applications, url to download sources tarball.

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

If source option is used, 3rd-party sources might be patched.

exec = <shell-command>

Execute external program to create sources tarball. Option might be used, e.g., to run make dist command. After executing exec shell command, sweets will pick up newly appeared tarball if it was created in package root directory.

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

If neither url nor exec options were used, all files will be bundled and these glob patterns might be used to concretize selection.

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

The packages that should be present before creating sources tarball. For example, if the exec command generates .c files from .vala, the vala dependency should be mentioned in the requires option.

Predefined options

Options defined within [Build] section:

BUILDDIR where the build happens, directory contains untarred sources bundle
DESTDIR temporary path to place installed files before bundling them
PREFIX should be used as installation prefix path, e.g., for ./configure --prefix
CFLAGS default gcc CFLAGS
CXXFLAGS default gcc CXXFLAGS

In sections that contain langs option:

LANG current language while building per language implementation

Examples

Python activity

Python-based activity with standard Sugar Platform dependencies.

[Activity]
sweet     = cartoon-builder
name      = Cartoon Builder
summary   = Create your own cell-animation sequences
license   = GPLv2+
homepage  = http://wiki.sugarlabs.org/go/Activities/Cartoon_Builder
icon      = activity/activity-cartoonbuilder.svg
version   = 11.4.9-pre3
stability = testing
exec      = sugar-activity activity.CartoonBuilderActivity

Python library

A python-based library that could be used as is, or as an activity dependency.

[Component]
sweet     = journal
summary   = Hight level library to create your own Journal-like activity
license   = GPLv3+
homepage  = http://wiki.sugarlabs.org/go/Activity_Team/Services/Journal
version   = 1
stability = testing
requires  = toolkit/python
binding   = PYTHONPATH

C-based library

[DEFAULT]
sweet     = polyol
summary   = Intermediate level GObject based libraries for Sugar
description = Polyol is a set of libraries that are written in Vala.
            Libraries are intended to provide high-level C API to basic Sugar
            features including Gtk based user interface. Applications that are
            linked against Polyol, interact with sugar processes
            (like shell, datastore, etc.) via DBus.
license   = LGPLv3+
homepage  = http://wiki.sugarlabs.org/go/Activity_Team/Polyol

age       = 0
version   = 1
stability = testing

depends   = glib; gconf; libgee >= 0.5; gtk+ >= 2.12; pango >= 1.20; librsvg

[Component]
requires  = %(depends)s
binding   = LD_LIBRARY_PATH lib
            PKG_CONFIG_PATH lib/pkgconfig
            VAPIDIR share/vala/vapi
exclude   = python/**
arch      = any

[Component/python]
requires  = %(sweet)s; python; pygtk; pycairo
binding   = PYTHONPATH python
include   = python/**
arch      = any

[Build]
requires  = %(depends)s; pkg-config; cmake; make; gcc-c
configure = cmake -D CMAKE_INSTALL_PREFIX=%(PREFIX)s
                  -D PYTHON_SITEDIR=%(PREFIX)s/python
                  -D COMPONENTS="collab;ds;env;gui;shell;toolkit"
                  -D BINDING=python
                  -D CMAKE_C_FLAGS:STRING="%(CFLAGS)s"
                  .
make      = make
install   = make DESTDIR=%(DESTDIR)s install