Changes
Jump to navigation
Jump to search
Development Team/Almanac/Activity Bundles (view source)
Revision as of 10:06, 1 September 2006
, 10:06, 1 September 2006→Bundle Structure
= 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.
= 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, currently $(prefix)/share/sugar/activities. 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). 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.
= Bundle Structure =
The activity bundle is a directory, with a name ending in ".activity". Each activity bundle must, in its root directory, contain a file named "activity.info", and following a special format. For example:
Drawing.activity/
activity.info
drawing-activity.svg
images/
sounds/
bin/
(the images, sounds, and bin subdirectories are not required, but are shown as examples of how an activity may wish to organize its resources)
= .info File Format =
.info files follow a key/value pair format, similar to the [http://www.freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec Desktop Entry standard], but not conforming to it. An example is shown here:
[Activity]
name = Web
name[de] = Web
version = 1
id = com.redhat.Sugar.BrowserActivity
icon = activity-web
python_module = BrowserActivity.BrowserActivity
exec = super-duper-web-browser
default_type = _web_olpc._udp
show_launcher = yes
A more detailed explanation of each line follows:
[Activity]
: All .info files 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 assumed to be US English. All .info files must have this key.
name[de] = Web
: This is a localized name for the activity. The language codes between the brackets are ISO language codes (fixme: need specific ISO standard).
version = 1
: Each activity must have a version key. The version is a single positive integer, and may only contain the characters 1 through 9. Larger versions are considered "newer".
id = com.redhat.Sugar.BrowserActivity
: This is the activity's dbus service name. It is required.
icon = activity-web
: This key is optional. It points to the activity's icon. The icon is first searched for in the activity bundle's root directory, and if not found, is looked up in the current GTK icon theme. It cannot contain a path.
python_module = BrowserActivity.BrowserActivity
exec = super-duper-web-browser
: The python_module and exec keys are used when [[Sugar]] installs the activity. The python_module key should point to the activity class in a python module; i.e. if running python from the root activity directory, one should be able to 'import <contents of python_module value>' successfully. If the activity is not written in Python, then the exec key should contain the executable of the activity's factory to run when launching an instance of the activity. (fixme: python_module is somewhat redundant; it should get folded into exec)
default_type = _web_olpc._udp
: Each activity must have a default type. This must follow the mDNS specification for serivce types and must be globally unique. This key is required. It is used as the service type for the mDNS service when the activity is shared.
show_launcher = yes
: This key is optional. If specified, it indicates that the activity should show in the [[Sugar]] panel launcher, represented by the activity's icon. If specified, the 'icon' key must also be specified.
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.
= 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, currently $(prefix)/share/sugar/activities. 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). 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.
= Bundle Structure =
The activity bundle is a directory, with a name ending in ".activity". Each activity bundle must, in its root directory, contain a file named "activity.info", and following a special format. For example:
Drawing.activity/
activity.info
drawing-activity.svg
images/
sounds/
bin/
(the images, sounds, and bin subdirectories are not required, but are shown as examples of how an activity may wish to organize its resources)
= .info File Format =
.info files follow a key/value pair format, similar to the [http://www.freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec Desktop Entry standard], but not conforming to it. An example is shown here:
[Activity]
name = Web
name[de] = Web
version = 1
id = com.redhat.Sugar.BrowserActivity
icon = activity-web
python_module = BrowserActivity.BrowserActivity
exec = super-duper-web-browser
default_type = _web_olpc._udp
show_launcher = yes
A more detailed explanation of each line follows:
[Activity]
: All .info files 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 assumed to be US English. All .info files must have this key.
name[de] = Web
: This is a localized name for the activity. The language codes between the brackets are ISO language codes (fixme: need specific ISO standard).
version = 1
: Each activity must have a version key. The version is a single positive integer, and may only contain the characters 1 through 9. Larger versions are considered "newer".
id = com.redhat.Sugar.BrowserActivity
: This is the activity's dbus service name. It is required.
icon = activity-web
: This key is optional. It points to the activity's icon. The icon is first searched for in the activity bundle's root directory, and if not found, is looked up in the current GTK icon theme. It cannot contain a path.
python_module = BrowserActivity.BrowserActivity
exec = super-duper-web-browser
: The python_module and exec keys are used when [[Sugar]] installs the activity. The python_module key should point to the activity class in a python module; i.e. if running python from the root activity directory, one should be able to 'import <contents of python_module value>' successfully. If the activity is not written in Python, then the exec key should contain the executable of the activity's factory to run when launching an instance of the activity. (fixme: python_module is somewhat redundant; it should get folded into exec)
default_type = _web_olpc._udp
: Each activity must have a default type. This must follow the mDNS specification for serivce types and must be globally unique. This key is required. It is used as the service type for the mDNS service when the activity is shared.
show_launcher = yes
: This key is optional. If specified, it indicates that the activity should show in the [[Sugar]] panel launcher, represented by the activity's icon. If specified, the 'icon' key must also be specified.