8,288
edits
Changes
Jump to navigation
Jump to search
Line 6:
Line 6: − + − + − + − + − + − + − + − + − + − + − + Line 38:
Line 38: − + − + Line 46:
Line 46: − + − + − + − + − + − + − + − + − + − + − Commands ''dist'' and ''dist_bin'' rewrite releases with the same ''version'' versions and don't remove other releases.+ − + − + − + − + − + − + − + − + − + − + − + − + − + − + − + Line 105:
Line 105: − + − + − + − + − + − + − + − + Line 122:
Line 122: − + − + − + − + − + − + − +
Platform Team/Guide/Sweets Packaging (view source)
Revision as of 21:55, 6 March 2010
, 21:55, 6 March 2010work on English
== Introduction ==
== Introduction ==
The purpose of this Guide is describing 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.
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|p native packages HOWTO]].
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 service is not just a [[Documentation_Team/Services/Native_packages_usage|wrapper]] for upstream project, please consider possibility to create service page using [[Activity Team/Services/Template|template]].
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 ==
== Detailed description ==
The result for service development process will be regular 0install files that are placed to subdirectory on http://services.sugarlabs.org/ with name which is identity for the service in the rest of 0sugar infrastructure. Service's subdirectory will contain:
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. Service's subdirectory will contain:
* several .xml files that are regular 0install feeds, service.xml is the main feed for service, other feed files are optional and represent sub services e.g. [http://download.sugarlabs.org/services/toolkit/]
* 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/].
* bunch of tarballs with sources and binaries, feed files contain links to these files
* A bunch of tarballs with sources and binaries. Feed files contain links to these files.
See 0install [http://0install.net/interface-spec.html documentation] to know more about feeds.
See the 0install [http://0install.net/interface-spec.html documentation] to learn more about feeds.
Services could be identified using two methods
Services could be identified using two methods:
* by name in 0sugar environment
* by name in the 0sugar environment
<service>
<service>
<service>/<subservice>
<service>/<subservice>
* as regular 0install identifiers in 0isntall environment
* as regular 0install identifiers in the 0install environment
http://services.sugarlabs.org/<service>
http://services.sugarlabs.org/<service>
http://services.sugarlabs.org/<service>/<subservice>.xml
http://services.sugarlabs.org/<service>/<subservice>.xml
Sugar Services maintainer process is using [[#0sugar_tool|0sugar]] tool to create proper feeds and tarballs. 0sugar uses spec file service/service.info as an scenario file(like .spec files in RPM). See also [[Documentation_Team/Services/Service.info_Specification|specification]] of service.info files.
The Sugar Services maintainer process is to use the [[#0sugar_tool|0sugar]] tool to create the proper feeds and tarballs. 0sugar uses a spec file service/service.info as an scenario file (like .spec files in RPM). See also [[Documentation_Team/Services/Service.info_Specification|specification]] of service.info files.
== 0sugar tool ==
== 0sugar tool ==
To start developing services, install injector and 0sugar tools:
To start developing services, install injector and 0sugar tools:
* Install [http://download.sugarlabs.org/services/zeroinstall-injector/bundles/zeroinstall-injector-latest.sh last version] of patched zeroinstall-injector, see also 0install [http://0install.net/injector-using.html|tutorials] for more 0install related information
* Install the [http://download.sugarlabs.org/services/zeroinstall-injector/bundles/zeroinstall-injector-latest.sh latest version] of patched zeroinstall-injector, see also 0install [http://0install.net/injector-using.html|tutorials] for more 0install-related information.
* Tweak PATH environment variable, after executing command you need to relogin
* Tweak the PATH environment variable, and after executing the command, you need to relogin.
echo 'PATH=~/.local/bin:$PATH' >> ~/.bashrc
echo 'PATH=~/.local/bin:$PATH' >> ~/.bashrc
0alias 0sugar http://services.sugarlabs.org/0sugar
0alias 0sugar http://services.sugarlabs.org/0sugar
While working, 0sugar creates .0sugar directory which is cache directory and should not be included to version control system repository, it has hierarchy:
While working, 0sugar creates the .0sugar directory, which is a cache directory, and should not be included in version control system repositories. It has the following hierarchy:
* .0sugar/remote, rsynced copy(could be partial) of service directory on the server
* .0sugar/remote, rsynced copy (could be partial) of the service directory on the server,
* .0sugar/local, directory with output tarballs after invoking dist and build commands
* .0sugar/local, directory with output tarballs after invoking dist and build commands,
* .0sugar/(src|build|dist) directories after invoking build command
* .0sugar/(src|build|dist) directories after invoking the build command.
During maintaining session, 0sugar will create result files in .0sugar/remote directory that will be rsynced to the server by push command i.e. shell account on sunjammer server is required, to get one follow [[Sysadmin/Shell_account_request|instructions]].
During a maintenance session, 0sugar will create result files in .0sugar/remote directory that will be rsynced to the server by a push command, therefore, a shell account on sunjammer server is required, to get one, follow these [[Sysadmin/Shell_account_request|instructions]].
== Versioning scheme ==
== Versioning scheme ==
There could be two different versioning scheme for services.
There could be two different versioning schemes for services.
=== Upstream versions ===
=== Upstream versions ===
If service is just a wrapper around existed project with its own versioning scheme then there is even no need in any mentioning of versions in service.info file. Particular version will be chosen on every ''0sugar dist*'' command invoking or will be fetched from native packaging systems(if service doesn't provide binaries and [[Documentation Team/Services/Native packages usage|only]] contains information about already well packaged in various GNU/Linux distributions).
If the service is just a wrapper around an existing project with its own versioning scheme, then there is no need in even any mentioning of versions in the service.info file. The particular version will be chosen on every ''0sugar dist*'' command invocation or will be fetched from native packaging systems (if the service doesn't provide binaries and [[Documentation Team/Services/Native packages usage|only]] contains information about software already well-packaged in various GNU/Linux distributions).
=== Native versions ===
=== Native versions ===
The rest of services will use scheme:
The rest of services will use this scheme:
<version>-<revision>
<version>-<revision>
* <version> is a ''version'' field from service.info file which is a plain number
* <version> is a ''version'' field from the service.info file which is a plain number.
* <revision> is an auto incremented number which is beeing changed by ''0sugar push'' command (like Subversion revision)
* <revision> is an auto-incremented number, which is changed by the ''0sugar push'' command (like Subversion revision).
The commands ''dist'' and ''dist_bin'' rewrite releases with the same ''version'' versions and don't remove other releases.
[[#Library_section|Libraries]] have also ''age'' parameter which is [http://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html#Libtool-versioning libtool] like age version part. ''age'' won't be exposed in version string but will be present in feed files and 0sugar will check it while deciding what dependency version should be chosen.
[[#Library_section|Libraries]] have also an ''age'' parameter which is a [http://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html#Libtool-versioning libtool]-like age version part. ''age'' won't be exposed in version string, but will be present in feed files, and 0sugar will check it while deciding what dependency version should be chosen.
== Stability status ==
== Stability status ==
One of core differences from 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 stability [http://0install.net/interface-spec.html#id4091477 statuses]:
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
* ''stable'', final stable release,
* ''testing'', let interested in testing people, try last changes that are not yet stable
* ''testing'', let people interested in testing try latest changes that are not yet stable,
* ''developer'', just more extreme version of ''testing''
* ''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 upgrade to new bugfix version
* ''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'', extreme version of ''buggy''
* ''insecure'', an extreme version of ''buggy''.
''0sugar push'' w/o arguments will push local changes as is. If you want to push with particular stability status, use ''0sugar push <status>''.
''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 [[#Bugfix_releases|bugfix releases]] workflow.
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 ==
== Development workflows ==
Service developer can follow one of several step-by-step scenarios:
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/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-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]] services that contain binaries
* [[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 project which is not part of Sugar Platform, follow this howto to create wrapper around upstream project and just add its name to ''requires'' section of .info file
* [[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 to various GNU/Linux distributions but is not Sugar Platform component, just create "fake" service.
* [[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 ==
== Release workflows ==
All releases of your services will have ''stable'' stability status.
All releases of your services will have ''stable'' stability status.
* when your code is ready to release
* when your code is ready to release,
* ''0sugar dist*'' to make bundles
* ''0sugar dist*'' to make bundles,
* ''0sugar push stable'' to rsync bundles to the server
* ''0sugar push stable'' to rsync bundles to the server,
* if it was wrong time to release and you want to re-release it, repeat previous steps to rewrite wrong release
* 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'''
'''Bugfix releases'''
Services assume simple versioning scheme, if you found bugs in stable version:
Services assume a simple versioning scheme, if you found bugs in the stable version,
* either ''0sugar push stable'' release once more(users will not mess this new copy of release with previous ones)
* either ''0sugar push stable'' the release once more (users will not mess this new copy of release with previous ones),
* or ''0sugar push stable'' release with incremented ''version'' field
* or ''0sugar push stable'' the release with incremented ''version'' field.
* if bugs are critical, mark previous release as ''buggy'' or ''insecure'' to force users upgrade their old releases. If you re-pushed release w/o incrementing ''version'' number, you should use revision number
* 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]}
0sugar push {buggy|insecure} {version[-revision]}
''' Development releases '''
''' Development releases '''
If you want to test your new version among interested people:
If you want to test your new version among interested people,
* do all steps that are mentioned in previous workflows
* do all the steps mentioned in the previous workflows,
* but use either ''testing'' or ''developer'' status for ''push'' command
* but use either the ''testing'' or ''developer'' status for the ''push'' command.
* users who interested in testing(enabled testing mode) will get your new development version
* Users interested in testing (with testing mode enabled) will get your new development version.
* you don't have to change ''version'' all time for micro releases, ''0sugar'' will implicitly change revision of new pushes and users will download last changes
* 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 ==
== Tips ==
* Via ''binding'''s variables, service's root directory will be accessible for service users, so for python services(for example), better to use subdirectory for service's import modules like [http://git.sugarlabs.org/projects/toolkit/repos/mainline/trees/master Toolkit] does - there is ''toolkit'' subdirectory in Toolkit's root.
* 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. XO-1 arch is i586 but built in XO VM, binaries could have i686 thus won't start(0install won't let) on XO-1. Use --arch 0sugar's argument to set targeted architecture explicitly.
* 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 ==
== Documentation ==