| Line 61: |
Line 61: |
| | | | |
| | 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. |
| | + | |
| | + | === Stability status === |
| | + | |
| | + | Sweets should have stability status: |
| | + | |
| | + | * ''stable'', final stable release, |
| | + | * ''testing'', let people interested in testing try latest changes that are not yet stable, |
| | + | * ''developer'', just a more extreme version of ''testing'', |
| | + | |
| | + | This is a useful Zero Install feature that let developers share not yet stable version among the community. Since by default, only stable versions are being used, people, who are interested in helping developers in polishing not yet stable versions, need to explicitly choose not stable versions. |
| | + | |
| | + | === Glob patterns === |
| | + | |
| | + | The ''include'' and ''exclude'' options contain file patterns. A pattern could be of two types: |
| | + | |
| | + | * doesn't contain ''/'' or ''**'' substrings, will be applied only to file names |
| | + | * contains ''/'' or ''**'' substring, will be applied to the full file path (relative to the root), thus could affect several directory levels |
| | + | |
| | + | Only these pattern symbols are allowed: |
| | + | |
| | + | * ''*'' matches everything, except directory separator |
| | + | * ''?'' matches any single character, except directory separator |
| | + | * ''**'' matches everything, including directory separator |
| | | | |
| | === Examples === | | === Examples === |
| Line 141: |
Line 164: |
| | make = make | | make = make |
| | install = make DESTDIR=%(DESTDIR)s install | | install = make DESTDIR=%(DESTDIR)s install |
| | + | |
| | + | == Releasing == |
| | | | |
| | == Development with Sweets == | | == Development with Sweets == |
| Line 150: |
Line 175: |
| | | | |
| | 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}}. |
| − |
| |
| − | == Feedback ==
| |
| − |
| |
| − | * [http://bugs.sugarlabs.org/newticket?component=sweets Submit] your bug report.
| |
| − | * Ask your question on IRC channels, [irc://irc.freenode.net/sugar #sugar] (not logged) or [irc://irc.freenode.net/sugar-newbies #sugar-newbies] (logged).
| |
| − |
| |
| − | <!--
| |
| − |
| |
| − | The only thing that is required from sources is having a [[Platform Team/Recipe Specification|sweets.recipe]] spec file for non-activity projects or an {{Code|activity/activity.info}} file (that conforms to the same spec) for activities. All sweets for Glucose components are located in the http://git.sugarlabs.org/sdk project.
| |
| − |
| |
| − | Once checked out, these sources might be launched using {{Code|<nowiki>http://</nowiki>sweets.sugarlabs.org/''sweet-value-from-sweets.recipe''}} or just mentioning a sweet value:
| |
| − |
| |
| − | sweets ''sweet''
| |
| − |
| |
| − | For glucose projects, you can find ready-to-use and always-rebased-to-upstream projects in the [http://git.sugarlabs.org/sdk SDK] http://git.sugarlabs.org project. For now, there are two branches: {{Code|master}} for recent trunk, and {{Code|master-0.88}} for 0.88 code based on Dextrose-2 patches.
| |
| − |
| |
| − | Checked-out projects will be built according to the {{Code|[Build]}} section commands in the {{Code|sweets.recipe}} files. In general, for autotools-based projects, there is no further need for the {{Code|sweets}} command; just run {{Code|make install}} to build current sources and install them to the directory that was specified by {{Code|sweets}} in the configure stage. For glucose projects, there is no need even in calling the {{Code|make}} command (python code will be reused from its original location, see {{Code|binding}} options in [[Platform Team/Recipe Specification|sweets.recipe]] files), just change the code and restart sugar.
| |
| − |
| |
| − |
| |
| − | == Writing recipe files ==
| |
| − |
| |
| − | See also [[Platform_Team/Recipe_Specification|recipe specification]].
| |
| − |
| |
| − | === Package names ===
| |
| − |
| |
| − | Within recipe files, Zero packages might be identified by several methods:
| |
| − |
| |
| − | * current package (instead of a direct slug value, to make the recipe file more robust, move the ''slug'' option to the [DEFAULT] section and use {{Code|%(slug)s}} interpolation),
| |
| − | <current-slug>[/<nowiki><sub-package></nowiki>]
| |
| − |
| |
| − | * other packages from Bazaar that are accessible in the current project,
| |
| − | <other-package-slug>[/<nowiki><sub-package></nowiki>]
| |
| − |
| |
| − | * direct 0install link.
| |
| − | <0install-feed-url>
| |
| − |
| |
| − | At the end, all links will be transfered to 0install feed urls. The final 0install url will be in the following format:
| |
| − |
| |
| − | <nowiki>http</nowiki>://sweets.sugarlabs.org/<Bazaar-project>/<slug>
| |
| − |
| |
| − | === Versioning ===
| |
| − |
| |
| − | The versioning scheme for Zero packages can be arbitrary, since the ''version'' recipe option supports [http://0install.net/interface-spec.html#id4016582 0install version format]. But in some cases, e.g., libraries, stricter versioning could be useful. In that case, the ''age'' recipe option should be used.
| |
| − |
| |
| − | The recipe option ''age'' is intended to support, mostly, API breakages of library packages. But not ABI, because tracking an ABI is not trivial within the Sugar ecosystem (due to the enormous potential code base of varying quality) and of little utility, and since packages may at any time be rebuilt from sources and multiple library versions may be installed (thanks to 0install).
| |
| − |
| |
| − | Using the ''age'' option is simple, on every API breakage for the library package, increment the ''age'' value. The final package version will be:
| |
| − | <age-option>.<version-option>
| |
| − |
| |
| − | === Glob patterns ===
| |
| − |
| |
| − | A pattern could be of two types:
| |
| − |
| |
| − | * doesn't contain ''/'' or ''**'' substrings, will be applied only to file names
| |
| − | * contains ''/'' or ''**'' substring, will be applied to the full file path (relative to the root), thus could affect several directory levels
| |
| − |
| |
| − | Only these pattern symbols are allowed:
| |
| − |
| |
| − | * ''*'' matches everything, except directory separator
| |
| − | * ''?'' matches any single character, except directory separator
| |
| − | * ''**'' matches everything, including directory separator
| |
| | | | |
| | == Pitfalls == | | == Pitfalls == |
| Line 216: |
Line 180: |
| | === 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 0install 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 runtime package. | + | Keep all build-time files in the sweet as runtime files. |
| | | | |
| | + | == Feedback == |
| | | | |
| − | | + | * [http://bugs.sugarlabs.org/newticket?component=sweets Submit] your bug report. |
| − | | + | * Ask your question on IRC channels, [irc://irc.freenode.net/sugar #sugar] (not logged) or [irc://irc.freenode.net/sugar-newbies #sugar-newbies] (logged). |
| − | | |
| − | | |
| − | == Introduction ==
| |
| − | | |
| − | The purpose of this Guide is to describe how to deploy your code via [[Activity_Team/Services|Sugar Services]] and let other people [[Documentation_Team/Services/Activity_Developers_Guide|use]] it in simple and convenient way.
| |
| − | | |
| − | If you are looking for a method to install some software from native packages, see [[Documentation_Team/Services/Wrap native packages HOWTO| native packages HOWTO]].
| |
| − | | |
| − | If the service is not just a [[Documentation_Team/Services/Native_packages_usage|wrapper]] for an upstream project, please consider the possibility of creating a service page using [[Activity Team/Services/Template|template]].
| |
| − | | |
| − | == Detailed description ==
| |
| − | | |
| − | The resulting service development process will consist of regular 0install files that are placed in a subdirectory on http://services.sugarlabs.org/ with a name that is the identity for the service in the rest of the 0sugar infrastructure. The Service's subdirectory will contain:
| |
| − | | |
| − | * Several .xml files that are regular 0install feeds. service.xml is the main feed for the service, other feed files are optional and represent sub services, e.g., [http://download.sugarlabs.org/services/toolkit/].
| |
| − | | |
| − | * A bunch of tarballs with sources and binaries. Feed files contain links to these files. | |
| − | | |
| − | See the 0install [http://0install.net/interface-spec.html documentation] to learn more about feeds.
| |
| − | | |
| − | Services could be identified using two methods:
| |
| − | | |
| − | * by name in the 0sugar environment
| |
| − | <service>
| |
| − | <service>/<subservice>
| |
| − | | |
| − | * as regular 0install identifiers in the 0install environment
| |
| − | http://services.sugarlabs.org/<service>
| |
| − | http://services.sugarlabs.org/<service>/<subservice>.xml
| |
| − | | |
| − | To start the Sugar Services developing process:
| |
| − | * Install the [[Documentation_Team/Services/0sugar|0sugar]] tool.
| |
| − | * Read ''service.info'' file.
| |
| − | [[Documentation_Team/Services/Service.info_Specification|specification]]
| |
| − | and follow the rest of this document instruction about development details.
| |
| − | | |
| − | == Stability status ==
| |
| − | | |
| − | One of the core differences from the Sucrose development process is having not stable "releases" (here, release is a result of ``0sugar push`` command). So, services need stability status. Internally, each service release will have one of 0install's stability [http://0install.net/interface-spec.html#id4091477 statuses]:
| |
| − | | |
| − | * ''stable'', final stable release,
| |
| − | * ''testing'', let people interested in testing try latest changes that are not yet stable,
| |
| − | * ''developer'', just a more extreme version of ''testing'',
| |
| − | * ''buggy'', already-released versions (of any status) could be [[#Bugfix_releases|marked]] as buggy after a while to force people to upgrade to a new bugfix version,
| |
| − | * ''insecure'', an extreme version of ''buggy''.
| |
| − | | |
| − | ''0sugar push'' w/o arguments will push local changes as is. If you want to push with a particular stability status, use ''0sugar push <status>''.
| |
| − | | |
| − | By default, all users will use only ''stable'' versions and won't upgrade to new versions, even if there are stable ones. To force people to upgrade from buggy versions, see the [[#Bugfix_releases|bugfix releases]] workflow.
| |
| − | | |
| − | == Development workflows ==
| |
| − | | |
| − | A Service developer can follow one of several step-by-step scenarios:
| |
| − | | |
| − | * [[Documentation Team/Services/Activity specific Services HOWTO|Activity specific Services HOWTO]] - if your activity uses its own binaries,
| |
| − | * [[Documentation Team/Services/Binary-less Services HOWTO|Binary-less Services HOWTO]] - to make any architecture service, e.g., python based,
| |
| − | * [[Documentation Team/Services/Binary Services HOWTO|Binary Services HOWTO]] - for services that contain binaries,
| |
| − | * [[Documentation Team/Services/Upstream Services HOWTO|Upstream Services HOWTO]] - if your activity or service uses a project which is not part of Sugar Platform, follow this howto to create a wrapper around the upstream project, and just add its name to the ''requires'' section of .info file,
| |
| − | * [[Documentation Team/Services/Wrap native packages HOWTO|Wrap native packages HOWTO]] - this is a special one, if some project is already well packaged in various GNU/Linux distributions, but is not a Sugar Platform component, just create a "fake" service.
| |
| − | | |
| − | == Release workflows ==
| |
| − | | |
| − | '''Having only stable releases'''
| |
| − | | |
| − | All releases of your services will have ''stable'' stability status.
| |
| − | | |
| − | * when your code is ready to release,
| |
| − | * ''0sugar dist*'' to make bundles,
| |
| − | * ''0sugar push stable'' to rsync bundles to the server,
| |
| − | * if it was the wrong time to release and you want to re-release it, repeat the previous steps to rewrite the wrong release.
| |
| − | | |
| − | '''Bugfix releases'''
| |
| − | | |
| − | Services assume a simple versioning scheme, if you found bugs in the stable version,
| |
| − | | |
| − | * either ''0sugar push stable'' the release once more (users will not mess this new copy of release with previous ones),
| |
| − | * or ''0sugar push stable'' the release with incremented ''version'' field.
| |
| − | * If bugs are critical, mark the previous release as ''buggy'' or ''insecure'' to force users to upgrade their old releases. If you re-pushed release w/o incrementing ''version'' number, you should use revision number.
| |
| − | | |
| − | 0sugar push {buggy|insecure} {version[-revision]}
| |
| − | | |
| − | ''' Development releases '''
| |
| − | | |
| − | If you want to test your new version among interested people,
| |
| − | | |
| − | * do all the steps mentioned in the previous workflows,
| |
| − | * but use either the ''testing'' or ''developer'' status for the ''push'' command.
| |
| − | * Users interested in testing (with testing mode enabled) will get your new development version. | |
| − | * You don't have to change the ''version'' every time for micro releases, ''0sugar'' will implicitly change the revision of new pushes, and users will download the latest changes.
| |
| − | | |
| − | == Tips ==
| |
| − | | |
| − | * Via ''binding'' variables, a service's root directory will be accessible for service users, so for python services (for example), it is better to use a subdirectory for a service's import modules, like [http://git.sugarlabs.org/projects/toolkit/repos/mainline/trees/master Toolkit] does - there is a ''toolkit'' subdirectory in Toolkit's root.
| |
| − | | |
| − | * Be careful with machine architecture, especially in making binaries in VMs, e.g., the XO-1 arch is i586, but built-in XO VM, binaries could have i686 and thus, won't start (0install won't allow) on XO-1. Use --arch 0sugar's argument to set targeted architecture explicitly.
| |
| − | | |
| − | == Documentation ==
| |
| − | | |
| − | * [http://0install.net/injector-packagers.html Packaging guide] for 0install packages
| |
| − | * [http://0install.net/interface-spec.html Feed file format specification]
| |
| − | * [http://0install.net/0compile.html 0compile] [http://0install.net/0compile-dev.html guide]
| |
| − | | |
| − | == The workflow of regular Sugar doer will look like: ==
| |
| − | | |
| − | # Having a directory with Sugar project to develop.
| |
| − | #* Directory should be placed to one of default paths.
| |
| − | #* The only important element is a [[Platform Team/Sugar_Doers_Kit/Implementation#Recipes|recipe file]], i.e., an analog of {{Code|activity.info}} file for activities.
| |
| − | # To make it useful, just run it.
| |
| − | #* For activities, just click on activity icon in Sugar Shell.
| |
| − | #* Otherwise, run application using its unique Web url.
| |
| − | # Everything which is related to the process of project running, will be handled automatically.
| |
| − | #* There is always a way to fallback to the particular running step.
| |
| − | #* If project has dependencies, they will be installed or passed though the same running procedure (for under development dependencies).
| |
| − | #* If project needs to be build, it will happen automatically (including installing buildtime dependencies).
| |
| − | # Make Sugar project accessible for others.
| |
| − | #* Only one command call or one click in Sugar Shell is needed.
| |
| − | #* The only requirement, being registered in the system (particular implementations might be different, from [https://cas.sugarlabs.org/ Sugar Labs Central Login] to local school server).
| |
| − | #* Anyone can run recent version of your project just be mentioning its Web url.
| |
| − | # Sharing information about Sugar project.
| |
| − | #* Information about newly released project might be automatically published on [[Activity Library]].
| |
| − | | |
| − | -->
| |