Development Team/Almanac/Activity Bundles - Revision history

Quozl: .info file format, deprecate some parts, refer to specification in git

2018-06-03T22:16:10Z

.info file format, deprecate some parts, refer to specification in git

← Older revision		Revision as of 18:16, 3 June 2018
Line 71:		Line 71:
	== .info file format ==		== .info file format ==

	See [https://github.com/sugarlabs/sugar-toolkit-gtk3/blob/master/src/sugar3/bundle/__init__.py sugar3/bundle] for the ~~file format, with keys and values~~.		See [https://github.com/sugarlabs/sugar-toolkit-gtk3/blob/master/src/sugar3/bundle/__init__.py sugar3/bundle] for the latest bundle metadata specification.

	~~.info files follow a key/value pair format~~, ~~similar to~~ the ~~[http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec fd.o desktop entry spec], but not conforming to it~~. ~~An example is shown here:~~		This section below deprecated, but has some useful historical information that goes beyond what the specification needs.

	~~[Activity]~~		Some additional comments on the key;
	~~name = Browse~~
	~~activity_version = 156~~
	~~bundle_id = org.laptop.WebActivity~~
	~~icon = activity-web~~
	~~exec = sugar-activity webactivity.WebActivity -s~~
	~~mime_types = image/png;image/gif;image/jpeg;text/html;text/uri-list;application/xhtml+xml;application/rss+xml;application/xml;text/css~~
	~~license = GPLv2+~~
	~~summary = Surf~~ the ~~world! Here you can do research, watch educational videos, take online courses, find books, connect with friends and more.~~
	~~update_url = http://host.net/bundles/FooBar~~
	~~tags = exploration~~;~~web~~
	~~single_instance = no~~
	~~max_participants = 4~~
	~~repository = https://github.com/sugarlabs/browse-activity~~

	A ~~more detailed explanation~~ of the ~~valid properties follows:~~		name
			: A 'name' key without a bracketed language code is the "en_US" localized name of the activity.

	~~[Activity]~~		activity_version
	: ~~The~~ activity~~.info file must begin with [Activity]~~, and ~~only that, on the first line of the file~~		: An activity should not use the value in source code, as it may be changed by developers and packagers.

	~~name = Browse~~		bundle_id
	: 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.		: The name should conform to the [http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names D-Bus spec] - in particular, hyphens are not allowed. It is recommended that [http://en.wikipedia.org/wiki/Java_package#Package_naming_conventions Java package naming conventions] are used when choosing bundle identifiers, to ensure uniqueness. Briefly, your name should begin with the reversed domain name of an organization you belong to.

	~~activity_version = 156~~
	: Each activity.info file must have a "activity_version" key. Example versions are 1, 1.2, 1.2.3, 1.2.3-peru, and 1.2.3~me. Larger versions are considered "newer". An activity should not use the value, as it may be changed by developers and packagers. The value must be newer for newer activities.

	~~host_version = 1~~
	~~: This key is deprecated. This used to specify the version of the Sugar environment the activity is compatible with; however, it was never implemented.~~

	bundle_id ~~= org.laptop.WebActivity~~
	: ~~This is the activity bundle identifier. It is required.~~ The name should conform to the [http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names D-Bus spec] - in particular, hyphens are not allowed ~~(although this wasn't enforced in earlier builds, see [http://dev.laptop.org/ticket/6226 Trac 6226])~~. It is recommended that [http://en.wikipedia.org/wiki/Java_package#Package_naming_conventions Java package naming conventions] are used when choosing bundle identifiers, to ensure uniqueness. Briefly, your name should begin with the reversed domain name of an organization you belong to.
	: The reversed domain name part is supposed to be rooted in some actual DNS-rooted namespace. You don't need to own this domain; you just need to have a reasonable claim on some ''unique'' name at that domain. There are several ways to derive one:		: The reversed domain name part is supposed to be rooted in some actual DNS-rooted namespace. You don't need to own this domain; you just need to have a reasonable claim on some ''unique'' name at that domain. There are several ways to derive one:
	:* If your email address is ''yourname''@''somemailhost''.com, then you could use ''com.somemailhost.yourname''.''YourActivity''.		:* If your email address is ''yourname''@''somemailhost''.com, then you could use ''com.somemailhost.yourname''.''YourActivity''.
Line 112:		Line 91:
	: In the Python bindings, the bundle_id is also used as the activity's default service type when the activity 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 "_WebActivity_laptop_org".		: In the Python bindings, the bundle_id is also used as the activity's default service type when the activity 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 "_WebActivity_laptop_org".

	license ~~= GPLv2+~~		license
	: This field names the licenses used for the activity bundle (the binary .xo file). For multiple licenses, separate them with semicolons ";". Otherwise, the value should conform to the same guidelines as the [http://fedoraproject.org/wiki/Packaging/LicensingGuidelines#License:_field <code>License:</code> field] of an RPM package; consult the [http://fedoraproject.org/wiki/Packaging/LicensingGuidelines Fedora Licensing Guidelines] for more information. A 'license' field naming an entry or entries in the "Good Licenses" table at [http://fedoraproject.org/wiki/Licensing Fedora's Licensing list] is required for any activities distributed by Sugar Labs.		: This field names the licenses used for the activity bundle (the "binary" .xo file). For multiple licenses, separate them with semicolons ";". Otherwise, the value should conform to the same guidelines as the [http://fedoraproject.org/wiki/Packaging/LicensingGuidelines#License:_field <code>License:</code> field] of an RPM package; consult the [http://fedoraproject.org/wiki/Packaging/LicensingGuidelines Fedora Licensing Guidelines] for more information. A 'license' field naming an entry or entries in the "Good Licenses" table at [http://fedoraproject.org/wiki/Licensing Fedora's Licensing list] is required for any activities distributed by Sugar Labs.

	icon ~~= activity-web~~		icon
	: ~~It points to the activity's icon.~~ The icon is looked up in the activity bundle's 'activity' directory (the same directory the activity.info file is in). It cannot contain a path. When searching for the icon in the activity bundle's 'activity' directory, only a file with the icon name and the extension '.svg' will be looked for~~. This property is required unless 'show_launcher' is 'no' (see below)~~.		: The icon is looked up in the activity bundle's 'activity' directory (the same directory the activity.info file is in). It cannot contain a path. When searching for the icon in the activity bundle's 'activity' directory, only a file with the icon name and the extension '.svg' will be looked for.

	exec ~~= sugar-activity webactivity.WebActivity -s~~		exec
	: 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:		: 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:

Line 128:		Line 107:
	Python activities should generally use the generic sugar-activity executable. Other activities need to adhere to the [[olpc:Low-level Activity API]].		Python activities should generally use the generic sugar-activity executable. Other activities need to adhere to the [[olpc:Low-level Activity API]].

	~~mime_types = application/pdf;image/tiff~~		tags
	: 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.

	~~update_url = ...~~

	: URL to retrieve update information; implemented in [http://dev.laptop.org/ticket/4951 #4951]. The software update control panel will attempt to look for information about the latest version of the activity by fetching the given url with first the core OS build number, then the release number, then the release major version number appended, then finally as-is. (For example, if your update URL tag has the value 'http://host.net/bundles/FooBar' and you are currently running release 8.1.1 (core OS 708), the following URLs will be tried, in this order: http://host.net/bundles/FooBar/708, http://host.net/bundles/FooBar/8.1.1, http://host.net/bundles/FooBar/8.1, http://host.net/bundles/FooBar .) The contents of the URLs should be in the [[olpc:Activity microformat]]. If no update_url is specified, http://wiki.laptop.org/go/Activities will be used. See [[olpc:Software updater]] for more information.

	tags ~~= exploration;web~~
	: Tags give more context in which to place the activity. This is used to allow users to find activities more easily in the journal, the home view, [http://activities.sugarlabs.org http://activities.sugarlabs.org], etc.		: Tags give more context in which to place the activity. This is used to allow users to find activities more easily in the journal, the home view, [http://activities.sugarlabs.org http://activities.sugarlabs.org], etc.

	single_instance ~~= yes~~		single_instance
	: This key is optional. If not present, or if present with a value of "no", multiple instances of the activity can be launched at once. If present with a value of "yes", then only one instance of the activity will be open at any one time. This key was added in order to flag activities that use resources that cannot be shared.		: Added to flag activities that use resources that cannot be shared, such as a camera.

	~~max_participants = 4~~
	~~: This key is optional. If not present, or if present with a value of <=1, the activity is not shared. Otherwise~~, ~~it limits the number of participants who can join~~ a ~~shared activity. Note that setting max_participants in activity.py is deprecated~~.

	~~summary = ...~~		max_participants
	: ~~A short summary of the~~ activity is ~~displayed in the List View~~.		: Setting max_participants in activity.py is possible, but deprecated.

	repository ~~= https://...~~		repository
	: The URL of the master git repository for the activity, for use by {{code\|git clone}}. Since activities are not all hosted in a single repository, it is important to include a link so that users can readily find the activity. Some git hosting services allow the URL to be used by web browser as well as {{code\|git clone}}.		: The URL of the master git repository for the activity, for use by {{code\|git clone}}. Since activities are not all hosted in a single repository, it is important to include a link so that users can readily find the activity. Some git hosting services allow the URL to be used by web browser as well as {{code\|git clone}}.

Quozl at 21:53, 3 June 2018

2018-06-03T21:53:47Z

← Older revision		Revision as of 17:53, 3 June 2018
Line 70:		Line 70:

	== .info file format ==		== .info file format ==

			See [https://github.com/sugarlabs/sugar-toolkit-gtk3/blob/master/src/sugar3/bundle/__init__.py sugar3/bundle] for the file format, with keys and values.

	.info files follow a key/value pair format, similar to the [http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec fd.o desktop entry spec], but not conforming to it. An example is shown here:		.info files follow a key/value pair format, similar to the [http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec fd.o desktop entry spec], but not conforming to it. An example is shown here:

Quozl: /* .info file format */

2018-01-18T03:20:00Z

.info file format

← Older revision		Revision as of 23:20, 17 January 2018
Line 111:		Line 111:

	license = GPLv2+		license = GPLv2+
	: This field names the ~~license~~ used for the activity bundle (the binary .xo file). ~~The contents of this field~~ should conform to the same guidelines as the [http://fedoraproject.org/wiki/Packaging/LicensingGuidelines#License:_field <code>License:</code> field] of an RPM package; consult the [http://fedoraproject.org/wiki/Packaging/LicensingGuidelines Fedora Licensing Guidelines] for more information. A 'license' field naming an entry or entries in the "Good Licenses" table at [http://fedoraproject.org/wiki/Licensing Fedora's Licensing list] is required for any activities distributed by ~~OLPC~~.		: This field names the licenses used for the activity bundle (the binary .xo file). For multiple licenses, separate them with semicolons ";". Otherwise, the value should conform to the same guidelines as the [http://fedoraproject.org/wiki/Packaging/LicensingGuidelines#License:_field <code>License:</code> field] of an RPM package; consult the [http://fedoraproject.org/wiki/Packaging/LicensingGuidelines Fedora Licensing Guidelines] for more information. A 'license' field naming an entry or entries in the "Good Licenses" table at [http://fedoraproject.org/wiki/Licensing Fedora's Licensing list] is required for any activities distributed by Sugar Labs.

	icon = activity-web		icon = activity-web

Quozl at 20:58, 15 December 2017

2017-12-15T20:58:41Z

← Older revision		Revision as of 16:58, 15 December 2017
Line 193:		Line 193:

	sugar-activity model_app.ModelActivity		sugar-activity model_app.ModelActivity

	Make sure to add your shell script and any native libraries to the MANIFEST before you package your bundle. You can also accomplish the same thing by throwing all your libraries in the root folder of the bundle, like the [[olpc:Map_(activity)\|Map activity]] does, but if you have more than a few libraries to include it can get quite cluttered.


	== activity/permissions.info ==		== activity/permissions.info ==

Quozl at 01:40, 18 July 2017

2017-07-18T01:40:19Z

← Older revision		Revision as of 21:40, 17 July 2017
Line 97:		Line 97:

	activity_version = 156		activity_version = 156
	: Each activity.info file must have a "activity_version" key. ~~The version is a single positive float~~. 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~~.		: Each activity.info file must have a "activity_version" key. Example versions are 1, 1.2, 1.2.3, 1.2.3-peru, and 1.2.3~me. Larger versions are considered "newer". An activity should not use the value, as it may be changed by developers and packagers. The value must be newer for newer activities.

	host_version = 1		host_version = 1

Quozl: /* .info file format */

2016-05-24T21:59:47Z

.info file format

← Older revision		Revision as of 17:59, 24 May 2016
Line 148:		Line 148:
	: A short summary of the activity is displayed in the List View.		: A short summary of the activity is displayed in the List View.

	repository = ~~http~~://...		repository = https://...
	: The URL of the master git repository for the activity. Since activities are not all hosted in a single repository, it is important to include a link so that users can readily find the activity ~~source~~.		: The URL of the master git repository for the activity, for use by {{code\|git clone}}. Since activities are not all hosted in a single repository, it is important to include a link so that users can readily find the activity. Some git hosting services allow the URL to be used by web browser as well as {{code\|git clone}}.

	== Localization/translation of the activity name and tags ==		== Localization/translation of the activity name and tags ==

Walter: /* .info file format */

2016-05-15T23:46:43Z

.info file format

← Older revision		Revision as of 19:46, 15 May 2016
Line 86:		Line 86:
	single_instance = no		single_instance = no
	max_participants = 4		max_participants = 4
			repository = https://github.com/sugarlabs/browse-activity

	A more detailed explanation of the valid properties follows:		A more detailed explanation of the valid properties follows:
Line 146:		Line 147:
	summary = ...		summary = ...
	: A short summary of the activity is displayed in the List View.		: A short summary of the activity is displayed in the List View.

			repository = http://...
			: The URL of the master git repository for the activity. Since activities are not all hosted in a single repository, it is important to include a link so that users can readily find the activity source.

	== Localization/translation of the activity name and tags ==		== Localization/translation of the activity name and tags ==

Godiard: /* Bundle structure */

2015-01-15T13:00:10Z

Bundle structure

← Older revision		Revision as of 09:00, 15 January 2015
Line 39:		Line 39:
	text-plain.svg (icons for documents, e.g. "text-plain.svg" for "text/plain")		text-plain.svg (icons for documents, e.g. "text-plain.svg" for "text/plain")
	text-html.svg		text-html.svg
	~~contents (manifest for bundle contents -- not supported by Sugar)~~
	~~contents.sig (credentials for signed bundle -- not supported by Sugar)~~
	~~permissions.info (optional; '''not a stable API''')~~
	bin/		bin/
	web-activity (launcher script or activity executable)		web-activity (launcher script or activity executable)

Godiard: /* activity/permissions.info */

2015-01-15T12:59:09Z

activity/permissions.info

← Older revision		Revision as of 08:59, 15 January 2015
Line 198:		Line 198:
	== activity/permissions.info ==		== activity/permissions.info ==

	'''Note: the API described in this section is ~~NOT STABLE and will probably change in future releases; perhaps drastically~~.'''		'''Note: the API described in this section is DEPRECATED.'''

	Bitfrost describes a variety of security-related settings which activity authors can specify about their activity. At the option of the activity author, these settings can be described in a file called 'permissions.info' which can be placed alongside 'activity.info' in the 'activity' directory of the bundle.		Bitfrost describes a variety of security-related settings which activity authors can specify about their activity. At the option of the activity author, these settings can be described in a file called 'permissions.info' which can be placed alongside 'activity.info' in the 'activity' directory of the bundle.

Walter: /* .info file format */

2014-05-02T14:47:18Z

.info file format

← Older revision		Revision as of 10:47, 2 May 2014
Line 88:		Line 88:
	tags = exploration;web		tags = exploration;web
	single_instance = no		single_instance = no
			max_participants = 4

	A more detailed explanation of the valid properties follows:		A more detailed explanation of the valid properties follows:
Line 142:		Line 143:
	single_instance = yes		single_instance = yes
	: This key is optional. If not present, or if present with a value of "no", multiple instances of the activity can be launched at once. If present with a value of "yes", then only one instance of the activity will be open at any one time. This key was added in order to flag activities that use resources that cannot be shared.		: This key is optional. If not present, or if present with a value of "no", multiple instances of the activity can be launched at once. If present with a value of "yes", then only one instance of the activity will be open at any one time. This key was added in order to flag activities that use resources that cannot be shared.

			max_participants = 4
			: This key is optional. If not present, or if present with a value of <=1, the activity is not shared. Otherwise, it limits the number of participants who can join a shared activity. Note that setting max_participants in activity.py is deprecated.

	summary = ...		summary = ...