Difference between revisions of "Platform Team/Guide/Sweets Packaging"

Revision as of 05:32, 22 December 2010

NOTICE: This page is a draft in active flux...
Please contribute to these contents and discuss issues on the discussion page.

Writing recipe files

Package names

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

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 %(slug)s interpolation),

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

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

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

direct 0install link.

<0install-feed-url>

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

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

Versioning

The versioning scheme for Zero packages can be arbitrary, since the version recipe option supports 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 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, and since packages may at any time be rebuilt 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. The 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
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

Multiple 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. 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.

Additional components need to be placed to different sections with the same options as [Component] has:

 [Component/<name>]

Pitfalls

Devel packages

It is common practice in binary-based GNU/Linux distributions to use satellite devel packages to collect various build-time files like C headers or pkg-config files. In the 0install environment, this doesn't work, because every package is stored in a separate directory hierarchy, e.g., *.so symlinks, from devel package, will point to nothing, since all *.so.* files from the library package live in a separate directory.

Keep all build-time files in the runtime package.

@@ Line 1: / Line 1: @@
-[[Category:Zero Sugar]]
+{{Draft}}
 == Writing recipe files ==
@@ Line 44: / Line 44: @@
 * ''**'' matches everything, including directory separator
-=== Sub packages ===
+=== Multiple components ===
-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:
+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. Possible use cases:
-  [Package/<nowiki><sub-package></nowiki>]
+* 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''.
-Formatting of sub sections is identical to the ''[Package]'' section. Sub packages could make sense, e.g., for packaging additional content, or to separate a library and its script language binding.
+Additional components need to be placed to different sections with the same options as ''[Component]'' has:
-Other packages can mention sub packages by the format:
+  [Component/<nowiki><name></nowiki>]
- <package>/<nowiki><sub-package></nowiki>
-Good practise is using the following names for sub packages:
-* ''python'' for Python binding,
-* ''standalone'' if package might be used not only as a Sugar activity but also as a regular application (also, the [[Platform_Team/Recipe_Specification#.5BActivity.5D|Activity]] preset could be used for such sub packages).
-=== 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.
-The key differences between bundles and sub packages:
-* 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 bundle components are identified by the same url;
-* 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 ''bundle'' option to declare a (sub)package(s) as a bundle:
-  [Package]
-  bundle = <bundle-component-name> [; ...]
-and declare sections that contain components:
-  [<component-name>]
-  ...
-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 bundles. In that case, the different package implementations will contain the same bundle component tarball.
 == Pitfalls ==