Platform Team/Guide/Sweets Packaging

Introduction

The purpose of this Guide is to describe how to deploy your code via Sugar Services and let other people use it in simple and convenient way.

If you are looking for a method to install some software from native packages, see native packages HOWTO.

If the service is not just a wrapper for an upstream project, please consider the possibility of creating a service page using template.

Detailed description

The resulting service development process will consist of regular 0install files that are placed in a subdirectory on http://services.sugarlabs.org/ with a name that is the identity for the service in the rest of the 0sugar infrastructure. Service's subdirectory will contain:

Several .xml files that are regular 0install feeds. service.xml is the main feed for the service, other feed files are optional and represent sub services, e.g., [1].

A bunch of tarballs with sources and binaries. Feed files contain links to these files.

See the 0install documentation to learn more about feeds.

Services could be identified using two methods:

by name in the 0sugar environment

<service>
<service>/<subservice>

as regular 0install identifiers in the 0install environment

http://services.sugarlabs.org/<service>
http://services.sugarlabs.org/<service>/<subservice>.xml

To start Sugar Services developing process:

Install 0sugar tool
Read service.info file specification

and follow the rest of this document instruction about development details.

Versioning scheme

There could be two different versioning schemes for services.

Upstream versions

If the service is just a wrapper around an existing project with its own versioning scheme, then there is no need in even any mentioning of versions in the service.info file. The particular version will be chosen on every 0sugar dist* command invocation or will be fetched from native packaging systems (if the service doesn't provide binaries and only contains information about software already well-packaged in various GNU/Linux distributions).

Native versions

The rest of services will use this scheme:

<version>-<revision>

<version> is a version field from the service.info file which is a plain number.
<revision> is an auto-incremented number, which is changed by the 0sugar push command (like Subversion revision).

The commands dist and dist_bin rewrite releases with the same version versions and don't remove other releases.

Libraries have also an age parameter which is a libtool-like age version part. age won't be exposed in version string, but will be present in feed files, and 0sugar will check it while deciding what dependency version should be chosen.

Stability status

One of the core differences from the Sucrose development process is having not stable "releases" (here, release is a result of ``0sugar push`` command). So, services need stability status. Internally, each service release will have one of 0install's stability statuses:

stable, final stable release,
testing, let people interested in testing try latest changes that are not yet stable,
developer, just a more extreme version of testing,
buggy, already-released versions (of any status) could be marked as buggy after a while to force people to upgrade to a new bugfix version,
insecure, an extreme version of buggy.

0sugar push w/o arguments will push local changes as is. If you want to push with a particular stability status, use 0sugar push <status>.

By default, all users will use only stable versions and won't upgrade to new versions, even if there are stable ones. To force people to upgrade from buggy versions, see the bugfix releases workflow.

Development workflows

A Service developer can follow one of several step-by-step scenarios:

Activity specific Services HOWTO - if your activity uses its own binaries,
Binary-less Services HOWTO - to make any architecture service, e.g., python based,
Binary Services HOWTO - for services that contain binaries,
Upstream Services HOWTO - if your activity or service uses a project which is not part of Sugar Platform, follow this howto to create a wrapper around the upstream project, and just add its name to the requires section of .info file,
Wrap native packages HOWTO - this is a special one, if some project is already well packaged in various GNU/Linux distributions, but is not a Sugar Platform component, just create a "fake" service.

Release workflows

Having only stable releases

All releases of your services will have stable stability status.

when your code is ready to release,
0sugar dist* to make bundles,
0sugar push stable to rsync bundles to the server,
if it was the wrong time to release and you want to re-release it, repeat the previous steps to rewrite the wrong release.

Bugfix releases

Services assume a simple versioning scheme, if you found bugs in the stable version,

either 0sugar push stable the release once more (users will not mess this new copy of release with previous ones),
or 0sugar push stable the release with incremented version field.
If bugs are critical, mark the previous release as buggy or insecure to force users to upgrade their old releases. If you re-pushed release w/o incrementing version number, you should use revision number.

0sugar push {buggy|insecure} {version[-revision]}

Development releases

If you want to test your new version among interested people,

do all the steps mentioned in the previous workflows,
but use either the testing or developer status for the push command.
Users interested in testing (with testing mode enabled) will get your new development version.
You don't have to change the version every time for micro releases, 0sugar will implicitly change the revision of new pushes, and users will download the latest changes.

Tips

Via binding variables, a service's root directory will be accessible for service users, so for python services (for example), it is better to use a subdirectory for a service's import modules, like Toolkit does - there is a toolkit subdirectory in Toolkit's root.

Be careful with machine architecture, especially in making binaries in VMs, e.g., the XO-1 arch is i586, but built-in XO VM, binaries could have i686 and thus, won't start (0install won't allow) on XO-1. Use --arch 0sugar's argument to set targeted architecture explicitly.

Documentation