Write your own Sugar desktop activity

Most Sugar desktop activities are written in Python, using our Sugar
Toolkit libraries.

Some Sugar desktop activities are written in languages other than
Python, such as Smalltalk, C, and JavaScript. For new activities to
run on both Sugar desktop and Sugarizer, please consider Write your
own Sugar web activity.

This page shows how to develop an activity using Python 3 with Sugar Toolkit.

Setting up a development environment

Setup a development
environment, for testing your activity and
releasing it for distribution.

Create a new activity from a template

Locate the activity directories. They may include:

Each installed activity is in a directory under the activity
directories. This is where you will create your new activity.

Clone the Hello World activity from
hello-world on GitHub:

git clone https://github.com/sugarlabs/hello-world-fork.git Name.activity

Use the .activity suffix in the directory name of an activity,
because that's the way an activity bundle is released.

Customize

Your clone of the Hello World activity contains a file,
activity/activity.info:

[Activity]
name = HelloWorld
activity_version = 1
bundle_id = org.sugarlabs.HelloWorld
exec = sugar-activity3 activity.HelloWorldActivity
icon = activity-helloworld
licence = GPLv3+
repository = https://github.com/sugarlabs/hello-world-fork.git

You must set a new name and a unique bundle_id for your activity.

Avoid punctuation in your bundle_id, e.g.,
org.sugarlabs.my-activity-name is not valid. Instead, use
CamelCase, e.g., org.sugarlabs.MyActivity.

You should change the Activity class in your activity.py file, e.g., from:

class HelloWorldActivity(activity.Activity):

to:

class MyActivity(activity.Activity):

You must change the exec field as well, e.g., from:

exec = sugar-activity3 activity.HelloWorldActivity

to:

exec = sugar-activity3 activity.MyActivity

You should set the repository field to the URL of the git repository
of your project.

And we recommend that you use a GPLv3+ license.

Your activity.info file will look something like:

[Activity]
name = MyActivity
activity_version = 1
bundle_id = org.sugarlabs.MyActivity
exec = sugar-activity3 activity.MyActivity
icon = activity-helloworld
licence = GPLv3+
repository = https://github.com/MyGitHubAccount/MyActivityRepo.git

To read more about the activity.info file, see Activity
Bundles
on our Wiki.

You must make your activity icon unique in the Sugar interface by
making a new one, or borrowing from another icon and making changes.
Ask for help from the community if you don't feel comfortable with
graphic design.

Here is activity/activity-helloworld.svg;

Activity Icon

You should rename this file and change icon in the activity.info
file.

Your activity icon must follow the guidelines as described in
The Sugar Interface:
Icons on our Wiki.

There is a helper script, Sugar
Iconify that will help
you create Sugar-compliant icons.

Of course, the interesting changes will be the ones you make to the
activity itself. Below you will find links to some resources
on Sugar Activity development, but perhaps the
best way to get started is to modify an existing activity that has
features similar to the one you want to create.

Running your activity

Launch Sugar and your new activity should be immediately available,
although since it has not yet been selected as a favorite, it will
not appear by default on the Sugar Home View (F3). You need to either;

If all goes well, your activity will launch.

There are many opportunities to make mistakes. Don't get discouraged,
as debugging is a great way to learn. One useful tool is the Log
Activity, which will show you the log files of the operating system,
Sugar and activities. Alternatively, you can look at the log files
from the command line.

Log files are usually in the directory ~/.sugar/default/logs.

Log files for sugar-build are in the directory ~/sugar-build/home/dotsugar/default/logs.

Log files are named using the bundle_id.

You may also test interactively by starting Terminal, then cd to the activity directory, and type:

sugar-activity .

if your activity uses python2. If it uses python3, type:

sugar-activity3 .

File structure

All activities should follow this file structure:

MyActivity.activity/
|-- activity/
|   |-- activity.info
|   `-- activity-icon.svg
|-- activity.py
`-- setup.py

Translation

Sugar serves a global audience, so it is important to enable your
activity for internationalization and localization. A guide to best
practices
is on our Wiki.

Revision control your code

For development you can initialize the repository as a git
repository. This will help you to track your changes. First use git
init
to initialize the repository:

git init

With git
status
you can show the available files in the folder they are still
untracked. Now add all the files in the directory and commit those
changes, you can use git status again to see the current state:

git add .
git commit -a -m 'Initial import'
git status

We recommend that you use github to host your
activity.

Check Python Coverage of your activity

You can check the Python Coverage of your activity by following this guide.

Ready to release

Once your activity is working, you can ask to have
your activity repository hosted under the Sugar Labs github
organization.

Make an XO bundle.

python setup.py dist_xo

And if it works with Python 2 then upload it to the Sugar Activity
Library http://activities.sugarlabs.org/.
After that, users of Sugar can download and install your activity.

For further releases, you must update the activity_version in
activity/activity.info.

More details

Coding standards

We currently use Python 3 for
the Sugar Toolkit and Sugar activity development.

We recommend flake8 as a
wrapper around the pep8
and pyflakes code checkers.

To check for flake8 warnings in the current directory, run this command

python3 -m flake8 *.py