API reference

From OLPC
Revision as of 15:07, 15 December 2007 by Mcfletch (talk | contribs) (→‎Building PyDoc Documentation: Simpler and smaller for users on laptops)
Jump to navigation Jump to search

This page describes the components of the XO software environment. For the low-level API available to non-Python activities, see the Low-level Activity API page.

The OLPC platform includes a large number of libraries and services. This page attempts to gather links to reference works which can be used when programming the XO laptops. This reference is primarily intended for Software Developers. You may want to try out a few Tutorials before diving into these documents.

Platform Overview

  • Software components is a somewhat old document describing the various pieces of software and libraries involved in the system.

Python Libraries

Where official reference documentation isn't available, PyDoc-generated documentation is provided. See below for instructions on how to produce the PyDoc documentation in your own running image.

GUI Libraries

Libraries for creating standard Windows-Icon-Menu-Pointer (WIMP) GUI applications.

High-Level Widgets

GUI (GTK) controls which expose the functionality of entire complex applications for use by other projects.

  • Abiword -- GTK widget embedding the Abiword Word-Processor
  • HulaHop -- embeds a Gecko 1.9 (Firefox 3.0 ocore) rendering widget XXX confirm that's what it really is
  • Evince -- PDF (and similar) document viewer as a GTK widget

Multimedia Libraries

Libraries that deal with multimedia and gaming functionality.

  • GStreamer (PyDoc) -- multimedia streaming library
  • CSound -- the CSound audio-generation library
  • OLPC Games -- PyGame wrapper that makes working within the OLPC-XO environment relatively straightforward (Strongly recommended for PyGame usage on the XO!)
  • PyGame -- GUI library suitable for Sprite-based 2D game development

Communications and Networking

Libraries for connecting to other processes, either on the local machine or across the network

  • D-BUS (PyDoc) -- desktop messaging (Remote Procedure Call (RPC) and Asynchronous Signalling) engine
  • Telepathy -- buddy and connection management including cross-machine RPC over D-BUS
  • PyXPCOM -- Library for controlling XPCOM applications (currently just XULRunner on the XO) XXX Should be available, but doesn't appear to be (that is, import xpcom doesn't work)

Support Libraries

Libraries which are neither GUI nor multi-media (necessarily)

  • Python Standard Modules -- modules which come with the Python language
  • SECore -- search engine implementation
  • JSON -- Javascript Object Notation parser/linearisation library
  • UrlGrabber -- url downloading library
  • OLPC -- the data-store implementation
  • Unicode -- the laptop must provide internationalized software, as a result you will need to use Python's Unicode support

Extraneous Libraries

Libraries which are present in the current builds, but not particularly "part" of the Sugar environment and which may be removed eventually.

  • Yum -- package manager for RPM-based distributions
  • RPM -- RPM manipulation library

Building PyDoc Documentation

If you just want access to the PyDoc documentation yourself, you do not need to build the documentation. You can simply start a Terminal window and run the pydoc script like so:

pydoc -p 8080

Then start a Web Browser activity and go to the URL:

http://localhost:8080

to browse all of the Python packages which are available by default on your machine.

If you really do want to create documentation for uploading to a web-site or the like, you can do the following...

In a new emulator image (you likely don't want to do this on a real OLPC as it will fill up your flash ram). Start a developer's console, then do the following:

Change to the root account (to allow for installing software with yum):

su 
yum install bzr
exit

that will download and install the bzr and python-crypto packages (about 4.8 MB) after asking you to verify that you want to do it (it will also download the yum updates, which should be small if you are using a recent emulator image).

Now, as your regular user (olpc), in the same developer's console, download the script to produce the PyDoc documentation:

bzr branch  http://www.vrplumber.com/bzr/autodoc
cd autodoc
./builddocs.py

the documentation-building process will run for a short while and produce a very large number of reasonably large HTML files in the autodoc folder.

Smalltalk Libraries

D-BUS Services

  • Avahi -- local service discovery, e.g. for finding particular services provided on the mesh network
  • NetworkManager -- network management service
  • Hardware Abstraction Layer Daemon (hald) -- control of standard hardware functionality
  • Presence Service -- friend discovery and collaboration primitives, including a description of the Telepathy API
    • Telepathy Connection Manager
    • Telepathy StreamEngine
  • Activity DBus API -- Describes the API an activity must implement on D-BUS in order to interact with the Sugar desktop
    • Activity Service (Python implementation of the Activity DBus API)
  • Data Store Service (Journal) -- the core data-storage operation of the laptop
  • Clipboard Service -- manages cross-activity sharing of data and files
  • Hardware Manager Service -- provides access to the OLPC-specific hardware on the laptop
  • Activity Registry Service -- registry of installed activity bundles on the laptop
  • Object Type Registry Service -- MIME-type registry service
  • Sugar Console Service

System Services/Hardware

  • Open Firmware/Forth -- bios-replacement system on the laptop
  • Hardware specification -- general description of the hardware on the laptops
    • DCON -- the display controller ASIC and its interface (note that normally you would use the HardwareManager D-BUS interface to manipulate the DCON)
    • Geode -- the Geode CPU (assembly-language optimization guide, links to data-sheets)
    • Power Domains -- description of which parts of the hardware are kept live in what situations
  • Kernel
    • Rebuilding OLPC kernel -- describes how to rebuild the OLPC kernel, which is sometimes necessary if you need to support otherwise unsupported hardware