Hacking Sugar: Difference between revisions

From OLPC
Jump to navigation Jump to search
m (Reverted edits by 96.242.230.3 (Talk) to last revision by Tonyforster)
 
(88 intermediate revisions by 23 users not shown)
Line 1: Line 1:
<div style="float:right; font-size:90%">
__TOC__
</div>

Here are various threads about how to program sugar, handbooks for running and demonstrating specific [[activities]], and other ways to [[hacking your XO|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 <code>/usr/share/sugar/shell/view/home/favoritesview.py</code> there is a chunk of code that looks like:
<pre><nowiki>
_LAYOUT_MAP = {RING_LAYOUT: favoriteslayout.RingLayout,
#BOX_LAYOUT: favoriteslayout.BoxLayout,
#TRIANGLE_LAYOUT: favoriteslayout.TriangleLayout,
#SUNFLOWER_LAYOUT: favoriteslayout.SunflowerLayout,
RANDOM_LAYOUT: favoriteslayout.RandomLayout}
</nowiki></pre>

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: [http://mathworld.wolfram.com/Hypocycloid.html Hypocycloid] (a/b=5), [http://mathworld.wolfram.com/ButterflyCurve.html Butterfly], [http://mathworld.wolfram.com/HeartCurve.html Heart], [http://mathworld.wolfram.com/Quadrifolium.html Quadrifolium], [http://mathworld.wolfram.com/Rose.html Rose], and [http://mathworld.wolfram.com/Superellipse.html 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! [[User:ChristophD|ChristophD]] 14:59, 12 October 2007 (EDT)


'''Update (2008-01-14):''' ''[http://www.olpcaustria.org/mediawiki/index.php/Activity_handbook The first version of the activity handbook]'' is now available. [[User:ChristophD|ChristophD]] 09:50, 14 January 2008 (EST)

= Hacking Sugar v1 =
''below is recent work by [[User:Edsiper|edsiper]]; needs to be merged with [[Sugar development]] and [[Sugar]] and [[Activity tutorial]]... and other pages.''

== Introduction ==
== Introduction ==


Line 6: Line 54:


== Motivation ==
== 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.
In the latest 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 a 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 spent 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 exactly information about your needs and a lot of tips from experienced developers.


== Is this document for me ? ==
== 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:
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:
<ul>
<li> do I have a developer skill, if don't, do I would like to have one?
<li> do I want to learn a lot of Python, GTK and Sugar Internals ?
<li> do I want to contribute and to put a better laptop in the hands of every child ?
</ul>


* Do I have development skills? If not, would I like to learn?
well, if you are reading this last line I'm happy that we got a new contributor.
* 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, 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, and the big part of this job is done through Internet. Let's understand how.
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 ===
=== Softwares are in repositories ===


Repositories are specialized software hosted in central servers that allow to manage different project with a Control Version System, the selected one by OLPC is GIT. So all pieces of softwares of OLPC are hosted in a development server called dev.laptop.org, every piece of software has it's own repository and it's 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:
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|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
<ul>
<li>http://dev.laptop.org/git
</ul>


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


* [[Git]]
About how to get the software from the GIT respositories, do some patch and others, please read this helpful pages:
* [[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 ;)
<ul>
<li>http://wiki.laptop.org/go/Git
<li>http://wiki.laptop.org/go/Git_Tips (advanced tips)
</ul>


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


=== Bug Tracker ===
=== 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 tracker 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:
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
<ul>
http://dev.laptop.org/query
</ul>


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)
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: {{ticket|1}})


=== Communication ===
=== 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 the people are around the world, OLPC uses different channels of communications such as:
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|IRC (Internet Relay Chat)]] - irc.freenode.net #olpc #sugar #olpc-help
<ul>
* [[Mailing lists]]
<li> IRC (Internet Relay Chat) - irc.freenode.net #olpc #sugar #olpc-help
* Teleconference calls
<li> Mailing List
* [[The OLPC Wiki]]!
<li> Teleconferences call
<li> WiKi! http://wiki.laptop.org
</ul>


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


====Mailing List====
====Mailing List====

Some useful page about all mailing list available here:
Some useful page about all mailing list available here:

<ul>
http://lists.laptop.org/listinfo
: http://lists.laptop.org/listinfo
</ul>


== Help is welcome! ==
== Help is welcome! ==


Be creative is important but this ideas are not restricted to "create something new", in Sugar you have two mainly areas where to contribute:
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:
<ul>
<li> Sugar core development
<li> Sugar Activities
<li> Localization
</ul>


* Sugar core development
Sugar Core is not so difficult, but it needs to read some code, there's necessary to build a lot of widgets in order to use them in activities, you can improve the internal API, public ideas about how to speed up some modules, etc. Take a look to the code, you need some Python knowledge, don't feel scared it's just Python!
* 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 aims to be a PyGTK program Sugarized called activities. You can create an Activity or just "sugarize" a good PyGTK program, in this document we will explain you how.


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 different countries, different languages, most of the activities are written in english, do you will like to translate something ??, just do it!

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


== Sugar ==
== 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 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 as Gnome, KDE or XFCE, it's a '''Graphical Shell''' for Kids and this shell has been written from scratch following the [[HIG]]
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.
(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 base, we need a Linux OS (no restricted distribution) and aditional software as:
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
<ul>
* HAL
<li>D-Bus
* Hippo-Canvas
<li>HAL
* GTK+
<li>Hippo-Canvas
* Avahi
<li>GTK+
* Matchbox Window Manager
<li>Avahi
<li>Matchox Window Manager
* Network Manager
* Others...
<li>Network Manager
<li> Others...
</ul>


=== How Sugar takes the control? ===
=== How Sugar takes the control? ===


Talking about code, Sugar is a GTK+ program that require a Windows Manager and a X Server. A main python script called '''sugar-shell''' execute the matchbox-window-manager and this last one connect to the X server, and then the script stay in the gtk main loop. Now we have a main window as an UI and have the control. Please take a look to:
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
<ul>
http://dev.laptop.org/git?p=sugar;a=blob_plain;f=shell/sugar-shell;hb=HEAD
: http://dev.laptop.org/git?p=sugar;a=blob;f=bin/sugar-shell.in;hb=HEAD
</ul>


=== Sugar Internals ===
=== Sugar Internals ===
Line 121: Line 153:
== Setting up a development environment ==
== Setting up a development environment ==


In order to develop software for Sugar (core or activities) you need a development environment, we have different ways such as:
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 ===
=== Emulation Images ===


OLPC provide '''every day''' a system image, you only need to run it inside an emulation software, the recommended one is QEMU, please take a look to this page for more information about how to emulate a XO system image:
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]]
<ul>
http://wiki.laptop.org/go/Emulation
</ul>


=== Sugar JHBUILD ===
=== Sugar JHBUILD ===


JHbuild is a tool designed to make building collections of source packages, the main idea is build a piece of software and all it's dependencies in a local directory, setup and environment to work and it avoid to cause problems in the local system. Sugar-JHBuild allow 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:
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 with sugar-jhbuild|Sugar-JHBuild]] allows you to have a safe running Sugar environment [[:Category:Installing Sugar|inside your local desktop]]. In order to get Sugar running, you need to get sugar-jhbuild and run the 'build' process:


==== Get Sugar-JHBuild ====
==== Get Sugar-JHBuild ====

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


==== Check Local Dependencies ====
==== Check Local Dependencies ====

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


cd sugar-jhbuild
cd sugar-jhbuild
./sugar-jhbuild sanitycheck
./sugar-jhbuild sanitycheck


now if you got the message ''Dependencies check succeeded.'', you're ready to build sugar, if don't, take a look to the dependencies needed in order to build sugar, if you have some problems or the dependencies are not available for your Linux distribution, come to #sugar channel in the irc server to get some help.
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 ====
==== Building Sugar ====

This process can take some time (some hours in some cases!), sugar-jhbuild gonna try to download a lot of packages and compile them, in this case is indispensable an good internet connection. Let's build Sugar and it dependencies:
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
./sugar-jhbuild build


==== Running Sugar ====
==== Running Sugar ====

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


./sugar-jhbuild run
./sugar-jhbuild run


==== More information about Sugar-JHBuild====
==== More information about Sugar-JHBuild====

You can find more information about sugar-jhbuild and some tips here:
You can find more information about sugar-jhbuild and some tips here:
<ul>
http://wiki.laptop.org/go/Sugar_with_sugar-jhbuild
</ul>


: [[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:

[[Image:Hellokids-activity.tar.gz||desc]]


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 [http://www.olpcaustria.org/mediawiki/index.php/Activity_handbook Activity handbook]
*[[Sugar Almanac]] covers the various Python packages in Sugar
*[[Beyond Hello World]]
*[http://en.flossmanuals.net/Sugar/ModifyingSugar Flossmanuals - Modifying Sugar]
*[http://wiki.sugarlabs.org/go/Activity_Team/Modifing_an_Activity Modifying an Activity]


=== Emulate or not Emulate, JHBuild or not JHBuild? ===
What's better?, well, all depends about what do you want to do, If you are just writing a simple Activity and you need to test it, maybe a emulation system is your solution, but always I recommend to use Sugar-JHBuild, you can get some problems in the beginning but when it's ready you will have a flexible development environment.


[[Category:Sugar]]
[[Category:Sugar]]
[[Category:Software]]
[[Category:Developers]]

Latest revision as of 02:15, 10 March 2011

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:

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

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:

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 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

Sugar Internals

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