Using jhbuild on Novell Linux Desktop

FOR IMPATIENT PEOPLE: This document describes in detail what you need to do to run jhbuild under Novell Linux Desktop. If you are an impatient person, and want to skip a lot of interesting technical discussion, at least make sure you follow these steps:

  1. Download and install jhbuild
  2. Set up your ~/.jhbuildrc
  3. Bootstrap jhbuild
  4. Build your GNOME desktop

If you read just that and something goes wrong, don't blame me. Read the whole document and learn how things really work. Then you will be able to fix problems by yourself.

After that little introduction...

Jhbuild is a wonderful set of scripts that you can use to keep an up-to-date build of GNOME without disturbing your existing installation. Jhbuild automatically pulls the latest sources from the GNOME CVS repository, and it figures out the correct order for compilation based on a dependency graph: you can type a single command like "jhbuild build meta-gnome-desktop", and some time later you'll have a bleeding-edge GNOME desktop neatly installed in your computer.

While jhbuild pretty much works out of the box, you may need to tweak the configuration a bit to run it under different GNU/Linux distributions. This page explains the changes I had to make to run jhbuild on Novell Linux Desktop.

Why are changes needed?

NLD is based on SUSE, which has a few idiosyncrasies.

NLD installs GNOME under /opt/gnome instead of the more conventional /usr. Configuration files get put in semi-disparate places like /etc/opt/gnome and /var/opt/gnome.

Some environment variables will have values that reflect the paths above. These environment variables are often just not set at all in other distributions, so you may not even see problems there. Here, however, having these values set means that they will clash with jhbuild's own environment.

Variable Value Remarks
ACLOCAL_FLAGS -I /opt/gnome/share/aclocal Used when compiling. You don't want packages built with jhbuild to pick up Autoconf macros from here.
GNOME2_PATH /usr/local:/opt/gnome:/usr Used at runtime. Various files such as icons and themes get looked up in subdirectories of these paths.
GTK_PATH /usr/local/lib/gtk-2.0:/opt/gnome/lib/gtk-2.0:/usr/lib/gtk-2.0 Used at runtime. GTK+ looks here for theme engines, input modules, pixbuf loaders, and other things.
GTK_RC_FILES /etc/opt/gnome/gtk/gtkrc:/home/federico/.gtkrc-1.2-gnome2 This is obsolete, and only used for programs which still use GTK+ 1.2.
G_BROKEN_FILENAMES 1 Used at runtime. Not only is this obsolete; it is useless if your locale uses UTF-8 encoding anyway.
PATH Will contain /opt/gnome/bin Used, of course, both at runtime and at compilation time. At runtime you may want the stock GNOME programs to be runnable. At compilation time, though, you almost certainly don't want the distribution's programs to run; instead you want the ones that jhbuild compiles.
PKG_CONFIG_PATH Will contain /opt/gnome/lib/pkgconfig Used at compilation time. You definitely don't want the .pc files from the distribution; you want the ones which get installed under jhbuild.

The changes you'll need to make to a stock jhbuild configuration refer to overriding the default environment variables to "clean" versions suitable for compilation.

Setting up jhbuild

Setting up jhbuild is easy; you just download it from the GNOME CVS repository and install it. Go to a directory where you'll be downloading things from CVS (for example, ~/cvs or ~/src and do the following (quoted from the jhbuild page):

$ cvs -d :pserver:anonymous@anoncvs.gnome.org:/cvs/gnome login
Logging in to :pserver:anonymous@anoncvs.gnome.org:2401/cvs/gnome
CVS password: <press enter>
$ cvs -d :pserver:anonymous@anoncvs.gnome.org:/cvs/gnome checkout jhbuild

Jhbuild can be installed to ~/bin (which should be in your $PATH) with the following commands:

$ cd jhbuild
$ make
$ make install

IMPORTANT: At this point you will need to set up your ~/.jhbuildrc file. This is what jhbuild uses to know where to put the sources it downloads from CVS, to know where to install things, and to know the particular compilation options that you want to use for each module. Jhbuild comes with a sample ~/.jhbuildrc, but it will not serve you very well under NLD.

Instead, put the following text into ~/.jhbuildrc, and change the lines that say CHANGEME:

# -*- mode: python -*-

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

# if you have a cvs account, uncomment this line
#cvsroots['gnome.org'] = 'CHANGEME@cvs.gnome.org:/cvs/gnome'

# what module set should be used.
moduleset = 'gnome-2.10'  # CHANGEME if you want another version

# A list of the modules to build.  Defaults to the Gnome Desktop and
# developer platform.
# CHANGEME: I always specify what I want to the jhbuild command line, rather than building
# this default:
# modules = [ 'meta-gnome-desktop' ]

# what directory should the source be checked out to?
checkoutroot = '/home/CHANGEME/cvs'

# the prefix to configure/install modules to (must have write access)
prefix = '/home/CHANGEME/gnome-install

# extra arguments to pass to all autogen.sh scripts
# to speed up builds of gnome2, try '--disable-static --disable-gtk-doc'
#autogenargs=''

# set CFLAGS:
os.environ['CFLAGS'] = '-Wall -g'

# 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.join(os.environ['HOME'],
                                     'bin', 'install-check')

# CHANGEME: I use these options, but you may want to change them
module_autogenargs['glib'] = '--enable-debug --enable-maintainer-mode --enable-gtk-doc'
module_autogenargs['pango'] = '--enable-debug --enable-maintainer-mode --enable-gtk-doc'
#module_autogenargs['gtk+'] = '--enable-debug --enable-maintainer-mode --disable-gtk-doc'
module_autogenargs['gtk+'] = '--enable-debug --enable-maintainer-mode --disable-man'
module_autogenargs['howl'] = ''
module_autogenargs['gstreamer'] = '--disable-docs-build'
module_autogenargs['dbus'] = '--disable-mono --disable-mono-docs'
module_autogenargs['hal'] = '--disable-docbook-docs'

### Remove SuSE-isms...
os.unsetenv("GNOME2_PATH")
os.environ["GNOME2_PATH"] = ""

os.unsetenv("ACLOCAL_FLAGS")
os.environ["ACLOCAL_FLAGS"] = ""

os.unsetenv("PKG_CONFIG_PATH")
os.environ["PKG_CONFIG_PATH"] = "/usr/lib/pkgconfig"

os.unsetenv("GTK_PATH")
os.environ["GTK_PATH"] = ""

os.unsetenv("GTK_RC_FILES")
os.environ["GTK_RC_FILES"] = ""

os.environ['UNDER_JHBUILD'] = 'true'

It is very important that you change the lines with CHANGEME in them!

IMPORTANT: At this point you will need to run this:

$ jhbuild bootstrap

This will take a little while, as jhbuild downloads and installs specific versions of the autoconf/automake/libtool trio of death and other goodies. Note that these will be installed under /home/CHANGEME/gnome-install or whatever you put in your ~/.jhbuildrc.

After that, you are ready to start building GNOME.

Building GNOME

If you just want to do a massive build of the whole desktop, do this:

$ jhbuild build meta-gnome-desktop

If errors occur, jhbuild will ask you for instructions. That's when you actually go and read jhbuild's documentation, although things will be pretty much self-explanatory.

Building the whole GNOME desktop takes a long time even on fast machines, so you can use this to get a very minimal desktop instead:

$ jhbuild build meta-gnome-core nautilus gnome-control-center metacity

If you change some of the module_autogenargs values in your ~/.jhbuildrc, or if any updated modules have changes to their autoconf files, you may need to use the -a option to jhbuild build. This makes jhbuild re-autogen the modules in question:

$ jhbuild build -a some_module

Running GNOME

Now that you built your desktop, how do you run it?

It depends. The most convenient thing to test a program quickly is to do this:

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

The jhbuild shell command drops you into a shell that has its environment set up to run programs from your /home/CHANGEME/gnome-install prefix. When you have many terminals open, it's useful to know whether you are inside a "normal" shell or a jhbuild shell. I use the following in my ~/.bashrc:

if [ x$UNDER_JHBUILD = x ]; then
    PS1='\u\$ '
else
    PS1='[jhbuild]\u\$ '
fi 

This way, my prompt becomes "[jhbuild]federico$" if I'm inside a jhbuild shell, whereas it would normally be "federico$". This is also why you see that "os.environ['UNDER_JHBUILD'] = 'true'" in the configuration file above.

Using a different user for testing

However, running individual programs like this has a few problems.

Those programs will use your existing GConf values from ~/.gconf. Most of the time this is a good thing, as you don't want to reconfigure everything for your spanking new version of GNOME. However, it is problematic if you want to test a "clean" environment where no configuration values have been set.

Also, you can have problems due to mismatched versions of the program you are running and the various daemons which it uses. For example, your regular user may be running an older version of gnome-vfs-daemon than the program expects.

The easiest solution is to create a different user account in your machine, which you will uses solely for testing purposes. My normal account is called "federico", and I use "devel" as the username for the testing account. So, go ahead and create a separate user account for testing.

Once you have a testing account, you should install jhbuild in it as well. Log in to the testing account, go to the directory where you downloaded jhbuild (/home/CHANGEME/cvs if you used the example above), and run make install again. This will copy the jhbuild scripts to /home/devel/bin or similar. Now copy ~user/.jbuildrc into ~devel/.jhbuildrc and make sure the variables in it make sense — they should point to the directories of your regular user.

Now you can do a few interesting things.