Difference between revisions of "Sugar Network/Recipe Specification"

From Sugar Labs
Jump to navigation Jump to search
 
(123 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
{{TOCright}}
+
== Summary ==
−
[[Category:Zero Sugar]]
 
  
−
== Spec file sections ==
+
The document describes software specification files format which is a superset on top of the Sugar [[Development_Team/Almanac/Activity_Bundles|activity bundles]] specification. This format is backwards compatible with [[Development_Team/Almanac/Activity_Bundles#.info_file_format|activity.info]] files to make sure that software starts well from the regular Sugar Shell. But the major purpose of introducing new format is supporting software hosted on the [[Sugar Network]]. In particular, new format assumes the following functionality:
  
−
The sweets.recipe 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 sweets.recipe spec file.
+
* Support binary based software;
 +
* Provide information about software dependencies;
 +
* Introduce stability levels to make it possible (for interested in people) to run development versions using the same, like for stable releases, distribution channel;
 +
* Distribute not only Sugar activities, e.g., software libraries;
 +
* Include all required information to make it possible to reuse the same spec file on different software evolution phases, like, making sources tarball, building binaries on Sugar Labs [[Platform_Team/Open_Build_Service|instance]] of the [http://openbuildservice.org/ Open Build Service], executing.
  
−
For activities, activity.info, an inherited recipe file name, is supported.
+
The format is partially based on the [http://0install.net/ Zero Install] [http://0install.net/interface-spec.html specification] since implementation code reuses Zero Install library in order to launch software on users side.
  
−
=== [DEFAULT] ===
+
== Spec file locations ==
  
−
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.
+
There are two possible spec file locations (staring from the top directory of a distribution bundle):
  
−
'''import''' = <filename> [; ...]
+
* {{Code|/activity/activity.info}}<br>for Sugar activities to make them capable to be launched from the regular Sugar Shell;
 +
* {{Code|/sweets.recipe}}<br>in the rest of cases.
  
−
Import another recipe file. Makes sense only within the [DEFAULT] section itself.
+
== Configuration sections ==
 +
 
 +
As ''activity.info'' files, new format is based on [[wikipedia:INI_file|INI files]] and should contain at least one of the following sections.
  
 
=== Common options ===
 
=== Common options ===
  
−
Options that are common for all sections except [DEFAULT].
+
Regardless of the software type, a recipe section (or one of them) should contain the following options.
  
−
'''inherit''' = <section-name> [; ...]
+
<div id="context"></div>
  
−
Include options from another section.
+
'''context''' = ''GUID''
  
−
'''merge''' = <section-name> [; ...]
+
Required (but see the [[#.5BActivity.5D|[Activity]]] section). The value which uniquely identifies a software project this particular version implements. This is a Sugar Network [[Platform_Team/Sugar_Network/Objects_model|Context]] GUID.
  
−
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:
+
<div id="name"></div>
  
−
* category
+
'''name''' = ''NAME''
−
* requires
 
−
* binding
 
−
* include
 
−
* exclude
 
−
* langs
 
−
* packaged
 
  
−
=== [Component] ===
+
Optional. Free-form name. (It is equal to the ''implemented'', by default.)
  
−
This is a required section (but see also [[#Presets|presets]]). It describes the main recipe component.
+
<div id="summary"></div>
  
−
  '''sweet''' = <name>
+
  '''summary''' = ''ONE_LINE_TEXT''
  
−
A short name of the package. Only lower alphabetic, numeric, "+"  or "-" symbols are allowed. Sweet value should be at least two characters long and start with an alphanumeric character.
+
Required. Short descriptive line.
  
−
''sweet'' is used in several cases:
+
<div id="description"></div>
  
−
* OBS package name should be equal to ''sweet'' value,
+
'''description''' = ''MULTI_LINE_TEXT''
−
* in 0isntall feed url - <code><nowiki>http</nowiki>://sweets.sugarlabs.org/''obs-project''/''sweet''</code>,
 
−
* in native package names generated from this recipe - <code>sugar-''sweet''</code>.
 
  
−
'''origin''' = <colon-separated-obs-project-path>[/<origin-sweet>]
+
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.
  
−
If current package is a different implementation of another one, ''origin'' should point to original OBS project. Also if current ''sweet'' is different, original should be mentioned.
+
<div id="license"></div>
  
−
  '''name''' = <package-name>
+
  '''license''' = ''LICENSE'' [; ...]
  
−
Package name, in free form, equals to ''obs-package'', by default.
+
Required. Short license names. The licenses should conform with the [[Activity Library]] licensing [[Activity_Library/Editors/Policy/Licensing|policy]].
  
−
'''summary''' = <one-line-description>
+
<div id="homepage"></div>
  
−
Short descriptive line.
+
'''homepage''' = ''URL''
  
−
'''description''' = <multi-line-description>
+
Required. Software project home page.
  
−
Long descriptive text. To wrap long text, all lines after the second, should start with spaces. This field is equal to ''summary'' by default.
+
<div id="icon"></div>
  
−
  '''license''' = <licence-name>
+
  '''icon''' = ''FILENAME''
  
−
Package license. Short licence names from [http://fedoraproject.org/wiki/Licensing Fedora naming scheme] are welcome.
+
Optional (but see the [[#.5BActivity.5D|[Activity]]] section). Path to the icon file starting from the path where the recipe file is located.
  
−
'''homepage''' = <url>
+
<div id="tags"></div>
  
−
Packaged project home page.
+
'''tags''' = ''TAG'' [; ...]
  
−
'''icon''' = <icon-file-name>
+
Optional. Tags give more context by which to group the software. This is done to allow users to make search more easily.
  
−
Relative (from Zero Sugar based project) path to icon file.
+
<div id="version"></div>
  
−
  '''category''' = <category> [; ...]
+
  '''version''' = ''VERSION''
  
−
A classification for the package using values defined by [http://standards.freedesktop.org/menu-spec/latest/apa.html freedesktop.org menu specification].
+
Required. Current version of the software using [[#Version_numbers|special notation]]. Note, to make Sugar activity bundles compatible with pristine Sugar, use a limited format subset supported by the Sugar Shell.
  
−
'''age''' = <age-number>
+
<div id="stability"></div>
  
−
Simple number that will be used as a major number for ''version'', see [[Activity Team/Zero Sugar/Packaging Guide#Versioning|versioning scheme]] for details.
+
'''stability''' = ''LEVEL''
  
−
'''version''' = <version-number>
+
Required. Stability level of the current version. Values conform to the [[#Software_stability_levels|below list]].
  
−
Current version of the package using [http://0install.net/interface-spec.html#id4016582 0install version format]. If the ''age'' option was set, versioning is a bit [[Activity Team/Zero Sugar/Packaging Guide#Versioning|different]].
+
<div id="requires"></div>
  
−
  '''stability''' = <stability-level>
+
  '''requires''' = ''DEPENDENCY'' [; ...]
  
−
Stability level of current version. Values conform to [http://0install.net/interface-spec.html#id4016716 0install stability levels] and could be:
+
Optional. List of [[#Dependencies|dependencies]] that should exist at run-time before launching the release.
−
* insecure
 
−
* buggy
 
−
* developer
 
−
* testing
 
−
* stable
 
  
−
'''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
+
=== [Activity] ===
  
−
List of [[Activity Team/Zero Sugar/Packaging Guide#Package_names|dependencies]] that should exist before using the package.
+
This section type should be present only in Sugar activities.
  
−
'''binding''' = [prepend|append|replace] <variable-name> [<insert-text-to-prepend-variable-value>] [; ...]
+
<div id="activity_version"></div>
  
−
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.
+
'''activity_version''' = ''VERSION''
  
−
'''main''' = <path-to-exec-file>
+
Required. An alias of the ''version'' option.
  
−
The relative path of an executable inside the implementation that should be executed by default when the package is run.
+
<div id="bundle_id"></div>
  
−
  '''exec''' = <shell-command>
+
  '''bundle_id''' = ''BUNDLE_ID''
  
−
Instead of using an executable program from the ''main'' option, {{Code|sweets}} can bundle a script to run an arbitrary shell command.
+
Required. An alias of the ''context'' option.
  
−
If a package has neither ''main'' nor ''exec'', then it cannot be executed. This typically means that the package is for a library.
+
<div id="icon"></div>
  
−
  '''include''' = <glob-pattern> [; ...]
+
  '''icon''' = ''FILENAME_WITHOUT_SUFFIX''
  
−
[[Activity Team/Zero Sugar/Packaging Guide#Glob patterns|Glob pattern]] for files to include to the package. Path related patterns will be processed starting from [[#Predefined_options|%(DISTDIR)s/%(PREFIX)s]] directory. By default, all files are assumed.
+
Required. Behaviour from {{Code|activity.info}} is supported (value should not have a {{Code|.svg}} suffix, and the icon file can be found only in the {{Code|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.
  
−
'''exclude''' = <glob-pattern> [; ...]
+
<div id="activity_exec"></div>
  
−
Like ''include'' option but for excluding files from the package. In additional, various temporary files will be excluded like ''.bak'' or ''.pyc''.
+
'''exec''' = ''SHELL_COMMAND''
  
−
'''langs''' = <lang-name> [; ...]
+
Required. Sugar will pass additional [[Development_Team/Low-level_Activity_API#Command_Line_Arguments| command line arguments]] to this command.
−
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 [[#Predefined_options|LANG]] variable makes sense).
+
<div id="mime_types"></div>
  
−
  '''arch''' = <arch>
+
  '''mime_types''' = ''MIME_TYPE'' [; ...]
  
−
Makes sense only for binary (sub)packages, and can contain:
+
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.
−
* ''all'' for noarch (by default)
 
−
* ''any'' for binaries to use the current architecture
 
  
−
=== [Buid] ===
+
<!--
 +
=== [Application] ===
  
−
How to build binaries. If package contains binary implementations, this section should be present to describe the building process.
+
Application to run outside of Sugar Shell.
  
−
'''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.
+
'''exec''' = ''SHELL_COMMAND''
  
−
'''requires''' = <dependency-name> [(=|>=|<) <version>] [; ...]
+
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.
  
−
What [[Activity Team/Zero Sugar/Packaging Guide#Package_names|dependencies]] should be present before building the package from sources, in addition to ''requires'' values from the ''[Component]'' sections.
+
=== [Library] ===
  
−
  '''configure''' = <shell-command>
+
  '''binding''' = [prepend|append|replace] <variable-name> [<insert-text-to-prepend-variable-value>] [; ...]
  
−
Shell command to configure sources before building, e.g, invoking the ''configure'' script in auto-tools-based projects. It is important to use [[#Predefined_options|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.
+
Required. The environment variables 0install should export to the process that uses this sweet.
 +
-->
 +
=== [Archive] ===
  
−
'''make''' = <shell-command>
+
This configuration section makes sense only while building binary distribution bundles from the sources. The section is optional for spec files that describe software assumed to be launched as-is, e.g., ''.xo'' bundles.
  
−
Shell command to make binaries from sources. If the source code does not require a making stage, this option could be omited.
+
Each ''[Archive]'' section describes one particular binary bundle. There are might be several sections to define binaries for different cases:
  
−
'''install''' = <shell-command>
+
* To save storage space or bandwidth when some bundles will contain any-arch data that are common for all platforms, and another bundle will contain binaries for a particular platform;
 +
* Per language bundles, e.g., for media content.
  
−
Shell command to place files that are ready for distribution into the ''%(DISTDIR)s'' directory.
+
All archive sections are named:
  
−
=== [Source] ===
+
Archive[:''SUBNAME'']
  
−
How to create sources tarball. Options make sense only in the package-developer's environment.
+
And contain the following options:
  
−
'''url''' = <url>
+
<div id="archive-include"></div>
  
−
While packaging 3rd-party applications, url to download sources tarball.
+
'''include''' = ''GLOB'' [; ...]
  
−
'''patch''' = <path-to-patch> [patch-level] [; ...]
+
Optional. [[#Glob_patterns|Glob pattern]] for files to include in the archive. By default, all files are assumed.
  
−
If ''source'' option is used, 3rd-party sources might be patched.
+
<div id="archive-exclude"></div>
  
−
  '''exec''' = <shell-command>
+
  '''exclude''' = ''GLOB'' [; ...]
  
−
Execute external program to create sources tarball. Option might be used, e.g., to run {{Code|make dist}} command. After executing ''exec'' shell command, {{Code|sweets}} will pick up newly appeared tarball if it was created in package root directory.
+
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''.
 +
<!-- Not yet implemented
 +
'''langs''' = <lang-name> [; ...]
 +
include[<lang-name>] = <glob-pattern> [; ...]
 +
exclude[<lang-name>] = <glob-pattern> [; ...]
  
−
'''include''' = <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 [[#Predefined_constants|LANG]] constant makes sense).-->
−
'''exclude''' = <glob-pattern> [; ...]
 
  
−
If neither ''url'' nor ''exec'' options were used, all files will be bundled and these [[Activity Team/Zero Sugar/Packaging Guide#Glob patterns|glob patterns]] might be used to concretize selection.
+
<div id="arch"></div>
  
−
  '''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
+
  '''arch''' = ''ARCH''
  
−
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.
+
Optional. Makes sense only for binary archives, and can contain:
  
−
== Presets ==
+
* ''all'' for noarch (by default),
 +
* ''any'' for binaries to use the current architecture.
  
−
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.
+
=== [Build] ===
  
−
=== [Activity] ===
+
This section is required if software needs additional work in order to prepare a ready-to-use installation. It is important to use [[#Predefined_constants|predefined constants]] for options that contain shell commands. All shell commands will be executed from the {{Code|%(BUILDDIR)s}} directory.
  
−
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).  
+
'''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 {{Code|autogen.sh}}, to the ''[Source]'' section.
  
−
Preset uses the same options as ''[Component]'' with these additions:
+
<div id="build-requires"></div>
  
−
  '''activity_version'''
+
  '''requires''' = ''DEPENDENCY'' [; ...]
  
−
Option is deprecated, ''version'' should be used instead.
+
Optional. This defines what [[#Dependencies|dependencies]] should be present before building the software from sources. Note that common ''requires'' option values are not auto included in the build-time dependencies.
  
−
'''bundle_id''' = <bundle-id>
+
<div id="clean"></div>
  
−
See [[Development_Team/Almanac/Activity_Bundles#.info_file_format|activity.info file specification]]. Option will be deprecated after implementing Zero Sugar in glucose and switching to identifying activities by urls (like 0install feeds).
+
'''clean''' = ''SHELL_COMMAND''
  
−
'''icon''' = <icon-file-name-without-suffix>
+
Optional. Cleanup build environment before running ''configure'' command.
  
−
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.
+
<div id="configure"></div>
  
−
  '''exec''' = <shell-command>
+
  '''configure''' = ''SHELL_COMMAND''
  
−
Sugar will pass additional [[Development_Team/Low-level_Activity_API#Command_Line_Arguments| command line arguments]] to this 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.
  
−
'''mime_types''' = <mime-type> [; ...]
+
<div id="build-make"></div>
  
−
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.
+
'''make''' = ''SHELL_COMMAND''
  
−
'''tags''' = <tag> [; ...]
+
Optional. Shell command to make binaries from sources. If the source code does not require a making stage, this option could be omitted.
  
−
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.
+
<div id="install"></div>
  
−
=== [Application] ===
+
'''install''' = ''SHELL_COMMAND''
  
−
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.
+
Required. Shell command to place files that are ready for distribution into the {{Code|%(DESTDIR)s}} directory. If ''install'' is missing, the entire {{Code|%(BUILDDIR)s}} (excepting temporary files) will be copied.
  
−
=== [Package] ===
+
=== [Source] ===
  
−
If this section is present, the recipe should be used only for defining native packages on http://refinery.sugarlabs.org.
+
The section makes sense only while building sources bundles and is a replacement of former ''MANIFEST'' file in Sugar activity bundles.
  
−
'''package''' = <native-package-name>
+
<div id="source-exec"></div>
  
−
Name of a package (binary package, for binary-based distributions) associated with the recipe. Option value might be a name of virtual package (a name that original package provides).
+
'''exec''' = ''SHELL_COMMAND''
  
−
'''devel''' = <native-package-name>
+
Optional. Execute an external program to create sources tarball. Option might be used, e.g., to run {{Code|make dist}} command.
  
−
Name of devel package (for binary-based distributions) associated with the recipe. Option value might be a name of virtual package (a name that original package provides).
+
<div id="source-include"></div>
  
−
  '''type''' = <package-type>
+
  '''include''' = ''GLOB'' [; ...]
 +
'''exclude''' = ''GLOB'' [; ...]
  
−
Packaging system type that describing package belongs to. Should be used only for non-rpm/deb packages. Supported values (case-sensitive):
+
Optional. If the ''exec'' option was not used, all files will be bundled and these [[#Glob_patterns|glob patterns]] might be used to reify the selection.
  
−
* ''Gentoo'' for Gentoo distribution,
+
<div id="source-requires"></div>
−
* ''Slack'' for Slackware distribution,
 
−
* ''Ports'' for FreeBSD Ports.
 
  
−
  '''repo''' = <glob-mask> [; ...]
+
  '''requires''' = ''DEPENDENCY'' [; ...]
  
−
Case insensitive glob masks of repository names in OBS project that current recipe belongs to. If option is absent, aliasing will be applied to all repositories.
+
Optional. The [[#Dependencies|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.
  
−
Aliasing might be different for different repositories, e.g., if repositories come from several GNU/Linux distributions. In that case per-repository Package sections (with setting ''repo'' option) should be used:
+
=== Predefined constants ===
  
−
[Package/<arbitrary-unique-name>]
+
Constants defined within the ''[Build]'' section:
  
−
== Predefined options ==
+
* ''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
−
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 {{Code|./configure --prefix}}
 
* ''PREFIX'' should be used as installation prefix path, e.g., for {{Code|./configure --prefix}}
 
* ''CFLAGS'' default gcc CFLAGS
 
* ''CFLAGS'' default gcc CFLAGS
 
* ''CXXFLAGS'' default gcc CXXFLAGS
 
* ''CXXFLAGS'' default gcc CXXFLAGS
  
−
In sections that contain ''langs'' option:
+
In sections that contain a ''langs'' option:
  
 
* ''LANG'' current language while building per language implementation
 
* ''LANG'' current language while building per language implementation
  
−
== Examples ==
+
== Version numbers ==
 +
 
 +
A version number string has the following form:
 +
 
 +
Version := DottedList ("-" Modifier? DottedList?)*
 +
DottedList := (Integer ("." Integer)*)
 +
Modifier := "pre" | "rc" | "post"
 +
 
 +
Numerically, the modifiers come in the order "-pre" (pre-release), "-rc" (release candidate), "-" (no modifier name), "-post" (post-release or patch level). Versions are ordered like this:
 +
 
 +
0.1
 +
1
 +
1.0
 +
1.2-pre
 +
1.2-pre1
 +
1.2-rc1
 +
1.2
 +
1.2-0
 +
1.2-post
 +
1.2-post1-pre
 +
1.2-post1
 +
1.2.1-pre
 +
1.2.1.4
 +
1.2.2
 +
1.2.10
 +
3
 +
 
 +
== Software stability levels ==
 +
 
 +
The spec file also gives a stability rating for each implementation. The following levels are allowed (must be lowercase in the feed files):
 +
 
 +
* ''stable'',
 +
* ''testing'',
 +
* ''developer'',
 +
* ''buggy'',
 +
* ''insecure''.
 +
 
 +
Stability ratings are expected to change over time. When any new release is made, its stability should be set to testing. Users who have selected Help test new versions will then start using it. Other users will continue with the previous stable release. After a while (days, weeks or months, depending on the project) with no serious problems found, the implementation's stability can be changed to stable so that everyone will use it.
 +
 
 +
If problems are found, it can instead be marked as ''buggy'', or ''insecure'' to avoid selecting these versions while launching on users side. ''developer'' is like a more extreme version of ''testing'', where the program is expected to have bugs.
 +
 
 +
When to use ''buggy''? Don't mark old releases as buggy every time you do a new release, just because a few bugs have been fixed. People who have selected network connectivity automatically pickup the new version anyway, so marking an older version as ''buggy'' only affects people who have explicitly stated that they don't want to use the latest version, but would prefer to use an older release to save network use.
 +
 
 +
== Dependencies ==
 +
 
 +
Dependencies might be used to declare software that the current release depends on.
  
−
=== Python activity ===
+
The format of a dependency string is:
  
−
Python-based activity with standard Sugar Platform dependencies.
+
''DEPENDENCY'' [(<|<=|=|>=|>) ''VERSION'']
  
−
[Activity]
+
The ''DEPENDENCY'' value is a GUID associated with dependency project, i.e., ''context'' value from dependency spec file. In general, it might be any software Sugar Network [http://node.sugarlabs.org/context Context], but current implementation assumes only GNU/Linux [http://node.sugarlabs.org/context?type=package packages].
−
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 ===
+
== Glob patterns ==
  
−
A python-based library that could be used as is, or as an activity dependency.
+
The ''include'' and ''exclude'' options contain file patterns. A pattern could be of two types:
  
−
[Component]
+
* doesn't contain ''/'' or ''**'' substrings, will be applied only to file names
−
slug      = journal
+
* contains ''/'' or ''**'' substring, will be applied to the full file path (relative to the root), thus could affect several directory levels
−
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 ===
+
Only these pattern symbols are allowed:
  
−
[DEFAULT]
+
* ''*'' matches everything, except directory separator
−
slug      = polyol
+
* ''?'' matches any single character, except directory separator
−
summary  = Intermediate level GObject based libraries for Sugar
+
* ''**'' matches everything, including directory separator
−
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
 

Latest revision as of 19:00, 3 July 2013

Summary

The document describes software specification files format which is a superset on top of the Sugar activity bundles specification. This format is backwards compatible with activity.info files to make sure that software starts well from the regular Sugar Shell. But the major purpose of introducing new format is supporting software hosted on the Sugar Network. In particular, new format assumes the following functionality:

  • Support binary based software;
  • Provide information about software dependencies;
  • Introduce stability levels to make it possible (for interested in people) to run development versions using the same, like for stable releases, distribution channel;
  • Distribute not only Sugar activities, e.g., software libraries;
  • Include all required information to make it possible to reuse the same spec file on different software evolution phases, like, making sources tarball, building binaries on Sugar Labs instance of the Open Build Service, executing.

The format is partially based on the Zero Install specification since implementation code reuses Zero Install library in order to launch software on users side.

Spec file locations

There are two possible spec file locations (staring from the top directory of a distribution bundle):

  • /activity/activity.info
    for Sugar activities to make them capable to be launched from the regular Sugar Shell;
  • /sweets.recipe
    in the rest of cases.

Configuration sections

As activity.info files, new format is based on INI files and should contain at least one of the following sections.

Common options

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

context = GUID

Required (but see the [Activity] section). The value which uniquely identifies a software project this particular version implements. This is a Sugar Network Context GUID. 

name = NAME

Optional. Free-form name. (It is equal to the implemented, by default.) 

summary = ONE_LINE_TEXT

Required. Short descriptive line. 

description = MULTI_LINE_TEXT

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

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

homepage = URL

Required. Software project home page. 

icon = FILENAME

Optional (but see the [Activity] section). Path to the icon file starting from the path where the recipe file is located. 

tags = TAG [; ...]

Optional. Tags give more context by which to group the software. This is done to allow users to make search more easily. 

version = VERSION

Required. Current version of the software using special notation. Note, to make Sugar activity bundles compatible with pristine Sugar, use a limited format subset supported by the Sugar Shell. 

stability = LEVEL

Required. Stability level of the current version. Values conform to the below list. 

requires = DEPENDENCY [; ...]

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

[Activity]

This section type should be present only in Sugar activities. 

activity_version = VERSION

Required. An alias of the version option. 

bundle_id = BUNDLE_ID

Required. An alias of the context option. 

icon = FILENAME_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.

[Archive]

This configuration section makes sense only while building binary distribution bundles from the sources. The section is optional for spec files that describe software assumed to be launched as-is, e.g., .xo bundles.

Each [Archive] section describes one particular binary bundle. There are might be several sections to define binaries for different cases:

  • To save storage space or bandwidth when some bundles will contain any-arch data that are common for all platforms, and another bundle will contain binaries for a particular platform;
  • Per language bundles, e.g., for media content.

All archive sections are named: 

Archive[:SUBNAME]

And contain the following options: 

include = GLOB [; ...]

Optional. Glob pattern for files to include in the archive. By default, all files are assumed. 

exclude = GLOB [; ...]

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. 

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.

[Build]

This section is required if software needs additional work in order to prepare a ready-to-use installation. 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 software from sources. Note that common requires option values 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]

The section makes sense only while building sources bundles and is a replacement of former MANIFEST file in Sugar activity bundles. 

exec = SHELL_COMMAND

Optional. Execute an external program to create sources tarball. Option might be used, e.g., to run make dist command. 

include = GLOB [; ...]
exclude = GLOB [; ...]

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 constants

Constants defined within the [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

Version numbers

A version number string has the following form: 

Version := DottedList ("-" Modifier? DottedList?)*
DottedList := (Integer ("." Integer)*)
Modifier := "pre" | "rc" | "post"

Numerically, the modifiers come in the order "-pre" (pre-release), "-rc" (release candidate), "-" (no modifier name), "-post" (post-release or patch level). Versions are ordered like this: 

0.1
1
1.0
1.2-pre
1.2-pre1
1.2-rc1
1.2
1.2-0
1.2-post
1.2-post1-pre
1.2-post1
1.2.1-pre
1.2.1.4
1.2.2
1.2.10
3

Software stability levels

The spec file also gives a stability rating for each implementation. The following levels are allowed (must be lowercase in the feed files):

  • stable,
  • testing,
  • developer,
  • buggy,
  • insecure.

Stability ratings are expected to change over time. When any new release is made, its stability should be set to testing. Users who have selected Help test new versions will then start using it. Other users will continue with the previous stable release. After a while (days, weeks or months, depending on the project) with no serious problems found, the implementation's stability can be changed to stable so that everyone will use it.

If problems are found, it can instead be marked as buggy, or insecure to avoid selecting these versions while launching on users side. developer is like a more extreme version of testing, where the program is expected to have bugs.

When to use buggy? Don't mark old releases as buggy every time you do a new release, just because a few bugs have been fixed. People who have selected network connectivity automatically pickup the new version anyway, so marking an older version as buggy only affects people who have explicitly stated that they don't want to use the latest version, but would prefer to use an older release to save network use.

Dependencies

Dependencies might be used to declare software that the current release depends on.

The format of a dependency string is: 

DEPENDENCY [(<|<=|=|>=|>) VERSION]

The DEPENDENCY value is a GUID associated with dependency project, i.e., context value from dependency spec file. In general, it might be any software Sugar Network Context, but current implementation assumes only GNU/Linux packages.

Glob patterns

The include and exclude options contain file patterns. A pattern could be of two types:

  • doesn't contain / or ** substrings, will be applied only to file names
  • 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
Retrieved from "https://wiki.sugarlabs.org/index.php?title=Sugar_Network/Recipe_Specification&oldid=88603"