Getting your system ready

First, go to JhbuildDependencies, find your distribution and run the apt or yum command to make sure that you have all the required dependencies. Do this even if you've gotten jhbuild working in the past, since installing missing dependencies while running jhbuild will slow you way, way down.

Starting from scratch

The following assumes that you want to install everything in the directory od/ in your home directory.

mkdir ~/od
cd ~/od
mkdir checkout
mkdir install
mkdir -p install/var/lib/dbus
ln -s /var/lib/dbus/machine-id install/var/lib/dbus

First, get jhbuild and install jhbuild. (Installation just copies files into your ~/bin; it doesn't do a system install).

cd ~/od
svn co http://svn.gnome.org/svn/jhbuild/trunk jhbuild
cd jhbuild
./autogen.sh --prefix=/home/[YOUR USERNAME]/od/install ; make ; make install

Then create a file ~/.jhbuildrc with contents:

# -*- mode: python -*-

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

moduleset = 'online-desktop'

modules = [ 'meta-online-desktop' ]

# This will take a long time, and conflicts with the jhbuild cairo
skip = ['mozilla']

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

# the prefix to configure/install modules to (must have write access)
prefix = os.path.expanduser('~/od/install')

# Use system libraries for the builds
addpath('PKG_CONFIG_PATH', os.path.join(os.sep, 'usr', 'lib', 'pkgconfig'))
addpath('PKG_CONFIG_PATH', os.path.join(os.sep, 'usr', 'share', 'pkgconfig'))

# Look in /usr/share for icons, D-BUS service files, etc
addpath('XDG_DATA_DIRS', '/usr/share')
# Look in /etc/xdg for system-global autostart files
addpath('XDG_CONFIG_DIRS', '/etc/xdg')

# We need to add the gtk-2.0 directory explicitly to the Python path since '.pth'
# files (here pygtk.pth) only work properly in system directories
import os
import sys
pythonversion = 'python' + str(sys.version_info[0]) + '.' + str(sys.version_info[1])
if use_lib64:
    pythonpath = os.path.join(prefix, 'lib64', pythonversion, 'site-packages', 'gtk-2.0')
else:
    pythonpath = os.path.join(prefix, 'lib', pythonversion, 'site-packages', 'gtk-2.0')
addpath('PYTHONPATH', pythonpath)

# Rebuild faster
os.environ['INSTALL'] = os.path.expanduser('~/bin/install-check')

# Use the standard system bus
os.environ['DBUS_SYSTEM_BUS_ADDRESS'] = 'unix:path=/var/run/dbus/system_bus_socket'

# Enable gtk-doc deneration for online-desktop module 
module_autogenargs['online-desktop'] = '--enable-gtk-doc'

Adapting your existing JHBuild

If you are already using jhbuild, you have two choices; either you can adapt your existing jhbuild configuration to use the online-desktop moduleset and add any other missing necessary lines from the above (make sure that you have the XDG_DATA_DIRS and DBUS_SYSTEM_BUS_ADDRESS lines in particular). Or you could create a separate ~/.jhbuild-od with the contents above and add a shell alias:

alias odbuild="jhbuild -f $HOME/.jhbuild-od"

Building

jhbuild build -a meta-online-desktop

If you stop the compilation for any problem you can resume it with the -t argument and module to restart the compilation, for example:

jhbuild build -a meta-online-desktop -t pyorbit

Will build just the "minimal" packages for the online-desktop (92 or so packages). Or:

jhbuild build -a meta-online-desktop meta-gnome-desktop

For a more comprehensive build of most of GNOME. You don't need the -a after the initial time, but one or two of the packages (the mugshot client in particular) need to be bootstrapped using the explicit -a.

If you have any problem during compilation you can go to JhbuildIssues and, perhaps, you can find a solution to solve your problems.

After your first build

You need to change some configuration to make the installed build interoperate more seamlessly with your system applications. Edit ~/od/install/etc/bonobo-activation/bonobo-activation-config.xml and inside <searchpath/> add the lines:

<item>/home/[YOUR USERNAME]/od/install/lib/bonobo/servers</item>
<item>/usr/lib/bonobo/servers</item>

replacing [YOUR USERNAME] with your user name. This allows system-installed applications to correctly launch their Bonobo components. (In particular, system-installed Evolution won't work without this step.)

Also edit ~/od/install/etc/gconf/2/path and add at the very end:

xml:readonly:/etc/gconf/gconf.xml.defaults

This will allow system-installed applications to find their correct default GConf preferences.

[Possible improvement to instructions: suggest creating these file as a setup step with the complete contents]

To get the Pidgin integration for the Online Desktop working, you need to convince the system Pidgin application to find the "DBUS API Plugin" that the online-desktop JHBuild has installed. To do this, run the commands:

$ mkdir -p ~/.purple/plugins
$ ln -s ~/od/install/lib/pidgin/libdbus-api-plugin.so ~/.purple/plugins/

After your first login

Change the default browser to Firefox:

gconftool-2 -s -t string /desktop/gnome/url-handlers/http/command "firefox %s"
gconftool-2 -s -t string /desktop/gnome/url-handlers/https/command "firefox %s"

Build Failures?

Build failures are probably due to missing dependencies. Each distro needs development packages installed Check that you have the proper packages installed with JhbuildDependencies and then see JhbuildIssues for module-by-module tips. Eventually, jhbuild will be modified to detect these and alert you about them before starting the build.

You may need to turn off -Werror for some modules to avoid getting errors like "error: dereferencing type-punned pointer will break strict-aliasing rules". Add the following for each module at the bottom of your .jhbuildrc file for that:

module_autogenargs['<module_name>'] = '--disable-more-warnings'

At the moment, this option needed to be added for gnome-vfs, gnome-keyring, and eel modules. You need to restart jhbuild each time .jhbuildrc is modified and you can use -t option to pass in the module name with which to restart the compilation.

When you encounter errors about failed svn operations on locally modified directories, it's easiest to delete the whole modules and let jhbuild do a fresh checkout.

Logging in to the desktop

To enable logging into the desktop from your system build install of GDM, create /usr/local/bin/run-online-desktop with the following contents:

if [ -x $HOME/bin/jhbuild ] ; then
   exec $HOME/bin/jhbuild run dbus-launch --exit-with-session od-session
else
   zenity --error --text="No JHBuild session found for user $USER"
   exit 1
fi

And make it executable:

chmod a+x /usr/local/bin/run-online-desktop

And then create /etc/X11/sessions/online-desktop-jhbuild.desktop with the following contents (this file could also be in the /usr/share/gdm/BuiltInSessions directory)

(Note: In Ubuntu 7.10, the /etc/X11sessions directory does not exist, and you need to create it first)

[Desktop Entry]
Encoding=UTF-8
Name=Online Desktop (JHBuild)
Comment=JHBuild of Online Desktop
Exec=/usr/local/bin/run-online-desktop
Icon=
Type=Application

Then if you log out, you can select the Online Desktop session from GDM before logging in again. The details of this will depend on your GDM configuration; under Fedora, click on Options, the "Select Session..."

Testing as another user

You may find it convenient to jhbuild as your main user, but actually run the built software as a secondary user. Here's how to do that.

TESTUSERNAME=testuser
sudo mkdir -p /home/${TESTUSERNAME}/bin 
sudo chown ${TESTUSERNAME}: /home/
sudo cp /home/mainuser/bin/jhbuild /home/${TESTUSERNAME}/bin/jhbuild
sudo chmod a+x /home/${TESTUSERNAME}/bin/jhbuild

Note if you built into ~/od as the default instructions say to do (I personally use /src), then you will need to ensure that the test user has access to that path. For example this should work:

setfacl -m u:${TESTUSERNAME}:rX ~
setfacl -m -d u:${TESTUSERNAME}:r ~/od