5,705
edits
Changes
Sugar Network/Recipe Specification (view source)
Revision as of 11:32, 15 January 2010
, 11:32, 15 January 2010Created page with '<noinclude> {{TOCright}} Category:Activity Team </noinclude> Service publishing workflow is similar to activities. There is an info file, here ''service/service.info'', whic…'
<noinclude>
{{TOCright}}
[[Category:Activity Team]]
</noinclude>
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.info file is an analog of scenario files in regular GNU/Linux distributions like .spec files in RPM.
== [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.
{{TOCright}}
[[Category:Activity Team]]
</noinclude>
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.info file is an analog of scenario files in regular GNU/Linux distributions like .spec files in RPM.
== [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.