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.
See OBS [https://packages.sugarlabs.org/project/list_public projects] for all existed sweets.
See OBS [https://packages.sugarlabs.org/project/list_public projects] for all existed sweets.
=== Dependencies ===
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 a dependency string is:
<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.
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.
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_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_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:
sweets commit
The {{Code|sweets}} command will ask for a commit message, i.e., release notes. The same notes might be passed to {{Code|commit}} command via the {{Code|--message}} command-line argument.
If the releasing sweet is binary based, only the most recent stable version will be built on the OBS side, other versions will be built on the client side.
== Development with Sweets ==
== Development with Sweets ==
Source bundles might be used on a client side not only indirectly, via {{Code|sweets}} command for example, but also explicitly. Sources might be bundled, emailed, etc. In this case, it is no different from {{Code|.xo}} files. To make sources useful within Sweets, the local directory with sources might be used in several ways:
Source bundles might be used on the client side not only indirectly, via {{Code|sweets}} command for example, but also explicitly. Sources might be bundled, emailed, etc. In this case, it is just like {{Code|.xo}} files. To make sources useful within Sweets, the local directory with sources might be employed in several ways:
* Applications might be launched from sources, {{Code|sweets ''<path-to-sources>''}};
* Applications might be launched from sources, {{Code|sweets ''<path-to-sources>''}};
* To reuse sources as dependencies for other sweets, source directory needs to be registered in Sweets, {{Code|sweets checkout ''<path-to-sources>''}}; applications might be checked out as well.
* To reuse sources as dependencies for other sweets, the source directory needs to be registered in Sweets, {{Code|sweets checkout ''<path-to-sources>''}}; applications might be checked out as well.
Checking out will register a ''sweet'' in the local ''Sweets'' instance as a single ''implementation'' for the ''interfaces'' it ''implements''. This feature is especially useful for libraries, for example, if the sugar-toolkit sources, which implement the {{Code|sdk/sugar-toolkit}} ''interface'', were cloned to the {{Code|~/src/sugar-toolkit}} directory, then, while running a {{Code|sdk/sugar}} ''sweet'', it would become possible to reuse local sugar-toolkit sources as a regular ''implementation'' of the {{Code|sdk/sugar-toolkit}} dependency of {{Code|sdk/sugar}}.
Checking out will register a ''sweet'' in the local ''Sweets'' instance as a single ''implementation'' for the ''interfaces'' it ''implements''. This feature is especially useful for libraries, for example, if the sugar-toolkit sources, which implement the {{Code|sdk/sugar-toolkit}} ''interface'', were cloned to the {{Code|~/src/sugar-toolkit}} directory, then, while running a {{Code|sdk/sugar}} ''sweet'', it would become possible to reuse local sugar-toolkit sources as a regular ''implementation'' of the {{Code|sdk/sugar-toolkit}} dependency of {{Code|sdk/sugar}}.
== Pitfalls ==
=== Sugar sweets ===
There are [[Platform_Team/Guide/Sweets_Usage#Sugar_via_Sweets|sdk/sugar]] sweets that might be used as an example how to support sweets. Sweets Sugar sources are always rebased [http://git.sugarlabs.org/sdk forks] of upstream projects with added {{Code|sweets.recipe}} files and lightweight patches that make the original code useful via Sweets.
Checkout sources from:
* http://git.sugarlabs.org/sdk/sugar-base
* http://git.sugarlabs.org/sdk/sugar-toolkit
* http://git.sugarlabs.org/sdk/sugar-artwork
* http://git.sugarlabs.org/sdk/sugar
and see its {{Code|sweets.recipe}} files.
== 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 ===
It is common practice in binary-based GNU/Linux distributions to use satellite devel packages to collect various build-time files like C headers or pkg-config files. In the Zero Install environment, this doesn't work, because every package is stored in a separate directory hierarchy, e.g., *.so symlinks, from devel package, will point to nothing, since all *.so.* files from the library package live in a separate directory.
It is common practice in binary-based GNU/Linux distributions to use satellite devel packages to collect various build-time files like C headers or pkg-config files. In the Zero Install environment, this doesn't work, because every package is stored in a separate directory hierarchy, e.g., *.so symlinks, from devel package, will point to nothing, since all *.so.* files from the library package live in a separate directory.
Keep all build-time files in the sweet as 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}}