Hacking Sugar

Here are various threads about how to program sugar, handbooks for running and demonstrating specific activities, and other ways to hack your XO. If you have written about how to hack sugar, program Activities for the XO, or make new projects within popular activities, please add links to your notes here. See also Hacking your XO

Fun tricks

Alternative 'favorites view' layouts

In /usr/share/sugar/shell/view/home/favoritesview.py there is a chunk of code that looks like:

_LAYOUT_MAP = {RING_LAYOUT: favoriteslayout.RingLayout,
               #BOX_LAYOUT: favoriteslayout.BoxLayout,
               #TRIANGLE_LAYOUT: favoriteslayout.TriangleLayout,
               #SUNFLOWER_LAYOUT: favoriteslayout.SunflowerLayout,
               RANDOM_LAYOUT: favoriteslayout.RandomLayout}

If you remove the '#' characters, you can try out three new fun 'home view' layouts for your icons! See <trac>7685</trac> for some screenshots.

The code for the new layouts is further down in that same file. Some other fun shapes it might be fun to try to code: Hypocycloid (a/b=5), Butterfly, Heart, Quadrifolium, Rose, and Superellipse (the 'starfish' example).

This hack will only work on newer software builds, because older builds do not have the alternative layouts. They were introduced in build 8.2-761 (Sugar version 0.82.8).

Programming Sugar

...from recent discussions with Christoph Derndorfer and others: OLPC Austria are working on a set of guidelines for hacking sugar and specific activities.

chapters that we're thinking to include:

#0: "Preface"
#1: "Introduction"
#2: "Sugar Basics"
#3: "Sugar User Interface"
#4: "Using the XO Input Devices"
#5: "Collaboration"
#6: "Content Sharing"
#X: "Turning existing applications into activities"

Note: We're always open for suggestions and comments with regards to the Activity Handbook that we're working on, please submit them via the sugar mailing-list (and include "handbook" in the subject so we can easily filter the messages) or directly contact me at handbook AT olpcaustria.org. Thanks! ChristophD 14:59, 12 October 2007 (EDT)

Update (2008-01-14): The first version of the activity handbook is now available. ChristophD 09:50, 14 January 2008 (EST)

Hacking Sugar v1

below is recent work by edsiper; needs to be merged with Sugar development and Sugar and Activity tutorial... and other pages.

Introduction

Hacking Sugar is a public resource for developers that want to get involved in the Sugar Shell development. Here you can find useful information about how to hack/write new sugar components or write external activities and how to integrate them in Sugar.

Sugar is a big opportunity for developers, you can get involved and get the chance to create and improve this wonderful graphical Shell

Motivation

Over the last two years, OLPC has developed and improved a lot of components for the XO platform, including Hardware, Firmwares, Linux Devices Drivers and a graphical shell for kids called Sugar. To start working in an open source project, sometimes it can be a little difficult if you don't have an updated documentation about "how this piece of software works ?", and you have to spend some time reading the source code.

The OLPC project, specially Sugar is changing every day, new API, components, ideas, etc. The main idea of "Hacking Sugar" is to write a collaborative document where you can find the exact information you require and a lot of tips from experienced developers.

Is this document for me?

Every time that we read some document, we ask our self if "is this document that we want?", so let's do some questions before to spent many hours reading this:

• Do I have development skills? If not, would I like to learn?
• Do I want to learn a lot of Python, GTK and Sugar Internals?
• Do I want to contribute and to put a better laptop in the hands of every child?

If your answer is yes to each of these, I'm happy that we have a new contributor.

OLPC, a collaborative work

OLPC is a big project, and talking about the software components we can't avoid to talk about how is development done? OLPC has a main staff of developers, most of them provided by RedHat Inc. and lot of collaborators and volunteers from different countries. The big part of this job is done through Internet. Let's understand how.

Softwares are in repositories

Repositories are specialized software hosted in central servers that allow to manage different project with a Version Control System, the selected one by OLPC is GIT. So all of the software for OLPC is hosted in a development server called dev.laptop.org. Every piece of software has its own repository and its own maintainer and developers. You can browse through the code, look for applied patches, commits, revision changes, etc. A real example about this is here:

• http://dev.laptop.org/git

To learn about how to get the software from the GIT respositories, do some patch and others, please read these helpful pages:

• Git
• Git tips (advanced tips)

So if want to develop some SW, try to install GIT in your local Linux distribution, it's a good step to start ;)

Bug Tracker

As everybody knows, software can have a lot of problems such as special cases with bad validations or security holes that can cause many problems. It's indispensable to file this information in a bug tracking system in order to be sure that every problem has been fixed and which of it's not. Bug trackers allow to assign special problems or task TO-DO to specific developers, in OLPC the tracker system can be found here:

http://dev.laptop.org/query

So you have to sign up to the track system and then view/create/comment tickets, report bugs or maybe assign your self some ticket not assigned (it's your opportunity to contribute) (ie: #1)

Communication

Sharing ideas is fundamental, and more important is the opinion from others about it. Communication is the base of every project and is more difficult in this case where people participate from all over the globe. OLPC uses various channels of communications such as:

• IRC (Internet Relay Chat) - irc.freenode.net #olpc #sugar #olpc-help
• Mailing lists
• Teleconference calls
• The OLPC Wiki!

You can always find someone available to help in the IRC channels, join us!

Mailing List

Some useful page about all mailing list available here:

http://lists.laptop.org/listinfo

Help is welcome!

Being creative is important but ideas are not just restricted to creating something new. In Sugar, there are three main areas that need your contribution:

• Sugar core development
• Sugar Activities
• Localization

Sugar Core is not complicated but there are a lot of widgets to build in order to use them in activities. You could improve the internal API, come up with ideas about how to speed up modules, etc. Take a look at the code, you'll need some Python knowledge but don't feel scared, it's just Python!

Activities are external programs to the Sugar Core. They are PyGTK programs Sugarized and called activities. You can create an Activity or just "sugarize" a good PyGTK program, in this document we will explain how.

OLPC is going to work in different countries in different languages. Most of the activities are written in English so we need help with translation. Please have a go!

Sugar

Sugar is the core of the OLPC Human Interface. Its goal is to turn the Laptop into a fun, easy to use, social experience that promotes sharing and learning. Our first step is to learn how sugar works. In order to do that, it's necessary to have some basic Python knowledge. If you don't know about Python, you can learn about it in http://www.diveintopython.org. Please read the book, to do some examples and come back here :) .

Sugar is not a Desktop like Gnome, KDE or XFCE. It is a Graphical Shell for kids and this shell has been written from scratch following the HIG (Human Interface Guidelines). So every change, feature or new component in the core of sugar must be approved by the designer team.

This great UI (user interface) needs external components to work in a better way (similar to normal Desktops). As a base, we need a Linux OS (no restricted distribution) and additional software such as:

• D-Bus
• HAL
• Hippo-Canvas
• GTK+
• Avahi
• Matchbox Window Manager
• Network Manager
• Others...

How Sugar takes the control?

Code-wise, Sugar is a GTK+ program that requires a windows manager and an X Server. A main Python script called sugar-shell executes the matchbox-window-manager, which connects to the X server, and then the script stays in the gtk main loop. Now we have a main window as an UI and have the control. Please take a look at:

http://dev.laptop.org/git?p=sugar;a=blob;f=src/main.py;hb=HEAD

http://dev.laptop.org/git?p=sugar;a=blob;f=bin/sugar-shell.in;hb=HEAD

Setting up a development environment

In order to develop software for Sugar (core or activities) you need a development environment. There are two main options: emulating the entire system, or using JHbuild to compile the system and run it natively.

Emulation Images

OLPC provides, every day, a system image. You only need to run it inside an emulation environment. The recommended one is QEMU, please take a look to this page for more information about how to emulate a XO system image:

Emulation

Sugar JHBUILD

JHbuild is a general tool to build collections of source packages. The main idea is build a piece of software and all its dependencies in a local directory, set up an environment that is isolated from the local system. Sugar-JHBuild allows you to have a safe running Sugar environment inside your local desktop. In order to get Sugar running, you need to get sugar-jhbuild and run the 'build' process:

Get Sugar-JHBuild

git clone git://dev.laptop.org/sugar-jhbuild

Check Local Dependencies

Sugar will probably need some package dependencies from your local distribution. Let's run a sanity check:

cd sugar-jhbuild
./sugar-jhbuild sanitycheck

If you got the message Dependencies check succeeded., you're ready to build sugar. If not, take a look at the dependencies needed in order to build sugar. If you have some problems or the dependencies are not available for your Linux distribution, use an irc client to connect to the #sugar channel on irc.freenode.net and ask for help.

Building Sugar

This process can take some time (some hours in some cases!). sugar-jhbuild is tries to download a lot of packages and compile them. It is essential to have a decent connection to the Internet. Let's build Sugar and it dependencies:

./sugar-jhbuild build

Running Sugar

If all the packages were built without problems, you can enjoy your sugar:

./sugar-jhbuild run

More information about Sugar-JHBuild

You can find more information about sugar-jhbuild and some tips here:

Sugar with sugar-jhbuild

To emulate or not to emulate? JHBuild or not?

What's better? It all depends on what you want to do. If you are just writing a simple Activity and you need to test it, an emulated system might be the answer. For standard sugar hacking I recommend Sugar-JHBuild. It takes more time to set up but once it's ready you will have a flexible development environment.

Activities

Every end user application in Sugar is called an "Activity". In the development scene and in this document we use the term "Activity Bundle", which defines a group of related files: source code, images, and documentation.

Simple activity bundle example

If we are interested in developing an activity bundle for Sugar, we need to know the main structure and its requirements. You can get a very simple activity bundle sample here:

File:Hellokids-activity.tar.gz

Please download the 'Hello Kids' activity bundle example and uncompress it with the command:

$ tar zxvf hellowkids-activity.tar.gz

Every activity bundle is a main directory with a name followed with the '-activity' string, like hellokids-activity.tar.gz. Let's see what we have inside our activity:

\-> hellokids-activity/
 |--> hellokids-activity/activity/
 |--> hellokids-activity/activity/activity.info
 |--> hellokids-activity/activity/hellokids-icon.svg
 |--> hellokids-activity/README
 |--> hellokids-activity/TODO
 |--> hellokids-activity/setup.py
 |--> hellokids-activity/NEWS
 |--> hellokids-activity/hellokids.py

• hello-activity: Main directory, the activity bundle!
• hello-activity/activity/: Here's the configuration directory of our bundle composed by two files.
• hellokids-activity/activity/activity.info: This file contains sugar the activity information:

[Activity]
name = Hello Kids
activity_version = 1
service_name = org.laptop.HelloKids
icon = hellokids-icon
exec = sugar-activity hellokids.HelloKidsActivity

This file contain some variables and values assigned to them:

• name: The activity name. This name is shown in the sugar bottom frame where the activities icons launcher are located.

• activity_version: Every bundle has a version number. We use a simple version format with integers starting from 1 to infinity.

• service_name: Bundles are identified by a service-name. This name is used for Sugar and D-Bus in order to launch the activity. Every activity bundle has a different service name. You can choose your own.

• icon: The activity icon. Every icon must be a SVG file and in the icon field we just fill the name without the '.svg' extension.

• exec: A shortened form of 'executable command line' to launch the activity. The format is 'sugar-activity yourmainfile.yourmainactivityclass'. For our first example we are telling sugar: call the HelloKidsActivity class from the hellokids file.

• hellokids-activity/activity/hellokids-icon.svg: The activity icon. Ref: Sugar Icon Format

• hellokids-activity/README: Write some information about your activity.

• hellokids-activity/TODO: It's always good to have a 'To Do' list containing needed features, bugs to fix, optimizations, etc.

• hellokids-activity/setup.py: This file allow as to build a XO activity bundle. Just put your activity name inside the bundlebuilder.start() call.

• hellokids-activity/NEWS: News about your activity.

• hellokids-activity/hellokids.py: Our main program, let's explain the content:

class HelloKidsActivity(activity.Activity):
   def __init__(self, handle):
       activity.Activity.__init__(self, handle)
       logging.debug('Starting the Hello-Kids Activity')
       self.set_title(_('Hello Kids Activity'))

       button = gtk.Button('Hello Kids!!!')
       button.connect('clicked', self._print_message)
       button.show()

       # CANVAS
       self.set_canvas(button)

       # TOOLBAR
       toolbox = activity.ActivityToolbox(self)
       self.set_toolbox(toolbox)
       self.show_all()

       # Dirty hide, we use this code to hide the 'share' and 'keep' 
       # buttons from the toolbar, we don't need it for now...
       toolbar = toolbox.get_activity_toolbar()
       toolbar.share.hide()
       toolbar.keep.hide()

   def _print_message(self, widget):
       print "Hello Kids !!!"

You can see more details in the Activity Bundles specification.

See also

• PyGTK
• The Sugar Activity handbook
• Sugar Almanac covers the various Python packages in Sugar
• Beyond Hello World
• Flossmanuals - Modifying Sugar
• Modifying an Activity