Activity bundles
Introduction
Every activity in the Sugar environment is packaged into a self-contained "bundle". The bundle contains all the resources and executable code (other than system-provided base libraries) which the activity needs to execute. Any resources or executable code that is not provided by the base system must be packaged within the bundle.
- See also
- OLPC Bitfrost in general and its section on software installation
- HIG-Activities and its section on activity bundles
- Creating an Activity bundle
Rationale
Activities are meant to be shared between children. If a child doesn't have the activity, it is automatically transfered to the child when he or she joins the shared activity. Packaging activities in self-contained bundles allows easy sharing, installation, removal, and backup.
Location
Activities are installed and removed automatically by Sugar, in response to user actions. Sugar places activities in directory of its choice. Activities should not rely on being installed in a specific location, and should use relative paths where paths are necessary (i.e., for shared library linkage, activity resources such as images, sounds, etc). They should also not rely on the bundle's base directory name remaining the same. Sugar may rename the activity bundle base directory at any time to prevent bundle conflicts.
Currently Sugar on jhbuild looks for bundles in the "activities" subfolders of XDG_DATA_DIRS. Right now this is /usr/share/activities and the usr/share/activities subfolder of the jhbuild build folder.
Sugar will automatically generate and remove the .service files necessary to launch the activity through D-Bus service activation when the activity is installed or removed.
Activities should also NEVER store local state or preferences in the activity bundle itself. These should always be stored in an activity-specific directory in the user's sugar profile, available through the SUGAR_PROFILE environment variable.
Python developers can also get the profile folder this way:
import sugar.env profile_path = sugar.env.get_profile_path()
Bundle Structure
The activity bundle is a directory, with a name ending in ".activity". Each activity bundle must, in a subdirectory called 'activity', contain a file named "activity.info", and following a special format. For example:
Web.activity/
bin/
web-activity
locale/
de_DE/
activity.linfo
zh_CN/
activity.linfo
activity/
activity.info
activity-web.svg
contents
contents.sig
mimetypes.xml
icons/
- activity
All metadata about the activity is organized in this subdirectory. The contents and contents.sig are manifest and credential files for the entire bundle contents (excepting the contents and contents.sig files themselves), as described by the Manifest Specification. The optional mimetypes.xml file is a freedesktop.org MIME type file describing how to recognize the MIME types defined by the activity.
- icons
Contains the icons used by the activity. When using the sugar.activity python package the path is automatically added to the default gtk icon theme.
.info File Format
.info files follow a key/value pair format, similar to the fd.o desktop entry spec, but not conforming to it. An example is shown here:
[Activity] name = Web activity_version = 1 host_version = 1 bundle_id = com.redhat.Sugar.BrowserActivity icon = activity-web exec = sugar-activity browseractivity.BrowserActivity -s mime_types = application/pdf;image/tiff
A more detailed explanation of the valid properties follows:
[Activity]
- The activity.info file must begin with [Activity], and only that, on the first line of the file
name = Web
- This is the name is displayed in Sugar referring to the activity. A 'name' key without a bracketed language code is the "en_US" localized name of the activity. The activity.info file must have this key.
activity_version = 1
- Each activity.info file must have a "activity_version" key. The version is a single positive integer. Larger versions are considered "newer". The value assigned to this key should be considered opaque to the activity; the only requirement of the activity is that it must be larger for new activity builds.
host_version = 1
- Each activity.info file must have a "host_version" key. The version is a single positive integer. This specifies the version of the Sugar environment which the activity is compatible with. (fixme: need to specify sugar versions somewhere. Obviously we start with 1.)
bundle_id = com.redhat.Sugar.BrowserActivity
- This is the activity bundle identifier. It is required. It is also used as the activity's default service type when the activity is shared on the network. To determine this type, the distince parts (separated by the '.' character) are reversed, any '.' is replaced by a '_' character, and the type is prefixed by a '_' character. So in this example, the default service type would be "_BrowserActivity_Sugar_redhat_com".
icon = activity-web
- It points to the activity's icon. The icon is looked up in the activity bundle's base directory. It cannot contain a path. When searching for the icon in the activity bundle's base directory, only an file with the icon name and the extension '.svg' will be looked for.
exec = sugar-activity webactivity.WebActivity
- The exec key specifies the executable which Sugar runs to start the activity instances. Environment variables given on the exec line are expanded. Executable files should be placed into the bin/ directory in the bundle. It should support the following arguments:
- -b, --bundle-id
- Identifier of the activity bundle
- -a, --activity-id
- Identifier of the activity instance.
- -o, --object-id
- Identifier of the associated datastore object.
- -u, --uri
- URI to load.
Python activities should generally use the generic sugar-activity executable. Other activities need to adhere to the Low-level Activity API.
mime_types = application/pdf;image/tiff
- List of mime types supported by the activity, separated by semi colons. It's used when opening a file from the web or to present to the user a list of activities which can open a certain journal object.
show_launcher = yes
- This key is optional. If not present, or if present with a value of "yes", the activity is shown with its icon in the Sugar panel launcher and a valid 'icon' key/value pair is required. If specified with a value of "no", the activity is not shown in the Sugar panel launcher, and the 'icon' key is not required.
Activity Name Localization/Translation
Localized data lives in the locale directory. Each language stores its localized keys in a separate directory named for the language's ISO code. Localized keys from the 'activity.info' file are stored in the 'activity.linfo' files in that directory. For example, German-localized German (as opposed to Swiss-localized German) language translations are stored in the 'de_DE/activity.linfo' file:
Example.activity/
exampleactivity.py
activity/
activity.info
locale/
de_DE/
activity.linfo
de_CH/
activity.linfo
es/
activity.linfo
At this time, only translations for the 'name' key from the 'activity.info' file is supported. A localized 'de_DE/activity.linfo' file would look like:
[Activity] name = Web
Keys in the languague-specific '.linfo' files selectively override keys from the 'activity.info' file; if a key is not present in the '.linfo' file the value from the 'activity.info' file is used instead.
Package
Activity bundles should be packaged as zip files with the ".xo" extension.
Other Technologies Comparison
Activity bundles are similar to OS X bundles or Java JAR files; a simple mechanism to encapsulate everything you need in a single directory that can be moved around independently.
It differs from autopackage, it's not a package management system. There's no central database, no scripts get run on install/uninstall. There also is no special file format.
As compared to klik, it's not intended to replicate a local Unix directory structure inside the package; the activity can still link to system provided binaries and such. There's also no server-side component other than compressing the archive and sending it over the network.There is also no dependency checking since activities are required to be self-contained.
See also
- Bundle for a generic introduction to bundles
- Activity tutorial