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. Below are generic instructions on how to use jhbuild to get up and running with Sugar.
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:
Distro packaging guidelines vary, so please don't worry if jhbuild requires twice/half the packages in one distro that it did on another.
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.
- 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
gitcommand-line tool from the distributed version control system of the same name. In many distributions the minimal package you need to install is "git-core".
- A few packages (as of January 2010, only squeak and part of etoys) do not use git, and you need the
svncommand-line tool from the Subversion version control system to get their source code.
These should be enough to run sugar-jhbuild itself on a typical Linux 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://git.sugarlabs.org/sugar-jhbuild/mainline.git sugar-jhbuild
You'll know if it worked if you get something like this:
localhost ~]$ git clone git://git.sugarlabs.org/sugar-jhbuild/mainline.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
Install everything depscheck complains about. Read the distro-specific instructions for how to do this. Now build all Sugar packages in sugar-jhbuild:
If everything worked out fine, you can now run Sugar. 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.
A useful sequence of commands for building Sugar, from the Sugar mailing list: (Note that build without -n will update first anyway, so run update separately if you want to see what changed more easily.)
./sugar-jhbuild update ./sugar-jhbuild build -n -a --clean ./sugar-jhbuild run sugar-emulator
The use of -a and --clean flags are needed when a file is removed so that autogen.sh 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
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.
Note: if you have a non-US keyboard, please follow the instructions on running Sugar in a VNC session instead.
This command launches Sugar in a nested X session:
./sugar-jhbuild run sugar-emulator
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 sugar in a VNC session
Many users and developers have reported problems with running sugar-emulator because it uses Xephyr. As an alternative, you can run sugar in a VNC session. To accomplish this create a
~/.vnc/xstartup file containing the code below:
#!/bin/sh exec ~/sugar-jhbuild/sugar-jhbuild run dbus-launch --exit-with-session sugar
Note: The above code assumes that sugar-jhbuild is installed in the
Now, you may run Sugar by creating a VNC session and accessing it using a VNC viewer. E.g.:
vncserver :1 vncviewer :1
Run an individual activity
Within sugar, e.g. in Terminal, this command launches an individual activity for testing:
You will see debug output appearing in Terminal.
Configure the mode and resolution of Xephyr
You can make Xephyr run fullscreen or specify a size (in pixels):
./sugar-jhbuild run sugar-emulator --fullscreen ./sugar-jhbuild run sugar-emulator --dimensions 1200x900 ./sugar-jhbuild run sugar-emulator --dimensions 832x624
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). 832x624 approximates the display proportions of the XO laptops, closely matching the toolbar, for example.
JHBuild has several other commands that can be useful for development. You can get an overview with:
From within Sugar
Once you have Sugar running, here are some useful commands (these are not specific to sugar-jhbuild or sugar-emulator, but work in all Sugar sessions):
- 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 you can modify the configuration file named
sugar.jhbuildrc or create a copy of it and pass
--file /path/to/your/new/config to sugar-jhbuild.
Compiling using 2 or more CPU cores
./sugar-jhbuild build, append this to
os.environ["MAKEFLAGS"] = "-j4 -l4"
Adjust the numbers to be twice the number of CPU cores in your machine.
Using ccache to speed up rebuilds
To speed up full rebuilds of sugar-jhbuild (i.e. running
./sugar-jhbuild build after removing the
source directory) you can use ccache. Install it and append the following to
os.environ["CCACHE_DIR"] = os.path.join(os.path.dirname(__file__), "ccache") os.environ["PATH"] = "/usr/lib/ccache:"+os.environ["PATH"]
/usr/lib/ccache to the path used by your distribution and create the
ccache directory (inside your
Building specific version of Sugar
To build a specific version of Sugar do the following:
- Open sugar.jhbuildrc and find line:
modulesets = 'sugar'
- Set this to:
modulesets = 'sugar-0.84'
customizing the latter to your specific needs.
- Copy sugar.jhbuildrc to ~/.jhbuildrc
- Copy all your sugar-jhbuild to sugar-jhbuild-0.84 (for example) or check the repositories out again.
rm -r install source/
- If you want to keep the
sourcedirectory to save bandwidth, you need to be extra careful: delete all unpacked tarballs and cleanup all git repositories with
git clean -d -a.
- Don't forget to delete or modify .jhbuildrc after building the specific version of Sugar if you still want to receive the latest updates from the repositories, OR
- Create another user.
Useful Internal Links
- Understanding Sugar Code
- Taxonomy -- explains the components of Sugar (Glucose, Fructose, Sugar, Starches)
- Sugar Instructions -- how to actually use Sugar once you have it running
Known issue with hulahop
- hulahop stopped building because I had installed a more recent version of xulrunner on my machine. The workaround was to
rm -rf ~/sugar-jhbuild/source/hulahopand then run update and build again.