Changes

[[Category:Zero Sugar]]

[[Category:Zero Sugar]]

== Writing spec files ==

== Writing recipe files ==

See [[Activity_Team/Zero_Sugar/0sugar.recipe_Specification|0sugar.recipe specification]] at first.

See also 0sugar.recipe [[Activity_Team/Zero_Sugar/0sugar.recipe_Specification|specification]].

=== Package names ===

=== Package names ===

Within spec files, Zero packages might be identified by several methods:

Within recipe files, Zero packages might be identified by several methods:

* current package (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),

* current package (instead of a direct slug value, to make the recipe file more robust, move the ''slug'' option to the [DEFAULT] section and use {{Code|%(slug)s}} interpolation),

  <current-slug>[/<nowiki><sub-package></nowiki>]

  <current-slug>[/<nowiki><sub-package></nowiki>]

* package from default repository - http://build.sugarlabs.org,

* other packages from Bazaar that are accessible in the current project,

  <package-slug>[/<nowiki><sub-package></nowiki>]

  <other-package-slug>[/<nowiki><sub-package></nowiki>]

* direct 0install link.

* direct 0install link.

  <0install-feed-url>

  <0install-feed-url>

At the end, all links will be transfered to 0install feed urls. For default repository, the final 0install url will be composed by concatenating http://packages.sugarlabs.org/ prefix and package slug.

At the end, all links will be transfered to 0install feed urls. The final 0install url will be in format:

 

<nowiki>http</nowiki>://sweets.sugarlabs.org/<Bazaar-project>/<slug>

=== Versioning ===

=== Versioning ===

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 versioning scheme for Zero packages can be arbitrary, since the ''version'' recipe 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'' recipe 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).

The recipe 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:

Using the ''age'' option is simple, on every API breakage for the library package, increment the ''age'' value. Final package version will be:

=== Sub packages ===

=== 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:

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 recipe file should contain additional sections (per sub package) in the form:

   [Package/<nowiki><sub-package></nowiki>]

   [Package/<nowiki><sub-package></nowiki>]

* ''standalone'' if package might be used not only as Sugar activity but also as regular application (also, [[Activity_Team/Zero_Sugar/0sugar.recipe_Specification#.5BApplication.5D|Application]] preset could be used for such sub packages).

* ''standalone'' if package might be used not only as Sugar activity but also as regular application (also, [[Activity_Team/Zero_Sugar/0sugar.recipe_Specification#.5BApplication.5D|Application]] preset could be used for such sub packages).

=== Recipes ===

=== Bundles ===

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 another tarball will contain binaries for a particular platform. Thus, if an application supports several platforms, and any-arch data is big (multiple media, text, etc. files), duplicate tarballs are avoided.

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 another tarball will contain binaries for a particular platform. Thus, if an application supports several platforms, and any-arch data is big (multiple media, text, etc. files), duplicate tarballs are avoided.

The key differences between recipes and sub packages:

The key differences between bundles and sub packages:

* Sub packages are logically independent parts of the package; recipes make sense only to save storage space;

* Sub packages are logically independent parts of the package; bundles make sense only to save storage space;

* Each sub package is identified by a unique 0install url; all recipe components are identified by a recipe url;

* Each sub package is identified by a unique 0install url; all bundle components are identified by the same 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.

* Tarballs for different sub packages will be extracted to different directories; bundle component tarballs, within the same bundle, will be extracted to the same directory.

Use the ''recipe'' option to declare a (sub)package(s) as a recipe:

Use the ''bundle'' option to declare a (sub)package(s) as a bundle:

   [Package]

   [Package]

   recipe = <component-name> [; ...]

   bundle = <bundle-component-name> [; ...]

and declare sections that contain components:

and declare sections that contain components:

   ...

   ...

Recipe component sections can contain only files-related options such as ''include'', ''exclude'', ''arch'', and ''langs''.

Bundle component sections can contain only files-related options such as ''include'', ''exclude'', ''arch'', and ''langs''.

The same component could be a part of different recipes. In that case, the different package implementations will contain the same recipe component tarball.

The same component could be a part of different bundles. In that case, the different package implementations will contain the same bundle component tarball.

== Pitfalls ==

== Pitfalls ==