8,288
edits
Changes
Jump to navigation
Jump to search
Line 28:
Line 28: − + Line 48:
Line 48: − + Line 56:
Line 56: − + Line 97:
Line 97: − + − What environment variables, 0install should export to process which uses this package. Makes sense only for various activity dependencies (like libraries), not for activity itself.+ − + − + − + Line 132:
Line 132: − + − + − + − + − + − + − + − + − + − + Line 167:
Line 167: − + Line 179:
Line 179: − + − + Line 207:
Line 207: − + Line 215:
Line 215: − + Line 223:
Line 223: − What packages should be present before invoking ''exec'' command. For example if ''exec'' command generates .c files from .vala, vala dependency should be mentioned in ''requires'' option.+ − + Line 234:
Line 234: − + − + − + − + − + − + Line 254:
Line 254: − + − + Line 266:
Line 266: − + Line 279:
Line 279: − + Line 294:
Line 294: − + − + − + − + − + − + − + Line 328:
Line 328: − + Line 337:
Line 337: − + Line 353:
Line 353: − +
Sugar Network/Recipe Specification (view source)
Revision as of 09:24, 14 July 2010
, 09:24, 14 July 2010no edit summary
'''merge''' = <section-name> [; ...]
'''merge''' = <section-name> [; ...]
The same behaviour like ''inherit'' but merge values for list type options i.e. final values will consist of base-section values with adding child-section values. List options are:
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:
* category
* category
'''name''' = <package-name>
'''name''' = <package-name>
Package name in free form, equals to ''slug'' by default.
Package name, in free form, equals to ''slug'', by default.
'''summary''' = <one-line-description>
'''summary''' = <one-line-description>
'''description''' = <multi-line-description>
'''description''' = <multi-line-description>
Long descriptive text. To wrap long text, all lines after second, should start with spaces. This field is equal to ''summary'' by default.
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''' = <licence-name>
'''license''' = <licence-name>
To specify dependency [[#Slots|slots]].
To specify dependency [[#Slots|slots]].
'''binding''' = [prepend|append|replace] <variable-name> [<insert-text-to-prepand-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.
'''main''' = <path-to-exec-file>
'''main''' = <path-to-exec-file>
For applications, relative (from Zero Sugar based project) path to exec file. Doesn't make sense for packages like libraries.
For applications, the relative (from Zero Sugar based project) path to exec file. Doesn't make sense for packages like libraries.
'''exec''' = <shell-command>
'''exec''' = <shell-command>
Instead of using execution program from ''main'' option, 0sugar can bundle a script to run an arbitrary shell command.
Instead of using an executable program from the ''main'' option, 0sugar can bundle a script to run an arbitrary shell command.
'''exec'''[<script-name>] = <shell-command>
'''exec'''[<script-name>] = <shell-command>
Also, 0sugar can bundle arbitrary shell scripts. It may be useful for a 0install distribution, e.g., to pass a path to an already bundled command instead of using this command directly:
Also, 0sugar can bundle arbitrary shell scripts. It may be useful for a 0install distribution, e.g., to pass a path to an already-bundled command instead of using this command directly:
binding = replace VALADIR, PATH
binding = replace VALADIR, PATH
'''root''' = <path>
'''root''' = <path>
Could be used in conjunction with ''include''/''exclude'' to specify new root path within directory with files that will be included to package.
Could be used in conjunction with ''include''/''exclude'' to specify a new root path within a directory of files that will be included in the package.
'''arch''' = <arch>
'''arch''' = <arch>
Makes sense only for binary (sub)packages and can contain:
Makes sense only for binary (sub)packages, and can contain:
* ''*'' for noarch (by default)
* ''*'' for noarch (by default)
* ''build'' for binaries to use current architecture
* ''build'' for binaries to use the current architecture
'''packaged''' = <distro-name> <package-name> [; ...]
'''packaged''' = <distro-name> <package-name> [; ...]
If package could be installed from an official GNU/Linux distributions repository (i.e., not from packages generated from 0sugar.info spec file on OBS), use this option to let 0install know what packages names are on the particular GNU/Linux distribution.
If package could be installed from an official GNU/Linux distributions repository (i.e., not from packages generated from 0sugar.info spec file on OBS), use this option to let 0install know what package names are on the particular GNU/Linux distribution.
Distribution names could be:
Distribution names could be:
* ''rpm'' for all rpm based distros
* ''rpm'' for all rpm-based distros
* ''debian'' for deb based distros
* ''debian'' for deb-based distros
* ''gentoo'' for ebuild based distros
* ''gentoo'' for ebuild-based distros
* ''slack'' Slackware
* ''slack'' for Slackware
* ''ports'' FreeBSD Ports
* ''ports'' for FreeBSD Ports
=== [Activity] ===
=== [Activity] ===
This section 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).
This section 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).
Section uses the same options as [Package] with these additions:
Section uses the same options as [Package] with these additions:
'''icon''' = <icon-file-name-wo-suffix>
'''icon''' = <icon-file-name-wo-suffix>
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 [Package] section should be used instead.
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 [Package] section should be used instead.
'''exec''' = <shell-command>
'''exec''' = <shell-command>
'''tags''' = <tag> [; ...]
'''tags''' = <tag> [; ...]
Tags give more context in which to place the activity. This is used to allow users to find activities more easily in the Journal, the Home view, etc.
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.
=== [Source] ===
=== [Source] ===
Section makes sense only while packaging 3rd party applications.
Section makes sense only while packaging 3rd-party applications.
'''source''' = <url>
'''source''' = <url>
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.
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'' This command will be executed not only in 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
''NOTE'' This command will be executed not only in the developer's environment but also in the user's, if a proper binary wasn't found; so do not use here any development-related commands like autogen.sh
'''install''' = <shell-command>
'''install''' = <shell-command>
=== [Maintain] ===
=== [Maintain] ===
Various options that make sense only on package developer side.
Various options that make sense only in the package-developer's environment.
'''exec''' = <shell-command>
'''exec''' = <shell-command>
'''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
'''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
The packages that should be present before invoking the ''exec'' command. For example, if the ''exec'' command generates .c files from .vala, the vala dependency should be mentioned in the ''requires'' option.
== Glob patterns ==
== Glob patterns ==
A pattern could be two types:
A pattern could be of two types:
* doesn't contain ''/'' or ''**'' substrings, will be applied only to file names (not names of sub-directories within parent directory)
* doesn't contain ''/'' or ''**'' substrings, will be applied only to file names (not names of sub-directories within parent directory)
Only these pattern symbols are allowed:
Only these pattern symbols are allowed:
* ''*'' matches everything except directory separator
* ''*'' matches everything, except directory separator
* ''?'' matches any single character except directory separator
* ''?'' matches any single character, except directory separator
* ''**'' matches everything including directory separator
* ''**'' matches everything, including directory separator
== Sub packages ==
== Sub packages ==
By default, package 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:
By default, package has only one feed - ''service.xml'' which will be composed using ''[Service]'' section. But the service can have additional feeds, as well, in that case, ''service.info'' should contain additional sections (per sub feed) in the form:
[<nowiki>Service/<sub-name></nowiki>]
[<nowiki>Service/<sub-name></nowiki>]
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).
Format of sub sections is identical to ''[Service]'' section. Sub feeds could make sense, e.g., for combining non-arch data feeds and pure binary feeds (to make per-architecture implementations), or to have the packaged option for runtime packages (Service), and for *dev* packages (Service/devel).
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.
There is no need to keep a ''[Service]'' option that would apply to every sub section in every sub section. For that case, it would be easier to move common options to the ''[DEFAULT]'' section.
Other services can mention sub feeds by format:
Other services can mention sub feeds by format:
== Recipes ==
== Recipes ==
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-packages, i.e., the final service will depend on data sub-package (one implementation per application release) and sub-packages with binaries (implementations per arch per application release). But it's not possible to always use sub-packages. Applications could assume that data is placed in a particular relative path from launched binaries, and if there is no way to set data location via environment bindings, sub-packages are useless and recipes will help.
In some cases, e.g., to save storage space or bandwidth, it is useful to split a packaged application into several parts when some parts will be common. The most usual case is having any-arch data and binaries sub-packages, i.e., the final service will depend on a data sub-package (one implementation per application release) and sub-packages with binaries (implementations per arch per application release). But it's not possible to always use sub-packages. Applications could assume that data is placed in a particular relative path from the launched binaries, and if there is no way to set data location via environment bindings, sub-packages are useless and recipes will help.
Use ''recipe'' option to declare a (sub)packages as a recipe:
Use the ''recipe'' option to declare a (sub)package(s) as a recipe:
[Package]
[Package]
...
...
Being a recipe, package section cannot contain files related options (since package itself does not contain any tarballs directly, only via recipe components), these options could be set only in components:
Being a recipe, the package section cannot contain files-related options (since package itself does not contain any tarballs directly, only via recipe components), these options could be set only in components:
* root
* root
The same component could be a part of different recipes. In that case, different package implementations will contain the same recipe component tarball.
The same component could be a part of different recipes. In that case, different package implementations will contain the same recipe component tarball.
The final package implementation will contain tarball per component. All these tarballs will be unpacked to the same root directory. For example, having the following 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.
The final package implementation will contain a tarball per component. All these tarballs will be unpacked to the same root directory. For example, having the following 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 the ''[binary]'' section, and one common ''[data]'' tarball for both implementations.
[Package]
[Package]
== Slots ==
== Slots ==
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.
Slots make sense only for binary services when they could be built against several compatibility ranges for their dependencies and these dependencies could be installed from native packages.
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 be 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.
Assume that a service requires cairo, and that the source code uses a cairo feature that appeared only in v1.8, but the source code can fallback to previous cairo versions, as well. If cairo can be installed from 0install feeds, then there is no need for slots, since the service can declared as a "cairo >= 1.8" dependency, and so cairo will be installed from 0install feeds. But if cairo could be installed from native packages, there is no way to know in advance which cairo version will be present, and the service should have two implementations, one for cairo < 1.8 and one for cairo >= 1.8. In this case, slots will be useful.
To declare slots for a used dependency, ''slots'' and appropriate ''requires'' options should be placed in the ''[Service]'' section that uses dependency:
To declare slots for a package dependency, ''slots'' and appropriate ''requires'' options should be placed in the ''[Service]'' section that uses the dependency:
requires = <dependency>
requires = <dependency>
slots[<dependency>] = <versions-range>
slots[<dependency>] = <versions-range>
Option ''slots'' will declare compatibility ranges for particular dependency. Only one, closed from both sides, range can be used. For example in cairo case, it could be:
Option ''slots'' will declare compatibility ranges for a particular dependency. Only one, closed from both sides, range can be used. For example, in the cairo case, it could be:
1.0, 1.8, 2.0
1.0, 1.8, 2.0
1.0 (it could be 0.0 as well) version restricts ranges from the left and 2.0 (most likely v2.0 will not be backwards compatible with v1.x) from the right, so only two ranges can 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.
The 1.0 (it could be 0.0 as well) restricts the version range from the left and the 2.0 (most likely v2.0 will not be backwards compatible with v1.x) from the right; so only two ranges can be chosen, 1.0 >= x < 1.8, 1.8 >= x < 2.0. While building binaries for the ''0sugar build'' command, 0sugar will detect what the current cairo version is (the service that it is building/linking against), and will choose the proper slot or fail, otherwise.
== Predefined options ==
== Predefined options ==
* ''BUILDDIR'' where build happens
* ''BUILDDIR'' where the build happens
* ''SRCDIR'' path to directory with sources; for custom (via 0compile) build, ''BUILDDIR'' and ''SRCDIR'' are different, while building on OBS, the same
* ''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
* ''DISTDIR'' temporary path to place installed files before bundling them
* ''PREFIX'' prefix path for installed files, e.g., /usr
* ''PREFIX'' prefix path for installed files, e.g., /usr
* ''LANG'' current language while building per language implementation
* ''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.
Also, during the ''0sugar build'' command invocation, ''0sugar'' exports the environment variables that should be used in ''exec'' options, for example, to implement a conditional build.
* ''ZSUGAR_<argument-in-upper-case>'' map ''0sugar'' long command line arguments
* ''ZSUGAR_<argument-in-upper-case>'' map ''0sugar'' long command line arguments
=== Python activity ===
=== Python activity ===
Python based activity with standard Sugar Platform dependencies.
Python-based activity with standard Sugar Platform dependencies.
[Activity]
[Activity]
=== Python library ===
=== Python library ===
Package python based library that could be used as is or as an activity dependency.
Package python-based library that could be used as is, or as an activity dependency.
[Package]
[Package]