Platform Team/Guide/Sweets Packaging

Introduction

The purpose of this HOWTO is describe 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.

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.

All fields should be placed to [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
• gpg-key, identify gpg key to sign feeds, useful if there are several keys to sign
• 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

To see the full explanation of configure files format(e.g. using configure filed values in other fields) in python, see [2].

0sugar-publish tool

To start using services, install 0sugar-publish which is main tool to maintain services infrastructure.

0alias 0sugar-publish http://download.sugarlabs.org/services/0sugar-publish/feed.xml

While working, 0sugar-publish 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-publish commands are:

• init, get feed file from the server and place it to dist/
• fetch, rsync entirely dist/ from the server
• dist, create source or any arch tarball 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-publish 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 for current arch in dist/ directory and tweak dist/feed.xml correspondingly
• push, rsync dist/ to the server
• lint, check feed file on the server
  will run FeedLint application for http://download.sugarlabs.org/services/ feed

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:

• increase/change version/stability field in service.info file
• 0sugar-publish dist to change local feed in dist/ and place there tarball
• 0sugar-publish push to rsync changed files from dist/ to the server

Binary services

Work flow for services that require compilation stage:

• provide relevant value for build-command field in service.info file
• increase/change version/stability field in service.info file
• 0sugar-publish dist to add sources tarball to dist/ and change local feed correspondingly
• on every platform, you are trying to support binaries for, run 0sugar-publish dist-bin to build, and add to local field, binaries for this particular platform
• 0sugar-publish push to rsync changed files from dist/ to the server

Documentation

• Packaging guide for pure 0install packages
• Feed file format specification
• 0compile guide