Write your own Sugar desktop activity
Most Sugar desktop activities are written in Python, using our Sugar Toolkit libraries.
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:
~/Activitiesfor native Sugar desktop, and packaged Sugar desktop on Fedora, Debian or Ubuntu;
/usr/share/sugar/activitiesfor packaged Sugar desktop; and,
~/sugar-build/activitiesfor sugar-build only.
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
.activity suffix in the directory name of an activity,
because that's the way an activity bundle is released.
Your clone of the Hello World activity contains a file,
[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
org.sugarlabs.my-activity-name is not valid. Instead, use
You should change the Activity class in your
activity.py file, e.g., from:
You must change the
exec field as well, e.g., from:
exec = sugar-activity3 activity.HelloWorldActivity
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.
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
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.
You should rename this file and change
icon in the
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;
type the name of your activity into the search entry and press enter; or,
select the List View (ctrl+2) to see your activity, and click on it.
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
Log files for sugar-build are in the directory
Log files are named using the
You may also test interactively by starting Terminal, then
cd to the activity directory, and type:
All activities should follow this file structure:
MyActivity.activity/ |-- activity/ | |-- activity.info | `-- activity-icon.svg |-- activity.py `-- setup.py
activity/contains information about your activity, including the
bundle_id, and the
activity.pycontains an instance of the activity class, which is run when your activity is launched.
setup.pylets you install your activity or make an installable bundle with it.
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:
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
Make Your Own Sugar Activities, a book by James Simmons.
We currently use Python 3 for the Sugar Toolkit and Sugar activity development.
To check for flake8 warnings in the current directory, run this command
python3 -m flake8 *.py