Platform Team/Guide/Sweets Packaging

Introduction

The purpose of this Guide is describing how to get benefits of Sugar Services for your library/application, simplify support fork flows and let your users(developers) use your code in simple and convenient way.

Services are just a set of definitions for urls and names for 0install feeds, it provides to activity developers convenient way to use services. But regular 0install work flow still works. The rest of document describes sugar specific work flow to meet 0sugar benefits.

Detailed description

The result for service development process will be regular 0install files that are placed to subdirectory on http://download.sugarlabs.org/services/ with name which is identity for the service in the rest of 0sugar infrastructure:

runtime.xml, regular 0install feed file which will be used as a runtime dependency
buildtime.xml, regular 0install feed file which will be used as a buildtime dependency
bunch of tarballs with sources and binaries, feed files contain links to these files

Feed files, in addition to several information fields, contains tags that describe implementations of the service, in distribution terms, package. At the same time, feed file contains implementations for various service versions and the same version could be represented by several implementations:

source implementation in <implementation> tag with attribute arch == *-src, with links to source tarball and instructions how to build it
no arch implementation in <implementation> tag with attribute arch == *-*, which can be used as-is on different platforms e.g. pure python services
one or several binary implementations in <implementation> tags, that contain binaries of the same source implementation but for various architectures(attribute arch)
package implementation in <package-implementation> tag, to reuse native packages, see Native packages usage for more info.

service.info file

Service publishing work flow is similar to activities. There is an info file, here service/service.info, which describes current status(not history) of development process. All these fields, finally, go to feed file while publishing new version.

Service section

Service.info file should contain at least [Service] section:

name, the identity of service, this field defines name of feed's root directory on the server http://download.sugarlabs.org/services/ as well
summary, short descriptive line
description, long descriptive line, to wrap long text, all lines after second, should start with spaces
homepage
version, current version
stability, level of stability for version, see [1]
license, in 0install, typically a Trove category, as used on freshmeat.net, but could be fedora names, since the rest of sugar uses them
binding, what environment variables, 0sugar should export to session which uses this service

binding = [prepend|append|replace] <variable-name> [<insert-text-to-prepand-variable-value>] [; ...]

main, for applications, path to exec file from service root directory
build-command, for services that have compilation stage, command how to build binaries
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 service developer environment but also on user side if proper binary wasn't found, so do not use here any development related dependencies like autogen.sh
For example, followed command builds regular autotools based project

"$SRCDIR"/configure --prefix="$DISTDIR" && make install

requires, for any arch and binary implementations, list of runtime services that should exist before using service

requires = <service-name> [<not-before-version>[-<before-version>]] [; ...]

build-requires, what services should be installed before building service from sources

build-requires = <service-name> [<not-before-version>[-<before-version>]] [; ...]

Buildtime section

Service.info file could have optional Buildtime section which describe additional parameters that should be taken into account during other service(which uses this one) building e.g. C headers files. Section can contain:

requires, additional dependencies that will be required for building of other service

Support several ABIs of service dependencies

Service.info file could contain other sections for various binary implementations. These sections are intended to describe particular dependencies environment and should contain only:

requires that overwrite Service's section requires

For example if service developer is going to add binary implementations for f9/f11, and the same service dependency in these distributions has different ABIs, activity developer has to build two additional binaries, for f9 and f11. In that case developer creates two sections F9 and F11, put exact dependency versions(to separate particular section from others) and invoke 0sugar dist_bin <section-name> in proper f9/f11 environment.

0sugar tool

To start developing services, install injector tool, and 0sugar - main tool to maintain services infrastructure.

0alias 0sugar http://download.sugarlabs.org/services/0sugar/runtime.xml

While working, 0sugar creates dist/ directory in project's root and uses it as a rsynced copy of service's directory on the server. So, you need ssh access to sunjammer server, create ticket for shell.sugarlabs.org category on http://bugs.sugarlabs.org/.

0sugar commands are:

init, create service/ directory and default service.info file
clone, rsync entirely dist/ from the server
dist, create source or any arch tarball/implementation in dist/ directory and tweak dist/feed.xml correspondingly
If there is second option-less argument, it will be treated as a path of tarball to release(e.g. you can create such tarball by make distcheck command for autotools based projects), otherwise 0sugar will tar all project files(and try to avoid temporary files as much as possible)
dist will create
- any arch archive, if build-command field was omitted in service.info
- source archive, if service.info has build-command field
dist_bin, create binary tarball/implementation for current arch in dist/ directory and tweak dist/feed.xml correspondingly
if second argument was passed, it will be treated as a name of service.info section with additional requires fields
push, rsync dist/ to the server
lint, check feed file on the server
will run FeedLint application for http://download.sugarlabs.org/services/ feed

Workflows

How to build services.

Any arch services

Work flow for services that don't require compilation stage thus could be just packaged and used as is on server side:

create local initial service.info by invoking 0sugar init, tweak newly created service/service.info file
increase/change version/stability field in service.info file
0sugar dist to change local feed in dist/ and place there tarball
0sugar push to rsync changed files from dist/ to the server

Binary services

Work flow for services that require compilation stage:

create local initial service.info by invoking 0sugar init, tweak newly created service/service.info file
provide relevant value for build-command field in service.info file
if you want to support binaries for different dependencies environments, add additional sections to service.info file with requires fields that describe dependencies versions of particular environment
increase/change version/stability field in service.info file
0sugar dist to add sources tarball to dist/ and change local feed correspondingly
on every platform, you are trying to support binaries for, run 0sugar dist_bin to build, and add to local field, binaries for this particular platform
if you added additional sections to service.info, run 0sugar dist_bin <section-name> in every environment, services.info has additional sections for
0sugar push to rsync changed files from dist/ to the server

Versioning scheme

Services are welcome to use(fully or partially) API changes based versioning scheme (except obvious cases then service is a wrapper to native package).

<major-version>.<minor-version>.<micro-version>

the major version starts from 0(premature state) and exposes the fact of API backwards compatibility breakage
the minor version reflect on adding new features that don't break backwards compatibility
the micro version is a build number

Commands like dist and dist-bin don't remove previous versions from feed(you still can manually remove them from dist/*.xml) so, new release doesn't break code which depends on your service.

NOTE: Be careful, some services and activities could be stuck to particular versions(major versions) of your service, so do not delete stable releases if they still work in declared sugar environments.

Tips

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