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

Revision as of 15:42, 30 September 2011

Summary

This guide describes how to prepare software projects to be distributed via Sugar Labs' Packaging Management System, Sweets.

Make sure that you read the introduction page and Usage guide. To understand conceptual ideas, read the Glossary.

Prepare the environment

Using the Usage guide's instructions, install the Sweets. In addition, Sweets might be used from sources:

git clone git://git.sugarlabs.org/sdk/sweets.git
cd sweets
git submodule init
git submodule update
./sweets upgrade

The command ./sweets upgrade might require relogin from the X session to take into account the new PATH value.

Recipe files

The recipe specification file is an analog of scenario files in regular GNU/Linux distributions, like .spec files in RPM. It is the cornerstone of Sweets, everything on the sweet project level depends on the recipe file. For activities, activity/activity.info, an inherited recipe file name, is supported.

On a logical level, the entire Sweets infrastructure might be treated as a set of distribution bundles with sources that contain recipe files. Software projects are identified as Zero Install interfaces that contain information about which distribution bundle needs to be downloaded in order to launch a particular software version. That's not the full picture (there are binary bundles created based on sources), but it is useful for this topic's purpose. Read the Development with Sweets section to learn about the available usage scenarios.

A recipe file is an ini format configuration file that might consist of several sections:

One or more use case sections.
Optional archive sections.
Optional auxiliary sections.
Optional [DEFAULT] section with common options that are accessible from all other sections.

These files need to be placed in the root sources directory with names sweets.recipe or activity/activity.info for Sugar activities.

Writing recipe files

In sources directory, create a recipe file, e.g., using sweets init command. Recipe file should contain at least one use case section. There are several types of use case sections:

Activity for Sugar activities,
Application for stand alone applications,
Library for libraries.

Make sure that all required options were set. The implement option has a special meaning, it is an identifier of the sweet.

By default, the entirely sources directory will be packaged into sources tarball. In case if sources list needs to be restricted, add Source section with appropriate include and/or exclude options.

If the sweet needs to be built, add Build section.

If built files are platform dependent, add Archive section with arch=any option.

Examples

A list of recipe examples.

Python activity

Python-based activity with standard Sugar Platform dependencies.

[Activity]
implement = cartoon-builder
name      = Cartoon Builder
summary   = Create your own cell-animation sequences
license   = GPLv2+
homepage  = http://wiki.sugarlabs.org/go/Activities/Cartoon_Builder

version   = %(activity_version)s
stability = stable

icon      = activity-cartoonbuilder
exec      = sugar-activity activity.CartoonBuilderActivity

# Backwards compatibility of original activity.info options
bundle_id = com.ywwg.CartoonBuilderActivity
activity_version = 7

Python library

A python-based library that could be used as is, or as an activity dependency.

[Library]
implement = libjournal
name      = libjournal
summary   = Hight level library to create your own Journal-like activity
license   = GPLv3+
homepage  = http://wiki.sugarlabs.org/go/Activity_Team/Services/Journal
version   = 1
stability = testing
requires  = toolkit
binding   = PYTHONPATH

C-based library

[DEFAULT]
depends   = base/glib; base/gconf; base/libgee >= 0.5; base/gtk+ >= 2.12
            base/pango >= 1.20; base/librsvg

[Library]
implement = polyol
name      = polyol
summary   = Intermediate level GObject based libraries for Sugar
description = Polyol is a set of libraries that are written in Vala.
            Libraries are intended to provide high-level C API to basic Sugar
            features including Gtk based user interface. Applications that are
            linked against Polyol, interact with sugar processes
            (like shell, datastore, etc.) via DBus.
license   = LGPLv3+
homepage  = http://wiki.sugarlabs.org/go/Activity_Team/Polyol

version   = 1
stability = developer

binding   = LD_LIBRARY_PATH lib
            PKG_CONFIG_PATH lib/pkgconfig
            VAPIDIR share/vala/vapi
requires  = %(depends)s

[Archive]
arch      = any

[Build]
requires  = %(depends)s; pkg-config; cmake; make; gcc-c
configure = cmake -D CMAKE_INSTALL_PREFIX=%(PREFIX)s
                  -D PYTHON_SITEDIR=%(PREFIX)s/python
                  -D COMPONENTS="collab;ds;env;gui;shell;toolkit"
                  -D BINDING=python
                  -D CMAKE_C_FLAGS:STRING="%(CFLAGS)s"
                  .
make      = make
install   = make DESTDIR=%(DESTDIR)s install

Development with Sweets

Source bundles might be used on a client side not only indirectly, via sweets command for example, but also explicitly. Sources might be bundled, emailed, etc. In this case, it is no different from .xo files. To make sources useful within Sweets, the local directory with sources might be used in several ways:

Applications might be launched from sources, sweets <path-to-sources>;
To reuse sources as dependencies for other sweets, source directory needs to be registered in Sweets, sweets checkout <path-to-sources>; applications might be checked out as well.

Checking out will register a sweet in the local Sweets instance as a single implementation for the interfaces it implements. This feature is especially useful for libraries, for example, if the sugar-toolkit sources, which implement the sdk/sugar-toolkit interface, were cloned to the ~/src/sugar-toolkit directory, then, while running a sdk/sugar sweet, it would become possible to reuse local sugar-toolkit sources as a regular implementation of the sdk/sugar-toolkit dependency of sdk/sugar.

Feedback

Submit your bug report.
Ask your question on IRC channels, #sugar (not logged) or #sugar-newbies (logged).

@@ Line 17: / Line 17: @@
 The command {{Code|./sweets upgrade}} might require relogin from the X session to take into account the new PATH value.
-== Writing recipe files ==
+== Recipe files ==
 The recipe specification file is an analog of scenario files in regular GNU/Linux distributions, like {{Code|.spec}} files in RPM. It is the cornerstone of Sweets, everything on the sweet project level depends on the recipe file. For activities, {{Code|activity/activity.info}}, an inherited recipe file name, is supported.
@@ Line 31: / Line 31: @@
 These files need to be placed in the root sources directory with names {{Code|sweets.recipe}} or {{Code|activity/activity.info}} for Sugar activities.
+== Writing recipe files ==
+In sources directory, create a recipe file, e.g., using {{Code|sweets init}} command. Recipe file should contain at least one [[Platform_Team/Recipe_Specification#Use case sections|use case]] section. There are several types of use case sections:
+* ''Activity'' for Sugar activities,
+* ''Application'' for stand alone applications,
+* ''Library'' for libraries.
+Make sure that all required options were set. The ''implement'' option has a special meaning, it is an [[Platform_Team/Sweets_Glossary#Implemented_interfaces|identifier]] of the sweet.
+By default, the entirely sources directory will be packaged into sources tarball. In case if sources list needs to be restricted, add [[Platform_Team/Recipe_Specification#.5BBuild.5D|Source]] section with appropriate ''include'' and/or ''exclude'' options.
+If the sweet needs to be built, add [[Platform_Team/Recipe_Specification#.5BBuild.5D|Build]] section.
+If built files are platform dependent, add [[Platform_Team/Recipe_Specification#Archive_sections|Archive]] section with ''arch=any'' option.
 === Examples ===