Difference between revisions of "Sugar Network/Recipe Specification"

From Sugar Labs
Jump to navigation Jump to search
 
(216 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
<noinclude>
+
== Summary ==
−
{{TOCright}}
 
−
[[Category:Zero Sugar]]
 
−
</noinclude>
 
  
−
== 0sugar.info file ==
+
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 {{Code|0sugar.info}} specification file is an analog of scenario files in regular GNU/Linux distributions, like .spec files in RPM.
+
* 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.
  
−
=== [DEFAULT] ===
+
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.
  
−
Common options. Options from this section will be accessible from all other sections.
+
== Spec file locations ==
  
−
'''import'''
+
There are two possible spec file locations (staring from the top directory of a distribution bundle):
  
−
Import another spec file.
+
* {{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 = <filename> [, ...]
+
== Configuration sections ==
  
−
=== [Package] ===
+
As ''activity.info'' files, new format is based on [[wikipedia:INI_file|INI files]] and should contain at least one of the following sections.
  
−
This is required section. It describes the main package.
+
=== Common options ===
  
−
'''inherit'''
+
Regardless of the software type, a recipe section (or one of them) should contain the following options.
  
−
Include options from another section.
+
<div id="context"></div>
  
−
  inherit = <section-name>
+
'''context''' = ''GUID''
  
−
'''slug'''
+
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 string used as identifier in cases like 0isntall feed urls or native package names. Only lower alphabetic, numeric, "_", "+"  or "-" symbols are allowed.
+
<div id="name"></div>
  
−
  slug = <package-slug>
+
'''name''' = ''NAME''
  
−
'''name'''
+
Optional. Free-form name. (It is equal to the ''implemented'', by default.)
  
−
Package name in free form, equals to ''slug'' by default.
+
<div id="summary"></div>
  
−
  name = <package-name>
+
'''summary''' = ''ONE_LINE_TEXT''
  
−
'''summary'''
+
Required. Short descriptive line.
  
−
Short descriptive line
+
<div id="description"></div>
  
−
  summary = <one-line-description>
+
'''description''' = ''MULTI_LINE_TEXT''
  
−
'''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.
  
−
Long descriptive text. To wrap long text, all lines after second, should start with spaces. This field is equal to ''summary'' by default.
+
<div id="license"></div>
  
−
  description = <multy-line-description>
+
  '''license''' = ''LICENSE'' [; ...]
  
−
'''licence'''
+
Required. Short license names. The licenses should conform with the [[Activity Library]] licensing [[Activity_Library/Editors/Policy/Licensing|policy]].
  
−
License. Short licence names from [http://fedoraproject.org/wiki/Licensing Fedora naming scheme] are welcome.
+
<div id="homepage"></div>
  
−
  license = <licence-name>
+
'''homepage''' = ''URL''
  
−
'''homepage'''
+
Required. Software project home page.
  
−
Packaged project home page.
+
<div id="icon"></div>
  
−
  homepage = <url>
+
'''icon''' = ''FILENAME''
  
−
'''version'''
+
Optional (but see the [[#.5BActivity.5D|[Activity]]] section). Path to the icon file starting from the path where the recipe file is located.
  
−
Current version of package.
+
<div id="tags"></div>
  
−
'''stability'''
+
'''tags''' = ''TAG'' [; ...]
  
−
Stability level of current version. Values could be:
+
Optional. Tags give more context by which to group the software. This is done to allow users to make search more easily.
−
* insecure
 
−
* buggy
 
−
* developer
 
−
* testing
 
−
* stable
 
  
−
'''requires'''
+
<div id="version"></div>
  
−
List of dependencies that should exist before using this one. Option accepts also full 0install urls (could be useful to include non 0sugar dependencies).
+
'''version''' = ''VERSION''
  
−
  requires = <dependency> [(>=|<|=) <version>] [, ...]
+
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.
  
−
'''slots'''
+
<div id="stability"></div>
  
−
To specify dependency [[#Slots|slots]] on using side:
+
'''stability''' = ''LEVEL''
  
−
  slots[<dependency>] = <dependency-version>, <dependency-verison> [, ...]
+
Required. Stability level of the current version. Values conform to the [[#Software_stability_levels|below list]].
  
−
'''binding'''
+
<div id="requires"></div>
  
−
What environment variables, 0install should export to process which uses this package.
+
'''requires''' = ''DEPENDENCY'' [; ...]
  
−
  binding = [prepend|append|replace] <variable-name> [<insert-text-to-prepand-variable-value>] [, ...]
+
Optional. List of [[#Dependencies|dependencies]] that should exist at run-time before launching the release.
  
−
'''main'''
+
=== [Activity] ===
  
−
For applications, path to exec file from root directory that will be executed from 0launch command.
+
This section type should be present only in Sugar activities.
  
−
  main = <relative-path-to-exec-file>
+
<div id="activity_version"></div>
  
−
'''exec'''
+
'''activity_version''' = ''VERSION''
  
−
Instead of using execution program from ''main'' option, 0sugar can bundle a script to run arbitrary shell command:
+
Required. An alias of the ''version'' option.
  
−
  exec = <shell-command>
+
<div id="bundle_id"></div>
  
−
Also, 0sugar can bundle arbitrary shell scripts:
+
'''bundle_id''' = ''BUNDLE_ID''
  
−
  exec[<script-name>] = <shell-command>
+
Required. An alias of the ''context'' option.
  
−
Last form could be useful when such scripts make sense only in 0install distribution e.g. to pass a path to already bundled command instead of using this command directly:
+
<div id="icon"></div>
  
−
  binding = replace VALADIR, PATH
+
'''icon''' = ''FILENAME_WITHOUT_SUFFIX''
−
  exec[valac] = exec "$VALADIR"/bin/valac --vapidir "$VALADIR"/share/vala/vapi "$@"
 
  
−
'''include'''
+
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.
  
−
[[#Glob patterns|Glob pattern]] for files to include to implementations.
+
<div id="activity_exec"></div>
  
−
  include = <glob-pattern> [, ...]
+
  '''exec''' = ''SHELL_COMMAND''
  
−
By default all files will be included.
+
Required. Sugar will pass additional [[Development_Team/Low-level_Activity_API#Command_Line_Arguments| command line arguments]] to this command.
  
−
'''exclude'''
+
<div id="mime_types"></div>
  
−
[[#Glob patterns|Glob pattern]] for files to exclude from implementations.
+
'''mime_types''' = ''MIME_TYPE'' [; ...]
  
−
exclude = <glob-pattern> [, ...]
+
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.
  
−
'''langs'''
+
<!--
 +
=== [Application] ===
  
−
A special form of ''include''/''exclude'' options that are intended to create separate, per locale, implementations.
+
Application to run outside of Sugar Shell.
  
−
  langs = <lang-name> [, ...]
+
'''exec''' = ''SHELL_COMMAND''
−
  include[<lang-name>] = <glob-pattern> [, ...]
 
−
  exclude[<lang-name>] = <glob-pattern> [, ...]
 
  
−
If language is mentioned in ''langs'' list but doesn't have ''include[]''/''exclude[]'' options, ''include''/''exclude'' will be used.
+
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.
  
−
'''prefix'''
+
=== [Library] ===
  
−
Specify path from ''DISTDIR'' for ''include''/''exclude'' options.
+
'''binding''' = [prepend|append|replace] <variable-name> [<insert-text-to-prepend-variable-value>] [; ...]
  
−
  prefix = <path>
+
Required. The environment variables 0install should export to the process that uses this sweet.
 +
-->
 +
=== [Archive] ===
  
−
'''arch'''
+
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.
  
−
Makes sense only for binary packages and can contain:
+
Each ''[Archive]'' section describes one particular binary bundle. There are might be several sections to define binaries for different cases:
  
−
* ''*'' for noarch (by default)
+
* 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;
−
* ''build'' for binaries to use current architecture
+
* Per language bundles, e.g., for media content.
  
−
'''packaged'''
+
All archive sections are named:
  
−
If service could be installed from native packaging system, use this option to let 0install know what packages names are on particular GNU/Linux distribution.
+
Archive[:''SUBNAME'']
  
−
  packaged = <distro-name> <package-name> [, ...]
+
And contain the following options:
  
−
There are basic distro names
+
<div id="archive-include"></div>
  
−
* ''rpm'' for all rpm based distros
+
'''include''' = ''GLOB'' [; ...]
−
* ''debian'' for deb based distros
 
−
* ''gentoo'' for ebuild based distros
 
−
* ''slack'' Slackware
 
−
* ''ports'' FreeBSD Ports
 
  
−
and also exact disto names to be more explicit
+
Optional. [[#Glob_patterns|Glob pattern]] for files to include in the archive. By default, all files are assumed.
  
−
* fedora
+
<div id="archive-exclude"></div>
−
* suse
 
−
* mandriva
 
−
* archlinux
 
−
* altlinux
 
  
−
See for more information in [[Documentation Team/Services/Wrap native packages HOWTO|Wrap native packages HOWTO]].
+
'''exclude''' = ''GLOB'' [; ...]
  
−
=== [Buid] ===
+
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> [; ...]
  
−
How to build binaries. If service contains binary implementations, this section should present to describe building process.
+
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).-->
  
−
'''requires'''
+
<div id="arch"></div>
  
−
What services should present before building this one from sources.
+
'''arch''' = ''ARCH''
  
−
  <service-name> [(>=|<|=) <version>] [, ...]
+
Optional. Makes sense only for binary archives, and can contain:
  
−
'''exec'''
+
* ''all'' for noarch (by default),
 +
* ''any'' for binaries to use the current architecture.
  
−
Command how to build binaries.
+
=== [Build] ===
  
−
  exec = <shell-command>
+
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.
  
−
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''' 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.
  
−
''NOTE'' This command will be executed not only in service 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
+
<div id="build-requires"></div>
  
−
=== [Maintain] ===
+
'''requires''' = ''DEPENDENCY'' [; ...]
  
−
Various service maintaining related settings.
+
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.
  
−
'''source'''
+
<div id="clean"></div>
  
−
Web link to the sources tarball, if parameter is absent, exec from this section will be used to generate tarball
+
'''clean''' = ''SHELL_COMMAND''
  
−
  source = <web-url>
+
Optional. Cleanup build environment before running ''configure'' command.
  
−
'''version'''
+
<div id="configure"></div>
  
−
Optional version of the service, if it's absent, version should be passed via ''--relese'' 0sugar argument or will be parsed from source tarball filename.
+
'''configure''' = ''SHELL_COMMAND''
  
−
  version = <version>
+
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.
  
−
'''requires'''
+
<div id="build-make"></div>
  
−
What services should present before invoking ''0sugar dist'' command i.e. only in maintainer environment not even while building service from sources on user side.
+
'''make''' = ''SHELL_COMMAND''
  
−
  requires = <dependency> [(>=|<|=) <version>] [, ...]
+
Optional. Shell command to make binaries from sources. If the source code does not require a making stage, this option could be omitted.
  
−
'''patch'''
+
<div id="install"></div>
  
−
Patch downloaded tarball, makes sense only if source parameter exists. Option ''exec'' should present as well to make new tarball.
+
'''install''' = ''SHELL_COMMAND''
  
−
  patch = <path-to-patch> [patch-level] [, ...]
+
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.
  
−
'''exec'''
+
=== [Source] ===
  
−
Command how to bundle service.
+
The section makes sense only while building sources bundles and is a replacement of former ''MANIFEST'' file in Sugar activity bundles.
  
−
  exec = <shell-command>
+
<div id="source-exec"></div>
  
−
Shell command, executed from service root directory. If this command starts to get complicated, you should move it to a script and just set this attribute to the command to run the script. By default 0sugar just bundle entirely service directory excluding temporary files. If source parameter exists in this section, command will be executed within extracted directory of downloaded tarball.
+
'''exec''' = ''SHELL_COMMAND''
  
−
== Glob patterns ==
+
Optional. Execute an external program to create sources tarball. Option might be used, e.g., to run {{Code|make dist}} command.
  
−
A pattern could be two types:
+
<div id="source-include"></div>
  
−
* doesn't contain ''/'' symbol, will be applied only to file names (not names of sub-directories within parent directory)
+
'''include''' = ''GLOB'' [; ...]
−
* contains ''/'' symbol, will be applied to the full file path (relative to the root) thus could affect several directory levels
+
'''exclude''' = ''GLOB'' [; ...]
  
−
Only these pattern symbols are allowed:
+
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.
  
−
* ''*'' matches everything except directory separator
+
<div id="source-requires"></div>
−
* ''?'' matches any single character except directory separator
 
−
* ''**'' matches everything including directory separator
 
  
−
== Sub services ==
+
'''requires''' = ''DEPENDENCY'' [; ...]
  
−
By default service 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:
+
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.
  
−
  [<nowiki>Service/<sub-name></nowiki>]
+
=== Predefined constants ===
  
−
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).
+
Constants defined within the ''[Build]'' section:
  
−
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.
+
* ''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 {{Code|./configure --prefix}}
 +
* ''CFLAGS'' default gcc CFLAGS
 +
* ''CXXFLAGS'' default gcc CXXFLAGS
  
−
Other services can mention sub feeds by format:
+
In sections that contain a ''langs'' option:
  
−
<nowiki><service-name>/<sub-service-name></nowiki>
+
* ''LANG'' current language while building per language implementation
  
−
== Recipes ==
+
== Version numbers ==
  
−
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
+
A version number string has the following form:
−
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:
+
Version := DottedList ("-" Modifier? DottedList?)*
 +
DottedList := (Integer ("." Integer)*)
 +
Modifier := "pre" | "rc" | "post"
  
−
  [Service]
+
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:
−
  recipe = <component-name> [, ...]
 
  
−
and declare sections that contain components:
+
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
  
−
  [<component-name>]
+
== Software stability levels ==
−
  ...
 
  
−
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:
+
The spec file also gives a stability rating for each implementation. The following levels are allowed (must be lowercase in the feed files):
  
−
* langs
+
* ''stable'',
−
* arch
+
* ''testing'',
−
* include
+
* ''developer'',
−
* exclude
+
* ''buggy'',
−
* main
+
* ''insecure''.
−
* exec
 
−
* slots
 
  
−
The same component could a part of different recipes. In that case, different (sub)service implementations will contain the same component tarball.
+
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.
  
−
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.
+
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.
  
−
[Service]
+
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.
−
recipe = data, binary
 
−
 
−
[data]
 
−
include = share/*
 
−
 
−
[binary]
 
−
include = bin/*, lib/*
 
−
main = bin/launch
 
−
arch = build
 
  
−
== Slots ==
+
== Dependencies ==
  
−
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.
+
Dependencies might be used to declare software that the current release depends on.
  
−
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.
+
The format of a dependency string is:
  
−
To declare slots for used dependency, ''slots'' and appropriate ''requires'' options should be placed to ''[Service]'' section that uses dependency:
+
''DEPENDENCY'' [(<|<=|=|>=|>) ''VERSION'']
  
−
  requires = <dependency>
+
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].
−
  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:
+
== Glob patterns ==
  
−
  1.0, 1.8, 2.0
+
The ''include'' and ''exclude'' options contain file patterns. A pattern could be of two types:
  
−
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.
+
* 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
  
−
== Predefined options ==
+
Only these pattern symbols are allowed:
−
 
 
−
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
+
* ''*'' matches everything, except directory separator
−
* ''SECTION_<section-name-in-upper-case>'' for every spec file section that will be processed
+
* ''?'' matches any single character, except directory separator
 +
* ''**'' matches everything, including directory separator

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"