Documentation Team/Services/Activity Developers Guide

From Sugar Labs

Contents 1 Introduction 2 Requirements 3 Using services 4 Launching 0install applications 5 Known issue

Introduction

The purpose of this Guide is to describe how to use Sugar Services for activity developers.

0sugar launching code will export the proper environment variables to the activity process, e.g., PYTHONPATH for python based services or LD_LIBRARY_PATH for binary services, i.e., the activity developer needs to use dependencies like they were installed to the /usr directory.

Requirements

To use services in your development environment, 0install and 0sugar-injector are required.

• Install latest version of patched zeroinstall-injector, see also 0install [1] for more 0install-related information.

• Tweak the PATH environment variable, and after executing this command, you need to relogin

echo 'PATH=~/.local/bin:$PATH' >> ~/.bashrc

• Register 0install aliases

0alias 0sugar-inject http://services.sugarlabs.org/0sugar/injector.xml
0alias 0sugar-launch http://services.sugarlabs.org/0sugar/launcher.xml

Using services

• Choose services that you want to use in your activity, see wiki pages or entirely list (subdirectory names are particular service names)
  See Sibling section on service http page (like [2]) to know about sub services, e.g., toolkit is a main service and contains only .so libraries and toolkit/python is a sub service, which contains python bindings

• Add new field requires to your activity.info file and list all services (sub services should be in format <service name>/<subname w/o ".xml" suffix>)

requires = <service-name> [{>=|<|~} <version>] [, ...]

• If services are optional, add new field suggested to your activity.info file and list all services where existence is optional

suggests = <service-name> [{>=|<|~} <version>] [, ...]

• To start an activity (and any command) from the command line with all dependencies exported, run from activity (sub)directory:

0sugar-launch <any-command-e.g.-sugar-activity>

• To let sugar-shell proper run your activity from the sugar environment, use 0sugar-inject
  the command will prepend the exec option in the activity.info file with the .0sugar/launch script, which will run 0sugar-launch (that's because 0sugar-launch is not part of glucose and most likely the user environment will not have it), and add the .0sugar directory to .gitignore files since the whole .0sugar directory should not be added to a VCS repository.

0sugar-inject init

• To create an .xo bundle with all 0sugar dependencies included
  the command will bundle all the requires dependencies so the user will not download them (but further dependency updates will be supported).

0sugar-inject dist_xo

Launching 0install applications

If there is an 0install application that should start in sugar properly, the easy way to do it:

• Create empty directory for activity root,
• Compose an appropriate service/service.info file,
• Add the following strings to the activity.info file,

exec = .0sugar/launch -main -sugarize
requires = <service-name|full-0install-link>, libsugarize

• Place setup.py file to the activity root directory
• Run 0sugar-inject command from the activity's root directory to create the .xo bundle

0sugar-inject dist_xo

Known issue

• Due to 0install design, under rainbow, 0sugar uses a per activity 0install cache, so if two activities have the same dependency they will use their own copy (it could be changed in the future to share the same code between activities).

• 0sugar can install dependencies from native packaging systems only if PackageKit and PolicyKit(default PackageKit's auth method) are installed and set up (e.g., auth agent for PolicyKit).