5,705
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: − + + Line 25:
Line 26: − − == service.info file == − − Service publishing workflow is similar to activities. There is an info file, here ''service/service.info'', which describes current status(not history) of development process. All these fields, finally, go to feed file while publishing new version. − − === [Service] section === − − File ''service.info' should contain at least ''[Service]'' section: − − * ''name'', the identity of service, this field defines name of feed's root directory on the server http://download.sugarlabs.org/services/ as well − * ''summary'', short descriptive line − * ''description'', long descriptive line, to wrap long text, all lines after second, should start with spaces<br>could be omited to reuse ''summary'' field − * ''license'', in 0install, typically a Trove category, as used on freshmeat.net, but could be [http://fedoraproject.org/wiki/Licensing#Good_Licenses fedora names], since the rest of sugar uses them − * ''homepage'' web link to project home page − − === [Runtime] section === − − This section describes parameters that should be taken into account only if service has 0install implementations(including source implementations) in contrast with [[Documentation Team/Services/Native packages usage|pure]] wrappers around native packages. − − Section contains: − − * ''version'', used only for services with [[#Native_versions|native]] versioning scheme − * ''binding'', what environment variables, 0install should export to session which uses this service − binding = [prepend|append|replace] ''<variable-name>'' [''<insert-text-to-prepand-variable-value>''] [; ...] − * ''main'', for applications, path to exec file from service root directory − * ''requires'', for any arch and binary implementations, list of runtime services that should exist before using service − requires = <service-name> [<not-before-version>[-<before-version>]] [; ...] − * exec, command how to make bundle for ''dist'' command, ''0sugar'' will pick up newly created file in service root directory<br>Shell command, executed from service root directory. If this command starts to get complicated, you should move it to a script and just set this attribute to the command to run the script.<br>By default ''0sugar'' just bundle entirely service directory excluding temporary files. − exec = make distcheck − − === [Library] section === − − Adds additional parameters if service is a library. Libraries should have plain ''version'' value and with ''age'' field, it will be used in [http://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html#Libtool-versioning libtool] like style e.g. in [[#Autotools|autotools]] based projects. − − Section contains: − − * ''age'' libtool like age of version − − === [Buildtime] section === − − File ''service.info'' could have optional ''[Buildtime]'' section which describes additional parameters that should be taken into account during other service(which uses this one) building i.e. it is an equivalent for *-dev(el) packages in GNU/Linux distributions. − − Section contains: − − * ''requires'', additional dependencies that will be required during building other service which depends on this one − − * ''exec'', command how to make buildtime bundle for ''dist'' command<br>Shell command, executed from service root directory. If this command starts to get complicated, you should move it to a script and just set this attribute to the command to run the script.<br>By default ''0sugar dist'' uses the same bundle as for runtime feed − − * ''generate-documentation'', if set, documentation project will be created on [http://api.sugarlabs.org/services/], for now only ''epydoc'' value is supported − − === [Build] section === − − If service contains binary implementations, this section should present to describe building process. − − Section contains: − − * ''requires'', what services should be installed before building this one from sources − requires = <service-name> [<not-before-version>[-<before-version>]] [; ...] − − * ''exec'', command how to build binaries<br>Its value is a shell command, executed inside the build directory $BUILDDIR. It must compile the source in $SRCDIR, putting the final result (ready for distribution) in $DISTDIR. If this command starts to get complicated, you should move it to a script (either inside the main source archive or in a separate dependency) and just set this attribute to the command to run the script.<br>'''NOTE''': This command will be executed not only in service developer environment but also on user side if proper binary wasn't found, so do not use here any development related commands like ''autogen.sh''<br>For example, followed command builds regular autotools based project − exec = "$SRCDIR"/configure --prefix="$DISTDIR" && make install − − === Support several ABIs of service dependencies === − − File ''service.info'' could contain other sections for various binary implementations. These sections are intended to describe particular dependencies environment and should contain only: − − * ''requires'' that overwrite ''Service'''s section ''requires'' − − For example if service developer is going to add binary implementations for f9/f11, and the same service dependency in these distributions has different ABIs, activity developer has to build two additional binaries, for f9 and f11. In that case developer creates two sections ''F9'' and ''F11'', put exact dependency versions(to separate particular section from others) and invoke ''0sugar dist_bin <section-name>'' in proper f9/f11 environment. Line 115:
Line 47: − − == Development workflows == − − How to build services. − − === Any arch services === − − Work flow for services that don't require compilation stage thus could be just packaged and used as is on server side: − − * create local initial service.info by invoking ''0sugar init'', tweak newly created ''service/service.info'' file − * increase/change version field in ''service.info'' file − * ''0sugar dist'' to change local feed in ''dist/'' and place there tarball − * ''0sugar push stable'' to rsync changed files from ''dist/'' to the server<br>see [[#Release workflows]] for other release scenarios − − === Binary services === − − Work flow for services that require compilation stage: − − * create local initial service.info by invoking ''0sugar init'', tweak newly created ''service/service.info'' file − * provide relevant value for ''build-command'' field in ''service.info'' file − * if you want to support binaries for different dependencies environments, add additional sections to ''service.info'' file with ''requires'' fields that describe dependencies versions of particular environment − * increase/change version field in ''service.info'' file − * ''0sugar dist'' to add sources tarball to ''dist/'' and change local feed correspondingly − * on every platform, you are trying to support binaries for, run ''0sugar dist_bin'' to build, and add to local field, binaries for this particular platform − * if you added additional sections to ''service.info'', run ''0sugar dist_bin <section-name>'' in every environment, ''services.info'' has additional sections for − * ''0sugar push stable'' to rsync changed files from ''dist/'' to the server<br>see [[#Release workflows]] for other release scenarios Line 176:
Line 82: + + + + + + + + + − Useful scenarios for service release process.+ − − === Having only stable releases === − + − + − === Bugfix releases ===+ Line 200:
Line 113: − === Development releases ===+ Line 207:
Line 120: − + − − == Development tools support == − − Useful addons to popular development tools. These are optional features that simplify service development process. − − === Autotools === − − Add [http://git.sugarlabs.org/projects/toolkit/repos/mainline/blobs/master/m4/service.m4 service.m4] macros file to your project. It provides: − − * ''SERVICE_INIT'' macro to initialize services support, use it after other (AC|AM)_INIT macros like in [http://git.sugarlabs.org/projects/toolkit/repos/mainline/blobs/master/configure.ac]<br>It takes optional string to define prefix value for ''DIST_'' variables, in most cases it should be just ''sugar''<br>Macro exports follows variables: − ** ''SERVICE_NAME'', name of service in service.info file − ** ''SERVICE_VERSION'', version of service in service.info file − ** ''SERVICE_REVISION'', revision number from dist/revision file − ** ''DIST_NAME'', combines prefix macro argument with ''SERVICE_NAME'' to use it as a distribution name(see example below) − ** ''DIST_VERSION'', combines ''SERVICE_VERSION'' and ''SERVICE_REVISION'' to use it as a distribution version(see example below) − ** ''SERVICE_SUMMARY'', summary from service.info file − ** macro also changes ''PACKAGE'' and ''VERSION'' variables with values from proper ''DIST_'', so it rewrites ''AC_INIT'' arguments(you have to use fake values for ''AC_INIT'' macro) − ** if ''[Library]'' section exists in service.info file, macro will − *** check if ''SERVICE_VERSION'' is a plain number − *** export ''SERVICE_AGE'', age from ''[Library]'' section − *** export ''SERVICE_LIBRARY_VERSION'' which is libtool's -version-info parameter − *** if ''service.pc.in'' presents in root directory, rename it to ''DIST_NAME''.pc.in − − * ''SERVICE_ECHO'' convenient macro to print various variables − − These macros could be used like in [http://git.sugarlabs.org/projects/toolkit/repos/mainline/trees/master Toolkit] serivce.
Platform Team/Guide/Sweets Packaging (view source)
Revision as of 13:03, 15 January 2010
, 13:03, 15 January 2010no edit summary
<noinclude>{{GoogleTrans-en}}{{TOCright}}
<noinclude>
{{TOCright}}
[[Category:Activity Team]]
[[Category:Activity Team]]
</noinclude>
</noinclude>
* one or several binary implementations in ''<implementation>'' tags, that contain binaries of the same source implementation but for various architectures(attribute ''arch'')
* one or several binary implementations in ''<implementation>'' tags, that contain binaries of the same source implementation but for various architectures(attribute ''arch'')
* package implementation in ''<package-implementation>'' tag, to reuse native packages, see [[Documentation_Team/Services/Native_packages_usage|Native packages usage]] for more info.
* package implementation in ''<package-implementation>'' tag, to reuse native packages, see [[Documentation_Team/Services/Native_packages_usage|Native packages usage]] for more info.
== 0sugar tool ==
== 0sugar tool ==
Feed files in ''dist/'' directory could be changed manually but keep in mind that ''dist*'' commands will rewrite entries for current service version.
Feed files in ''dist/'' directory could be changed manually but keep in mind that ''dist*'' commands will rewrite entries for current service version.
== Versioning scheme ==
== Versioning scheme ==
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 [[#Bugfix_releases|bugfix releases]] workflow.
== Development workflows ==
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]] 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
== Release workflows ==
== Release workflows ==
'''Having only stable releases'''
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''/''0sugar dist_bin'' to make local releases
* ''0sugar dist*'' to make bundles
* ''0sugar push stable'' to rsync local releases 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 wrong time to release and you want to re-release it, repeat previous steps to rewrite wrong release
'''Bugfix releases'''
Services assume simple versioning scheme, if you found bugs in stable version:
Services assume simple versioning scheme, if you found bugs in stable version:
0sugar push {buggy|insecure} {version[-revision]}
0sugar push {buggy|insecure} {version[-revision]}
''' Development releases '''
If you want to test your new version among interested people:
If you want to test your new version among interested people:
* but use either ''testing'' or ''developer'' status for ''push'' command
* but use either ''testing'' or ''developer'' status for ''push'' command
* users who interested in testing(enabled testing mode) will get your new development version
* users who interested in testing(enabled testing mode) will get your new development version
* you don't have to change ''compatibility-version'' and ''version'' all time for micro releases, ''0sugar'' will implicitly change revision of new pushes and user's saccharin will download last changes
* 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
== Tips ==
== Tips ==