Development Team/Jhbuild

From Sugar Labs
< Development Team
Revision as of 00:33, 2 October 2009 by TimClicks (talk | contribs) (→‎Jhbuild FAQ: formatting)
Jump to navigation Jump to search
english | 日本語 | spanish HowTo [ID# 38731]  +/-  

Sugar-jhbuild will automatically download the latest of Sugar's dependencies as well as Sugar itself directly from their source repositories, rather than relying on source packages that may have become stale. It can also run a Sugar session in a window on your desktop using the wikipedia:Xephyr nested X window server. Below are generic instructions on how to use jhbuild to get up and running with Sugar.

Compatible platforms

Jhbuild is quite demanding with regard to the packages and setup for the host Linux distribution. As a result there are only a few Linux distributions which are known to work with it.

See the distribution-specific instructions for information about whether your distribution is currently supported. Other distros which have a recent-enough release (e.g. including the latest stable GNOME release) can be supported if someone is willing to maintain the dependencies for that distro release (in config/sysdeps).

Check distro-specific instructions

Many distributions have some quirks that need to be catered for and there are different package managing tools in use, so please check the page for your distribution before proceeding:

Here are some videos of the Fedora jhbuild install process.

Some general advice

Note: Like most other Unix applications, sugar-jhbuild should never be run as root. It may easily screw up your whole system and/or break in unexpected ways if you do. If you get any permissions error, there's something wrong with your installation that should be fixed.

If you're stuck or if you get strange errors, feel free to ask for help on the #sugar IRC channel or the sugar-devel mailing list. Don't waste too much time chasing strange problems: usually it's caused by some basic, easy to fix problem. You might also want to check the bug tracker to see if it's a known issue.

Jhbuild FAQ

<dgd> jhbuild build on fedora11 requires 29 packages but on Ubuntu904 38... should I be concerned with the difference in number?
<sdziallas> dgd: this can be caused by different packaging policies...
<dgd> sdziallas, ergo not a reason for concern, thanks!

definitely do not compile as root with jhbuild -- you'll run into funky problems -- Colin A. :)


The sugar-jhbuild command is a Python script, so you need the Python interpreter.
To get the source code of sugar-jhbuild itself and many other Sugar packages you need the git command-line tool from the distributed version control system of the same name.
A few packages (as of September 2009, only squeak) do not yet use git, and you need the svn command-line tool from the Subversion version control system to get their source code.

These should be enough to run sugar-jhbuild on a typical Linux or Mac installation. Running sugar-jhbuild depscheck (see below) will probably list dozens of additional required packages.

Check out sugar-jhbuild

In a suitable directory (i.e. usually your user's home directory i.e. /home/yourusername/~), execute

git clone git:// sugar-jhbuild
Make sure you are in the _user's_ home directory

You'll know if it worked if you get something like this:

localhost ~]$ git clone git:// sugar-jhbuild
Initialized empty Git repository in /home/denny/sugar-jhbuild/.git/
remote: Counting objects: 4688, done.
remote: Compressing objects: 100% (1998/1998), done.
remote: Total 4688 (delta 2759), reused 4488 (delta 2638)
Receiving objects: 100% (4688/4688), 1.86 MiB | 197 KiB/s, done.
Resolving deltas: 100% (2759/2759), done.

Build sugar base system and its dependencies

Go into the directory you created and start the build. It takes about 30 minutes on a 1.6ghz machine with a wireless G connection.

cd sugar-jhbuild
./sugar-jhbuild update
./sugar-jhbuild depscheck
./sugar-jhbuild build
Here are videos of the process. Before saying that Youtube is unfriendly to Linux because of the flash player, try installing it. Adobe flash works on my Ubuntu 9.04 and Fedora 11 without hitch.

And now run it.

./sugar-jhbuild run

If it doesn't run or you have other problems read on.

Dealing with dependencies

sugar-jhbuild depscheck will print a list of required packages. They are part of the distribution you're using and should be installed using your favourite package manager (e.g. aptitude/synaptic for Debian, yum for Fedora).

If you notice that there's a package missing from the ./sugar-jhbuild depscheck output (i.e. it's required for Sugar to work properly and not installed, but depscheck does not mention it), please file a bug report (login required first, but currently no automatic redirection to login page) against the sugar-jhbuild Component in the Sugar Labs bug tracker.

Some tips and known issues

Question. How do you run autoconf to fix this problem?
when you get asked because of the error, choose the configure stage

Run Sugar

This command launches the Sugar emulator in a nested X session:

./sugar-jhbuild run

To exit the emulator, press Alt-Q.

To set debug variables, modify ~/.sugar/debug (this file will be created on first run of Sugar).

Note that due to a bug in Xephyr your keyboard might not work as expected. A partial workaround is to run setxkbmap <keymap name> by adding this command line to ~/.sugar/debug. Most "regular" keys should work fine after that, some "special keys" (e.g. cursor up/down) might still refuse to operate as intended.

The "keymap name" usually is a two letter country code, e.g. "de" for german or "fr" for french.

Running multiple instances

To run an additional instance of sugar, you can start the second instance in the following way:

SUGAR_PROFILE=2 ./sugar-jhbuild run

This will create a new profile in ~/.sugar/, i.e. ~/.sugar/2/. You will find logs and configuration for this instance here. The default profile is ~/.sugar/default/

Run an individual activity

Within sugar, e.g. in Terminal, this command launches an individual activity for testing:

sugar-launch bundle_name

You will see debug output appearing in Terminal.

Configure the mode and resolution of Sugar

You can make Sugar run fullscreen or specify a size (in pixels):

./sugar-jhbuild run sugar-emulator --fullscreen
./sugar-jhbuild run sugar-emulator --dimensions 1200x900

The default size of 800x600 is currently the minimum that should work without issues. I.e. activities should be tested to work in this mode (and in others as well).

Other commands

JHBuild has several other commands that can be useful for development. You can get an overview with:

./sugar-jhbuild --help-commands

A useful sequence of commands for building Sugar, from the Sugar mailing list: (Note that build will update first anyway, so run update separately if you want to see what changed more easily.)

./sugar-jhbuild update
./sugar-jhbuild build -a --clean
./sugar-jhbuild run

The use of -a and --clean flags are needed when a file is removed so that is run. Note: Some packages, e.g., squeak and etoys, don't have a make clean. Just ignore the error.

If build breaks after an update

The packages in sugar-jhbuild are the latest development versions, so you not only get the latest features, but also the latest breakages. The dependencies may change often, too, so be sure to run

./sugar-jhbuild depscheck

regularly and install the missing packages.

If your problem persists for more than a day (and even though you installed all missing packages), please file a bug report.

From within Sugar

Once you have Sugar running, here are some useful commands:

  • Alt+Shift+F makes the frame appear and disappear
  • Ctrl-Q quits an activity
  • Alt+Shift+Q quits Sugar
  • Alt+Shift+O opens the search
  • Alt+Shift+R rotates the screen


To customize the build create a configuration file, named .sugar.jhbuildrc, in your home directory.

Write access to the repositories

If you have write access to the repositories you can add this (if your login name happens to be marco):

repos[''] = ''
repos[''] = ''
repos[''] = 'git+ssh://'
repos[''] = 'git+ssh://'

Useful Internal Links

External links