Yet Another Gnome 2 Build Script
================================

This is another set of scripts for building GNOME 2.  They are still a
little rough around the edges, but may still be useful to you.

They don't enforce any particular checkout, build or install
directories for your gnome2 setup (this is deduced from the config
file).

You must have python >= 2.2 installed for jhbuild to run.

Note that the included module sets build most software from CVS (or
equivalent), so you may encounter occasional build failures.

If you want to build from released tarballs instead, some options
include:

 * use a jhbuild module set comprised of tarball releases:
     http://blogs.gnome.org/view/newren/2005/10/04/0

 * use GARNOME: a GAR configuration for building Gnome from tarballs:
     http://www.gnome.org/projects/garnome/


Why use jhbuild?
----------------

I wrote jhbuild because there were a few features missing from
vicious-build-scripts that I wanted.  The main one is dependency
handling.

With vicious-build-scripts, there is a list of modules that get built
in order.  In contrast, jhbuild stores a list of modules along with
their dependencies.  In the config file, you specify what modules you
want to end up with, and it will work out what dependencies need to be
built.

The other main feature of jhbuild is its error handling.  If an error
occurs while building a module, you are given a number of options:
rerun the build stage, start a shell, give up on the module, or ignore
the error.  If you give up on the module, then jhbuild will not
attempt to build any module that depends on it (taking into account
transitive dependencies, as needed).  At the end of the build, a list
of unbuilt modules is printed.

If you wish to run a non interactive build, you can pass the
--no-interact option.


Configuring
-----------

To install the scripts run "make install", and then copy
sample.jhbuildrc to you home directory, rename it to .jhbuildrc 
and edit to match your setup.  My rc file is provided for reference as 
jamesh.jhbuildrc.

For people using vicious-build-scripts to build gnome 2.0, the
vbs-head.jhbuildrc sample configuration file might be a good one to
start with.

Before you can build packages from CVS, you will need to have various
build tools installed.  Currently, these include:
  gettext >= 0.10.40
  libtool >= 1.5
  autoconf >= 2.58
  automake 1.4-p6
  automake 1.6.x
  automake 1.7.x
  automake 1.8.x
  pkg-config >= 0.14
  python >= 2.2
  audiofile

Some modules may be managed with Subversion or GNU Arch, so you will
need those tools to build affected modules:
  subversion  http://subversion.tigris.org/
  bazaar      http://bazaar.canonical.com/ (an Arch implementation)

You can check whether the tools are available by running the following
command:
  jhbuild sanitycheck

If any problems are reported, you have two options:

1) install packages from your distribution to satisfy the
   requirements.  You may need to pull some packages from the
   development branch of your distro (eg. for Red Hat 9 or Fedora Core
   1 you would need updated automake packages from
   rawhide/development).

2) Run jhbuild's bootstrap procedure to install all the build tools to
   your jhbuild installroot.  This can be done by running the
   following command:
     jhbuild bootstrap

   Note that if you depend on m4 macros or pkg-config files in /usr,
   you might need to adjust ACLOCAL_FLAGS and PKG_CONFIG_PATH after
   running bootstrap.  This can be done by adding the following lines
   to your ~/.jhbuildrc file:
     addpath('ACLOCAL_FLAGS', '/usr/share/aclocal')
     addpath('PKG_CONFIG_PATH', '/usr/lib/pkgconfig')

After installing the required build tools, rerun sanitycheck to make
sure everything is okay.

Bootstrapping should only need to be done once (unless the
requirements of some package change).


Using jhbuild
-------------

To build everything, just type 'jhbuild build', or just 'jhbuild'.
Some useful options that this command takes include:

  --autogen          always run autogen.sh
  --clean            run "make clean" before make when building
  --no-network       don't update source from cvs
  --skip=MODULES     skip building the given modules
  --start-at=MODULE  start building at the given module

If you just want to checkout the latest versions of everything, run:
  jhbuild update

If you want to build everything without updating from CVS (for
instance, when disconnected from the internet), use the following
command:
  jhbuild build --no-network

(this command takes the same options as 'jhbuild build').

If you want to run a command in the build environment (PATH,
LD_LIBRARY_PATH, etc all configured), use the following command:
  jhbuild run program

For example, to start a shell in the build environment:
  jhbuild run bash

To build a single module with no dependencies, use the following
command:
  jhbuild buildone modulename

(this command takes the same extra options as 'jhbuild build').

To run an unattended build and create a status page showing the
results of building each package:
  jhbuild tinderbox --output=/dir/to/store/build/logs

(this command takes the same extra options as 'jhbuild build').

For details of all jbhuild's command line options:
  jhbuild --help


Error handling
--------------

When an error is encountered while building, you will be given a
chance to fix the problem.  You can choose to rerun that part of the
build, start a shell to give you a chance to fix things, give up on
the module all together, or ignore the error (useful for certain cvs
errors).

If you give up on building a module, all modules that depend on it
will be skipped.  If you would prefer the build not to ask questions
on errors, you can pass the --no-interact switch, which is equivalent
to always choosing give up.


Module info
-----------

Information about how to build the modules is contained in the
moduleinfo.py file.  This file needs to be modified when dependencies
between modules change (usually, no change to the ~/.jhbuildrc will be
needed).


Running Gnome
--------------

Once you have built Gnome with jhbuild you need a way to start it:

If you use GDM to log into Gnome you need to create a session file in
/usr/share/xsessions/ (directory may be different on non-redhat systems). 
Call it 'jhbuild.desktop' and make it executable. Then add the lines:

[Desktop Entry]
Encoding=UTF-8
Name=Gnome-cvs
Comment=This session logs you into Gnome-cvs
Exec=jhbuild run gnome-session
Type=Application

In order to have the name & comment show up in your native language, you will
have to add lines similar to the following:

Name[es]=Gnome-cvs
Comment[es]=Con esta sesión accede a gnome-cvs

If you use startx to run gnome just add 'exec jhbuild run gnome-session'
to your ~/.xinitrc


Reporting Bugs
--------------

If you find any bugs in jhbuild, or have feature requests (or
implementations :), please file them in bugzilla at:

  http://bugzilla.gnome.org/enter_bug.cgi?product=jhbuild

This will make sure I don't lose your request.