/!\ Warning: This page is probably outdated. Follow the official jhbuild documentation

Building GNOME from Git on Ubuntu using JHBuild

General Notes

  • This is an Unofficial and Practical Guide to Gnome Development with Ubuntu. It is not associated with Ubuntu and Canonical Ltd.
  • This guide is tested on a full installation of Ubuntu 9.10 x86 Desktop CD (Karmic)
  • Text within boxes, preceeded by $ must be executed in the Terminal (Applications -> Accessories -> Terminal)

  • To reduce typos, copy and paste the commands into Terminal mode (right click on the commands -> "Copy" or "Paste")

  • "sudo" means "superuser do". The sudo command will prompt for a password. Enter your user password.

  • "apt-get" requires an Internet connection to install / update / download programs
  • Please add to this wiki and help others
  • May the humanity to others spirit be always with you ... ;-)

Guide Prepared by- MarcinAntczak

Editing and wikification by- BaishampayanGhose

Added part about starting DBUS, 2006-01-20 - BrentSmith

Updated after cvs2svn switch, 2007-01-08 - LucaFerretti

Updated for git, sync'd with library.gnome.org pages, 2010-03-24 - RyanMaki

Getting Started

Ubuntu is a community developed operating system that is perfect for laptops, desktops and servers. Whether you use it at home, at school or at work Ubuntu contains all the applications you'll ever need, from word processing and email applications, to web server software and programming tools.

For more information:

List of all the programs/libraries that come with Ubuntu:

Download Ubuntu:

Find help for Ubuntu:

Prepare your Ubuntu system for Gnome development

In order to assist in the development of packages that are part of the official Gnome D&DP (Desktop and Developer Platform), you will need to be running the latest development version. There best way to obtain latest development version is to build it with JHBuild scripts.

Install JHBuild

These instructions are adapted from the Jhbuild Getting Started documentation.

Install required JHBuild packages

JHBuild requires numerous additional packages that can be installed by apt-get, aptitude, or Synaptic.

Go to the section of the JhbuildDependencies/Ubuntu page which corresponds to your Ubuntu release for the most up-to-date instructions to install packages that are required by JHBuild to build Gnome. When complete, return to this page and continue.

Create the installation folder and setup permissions

$ sudo mkdir -p /opt/gnome2
$ sudo chown `whoami`:`whoami` /opt/gnome2

Create the build folder

$ mkdir -p ~/checkout/gnome2

Checkout JHBuild module

$ cd ~/checkout/gnome2
$ git clone git://git.gnome.org/jhbuild

Build JHBuild

$ cd jhbuild
$ ./autogen.sh
$ make
$ make install

Add JHBuild to PATH

Manually add ~/.local/bin to the PATH environment variable:

$ PATH=$PATH:~/.local/bin

To permanently add ~/.local/bin to the PATH variable, run the following command:

$ echo PATH=$PATH:~/.local/bin >> ~/.bashrc

Sanity Check the JHBuild environment

Use the sanitycheck to ensure all required packages are installed.

$ jhbuild sanitycheck

If failures are encountered, check the JhbuildDependencies/Ubuntu page and ensure all steps were followed for your version of Ubuntu.

Configure JHBuild

Before running JHBuild, it is necessary to set up a configuration file located at ~/.jhbuildrc.

$ cp sample.jhbuildrc ~/.jhbuildrc

Open the file, read the comments, and manually adjust variables to your preferences. Configuration variables are documented in the Configuration File Reference.

$ gedit ~/.jhbuildrc

The following is an example .jhbuildrc configuration file you can use for reference.

# -*- mode: python -*-

# edit this file to match your settings and copy it to ~/.jhbuildrc

# if you have a GNOME git account, uncomment this line
# repos['git.gnome.org'] = 'ssh://user@git.gnome.org/git/'

# what module set should be used.  The default at the moment is 'gnome-2.30',
# but it can be any of the files in the modulesets directory, or even
# the URL of a module set file on a web server.
moduleset = 'gnome-2.30'

# A list of the modules to build.  Defaults to the Gnome Desktop and
# developer platform.
# modules = [ 'meta-gnome-desktop' ]

# what directory should the source be checked out to?
checkoutroot = os.path.expanduser('~/checkout/gnome2')

# the prefix to configure/install modules to (must have write access)
prefix = '/opt/gnome2'

# extra arguments to pass to all autogen.sh scripts
# to speed up builds of gnome2, try '--disable-static --disable-gtk-doc'
# it is also possible to set CFLAGS this way, 'CFLAGS="-g -O2"' for example
autogenargs_docs='--enable-maintainer-mode --disable-static --enable-gtk-doc'

# On SMP systems you may use something like this to improve compilation time:
# be aware that not all modules compile correctly with make -j2
# You can also use 'make V=0' if you want less output while compiling.
#makeargs = '-j2'

module_autogenargs['glib'] = autogenargs_docs
module_autogenargs['atk'] = autogenargs_docs
module_autogenargs['pango'] = autogenargs_docs
module_autogenargs['gtk+'] = autogenargs_docs

# those are modules that could need some custom extra arguments
# in order to build in a proper way or to build extra features
module_autogenargs['dbus'] = autogenargs  \
                             + ' --with-system-socket=/var/run/dbus/system_bus_socket' \
                             + ' --with-system-pid-file=/var/run/dbus/pid '
module_autogenargs['hal'] = autogenargs  \
                            + ' --with-socket-dir=/var/run/hal' \
                            + ' --with-pid-file=/var/run/hal/hald.pid '

module_autogenargs['evolution-data-server'] = autogenargs \
                            + ' --with-krb5=/usr' + ' --with-openldap=/usr'

module_autogenargs['evolution'] = autogenargs \
                            + ' --with-krb5=/usr' + ' --with-openldap=/usr'

module_autogenargs['vinagre'] = autogenargs \
                            + ' --enable-avahi'
module_autogenargs['vino'] = autogenargs \
                             + ' --enable-gnome-keyring=yes' \
                             + ' --enable-session-support=yes' \
                             + ' --enable-avahi'

# set CFLAGS: -g to enable debug
os.environ['CFLAGS'] = '-g -O2'

# On SMP systems you may use something like this to improve compilation time:
# be aware that not all modules compile correctly with make -j2
#os.environ['MAKEFLAGS'] = '-j2'

# a alternative install program to use.
# The included install-check program won't update timestamps if the
# header hasn't changed
os.environ['INSTALL'] = os.path.expanduser('~/bin/install-check')

Instead of the os.environ variables, you can also add these lines in more recent versions of jhbuild

addpath('ACLOCAL_FLAGS', '/usr/share/aclocal')
addpath('PKG_CONFIG_PATH', '/usr/lib/pkgconfig', '/usr/share/pkgconfig')

Another jhbuildrc file that you can learn from is from MicroTinder: jhbuildrc

Remember to change the ~/.jhbuildrc file to suit your needs.

Build Gnome with JHBuild

After set up is complete, JHBuild can be used to build software. To build all the modules selected in the ~/.jhbuildrc file}, run the following command:

$ jhbuild build

JHBuild will download, configure, compile and install each of the modules. If an error occurs at any stage, JHBuild will present a menu asking what to do. The choices include dropping to a shell to fix the error, rerunning the build from various stages, giving up on the module, or ignore the error and continue.

It is also possible to build a different set of modules and their dependencies by passing the module names as arguments to the build command. For example, to build gtk+:

$ jhbuild build gtk+

To build one or more modules, ignoring their dependencies, JHBuild provides the buildone command. For the buildone command to complete successfully, all dependencies must be previously built and installed or provided by distribution packages.

$ jhbuild buildone gtk+

Using JHBuild Gnome

Create a new user for testing

  1. System -> Administration -> Users and Groups

  2. Click the Keys to make changes and authenticate
  3. Click Manage Groups
  4. Click Add Group
  5. Set the Group Name, example "gnometest"
  6. Set the Group ID, example "1024"
  7. Click OK to return to the Groups dialog
  8. Click Close to return to the Users Settings dialog
  9. Click Add User
  10. Enter a Username, example "gnometest"
  11. Enter a Real Name, exmaple "Gnome Testing"
  12. Set a password by hand, in both dialog boxes.
  13. Switch to the Advanced tab
  14. Set the Main Group to the new group, example "gnometest"
  15. Optionally set the User ID, example "1024"
  16. Click OK to return to the User Settings dialog
  17. Click Close to exit

Create a JHBuild Gnome session

Create the /etc/jhbuild.conf file.

$ sudo gedit /etc/jhbuild.conf

This file sets the 'prefix' to the same value as the ~/.jhbuildrc file. Note that if you want to use simultaneous X sessions (see below), you can't use os.environ['HOME'] (it will change depending on the current user). Save the file with the 'prefix' to match your installation.

prefix = '/opt/gnome2'

Create the /usr/bin/jhbuild-session file.

$ sudo gedit /usr/bin/jhbuild-session

with the following content:

exec jhbuild --file=/etc/jhbuild.conf run gnome-session

Make the session file executable by running

$ sudo chmod a+x /usr/bin/jhbuild-session

Create a JHBuild desktop file for the session.

$ sudo gedit /usr/share/xsessions/jhbuild.desktop

Insert the following lines into the new file.

[Desktop Entry]
Name=JHBuild GNOME
Comment=This session logs into the JHBuild GNOME

Now you can log into your new session with GDM by selecting Jhbuild GNOME from the GDM Sessions menu. You should not log into the experimental JHBuild Gnome using your main user account, create a new user account for Gnome testing, as shown above.

Run multiple X sessions simultaneously

In order to develop Gnome in an effective and secure way you should run two (or more) X sessions simultaneously. You should run your stable Gnome on the first session and your unstable JHBuild Gnome on another. In this way you can develop with your stable Gnome and test your efforts on the JHBuild Gnome.

  1. Before logging in as the test user for the first time set the

$ sudo -u gnometest echo 'exec jhbuild --file=/etc/jhbuild.conf run gnome-session' > .xinitrc
  1. To start another X session manually you need to switch to Console mode. Read How to switch to Console mode in GNOME? log in as the test user, 'gnometest' for example.

  2. Now you can start your new Xsession:

startx -- :1 &
  1. You also can configure GDM to run two Xsessions permanently. Read How to configure GDM to run two Xsessions simultaneously? and log as 'betatester' into jhbuild Gnome on 8-th console and on your regular account on 7-th console

  2. Now you can hack on your stable desktop with your favourite tools and test your code in the JHBuild session. See Tips & Tricks for shortcuts to switch between consoles.

Tips & Tricks

Run a single command with JHBuild

(cribbed from Federico's)

The following is the quickest and dirtiest way to run a single command in the current Gnome environment. It has many problems, such as requiring the the currently running gconfd, gnome-vfs-daemon, etc to be compatible with the new software. It also uses, and therefore might ruin, your gconf settings, possibly rendering your account unusable. Yes, it's easy, but be careful!

$ jhbuild shell
$ ./gnome-foo       # The program you want to run

Another way is to run the program in its own environment but have it display its windows on your desktop. This is much safer than above but is still open to subtle problems (sharing root window, etc).

You will need to run the following command once as the test user before running jhbuild shell.

$ sudo -u gnometest ln -sf /etc/jhbuild.conf ~/.jhbuildrc

$ ssh -X test@localhost
$ jhbuild shell
$ ./gnome-foo

You can automate the previous step using the jhrun script. Change USER to be the user you'd like to log in as, then save this script somewhere in your $PATH (~/bin/jhrun or /usr/local/bin/jhrun). Make sure to "chmod a+x jhrun". If you're annoyed at having to type your password all the time, run "sudo cat ~/.ssh/id_rsa.pub >> ~test/.ssh/authorized_keys". If you don't have an id_rsa.pub file, then run "ssh-keygen -t rsa" and hit <return> when it asks for a passphrase.

use File::Spec;
my $USER = 'test@localhost';
exec "ssh", "-X", $USER, "jhbuild", "run", File::Spec->rel2abs($ARGV[0]);

With all that set up, running a program in the test user's environment but displaying on your screen simply requires:

$ jhrun ./gnome-foo

Or, safest of all, you can run the "two simultaneous X sessions technique" as detailed below.

How to restart GNOME without rebooting computer?

  1. Save all open documents and close all applications
  2. Press 'Ctrl + Alt + Backspace'
  3. or

  4. Use $ sudo /etc/init.d/gdm restart

Switch to a console mode from GNOME

To switch to Console mode:

  • Press 'Ctrl + Alt + F1' (F2 - F6 for other text consoles)

To switch back to GNOME:

  • Press 'Ctrl + Alt + F7' for the main desktop
  • Press 'Ctrl + Alt + F8' for additional desktops, if you have created them.

Configure GDM to run two X sessions simultaneously

Ubuntu includes the fast-user-switch-applet (FUSA) that allows you to log in as the test user without logging out of your existing account.

  1. Create a test user account

  2. Create the JHBuild Gnome Session

  3. Use FUSA to switch to the new user, making sure to specify the JHBuild Gnome Session.

How to get dbus support

Some applications require access to dbus in order to start such as epiphany and evince.

To get access to dbus, you need to modify your .xinitrc slightly to run dbus-launch.

$ echo 'exec jhbuild --file=/etc/jhbuild.conf run dbus-launch gnome-session' > .xinitrc

This basically starts a per-session dbus-daemon and then launches gnome-session with the DBUS_SESSION_BUS_ADDRESS environment variable set. This allows all the applications that gnome-session spawns to have access to dbus.

Note that this will not use the latest version of dbus included with JHBuild. To do that, you will need to stop the system-wide message bus (requires root privileges via sudo). Before you startx, you should perform the following commands: (Make sure you have modified your .xinitrc as shown above)

sudo /etc/init.d/dbus-1 stop
sudo /opt/gnome/bin/dbus-daemon --system
sudo /opt/gnome/sbin/hald --daemon=yes --retain-privileges
startx -- :1 &

DBus support - alternative

An alternative approach to dbus is to use the already-running system dbus. This means you don't have to use .xinitrc and can just launch a JHBuild session from gdm using a jhbuild.desktop file. To use the system dbus:

mkdir -p $prefix/var/run
cd $prefix/var/run
ln -s /var/run/dbus dbus

Projects/Jhbuild/OnUbuntu (last edited 2013-11-25 16:27:56 by WilliamJonMcCann)