Development Team/Manual/Setup

  For Developers: almanac · api · bugs · gitorious · cgit · download · people · OLPC: wiki · activities · trac · cgit · build index · repository · firmware · Fedora: packages

Previous Next

Sugar GUI Shell (Our Goal)

The OLPC's software environment is a heavily modified Fedora 11 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. To put it simply, you will likely need to have Sugar running on a computer.

There are two major approaches to running Sugar, running it natively on your machine, and running it in an emulated environment. Which approach you choose will depend on a number of factors, including:

• whether you are just wanting to check the platform out, or are setting up for long-term development work (i.e how much time you want to invest in getting the best possible setup)
• what type of hardware you have available to you
• how comfortable you are with working with traditional Linux tools such as ssh, and vim/nano editors
• what type of development work you are interested in doing

Recommended Environments

For Activity Developers:

• if possible, use an Community/Distributions/Ubuntu
• if you are using MS Win32 and do not want to dual-boot to Linux, use the QEMU Quicker Start package for Win32 (~5 minute setup on XP, ~10 minutes on Vista)

If you can use either of those environments, you can skip down to the Configuration and Usage section once you've completed the installation.

If you can neither run an emulated machine or run Sugar natively, it is still possible that you may be able to develop for the platform by Cross Coding. Even if this isn't possible, you could consider working on one of the software components we use.

About Emulation

There are a number of tools which allow you to run an image of one operating system in a window on another system. If you have the hardware and want to get started as fast as possible, choosing an emulated approach is probably for you.

Emulation is a computationally intensive operation, it requires a powerful (modern) host machine with lots of RAM and lots of storage space. Each official image you wish to use will require about 2GB of disk storage with ancillary files and unpacking requirements.

Emulation is also a 90% thing, that is, it normally gets about 90% of the emulation correct, but things such as peripherals, sound, cameras, keyboards and the like can be "slightly off" in an emulated environment. You should always keep this in mind when working with a emulator.

Emulation Packages/Products

Emulation is a hot topic these days, there are lots of emulation systems available, some no-cost, some Open Source, some commercial. We cannot hope to support all of these systems, so we have focused our efforts on small subset of systems:

• OLPC:QEMU (with the KQemu Accelerator)
  • Our best-supported emulation system
  • With the KQemu package provides reasonably fast emulation
  • Open Source and runs well on Linux and Windows machines
  • Basic setup is reasonably easy
  • Allows for working in "overlays"
  • Command-line interface on Windows, Linux and Mac, GUI available for Windows and Mac
  • Works directly with offical builds
• OLPC:VMware / OLPC:VirtualBox
  • Commercial emulation packages with no-cost "players" for images
  • Somewhat easier setup than Qemu, particularly for advanced networking on Linux hosts
  • Require converted images, which are not always kept up-to-the-minute and do not include experimental/testing builds
  • Beta version of VMWare (Fusion) available for Mac OS X
• Parallels Desktop
  • Commercial emulation package
  • Extremely difficult setup
  • Mac friendly

Which emulation system you choose is mostly a matter of preference and suitability for your system.

See Also:

• OLPC:Emulating the XO -- has a handy chart outlining which system has been reported to work with which type of emulation task

Emulation for Exploration

Want to just see what Sugar is like? Want to play with the activities and kick the tires? Downloading a Qemu or VMWare/VirtualBox image and running it is normally a matter of a half hour or so.

Emulation for Development

It is possible to code software on an OLPC-XO running Sugar. One of our long-term goals is to make this an easy and straightforward process. The "Gear" key on the keyboard of the OLPC-XO will eventually hook up to an IDE activity for altering and creating new code. That IDE is not yet finished, however.

Official Images

The only "normal" code editing environments present on the OLPC-XO are all command-line environments available through the OLPC:Terminal activity. Official Sugar images include both the vim and nano editors, so users who know these editors can use them to write and modify software within the images.

Developers wishing to use the Etoys application stack can create new software from Etoys built-in development environment while running on an emulator.

Developer's Desktops

If you have a very powerful host machine, it is possible to run an entire "regular" Linux desktop with a sugar-jhbuild or package-based install of Sugar. This will tend to take a lot more memory, processing power and disk space than using an official image (which is, of course, intended to run on a relatively lightweight computer), but it gives you most of the benefits of the native Sugar approach.

See #Native Sugar

Emulation for Compilation/Experiments

One very useful feature of emulation systems is their ability to "snapshot" or "overlay" images. This feature allows you to leave a base image untouched while performing some messy or dangerous operation. When you are finished the operation, you can return to the unmodified base image.

For example:

If you want to support a piece of hardware that requires a kernel module, you can mount a Qemu copy-on-write or VMWare snapshot into which you install the whole kernel-compilation toolset (likely getting quite close to filling up the whole storage).

You can then compile the kernel and then the missing driver. When you are finished, you copy the driver to the host machine and can install the compiled driver into the base image.

Emulation for Testing

If you are #Cross Coding or using a #Native Sugar environment, you will often want to use an emulated official image for testing. This is often far more convenient than loading the image onto a real XO and doesn't require hardware you might not have.

For support operations, it is often handy to be able to load exactly the operating system image that a user is using in order to be able to duplicate a bug. You can use an emulated version of the system instead of a real XO to save "wear and tear" on the XO's flash storage.

Emulation tools often have the ability to share folders with the emulated machines, this lets you work on your host machine, quickly see if the code works on the emulator, and only then package up and test on a real machine (or potentially have someone else test).

It should be noted that emulators often have difficulties with sound support and graphics resolutions. They also can wind up being much faster or slower than the target hardware. See the Developer's FAQ below for some pointers on how to simulate the special hardware. Testing in emulation is valuable, but eventually the software needs to be tested on real hardware.

Getting Started (Emulation)

For a detailed exploration of emulation issues with a focus on using the official images, see OLPC:Emulating the XO, which includes setup and configuration issues, tips and hints, and a grid of known-working approaches to emulating an OLPC-XO laptop.

You will need to install one of the emulation systems and download an image:

• OLPC:QEMU + KQemu (recommended where possible)
  • Ship.2 -- patch releases for Official Releases
  • Joyride -- Bleeding Edge/Development Releases
  • Update.1 -- release candidates for the Update.1 refresh
• OLPC:VMware, OLPC:VirtualBox (good secondary choices, particularly if you already have one installed)
  • All Builds -- collection of all the pre-converted images (the same images work on either system)

More complete descriptions of the various Image Types are available. Follow the specific instructions on the emulation-system-specific pages linked to above to get started.

See Also:

• #Configuration and Usage -- instructions on how to setup and use Sugar once you have it installed

Native Sugar

If you are running a modern Linux Operating System (whether as your primary OS, as a Live CD, via dual-booting, or potentially even via emulation), it is quite possible that you can run Sugar directly on your Linux machine with its current OS.

Core developers, as opposed to Activity developers, will likely need to set up a sugar-jhbuild environment. sugar-jhbuild uses the bleeding edge version of each component, often checked directly out of the source-code-control for each project. It allows you to work with developers across many different projects, and it tends to be fragile as a result.

Activity developers without XO hardware can use pre-built sugar that is installed as packages. For Ubuntu and some other Linux distributions, developers can run the sugar emulator to create a separate, full screen X server.

Sugar as Your Shell

Sugar, though a bit exotic seeming compared to most GUI shells, such as KDE or Gnome, is really just a GUI shell. As such, you can run it either as the actual shell for a GUI login session, or in a virtual X session (that is, a window that mimics a whole X session/server).

The official OLPC images, of course, run Sugar as the GUI shell for the primary X server. So if you are running an official image (for example because you are working directly on an OLPC-XO) you will be running Sugar as your GUI shell. Similarly, the Live Backup Live CD, which is based on an official image, boots directly into the Sugar shell. On Fedora 11, you can also (with recent versions of Sugar) choose a Sugar session from your GDM/KDM/XDM-based login manager.

Virtual X Server

In most other cases, you want to run Sugar in a virtual X session. This allows you to have multiple Sugar desktops running and visible simultaneously to test networking and the like. The virtual X sessions can be quickly shut down and restarted without needing to log out and back in again. Most core developers are using this type of setup using sugar-jhbuild.

sugar-jhbuild

This is what the core development team uses and is one of the most pleasant ways to work (once set up). 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 environment.

The 'native' environment for sugar-jhbuild is Fedora, and this is by far the best supported development platform for sugar-jhbuild. Ubuntu and Gentoo can also build the environment.

Currently sugar-jhbuild requires about 2.5 hours to complete building on a modern workstation (AMD4800+).

You can run sugar-jhbuild under emulation. This has the advantage of working on a wider range of Linux hosts (as well as Windows or Mac OS-X), and does not "pollute" your host machine with Sugar libraries. It requires a lot of disk space and processing power, however.

See Development Team/Jhbuild to get started.

See Also:

• #Configuration and Usage -- instructions on how to setup and use Sugar once you have it installed

Native Sugar Packages on Linux

As Sugar stabilizes and is ported to more distributions, it should be possible to use your Linux distribution's package management system to install Sugar. Distributions with ports so far:

• Community/Distributions/Ubuntu -- These packages seem to work well and are extremely easy to set up. If you are running on Ubuntu Gutsy and are not working on Sugar's core software, this is very simple way to work.
• Community/Distributions/Debian-- Note that we need more testing of this package-set, please let us know your experiences

If you don't see your distribution here, ask your distribution maintainers, or if you have the skills, create the packages yourself and submit them.

See Also:

• #Configuration and Usage -- instructions on how to setup and use Sugar once you have it installed

A Real OLPC-XO Laptop

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

A large number of units were distributed in the Give 1 Get 1 program throughout the US or Canada. If you have sufficient funds, you can acquire a production-run machine from a secondary market such as EBay.

If you would like to run a non-official (i.e. experimental, unstable) build on a Mass-Production/G1G1 machine you will need to acquire a developer key to allow your (locked) laptop to load the unsigned image. You probably do not need to run an experimental image for most activity development purposes.

See Also:

• #Emulation for Development -- discussions on the current limitations on using the official images as development environments
• Getting Started -- guide to using a new OLPC-XO Laptop

Almost an OLPC

The introduction of the OLPC-XO has ignited the low-cost computer market. There are a large number of low-cost machines with approximately the same performance level as an OLPC-XO. As of right now, we don't have any reason to recommend that you should buy one of these "almost an OLPC" machines, while they may be superficially similar to an XO, they are not likely to be any closer than an emulated XO running an official image.

See: OLPC:Development Systems

Live CDs

There are currently a number of projects underway to produce various types of OLPC:LiveCD. LiveCDs are not a "normal" part of the development process, normally being used for lightweight deployments, experimentation, testing, and potentially installation onto a dedicated machine to create a workstation.

See #Emulation for Development for considerations regarding installing LiveCD's based on official images for development.

Cross Coding

If you can neither run an emulated machine nor run Sugar natively, it is still possible that you may be able to develop for the platform by developing your code on one machine and then porting it to the platform when you are finished.

Cross coding generally works best when you are working in a relatively constrained and abstracted environment. Of the stacks available on the Sugar platform, the following are well suited to Cross Coding activities:

• Browser -- Mozilla/Firefox-derived web browser
• Etoys -- Squeak/Smalltalk multimedia environment
• Pygame -- raster-graphics game development framework, see also Development_Team/Sugargame
• Flash -- Gnash or Adobe-Flash engine

You may be able to install just the software involved in that stack in order to test and develop your game. You can then have a development partner do porting and testing to a Sugar environment.

Configuration and Usage

Now that you have either a native or emulated Sugar environment, you are likely wondering how to use and configure it for your needs:

• OLPC:Sugar Instructions -- how to get around inside Sugar (i.e. how to use it)
• OLPC:Support -- how to get help with running Sugar (on an OLPC-XO)

You can install new software in your Sugar environment in a couple of ways.

• Activities -- can be downloaded using the built-in browser or installed from the command line
• General Linux packages can be downloaded and installed using Yum (note, these changes will be wiped out on the next OS upgrade)

Jabber Servers

By default your image may have been configured to connect to either an inaccessible or a non-existent Jabber server. You can see this by zooming out to the network view (Alt-F1 in an emulator). If there are no other XO icons in the view you are likely not connecting to a server.

At the moment (2007-12-17) we are in the middle of rebuilding the Jabber servers to support the much larger loads seen during deployment. Ask on the #olpc IRC channel which Jabber server you should use, then open a OLPC:Terminal activity and use the following command:

sugar-control-panel -s jabber jabber.server.url

and then restart the X server, either restart the machine or use ctrl-alt-backspace (erase), but do not do ctrl-alt-backspace on an emulator, or you will kill your entire GUI session!

SSH Access

You will often want to be able to use file-transfer and remote-login operations to access your Sugar environment. We recommend using ssh-based access for working with your Sugar environment remotely.

Note: If you are using sugar-jhbuild you likely do not need to follow these instructions (since you're already using a running Linux desktop that shares its login and file-system with the Sugar instance).

See:

• ??? SSH user's guide
  • ??? SFTP user's guide and tools

Password Based

Password-based SSH authentication is convenient and simple to set up.

(However, it is far easier to crack than key-based access. This is because a password can be guessed, especially if multiple automatic attacks are made. Attacks can arrive over a wireless network from hosts that you trust. It is more secure to use key-based authentication. Accept password-based authentication if you are confident that your network is secured.)

Open a OLPC:Terminal activity and run:

 passwd

which will prompt you to enter a password (and confirm it). This enables remote access for the default user.

Since the default user can su, you should also set a password on the root account:

su root
passwd

SSH Key Based

SSH Key based authentication provides strong public-key encrypted access control for your Sugar environment, but takes a bit more work than SSH Password base authentication.

In summary, you create a private key which will be stored on your remote system and encrypted with a strong password. You transfer the public key (think of it as a lock) that corresponds to that key to the Sugar environment and install it as an "authenticated key" which can be used to log into the Sugar environment.

On your remote system, install SSH (Linux and Mac OS X will already have it installed, on Windows use the PuTTY program) and generate a new ssh key pair (following is for Linux and Mac OS X, refer to PuTTY's documentation for details on Windows):

 ssh-keygen

Usage notes:

• Accept the defaults for key-type and size.
• If ssh-keygen asks if you want to overwrite a key say No, you are about to destroy your current ssh key!
• Use a strong passphrase that you can remember easily (the passphrase will need to be entered frequently unless you make use of an agent such as offered by PuTTY, ssh-agent or Gentoo's keychain)

ssh-keygen will normally create a file in your ~/.ssh/ directory named id_rsa.pub (if you accepted the defaults). Copy this file to your Sugar environment and add it to the contents of the ~/.ssh/authorized_keys file (you may need to create the file).

mkdir ~/.ssh
cat id_rsa.pub >> ~/.ssh/authorized_keys

add your key to your keychain or ssh-agent application and you can now use SSH with just a single sign-on for many concurrent actions.

See: SSH Into Qemu for Qemu-specific notes regarding port forwarding

See Also

• OLPC:Compiling C/C++ program for the OLPC

• OLPC:Building custom images -- how to create entirely custom Sugar OS images using Pilgrim

Previous Next