Sugar Labs

Sugar Network/Recipe Specification

< Sugar Network
Revision as of 10:57, 29 October 2011 by Alsroot (talk | contribs) (→‎Common options)

Read the Packaging Guide to learn how to write and use recipe files.

Use case sections

A recipe should contain at least one use case section to describe how the sweet might be used.

Use case sections are named: 

[use-case-type[:sub-name]]

Where use-case-type is one of the following sub sections and sub-name is an optional identifier used if there are more than one section of the same type.

Regardless of the type, a use case section (or one of them) should contain the following options.

Common options

implement = <sweet> [; ...]

Required. The list of interfaces that the current project is implementing. 

associate = <sweet> [; ...]

Optional. The list of interfaces whose implementations might be considered as additional implementations for the current one. 

name = <name>

Optional. Free-form name. (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 starting from the second, should start with spaces. This field is equal to summary by default. 

license = <license-name> [; ...]

Required. Short license names. The licenses should conform with the Activity Library licensing policy. 

homepage = <url>

Required. Sweet project home page. 

icon = <icon-file-name>

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

category = <category> [; ...]

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

tags = <tag> [; ...]

Optional. Tags give more context by which to group the sweet. This is done to allow users to find sweets more easily. 

version = <version-number>

Required. Current version of the sweet using 0install version format. 

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

Optional. List of dependencies that should exist at run-time before launching the sweet. 

suggests = <dependency> [; ...]

Optional. List of dependencies that will be demanded to be present at run-time only if it was explicitly required from a user.

[Activity]

This section type should be present only in activities. 

activity_version = <version>

Deprecated (in sweets case), use version instead. Should be still present only to run the activity in non-sweets environment. It will be useful to use expansion like %(version)s for this option. 

bundle_id = <bundle-id>

Deprecated. Should be still present only to run the activity in non-sweets environment. See activity.info file specification. 

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

Required. Behaviour from activity.info is supported (value should not have a .svg suffix, and the icon file can be found only in the activity subdirectory) and, while deprecated, it needs to be used to not break backwards compatibility. For the remaining cases, the regular icon behaviour 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 that can open a certain Journal object.

[Application]

Application to run outside 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 sweet is run. Command can have optional arguments.

[Library]

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

Required. The environment variables 0install should export to the process that uses this sweet.

[Package]

This is a special section that does not relate to sweets directly and is mentioned here only for recipe specification completeness. Using this section turns a recipe to some kind of meta-distribution spec file on OBS. The important things that need to be kept in mind in this case are these:

  • it is very limited by design in comparison with regular GNU/Linux distribution spec files;
  • there are not any intentions to follow this meta-distribution method;
  • the primary distribution method for sweets is using 0install, i.e., not using the [Package] section, thus, native packages, at all;
  • this section was introduced only for cases when having native packages makes sense, e.g., for Live Sugar distributions or LTSP.

In addition to the already existing predefined options, there are several new defines that make sense only for this section's packages:

  • EXEC_PREFIX;
  • BINDIR;
  • SBINDIR;
  • SYSCONFDIR;
  • DATADIR;
  • INCLUDEDIR;
  • LIBDIR;
  • LIBEXECDIR;
  • LOCALSTATEDIR;
  • MANDIR;
  • INFODIR;
  • PYTHONSITEDIR, equal to Python's PYTHONPATH environment variable;
  • LUACPATHDIR, equal to Lua's LUA_CPATH environment variable;
  • LUAPATHDIR, equal to Lua's LUA_PATH environment variable;
  • LUAINCDIR, path to a directory with Lua's C header file;
source = <filename>

Required. The filename with sources bundle. 

patches = <patch-filename> [patch-level] [; ...]

Optional. The list of patches that need to be applied before building. 

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

Optional. The list of native packages, i.e., names from a particular GNU/Linux distribution, that conflict with the sweet based package and cannot be installed at the same time. 

install = <shell-command>

Optional. The command that will be executed after installing the binary package composed from this recipe. 

uninstall = <shell-command>

Optional. The command that will be executed after uninstalling the binary package composed from this recipe.

Archive sections

An archive section describes the tarball that will contain the sweet implementation.

If there are not any archive sections, the sweet implementation consists of only one archive that includes the entire %(DESTDIR)s directory (excluding temporary files). At the same time, the sweet implementation might be split into several archives.

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.

All archive sections are named: 

[Archive[:sub-name]]

And contain the following options: 

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

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

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

Optional. Like the include option, but used for excluding files from the archive. In addition, 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, archives. If a language is mentioned in the langs list, but doesn't have any include[]/exclude[] options, include/exclude will be used (in that case, using the special LANG variable makes sense). 

arch = <arch>

Optional. Makes sense only for binary archives, and can contain:

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

Auxiliary sections

Sections that don't describe recipe components.

[Build]

This section is required if the sweet needs additional work in order to prepare a ready-to-use installation. To prepare valid sweets, it is important to use predefined constants for options that contain shell commands. All shell commands will be executed from the %(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> [; ...]

Optional. This defines what dependencies should be present before building the sweet from sources. Note that requires from [Component] sections are not auto included in the build-time dependencies. 

clean = <shell-command>

Optional. Cleanup build environment before running configure command. 

configure = <shell-command>

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

make = <shell-command>

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

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

[Source]

exec = <shell-command>

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

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

Optional. If the exec option was not used, all files will be bundled and these glob patterns might be used to reify the selection. 

requires = <dependency> [; ...]

Optional. The dependencies 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 un-tarred sources bundle. This variable can be used in binding options as well. During the local build, it will point environment variables to the root of sources directory.
  • 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 a langs option:

  • LANG current language while building per language implementation
Retrieved from "https://wiki.sugarlabs.org/index.php?title=Sugar_Network/Recipe_Specification&oldid=70507"