5,705
edits
Changes
Jump to navigation
Jump to search
Line 4:
Line 4: − + Line 17:
Line 17: − − '''repos''' = <name> <feeds-prefix> [downloads-prefix] [; ...] − − Add new or reset existing [[#Package_names|repositories]]. Attribute ''feeds-prefix'' defines a Web url prefix for 0install feeds, ''downloads-prefix'', for downloads that feeds contain (equals to ''feeds-prefix'' by default). Line 80:
Line 76: − + − + Line 97:
Line 93: − + − + Line 119:
Line 115: − + − + Line 136:
Line 132: − − === [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). − − Section uses the same options as [Package] with these additions: − − '''activity_version''' − − Option is deprecated, ''version'' should be used instead. − − '''bundle_id''' = <bundle-id> − − See [[Development_Team/Almanac/Activity_Bundles#.info_file_format|activity.info file specification]]. Option will be deprecated after implementing 0sugar in glucose and switching to identifying activities by urls (like 0install feeds). − − '''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. − − '''exec''' = <shell-command> − − Sugar will pass additional [[Development_Team/Low-level_Activity_API#Command_Line_Arguments| command line arguments]] to this command. − − '''mime_types''' = <mime-type> [; ...] − − 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> [; ...] − − 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. Line 187:
Line 153: − + Line 213:
Line 179: − + − Zero Sugar spec file options, like ''requires'', contain links to other packages. The following link formats are supported:+ − * current package to upload to ''target'' repository (instead of a direct slug value, to make the spec file more robust, move the ''slug'' option to the [DEFAULT] section and use {{Code|%(slug)s}} interpolation),+ − <slug-option-value>[/<nowiki><sub-package></nowiki>] − * package from default repository,+ − <package-name>[/<nowiki><sub-package></nowiki>] − * package from particular repository,+ − <repository>:<package-name>[/<nowiki><sub-package></nowiki>] − * direct 0install link.+ − <0install-feed-url> − At the end, all links will be transfered to 0install feed urls. Repository is just a Web url prefix like http://packages.sugarlabs.org/, the final 0install url will be composed by concatenating repository prefix and package name. Repositories might be:+ − * ''default'' or without mentioning repository name, the native GNU/Linux distributions packages from http://namedb.0install.net/;+ − * ''target'', the repository the current package will be uploaded to, equals to ''sl'' by default;+ − * ''sl'', repository hosted by Sugar Labs on http://packages.sugarlabs.org/;+ − Spec option ''repos'' can add new repositories or reset predefined ones.+ − + − The versioning scheme for Zero packages can be arbitrary, since the ''version'' spec option supports [http://0install.net/interface-spec.html#id4016582 0install version format]. But in some cases, e.g., libraries, stricter versioning could be useful. In that case, the ''age'' spec option should be used.+ − The spec option ''age'' is intended to support, mostly, API breakages of library packages. But not ABI, because tracking an ABI is not trivial within the Sugar ecosystem (due to the enormous potential code base of varying quality) and of little utility, since packages may at any time rebuild from sources and multiple library versions may be installed (thanks to 0install).+ − Using the ''age'' option is simple, on every API breakage for the library package, increment the ''age'' value. Final package version will be:+ − <age-option>.<version-option> − + − == Glob patterns ==+ − − 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) − * 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 − − == Sub packages == − − By default, package is the singular and will be composed using ''[Package]'' or/and ''[Activity]'' sections. But if the package contains several logical components, it might have sub packages. In that case, the spec file should contain additional sections (per sub package) in the form: − − [Package/<nowiki><sub-package></nowiki>] − − Format of sub sections is identical to ''[Package]'' section. Sub packages could make sense, e.g., for packaging additional content, or to separate library and its script language binding. − − Other packages can mention sub packages by the format: − − <package>/<nowiki><sub-package></nowiki> − − Good practise is using the following names for sub packages: − − * ''python'' for Python binding. − − == Recipes == − − In some cases, e.g., to save storage space or bandwidth, it is useful to split a packaged application into several tarballs when some tarballs will contain any-arch data, that are common for all platforms, and other will contain binaries for particular platform. Thus, if an application supports several platforms and any-arch data is big (various media, text, etc. files), there will not be duplicate tarballs. − − The key differences between recipes and sub packages: − * Sub packages are logically independent parts of the package; − * Each sub package is identified by unique 0install url, all recipe components are identified by recipe url; − * Tarballs for different sub packages will be extracted to different directories, recipe component tarballs, within the same recipe, will be extracted to the same directory. − − Use the ''recipe'' option to declare a (sub)package(s) as a recipe: − − [Package] − recipe = <component-name> [; ...] − − and declare sections that contain components: − − [<component-name>] − ... − − 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: − − * langs − * arch − * include − * exclude − * exec − * slots − − The same component could be a part of different recipes. In that case, different package implementations will contain the same recipe component tarball. − − == Slots == − − 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 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 package dependency, ''slots'' and appropriate ''requires'' options should be placed in the ''[Service]'' section that uses the dependency: − − requires = <dependency> − slots[<dependency>] = <versions-range> − − 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+ − 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.+
Sugar Network/Recipe Specification (view source)
Revision as of 04:28, 28 July 2010
, 04:28, 28 July 2010no edit summary
</noinclude>
</noinclude>
== 0sugar.info file ==
== Spec file sections ==
The 0sugar.info specification file is an analog of scenario files in regular GNU/Linux distributions, like .spec files in RPM. It is the cornerstone of Zero Sugar workflows, everything depends on the 0sugar.info spec file.
The 0sugar.info specification file is an analog of scenario files in regular GNU/Linux distributions, like .spec files in RPM. It is the cornerstone of Zero Sugar workflows, everything depends on the 0sugar.info spec file.
Import another spec file. Makes sense only within the [DEFAULT] section itself.
Import another spec file. Makes sense only within the [DEFAULT] section itself.
=== Common options ===
=== Common options ===
'''age''' = <age-number>
'''age''' = <age-number>
Simple number that will be used as a major number for ''version'', see [[#Versioning|versioning scheme]] for details.
Simple number that will be used as a major number for ''version'', see [[Activity Team/Zero Sugar/Packaging Guide#Versioning|versioning scheme]] for details.
'''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 [[#Versioning|different]].
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 [[Activity Team/Zero Sugar/Packaging Guide#Versioning|different]].
'''stability''' = <stability-level>
'''stability''' = <stability-level>
'''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
'''requires''' = <dependency> [(=|>=|<) <version>] [; ...]
List of [[#Package_names|dependencies]] that should exist before using the package.
List of [[Activity Team/Zero Sugar/Packaging Guide#Package_names|dependencies]] that should exist before using the package.
'''slots'''[<dependency>] = <first-dependency-version> [; ...], <last-dependency-verison>
'''slots'''[<dependency>] = <first-dependency-version> [; ...], <last-dependency-verison>
To specify dependency [[#Slots|slots]].
To specify dependency [[Activity Team/Zero Sugar/Packaging Guide#Slots|slots]].
'''binding''' = [prepend|append|replace] <variable-name> [<insert-text-to-prepend-variable-value>] [; ...]
'''binding''' = [prepend|append|replace] <variable-name> [<insert-text-to-prepend-variable-value>] [; ...]
'''include''' = <glob-pattern> [; ...]
'''include''' = <glob-pattern> [; ...]
[[#Glob patterns|Glob pattern]] for files to include to package. By default, all files are assumed.
[[Activity Team/Zero Sugar/Packaging Guide#Glob patterns|Glob pattern]] for files to include to package. By default, all files are assumed.
'''exclude''' = <glob-pattern> [; ...]
'''exclude''' = <glob-pattern> [; ...]
[[#Glob patterns|Glob pattern]] for files to exclude from package. In additional, various temporary files will be excluded like ''.bak'' or ''.pyc''.
[[Activity Team/Zero Sugar/Packaging Guide#Glob patterns|Glob pattern]] for files to exclude from package. In additional, various temporary files will be excluded like ''.bak'' or ''.pyc''.
'''langs''' = <lang-name> [; ...]
'''langs''' = <lang-name> [; ...]
* ''all'' for noarch (by default)
* ''all'' for noarch (by default)
* ''any'' for binaries to use the current architecture
* ''any'' for binaries to use the current architecture
=== [Source] ===
=== [Source] ===
'''requires''' = <dependency-name> [(=|>=|<) <version>] [; ...]
'''requires''' = <dependency-name> [(=|>=|<) <version>] [; ...]
What [[#Package_names|dependencies]] should be present before building the package from sources, in addition to ''requires'' values from the ''[Package]'' sections.
What [[Activity Team/Zero Sugar/Packaging Guide#Package_names|dependencies]] should be present before building the package from sources, in addition to ''requires'' values from the ''[Package]'' sections.
'''configure''' = <shell-command>
'''configure''' = <shell-command>
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.
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.
== Package names ==
== Presets ==
Instead of package sections (main ''[Package]'' section and sub package sections), special sections might be used. These sections extend standard ''[Package]'' options and might add special meaning of existed ones, see description for particular preset.
=== [Activity] ===
This preset 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).
Preset uses the same options as [Package] with these additions:
'''activity_version'''
Option is deprecated, ''version'' should be used instead.
'''bundle_id''' = <bundle-id>
See [[Development_Team/Almanac/Activity_Bundles#.info_file_format|activity.info file specification]]. Option will be deprecated after implementing 0sugar in glucose and switching to identifying activities by urls (like 0install feeds).
'''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.
== Versioning ==
'''exec''' = <shell-command>
Sugar will pass additional [[Development_Team/Low-level_Activity_API#Command_Line_Arguments| command line arguments]] to this command.
'''mime_types''' = <mime-type> [; ...]
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.
<!-- I like composing packages that are avoiding breakages and leakages a lot -->
'''tags''' = <tag> [; ...]
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] ===
If this preset exists, executable file will be created for native packages to launch ''main'' program or ''exec'' script. Executable file will be named by ''slug'' option value and placed to ''/usr/bin'' directory.
== Predefined options ==
== Predefined options ==