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.

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

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.

Build JHBuild

Add JHBuild to PATH

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 exampleautogenargs_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_docsmodule_autogenargs['atk'] = autogenargs_docsmodule_autogenargs['pango'] = autogenargs_docsmodule_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 featuresmodule_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 debugos.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 changedos.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

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

System -> Administration -> Users and Groups

Click the Keys to make changes and authenticate

Click Manage Groups

Click Add Group

Set the Group Name, example "gnometest"

Set the Group ID, example "1024"

Click OK to return to the Groups dialog

Click Close to return to the Users Settings dialog

Click Add User

Enter a Username, example "gnometest"

Enter a Real Name, exmaple "Gnome Testing"

Set a password by hand, in both dialog boxes.

Switch to the Advanced tab

Set the Main Group to the new group, example "gnometest"

Optionally set the User ID, example "1024"

Click OK to return to the User Settings dialog

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.

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.

Tips & Tricks

Run a single command with JHBuild

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.

Configure GDM to run two X sessions simultaneously

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

TODO: this section doesn't appear to be valid in Karmic, the gdm.conf file doesn't exist. If you don't have access to FUSA, you can get GDM to always launch two X sessions.

Open the file /etc/gdm/gdm.conf in a text editor

$ sudo gedit /etc/gdm/gdm.conf

Find [servers] section

[servers]
# These are the standard servers. You can add as many you want here
# and they will always be started. Each line must start with a unique
# number and that will be the display number of that server. Usually just
# the 0 server is used.
0=Standard

Uncomment the following line:

# 1=Standard

stop your current gdm session with

$ sudo /etc/init.d/gdm stop

and then start new one with

$ sudo /etc/init.d/gdm start

Now you can log into and switch between Xsessions on 7-th and 8-th console:

Press 'Ctrl + Alt + F7

Press 'Ctrl + Alt + F8

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.

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)

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: