Extended bundles
| Please copy/paste "{{Translationlist | xx | origlang=en | translated={{{translated}}}}}" (where xx is ISO 639 language code for your translation) to Extended bundles/translations | HowTo [ID# 90432] +/- |
There are a few different collections of objects and files that are bundled together with metadata for easy sharing and discovery. For a group of people working on bundling materials together, se the bundle project.
General bundles of content are ways to share material between nodes on a network. They might be zipped directories of files of various mimetypes, or collections or projects or files specific to one activity.
There are also extended bundles that include manifests and other metadata about their content. See Activity bundles and Content bundles. Facilities are needed for creating bundles, sharing them, and opening them and using their contents in other activities.
Introduction
Every general collection of related material in the Sugar environment is packaged into a self-contained "bundle". The bundle has a name and icon and may contain resources, including code and other files, needed to show or otherwise use the bundled materials. Resources or executable code not provided by the base system may be packaged within the bundle; the bundle may also indicate resources or activities on which it depends.
- See also
- OLPC Bitfrost in general and its section on software installation, HIG-Activities and its section on activity bundles and extended bundles
Rationale
Everything on a laptop, such as projects for an activity, recorded images or video or audio, or created text and other files, is meant to be sharable between children. Packaging sets of materials or resources together allows for a set of related work to be identified and shared as a group.
If a child doesn't have the activity used to create, edit, or view something, it should be automatically transfered to the child when he or she asks to receive a shared item. Identifying dependencies for extended bundles allows easy sharing and reuse of created work without elaborate comparisons of system components.
Location
Extended bundles are installed, opened, and removed automatically by Sugar, in response to user actions. Sugar places these bundles in a directory of its choice. These bundles should not rely on being installed in a specific location, and should use relative paths where paths are necessary. They should 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 conflicts.
To be implemented
There is an extended bundle activity that is launched when such a bundle is compiled for sharing or received.
- include note on current operation when this is implemented
- ditto any files created when an extended bundle is received or opened, to indicate it is open and in use for remixing with specific activities
Extended bundles should NEVER store local state or preferences in the extended bundle itself. These should be stored in a directory in the user's sugar profile, available through the SUGAR_PROFILE environment variable.
Bundle Structure
The extended bundle is a directory, with a name ending in ".collection". Each extended bundle must, in a subdirectory called 'collection', contain a file named "collection.info", and following a special format. For example:
monday-photos.collection/
locale/
de_DE/
collection.linfo
zh_CN/
collection.linfo
collection/
collection.info
collection-monday-photos.svg
icons/
- collection
All metadata about the extended bundle is organized in this subdirectory.
- icons
Contains icons used by the bundle while being opened and used.
.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:
[Collection] name = monday-photos collection_version = 1 host_version = 1 service_name = com.redhat.Sugar.CameraActivity icon = activity-web class = cameraactivity.CameraActivity mime_types = application/pdf;image/jpeg
A more detailed explanation of the valid properties follows:
[Collection]
- The collection.info file must begin with [Collection], and only that, on the first line of the file
name = monday-photos
- This is the name is displayed in Sugar referring to the collection. A 'name' key without a bracketed language code is the "en_US" localized name of the collection. The collection.info file must have this key.
collection_version = 1
- Each collection.info file must have a "collection_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 collection and the extended bundle activity; the only requirement of the collection is that it must be larger for new collections under the same name.
host_version = 1
- Each collection.info file must have a "host_version" key. The version is a single positive integer. This specifies the version of the Sugar environment with which the collection (and its metadata) is compatible... (fixme: need to specify sugar versions somewhere. Obviously we start with 1. see this problem in activity bundles)
service_name = com.redhat.Sugar.CameraActivity ???
- This is the collection's dbus service name... required? [TBD]. It is used as the collection's default service type when it is shared on the network. To determine this type, the distinct 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 "_CameraActivity_Sugar_redhat_com".
icon = collection-web
- It points to the collection'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 = myfactory myoptions
- something used for activity bundles that doesn't seem relevant here.
class = browseractivity.BrowserActivity
- something used for activity bundles that doesn't seem relevant here.
mime_types = application/pdf;image/jpeg
- List of mime types used by the collection, 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 collection is shown with its icon in the default extended-bundle-manager 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 launcher for the extended bundle manager, and the 'icon' key is not required.
Collection Name Localization/Translation
Localized [meta]data lives in a 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.collection/
examplecollection.py
collection/
collection.info
locale/
de_DE/
collection.linfo
de_CH/
collection.linfo
At this time, only translations for the 'name' key from the 'collection.info' file is supported. A localized 'de_DE/collection.linfo' file would look like:
[collection] name = Montag-Fotos
Keys in the languague-specific '.linfo' files selectively override keys from the 'collection.info' file; if a key is not present in the '.linfo' file the value from the 'collection.info' file is used instead.
Package
Extended bundles should be packaged as zip files with the ".xoc" extension.
Other technologies comparison
Extended bundles are similar to zip files or Java JAR files; a simple mechanism to encapsulate everything you need in a single directory that can be moved around independently, though without the notion that everything you need to understand or use elements of the extended bundle is contained within it.
As compared to klik, it's not intended to replicate a local Unix directory structure inside the package; the collection 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 some sort of dependency checking, since extended bundles are not required to be self-contained and often contain materials which derive from and can only be used with specific activities.
Use cases
Example use cases
1. Aliya wants to tag a set of 10 photographs, 2 sound recordings, and 2 text clips "Leaf Walk", and to share them with Barabbas. Barabbas receives a copy of this bundle, opens it, and tags some of the photographs as personal favorites; he also pulls the text clips and photos into an essay, and saves it as a document. He then adds photos of his own to the bundle and shares it with Aliya again (or perhaps it never stopped being shared?).
2. a Bundle Activity -- a tool for creating flat or heirarhcical structures out of different objects - perhaps from different places on one machine - and zipping them up into something that can be passed around and shared; so that they can be opened and separated into their subcomponents and stored in different places on another machine.