Sugar Network/Recipe Specification

From Sugar Labs
< Sugar Network
Revision as of 17:58, 7 August 2010 by TimClicks (talk | contribs) (→‎[Activity]: '''icon''' = <icon-file-name-wo-suffix> => '''icon''' = <icon-file-name-without-suffix>)
Jump to navigation Jump to search


Spec file sections

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

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

[DEFAULT]

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

import = <filename> [; ...]

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

Common options

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

inherit = <section-name> [; ...]

Include options from another section. 

merge = <section-name> [; ...]

The same behaviour as inherit, but merges values for list type options, i.e., the final values will consist of the base-section values with addtional child-section values. List options are:

  • category
  • requires
  • binding
  • include
  • exclude
  • langs
  • packaged

[Component]

This is a required section (but see also presets). It describes the main recipe component. 

slug = <package-slug>

The string used as identifier in cases like 0install feed urls or native package names. Only lower alphabetic, numeric, "+" or "-" symbols are allowed. Slug value should be at least two characters long and start with an alphanumeric character. 

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

age = <age-number>

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

version = <version-number>

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

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. 

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. 

main = <path-to-exec-file>

The relative path of an executable inside the implementation that should be executed by default when the package is run. 

exec = <shell-command>

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

If a package has neither main nor exec, then it cannot be executed. This typically means that the package is for a library. 

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

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

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

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>

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

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

[Buid]

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

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 [Maintain] section. 

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

What dependencies should be present before building the package from sources, in addition to requires values from the [Component] sections. 

configure = <shell-command>

Shell command to configure sources before building, e.g, invoking the configure script in auto-tools-based projects. It is important to use predefined constants, at least %(PREFIX)s, during configuration to prepare valid Zero packages. 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 omited. 

install = <shell-command>

Shell command to place files that are ready for distribution into the %(DISTDIR)s directory.

[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, 0sugar 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.

Presets

Instead of component sections, special sections might be used. These sections extend the standard [Component] options, and might add special meaning to existing ones, see the description for each particular preset.

[Activity]

This preset should be present only for activities (or for applications that could be used also as Activities, e.g., GCompris is a regular application but could be launched in Sugar mode).

Preset uses the same options as [Component] with these additions: 

activity_version

Option is deprecated, version should be used 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-without-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 [Component] 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 group the activity. This is used to allow users to find activities more easily in the Journal, the Home view, etc.

[Application]

If this preset exists, an executable file will be created for native packages to launch main program or exec script. The executable file will be named by the slug option value and placed in the /usr/bin directory.

[Package]

If this section is present, the recipe should be used only for defining native packages on http://refinery.sugarlabs.org.

Package section might define native package names only for particular repository for current OBS project. In that case subnames should be used: 

[Package/<repository-name-glob>]

Options: 

package = <native-package-name> [; ...]

Name of a package (binary package, for binary-based distributions) associated with the recipe. It is important to use real package name, for virtual packages, use provides option. 

provides = <native-package-name> [; ...]

If package can be installed by virtual name. 

devel = <native-package-name> [; ...]

Name of devel package (for binary-based distributions) associated with the recipe. It is important to use real package name, for virtual packages, use devel-provides option. 

devel-provides = <native-package-name> [; ...]

If devel package can be installed by virtual name. 

distro = <distro-name>

Name of distribution that current section is defining package names for. Supported values (case-sensitive):

  • RPM for all RPM-based distributions,
  • Debian for all Debian-based distributions,
  • Gentoo for Gentoo distribution,
  • Slack for Slackware distribution,
  • Ports for FreeBSD Ports.

Predefined options

Options defined within [Build] section:

  • BUILDDIR where the build happens
  • SRCDIR path to directory with sources; for a custom (via 0compile) build, BUILDDIR and SRCDIR are different, while building on OBS, they are the same
  • DISTDIR 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

Also, during the 0sugar build command invocation, 0sugar exports the environment variables that should be used in exec options, for example, to implement a 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

Examples

Python activity

Python-based activity with standard Sugar Platform dependencies. 

[Activity]
slug      = 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
category  = Games;Education
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]
slug      = 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 with Python binding

[DEFAULT]
slug      = 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

[Component]
requires  = glib; gconf; libgee >= 0.5; gtk+ >= 2.12; pango >= 1.20; librsvg
binding   = LD_LIBRARY_PATH lib
            PKG_CONFIG_PATH lib/pkgconfig
            VAPIDIR share/vala/vapi
exclude   = python/**
arch      = any

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

[Build]
requires  = 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"
                  %(SRCDIR)s
make      = make
install   = make DESTDIR=%(DISTDIR)s install
Retrieved from "https://wiki.sugarlabs.org/index.php?title=Sugar_Network/Recipe_Specification&oldid=55574"