5,705
edits
Changes
Sugar Network/Recipe Specification (view source)
Revision as of 12:54, 25 December 2010
, 12:54, 25 December 2010no edit summary
Recipe file is an [http://docs.python.org/library/configparser.html ini] format configuration file that might consist of several sections:
Recipe file is an [http://docs.python.org/library/configparser.html ini] format configuration file that might consist of several sections:
* One or more [[#Component sections|component sections]].
* One or more [[#Use case sections|use case sections]].
* Optional auxiliary sections:
* Optional [[#Archive sections|archive sections]].
* Optional [[#Auxiliary sections|auxiliary sections]].
** [[#.5Bsource.5D|[Source]]].
* Optional {{Code|[DEFAULT]}} section with common options that are accessible from all other sections.
* Optional {{Code|[DEFAULT]}} section with common options that are accessible from all other sections.
== Component sections ==
== Use case sections ==
Recipe should contain at least one component section. Component sections describe how the sweet might be used and can be one of [[#Component_types|predefined types]].
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 followed sub sections and ''sub-name'' is an optional identifier if there are more than one sections of the same type.
Regardless of the type, use case section (or one of them) should contain followed options:
Regardless of the type, component section (or one of them) should contain followed options:
'''sweet''' = <identifier>
'''sweet''' = <identifier>
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.
Required. An identifier of the sweet. 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:
* in native package names generated from the recipe.
* in native package names generated from the recipe.
Important note: The ''sweet'' is not intended to be unique. That means that there may be several implementations for the same ''sweet'' in the field. They might be different versions of the package from the same developer, or even separate implementations from other developers.
Important note: The ''sweet'' is not intended to be unique. That means that there may be several implementations for the same ''sweet'' in the field. They might be different versions of the sweet from the same developer, or even separate implementations from other developers.
'''name''' = <package-name>
'''name''' = <name>
Optional. Package name, in free form text. (It is equal to the ''sweet'', by default.)
Optional. Free form name. (It is equal to the ''sweet'', by default.)
'''summary''' = <one-line-description>
'''summary''' = <one-line-description>
'''license''' = <license-name>
'''license''' = <license-name>
Required. Package license. Short license names from [http://fedoraproject.org/wiki/Licensing Fedora naming scheme] are welcome.
Required. The license. Short license names from [http://fedoraproject.org/wiki/Licensing Fedora naming scheme] are welcome.
'''homepage''' = <url>
'''homepage''' = <url>
Required. Packaged project home page.
Required. Sweet project home page.
'''icon''' = <icon-file-name>
'''icon''' = <icon-file-name>
Optional. Path to package icon file starting from the path where the recipe file is located.
Optional. Path to the icon file starting from the path where the recipe file is located.
'''category''' = <category> [; ...]
'''category''' = <category> [; ...]
Optional. 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 sweet using values defined by [http://standards.freedesktop.org/menu-spec/latest/apa.html freedesktop.org menu specification].
'''version''' = <version-number>
'''version''' = <version-number>
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]].
Required. Current version of the sweet 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>
* testing
* testing
* stable
* stable
=== [Activity] ===
=== [Activity] ===
'''tags''' = <tag> [; ...]
'''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.
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.
'''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
Optional. List of [[Platform_Team/Guide/Packaging#Package_names|dependencies]] that should exist in run-time before launching the activity.
=== [Application] ===
=== [Application] ===
'''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 package 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.
'''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
Optional. List of [[Platform_Team/Guide/Packaging#Package_names|dependencies]] that should exist in run-time before launching the application.
=== [Library] ===
=== [Library] ===
'''binding''' = [prepend|append|replace] <variable-name> [<insert-text-to-prepend-variable-value>] [; ...]
'''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.
The environment variables 0install should export to the process that uses this sweet. This makes sense only for multiple-activity-serving dependencies (like libraries), not for the activity itself.
'''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
Optional. List of [[Platform_Team/Guide/Packaging#Package_names|dependencies]] the library is based on.
== Archive sections ==
Archive section describe the tarball that will contain sweet implementation.
If there are no any archive sections, the sweet implementation consist of only one archive that includes the entirely {{Code|%(DESTDIR)s}} directory (excluding temporary files). At the same time, the sweet implementation might be split into several archives.
Possible use cases:
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.
* 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 archive sections are named:
[Archive[:''sub-name'']]
And contain followed options:
'''include''' = <glob-pattern> [; ...]
Optional. [[Platform_Team/Guide/Packaging#Glob patterns|Glob pattern]] for files to include to the archive. 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 archive. 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, archives. 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 archives, and can contain:
* ''all'' for noarch (by default)
* ''any'' for binaries to use the current architecture
== Auxiliary sections ==
== Auxiliary sections ==
=== [Build] ===
=== [Build] ===
This section is required if package needs additional work to prepare ready-to-use installation. To prepare valid Zero packages, it is important to use [[#Predefined_options|predefined constants]] for options that contain shell commands. All shell commands will be executed from {{Code|%(BUILDDIR)s}} directory.
This section is required if sweet needs additional work to prepare 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 {{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-name> [(=|>=|<) <version>] [; ...]
'''requires''' = <dependency-name> [(=|>=|<) <version>] [; ...]
What [[Platform_Team/Guide/Packaging#Package_names|dependencies]] should be present before building the package from sources. Note that ''requires'' from [[#.5BComponent.5D|[Component]]] sections are not auto included to build-time dependencies.
What [[Platform_Team/Guide/Packaging#Package_names|dependencies]] should be present before building the sweet from sources. Note that ''requires'' from [[#.5BComponent.5D|[Component]]] sections are not auto included to build-time dependencies.
'''configure''' = <shell-command>
'''configure''' = <shell-command>
'''implement''' = <shell-command>
'''implement''' = <shell-command>
An analog of ''install'' command that will be used, if present, instead of ''install'' while building the package in the local environment.
An analog of ''install'' command that will be used, if present, instead of ''install'' while building the sweet in the local environment.
=== [Source] ===
=== [Source] ===
How to create sources tarball. Options make sense only in the package-developer's environment.
How to create sources tarball. Options make sense only in the developer's environment.
'''url''' = <url>
'''url''' = <url>
'''exec''' = <shell-command>
'''exec''' = <shell-command>
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.
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 sweet root directory.
'''include''' = <glob-pattern> [; ...]
'''include''' = <glob-pattern> [; ...]
'''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
'''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
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 dependencies that should be present before creating sources tarball. For example, if the ''exec'' command generates .c files from .vala, the vala dependency should be mentioned in the ''requires'' option.
== Predefined options ==
== Predefined options ==
=== C-based library ===
=== C-based library ===
[DEFAULT]
[Library]
sweet = polyol
sweet = polyol
summary = Intermediate level GObject based libraries for Sugar
summary = Intermediate level GObject based libraries for Sugar
stability = testing
stability = testing
binding = LD_LIBRARY_PATH lib
binding = LD_LIBRARY_PATH lib
PKG_CONFIG_PATH lib/pkgconfig
PKG_CONFIG_PATH lib/pkgconfig
VAPIDIR share/vala/vapi
VAPIDIR share/vala/vapi
requires = glib; gconf; libgee >= 0.5; gtk+ >= 2.12; pango >= 1.20; librsvg
[Component/python]
[Archive]
arch = any
arch = any