Getting started programming

english | 日本語 | 한국어

HowTo [ID# 69291]  +/-

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. Getting started is not yet as easy as we would like it to be (OLPC growing pains) - helping with that is one of many ways you might contribute.

Setting up a Development Environment

The OLPC's software environment is a heavily modified Fedora 7 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 - Emulated XO

An emulated XO laptop is the recommended platform both for "checking out" the Sugar environment and for developing new activities. By installing an emulation package on your (reasonably powerful) host desktop, you can run an emulated version of the Sugar environment which is essentially the same code as runs on the real laptops.

An emulated XO does not provide tools such as SVG editors or Integrated Development Environments. You will normally run such software on your host machine and push the results onto the emulated machine.

The emulated XO has certain limitations with regard to the specialized hardware in the XO. See the Developer's FAQ below for some pointers on how to simulate the special hardware.

Option 2 - sugar-jhbuild

Compared with using an Emulated XO, installing sugar takes more time and space to set up, and can be difficult to maintain, but results in a more flexible better environment. This is what the core development team uses. If you are intending to work on the core system you will likely need to use sugar-jhbuild to set up your environment.

On 32-bit Linux

sugar-jhbuild no longer supports building "base" libraries, so to get a working Sugar using jhbuild you will need to be running an OS that provides compatible versions of the various libraries that Sugar requires.

As of 2007-08-17 the only two distributions known to be able to support sugar-jhbuild are Fedora 7 and Ubuntu Feisty Fawn (or Greater). It seems likely that Gentoo could be made to work with some effort, but no successful build there has been reported in a number of months.

It is also possible to run one of these "just works" distributions in emulation under another operating system (Windows/Mac/Linux) using any of a number of emulators (Parallels, Qemu, VMWare).

At the moment, a Fedora 7 install with sugar-jhbuild is probably the most "sure" bet for getting a working full-speed (non-emulated) working environment for developing on Sugar with the latest libraries and solid upgrade path. As most of the core developers are working on Fedora boxes with sugar-jhbuild it is the most likely environment to be supported and continue to receive support.

On 64-bit Linux (not working)

As of 2007-08-17 it is not possible to build Sugar on 64-bit Linux. This appears to just be minor configuration issues in the build process.

Option 3 - 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.

Option 3.5 - Shared Laptop(s)

If you happen to be in Toronto, Canada, a BTest-2 laptop is available at the Linux Caffe for developers to use for testing their software. You can request access at the Caffe (you will be asked to give your name so we can track who is using the machine).

You'll probably want to use an emulator to develop your software and then use the shared hardware for testing. You'll want a USB key to flash the machine with the latest image.

[Update] Due to an unfortunately accident, the screen on the BTest-2 at Linux Caffe has been broken. We're working out what to do about that.

Operating Environment

Official description of the Software components on the laptop (XXX maybe merge this into that page, we want links to further information about each library, though?)

Development 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
• EToys

Operating Stack:

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

Libraries/modules/services of note:

• D-BUS -- efficient Desktop-level RPC engine, most specialized laptop hardware and operations are exposed over DBus
• Telepathy (Glib, Salut, Gabble) -- collaboration/communications engine with "Tubes" (cross-machine RPC over DBus) and various network traversal and discovery logic, activities are encouraged to use Tubes where ever practical
• CSound -- acoustically modelled sound-synthesis engine (seen in the TamTam activity)
• Abiword -- collaborative text editor/word processor usable as a GTK widget that can be embedded in other activities
• SQLite -- lightweight relational database
• XULRunner (with Python DOM-capable bindings) -- Gecko 1.9 (Firefox 3.x) engine
• GStreamer -- general purpose media streaming platform, used for accessing the video camera and playing media
• Avahi -- discovery and advertising mechanism for mesh-hosted services

Common libraries not available:

• OpenGL
• Server-based relational databases (MySQL, PostgreSQL)
• If you are unsure whether something is supported, ask, or load up an emulated machine and check for the presence of the library

Testing/working:

• Announce your project on the OLPC devel list so that people know what you are working on and duplication of effort is reduced
• Add your project to the Software projects page
• 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.
• When ready to test with real users add your activity to the Activities page to allow for easy download and installation

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

Unofficial news and interesting tidbits often show up in the blog aggregator for the project.

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

See the Tutorials page for introductory tutorials.

References

See the API Reference for pointers to the various library's reference documentation.

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?

Recommended pattern for networking applications on the OLPC laptops is to use the Tubes/Telepathy system. This is basically DBUS remote procedure calls over telepathy networking. The Telepathy framework allows for session establishment and routing across strange network topologies. See Activity Sharing

• Can I wrap Tubes with a socket compatibility layer to get the NAT traversal features and the like, but use old socket-based code? (yes with caveats)

The laptops will have IPv6 and IPv4 connectivity, they can use "normal" internet networking primitives as available in Python, Scheme and C.

• Standard Python supports synchronous and asynchronous networking including basic web-servers and the like.
• Twisted will not be available by default on the laptops but partial installs of the framework could be included in your activities if you want to do lots of multi-protocol networking operations
• PyRO (Python remote objects) is another common Python networking RPC approach.
• XMLRPC/SOAP can be used to produce web services

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
• You can simulate this hardware via a file source in gstreamer

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. In addition, it will have strange colors, since you are displaying the YCrCb colorspace as though it is RGB data. Use gst-launch-0.10 v4l2src ! ffmpegcolorspace ! ximagesink to run slowly and get the right colors.)
• See also: Programming the camera
• You can simulate this hardware via a file source in gstreamer

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)
• Specially named keys in the PyGame port

Touchpad / Glide Sensor

• Shows up as a normal mouse under X.
• This is not a multi-touch capable glide sensor.

Drawing pad (stylus pad)

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

Audio-port probe

Best sample code currently available is in the Measure Activity.

• How to get access?
  • You configure the ALSA mixer (using os.system in the example code) and then use gstreamer events to process a the incoming audio-buffer "handoff" using a fake data sink. You unpack the data from the string values and get integer values. (Or just use the utility class (AudioGrab) in the Measure Activity).

• What's going to come out when I get access (keeping in mind I (the developer) likely won't have the actual hardware available)?
  • You are processing a stream of audio data. In the sample code you are configuring gstreamer to produce a stream of integers at 48000 Hz. You should be able to produce the same effect using gstreamer on any linux box using your normal microphone port.

Mode-switching code for the screen

Much of this is controlled via the HardwareManager service on DBUS. There is sample code for getting a reference to the hardware manager in the Read Activity, from there, simply call the dbus-exposed methods to set the values you want. HardwareManager controlled operations:

• Display Controller (DCON) data-source (CPU or DCON)
• DCON freeze/unfreeze
• backlight brightness
• keyboard light brightness
• color/black and white mode

How do we:

• set all 8 (4 distinct) settings for MODE_MONO_LUMA, MODE_CSWIZZLE, MODE_COL_AA (as distinct from just colour/black and white)
• 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 (note that by default there is no way to easily kill a mis-behaving activity in Sugar)
• 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?
    • The system will "unify" common files across packages, so if you have a large package and another activity also uses that package then the system will only store one copy of the package (using a file-by-file comparison).
    • 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?
    • As with the common activities, the current plan is to have the system unify the packages on the laptop. There is a cost in that the packages must contain complete copies of their supporting framework for each activity.

How do I share files between applications?

Plan at the moment is to have file-sharing handled by the underlying system. That is, the system will simply notice that you have duplicate files with the same properties and hash and will share them between the two activities.

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.
• Zile may be closer to what you expect from Emacs install this RPM this rpm file to get it.

How do I mount a USB drive?

Normally this is done automatically by the HAL when you plug the USB key into the laptop. It will show up as a directory in the /media folder. If, however, you had the USB key in when you started the machine, or the HAL doesn't recognize the key, you may not get the mount completed. In that case you can try manually mounting the key:

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