5,705
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: − Read the [[Platform_Team/Guide/Sweets_Packaging|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.+ + + − + + + + + − + − '''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.)+ − + − + + + − + + + − + + + + + − Required. Sweet project home page.+ − + − + − '''category''' = <category> [; ...]+ − Optional. A classification for the sweet using values defined by [http://standards.freedesktop.org/menu-spec/latest/apa.html 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.+ − + − + − '''stability''' = <stability-level>+ − Required. Stability level of the current version. Values conform to [http://0install.net/interface-spec.html#id4016716 0install stability levels] and could be:+ − * insecure − * buggy − * developer − * testing − * stable − '''requires''' = <dependency> [; ...]+ − Optional. List of [[Platform_Team/Guide/Sweets_Packaging#Dependencies|dependencies]] that should exist at run-time before launching the sweet.+ − + − + − + − '''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 {{Code|%(version)s}} for this option.+ − '''bundle_id''' = <bundle-id>+ − Deprecated. '''Should be still present only to run the activity in non-sweets environment'''. See [[Development_Team/Almanac/Activity_Bundles#.info_file_format|activity.info file specification]].+ − + + + + + + + − + + + − + + + + − + Line 113:
Line 138: + + − === [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:+ − + − * 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; − − In addition to the already [[#Predefined_options|existing]] predefined options, there are several new defines that make sense only for this section's packages:+ − * {{Code|EXEC_PREFIX}};+ − * {{Code|BINDIR}}; − * {{Code|SBINDIR}}; − * {{Code|SYSCONFDIR}}; − * {{Code|DATADIR}}; − * {{Code|INCLUDEDIR}}; − * {{Code|LIBDIR}}; − * {{Code|LIBEXECDIR}}; − * {{Code|LOCALSTATEDIR}}; − * {{Code|MANDIR}}; − * {{Code|INFODIR}}; − * {{Code|PYTHONSITEDIR}}, equal to Python's {{Code|PYTHONPATH}} environment variable; − * {{Code|LUACPATHDIR}}, equal to Lua's {{Code|LUA_CPATH}} environment variable; − * {{Code|LUAPATHDIR}}, equal to Lua's {{Code|LUA_PATH}} environment variable; − * {{Code|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 {{Code|%(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. [[Platform_Team/Guide/Sweets_Packaging#Glob_patterns|Glob pattern]] for files to include in the archive. Path related patterns will be processed starting from the [[#Predefined_options|%(DISTDIR)s/%(PREFIX)s]] directory. By default, all files are assumed.+ − + Line 189:
Line 170: − + + + − + − * ''all'' for noarch (by default) − * ''any'' for binaries to use the current architecture − − == Auxiliary sections == − Sections that don't describe recipe components.+ + − + − + + + + + − Optional. This defines what [[Platform_Team/Guide/Sweets_Packaging#Dependencies|dependencies]] should be present before building the sweet from sources. Note that ''requires'' from [[#.5BComponent.5D|[Component]]] sections are not auto included in the build-time dependencies.+ − + − + + + − + + + − + + + Line 229:
Line 219: − + + + + + − + − '''include''' = <glob-pattern> [; ...]+ − '''exclude''' = <glob-pattern> [; ...] − Optional. If the ''exec'' option was not used, all files will be bundled and these [[Platform_Team/Guide/Sweets_Packaging#Glob_patterns|glob patterns]] might be used to reify the selection.+ + − '''requires''' = <dependency> [; ...]+ − Optional. The [[Platform_Team/Guide/Sweets_Packaging#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.+ − + − Options defined within ''[Build]'' section:+ + + + + Line 255:
Line 253: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Sugar Network/Recipe Specification (view source)
Revision as of 23:13, 1 July 2013
, 23:13, 1 July 2013no edit summary
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:
* 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.
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.
== Spec file locations ==
There are two possible spec file locations (staring from the top directory of a distribution bundle):
* {{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.
== 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 ===
'''implement''' = <sweet> [; ...]
Regardless of the software type, a recipe section (or one of them) should contain the following options.
<div id="context"></div>
'''context''' = ''GUID''
Required. The list of interfaces that the current project is implementing.
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.
<div id="name"></div>
'''name''' = ''NAME''
Optional. Free-form name. (It is equal to the ''implemented'', by default.)
<div id="summary"></div>
'''summary''' = <one-line-description>
'''summary''' = ''ONE_LINE_TEXT''
Required. Short descriptive line.
Required. Short descriptive line.
'''description''' = <multi-line-description>
<div id="description"></div>
'''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.
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> [; ...]
<div id="license"></div>
'''license''' = ''LICENSE'' [; ...]
Required. Short license names. The licenses should conform with the [[Activity Library]] licensing [[Activity_Library/Editors/Policy/Licensing|policy]].
Required. Short license names. The licenses should conform with the [[Activity Library]] licensing [[Activity_Library/Editors/Policy/Licensing|policy]].
'''homepage''' = <url>
<div id="homepage"></div>
'''homepage''' = ''URL''
Required. Software project home page.
<div id="icon"></div>
'''icon''' = <icon-file-name>
'''icon''' = ''FILENAME''
Optional. Path to the icon file starting from the path where the recipe file is located.
Optional (but see the [[#.5BActivity.5D|[Activity]]] section). Path to the icon file starting from the path where the recipe file is located.
<div id="tags"></div>
'''tags''' = ''TAG'' [; ...]
Optional. Tags give more context by which to group the software. This is done to allow users to make search more easily.
<div id="version"></div>
'''version''' = <version-number>
'''version''' = ''VERSION''
Required. Current version of the sweet using [http://0install.net/interface-spec.html#id4016582 0install version format].
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.
<div id="stability"></div>
'''stability''' = ''LEVEL''
Required. Stability level of the current version. Values conform to the [[#Software_stability_levels|below list]].
<div id="requires"></div>
'''suggests''' = <dependency> [; ...]
'''requires''' = ''DEPENDENCY'' [; ...]
Optional. List of [[Platform_Team/Guide/Sweets_Packaging#Dependencies|dependencies]] that will be demanded to be present at run-time only if it was explicitly required from a user.
Optional. List of [[#Dependencies|dependencies]] that should exist at run-time before launching the release.
=== [Activity] ===
=== [Activity] ===
This section type should be present only in activities.
This section type should be present only in Sugar activities.
<div id="activity_version"></div>
'''activity_version''' = ''VERSION''
Required. An alias of the ''version'' option.
<div id="bundle_id"></div>
'''icon''' = <icon-file-name-without-suffix>
'''bundle_id''' = ''BUNDLE_ID''
Required. An alias of the ''context'' option.
<div id="icon"></div>
'''icon''' = ''FILENAME_WITHOUT_SUFFIX''
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.
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.
'''exec''' = <shell-command>
<div id="activity_exec"></div>
'''exec''' = ''SHELL_COMMAND''
Required. Sugar will pass additional [[Development_Team/Low-level_Activity_API#Command_Line_Arguments| command line arguments]] to this command.
Required. Sugar will pass additional [[Development_Team/Low-level_Activity_API#Command_Line_Arguments| command line arguments]] to this command.
'''mime_types''' = <mime-type> [; ...]
<div id="mime_types"></div>
'''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.
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] ===
Application to run outside of Sugar Shell.
Application to run outside of Sugar Shell.
'''exec''' = <shell-command>
'''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.
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.
Required. The environment variables 0install should export to the process that uses this sweet.
Required. The environment variables 0install should export to the process that uses this sweet.
-->
=== [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:
* it is very limited by design in comparison with regular GNU/Linux distribution spec files;
* 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.
* this section was introduced only for cases when having native packages makes sense, e.g., for Live Sugar distributions or LTSP.
All archive sections are named:
Archive[:''SUBNAME'']
And contain the following options:
<div id="archive-include"></div>
'''include''' = ''GLOB'' [; ...]
Optional. [[#Glob_patterns|Glob pattern]] for files to include in the archive. By default, all files are assumed.
<div id="archive-exclude"></div>
'''exclude''' = <glob-pattern> [; ...]
'''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''.
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''.
exclude[<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 [[#Predefined_options|LANG]] variable makes sense).-->
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).-->
<div id="arch"></div>
'''arch''' = <arch>
'''arch''' = ''ARCH''
Optional. Makes sense only for binary archives, and can contain:
Optional. Makes sense only for binary archives, and can contain:
* ''all'' for noarch (by default),
* ''any'' for binaries to use the current architecture.
=== [Build] ===
=== [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_options|predefined constants]] for options that contain shell commands. All shell commands will be executed from the {{Code|%(BUILDDIR)s}} directory.
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.
'''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''' 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.
'''requires''' = <dependency> [; ...]
<div id="build-requires"></div>
'''requires''' = ''DEPENDENCY'' [; ...]
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.
<div id="clean"></div>
'''clean''' = <shell-command>
'''clean''' = ''SHELL_COMMAND''
Optional. Cleanup build environment before running ''configure'' command.
Optional. Cleanup build environment before running ''configure'' command.
'''configure''' = <shell-command>
<div id="configure"></div>
'''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.
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>
<div id="build-make"></div>
'''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.
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>
<div id="install"></div>
'''install''' = ''SHELL_COMMAND''
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.
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.
=== [Source] ===
=== [Source] ===
'''exec''' = <shell-command>
The section makes sense only while building sources bundles and is a replacement of former ''MANIFEST'' file in Sugar activity bundles.
<div id="source-exec"></div>
'''exec''' = ''SHELL_COMMAND''
Optional. Execute an external program to create sources tarball. Option might be used, e.g., to run {{Code|make dist}} command. After executing the ''exec'' shell command, {{Code|sweets}} will pick up a newly appearing tarball if it was created in the sweet root directory.
Optional. Execute an external program to create sources tarball. Option might be used, e.g., to run {{Code|make dist}} command.
<div id="source-include"></div>
'''include''' = ''GLOB'' [; ...]
'''exclude''' = ''GLOB'' [; ...]
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.
<div id="source-requires"></div>
== Predefined options ==
'''requires''' = ''DEPENDENCY'' [; ...]
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.
=== 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.
* ''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.
* ''LANG'' current language while building per language implementation
* ''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 [http://node.sugarlabs.org/context Context] GUID, but current implementation assumes only GNU/Linux [http://node.sugarlabs.org/context?type=package packages].