API reference: Difference between revisions

From OLPC
Jump to navigation Jump to search
(remove spam)
 
(73 intermediate revisions by 12 users not shown)
Line 1: Line 1:
{{Developers}}
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 [[Developers|Software Developers]].
<< [[Developers/Documentation]]


''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.''
== Platform Requirements ==


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 [[Developers|Software Developers]]. You may want to try out a few [[Tutorials]] before diving into these documents.

= API Changes =

* Documented [[API changes]] between OLPC XO sofware releases

= Platform =

* [[Sugar Architecture]]
* [[HIG|Human interaction guidelines (HIG)]] for Sugar activities
* [[HIG|Human interaction guidelines (HIG)]] for Sugar activities
* [[Activity Bundles]] describes the packaging structure
* [[Activity Bundles]] describes the packaging structure
Line 10: Line 20:
* [[Software components]] is a somewhat old document describing the various pieces of software and libraries involved in the system.
* [[Software components]] is a somewhat old document describing the various pieces of software and libraries involved in the system.


== Python Libraries ==
== Sugar Specs ==


Documentation describing how to integrate into the [[Sugar]] GUI shell:
Where official reference documentation isn't available, PyDoc-generated documentation is provided. You can generate local copies of the PyDoc-generated documentation from a running official image. Script is available via <tt>bzr branch http://www.vrplumber.com/bzr/autodoc</tt>


* [[Sugar almanac]] -- API reference
=== GUI Libraries ===
* [[Bundles]] -- general reference for OLPC bundles (including content)
** [[Activity bundles]] -- references to Sugar's Activity (code) bundle (.xo) file format/project structure
** [[Activity mimetypes]] -- how to specify that your activity handles a given MIME-type
* [[Low-level Activity API]] -- reference to the messages your activity should send/receive for Sugar integration

= Python Libraries =

Where official reference documentation isn't available, PyDoc-generated documentation is provided:

* See [http://api.sugarlabs.org/ api.sugarlabs.org] for an online version for Sugar, generated off the latest code, or
* See [[API reference#Building PyDoc Documentation|below]] for instructions on how to produce the PyDoc documentation in your own running image, for every Python package - not only Sugar.

== GUI Libraries ==


Libraries for creating standard Windows-Icon-Menu-Pointer (WIMP) GUI applications.
Libraries for creating standard Windows-Icon-Menu-Pointer (WIMP) GUI applications.
Line 20: Line 43:
* [[Sugar Architecture]] [http://www.vrplumber.com/sugar-docs/sugar.html (PyDoc)] -- core UI and service libraries
* [[Sugar Architecture]] [http://www.vrplumber.com/sugar-docs/sugar.html (PyDoc)] -- core UI and service libraries
** [http://www.vrplumber.com/sugar-docs/sugar.activity.html Activity Support] -- support mechanisms for writing activities
** [http://www.vrplumber.com/sugar-docs/sugar.activity.html Activity Support] -- support mechanisms for writing activities
** [[Graphics API]] [http://www.vrplumber.com/sugar-docs/sugar.graphics.html (PyDoc)] -- UI library based on Hippo Canvas
** [http://www.vrplumber.com/sugar-docs/sugar.presence.html Presence] [http://www.vrplumber.com/sugar-docs/sugar.chat.html Chat] [http://www.vrplumber.com/sugar-docs/sugar.p2p.html P2P]-- activity's interfaces to the Telepathy engine
** [http://www.vrplumber.com/sugar-docs/sugar.chat.html Clipboard] -- activity's interface to the UI's clipboard interface
** [http://www.vrplumber.com/sugar-docs/sugar.datastore.datastore.html Datastore] -- activity's interface to the datastore service
** [http://www.vrplumber.com/sugar-docs/sugar.datastore.datastore.html Datastore] -- activity's interface to the datastore service
*** [http://dev.laptop.org/git?p=web-activity;a=blob;f=downloadmanager.py;hb=HEAD Example] -- usage of the datastore API in the [[Web]] activity's download manager
** [[Sugar Code Snippets|Code Snippets]] -- short fragments of code describing the canonical way to achieve various effects
** [[Sugar Code Snippets|Code Snippets]] -- short fragments of code describing the canonical way to achieve various effects
* [http://www.pygtk.org/reference.html Gtk], [http://www.vrplumber.com/sugar-docs/gtk.html (PyDoc)] -- GUI library underlying the Sugar UI
** [http://www.vrplumber.com/sugar-docs/sugar.chat.html Chat] -- not widely used
** [http://www.pygtk.org/docs/pygtk/atk-class-reference.html Accessibility Toolkit (ATK)] [http://www.vrplumber.com/sugar-docs/atk.html (PyDoc)] -- tools for providing accessible interfaces
** [http://www.vrplumber.com/sugar-docs/sugar.p2p.html P2P]-- activity's interfaces to the Telepathy engine
** [[Graphics API]] [http://www.vrplumber.com/sugar-docs/sugar.graphics.html (PyDoc)] -- UI library based on Hippo Canvas
*** Note: this API is largely deprecated, please use standard GTK operations
** [http://www.vrplumber.com/sugar-docs/hippo.html Hippo Canvas] -- canvas mechanism used by the Sugar.graphics libraries
*** Note: this API is largely deprecated, please use standard GTK operations
** [http://www.vrplumber.com/sugar-docs/sugar.clipboard.clipboardservice.html Clipboard] -- activity's interface to the UI's clipboard interface
*** Note: this API is '''not''' necessary for most activities, the standard GTK clipboard can be used instead
* [http://www.pygtk.org/reference.html Gtk], [http://www.vrplumber.com/sugar-docs/gtk.html (PyDoc)] -- GUI library underlying the Sugar UI ([http://library.gnome.org/devel/gtk/unstable/index.html C API])
** [http://www.pygtk.org/docs/pygtk/atk-class-reference.html Accessibility Toolkit (ATK)] [http://www.vrplumber.com/sugar-docs/atk.html (PyDoc)] -- tools for providing accessible interfaces ([http://library.gnome.org/devel/atk/unstable/index.html C API)
** [http://www.pygtk.org/docs/pygobject/index.html GObject] [http://www.vrplumber.com/sugar-docs/gobject.html (PyDoc)] -- non-GUI core library
** [http://www.pygtk.org/docs/pygobject/index.html GObject] [http://www.vrplumber.com/sugar-docs/gobject.html (PyDoc)] -- non-GUI core library
** [http://www.pygtk.org/docs/pygtk/pango-class-reference.html Pango] [http://www.vrplumber.com/sugar-docs/pango.html (PyDoc)] -- text layout and rendering engine
** [http://www.pygtk.org/docs/pygtk/pango-class-reference.html Pango] [http://www.vrplumber.com/sugar-docs/pango.html (PyDoc)] -- text layout and rendering engine
*** [http://dev.laptop.org/git?p=projects/games-misc;a=blob;f=olpcgames-src/olpcgames/pangofont.py;hb=HEAD Example] -- example of using Pango to render into a GTK buffer (and from there a Pygame surface)
* [http://www.vrplumber.com/sugar-docs/hippo.html Hippo Canvas] -- canvas mechanism used by the Sugar.graphics libraries
* [http://cairographics.org/pycairo/ Cairo] [http://www.vrplumber.com/sugar-docs/cairo.html (PyDoc)] -- Low-level vector graphics rendering library
* [http://cairographics.org/pycairo/ Cairo] [http://www.vrplumber.com/sugar-docs/cairo.html (PyDoc)] -- Low-level vector graphics rendering library
* [http://www.vrplumber.com/sugar-docs/rsvg.html RSVG] -- Library for rendering SVG text from files/strings onto Cairo Canvases
** [http://dev.laptop.org/git?p=projects/block-party-activity;a=blob;f=BlockParty.py;hb=HEAD Example] -- rendering of a game via Cairo
** [http://www.vrplumber.com/sugar-docs/rsvg.html RSVG] -- Library for rendering SVG text from files/strings onto Cairo Canvases
*** [http://dev.laptop.org/git?p=projects/games-misc;a=blob;f=olpcgames-src/olpcgames/svgsprite.py;hb=HEAD Example] -- renders an SVG file to a pygame sprite
*** [http://dev.laptop.org/git?p=projects/calculate;a=blob;f=svgimage.py;hb=HEAD Example] -- rendering an SVG image to a GTK surface


=== High-Level Widgets ===
== High-Level Widgets ==


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


* [http://www.vrplumber.com/sugar-docs/abiword.html Abiword] -- GTK widget embedding the Abiword Word-Processor
* [http://www.abisource.com/doxygen/classes.html Abiword] ([http://www.vrplumber.com/sugar-docs/abiword.html PyDoc]) -- GTK widget embedding the Abiword Word-Processor
** [http://dev.laptop.org/git?p=projects/write;a=blob;f=AbiWordActivity.py;hb=HEAD Example] the [[Write]] activity
* [http://www.vrplumber.com/sugar-docs/hulahop.html HulaHop] -- embeds a Gecko 1.9 (Firefox 3.0 ocore) rendering widget XXX confirm that's what it really is
* [http://www.vrplumber.com/sugar-docs/hulahop.html HulaHop] -- embeds a [http://www.mozilla.org/newlayout/ Gecko] 1.9 (Firefox 3.0 core) rendering widget
** [http://dev.laptop.org/git?p=web-activity;a=blob;f=browser.py;hb=HEAD Example] -- the browser module from the [[Web]] activity
* [http://www.vrplumber.com/sugar-docs/evince.html Evince] -- PDF (and similar) document viewer as a GTK widget
* [http://www.vrplumber.com/sugar-docs/evince.html Evince] -- PDF (and similar) document viewer as a GTK widget
** [http://dev.laptop.org/git?p=projects/read-activity;a=blob;f=readactivity.py;hb=HEAD Example] -- the [[Read]] activity
* VteTerminal ([http://library.gnome.org/devel/vte/unstable/VteTerminal.html C API]) -- terminal widget
** [http://dev.laptop.org/git?p=projects/terminal-activity;a=blob;f=terminal.py;hb=HEAD Example] -- the [[Terminal]] activity
** [http://earobinson.wordpress.com/2007/09/10/python-vteterminal-example/ blog entry describing the widget]
* [http://www.pygtk.org/pygtksourceview/index.html GtkSourceView] ([http://gtksourceview.sourceforge.net/docs/index.html C API]) -- control provide source-code editing with syntax highlighting
** [http://dev.laptop.org/git?p=projects/pippy-activity;a=blob;f=pippy_app.py;hb=HEAD Example] -- the [[Pippy]] activity
** [http://gtksourceview.sourceforge.net/ GtkSourceView home page]


=== Multimedia Libraries ===
== Multimedia Libraries ==


Libraries that deal with multimedia and gaming functionality.
Libraries that deal with multimedia and gaming functionality.


* [http://pygstdocs.berlios.de/ GStreamer] [http://www.vrplumber.com/sugar-docs/gst.html (PyDoc)] -- multimedia streaming library
* [http://pygstdocs.berlios.de/ GStreamer] [http://www.vrplumber.com/sugar-docs/gst.html (PyDoc)] -- multimedia streaming library
** [https://penguintv.svn.sourceforge.net/svnroot/penguintv/trunk/penguintv/GStreamerPlayer.py Example] -- PenguinTV's gstreamer-based audio-visual control
** [http://dev.laptop.org/git?p=sugar;a=tree;h=c0d9a4abde7de3530ba70eaed230d28ccaaf59e0;hb=HEAD Example] -- Sugar's initial training/introduction video
* [http://www.vrplumber.com/sugar-docs/csnd.html CSound] -- the CSound audio-generation library
* [http://www.vrplumber.com/sugar-docs/csnd.html CSound] -- the CSound audio-generation library
** [http://blog.vrplumber.com/1876 Example] -- using CSound to create an audio system-load monitor application
* [http://www.vrplumber.com/sugar-docs/olpcgames.html OLPC Games] -- PyGame wrapper that makes working within the OLPC-XO environment relatively straightforward (Strongly recommended for PyGame usage on the XO!)
** [http://dev.laptop.org/git?p=projects/pippy-activity;a=blob;f=library/pippy/sound.py;hb=HEAD Pippy's Sound Module] -- play .wav and .csd files via CSound
* [http://www.pygame.org/docs/ PyGame] -- GUI library suitable for Sprite-based 2D game development
* [[OLPCGames]] ([http://www.vrplumber.com/sugar-docs/olpcgames.html PyDoc]) -- PyGame wrapper that makes working within the OLPC-XO environment relatively straightforward (Strongly recommended for PyGame usage on the XO!)
** [[Game development HOWTO]] -- tutorial with multiple samples (e.g. camera, video overlay, multi-channel sound, csound)
* [http://www.pygame.org/docs/ PyGame] -- GUI library suitable for Sprite-based 2D game development (usable from Pippy or OLPCGames)


=== Communications and Networking ===
== Communications and Networking ==


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


* [http://dbus.freedesktop.org/doc/dbus-python/ D-BUS] [http://www.vrplumber.com/sugar-docs/dbus.html (PyDoc)] -- desktop messaging (Remote Procedure Call (RPC) and Asynchronous Signalling) engine
* [http://www.vrplumber.com/sugar-docs/sugar.presence.html Sugar Presence] API to interact with [[Presence Service]] which in turn uses Telepathy
** [[Activity sharing]] -- includes some minimalist code on how to use Presence Service in your activities
* [http://www.vrplumber.com/sugar-docs/telepathy.html Telepathy] -- buddy and connection management including cross-machine RPC over D-BUS
** [http://dev.laptop.org/git?p=projects/hellomesh;a=summary Example] -- [[HelloMesh]] example activity using D-Bus Tubes, documented in [[Collaboration Tutorial]]
** [[Shared Sugar Activities]] -- includes some minimalist code on how to use Telepathy in your activities
** [http://dev.laptop.org/git?p=web-activity;a=blob;f=webactivity.py;hb=HEAD Example] -- example of using the Presence service in the [[Web]] activity
** [http://dev.laptop.org/git?p=projects/sharedstate;a=tree;f=sharedstate;hb=HEAD SharedState] -- project to create a shared-object model over telepathy (used by [[Calculate]])
** [http://dev.laptop.org/git?p=chat-activity;a=blob;f=pippy_app.py;hb=HEAD Example] -- the [[Chat]] activity uses Telepathy text channels
** [http://dev.laptop.org/git?p=projects/connect-activity;a=blob;f=activity.py;hb=HEAD Example] -- the [[Connect]] activity uses DBUS Tube connections
** [http://dev.laptop.org/git?p=projects/read-activity;a=blob;f=readactivity.py;hb=HEAD Example] -- the [[Read]] activity opens an HTTP server running on a StreamTube to share files
** [http://dev.laptop.org/git?p=projects/productive;a=blob;f=Productive.activity/productive/networkserver.py;hb=HEAD Example] -- [[Games/Productive]] uses an ExportedGObject shared over the same tube as [[OLPCGames]].mesh
** [http://penguintv.svn.sourceforge.net/viewvc/penguintv/trunk/NewsReaderLite.py?view=markup Example] [http://penguintv.svn.sourceforge.net/viewvc/penguintv/trunk/penguintv/NRLTube.py?view=markup Example] -- the [[NewsReader]] activity shares the current feed with joined members via an ExportedGObject (second link)
** [http://dev.laptop.org/git?p=web-activity;a=blob;f=webactivity.py;hb=HEAD Example] -- the [[Web]] Browser activity shares the current URL
** [http://dev.laptop.org/git?p=projects/write;a=blob;f=AbiWordActivity.py;hb=HEAD Example] -- the [[Write]] activity shares an instance of its core control's AbiCollab interface across a Tube
** [http://dev.laptop.org/git?p=projects/games-misc;a=blob;f=olpcgames-src/olpcgames/mesh.py;hb=HEAD Example] -- the OLPCGames mesh wrapper provides an example of how to use raw Tubes in a (Pygame) application, the complication being that it has to package incoming events as Pygame events.
*** [http://dev.laptop.org/git?p=projects/productive;a=blob;f=Productive.activity/productive/graphics/ui.py;hb=HEAD Example] -- use of [[OLPCGames]].mesh to create a "Game Lobby" interface for configuring a game to be played
** [http://darcs.collabora.co.uk/darcs/telepathy/telepathy-python/examples/ Examples] -- the Telepathy-python example code (non-OLPC-specific)
* 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)
* 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 ===
== Support Libraries ==


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


* [http://www.vrplumber.com/sugar-docs/secore.html SECore] -- search engine implementation
* [http://docs.python.org/lib/modindex.html Python Standard Modules] -- modules which come with the Python language
* [http://www.xapian.org/docs/bindings/python/ Xapian] -- Full-Text Search library
** [http://dev.laptop.org/git?p=projects/datastore;a=tree;f=src/olpc/datastore;hb=HEAD Example] -- the datastore uses Xapian for full-text searches
** [http://www.vrplumber.com/sugar-docs/secore.html SECore] -- search engine implementation
* [http://www.vrplumber.com/sugar-docs/json.html JSON] -- Javascript Object Notation parser/linearisation library
* [http://www.vrplumber.com/sugar-docs/json.html JSON] -- Javascript Object Notation parser/linearisation library
** [http://dev.laptop.org/git?p=web-activity;a=blob;f=model.py;hb=HEAD Example] -- [[Web]] activity that uses JSON for some internal storage
* [http://www.vrplumber.com/sugar-docs/urlgrabber.html UrlGrabber] -- url downloading library
* [http://www.vrplumber.com/sugar-docs/urlgrabber.html UrlGrabber] -- url downloading library
* [http://www.vrplumber.com/sugar-docs/olpc.html OLPC] -- the data-store implementation
* [http://www.vrplumber.com/sugar-docs/olpc.html OLPC] -- the data-store implementation
* [[Python Unicode|Unicode]] -- the laptop must provide internationalized software, as a result you will need to use Python's Unicode support
* [[Python Unicode|Unicode]] -- the laptop must provide internationalized software, as a result you will need to use Python's Unicode support


=== Extraneous Libraries ===
== Extraneous Libraries ==


Libraries which are present in the current builds, but not particularly "part" of the Sugar environment and which may be removed eventually.
Libraries which are present in the current builds, but not particularly "part" of the Sugar environment and which may be removed eventually.
Line 76: Line 138:
* [http://www.vrplumber.com/sugar-docs/rpm.html RPM] -- RPM manipulation library
* [http://www.vrplumber.com/sugar-docs/rpm.html RPM] -- RPM manipulation library


== Building PyDoc Documentation ==
== Smalltalk Libraries ==


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:
* [[EToys]]


pydoc -p 8080
== C Libraries ==


Then start a Web Browser activity and go to the URL:
== D-BUS Services ==


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.

== Building epydoc Documentation ==

Another option is building full-system documentation like that at http://dev.laptop.org/~cscott/joyride-api/

The [http://epydoc.sourceforge.net/ epydoc] documentation configuration can be found at http://dev.laptop.org/~cscott/joyride-2083-api/epydoc.py and http://dev.laptop.org/~cscott/joyride-2083-api/epydoc.config

= Smalltalk Libraries =

* [[Etoys]]

= D-BUS Services =

* [http://dbus.freedesktop.org/doc/dbus-python/ D-BUS] [http://www.vrplumber.com/sugar-docs/dbus.html (PyDoc)] -- desktop messaging (Remote Procedure Call (RPC) and Asynchronous Signalling) engine
* [[Presence Service]] -- buddy discovery and activity collaboration layer on top of Telepathy
* [[Telepathy]] [http://telepathy.freedesktop.org/spec.html Spec] [http://www.vrplumber.com/sugar-docs/telepathy.html (PyDoc)] -- buddy and connection management including cross-machine RPC over D-BUS
** Telepathy Connection Manager
** Telepathy StreamEngine
* [http://avahi.org/wiki/ProgrammingDocs Avahi] -- local service discovery, e.g. for finding particular services provided on the mesh network
* [http://avahi.org/wiki/ProgrammingDocs Avahi] -- local service discovery, e.g. for finding particular services provided on the mesh network
* [http://cvs.gnome.org/viewcvs/NetworkManager/docs/NetworkManager%20DBUS%20API.txt?rev=HEAD NetworkManager] -- network management service
* [http://cvs.gnome.org/viewcvs/NetworkManager/docs/NetworkManager%20DBUS%20API.txt?rev=HEAD NetworkManager] -- network management service
* [http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces Hardware Abstraction Layer Daemon (hald)] -- control of standard hardware functionality
* [http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces Hardware Abstraction Layer Daemon (hald)] -- control of standard hardware functionality
* [[Activity DBus API]] -- Describes the API an activity must implement on D-BUS in order to interact with the [[Sugar]] desktop
* [[Presence Service DBus API|Presence Service]] -- friend and shared-activity discovery service
** 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
* [http://dev.laptop.org/git.do?p=hardware-manager;a=blob;f=hardwaremanager.py;h=3154b17553621cc41fa947cbff2756372e6e37ec;hb=HEAD 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 ==
= System Services/Hardware =


* [[Forth Lessons]] -- Series of tutorial-style lessons on the Forth language and the [[Open Firmware]] bios-replacement system on the laptop
* [[Open Firmware]]/Forth -- bios-replacement system on the laptop
** [[Forth Lessons]] -- Series of tutorial-style lessons on the Forth language and Open Firmware in particular
** [http://firmworks.com/QuickRef.html Open Firmware Quick Reference]
* [[Hardware specification]] -- general description of the hardware on the laptops
* [[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)
** [[DCON]] -- the display controller ASIC and its interface (note that normally you would use the HardwareManager D-BUS interface to manipulate the DCON)
Line 98: Line 210:
* Kernel
* Kernel
** [[Rebuilding OLPC kernel]] -- describes how to rebuild the OLPC kernel, which is sometimes necessary if you need to support otherwise unsupported hardware
** [[Rebuilding OLPC kernel]] -- describes how to rebuild the OLPC kernel, which is sometimes necessary if you need to support otherwise unsupported hardware

= See Also =

* [[Developers/Stack]] -- Developer's Manual discussion of the various operating stacks available to software developers
* [[Sugar Architecture]] -- overall discussion of the architecture (a bit dated)
** [[Sugar Architecture/API]] -- again, a bit dated as a reference
* [[Graphics API]] -- older document describing the sugar.graphics codebase, which is now largely deprecated

[[Category:Developers]]

Latest revision as of 05:26, 10 November 2010

<< Developers/Documentation

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.

API Changes

  • Documented API changes between OLPC XO sofware releases

Platform

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

Sugar Specs

Documentation describing how to integrate into the Sugar GUI shell:

  • Sugar almanac -- API reference
  • Bundles -- general reference for OLPC bundles (including content)
    • Activity bundles -- references to Sugar's Activity (code) bundle (.xo) file format/project structure
    • Activity mimetypes -- how to specify that your activity handles a given MIME-type
  • Low-level Activity API -- reference to the messages your activity should send/receive for Sugar integration

Python Libraries

Where official reference documentation isn't available, PyDoc-generated documentation is provided:

  • See api.sugarlabs.org for an online version for Sugar, generated off the latest code, or
  • See below for instructions on how to produce the PyDoc documentation in your own running image, for every Python package - not only Sugar.

GUI Libraries

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

  • Sugar Architecture (PyDoc) -- core UI and service libraries
    • Activity Support -- support mechanisms for writing activities
    • Datastore -- activity's interface to the datastore service
      • Example -- usage of the datastore API in the Web activity's download manager
    • Code Snippets -- short fragments of code describing the canonical way to achieve various effects
    • Chat -- not widely used
    • P2P-- activity's interfaces to the Telepathy engine
    • Graphics API (PyDoc) -- UI library based on Hippo Canvas
      • Note: this API is largely deprecated, please use standard GTK operations
    • Hippo Canvas -- canvas mechanism used by the Sugar.graphics libraries
      • Note: this API is largely deprecated, please use standard GTK operations
    • Clipboard -- activity's interface to the UI's clipboard interface
      • Note: this API is not necessary for most activities, the standard GTK clipboard can be used instead
  • Gtk, (PyDoc) -- GUI library underlying the Sugar UI (C API)
  • Cairo (PyDoc) -- Low-level vector graphics rendering library
    • Example -- rendering of a game via Cairo
    • RSVG -- Library for rendering SVG text from files/strings onto Cairo Canvases
      • Example -- renders an SVG file to a pygame sprite
      • Example -- rendering an SVG image to a GTK surface

High-Level Widgets

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

Multimedia Libraries

Libraries that deal with multimedia and gaming functionality.

  • GStreamer (PyDoc) -- multimedia streaming library
    • Example -- PenguinTV's gstreamer-based audio-visual control
    • Example -- Sugar's initial training/introduction video
  • CSound -- the CSound audio-generation library
  • OLPCGames (PyDoc) -- PyGame wrapper that makes working within the OLPC-XO environment relatively straightforward (Strongly recommended for PyGame usage on the XO!)
    • Game development HOWTO -- tutorial with multiple samples (e.g. camera, video overlay, multi-channel sound, csound)
  • PyGame -- GUI library suitable for Sprite-based 2D game development (usable from Pippy or OLPCGames)

Communications and Networking

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

  • Sugar Presence API to interact with Presence Service which in turn uses Telepathy
    • Activity sharing -- includes some minimalist code on how to use Presence Service in your activities
    • Example -- HelloMesh example activity using D-Bus Tubes, documented in Collaboration Tutorial
    • Example -- example of using the Presence service in the Web activity
    • SharedState -- project to create a shared-object model over telepathy (used by Calculate)
    • Example -- the Chat activity uses Telepathy text channels
    • Example -- the Connect activity uses DBUS Tube connections
    • Example -- the Read activity opens an HTTP server running on a StreamTube to share files
    • Example -- Games/Productive uses an ExportedGObject shared over the same tube as OLPCGames.mesh
    • Example Example -- the NewsReader activity shares the current feed with joined members via an ExportedGObject (second link)
    • Example -- the Web Browser activity shares the current URL
    • Example -- the Write activity shares an instance of its core control's AbiCollab interface across a Tube
    • Example -- the OLPCGames mesh wrapper provides an example of how to use raw Tubes in a (Pygame) application, the complication being that it has to package incoming events as Pygame events.
      • Example -- use of OLPCGames.mesh to create a "Game Lobby" interface for configuring a game to be played
    • Examples -- the Telepathy-python example code (non-OLPC-specific)
  • 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
  • Xapian -- Full-Text Search library
    • Example -- the datastore uses Xapian for full-text searches
    • SECore -- search engine implementation
  • JSON -- Javascript Object Notation parser/linearisation library
    • Example -- Web activity that uses JSON for some internal storage
  • 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.

Building epydoc Documentation

Another option is building full-system documentation like that at http://dev.laptop.org/~cscott/joyride-api/

The epydoc documentation configuration can be found at http://dev.laptop.org/~cscott/joyride-2083-api/epydoc.py and http://dev.laptop.org/~cscott/joyride-2083-api/epydoc.config

Smalltalk Libraries

D-BUS Services

  • D-BUS (PyDoc) -- desktop messaging (Remote Procedure Call (RPC) and Asynchronous Signalling) engine
  • Presence Service -- buddy discovery and activity collaboration layer on top of Telepathy
  • Telepathy Spec (PyDoc) -- buddy and connection management including cross-machine RPC over D-BUS
    • Telepathy Connection Manager
    • Telepathy StreamEngine
  • 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
  • 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

See Also

  • Developers/Stack -- Developer's Manual discussion of the various operating stacks available to software developers
  • Sugar Architecture -- overall discussion of the architecture (a bit dated)
  • Graphics API -- older document describing the sugar.graphics codebase, which is now largely deprecated