Platform Team/Guide/Sweets Packaging

Introduction

The purpose of this Guide is describing 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 p native packages HOWTO.

If service is not just a wrapper for upstream project, please consider possibility to create service page using template.

Detailed description

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

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

• bunch of tarballs with sources and binaries, feed files contain links to these files

See 0install documentation to know more about feeds.

Services could be identified using two methods

• by name in 0sugar environment

<service>
<service>/<subservice>

• as regular 0install identifiers in 0isntall environment

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

Sugar Services maintainer process is using 0sugar tool to create proper feeds and tarballs. 0sugar uses spec file service/service.info as an scenario file(like .spec files in RPM). See also specification of service.info files.

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

Feed files in dist/ directory could be changed manually but keep in mind that dist* commands will rewrite entries for current service version.

Versioning scheme

There could be two different versioning scheme for services.

Upstream versions

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

Native versions

The rest of services will use scheme:

<version>-<revision>

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

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

Libraries have also age parameter which is 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 core differences from 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 stability statuses:

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

0sugar push w/o arguments will push local changes as is. If you want to push with 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 bugfix releases workflow.

Development workflows

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 services that contain binaries
• Upstream Services HOWTO if your activity or service uses project which is not part of Sugar Platform, follow this howto to create wrapper around upstream project and just add its name to requires section of .info file
• Wrap native packages HOWTO this is a special one, if some project is already well packaged to various GNU/Linux distributions but is not Sugar Platform component, just create "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 wrong time to release and you want to re-release it, repeat previous steps to rewrite wrong release

Bugfix releases

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

• either 0sugar push stable release once more(users will not mess this new copy of release with previous ones)
• or 0sugar push stable release with incremented version field
• if bugs are critical, mark previous release as buggy or insecure to force users 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 steps that are mentioned in previous workflows
• but use either testing or developer status for push command
• users who interested in testing(enabled testing mode) will get your new development version
• you don't have to change version all time for micro releases, 0sugar will implicitly change revision of new pushes and users will download last changes

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.

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

Documentation

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