5,705
edits
Changes
Platform Team/Guide/Sweets Packaging (view source)
Revision as of 00:30, 23 September 2012
, 00:30, 23 September 2012no edit summary
* suffixes for final ''interface''s, e.g., {{Code|http://sweets.sugarlabs.org/''<value>''}},
* suffixes for final ''interface''s, e.g., {{Code|http://sweets.sugarlabs.org/''<value>''}},
* the name of project/package on [[Platform_Team/Open_Build_System|OBS]] that will be used to host released sweet.
* the name of project/package on [[Platform_Team/Open_Build_Service|OBS]] that will be used to host released sweet.
In the 2nd case, the last slash separated part is a package, and the rest is a project, e.g., for ''sdk/sugar'', ''sdk'' is a project and ''sugar'' is a package in the ''sdk'' project.
In the 2nd case, the last slash separated part is a package, and the rest is a project, e.g., for ''sdk/sugar'', ''sdk'' is a project and ''sugar'' is a package in the ''sdk'' project.
It is possible to have interface values without slashes, in that case, project and package names are the same.
It is possible to have interface values without slashes, in that case, project and package names are the same.
In the [[Platform_Team/Open_Build_System|OBS]], there is a special project named ''base''. This project contains sweets that all time will be represented only by native packages. In other words, if you need to make sure that your sweet needs to depend only on native packages, use dependencies from the ''base'' project.
In the [[Platform_Team/Open_Build_Service|OBS]], there is a special project named ''base''. This project contains sweets that all time will be represented only by native packages. In other words, if you need to make sure that your sweet needs to depend only on native packages, use dependencies from the ''base'' project.
The ''base'' project is also useful for [[Platform_Team/Sweets/Glossary#Associated_interfaces|associated]] interfaces set in ''associate'' recipe option. For example, if your sweet needs ''pygame=2'' dependency that is not yet widespread, create ''~user/pygame'' temporary sweet with ''2'' version only, and use ''~user/pygame'' as a dependency in your sweet. If ''base/pygame'' will be added as associated interface to the ''~user/pygame'', users that have ''>=2'' version in native packages will reuse them instead of ''~user/pygame'''s one.
The ''base'' project is also useful for [[Platform_Team/Sweets/Glossary#Associated_interfaces|associated]] interfaces set in ''associate'' recipe option. For example, if your sweet needs ''pygame=2'' dependency that is not yet widespread, create ''~user/pygame'' temporary sweet with ''2'' version only, and use ''~user/pygame'' as a dependency in your sweet. If ''base/pygame'' will be added as associated interface to the ''~user/pygame'', users that have ''>=2'' version in native packages will reuse them instead of ''~user/pygame'''s one.
=== Dependencies ===
=== Dependencies ===
Dependencies might be used in ''requires'' and ''suggests'' options in recipes files to declare that the current sweet is depending on another ones.
Dependencies might be used in the ''requires'' and ''suggests'' options in recipes files to declare that the current sweet depends on another sweet/s.
The format of dependency string is:
The format of a dependency string is:
<interface> [(=|>=|<) <version>]
<interface> [(=|>=|<) <version>]
The ''interface'' value supports all interface [[#Interfaces|forms]]. The limited set of version conditions depends on Zero Install [http://0install.net/interface-spec.html specification] when the {{Code|<nowiki>=</nowiki>}} condition is a high level one and will be described in {{Code|<nowiki>>=</nowiki>}} and {{Code|<}} terms.
The ''interface'' value supports all interface [[#Interfaces|forms]]. The limited set of version conditions depends on Zero Install [http://0install.net/interface-spec.html specification] when the {{Code|<nowiki>=</nowiki>}} condition is a high level one and will be described in {{Code|<nowiki>>=</nowiki>}} and {{Code|<}} terms.
Dependencies might be optional. In that case, they need to be wrapped into square brackets. Optional dependencies will be used only if there are implementation to choose, otherwise they will be discarded without errors.
Dependencies may be optional. In that case, they need to be wrapped in square brackets. Optional dependencies will be used ''only'' if there is an [[Platform_Team/Sweets/Glossary#implementation|implementation]] to choose, otherwise they will be discarded without errors.
=== Stability status ===
=== Stability status ===
=== Examples ===
=== Examples ===
A list of recipe examples. Besides, see {{Code|sugar*}} repositories in [http://git.sugarlabs.org/sdk Gitorious] project, all of them are sweets.
A list of recipe examples. Additionally, see {{Code|sugar*}} repositories in the [http://git.sugarlabs.org/sdk Gitorious sdk] repository, all of them are sweets.
'''Python activity'''
'''Python activity'''
== Releasing ==
== Releasing ==
In Sweets, releasing means uploading a sources tarball with a release (though, that [[#Stability_status|doesn't only mean]] stable versions) to the Sugar Labs [[Platform_Team/Open_Build_System|instance]] of the [http://openbuildservice.org/ Open Build Service] (OBS). Before releasing, make sure that you have a Sugar Labs [[Service/Account#Sugar_Labs_Central_Login|account]]. A login with password will be required the first time or when your cookie is missing.
In Sweets, releasing means uploading a sources tarball with a release (though, that [[#Stability_status|doesn't only mean]] stable versions) to the Sugar Labs [[Platform_Team/Open_Build_Service|instance]] of the [http://openbuildservice.org/ Open Build Service] (OBS). Before releasing, make sure that you have a Sugar Labs [[Service/Account#Sugar_Labs_Central_Login|account]]. A login with password will be required the first time or when your cookie is missing.
Before releasing, make sure that your recipe conforms to the OBS [[Platform_Team/Open_Build_System/Policy|Policy]]. While releasing, sweet sources will be uploaded to an OBS project/package according to the [[#Interfaces|implement]] recipe option. If a particular project or package don't exist, they will be created (upon user's confirmation for project creation).
Before releasing, make sure that your recipe conforms to the OBS [[Platform_Team/Open_Build_Service/Policy|Policy]]. While releasing, sweet sources will be uploaded to an OBS project/package according to the [[#Interfaces|implement]] recipe option. If a particular project or package don't exist, they will be created (upon user's confirmation for project creation).
To initiate releasing, enter from the sweet sources directory:
To initiate releasing, enter from the sweet sources directory:
and see its {{Code|sweets.recipe}} files.
and see its {{Code|sweets.recipe}} files.
== Pitfalls ==
== Developing activities ==
How Sweets might be useful while developing activities.
=== Manage sources ===
The traditional development related routine for activity sources is to run the {{Code|setup.py}} script located in the root activity directory. With Sweets, these routines might be accomplished with the {{Code|sweets}} command. Here is some background information:
* A downside of using Sweets is that running {{Code|setup.py}} requires being in the Sugar session (in order to have all the libraries that {{Code|setup.py}} injects);
* Sweets is designed to support multiple software versions at the same time. So to avoid having to login to different Sugar sessions for creating source tarballs, for example, it makes more sense to have a standalone utility;
* The {{Code|sweets}} command already contains development related functionality; it is useful to keep all development related functions in one utility.
Sweets support the following {{Code|setup.py}}'s commands:
* {{Code|build}}, build generated files, e.g., {{Code|locale/}} directory;
* {{Code|dist_xo}}, create a .xo with activity sources;
* {{Code|dist_source}}, create activity sources tarball;
* {{Code|genpot}}, generate the gettext pot file.
And doesn't support the following:
* {{Code|dev}} - seems to be a needlessly exaggerated function that creates a symbolic link in the {{Code|~/Activities}} directory to activity sources. The same might be done using the {{Code|ln -s}} command to avoid having derived functionality, or better, place sources directly in the {{Code|~/Activities}} directory;
* {{Code|fix_manifest}} - function creates {{Code|MANIFEST}} file. Not having this file is not a failure, and Sweets is designed to have include/exclude rules in recipe files instead;
* {{Code|install}} - function installs the activity to the root system. Sweets avoid, by design, any global changes during its regular behaviour.
As regular {{Code|sweets}}'s commands, these commands need to be executed from the activity directory (or in any of its sub-directories, not just in the root), or the path to activity sources might be specified after the command name, e.g.:
sweets build [PATH]
=== Launch activity ===
Before starting Sugar Shell, place your activity's sources directory under the {{Code|~/Activities/}} directory, or place there a symbolic link to the activity sources. After running Sugar Shell, the new activity will appear in the Home view (if it's absent in the Favorites view, switch to the List view).
== Good practices ==
=== Devel packages ===
=== Devel packages ===
Keep all build-time files in the sweet with runtime files.
Keep all build-time files in the sweet with runtime files.
=== Transparent behaviour ===
Library sweets that are associated with native packages ({{Code|base/*}} sweets), should use regular environment variables for binding, such as {{Code|LD_LIBRARY_PATH}}. The idea is that it should be possible to replace them with native packages transparently and avoid changes in sweets that use these libraries.
== Feedback ==
== Feedback ==
{{:Platform_Team/Sweets/Feedback}}
{{:Platform_Team/Sweets/Feedback}}