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
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 X0 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)
Hacking Sugar v1
below is recent work by edsiper; needs to be merged with Sugar development and Sugar and Sugar 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
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 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 ?
well, if you are reading this last line I'm happy that we got 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 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:
About how to get the software from the GIT respositories, do some patch and others, please read this helpful pages:
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
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:
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 the people are around the world, OLPC uses different 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:
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 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 as Gnome, KDE or XFCE, it's 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 base, we need a Linux OS (no restricted distribution) and aditional software as:
- D-Bus
- HAL
- Hippo-Canvas
- GTK+
- Avahi
- Matchbox Window Manager
- Network Manager
- Others...
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:
Sugar Internals
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:
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:
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 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 need some packages dependencies from your local distribution, let's run a sanity check:
cd sugar-jhbuild ./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.
Building Sugar
This process can take some time (some hours in some cases!), sugar-jhbuild is 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:
./sugar-jhbuild build
Running Sugar
Now if all packages was 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:
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.
Activities
Every end user application in Sugar receive the name of "Activity" and for a development scene and in this document we are going oto use the term "Activity Bundle", which define a group of related files—source code, images and documentation.
Simple activity bundle example
If we are interested in develop an activity bundle for Sugar, we need to know the main structure and it requirements, here you can get the most simple activity bundle sample:
Please download the 'Hello Kids' activity bundle example and uncompress it with:
$ tar zcfv 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 tells 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 showed in the sugar bottom frame where the activities icons launcher are located.
- activity_version: Every bundle has a version number, it just use a simple version format with integers starting from 1 to the infinite.
- 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 the own you.
- icon: The activity Icon, every icon must be a SVG file and in the icon field we just fill the name avoinding the '.svg' extension
- exec: It means the 'executable command line' to launch the activity, the format is 'sugar-activity yourmainfile.yourmainactivityclass'. So 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: Always is good to have a 'To Do' list, some features needed, bugs to fix, improves, 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.