Getting started programming

Thank you for considering working on the One Laptop Per Child project. This page tries to provide you with the answers you need to get started either by contributing to existing projects or starting your own. See also Game Development Newbies

Setting up a Development Environment

The OLPC's software environment is a heavily modified Fedora Core Linux system running a custom GUI shell (Sugar). To develop for the platform you will eventually need access to a platform which runs in a manner substantially similar to the OLPC environment. Luckily there are many available options.

Option 1 - sugar-jhbuild

Compared with using an Emulated XO, installing sugar takes more time and space to set up, but results in a better environment. This is what the core development team uses.

On 32-bit Linux

sugar-jhbuild builds a parallel set of the libraries required to run the OLPC software. This approach generally works reasonably well on most modern Linux distributions. On some linuxes (32-bit Ubuntu, 32-bit Fedora(?)), it "just works". Though the build system (jhbuild) can be fragile. On others, you may spend quite some time rebuilding and fixing errors to get a final working system, so consider running a "just works" linux in emulation.

On Windows/Mac/Linux, with a vitual linux

sugar-jhbuild, on a virtual 32-bit Ubuntu, inside of an emulator (eg, Parallels, qemu, vmware).

Option 2 - Emulated XO

Running an XO OS image in emulation is, for Unix-friendly developers (those who like using command-line tools via ssh), the simplest way to start developing for the OLPC system. They can be run in one of the popular emulation/virtualisation systems, such as Qemu, VMWare or Parallels. These images allow you to run a virtual OLPC-configured machine on your regular development workstation.

These official images do not provide GUI IDEs or SVG graphics editors. They normally would be used either with command-line tools (e.g. VIM) or using NFS (or ssh, or similar) to a workstation on which you will do your actual coding.

Option 3 - Sugar pre-installed on a Linux image or LiveCD

Developer Images are intended to be used as virtual desktop machines. The images have far more software than is installed on the OLPC laptops. They resemble a developer's desktop machine which has been upgraded to support the Sugar environment. They tend to have GUI IDEs, full Gnome desktop installations and the like, which make it easy for developers to work entirely within the emulated environment.

Developers working on Developer Images should be sure to test their creations on real OLPC Laptops or official images in order to be sure that they do not have dependencies on software not available on the actual laptops.

As of 2007-May-23, the developer images have not been updated since early April. Is this approach depreciated? MitchellNCharity 18:13, 23 May 2007 (EDT)

No, it is *not* deprecated. For those who are not Linux developers the developer builds are much more likely to allow for starting to develop on day one. These images are intended to be download-and-start-coding tools for developers who prefer GUI environments for working. Mcfletch 24 May 2007

Might such developers be better off with running sugar-jhbuild on a virtual Ubuntu? MitchellNCharity 09:02, 23 June 2007 (EDT)

Option 4 - Sugar on Linux, with upgraded system libaries

Update your Linux operating system to such a point that it resembles the OLPC environment. You then need only use the more fragile build system for a tiny fraction of the packages required. You should be aware that such upgrades often will require you to update well beyond the "stable" configurations for your Linux distribution, and as such may make your system unstable.

As of 2007-04-08 only Fedora Core 6/7, Gentoo and Ubuntu Feisty Fawn are known to upgrade reasonably well.

As of 2007-05-23 it appears this approach is deprecated on Fedora Core, and doesn't work with x86_64. MitchellNCharity 16:54, 23 May 2007 (EDT)

Option 5 - A real XO laptop

Hardware Developer's Program - while there are only a small number of test units being produced, developers can submit proposals to receive one of those units for testing and development.

Operating Environment

Languages:

• Technically any language is usable
• Python is strongly encouraged, to have a single language "under the hood" when the curious child looks inside
• C/C should be used where Python performance is unacceptable, but try to keep it to a minimum, preferably as standard well-encapsulated and documented components
• Smalltalk-speaking developers may wish to work within the eToys environment
• Javascript can be used in web-based applications (Gecko or Opera engine Javascript implementation)

GUI Environments:

• PyGTK or the PyGTK-derived Sugar system should be used for most "Window, Icon, Mouse, Pointer" type GUIs. Note, however, as of 2007-04-21 that the Sugar "graphics" package is in Flux.
• Pygame SDL-based 2D game environment can be used for "Canvas" graphics using "Sprites".
• (Mozilla) XULRunner can be used to develop Gecko-based activities

Operating Stack:

• Hardware
• Fedora Core based Operating System
• Bitfrost Security System
• Sugar GUI Shell

Libraries/modules:

• Check to see what libraries are included before you begin development. Even some "universally available" libraries, such as OpenGL, are not available!
• Carefully choose support modules to minimize your storage footprint, for instance if you need a database, choose Sqlite rather than MySQL. Or better yet, use dbm.
• If you are unsure what is supported, ask.

Testing/working:

• Test your application in an official image (or a physical laptop) before publishing broadly
• To conserve memory or improve performance, consider replacing problematic areas in your Python code with C. For example, a rewrite of the hardware manager service in C saved 1.8 megabytes of private dirty memory. On a machine with only 256 megabytes of RAM and no swap space, efficient use of memory can make the difference between a usable system and a system made unreliable by out-of-memory failures.
• Distribute your source code under the GPL, LGPL or MIT license.

Joining or Starting a Project

Most developers will probably be working on an Activity for use on the OLPC. This kind of development can normally be done with little interaction with other development groups, save for the core Sugar developers (whose work directly affects activity developers).

Communications Channels

Most of the core developers use IRC for instant-messaging-style communications:

 irc.freenode.net #sugar

the Sugar mailing list is also used for broader comment and collaboration:

 List Information

If you have a large number of developers in a given area and would like to set up a local discussion list, post to the Sugar mailing list with a request for a new discussion list.

Current Active Local Discussion Lists:

• Argentina
• Brasil
• India
• Toronto (Canada)
• OLPC Nepal
• Developers OLPC Nepal

Requests and Ideas for Projects

Software ideas describes activity and tool types that are currently needed. If you have an idea for an activity, add it to the list in the appropriate category (create a new category if necessary). You can create a new wiki page to describe your idea in more detail.

Existing Projects

Software projects describes the currently active projects that may need help. Once you have decided on a project, add yourself to the list along with your contact information, homepage (which may be a wiki page on the OLPC wiki), etceteras. In particular, the various Activities available on the XO may need help as build time draws near; if you're looking for an existing project to get your feet wet with, check there.

Available Resources

The Developers Program provides general project management facilities for OLPC projects.

Documentation

Tutorials

• Original HelloWorld Tutorial using regular GTK
• Tuquito's Hello World! using GTK Glade rather than hand-coded GTK
• Red Hat Magazine
  • Introducing Sugar Article describing how to use sugar-jhbuild to set up a development environment
  • Anatomy of an Activity Basic Hello World style introduction to creating a new activity
  • Porting a PyGTK Game to the XO Very involved tutorial describing the Block Party game distributed with the XO.

References

These documents are frequently referenced during the development process.

• Sugar Architecture covers Sugar APIs and specifications
• Human interaction guidelines (HIG) for Sugar activities
• Bitfrost summary (full spec) the security system which will control activities and their interaction with the system and other users
• Sugar PyDoc just provides the raw API documentation, which is severely lacking in documentation strings (Good familiarisation project might be working with Marco to improve that situation)
• Hippo PyDoc again, just raw API documentation, needs lots of documentation effort
• Software components is a somewhat old document describing the various pieces of software and libraries involved in the system.
• Instructions on using the Sugar user interface
• Understanding sugar code provides an overview of how Sugar interacts with activities, including startup and shutdown, useful to understand the environment in which your activity will run
• Activity Bundles describes the packaging structure

Resources

• The Developer's Category collects everything in the wiki that's been tagged as pertaining to developers (it's a bit hard to navigate)
• Developers Program focuses on development for the core system, but with information useful for activity developers as well
• Sugar Code Snippets
• Getting involved in OLPC - general guide to where help is needed, though written a while ago, before direct development was particularly easy (thus the emphasis on working on upstream projects AFAICS)
• Game development HOWTO

Code worth reading:

• BlockParty for overall organization of an activity.
• HelloMesh, Connect or Write for tubes.

Frequently Asked Questions

How do I do networking in Sugar?

• Internal (to other laptops)
• External (to the wider internet)
• Activity Sharing (session establishment)
• Otherwise general Python networking
  • Twisted (will this be available on the images?)
  • Asyncore
  • PyRO (Python remote objects)
  • XMLRPC/SOAP

How do I create a persistent server/service?

• How do I register for start-time loading?
• Is there any dbus event service for loading only on response to messages? That is, not loading until there is an event of a given type, such as a presence event?
  • Yes, of a sort, services are defined in .service files, these match a named service to an executable which is to provide that service. Thus one can register to handle requests for a given named service, but you still need to arrange to have that service called by something.

How do I access the special hardware?

Camera

• Have to script v4l2 via gstreamer to capture a single frame from the camera. See sugar/shell/intro/glive.py for sample code
• Try this from the command line: gst-launch-0.10 v4l2src ! ffmpegcolorspace ! pngenc ! filesink location=foo.png
• See also: Programming the camera

Camera-as-video-camera (v4l2?)

• Is a regular v4l2 device available via gstreamer (gst module)
  • If you do not have hardware, you can simulate the camera interactively with an regular v4l2 source (many cheap web-cams provide this type of source)
  • For test-driven development, you can use any gstreamer source (such as a regular file), hooking up your code to use a file source instead of a v4l2src
• Try this from a terminal in the developer console: gst-launch-0.10 v4l2src ! ximagesink (The image will appear behind the developer console window so you'll need to move the window aside.)
• See also: Programming the camera

Directional pad/buttons

• Have their own X key names
• Currently 4-button set mapped to arrow (cursor) keys
• Two separate buttons mapped to ??? (pageup/pagedown)

Drawing pad (stylus pad)

• How to switch in/out of stylus mode?
• How to set interpretation parameters?

Audio-port probe

• How to get access?
  • What's going to come out when I get access (keeping in mind I (the developer) likely won't have the actual hardware available)

Mode-switching code for the screen

• backlight on/off
• backlight brightness
• set all 8 (4 distinct) settings for MODE_MONO_LUMA, MODE_CSWIZZLE, MODE_COL_AA
• query, change, and restrict screen orientation
• drop to a lower resolution for performance or ease of porting, such as 600x450 or 400x300

See also Display.

How do I create my activity GUI?

• Can I just use Cairo, Pygame or GTK directly?
  • Sugar's own GUI interface is coded in a GTK derived library (Hippo), using an internal "sugar.graphics" package. This package is currently in flux and you should not likely start new projects using it until the API stabilises. In the meantime please use GTK or PyGame (SDL) for you project's GUI.
• How can a non-GTK (or Qt) app fully interact with Sugar?
  • At the moment it cannot do this easily.
  • Sugar is using custom dbus messages to communicate with a server that must be present for every activity. That restriction may be relaxed in the future.
    • Can be easily "fixed" by creating a wrapper in Python (e.g. the ClassicGnome activity)
    • Can write various DBUS services using a GTK event loop to provide the required introspection services (implies that GTK must be loaded by every process, regardless of whether it is needed)
    • Can alter your core event loop to cooperate with an embedded GObject event loop (PyGame allows this, for instance), with the small concern that this requires loading GObject into your process' memory space
• How flexible does the GUI need to be?
  • Should be able to handle a resize-and-rotate event from the X server
  • Should be able to handle internationalisation/localisation, including to right-to-left-written scripts
• What's the best development approach:
  • Write outside Sugar, finish and debug, then port?
    • For older PowerPC-based Macs, this is likely the best approach
  • Write to Sugar, test and debug within the system?
    • Usable if you can set up a reasonably-performing emulated system or upgrade your system to support Sugar directly
• How does HippoCanvas work?

How do I package my activity?

• How do I work from an in-process activity (develop registration)?
  • setup.py develop
  • You can use sugar-activity to start the activity, but you have to manually close it (using the Sugar GUI: show the frame, then move to the activity icon on the top bar, hover for a second, then click close (yes, it's really that awkward))
• How do I produce a binary extension?
• How do I make my package available for users to download dynamically?
• How do I tell users about updates to the packages?
• How do I share code between activities?
  • How do I use (large, common) Python packages?
    • Numpy
    • Matplotlib
    • MySQL or PostgreSQL client code
    • Twisted
    • Zope Interfaces
    • Pygsear or other PyGame extensions
  • How do I provide my own base packages on top of which I have written dozens of applications?

How do I test a Sugar activity?

• Start sugar, start a bash shell, run "sugar-jhbuild shell" to set up the sugar environment variables, then use "sugar-activity YourActivityName" to run the activity with output going to your local shell

How do I debug a Sugar activity?

If you start your Sugar activity from the command line, you can insert a standard Python:

 import pdb
 pdb.set_trace() 

command into your activity and then use the Python debugger to step through your activity's behaviour. Note that this will "freeze" your application while you are working, so you may have display issues.

How do I edit with emacs on the laptop?

• Install MicroEMACS by copying this file to the laptop. Actually, zile works more as I expected, try installing this rpm file instead.

How do I mount a USB drive?

• Enter the linux shell mode
• First become root: $ su
• Then make a place to mount it: $ mkdir /mnt/usb
• Then mount the drive: $ mount /dev/sda1 /mnt/usb
• Don't forget to unmount it before removal: $ umount /mnt/usb
• If anything fails you should edit your /etc/fstab file to include the mount point, device, and filesystem for the device to mount.