README

   1 Yet Another Gnome 2 Build Script
   2 ================================
   3
   4 This is another set of scripts for building GNOME 2.  They are still a
   5 little rough around the edges, but may still be useful to you.
   6
   7 They don't enforce any particular checkout, build or install
   8 directories for your gnome2 setup (this is deduced from the config
   9 file).
  10
  11 You must have python >= 2.3 installed for jhbuild to run.
  12
  13 Note that the included module sets build most software from CVS (or
  14 equivalent), so you may encounter occasional build failures.
  15
  16 If you want to build from released tarballs instead, some options
  17 include:
  18
  19  * use a jhbuild module set comprised of tarball releases:
  20      http://blogs.gnome.org/view/newren/2005/10/04/0
  21
  22  * use GARNOME: a GAR configuration for building Gnome from tarballs:
  23      http://www.gnome.org/projects/garnome/
  24
  25
  26 Why use jhbuild?
  27 ----------------
  28
  29 I wrote jhbuild because there were a few features missing from
  30 vicious-build-scripts that I wanted.  The main one is dependency
  31 handling.
  32
  33 With vicious-build-scripts, there is a list of modules that get built
  34 in order.  In contrast, jhbuild stores a list of modules along with
  35 their dependencies.  In the config file, you specify what modules you
  36 want to end up with, and it will work out what dependencies need to be
  37 built.
  38
  39 The other main feature of jhbuild is its error handling.  If an error
  40 occurs while building a module, you are given a number of options:
  41 rerun the build stage, start a shell, give up on the module, or ignore
  42 the error.  If you give up on the module, then jhbuild will not
  43 attempt to build any module that depends on it (taking into account
  44 transitive dependencies, as needed).  At the end of the build, a list
  45 of unbuilt modules is printed.
  46
  47 If you wish to run a non interactive build, you can pass the
  48 --no-interact option.
  49
  50
  51 Configuring
  52 -----------
  53
  54 To install the scripts run "make -f Makefile.plain install", and then copy
  55 sample.jhbuildrc to you home directory, rename it to .jhbuildrc
  56 and edit to match your setup.  My rc file is provided for reference as
  57 jamesh.jhbuildrc.
  58
  59 For people using vicious-build-scripts to build gnome 2.0, the
  60 vbs-head.jhbuildrc sample configuration file might be a good one to
  61 start with.
  62
  63 Before you can build packages from CVS, you will need to have various
  64 build tools installed.  Currently, these include:
  65   gettext >= 0.10.40
  66   libtool >= 1.5
  67   autoconf >= 2.58
  68   automake 1.4-p6
  69   automake 1.6.x
  70   automake 1.7.x
  71   automake 1.8.x
  72   pkg-config >= 0.14
  73   python >= 2.2
  74   audiofile
  75
  76 Some modules may be managed with Subversion or GNU Arch, so you will
  77 need those tools to build affected modules:
  78   subversion  http://subversion.tigris.org/
  79   bazaar      http://bazaar.canonical.com/ (an Arch implementation)
  80
  81 You can check whether the tools are available by running the following
  82 command:
  83   jhbuild sanitycheck
  84
  85 If any problems are reported, you have two options:
  86
  87 1) install packages from your distribution to satisfy the
  88    requirements.  You may need to pull some packages from the
  89    development branch of your distro (eg. for Red Hat 9 or Fedora Core
  90    1 you would need updated automake packages from
  91    rawhide/development).
  92
  93 2) Run jhbuild's bootstrap procedure to install all the build tools to
  94    your jhbuild installroot.  This can be done by running the
  95    following command:
  96      jhbuild bootstrap
  97
  98    Note that if you depend on m4 macros or pkg-config files in /usr,
  99    you might need to adjust ACLOCAL_FLAGS and PKG_CONFIG_PATH after
 100    running bootstrap.  This can be done by adding the following lines
 101    to your ~/.jhbuildrc file:
 102      addpath('ACLOCAL_FLAGS', '/usr/share/aclocal')
 103      addpath('PKG_CONFIG_PATH', '/usr/lib/pkgconfig')
 104
 105 After installing the required build tools, rerun sanitycheck to make
 106 sure everything is okay.
 107
 108 Bootstrapping should only need to be done once (unless the
 109 requirements of some package change).
 110
 111
 112 Using jhbuild
 113 -------------
 114
 115 To build everything, just type 'jhbuild build', or just 'jhbuild'.
 116 Some useful options that this command takes include:
 117
 118   --autogen          always run autogen.sh
 119   --clean            run "make clean" before make when building
 120   --no-network       don't update source from cvs
 121   --skip=MODULES     skip building the given modules
 122   --start-at=MODULE  start building at the given module
 123
 124 If you just want to checkout the latest versions of everything, run:
 125   jhbuild update
 126
 127 If you want to build everything without updating from CVS (for
 128 instance, when disconnected from the internet), use the following
 129 command:
 130   jhbuild build --no-network
 131
 132 (this command takes the same options as 'jhbuild build').
 133
 134 If you want to run a command in the build environment (PATH,
 135 LD_LIBRARY_PATH, etc all configured), use the following command:
 136   jhbuild run program
 137
 138 For example, to start a shell in the build environment:
 139   jhbuild run bash
 140
 141 To build a single module with no dependencies, use the following
 142 command:
 143   jhbuild buildone modulename
 144
 145 (this command takes the same extra options as 'jhbuild build').
 146
 147 To run an unattended build and create a status page showing the
 148 results of building each package:
 149   jhbuild tinderbox --output=/dir/to/store/build/logs
 150
 151 (this command takes the same extra options as 'jhbuild build').
 152
 153 For details of all jbhuild's command line options:
 154   jhbuild --help
 155
 156
 157 Error handling
 158 --------------
 159
 160 When an error is encountered while building, you will be given a
 161 chance to fix the problem.  You can choose to rerun that part of the
 162 build, start a shell to give you a chance to fix things, give up on
 163 the module all together, or ignore the error (useful for certain cvs
 164 errors).
 165
 166 If you give up on building a module, all modules that depend on it
 167 will be skipped.  If you would prefer the build not to ask questions
 168 on errors, you can pass the --no-interact switch, which is equivalent
 169 to always choosing give up.
 170
 171
 172 Module info
 173 -----------
 174
 175 Information about how to build the modules is contained in the
 176 moduleinfo.py file.  This file needs to be modified when dependencies
 177 between modules change (usually, no change to the ~/.jhbuildrc will be
 178 needed).
 179
 180
 181 Running Gnome
 182 --------------
 183
 184 Once you have built Gnome with jhbuild you need a way to start it:
 185
 186 If you use GDM to log into Gnome you need to create a session file in
 187 /usr/share/xsessions/ (directory may be different on non-redhat systems).
 188 Call it 'jhbuild.desktop' and make it executable. Then add the lines:
 189
 190 [Desktop Entry]
 191 Encoding=UTF-8
 192 Name=Gnome-cvs
 193 Comment=This session logs you into Gnome-cvs
 194 Exec=jhbuild run gnome-session
 195 Type=Application
 196
 197 In order to have the name & comment show up in your native language, you will
 198 have to add lines similar to the following:
 199
 200 Name[es]=Gnome-cvs
 201 Comment[es]=Con esta sesiÃ³n accede a gnome-cvs
 202
 203 If you use startx to run gnome just add 'exec jhbuild run gnome-session'
 204 to your ~/.xinitrc
 205
 206
 207 Reporting Bugs
 208 --------------
 209
 210 If you find any bugs in jhbuild, or have feature requests (or
 211 implementations :), please file them in bugzilla at:
 212
 213   http://bugzilla.gnome.org/enter_bug.cgi?product=jhbuild
 214
 215 This will make sure I don't lose your request.