Changes
Jump to navigation
Jump to search
Development Team/Almanac/Activity Bundles (view source)
Revision as of 18:45, 27 November 2006
, 18:45, 27 November 2006no edit summary
= 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. 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/
activity/
activity.info
activity-web.svg
localized/
de_DE.linfo
zh_CN.linfo
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)
All metadata about the activity is organized in the 'activity' subdirectory of the activity bundle.
The 'activity/localized/' directory contains localizations of the activity bundle's name. It must be present.
= .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
activity_version = 1
host_version = 1
service_name = com.redhat.Sugar.BrowserActivity
icon = activity-web
exec = sugar-activity-factory com.redhat.Sugar.BrowserActivity BrowserActivity.BrowserActivity
show_launcher = yes
A more detailed explanation of each line 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, and may only contain the characters 1 through 9. 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, and may only contain the characters 1 through 9. 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.)
service_name = com.redhat.Sugar.BrowserActivity
: This is the activity's dbus service name. 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
: This key is optional. It points to the activity's icon. The icon will be first searched for in the activity bundle's base directory, and if not found, is looked up in the current GTK icon theme. 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. Currently this is not implemented, and icons must be in the current icon theme.
exec = sugar-activity-factory com.redhat.Sugar.BrowserActivity BrowserActivity.BrowserActivity
: The exec key are used when [[Sugar]] installs the activity. It specifies the executable which [[Sugar]] runs to start the activity's factory service. A factory service spawns instances of the actual activity. A factory service for Python-based activities is provided with [[Sugar]].
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 =
Localizated data lives in the activity/localized/ directory. Localized keys from the 'activity.info' file are stored in the '.linfo' files in that directory. Each language stores its localized keys in a <u>separate</u> '.linfo' file named for the language's ISO code. For example, German-localized German (as opposed to Swiss-localized German) language translations are stored in the 'de_DE.linfo' file.
At this time, only translations for the 'name' and 'icon' keys from the 'activity.info' file are supported. A localized 'de_DE.linfo' file would look like:
name = Web
'icon' keys only need to be localized when the icon itself includes language- or culture-specific material. For example, if the icon was the first letter of a word, that word may be different in other languages and therefore would need to be localized.
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.
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. 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/
activity/
activity.info
activity-web.svg
localized/
de_DE.linfo
zh_CN.linfo
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)
All metadata about the activity is organized in the 'activity' subdirectory of the activity bundle.
The 'activity/localized/' directory contains localizations of the activity bundle's name. It must be present.
= .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
activity_version = 1
host_version = 1
service_name = com.redhat.Sugar.BrowserActivity
icon = activity-web
exec = sugar-activity-factory com.redhat.Sugar.BrowserActivity BrowserActivity.BrowserActivity
show_launcher = yes
A more detailed explanation of each line 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, and may only contain the characters 1 through 9. 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, and may only contain the characters 1 through 9. 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.)
service_name = com.redhat.Sugar.BrowserActivity
: This is the activity's dbus service name. 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
: This key is optional. It points to the activity's icon. The icon will be first searched for in the activity bundle's base directory, and if not found, is looked up in the current GTK icon theme. 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. Currently this is not implemented, and icons must be in the current icon theme.
exec = sugar-activity-factory com.redhat.Sugar.BrowserActivity BrowserActivity.BrowserActivity
: The exec key are used when [[Sugar]] installs the activity. It specifies the executable which [[Sugar]] runs to start the activity's factory service. A factory service spawns instances of the actual activity. A factory service for Python-based activities is provided with [[Sugar]].
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 =
Localizated data lives in the activity/localized/ directory. Localized keys from the 'activity.info' file are stored in the '.linfo' files in that directory. Each language stores its localized keys in a <u>separate</u> '.linfo' file named for the language's ISO code. For example, German-localized German (as opposed to Swiss-localized German) language translations are stored in the 'de_DE.linfo' file.
At this time, only translations for the 'name' and 'icon' keys from the 'activity.info' file are supported. A localized 'de_DE.linfo' file would look like:
name = Web
'icon' keys only need to be localized when the icon itself includes language- or culture-specific material. For example, if the icon was the first letter of a word, that word may be different in other languages and therefore would need to be localized.
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.