5,705
edits
Changes
Sugar Network/Recipe Specification (view source)
Revision as of 09:12, 24 December 2010
, 09:12, 24 December 2010no edit summary
[[Category:Zero Sugar]]
The recipe specification file is an analog of scenario files in regular GNU/Linux distributions, like .spec files in RPM. It is the cornerstone of [[Platform_Team/Doers_environment|Doers environment]], everything on Sugar project level depends on the recipe file. For activities, activity.info, an inherited recipe file name, is supported.
== Spec file sections ==
== Recipe structure ==
Recipe file is an [http://docs.python.org/library/configparser.html ini] format configuration file that might consist of several sections:
* Component sections:
** [[#Main component|Main component]] section,
** Optional [[#Extra_components|extra component]] sections.
* Optional auxiliary sections:
** [[#.5BBuild.5D|[Build]]],
** [[#.5Bsource.5D|[Source]]].
* Optional {{Code|[DEFAULT]}} section with common options that are accessible from all other sections.
=== [DEFAULT] ===
== Recipe components ==
The sweet distribution contains one or several tarballs. Each tarball is being described by component section.
=== [Component] ===
=== Main component ===
This is a required section (but see also [[#Presets|presets]]). It describes the main recipe component.
This is a required section with the name:
<nowiki>[</nowiki>[[#Component_types|type]]<nowiki>]</nowiki>
Regardless of the type, it contains followed options:
'''sweet''' = <identifier>
'''sweet''' = <identifier>
An identifier of the package. Only lower alphabetic, numeric, "+", "-" or "." symbols are allowed. The sweet identifier should be at least two characters long and start with an alphanumeric character.
Required. An identifier of the package. Only lower alphabetic, numeric, "+", "-" or "." symbols are allowed. The sweet identifier should be at least two characters long and start with an alphanumeric character.
''sweet'' is used in several cases:
''sweet'' is used in several cases:
'''name''' = <package-name>
'''name''' = <package-name>
Package name, in free form text. (It is equal to the ''sweet'', by default.)
Optional. Package name, in free form text. (It is equal to the ''sweet'', by default.)
'''summary''' = <one-line-description>
'''summary''' = <one-line-description>
Short descriptive line.
Required. Short descriptive line.
'''description''' = <multi-line-description>
'''description''' = <multi-line-description>
Long descriptive text. To wrap long text, all lines after the second, should start with spaces. This field is equal to ''summary'' by default.
Optional. Long descriptive text. To wrap long text, all lines after the second, should start with spaces. This field is equal to ''summary'' by default.
'''license''' = <license-name>
'''license''' = <license-name>
Package license. Short license names from [http://fedoraproject.org/wiki/Licensing Fedora naming scheme] are welcome.
Required. Package license. Short license names from [http://fedoraproject.org/wiki/Licensing Fedora naming scheme] are welcome.
'''homepage''' = <url>
'''homepage''' = <url>
Packaged project home page.
Required. Packaged project home page.
'''icon''' = <icon-file-name>
'''icon''' = <icon-file-name>
Path to package icon file starting from the path where the recipe file is located.
Optional. Path to package icon file starting from the path where the recipe file is located.
'''category''' = <category> [; ...]
'''category''' = <category> [; ...]
A classification for the package using values defined by [http://standards.freedesktop.org/menu-spec/latest/apa.html freedesktop.org menu specification].
Optional. A classification for the package using values defined by [http://standards.freedesktop.org/menu-spec/latest/apa.html freedesktop.org menu specification].
'''version''' = <version-number>
'''version''' = <version-number>
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 [[Platform_Team/Guide/Packaging#Versioning|different]].
Required. 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 [[Platform_Team/Guide/Packaging#Versioning|different]].
'''stability''' = <stability-level>
'''stability''' = <stability-level>
Stability level of the current version. Values conform to [http://0install.net/interface-spec.html#id4016716 0install stability levels] and could be:
Required. Stability level of the current version. Values conform to [http://0install.net/interface-spec.html#id4016716 0install stability levels] and could be:
* insecure
* insecure
* buggy
* buggy
'''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
'''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
List of [[Platform_Team/Guide/Packaging#Package_names|dependencies]] that should exist in run-time before using the package. Note that ''requires'' from [[#.5BBuid.5D|[Build]]] section are not auto included to this list (e.g., like RPM does).
Optional. List of [[Platform_Team/Guide/Packaging#Package_names|dependencies]] that should exist in run-time before using the package. Note that ''requires'' from [[#.5BBuid.5D|[Build]]] section are not auto included to this list (e.g., like RPM does).
'''include''' = <glob-pattern> [; ...]
Optional. [[Platform_Team/Guide/Packaging#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.
'''exclude''' = <glob-pattern> [; ...]
Optional. Like ''include'' option but for excluding files from the package. In additional, various temporary files will be excluded like ''.bak'' or ''.pyc''.
'''langs''' = <lang-name> [; ...]
include[<lang-name>] = <glob-pattern> [; ...]
exclude[<lang-name>] = <glob-pattern> [; ...]
Optional. 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).
'''arch''' = <arch>
Optional. Makes sense only for binary (sub)packages, and can contain:
* ''all'' for noarch (by default)
* ''any'' for binaries to use the current architecture
=== Extra components ===
The sweet distribution might be split into several tarballs that can be composed in different ways when the same sweet release contains several implementations with different tarballs compositions. Each component section (including [[#Main component|main]] one) describes one of these tarballs.
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.
* ''TODO''.
'''binding''' = [prepend|append|replace] <variable-name> [<insert-text-to-prepend-variable-value>] [; ...]
Extra component sections should be named:
<nowiki>[</nowiki>[[#Component_types|type]]/''name''<nowiki>]</nowiki>
== Component types ==
Depending on purpose, component sections might be one of followed types.
=== [Activity] ===
This component section type should be present only in activities.
'''activity_version''' = <version>
Required. Option is deprecated, use ''version'' instead, but should be still present to not fail in current sugar. It will be useful to use expansion like {{Code|%(version)s}} for this option.
'''bundle_id''' = <bundle-id>
Required. See [[Development_Team/Almanac/Activity_Bundles#.info_file_format|activity.info file specification]]. Option is deprecated, use ''sweet'' instead, but should be still present to not fail in current sugar.
'''main''' = <path-to-exec-file>
'''icon''' = <icon-file-name-without-suffix>
Required. Behaviour from activity.info is supported (value should not have ".svg" suffix, and icon file could be found only in activity subdirectory) but deprecated. Regular ''icon'' behaviour from ''[Component]'' section should be used instead.
'''exec''' = <shell-command>
'''exec''' = <shell-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> [; ...]
'''include''' = <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 which can open a certain Journal object.
'''tags''' = <tag> [; ...]
Optional. Tags give more context in which to group the activity. This is used to allow users to find activities more easily in the Journal, the Home view, etc.
=== [Application] ===
Application to run out of Sugar Shell.
'''exec''' = <shell-command>
Required. The relative path of an executable command inside the implementation that should be executed by default when the package is run. Command can have optional arguments.
[[Platform_Team/Guide/Packaging#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.
=== [Library] ===
'''exclude''' = <glob-pattern> [; ...]
'''age''' = <age-number>
Simple number that will be used as a major number for ''version'', see [[Platform_Team/Guide/Packaging#Versioning|versioning scheme]] for details.
'''langs''' = <lang-name> [; ...]
'''binding''' = [prepend|append|replace] <variable-name> [<insert-text-to-prepend-variable-value>] [; ...]
The environment variables 0install should export to the process that uses this package. This makes sense only for multiple-activity-serving dependencies (like libraries), not for the activity itself.
== Auxiliary sections ==
Sections that don't describe recipe components.
=== [Build] ===
=== [Build] ===
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.
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.
== Predefined options ==
== Predefined options ==