doc/C/jhbuild.xml

   1 <?xml version="1.0" standalone="no"?><!--*- mode: nxml -*-->
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3     "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- process to HTML with: xmlto xhtml-nochunks -m custom.xsl jhbuild.xml -->
   5 <article id="index">
   6   <articleinfo>
   7     <title>JHBuild Manual</title>
   8     <authorgroup>
   9       <author role="maintainer">
  10         <firstname>James</firstname>
  11         <surname>Henstridge</surname>
  12       </author>
  13       <author>
  14         <firstname>C.J.</firstname>
  15         <surname>Adams-Collier</surname>
  16       </author>
  17       <author>
  18         <firstname>Frederic</firstname>
  19         <surname>Peters</surname>
  20       </author>
  21       <author>
  22         <firstname>David</firstname>
  23         <surname>Turner</surname>
  24       </author>
  25     </authorgroup>
  26     <copyright>
  27       <year>2004, 2008</year>
  28       <holder>James Henstridge</holder>
  29     </copyright>
  30
  31     <revhistory>
  32       <revision>
  33         <revnumber>JHBuild Manual v0.5</revnumber>
  34         <date>January 2008</date>
  35       </revision>
  36       <revision>
  37         <revnumber>JHBuild Manual v0.1</revnumber>
  38         <date>August 2007</date>
  39       </revision>
  40     </revhistory>
  41
  42     <abstract role="description">
  43       <para>JHBuild is a tool used to build the whole GNOME desktop
  44       from the version control system. JHBuild can also be customized
  45       to build other projects too.</para>
  46     </abstract>
  47   </articleinfo>
  48
  49   <section id="introduction">
  50     <title>Introduction</title>
  51
  52     <para>JHBuild is a tool designed to ease building collections of
  53     source packages, called <quote>modules</quote>.  JHBuild uses
  54     <quote>module set</quote> files to describe the modules available
  55     to build. The <quote>module set</quote> files include dependency
  56     information that allows JHBuild to discover what modules need to be
  57     built and in what order.</para>
  58
  59     <para>JHBuild was originally written for building <ulink
  60     url="http://www.gnome.org">GNOME</ulink>, but has since been
  61     extended to be usable with other projects.  A <quote>module
  62     set</quote> file can be hosted on a web server, allowing for build
  63     rules independent of the JHBuild project.</para>
  64
  65     <para>JHBuild can build modules from a variety of sources,
  66     including
  67     <ulink url="http://www.cvshome.org/">CVS</ulink>,
  68     <ulink url="http://subversion.tigris.org/">Subversion,</ulink>
  69     <ulink url="http://wiki.gnuarch.org/">Arch</ulink>,
  70     <ulink url="http://www.bazaar-vcs.org/">Bazaar</ulink>,
  71     <ulink url="http://darcs.net/">Darcs</ulink>,
  72     <ulink url="http://git.or.cz/">Git</ulink> and
  73     <ulink url="http://www.selenic.com/mercurial/">Mercurial</ulink>
  74     repositories, as well as Tar and Zip archives hosted on web or FTP
  75     sites. JHBuild can build modules using a variety of build systems,
  76     including Autotools, CMake, WAF, Ant, Python Distutils and Perl
  77     Makefiles.</para>
  78
  79     <para>JHBuild is not intended as a replacement for the
  80     distribution's package management system.  Instead, it makes it
  81     easy to build software into a separate install prefix without
  82     interfering with the rest of the system.</para>
  83
  84   </section>
  85
  86   <section id="getting-started">
  87     <title>Getting Started</title>
  88
  89     <para>JHBuild requires a few set up steps to be run before building
  90     software.  JHBuild requires some prerequisite software, and it is
  91     necessary to install prerequisite tools needed to obtain and build
  92     the software modules.</para>
  93
  94     <section id="getting-started-install">
  95       <title>Installing JHBuild</title>
  96
  97       <para>Before downloading JHBuild, verify a copy of Python
  98       &gt;= 2.0 is installed.  It is essential that the Expat XML
  99       parser extension is installed. Expat XML is supplied with Python
 100       &gt;= 2.3. To verify Expat XML is installed run the following
 101       commands:</para>
 102
 103       <screen><prompt>#</prompt> <userinput>python</userinput>
 104 Python 2.6.2+ (release26-maint, Sep 13 2009, 21:26:06)
 105 [GCC 4.4.1] on linux2
 106 Type "help", "copyright", "credits" or "license" for more information.
 107 <prompt>&gt;&gt;&gt;</prompt> <userinput>import xml.parsers.expat</userinput>
 108 <prompt>&gt;&gt;&gt;</prompt></screen>
 109
 110       <para>If the above completes without an exception, then Expat
 111       XML is installed correctly.</para>
 112
 113       <para>The only way to download JHBuild is via the version control
 114       system, <command>git</command>.  This can be achieved with the
 115       following command.  It is recommended to run the command from a
 116       new directory where all source code will be installed, for
 117       example, <filename>~/checkout/gnome2</filename>.</para>
 118
 119       <screen><prompt>$</prompt> <userinput>git clone git://git.gnome.org/jhbuild</userinput>
 120 <computeroutput>...</computeroutput>
 121 <prompt>$</prompt></screen>
 122
 123       <para>This will download JHBuild into a new folder named
 124       <filename>jhbuild</filename> under the current
 125       directory.  Now to build and install JHBuild:</para>
 126
 127       <screen><prompt>$</prompt> <userinput>cd jhbuild</userinput>
 128 <prompt>$</prompt> <userinput>./autogen.sh</userinput>
 129 <computeroutput>...</computeroutput>
 130 <prompt>$</prompt> <userinput>make</userinput>
 131 <computeroutput>...</computeroutput>
 132 <prompt>$</prompt> <userinput>make install</userinput>
 133 <computeroutput>...</computeroutput>
 134 <prompt>$</prompt></screen>
 135
 136       <para>Alternatively, if autotools or gnome-doc-utils is not
 137       installed, install JHBuild as follows:</para>
 138
 139       <screen><prompt>$</prompt> <userinput>cd jhbuild</userinput>
 140 <prompt>$</prompt> <userinput>make -f Makefile.plain</userinput>
 141 <computeroutput>...</computeroutput>
 142 <prompt>$</prompt> <userinput>make -f Makefile.plain install</userinput>
 143 <computeroutput>...</computeroutput>
 144 <prompt>$</prompt></screen>
 145
 146       <para>If the above steps complete successfully, a small shell
 147       script will be installed in <filename>~/.local/bin</filename> to
 148       start JHBuild.  Add <filename>~/.local/bin</filename> to the
 149       <envar>PATH</envar>:</para>
 150
 151 <screen><prompt>$</prompt> <userinput>PATH=$PATH:~/.local/bin</userinput>
 152 <prompt>$</prompt></screen>
 153
 154       <para>To permanently add <filename>~/.local/bin</filename>
 155       to the <envar>PATH</envar> variable, run the following command:
 156       </para>
 157
 158 <screen>
 159 <prompt>$</prompt> <userinput>echo PATH=$PATH:~/.local/bin >> ~/.bashrc</userinput>
 160 <prompt>$</prompt></screen>
 161
 162       <para>Before running JHBuild, it is necessary to set up a
 163       configuration file located at <filename>~/.jhbuildrc</filename>.
 164       </para>
 165
 166     </section>
 167
 168     <section id="getting-started-configure">
 169       <title>Configuring JHBuild</title>
 170
 171       <para>The <filename>~/.jhbuildrc</filename> file uses Python
 172       syntax to set configuration variables for JHBuild.  An example is
 173       provided within the jhbuild directory, see
 174       <filename>sample.jhbuildrc</filename>. Copy
 175       <filename>sample.jhbuildrc</filename> to
 176       <filename>~/.jhbuildrc</filename> and customize as required.
 177       </para>
 178
 179       <para>The sample configuration will make JHBuild build the
 180       <application>meta-gnome-desktop</application> module and its
 181       dependencies from the <systemitem>gnome-2.30</systemitem> module
 182       set.  JHBuild will unpack source trees to
 183       <filename>~/checkout/gnome2</filename> and install all files to
 184       subdirectories of <filename>/opt/gnome2</filename>. The two
 185       directories must be writable.</para>
 186
 187       <para>Configuration variables are documented in <xref
 188       linkend="config-reference"/>. The most commonly used
 189       variables are:</para>
 190
 191       <variablelist>
 192         <?dbhtml list-presentation="table"?>
 193         <varlistentry>
 194           <term><link linkend="cfg-repos"><varname>repos</varname></link></term>
 195           <listitem>
 196                 <simpara>A dictionary that can be used to specify an alternative
 197                 repository location for a particular repository. This configuration
 198                 variable is useful to a module developer. By default, JHBuild will
 199                 check out code from repositories using an anonymous repository
 200                 location. The dictionary keys are short repository names and the
 201                 values are alternative repository location strings. For example:
 202                 </simpara>
 203         <programlisting>repos['git.gnome.org'] = 'ssh://<replaceable>username</replaceable>@git.gnome.org/git/'</programlisting>
 204           </listitem>
 205         </varlistentry>
 206         <varlistentry>
 207           <term><link linkend="cfg-moduleset"><varname>moduleset</varname></link></term>
 208           <listitem>
 209             <simpara>A string or list of strings specifying the name(s) of
 210             the module set(s) to use.  This can either be the filename of
 211             a moduleset included with JHBuild (excluding the path and
 212             extension), or a full HTTP URL to an externally managed
 213         moduleset.  HTTP URL modulesets are cached locally.  If a
 214         module with the same name is present in more than one
 215         moduleset, the last set listed takes priority. Modulesets
 216         provided with JHBuild are updated to match the current GNOME
 217         development release.</simpara>
 218           </listitem>
 219         </varlistentry>
 220         <varlistentry>
 221           <term><link linkend="cfg-modules"><varname>modules</varname></link></term>
 222           <listitem>
 223             <simpara>A list of strings specifying the modules to
 224             build.  The list of modules actually built will be
 225             recursively expanded to include all the dependencies
 226             unless the
 227         <link linkend="command-reference-buildone">
 228         <command>buildone</command></link> command is used.
 229         Defaults to <literal>['meta-gnome-desktop']</literal>.
 230         </simpara>
 231           </listitem>
 232         </varlistentry>
 233         <varlistentry>
 234           <term><link linkend="cfg-checkoutroot"><varname>checkoutroot</varname></link></term>
 235           <listitem>
 236             <simpara>A string specifying the directory to unpack source
 237             trees to.  Unless <link linkend="cfg-buildroot">
 238         <varname>buildroot</varname></link> is set, builds will occur
 239         in this directory too.  Defaults to
 240             <filename>~/checkout/gnome2</filename>.</simpara>
 241           </listitem>
 242         </varlistentry>
 243         <varlistentry>
 244           <term><link linkend="cfg-prefix"><varname>prefix</varname></link></term>
 245           <listitem>
 246             <simpara>A string specifying the prefix to install modules to.
 247             This directory must be writable.   Defaults to
 248             <literal>'/opt/gnome2'</literal>.</simpara>
 249           </listitem>
 250         </varlistentry>
 251         <varlistentry>
 252           <term><link linkend="cfg-autogenargs"><varname>autogenargs</varname></link></term>
 253           <listitem>
 254             <simpara>A string containing arguments passed to the
 255             <command>autogen.sh</command> script of all modules.  Can
 256             be overridden for particular modules using the
 257             <link linkend="cfg-module-autogenargs">
 258         <varname>module_autogenargs</varname></link> dictionary.
 259         </simpara>
 260           </listitem>
 261         </varlistentry>
 262         <varlistentry>
 263           <term><link linkend="cfg-makeargs"><varname>makeargs</varname></link></term>
 264           <listitem>
 265             <simpara>A string listing additional arguments to be
 266             passed to <command>make</command>.  Defaults to
 267             <literal>''</literal>.</simpara>
 268           </listitem>
 269         </varlistentry>
 270       </variablelist>
 271     </section>
 272
 273     <section id="getting-started-bootstrap">
 274       <title>Build Prerequisites</title>
 275
 276       <para>Before any modules can be built, it is necessary to have
 277       certain build tools installed.  Common build tools include the GNU
 278       Autotools (<application>autoconf</application>,
 279       <application>automake</application>,
 280       <application>libtool</application> and
 281       <application>gettext</application>), The GNU Toolchain
 282       (<application>binutils</application>,
 283       <application>gcc</application>,
 284       <application>g++</application>), pkg-config and
 285       Python, depending on which modules will be built.</para>
 286
 287       <para>JHBuild can check the tools are installed using the
 288       <command>sanitycheck</command> command:</para>
 289
 290       <screen><prompt>$</prompt> <userinput>jhbuild sanitycheck</userinput></screen>
 291
 292       <para>If this command displays any messages, the errors can be
 293       fixed in one of two ways:</para>
 294
 295       <orderedlist>
 296         <listitem>
 297           <simpara>Install the required package from your distribution's
 298           repository.  A list of <ulink
 299       url="http://live.gnome.org/JhbuildDependencies">package names</ulink>
 300       for different distributions is maintained on the GNOME wiki.
 301           Run the <command>sanitycheck</command> command again after
 302       installing the distribution's packages to ensure the required
 303       tools are present.</simpara>
 304         </listitem>
 305         <listitem>
 306           <simpara>Run the <command>bootstrap</command> command to
 307           download, build and install the build prerequisites:</simpara>
 308       <screen><prompt>$</prompt> <userinput>jhbuild bootstrap</userinput></screen>
 309       <para>When complete, run the
 310       <command>sanitycheck</command> command to verify the required
 311       tools are present.</para>
 312
 313       <note>
 314             <para>The <command>bootstrap</command> command does not build
 315             all the package dependencies required by the build tools.  If
 316         your distribution does not provide the required packages, they
 317         will need to be built outside of the JHBuild environment.
 318         </para>
 319
 320             <para>The build tools dependencies include
 321             <application>m4</application>, <application>perl</application>
 322             and a C compiler (for example, <application>gcc</application>).
 323         </para>
 324       </note>
 325
 326         </listitem>
 327       </orderedlist>
 328     </section>
 329
 330     <section id="getting-started-use">
 331       <title>Using JHBuild</title>
 332
 333       <para>After set up is complete, JHBuild can be used to build
 334       software.  To build all the modules selected in the
 335       <filename>~/.jhbuildrc</filename> file, run the following command:</para>
 336
 337       <screen><prompt>$</prompt> <userinput>jhbuild build</userinput></screen>
 338
 339       <para>JHBuild will download, configure, compile and install each
 340       of the modules.  If an error occurs at any stage, JHBuild will
 341       present a menu asking what to do.  The choices include dropping
 342       to a shell to fix the error, rerunning the build from various
 343       stages, giving up on the module, or ignore the error and
 344       continue.</para>
 345
 346       <note><simpara>Giving up on a module will cause any
 347       modules depending on the module to fail.</simpara></note>
 348
 349       <para>Below is an example of the menu displayed:</para>
 350 <screen>  [1] Rerun phase build
 351   [2] Ignore error and continue to install
 352   [3] Give up on module
 353   [4] Start shell
 354   [5] Reload configuration
 355   [6] Go to phase "wipe directory and start over"
 356   [7] Go to phase "configure"
 357   [8] Go to phase "clean"
 358   [9] Go to phase "distclean"
 359 <prompt>choice:</prompt> </screen>
 360
 361       <para>It is also possible to build a different set of modules
 362       and their dependencies by passing the module names as arguments
 363       to the <command>build</command> command. For example, to build
 364       gtk+:</para>
 365
 366       <screen><prompt>$</prompt> <userinput>jhbuild build gtk+</userinput></screen>
 367
 368       <para>If JHBuild is cancelled part way through a build, it is
 369       possible to resume the build at a particular module using the
 370       <option>--start-at</option> option:</para>
 371
 372       <screen><prompt>$</prompt> <userinput>jhbuild build --start-at=pango</userinput></screen>
 373
 374       <para>To build one or more modules, ignoring their dependencies,
 375       JHBuild provides the <command>buildone</command> command.  For the
 376       <command>buildone</command> command to complete successfully,
 377       all dependencies must be previously built and installed or provided
 378       by distribution packages.</para>
 379
 380       <screen><prompt>$</prompt> <userinput>jhbuild buildone gtk+</userinput></screen>
 381
 382       <para>To get a list of the modules and dependencies JHBuild will
 383       build, and the order they will be built, use the
 384       <command>list</command> command:</para>
 385
 386       <screen><prompt>$</prompt> <userinput>jhbuild list</userinput></screen>
 387
 388       <para>To get information about a particular module, use the
 389       <command>info</command> command:</para>
 390
 391       <screen><prompt>$</prompt> <userinput>jhbuild info gtk+</userinput></screen>
 392
 393       <para>To download or update all the software sources without
 394       building, use the <command>update</command> command. The
 395       <command>update</command> command provides an opportunity to
 396       modify the sources before building and can be useful if
 397       internet bandwidth varies.</para>
 398
 399       <screen><prompt>$</prompt> <userinput>jhbuild update</userinput></screen>
 400
 401       <para>Later, JHBuild can build everything without downloading or
 402       updating the sources:</para>
 403
 404       <screen><prompt>$</prompt> <userinput>jhbuild build --no-network</userinput></screen>
 405
 406       <para>To run a particular command with the same environment used
 407       by JHBuild, use the <command>run</command> command:</para>
 408
 409       <screen><prompt>$</prompt> <userinput>jhbuild run <replaceable>program</replaceable></userinput></screen>
 410
 411       <para>To start a shell with the same environment used by JHBuild,
 412       use the <command>shell</command> command:</para>
 413
 414       <screen><prompt>$</prompt> <userinput>jhbuild shell</userinput></screen>
 415
 416     </section>
 417   </section>
 418
 419   <section id="buildbot-integration">
 420     <title>Buildbot Integration</title>
 421
 422     <para>
 423       Coupled with the <ulink url="http://buildbot.net">Buildbot</ulink>
 424       project, JHBuild can also function as a continuous integration
 425       tool.  The Buildbot configuration is used by the GNOME project at
 426       <ulink url="http://build.gnome.org">build.gnome.org</ulink>.
 427     </para>
 428
 429     <section id="buildbot-slave">
 430       <title>Configuring a Buildbot Slave</title>
 431
 432       <para>
 433         A Buildbot slave is a variation of a normal JHBuild installation
 434             that serves the requests of a Buildbot master.  It is recommended
 435         to set up JHBuild and complete a build with most modules
 436         building successfully before adding the Buildbot customizations.
 437       </para>
 438
 439       <para>
 440         Buildbot commands are options to the
 441             <command>bot</command> command. To download and install the
 442         extra required software, run the following command:
 443       </para>
 444
 445       <screen><prompt>$</prompt> <userinput>jhbuild bot --setup</userinput></screen>
 446
 447       <para>
 448         Once this step has completed successfully, three new
 449             configuration variables are required in <filename>~/.jhbuildrc</filename>.
 450       </para>
 451
 452       <note>
 453         <para>
 454               It is not possible to use an alternate configuration file,
 455               the <link linkend="option-file"><option>--file</option></link>
 456           will not get desired effects.
 457             </para>
 458       </note>
 459
 460       <programlisting>
 461 jhbuildbot_master = 'build.gnome.org:9070'
 462 jhbuildbot_slavename = 'slavename'
 463 jhbuildbot_password = 'password'
 464 </programlisting>
 465
 466       <para>
 467         <varname>jhbuildbot_master</varname> is a string specifying the
 468         Buildbot master server; it defaults to
 469         <literal>'build.gnome.org:9070'</literal>.
 470         <varname>jhbuildbot_slavename</varname> and
 471         <varname>jhbuildbot_password</varname> identify the slave on the
 472         master server. Contact the Buildbot master administrators to
 473         obtain the slave name and password.
 474       </para>
 475
 476       <note>
 477         <para>
 478           The administrators of <ulink
 479           url="http://build.gnome.org">build.gnome.org</ulink>
 480           can be reached on the <ulink
 481           url="mailto:build-brigade-list@gnome.org">Build Brigade mailing
 482           list</ulink>.
 483         </para>
 484       </note>
 485
 486     </section>
 487
 488     <!-- TODO: configuring a buildbot master
 489     <section id="buildbot-master">
 490       <title>Configuring a Buildbot Master</title>
 491     </section>
 492     -->
 493
 494   </section>
 495
 496   <section id="command-reference">
 497     <title>Command Reference</title>
 498
 499     <para>JHBuild uses a command line syntax similar to tools like CVS:</para>
 500
 501     <cmdsynopsis>
 502       <command>jhbuild</command>
 503       <arg><replaceable>global-options</replaceable></arg>
 504       <arg choice="plain"><replaceable>command</replaceable></arg>
 505       <arg><replaceable>command-arguments</replaceable></arg>
 506     </cmdsynopsis>
 507
 508     <para>The global JHBuild options are:</para>
 509
 510     <variablelist>
 511       <varlistentry>
 512         <term id="option-file"><option>-f</option>, <option>--file</option>
 513         <replaceable>config</replaceable></term>
 514         <listitem>
 515           <simpara>Use an alternative configuration file instead of
 516           the default <filename>~/.jhbuildrc</filename>.</simpara>
 517         </listitem>
 518       </varlistentry>
 519
 520       <varlistentry>
 521         <term><option>-m</option>, <option>--moduleset</option>
 522         <replaceable>moduleset</replaceable></term>
 523         <listitem>
 524           <simpara>Use a module set other than the module set listed in the
 525           configuration file.  This option can be a relative path if the
 526           module set is located in the JHBuild moduleset folder, or an
 527           absolute path if located elsewhere.</simpara>
 528         </listitem>
 529       </varlistentry>
 530
 531       <varlistentry>
 532         <term><option>--no-interact</option></term>
 533         <listitem>
 534           <simpara>Do not prompt the user for any input.  This option is
 535       useful if leaving a build unattended, in order to ensure the
 536       build is not interrupted.</simpara>
 537         </listitem>
 538       </varlistentry>
 539     </variablelist>
 540
 541     <para>Command specific options are listed below.</para>
 542
 543     <section id="command-reference-autobuild">
 544       <title>autobuild</title>
 545
 546       <para>The <command>autobuild</command> command automatically
 547       builds the modules as specified in the configuration
 548       file, and then upload the results to JhAutobuild.</para>
 549
 550       <cmdsynopsis>
 551         <command>jhbuild autobuild</command>
 552         <arg>--autogen</arg>
 553         <arg>--clean</arg>
 554         <arg rep="repeat">--skip=<replaceable>module</replaceable></arg>
 555         <arg>--start-at=<replaceable>module</replaceable></arg>
 556         <arg>--report-url=<replaceable>reporturl</replaceable></arg>
 557         <arg>--verbose</arg>
 558       </cmdsynopsis>
 559
 560       <para>The <option>--autogen</option>, <option>--clean</option>,
 561       <option>--skip</option> and <option>--start-at</option> options
 562       are processed as per the
 563       <link linkend="command-reference-build"><command>build</command></link>
 564       command.</para>
 565
 566       <variablelist>
 567         <varlistentry>
 568           <term><option>--report-url=<replaceable>reporturl</replaceable></option>,
 569           <option>-r <replaceable>reporturl</replaceable></option></term>
 570           <listitem>
 571             <simpara>This option specifies the JhAutobuild URL to report
 572         to.</simpara>
 573           </listitem>
 574         </varlistentry>
 575
 576         <varlistentry>
 577           <term><option>--verbose</option>, <option>-v</option></term>
 578           <listitem>
 579             <simpara>If specified, JHBuild's output will be more
 580             verbose.</simpara>
 581           </listitem>
 582         </varlistentry>
 583       </variablelist>
 584     </section>
 585
 586
 587     <section id="command-reference-bootstrap">
 588       <title>bootstrap</title>
 589
 590       <para>The <command>bootstrap</command> command installs a set of
 591       build utilities required to build most modules (e.g.
 592       <application>autoconf</application>,
 593       <application>automake</application>, etc).</para>
 594
 595       <cmdsynopsis>
 596         <command>jhbuild bootstrap</command>
 597       </cmdsynopsis>
 598
 599       <para>The <command>bootstrap</command> command builds modules
 600       using the same method as the <command>build</command> command,
 601       but uses the <filename>bootstrap.modules</filename> moduleset.</para>
 602
 603       <para>See the
 604       <link linkend="command-reference-build"><command>build</command></link>
 605       command documentation for available options.</para>
 606
 607     </section>
 608
 609     <section id="command-reference-build">
 610       <title>build</title>
 611
 612       <para>The <command>build</command> command builds one or more
 613       packages, including their dependencies.</para>
 614
 615       <cmdsynopsis>
 616         <command>jhbuild build</command>
 617         <arg>--autogen</arg>
 618         <arg>--clean</arg>
 619         <arg>--dist</arg>
 620         <arg>--distcheck</arg>
 621         <arg>--ignore-suggests</arg>
 622         <arg>--no-network</arg>
 623         <arg rep="repeat">--skip=<replaceable>module</replaceable></arg>
 624         <arg>--start-at=<replaceable>module</replaceable></arg>
 625         <arg>--tags=<replaceable>tags</replaceable></arg>
 626         <arg>-D <replaceable>date</replaceable></arg>
 627         <arg>--no-xvfb</arg>
 628         <arg>--try-checkout</arg>
 629         <arg>--no-poison</arg>
 630         <arg>--force</arg>
 631         <arg>--build-optional-modules</arg>
 632         <arg>--min-age=<replaceable>time</replaceable></arg>
 633         <arg rep="repeat">module</arg>
 634       </cmdsynopsis>
 635
 636       <para>If no module names are provided on the command line, the
 637       <link linkend="cfg-modules">modules</link> list from the
 638       configuration file will be used.</para>
 639
 640       <variablelist>
 641         <varlistentry>
 642           <term><option>-a</option>, <option>--autogen</option></term>
 643           <listitem>
 644             <simpara>Always run <command>autogen.sh</command>
 645             before building modules.  By default,
 646             <command>autogen.sh</command> will only be called if the
 647             top-level makefile is missing.  Otherwise, JHBuild relies on
 648         the package's makefiles to detect if configure needs to be
 649             rebuilt or rerun.</simpara>
 650           </listitem>
 651         </varlistentry>
 652
 653         <varlistentry>
 654           <term><option>-c</option>, <option>--clean</option></term>
 655           <listitem>
 656             <simpara>Run <command>make clean</command> before building
 657             modules.</simpara>
 658           </listitem>
 659         </varlistentry>
 660
 661         <varlistentry>
 662           <term><option>-d</option>, <option>--dist</option></term>
 663           <listitem>
 664             <simpara>Run <command>make dist</command> after building
 665             modules.</simpara>
 666           </listitem>
 667         </varlistentry>
 668
 669         <varlistentry>
 670           <term><option>--distcheck</option></term>
 671           <listitem>
 672             <simpara>Run <command>make distcheck</command> after building
 673             modules.</simpara>
 674           </listitem>
 675         </varlistentry>
 676
 677         <varlistentry>
 678           <term><option>--ignore-suggests</option></term>
 679           <listitem>
 680             <simpara>Do not build soft dependencies.</simpara>
 681           </listitem>
 682         </varlistentry>
 683
 684         <varlistentry>
 685           <term><option>-n</option>, <option>--no-network</option></term>
 686           <listitem>
 687             <simpara>Do not access the network when building modules.
 688             This will skip download or update stages in a build.  If a
 689             module can't be built without network access, the module build
 690         will fail.</simpara>
 691           </listitem>
 692         </varlistentry>
 693
 694         <varlistentry>
 695           <term><option>-s</option>,
 696           <option>--skip</option>=<replaceable>module,...</replaceable></term>
 697           <listitem>
 698             <simpara>Do not build the listed modules. Used to skip
 699         the building of specified dependencies.</simpara>
 700           </listitem>
 701         </varlistentry>
 702
 703         <varlistentry>
 704           <term>
 705           <option>--tags</option>=<replaceable>tag,...</replaceable></term>
 706           <listitem>
 707             <simpara>Ignore modules that do not match
 708             <replaceable>tag</replaceable>. Modules are automatically
 709         attributed a tag matching the name of the module's module set.
 710         </simpara>
 711           </listitem>
 712         </varlistentry>
 713
 714         <varlistentry>
 715           <term><option>-t</option>,
 716           <option>--start-at</option>=<replaceable>module</replaceable></term>
 717           <listitem>
 718             <simpara>Start at the named module rather than at the beginning
 719         of the list.  This option is useful if the build was
 720         interrupted.</simpara>
 721           </listitem>
 722         </varlistentry>
 723
 724         <varlistentry>
 725           <term><option>-D</option>
 726           <replaceable>date</replaceable></term>
 727           <listitem>
 728             <simpara>If supported by the underlying version control system,
 729         update the source tree to the specified date before
 730         building.  An ISO date format is required, e.g.
 731         <literal>"2009-09-18 02:32Z"</literal>.</simpara>
 732           </listitem>
 733         </varlistentry>
 734
 735         <varlistentry>
 736           <term><option>-x</option>, <option>--no-xvfb</option></term>
 737           <listitem>
 738             <simpara>Run graphical tests on the actual X server rather
 739             than in a simulated Xvfb.</simpara>
 740           </listitem>
 741         </varlistentry>
 742
 743         <varlistentry>
 744           <term><option>-C</option>,
 745           <option>--try-checkout</option></term>
 746           <listitem>
 747             <simpara>If the build fails, and if supported by the version
 748         control system, force a checkout and run
 749             <command>autogen.sh</command> before retrying the
 750             build.</simpara>
 751           </listitem>
 752         </varlistentry>
 753
 754         <varlistentry>
 755           <term><option>-N</option>, <option>--no-poison</option></term>
 756           <listitem>
 757             <simpara>If one or more of a module's dependencies failed,
 758             this option forces JHBuild to try to build the module
 759             anyway.</simpara>
 760           </listitem>
 761         </varlistentry>
 762
 763         <varlistentry>
 764           <term><option>-f</option>, <option>--force</option></term>
 765           <listitem>
 766         <simpara>Build the modules even if policy states it is
 767             not required.</simpara>
 768       </listitem>
 769         </varlistentry>
 770
 771         <varlistentry>
 772           <term><option>--build-optional-modules</option></term>
 773           <listitem>
 774         <simpara>Modules listed as optional dependencies, may not be
 775         required to build the module. This option forces JHBuild to
 776         build optional dependencies.</simpara>
 777       </listitem>
 778         </varlistentry>
 779
 780     <varlistentry>
 781       <term><option>--min-time</option>=<replaceable>time</replaceable></term>
 782       <listitem>
 783         <simpara>Skip modules installed more recently than the
 784         specified relative time. The <replaceable>time</replaceable>
 785         string format is a number followed by a unit. The
 786         following units are supported: seconds (s), minutes (m),
 787         hours (h) and days (d). For example,
 788         <option>--min-time=2h</option> will skip modules built less
 789         than two hours ago.</simpara>
 790       </listitem>
 791     </varlistentry>
 792
 793       </variablelist>
 794
 795     </section>
 796
 797     <section id="command-reference-buildone">
 798       <title>buildone</title>
 799
 800       <para>The <command>buildone</command> command is similar to
 801       <command>build</command>, but it does not build the dependent
 802       modules. It is useful for rebuilding one or more modules.</para>
 803
 804       <cmdsynopsis>
 805         <command>jhbuild buildone</command>
 806         <arg>--autogen</arg>
 807         <arg>--clean</arg>
 808         <arg>--distcheck</arg>
 809         <arg>--no-network</arg>
 810         <arg>-D <replaceable>date</replaceable></arg>
 811         <arg>--no-xvfb</arg>
 812         <arg>--force</arg>
 813         <arg>--min-age=<replaceable>time</replaceable></arg>
 814         <arg choice="plain" rep="repeat">module</arg>
 815       </cmdsynopsis>
 816
 817       <para>The <option>--autogen</option>, <option>--clean</option>,
 818       <option>-d</option>, <option>--distcheck</option>,
 819       <option>--no-network</option>, <option>-D</option> and
 820       <option>-x</option> options are processed as per the
 821       <link linkend="command-reference-build"><command>build</command></link>
 822       command.</para>
 823
 824       <para>At least one module must be listed on the command line.
 825       </para>
 826
 827     </section>
 828
 829     <section id="command-reference-checkbranches">
 830       <title>checkbranches</title>
 831
 832       <para>The <command>checkbranches</command> checks the module's
 833       branches are defined correctly within the version control system
 834       and the branches are consistent with the module set.</para>
 835
 836       <cmdsynopsis>
 837         <command>jhbuild checkbranches</command>
 838         <arg rep="repeat">--branch=<replaceable>branch</replaceable></arg>
 839       </cmdsynopsis>
 840
 841       <variablelist>
 842         <varlistentry>
 843         <term><option>--branch</option>=<replaceable>branch</replaceable>, <option>-b</option> <replaceable>branch</replaceable></term>
 844         <listitem>
 845           <simpara>The branch to check.</simpara>
 846         </listitem>
 847         </varlistentry>
 848       </variablelist>
 849
 850       <screen><prompt>$</prompt> <userinput>jhbuild -m gnome-2.20 checkbranches</userinput>
 851 libgnomecanvas is missing branch definition for gnome-2-20
 852 <prompt>$</prompt></screen>
 853
 854     </section>
 855
 856     <section id="command-reference-clean">
 857       <title>clean</title>
 858
 859       <para>The <command>clean</command> command cleans the build
 860       directories of one or more modules.</para>
 861
 862       <cmdsynopsis>
 863         <command>jhbuild clean</command>
 864         <arg rep="repeat">--skip=<replaceable>module</replaceable></arg>
 865         <arg>--start-at=<replaceable>module</replaceable></arg>
 866       </cmdsynopsis>
 867
 868       <para>If no module names are provided on the command line, the
 869       <link linkend="cfg-modules">modules</link> list from the
 870       configuration file will be used.</para>
 871
 872       <para>See the
 873       <link linkend="command-reference-build"><command>build</command></link>
 874       command documentation for a description of available options.</para>
 875
 876     </section>
 877
 878     <section id="command-reference-dot">
 879       <title>dot</title>
 880
 881       <para>The <command>dot</command> command generates a file
 882       describing the directed graph formed by the dependencies between
 883       a set of modules.  This file can then be processed using the
 884       <ulink url="http://www.graphviz.org/">GraphViz</ulink> software
 885       to produce a diagram.</para>
 886
 887       <cmdsynopsis>
 888         <command>jhbuild dot</command>
 889         <arg>--soft-deps</arg>
 890         <arg>--clusters</arg>
 891         <arg rep="repeat">module</arg>
 892       </cmdsynopsis>
 893
 894       <para>If no module names are provided on the command line, the
 895       <link linkend="cfg-modules">modules</link> list from the
 896       configuration file will be used.</para>
 897
 898       <para>The <option>--soft-deps</option> option adds dotted lines
 899       from the modules to the soft dependencies.  The
 900       <option>--clusters</option> option groups modules from <link
 901       linkend="moduleset-syntax-defs-metamodule">metamodules</link>
 902       together.</para>
 903
 904       <para>The output of the dot command can be piped to the dot
 905       utility to generate a PostScript file:</para>
 906
 907       <screen><prompt>$</prompt> <userinput>jhbuild dot <replaceable>modules</replaceable> | dot -Tps > dependencies.ps</userinput></screen>
 908
 909       <para>Or a PNG image:</para>
 910
 911       <screen><prompt>$</prompt> <userinput>jhbuild dot <replaceable>modules</replaceable> | dot -Tpng > dependencies.png</userinput></screen>
 912
 913       <figure id="sample-dot-output">
 914         <title>Sample JHBuild dot output</title>
 915         <screenshot>
 916           <mediaobject>
 917             <imageobject>
 918               <imagedata fileref="figures/jhbuild_sample_dot_output.png" format="PNG"/>
 919             </imageobject>
 920           </mediaobject>
 921         </screenshot>
 922       </figure>
 923
 924     </section>
 925
 926     <section id="command-reference-gui">
 927       <title>gui</title>
 928
 929       <para>The <command>gui</command> command starts a graphical
 930       interface to JHBuild which can be used to select modules to
 931       build and change some options.</para>
 932
 933       <cmdsynopsis>
 934         <command>jhbuild gui</command>
 935       </cmdsynopsis>
 936
 937       <para>The graphical interface is rendered using GTK, so extra
 938       support libraries are required.</para>
 939     </section>
 940
 941     <section id="command-reference-info">
 942       <title>info</title>
 943
 944       <para>The <command>info</command> command displays
 945       information about one or more modules.</para>
 946
 947       <cmdsynopsis>
 948         <command>jhbuild info</command>
 949         <arg choice="plain" rep="repeat">module</arg>
 950       </cmdsynopsis>
 951
 952       <para>The command displays the module name, type, dependencies,
 953       dependent packages, and the time it was last installed with
 954       JHBuild.  If available, information specific to the
 955       module type such as the CVS repository or download URL will also
 956       be displayed.</para>
 957
 958       <para>If there is no module specified the command will display
 959       information about all the modules defined in the module set.</para>
 960
 961     </section>
 962
 963     <section id="command-reference-list">
 964       <title>list</title>
 965
 966       <para>The <command>list</command> command displays the
 967       expanded list of modules the <command>build</command> command
 968       would build.</para>
 969
 970       <cmdsynopsis>
 971         <command>jhbuild list</command>
 972         <arg>-a</arg>
 973         <arg>-r</arg>
 974         <arg>-s</arg>
 975         <arg>--start-at=<replaceable>module</replaceable></arg>
 976         <arg>--tags=<replaceable>tags</replaceable></arg>
 977         <arg>--ignore-suggests</arg>
 978         <arg>--list-optional-modules</arg>
 979         <arg rep="repeat">module</arg>
 980       </cmdsynopsis>
 981
 982       <para>If no module names are provided on the command line, the
 983       <link linkend="cfg-modules">modules</link> list from the
 984       configuration file will be used.</para>
 985
 986       <para>The <option>--skip</option>, <option>--start-at</option>,
 987       <option>--tags</option>, <option>--start-at</option> and
 988       <option>--ignore-suggests</option> options are processed as per
 989       the
 990       <link linkend="command-reference-build"><command>build</command></link>
 991       command.</para>
 992
 993       <variablelist>
 994         <varlistentry>
 995           <term><option>-a</option>,
 996           <option>--all-modules</option></term>
 997           <listitem>
 998             <simpara>List all the modules from the module set regardless of
 999         the build dependencies.</simpara>
1000           </listitem>
1001         </varlistentry>
1002
1003         <varlistentry>
1004           <term><option>-r</option>,
1005           <option>--show-revision</option></term>
1006           <listitem>
1007             <simpara>If a module is set to a branch, show the branch
1008         name with the module name.</simpara>
1009           </listitem>
1010         </varlistentry>
1011
1012     <varlistentry>
1013       <term><option>--list-optional-modules</option></term>
1014       <listitem>
1015         <simpara>This option forces JHBuild to list optional
1016         dependencies.</simpara>
1017       </listitem>
1018     </varlistentry>
1019       </variablelist>
1020
1021     </section>
1022
1023     <section id="command-reference-rdepends">
1024       <title>rdepends</title>
1025
1026       <para>The <command>rdepends</command> command displays the
1027       reverse dependencies of a module.</para>
1028
1029       <cmdsynopsis>
1030         <command>jhbuild rdepends</command>
1031         <arg>module</arg>
1032       </cmdsynopsis>
1033
1034       <variablelist>
1035         <varlistentry>
1036           <term><option>--dependencies</option></term>
1037           <listitem>
1038             <simpara>Show dependency path next to modules.</simpara>
1039           </listitem>
1040         </varlistentry>
1041
1042         <varlistentry>
1043           <term><option>--direct</option></term>
1044           <listitem>
1045             <simpara>Limit display to modules directly depending on
1046         specified module.</simpara>
1047           </listitem>
1048         </varlistentry>
1049       </variablelist>
1050     </section>
1051
1052     <section id="command-reference-run">
1053       <title>run</title>
1054
1055       <para>The <command>run</command> command runs the specified
1056       command using the same environment that JHBuild uses when
1057       building modules.</para>
1058
1059       <cmdsynopsis>
1060         <command>jhbuild run</command>
1061         <arg>--in-builddir</arg>
1062         <arg>--in-checkoutdir</arg>
1063         <arg choice="plain"><replaceable>program</replaceable></arg>
1064         <arg rep="repeat"><replaceable>argument</replaceable></arg>
1065       </cmdsynopsis>
1066
1067       <para>If using JHBuild to build GNOME, this command can be
1068       useful in X startup scripts.</para>
1069
1070       <variablelist>
1071         <varlistentry>
1072           <term><option>--in-builddir</option>=<replaceable>module</replaceable></term>
1073           <listitem>
1074             <simpara>Run the command in the build directory of the
1075             specified module.</simpara>
1076           </listitem>
1077         </varlistentry>
1078       </variablelist>
1079
1080       <variablelist>
1081         <varlistentry>
1082           <term><option>--in-checkoutdir</option>=<replaceable>module</replaceable></term>
1083           <listitem>
1084             <simpara>Run the command in the source directory of the
1085             specified module.</simpara>
1086           </listitem>
1087         </varlistentry>
1088       </variablelist>
1089
1090     </section>
1091
1092     <section id="command-reference-sanitycheck">
1093       <title>sanitycheck</title>
1094
1095       <para>The <command>sanitycheck</command> command performs a
1096       number of checks to verify the build environment is okay.</para>
1097
1098       <cmdsynopsis>
1099         <command>jhbuild sanitycheck</command>
1100       </cmdsynopsis>
1101
1102       <para>Some of the checks include:</para>
1103
1104       <itemizedlist>
1105         <listitem>
1106           <simpara>The checkout and install prefixes are writable.
1107       </simpara>
1108         </listitem>
1109         <listitem>
1110           <simpara>The required build tools are installed.</simpara>
1111         </listitem>
1112         <listitem>
1113           <simpara>Some commonly used macros are available in the
1114           search paths of the <command>aclocal</command> commands
1115           associated with the various versions of
1116           <command>automake</command>.</simpara>
1117         </listitem>
1118         <listitem>
1119           <simpara>The XML catalog contains the DocBook DTD and
1120           stylesheets.</simpara>
1121         </listitem>
1122       </itemizedlist>
1123
1124     </section>
1125
1126     <section id="command-reference-shell">
1127       <title>shell</title>
1128
1129       <para>The <command>shell</command> command starts the user's
1130       shell with the same environment as JHBuild uses when building
1131       modules.</para>
1132
1133       <cmdsynopsis>
1134         <command>jhbuild shell</command>
1135       </cmdsynopsis>
1136
1137       <para>This command is equivalent to the following:</para>
1138
1139       <screen><prompt>$</prompt> <userinput>jhbuild run $SHELL</userinput></screen>
1140     </section>
1141
1142     <section id="command-reference-tinderbox">
1143       <title>tinderbox</title>
1144
1145       <para>The <command>tinderbox</command> command is similar to
1146       <command>build</command>, but writes all terminal output to HTML
1147       files suitable for publishing on a website.  It can be used to
1148       set up systems similar to Mozilla's Tinderbox, or Debian's
1149       Buildd.</para>
1150
1151       <cmdsynopsis>
1152         <command>jhbuild tinderbox</command>
1153         <arg>--autogen</arg>
1154         <arg>--clean</arg>
1155         <arg>--no-network</arg>
1156         <arg>--output=<replaceable>directory</replaceable></arg>
1157         <arg rep="repeat">--skip=<replaceable>module</replaceable></arg>
1158         <arg>--start-at=<replaceable>module</replaceable></arg>
1159         <arg>-D <replaceable>date</replaceable></arg>
1160         <arg>-C</arg>
1161         <arg>-N</arg>
1162         <arg>-f</arg>
1163         <arg rep="repeat">module</arg>
1164       </cmdsynopsis>
1165
1166       <para>The <option>--autogen</option>, <option>--clean</option>,
1167       <option>--no-network</option>, <option>--skip</option>,
1168       <option>--start-at</option>, <option>-D</option>,
1169       <option>-C</option>, <option>-N</option> and <option>-f</option>
1170       options are processed as per the
1171       <link linkend="command-reference-build"><command>build</command></link>
1172       command.</para>
1173
1174       <variablelist>
1175         <varlistentry>
1176           <term><option>-o</option>,
1177           <option>--output</option>=<replaceable>directory</replaceable></term>
1178           <listitem>
1179             <simpara>The directory to write the HTML files.</simpara>
1180           </listitem>
1181         </varlistentry>
1182       </variablelist>
1183
1184     </section>
1185
1186     <section id="command-reference-uninstall">
1187       <title>uninstall</title>
1188
1189       <para>The <command>uninstall</command> command uninstalls one or
1190       more modules.</para>
1191
1192       <cmdsynopsis>
1193         <command>jhbuild uninstall</command>
1194         <arg choice="plain" rep="repeat">module</arg>
1195       </cmdsynopsis>
1196
1197     </section>
1198
1199     <section id="command-reference-update">
1200       <title>update</title>
1201
1202       <para>The <command>update</command> command is similar to
1203       <command>build</command>, but only performs the download or
1204       update stage for modules without building them.</para>
1205
1206       <cmdsynopsis>
1207         <command>jhbuild update</command>
1208         <arg rep="repeat">--skip=<replaceable>module</replaceable></arg>
1209         <arg>--start-at=<replaceable>module</replaceable></arg>
1210         <arg>--tags=<replaceable>tags</replaceable></arg>
1211         <arg>--ignore-suggests</arg>
1212         <arg>-D <replaceable>date</replaceable></arg>
1213         <arg rep="repeat">module</arg>
1214       </cmdsynopsis>
1215
1216       <para>The <option>--skip</option>, <option>--start-at</option>,
1217       <option>--tags</option>, <option>--ignore-suggests</option> and
1218       <option>-D</option> options are processed as per the
1219       <link linkend="command-reference-build"><command>build</command></link>
1220       command.</para>
1221
1222     </section>
1223
1224     <section id="command-reference-updateone">
1225       <title>updateone</title>
1226
1227       <para>The <command>updateone</command> command is similar to
1228       <command>update</command>, but it does not update the dependent
1229       modules.  It is useful for updating one or more modules.</para>
1230
1231       <cmdsynopsis>
1232         <command>jhbuild updateone</command>
1233         <arg>-D <replaceable>date</replaceable></arg>
1234         <arg choice="plain" rep="repeat">module</arg>
1235       </cmdsynopsis>
1236
1237       <para>The <option>-D</option> option is processed as per the
1238       <link linkend="command-reference-build"><command>build</command></link>
1239       command.</para>
1240
1241       <para>At least one module must be listed on the command line.
1242       </para>
1243     </section>
1244
1245   </section>
1246
1247   <section id="config-reference">
1248     <title>Configuration File Reference</title>
1249
1250     <para>The <filename>~/.jhbuildrc</filename> file uses standard
1251     Python syntax.  The file is run, and the resulting variables
1252     defined in the namespace are used to control how JHBuild acts.  A
1253     set of default values are inserted into the namespace before
1254     running the user's configuration file.</para>
1255
1256         <para>Boolean configuration variables are set using syntax as
1257         demonstrated in the following example:</para>
1258         <programlisting>use_local_modulesets = True</programlisting>
1259
1260         <para>String configuration variables are set using syntax as
1261         demonstrated in the following example:</para>
1262         <programlisting>autogenargs = '--disable-static --disable-gtk-doc'</programlisting>
1263
1264         <para>List configuration variables are set using syntax as
1265         demonstrated in the following example:</para>
1266         <programlisting>skip = ['mozilla', 'pulseaudio']</programlisting>
1267
1268         <para>Dictionary configuration variables are set using syntax as
1269         demonstrated in the following example:</para>
1270         <programlisting>repos['git.gnome.org'] = 'ssh://username@git.gnome.org/git/'</programlisting>
1271
1272     <section id="config-reference-variables">
1273       <title>Configuration Variables</title>
1274
1275       <variablelist>
1276         <?dbhtml list-presentation="table"?>
1277         <varlistentry>
1278           <term id="cfg-alwaysautogen"><varname>alwaysautogen</varname></term>
1279           <listitem>
1280             <simpara>A boolean value if set to <constant>True</constant>, always
1281             run <command>autogen.sh</command> before
1282             <command>make</command>, even if a makefile exists.  This
1283             is equivalent to passing <option>--always-autogen</option>
1284             option to JHBuild.  Defaults to
1285             <constant>False</constant>.</simpara>
1286           </listitem>
1287         </varlistentry>
1288         <varlistentry>
1289           <term id="cfg-autogenargs"><varname>autogenargs</varname></term>
1290           <listitem>
1291             <simpara>A string containing arguments passed to the
1292             <command>autogen.sh</command> script of all modules.  Can
1293             be overridden for particular modules using the
1294             <varname>module_autogenargs</varname>
1295             dictionary.</simpara>
1296         </listitem>
1297         </varlistentry>
1298         <varlistentry>
1299           <term id="cfg-branches"><varname>branches</varname></term>
1300           <listitem>
1301             <simpara>A dictionary that can be used to override the
1302             branch used for a particular module.  This is useful if
1303             you are making some changes on a branch of a module and
1304             want JHBuild to build that branch instead of the one
1305             listed in the module set.</simpara>
1306             <simpara>The definition of branches depends on the module
1307             VCS:</simpara>
1308             <itemizedlist>
1309               <listitem><simpara>CVS: revision.
1310               E.g. <literal>'BRANCH-PROJECT-0_8'</literal>
1311               </simpara></listitem>
1312               <listitem><simpara>Bazaar: URI of module branch.
1313               E.g. <literal>'http://bzr.example.net/project/gnome-2-28'</literal>
1314               </simpara></listitem>
1315               <listitem><simpara>Git: tuple,
1316               with first part being an optional repository (or the None value)
1317               and the second part the name of the branch.
1318               E.g. <literal>('git://git.example.net/project', 'gnome-2-28')</literal>
1319               </simpara></listitem>
1320               <listitem><simpara>Subversion: URI of module branch
1321               E.g. <literal>'svn://svn.example.net/project/gnome-2-28'</literal>
1322               </simpara></listitem>
1323             </itemizedlist>
1324           </listitem>
1325         </varlistentry>
1326         <varlistentry>
1327           <term id="cfg-builddir-pattern"><varname>builddir_pattern</varname></term>
1328           <listitem>
1329             <simpara>A <function>printf</function> style formatting
1330             pattern used to generate build directory names.  This is
1331             only used when using separate source and build trees.  The
1332             <literal>%s</literal> in the format string will be
1333             replaced with the source directory name.  Defaults to
1334             <literal>'%s'</literal>.</simpara>
1335           </listitem>
1336         </varlistentry>
1337         <varlistentry>
1338           <term id="cfg-buildroot"><varname>buildroot</varname></term>
1339           <listitem>
1340             <simpara>A string specifying the parent directory to place
1341             build trees.  Defaults to <constant>None</constant>, which
1342             causes builds to be performed within the source
1343             trees.</simpara>
1344           </listitem>
1345         </varlistentry>
1346         <varlistentry>
1347           <term id="cfg-buildscript"><varname>buildscript</varname></term>
1348           <listitem>
1349             <simpara>A string specifying which buildscript to use.
1350             The recommended setting is the default,
1351         <literal>terminal</literal>.  In particular, do not
1352             set to <literal>gtk</literal>.</simpara>
1353           </listitem>
1354         </varlistentry>
1355         <varlistentry>
1356           <term id="cf-build-policy"><varname>build_policy</varname></term>
1357           <listitem>
1358             <simpara>A string specifying which modules to build.
1359             The three possible options are <literal>all</literal>, to
1360             build all modules requested, <literal>updated</literal> to
1361             build only modules which have changed, or
1362             <literal>updated-deps</literal> to build modules which have
1363             changed or which have dependencies which have changed.
1364             Defaults to <literal>all</literal>.</simpara>
1365           </listitem>
1366         </varlistentry>
1367         <varlistentry>
1368           <term id="cfg-checkoutroot"><varname>checkoutroot</varname></term>
1369           <listitem>
1370             <simpara>A string specifying the directory to unpack source
1371             trees to.  Unless <varname>buildroot</varname> is set,
1372             builds will occur in this directory too.  Defaults to
1373             <filename>~/checkout/gnome2</filename>.</simpara>
1374           </listitem>
1375         </varlistentry>
1376         <varlistentry>
1377           <term id="cfg-checkout-mode"><varname>checkout_mode</varname></term>
1378           <listitem>
1379             <simpara>A string specifying how the checkout is performed for
1380             directories in version control.  Defaults to
1381             <literal>update</literal>.  This can be set per module
1382             using <varname>module_checkout_mode</varname>.  Possible
1383             values are <literal>update</literal> (update checkout
1384             directory), <literal>clobber</literal> (wipe out directory
1385             before checking out the sources), <literal>export</literal>
1386             (wipe out directory then create an unversioned copy of the
1387             sources) and <literal>copy</literal> (checkout in a directory
1388             different from the one it will build).
1389             </simpara>
1390           </listitem>
1391         </varlistentry>
1392         <varlistentry>
1393           <term id="cfg-copy-dir"><varname>copy_dir</varname></term>
1394           <listitem>
1395             <simpara>A string specifying the directory to copy to, if
1396             the copy <link linkend="cfg-checkout-mode">
1397         <varname>checkout_mode</varname></link> is in use.  Defaults to
1398         the checkout directory.</simpara>
1399           </listitem>
1400         </varlistentry>
1401         <varlistentry>
1402           <term id="cfg-cvs-program"><varname>cvs_program</varname></term>
1403           <listitem>
1404             <simpara>A string specifying which program to use for
1405             CVS support.  Defaults to <literal>cvs</literal>.</simpara>
1406           </listitem>
1407         </varlistentry>
1408         <varlistentry>
1409           <term id="cfg-installprog"><varname>installprog</varname></term>
1410           <listitem>
1411             <simpara>A string specifying a program to use as
1412             replacement for <literal>/usr/bin/install</literal>. If
1413         available, defaults to the <literal>install-check</literal>
1414         wrapper provided by JHBuild. The
1415         <literal>install-check</literal> wrapper optimizes header
1416         installation to reduce the time taken for rebuilds.
1417             </simpara>
1418           </listitem>
1419         </varlistentry>
1420         <varlistentry>
1421           <term id="cfg-ignore-suggests"><varname>ignore_suggests</varname></term>
1422           <listitem>
1423             <simpara>A boolean value specifying whether to ignore
1424             soft dependencies when calculating the dependency tree.
1425             Defaults to <constant>False</constant>.</simpara>
1426           </listitem>
1427         </varlistentry>
1428         <varlistentry>
1429           <term id="cfg-interact"><varname>interact</varname></term>
1430           <listitem>
1431             <simpara>A boolean value specifying whether to interact
1432             with the user.  Setting this value to
1433             <constant>False</constant> is equivalent to passing the
1434             <option>--no-interact</option> option.  Defaults to
1435             <constant>True</constant>.</simpara>
1436           </listitem>
1437         </varlistentry>
1438         <varlistentry>
1439           <term id="cfg-makeargs"><varname>makeargs</varname></term>
1440           <listitem>
1441             <simpara>A string listing additional arguments to be
1442             passed to <command>make</command>.  Defaults to
1443             <literal>''</literal>.</simpara>
1444           </listitem>
1445         </varlistentry>
1446         <varlistentry>
1447           <term id="cfg-makecheck"><varname>makecheck</varname></term>
1448           <listitem>
1449             <simpara>A boolean value specifying whether to run
1450             <command>make check</command> after
1451             <command>make</command>.
1452             Defaults to <constant>False</constant>.</simpara>
1453           </listitem>
1454         </varlistentry>
1455         <varlistentry>
1456           <term id="cfg-makecheck-advistory"><varname>makecheck_advisory</varname></term>
1457           <listitem>
1458             <simpara>A boolean value specifying whether failures when running
1459             <command>make check</command> should be advisory only and not cause
1460             a build failure.  Defaults to <constant>False</constant>.</simpara>
1461           </listitem>
1462         </varlistentry>
1463         <varlistentry>
1464           <term id="cfg-makeclean"><varname>makeclean</varname></term>
1465           <listitem>
1466             <simpara>A boolean value specifying whether to run
1467             <command>make clean</command> before
1468             <command>make</command>.  Defaults to
1469             <constant>False</constant>.</simpara>
1470           </listitem>
1471         </varlistentry>
1472         <varlistentry>
1473           <term id="cfg-makedist"><varname>makedist</varname></term>
1474           <listitem>
1475             <simpara>A boolean value specifying whether to run
1476             <command>make dist</command> after <command>make</command>.
1477             Defaults to <constant>False</constant>.  This setting is
1478             equivalent to passing the <option>--dist</option>
1479             option.</simpara>
1480           </listitem>
1481         </varlistentry>
1482         <varlistentry>
1483           <term id="cfg-makedistcheck"><varname>makedistcheck</varname></term>
1484           <listitem>
1485             <simpara>A boolean value specifying whether to run
1486             <command>make distcheck</command> after
1487             <command>make</command>.  Defaults to
1488             <constant>False</constant>.  This setting is equivalent to
1489             passing the <option>--distcheck</option> option.</simpara>
1490           </listitem>
1491         </varlistentry>
1492         <varlistentry>
1493           <term id="cfg-module-autogenargs"><varname>module_autogenargs</varname></term>
1494           <listitem>
1495             <simpara>A dictionary mapping module names to strings
1496             specifying the arguments to be passed to
1497             <command>autogen.sh</command>.  The setting in
1498             <varname>module_autogenargs</varname> is used instead of
1499             the global <varname>autogenargs</varname> setting.
1500             If a particular module isn't listed in the dictionary, the
1501             global <varname>autogenargs</varname> will be used.</simpara>
1502           </listitem>
1503         </varlistentry>
1504         <varlistentry>
1505           <term id="cfg-module-checkout-mode"><varname>module_checkout_mode</varname></term>
1506           <listitem>
1507             <simpara>A dictionary specifying which checkout mode to
1508             use for modules.  This overrides the global
1509             <varname>checkout_mode</varname> setting.</simpara>
1510           </listitem>
1511         </varlistentry>
1512         <varlistentry>
1513           <term id="cfg-module-makeargs"><varname>module_makeargs</varname></term>
1514           <listitem>
1515             <simpara>A dictionary mapping module names to strings
1516             specifying the arguments to pass to
1517         <command>make</command>. The setting in
1518         <varname>module_makeargs</varname> replaces the value of
1519         <varname>makeargs</varname>.  If a particular module isn't
1520         listed in the dictionary, the global
1521         <varname>makeargs</varname> will be used.</simpara>
1522           </listitem>
1523         </varlistentry>
1524         <varlistentry>
1525           <term id="cfg-module-extra-env"><varname>module_extra_env</varname></term>
1526           <listitem>
1527             <simpara>A dictionary mapping module names to dictionaries
1528             with extra environment variables to pass when executing commands
1529             for the module.
1530             </simpara>
1531           </listitem>
1532         </varlistentry>
1533         <varlistentry>
1534           <term id="cfg-modules"><varname>modules</varname></term>
1535           <listitem>
1536             <simpara>A list of strings specifying the modules to
1537             build.  The list of modules actually built will be
1538             recursively expanded to include all the dependencies
1539             unless the <link linkend="command-reference-buildone">
1540         <command>buildone</command></link> command is used. Defaults to
1541             <literal>['meta-gnome-desktop']</literal>.</simpara>
1542           </listitem>
1543         </varlistentry>
1544         <varlistentry>
1545           <term id="cfg-moduleset"><varname>moduleset</varname></term>
1546           <listitem>
1547             <simpara>A string or list of strings specifying the name(s) of
1548             the module set(s) to use.  This can either be the filename of
1549             a moduleset included with JHBuild (excluding the path and
1550             extension), or a full HTTP URL to an externally managed
1551         moduleset.  HTTP URL modulesets are cached locally.  If a
1552         module with the same name is present in more than one
1553         moduleset, the last set listed takes priority. Modulesets
1554         provided with JHBuild are updated to match the current GNOME
1555         development release.</simpara>
1556           </listitem>
1557         </varlistentry>
1558         <varlistentry>
1559           <term id="cfg-modulesets-dir"><varname>modulesets_dir</varname></term>
1560           <listitem>
1561             <simpara>A string specifying the directory containing the
1562             modulesets to use.  Defaults to the
1563             <filename>modulesets/</filename> directory in JHBuild sources.
1564             </simpara>
1565           </listitem>
1566         </varlistentry>
1567         <varlistentry>
1568           <term id="cfg-nobuild"><varname>nobuild</varname></term>
1569           <listitem>
1570             <simpara>A boolean value, if set to <constant>True</constant>
1571         JHBuild will not build modules, but just download and
1572         unpack the sources.  The default vale is
1573         <constant>False</constant>.</simpara>
1574           </listitem>
1575         </varlistentry>
1576         <varlistentry>
1577           <term id="cfg-nonetwork"><varname>nonetwork</varname></term>
1578           <listitem>
1579             <simpara>A boolean value specifying whether to access the
1580             network.  This affects checking out or updating CVS
1581             modules, downloading tarballs and updating module sets.
1582             Setting this to <constant>True</constant> is equivalent to
1583             passing the <option>--no-network</option> option.  Defaults to
1584         <constant>False</constant>.</simpara>
1585           </listitem>
1586         </varlistentry>
1587         <varlistentry>
1588           <term id="cfg-nonotify"><varname>nonotify</varname></term>
1589           <listitem>
1590             <simpara>A boolean value specifying whether to emit
1591             notifications using the notification daemon.  If set to
1592             <constant>True</constant>, notifications are not emitted.
1593             Defaults to <constant>False</constant>, except on Win32
1594                 where it defaults to <constant>True</constant>.</simpara>
1595           </listitem>
1596         </varlistentry>
1597         <varlistentry>
1598           <term id="cfg-nopoison"><varname>nopoison</varname></term>
1599           <listitem>
1600             <simpara>A boolean value, if set to <constant>True</constant>
1601         JHBuild attempts to build modules even if one or more of
1602         the module's dependencies failed to build.  This option is
1603         equivalent to the <option>--no-poison</option> argument.  The
1604         default value is <constant>False</constant>.</simpara>
1605           </listitem>
1606         </varlistentry>
1607         <varlistentry>
1608           <term id="cfg-notrayicon"><varname>notrayicon</varname></term>
1609           <listitem>
1610             <simpara>A boolean value specifying whether to show an icon
1611             in the system tray using Zenity. If set to
1612             <constant>True</constant>, notifications are not emitted.
1613             Defaults to <constant>False</constant> except from on Win32,
1614                 where it defaults to <constant>True</constant>.</simpara>
1615           </listitem>
1616         </varlistentry>
1617         <varlistentry>
1618           <term id="cfg-noxvfb"><varname>noxvfb</varname></term>
1619           <listitem>
1620             <simpara>A boolean value, if set to <constant>True</constant>
1621         JHBuild will run any graphical tests on the real X server,
1622         rather than using <command>Xvfb</command>.  This option is
1623         equivalent to passing <option>--no-xvfb</option>.  The default
1624         value is <constant>False</constant></simpara>
1625           </listitem>
1626         </varlistentry>
1627         <varlistentry>
1628           <term id="cfg-prefix"><varname>prefix</varname></term>
1629           <listitem>
1630             <simpara>A string specifying the prefix to install modules to.
1631             This directory must be writable.  Defaults to
1632             <literal>'/opt/gnome2'</literal>.</simpara>
1633           </listitem>
1634         </varlistentry>
1635         <varlistentry>
1636           <term id="cfg-pretty-print"><varname>pretty_print</varname></term>
1637           <listitem>
1638             <simpara>A boolean value specifying whether to pretty
1639         format the subprocess output.  Only CVS output supports pretty
1640         printing.  Disable if the pretty printing causes problems.
1641         Defaults to <literal>True</literal>.</simpara>
1642           </listitem>
1643         </varlistentry>
1644     <varlistentry>
1645       <term id="cfg-progress-bar"><varname>progress_bar</varname></term>
1646       <listitem>
1647         <simpara>A boolean value specifying whether to display a
1648         progress bar during <link linkend="cfg-quiet-mode">quiet mode
1649         </link>.  Defaults to <literal>True</literal>.</simpara>
1650       </listitem>
1651     </varlistentry>
1652     <varlistentry>
1653       <term id="cfg-quiet-mode"><varname>quiet_mode</varname></term>
1654       <listitem>
1655         <simpara>A boolean value, if set to <constant>True</constant>
1656         disables the output of running commands.  Defaults to
1657         <literal>False</literal>.</simpara>
1658       </listitem>
1659     </varlistentry>
1660         <varlistentry>
1661           <term id="cfg-repos"><varname>repos</varname></term>
1662           <listitem>
1663                 <simpara>A dictionary specifying an alternative repository
1664         location for a particular repository. This configuration
1665                 variable is useful to a module developer. By default, JHBuild
1666         will check out code from repositories using an anonymous
1667         repository location. The dictionary keys are short repository
1668         names and the values are the alternative repository location
1669         strings. For example:</simpara>
1670         <programlisting>repos['git.gnome.org'] = 'ssh://username@git.gnome.org/git/'</programlisting>
1671           </listitem>
1672         </varlistentry>
1673         <varlistentry id="cfg-skip">
1674           <term><varname>skip</varname></term>
1675           <listitem>
1676             <simpara>A list of modules to skip.  This
1677             <option>--skip</option> command line option extends the list.
1678         This list is empty by default.</simpara>
1679           </listitem>
1680         </varlistentry>
1681         <varlistentry id="cfg-sticky-date">
1682           <term><varname>sticky_date</varname></term>
1683           <listitem>
1684             <simpara>A string if set, and if supported by the underlying
1685         version control system, JHBuild will update the source tree to
1686         the specified date before building.  An ISO date format is
1687         required, e.g.
1688             <literal>'<replaceable>yyyy</replaceable>-<replaceable>mm</replaceable>-<replaceable>dd</replaceable>'</literal>.
1689             Defaults to <constant>None</constant>.</simpara>
1690         </listitem>
1691         </varlistentry>
1692         <varlistentry id="cfg-svn-program">
1693           <term><varname>svn_program</varname></term>
1694           <listitem>
1695             <simpara>A string specifying which program to use for
1696             subversion support.  This can be <literal>svn</literal>
1697             or <literal>bzr</literal>.  Defaults to
1698             <literal>svn</literal>.</simpara>
1699           </listitem>
1700         </varlistentry>
1701         <varlistentry id="cfg-tarballdir">
1702           <term><varname>tarballdir</varname></term>
1703           <listitem>
1704             <simpara>A string if set, tarballs will be downloaded the
1705         specified directory instead of <varname>checkoutroot</varname>.
1706             This is useful if you have multiple JHBuild environments
1707             or regularly clear out <varname>checkoutroot</varname> and want
1708         to reduce bandwidth usage.</simpara>
1709           </listitem>
1710         </varlistentry>
1711         <varlistentry id="cfg-tinderbox-outputdir">
1712           <term><varname>tinderbox_outputdir</varname></term>
1713           <listitem>
1714             <simpara>A string specifying the directory to store
1715             <command>jhbuild tinderbox</command> output.  This string
1716             can be overridden by the <option>--output</option> option.
1717             Defaults to <constant>None</constant>, so either the
1718             command line option must be used or this variable must be
1719             set in the configuration file.</simpara>
1720           </listitem>
1721         </varlistentry>
1722         <varlistentry id="cfg-trycheckout">
1723           <term><varname>trycheckout</varname></term>
1724           <listitem>
1725             <simpara>A boolean value, if set to
1726             <constant>True</constant> JHBuild will automatically
1727             try to solve failures by 1) running <command>autogen.sh</command>
1728             again, and 2) checking out a newer version of a module from version
1729             control. This setting is equivalent to passing the
1730             <option>--try-checkout</option> option.</simpara>
1731           </listitem>
1732         </varlistentry>
1733         <varlistentry id="cfg-use-lib64">
1734           <term><varname>use_lib64</varname></term>
1735           <listitem>
1736             <simpara>A boolean value that specifies whether to install
1737             libraries to <filename>lib64</filename> directories.  If
1738             set, <literal>--libdir=\${exec_prefix}/lib64</literal> will be
1739             passed to configure.  Defaults to
1740             <constant>True</constant> if running on
1741             <literal>x86_64</literal>, <literal>ppc64</literal> or
1742             <literal>s390x</literal> Linux, and
1743             <constant>False</constant> on other systems.</simpara>
1744           </listitem>
1745         </varlistentry>
1746         <varlistentry id="cfg-use-local-modulesets">
1747           <term><varname>use_local_modulesets</varname></term>
1748           <listitem>
1749             <simpara>A boolean value that specifies to use modulesets
1750             that were checked out along the JHBuild source code; instead
1751             of downloading them on-the-fly from GNOME version control
1752         system.  Defaults to <constant>False</constant>.
1753             </simpara>
1754           </listitem>
1755         </varlistentry>
1756         <varlistentry id="cfg-xvfbargs">
1757           <term><varname>xvfbargs</varname></term>
1758           <listitem>
1759             <simpara>A string listing arguments to pass to
1760             <command>Xvfb</command> if running graphical tests.</simpara>
1761           </listitem>
1762         </varlistentry>
1763       </variablelist>
1764     </section>
1765
1766     <section id="config-reference-other">
1767       <title>Other Configuration File Structures</title>
1768
1769       <para>In addition to the above variables, there are other
1770       settings that can be set in the configuration file:</para>
1771
1772       <variablelist>
1773         <varlistentry id="cfg-os-environ">
1774           <term><varname>os.environ</varname></term>
1775           <listitem>
1776             <para>A dictionary representing the environment. This
1777             environment is passed to processes that JHBuild spawns.</para>
1778             <para>Some influential environment variables include
1779             <envar>CPPFLAGS</envar>, <envar>CFLAGS</envar>,
1780             <envar>INSTALL</envar> and <envar>LDFLAGS</envar>.
1781             For example:</para>
1782             <programlisting>os.environ['CFLAGS'] = '-O0 -g'</programlisting>
1783           </listitem>
1784         </varlistentry>
1785         <varlistentry>
1786           <term><function>addpath</function>(<parameter>envvar</parameter>,
1787           <parameter>pathname</parameter>)</term>
1788           <listitem>
1789             <para>This will add a directory to the
1790             <envar>PATH</envar> environment variable.
1791         <function>addpath</function> will correctly handle the case
1792         when the environment variable is initially empty (having a
1793         stray colon at the beginning or end of an environment variable
1794         can have unexpected consequences).</para>
1795             <para><function>addpath</function> has special handling for the
1796             <envar>ACLOCAL_FLAGS</envar> environment variable, which
1797             expects paths to be listed in the form <literal>-I
1798             <replaceable>pathname</replaceable></literal>.</para>
1799           </listitem>
1800         </varlistentry>
1801         <varlistentry>
1802           <term><function>prependpath</function>(<parameter>envvar</parameter>,
1803           <parameter>pathname</parameter>)</term>
1804           <listitem>
1805             <para>After processing the configuration file, JHBuild
1806             will alter some paths based on variables such as
1807             <varname>prefix</varname> (e.g. adding
1808             <literal>$prefix/bin</literal> to the start of
1809             <envar>PATH</envar>).</para>
1810             <para>The <function>prependpath</function> function works
1811             like <function>addpath</function>, except that the
1812             environment variable is modified after JHBuild has made
1813             its changes to the environment.</para>
1814           </listitem>
1815         </varlistentry>
1816       </variablelist>
1817     </section>
1818   </section>
1819
1820   <section id="moduleset-syntax">
1821     <title>Module Set File Syntax</title>
1822
1823     <para>JHBuild uses XML files to describe the dependencies
1824     between modules.  A RELAX-NG schema and Document Type Definition
1825     are included with JHBuild in the <filename>modulesets/</filename>
1826     directory.  The RELAX-NG schema can be used to edit module
1827     set files using <literal>nxml-mode</literal> in Emacs.</para>
1828
1829     <para>The top-level element in a module set file is <sgmltag
1830     class="element">moduleset</sgmltag> element.  No XML namespace is
1831     used.  The elements below the top-level come in three types:
1832     module sources, include statements and module definitions.</para>
1833
1834     <section id="moduleset-syntax-sources">
1835       <title>Module Sources</title>
1836
1837       <para>Rather than listing the full location of every module, a
1838       number of "module sources" are listed in the module set, and
1839       then referenced by name in the module definitions.  As well as
1840       reducing the amount of redundant information in the module set,
1841       it makes it easy for a user to specify an alternative source for
1842       those modules (for CVS and Subversion, it is common for
1843       developers and users to use different repository access
1844       methods).</para>
1845
1846       <para>The <sgmltag class="element">repository</sgmltag>
1847       element is used to describe all types of repository.</para>
1848
1849 <programlisting>
1850 &lt;repository name="<replaceable>name</replaceable>"
1851   type="<replaceable>type</replaceable>"
1852   [ default="<replaceable>default</replaceable>" ]
1853   [ password="<replaceable>password</replaceable>" ]
1854   [ cvsroot="<replaceable>cvsroot</replaceable>" ]
1855   [ archive="<replaceable>archive</replaceable>" ]
1856   [ href="<replaceable>href</replaceable>" ]
1857   [ server="<replaceable>server</replaceable>" ]
1858   [ database="<replaceable>database</replaceable>" ]
1859   [ defbranch="<replaceable>defbranch</replaceable>" ]
1860   [ developer-href-example="<replaceable>developer-href-example</replaceable>" ] /&gt;
1861 </programlisting>
1862
1863       <para>The <sgmltag class="attribute">name</sgmltag> attribute
1864       is a unique identifier for the repository.</para>
1865
1866       <para>The <sgmltag class="attribute">default</sgmltag>
1867       attribute specifies whether this repository is the default
1868       source for this module set.</para>
1869
1870       <para>The <sgmltag class="attribute">type</sgmltag> attribute
1871       specifies the type of repository.  It can be one of:
1872       <literal>arch</literal>, <literal>bzr</literal>,
1873       <literal>cvs</literal>, <literal>darcs</literal>,
1874       <literal>git</literal>, <literal>hg</literal>,
1875       <literal>mtr</literal>, <literal>svn</literal>,
1876       <literal>tarball</literal>.  Other attributes depends on the
1877       <sgmltag class="attribute">type</sgmltag>, as well as the <sgmltag
1878       class="element">branch</sgmltag> used inside module definitions.
1879       Those are described below.</para>
1880
1881       <para>The <sgmltag class="attribute">developer-href-example</sgmltag>
1882       attribute is used to specify the format of the URL for
1883       the repository used by developers.  This is informational only.</para>
1884
1885       <section id="moduleset-syntax-sources-arch">
1886         <title>Arch</title>
1887
1888         <para>This repository type is used to define a Arch repository.</para>
1889
1890         <para>The <sgmltag class="attribute">archive</sgmltag>
1891         attribute is used to specify the archive to use.</para>
1892
1893         <para>The <sgmltag class="attribute">href</sgmltag>
1894         attribute is used to specify the URL of the repository.</para>
1895
1896         <programlisting>
1897 &lt;repository type="arch" name="rhythmbox"
1898     archive="rhythmbox-devel@gnome.org--2004"
1899     href="http://web.rhythmbox.org/arch/2004"/&gt;
1900 </programlisting>
1901
1902       </section>
1903
1904       <section id="moduleset-syntax-sources-bzr">
1905         <title>Bazaar</title>
1906         <para>This repository type is used to define a Bazaar repository.</para>
1907
1908         <programlisting>
1909 &lt;repository type="bzr" name="launchpad.net"
1910       href="http://bazaar.launchpad.net/"/&gt;
1911 </programlisting>
1912       </section>
1913
1914       <section id="moduleset-syntax-sources-cvs">
1915         <title>CVS</title>
1916         <para>This repository type is used to define a CVS repository.</para>
1917
1918         <para>The <sgmltag class="attribute">password</sgmltag>
1919         attribute is used to specify the password to the repository.
1920         </para>
1921
1922         <para>The <sgmltag class="attribute">cvsroot</sgmltag>
1923         attribute is used to specify the root of the repository.
1924         </para>
1925
1926         <programlisting>
1927 &lt;repository type="cvs" name="tango.freedesktop.org"
1928     cvsroot=":pserver:anoncvs@anoncvs.freedesktop.org:/cvs/tango"
1929     password=""/&gt;
1930 </programlisting>
1931
1932       </section>
1933
1934       <section id="moduleset-syntax-sources-darcs">
1935         <title>Darcs</title>
1936         <para>This repository type is used to define a Darcs repository.</para>
1937
1938         <programlisting>
1939 &lt;repository type="darcs" name="telepathy.freedesktop.org"
1940       href="http://projects.collabora.co.uk/darcs/telepathy/"/&gt;
1941 </programlisting>
1942       </section>
1943
1944       <section id="moduleset-syntax-sources-git">
1945         <title>Git</title>
1946         <para>This repository type is used to define a Git repository.</para>
1947
1948         <programlisting>
1949 &lt;repository type="git" name="git.freedesktop.org"
1950     href="git://anongit.freedesktop.org/git/"/&gt;
1951 </programlisting>
1952
1953         <programlisting>
1954 &lt;branch repo="git.freedesktop.org" module="swfdec/swfdec"
1955     checkoutdir="swfdec"/&gt;
1956 </programlisting>
1957
1958
1959       </section>
1960
1961       <section id="moduleset-syntax-sources-hg">
1962         <title>Mercurial</title>
1963         <para>This repository type is used to define a Mercurial repository.</para>
1964
1965         <programlisting>
1966 &lt;repository type="hg" name="hg.gtk-vnc"
1967     href="http://gtk-vnc.codemonkey.ws/hg/" /&gt;
1968 </programlisting>
1969
1970         <programlisting>
1971 &lt;branch repo="hg.gtk-vnc" module="outgoing.hg" checkoutdir="gtk-vnc"/&gt;
1972 </programlisting>
1973
1974       </section>
1975
1976       <section id="moduleset-syntax-sources-mtn">
1977         <title>Monotone</title>
1978         <para>This repository type is used to define a Monotone repository.</para>
1979
1980         <para>The <sgmltag class="attribute">server</sgmltag>
1981         attribute is used to specify the repository server.</para>
1982
1983         <para>The <sgmltag class="attribute">database</sgmltag>
1984         attribute is used to specify the database to use for
1985         the repository.</para>
1986
1987         <para>The <sgmltag class="attribute">defbranch</sgmltag>
1988         attribute is used specify the branch of the repository
1989         to use.</para>
1990
1991         <programlisting>
1992 &lt;repository type="mtn" name="pidgin.im"
1993     server="pidgin.im" database="pidgin.im.mtn"
1994     defbranch="im.pidgin.pidgin"/&gt;
1995 </programlisting>
1996
1997       </section>
1998
1999       <section id="moduleset-syntax-sources-svn">
2000         <title>Subversion</title>
2001         <para>This repository type is used to define a Subversion repository.</para>
2002
2003         <programlisting>
2004 &lt;repository type="svn" name="svn.gnome.org" default="yes"
2005     href="http://svn.gnome.org/svn/"/&gt;
2006 </programlisting>
2007
2008         <para>It allows a <sgmltag class="attribute">revision</sgmltag>
2009         on the <sgmltag class="element">branch</sgmltag> element.  This
2010         attribute defines the branch to checkout or, if it is a number,
2011         a specific revision to checkout.</para>
2012
2013         <programlisting>
2014 &lt;branch revision="gnome-2-20"/&gt;
2015 </programlisting>
2016
2017       </section>
2018
2019       <section id="moduleset-syntax-sources-tarball">
2020         <title>Tarballs</title>
2021         <para>This repository type is used to define a tarball repository.</para>
2022
2023         <programlisting>
2024 &lt;repository type="tarball" name="dbus/dbus-python"
2025     href="http://dbus.freedesktop.org/releases/dbus-python/"/&gt;
2026 </programlisting>
2027
2028         <para>It allows the following attributes on the <sgmltag
2029         class="element">branch</sgmltag> element:</para>
2030
2031         <para>The <sgmltag class="attribute">module</sgmltag> attribute
2032         specifies the file to download and compile, the <sgmltag
2033         class="attribute">version</sgmltag> attribute specifies the
2034         module version.</para>
2035
2036         <para>The <sgmltag class="attribute">size</sgmltag> and <sgmltag
2037         class="attribute">hash</sgmltag>, as well as the obsolete
2038         <sgmltag class="attribute">md5sum</sgmltag>, attributes are optional.
2039         If these attributes are present, they are used to check
2040         that the source package was downloaded correctly.</para>
2041
2042         <para>The <sgmltag class="element">patches</sgmltag> element
2043         is used to specify one or more patches to apply to the source
2044         tree after unpacking, the <sgmltag class="attribute">file</sgmltag>
2045         attribute gives the patch filename, and the <sgmltag
2046         class="attribute">strip</sgmltag> attribute says how
2047         many levels of directories to prune when applying the
2048         patch.</para>
2049
2050         <para>For module sets shipped with JHBuild, the patch files are
2051         looked up in the <filename>jhbuild/patches/</filename> directory;
2052         for module sets referred by URI, the patch files are looked for
2053         in the same directory as the moduleset file, or in its
2054         <filename>patches/</filename> subdirectory.  It is also possible
2055         for the <sgmltag class="attribute">file</sgmltag> attribute to
2056         specify a URI, in which case it will be downloaded from that location.
2057         </para>
2058
2059         <programlisting>
2060 &lt;branch module="dbus-python-0.80.2.tar.gz" version="0.80.2"
2061     repo="dbus/dbus-python"
2062     hash="md5:2807bc85215c995bd595e01edd9d2077" size="453499"&gt;
2063   &lt;patches&gt;
2064     &lt;patch file="dbus-glib-build.patch" strip="1" /&gt;
2065   &lt;/patches&gt;
2066 &lt;branch&gt;
2067 </programlisting>
2068
2069       </section>
2070
2071     </section>
2072
2073     <section id="moduleset-syntax-includes">
2074       <title>Including Other Module Sets</title>
2075
2076       <para>JHBuild allows one module set to include the contents of
2077       another by reference using the <sgmltag
2078       class="element">include</sgmltag> element.</para>
2079
2080       <programlisting>
2081 &lt;include href="<replaceable>uri</replaceable>"/&gt;
2082 </programlisting>
2083
2084       <para>The <sgmltag class="attribute">href</sgmltag> is a URI
2085       reference to the module set to be included, relative to the file
2086       containing the <sgmltag class="element">include</sgmltag>
2087       element.</para>
2088
2089       <para>Only module definitions are imported from the referenced
2090       module set - module sources are not.  Multiple levels of
2091       includes are allowed, but include loops are not (there isn't any
2092       code to handle loops at the moment).</para>
2093     </section>
2094
2095     <section id="moduleset-syntax-defs">
2096       <title>Module Definitions</title>
2097
2098       <para>There are various types of module definitions that can be
2099       used in a module set file, and the list can easily be extended.
2100       Only the most common ones will be mentioned here.</para>
2101
2102       <para>They are all basically composed of a <sgmltag
2103       class="element">branch</sgmltag> element describing how to get
2104       the module and <sgmltag class="element">dependencies</sgmltag>,
2105       <sgmltag class="element">suggests</sgmltag> and
2106       <sgmltag class="element">after</sgmltag> elements
2107       to declare the dependencies of the module.</para>
2108
2109       <para>Any modules listed
2110       in the <sgmltag class="element">dependencies</sgmltag> element
2111       will be added to the module list for <command>jhbuild
2112       build</command> if it isn't already included, and make sure
2113       the dependent modules are built first.</para>
2114
2115       <para>After generating the modules list, the modules listed in
2116       the <sgmltag class="element">suggests</sgmltag> element will
2117       be used to further sort the modules list (although it will not
2118       pull any additional modules).  This is intended for cases
2119       where a module has an optional dependency on another
2120       module.</para>
2121
2122       <section id="moduleset-syntax-defs-autotools">
2123         <title>autotools</title>
2124
2125         <para>The <sgmltag class="element">autotools</sgmltag>
2126         element is used to define a module which is compiled using
2127         the GNU Autotools build system.</para>
2128
2129         <programlisting>
2130 &lt;autotools id="<replaceable>id</replaceable>"
2131               [ autogenargs="<replaceable>autogenargs</replaceable>" ]
2132               [ makeargs="<replaceable>makeargs</replaceable>" ]
2133               [ makeinstallargs="<replaceable>makeinstallargs</replaceable>" ]
2134               [ autogen-sh="<replaceable>autogen-sh</replaceable>" ]
2135               [ makefile="<replaceable>makefile</replaceable>" ]
2136               [ skip-autogen="<replaceable>skip-autogen</replaceable>" ]
2137               [ autogen-template="<replaceable>autogen-template</replaceable>" ]
2138               [ check-target="<replaceable>check-target</replaceable>" ]
2139               [ supports-non-srcdir-builds="<replaceable>supports-non-srcdir-builds</replaceable>" ]&gt;
2140
2141   &lt;branch [ ... ] &gt;
2142     [...]
2143   &lt;/branch&gt;
2144
2145   &lt;dependencies&gt;
2146     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2147     ...
2148   &lt;/dependencies&gt;
2149   &lt;after&gt;
2150     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2151     ...
2152   &lt;/after&gt;
2153
2154 &lt;/autotools&gt;
2155 </programlisting>
2156
2157         <para>The <sgmltag class="attribute">autogenargs</sgmltag> and
2158         <sgmltag class="attribute">makeargs</sgmltag> and
2159         <sgmltag class="attribute">makeinstallargs</sgmltag>
2160         attributes are used to specify additional arguments to pass to
2161         <command>autogen.sh</command>, <command>make</command> and
2162         <command>make install</command> respectively.</para>
2163
2164         <para>The <sgmltag class="attribute">autogen-sh</sgmltag>
2165         attribute specifies the name of the autogen.sh script to run.
2166         The value <literal>autoreconf</literal> can be used if your
2167         module has no <command>autogen.sh</command> script
2168         equivalent. In that case, JHBuild will run <command>autoreconf
2169         -i</command>, followed by the proper
2170         <command>configure</command>.
2171
2172         <sgmltag class="attribute">skip-autogen</sgmltag> chooses whether
2173         or not to run autogen.sh, it is a boolean with an extra
2174         <literal>never</literal> value to tell JHBuild to never skip running
2175         <command>autogen.sh</command>.
2176         <sgmltag class="attribute">makefile</sgmltag> specifies the
2177         filename of the makefile to use.</para>
2178
2179         <para>The <sgmltag
2180         class="attribute">supports-non-srcdir-builds</sgmltag>
2181         attribute is used to mark modules that can't be cleanly built
2182         using a separate source directory.</para>
2183
2184         <para>The <sgmltag class="attribute">autogen-template</sgmltag>
2185         attribute can be used if you need finer control over the autogen
2186         command line. It is a python format string, which will be
2187         substituted with the following variables:
2188         <varname>srcdir</varname>, <varname>autogen-sh</varname>,
2189         <varname>prefix</varname>, <varname>libdir</varname>, and
2190         <varname>autogenargs</varname>. For example, here is the default
2191         autogen-template:</para>
2192
2193         <programlisting>
2194 %(srcdir)s/%(autogen-sh)s --prefix %(prefix)s --libdir %(libdir)s %(autogenargs)s
2195 </programlisting>
2196
2197         <para>The <sgmltag class="attribute">check-target</sgmltag> attribute
2198         must be specified (with false as value) for modules that do not have
2199         a <command>make check</command> target.</para>
2200
2201       </section>
2202
2203       <section id="moduleset-syntax-defs-cmake">
2204         <title>cmake</title>
2205
2206         <para>The <sgmltag class="element">cmake</sgmltag> element is used to
2207         define a module which is built using the CMake build system.</para>
2208
2209         <programlisting>
2210 &lt;cmake id="<replaceable>modulename</replaceable>"&gt;
2211   &lt;branch [ ... ] &gt;
2212     [...]
2213   &lt;/branch&gt;
2214
2215   &lt;dependencies&gt;
2216     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2217     ...
2218   &lt;/dependencies&gt;
2219   &lt;after&gt;
2220     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2221     ...
2222   &lt;/after&gt;
2223 &lt;/cmake&gt;
2224 </programlisting>
2225
2226       </section>
2227
2228       <section id="moduleset-syntax-defs-distutils">
2229         <title>distutils</title>
2230
2231         <para>The <sgmltag class="element">distutils</sgmltag> element
2232         is used to define a module which is built using python's
2233         distutils</para>
2234
2235         <programlisting>
2236 &lt;distutils id="<replaceable>modulename</replaceable>"
2237             [ supports-non-srcdir-builds="<replaceable>yes|no</replaceable>" ]&gt;
2238   &lt;branch [ ... ] &gt;
2239     [...]
2240   &lt;/branch&gt;
2241
2242   &lt;dependencies&gt;
2243     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2244     ...
2245   &lt;/dependencies&gt;
2246   &lt;after&gt;
2247     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2248     ...
2249   &lt;/after&gt;
2250 &lt;/distutils&gt;
2251 </programlisting>
2252
2253       </section>
2254
2255       <section id="moduleset-syntax-defs-linux">
2256         <title>linux</title>
2257
2258         <para>The <sgmltag class="element">linux</sgmltag>
2259         element defines a module used to build a linux kernel.
2260         In addition, a separate kernel configuration can be
2261         chosen using the <sgmltag class="element">kconfig</sgmltag>
2262         subelement.</para>
2263
2264         <programlisting>
2265 &lt;linux id="<replaceable>id</replaceable>"
2266           [ makeargs="<replaceable>makeargs</replaceable>" ]&gt;
2267
2268   &lt;branch [ ... ] &gt;
2269     [...]
2270   &lt;/branch&gt;
2271
2272   &lt;dependencies&gt;
2273     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2274     ...
2275   &lt;/dependencies&gt;
2276   &lt;after&gt;
2277     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2278     ...
2279   &lt;/after&gt;
2280
2281   &lt;kconfig [ repo="<replaceable>repo</replaceable>" ]
2282             version="<replaceable>version</replaceable>"
2283             [ module="<replaceable>module</replaceable>" ]
2284             [ config="<replaceable>config</replaceable>" ] /&gt;
2285
2286 &lt;/linux&gt;
2287 </programlisting>
2288
2289       </section>
2290
2291       <section id="moduleset-syntax-defs-perl">
2292         <title>perl</title>
2293
2294         <para>The <sgmltag class="element">perl</sgmltag> element
2295         is used to build perl modules.</para>
2296
2297         <para>The <sgmltag class="attribute">makeargs</sgmltag> attribute
2298         is used to specify additional arguments to pass to
2299         <command>make</command>.</para>
2300
2301         <programlisting>
2302 &lt;perl id="<replaceable>modulename</replaceable>"
2303          [ makeargs="<replaceable>makeargs</replaceable>" ]&gt;
2304
2305   &lt;branch [ ... ] &gt;
2306     [...]
2307   &lt;/branch&gt;
2308
2309   &lt;dependencies&gt;
2310     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2311     ...
2312   &lt;/dependencies&gt;
2313   &lt;after&gt;
2314     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2315     ...
2316   &lt;/after&gt;
2317
2318 &lt;/perl&gt;
2319 </programlisting>
2320       </section>
2321
2322       <section id="moduleset-syntax-defs-waf">
2323         <title>waf</title>
2324
2325         <para>The <sgmltag class="element">waf</sgmltag> element is used to
2326         define a module which is built using the Waf build system.</para>
2327
2328         <para>The <sgmltag class="attribute">waf-command</sgmltag> attribute
2329         is used to specify the waf command script to use; it defaults to
2330         <command>waf</command>.</para>
2331
2332         <programlisting>
2333 &lt;waf id="<replaceable>modulename</replaceable>"&gt;
2334          [ waf-command="<replaceable>waf-command</replaceable>" ]&gt;
2335   &lt;branch [ ... ] &gt;
2336     [...]
2337   &lt;/branch&gt;
2338
2339   &lt;dependencies&gt;
2340     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2341     ...
2342   &lt;/dependencies&gt;
2343   &lt;after&gt;
2344     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2345     ...
2346   &lt;/after&gt;
2347 &lt;/waf&gt;
2348 </programlisting>
2349
2350       </section>
2351
2352       <section id="moduleset-syntax-defs-ant">
2353         <title>Ant</title>
2354
2355         <para>The <sgmltag class="element">ant</sgmltag> element is used to
2356         define a module which is built using Ant, the Java based build tool.</para>
2357
2358         <programlisting>
2359 &lt;ant id="<replaceable>modulename</replaceable>"&gt;
2360   &lt;branch [ ... ] &gt;
2361     [...]
2362   &lt;/branch&gt;
2363
2364   &lt;dependencies&gt;
2365     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2366     ...
2367   &lt;/dependencies&gt;
2368   &lt;after&gt;
2369     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2370     ...
2371   &lt;/after&gt;
2372 &lt;/ant&gt;
2373 </programlisting>
2374
2375         <example id="example-ant-module">
2376           <title>Example of a module built with ant</title>
2377           <programlisting><![CDATA[
2378 <repository type="svn" name="wikimedia"
2379   href="http://svn.wikimedia.org/svnroot/"/>
2380
2381 <ant id="cortado">
2382   <branch repo="wikimedia" module="mediawiki/trunk/cortado"
2383       checkoutdir="cortado"/>
2384 </ant>]]></programlisting>
2385         </example>
2386
2387       </section>
2388
2389       <section id="moduleset-syntax-defs-testmodule">
2390         <title>testmodule</title>
2391
2392         <para>The <sgmltag class="element">testmodule</sgmltag>
2393         element is used to create a module which runs a suite of
2394         tests using LDTP or Dogtail.</para>
2395
2396         <programlisting>
2397 &lt;testmodule id="<replaceable>id</replaceable>"
2398                type="<replaceable>type</replaceable>"&gt;
2399
2400   &lt;branch [ ... ] &gt;
2401     [...]
2402   &lt;/branch&gt;
2403
2404   &lt;dependencies&gt;
2405     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2406     ...
2407   &lt;/dependencies&gt;
2408   &lt;after&gt;
2409     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2410     ...
2411   &lt;/after&gt;
2412
2413   &lt;testedmodules&gt;
2414     &lt;tested package="<replaceable>package</replaceable>" /&gt;
2415   &lt;/testedmodules&gt;
2416
2417 &lt;/testmodule&gt;
2418 </programlisting>
2419
2420       </section>
2421
2422       <section id="moduleset-syntax-defs-metamodule">
2423         <title>metamodule</title>
2424
2425         <para>The <sgmltag class="element">metamodule</sgmltag>
2426         element defines a module that doesn't actually do anything.
2427         The only purpose of a module of this type is its
2428         dependencies.</para>
2429
2430         <para>For example, meta-gnome-desktop depends on all the key
2431         components of the GNOME desktop, therefore telling JHBuild to
2432         install it actually installs the full desktop.</para>
2433
2434         <programlisting>
2435 &lt;metamodule id="<replaceable>modulename</replaceable>"&gt;
2436   &lt;dependencies&gt;
2437     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2438     ...
2439   &lt;/dependencies&gt;
2440   &lt;suggests&gt;
2441     &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2442     ...
2443   &lt;/suggests&gt;
2444 &lt;/metamodule&gt;
2445 </programlisting>
2446         <para>The <sgmltag class="attribute">id</sgmltag> attribute
2447         gives the name of the module.  The child elements are handled
2448         as for <link
2449         linkend="moduleset-syntax-defs-autotools"><sgmltag
2450         class="element">autotools</sgmltag></link>.</para>
2451       </section>
2452     </section>
2453
2454     <section id="moduleset-deprecated-elements">
2455       <title>Deprecated Elements</title>
2456
2457       <section id="moduleset-deprecated-elements-syntax-sources">
2458         <title>Module Sources</title>
2459
2460         <section id="moduleset-syntax-sources-cvsroot">
2461           <title>cvsroot</title>
2462
2463           <para>The <sgmltag class="element">cvsroot</sgmltag> element
2464           is now deprecated - the
2465           <sgmltag class="element">repository</sgmltag> element should
2466           be used instead.</para>
2467
2468           <para>The <sgmltag class="element">cvsroot</sgmltag> element
2469           is used to describe a CVS repository.</para>
2470
2471           <programlisting>
2472   &lt;cvsroot name="<replaceable>rootname</replaceable>"
2473            [ default="<replaceable>yes|no</replaceable>" ]
2474            root="<replaceable>anon-cvsroot</replaceable>"
2475            password="<replaceable>anon-password</replaceable>"/&gt;
2476 </programlisting>
2477
2478           <para>The <sgmltag class="attribute">name</sgmltag> attribute
2479           should be a unique identifier for the CVS repository.</para>
2480
2481           <para>The <sgmltag class="attribute">default</sgmltag>
2482           attribute says whether this is the default module source for
2483           this module set file.</para>
2484
2485           <para>The <sgmltag class="attribute">root</sgmltag> attribute
2486           lists the CVS root used for anonymous access to this
2487           repository, and the <sgmltag
2488           class="attribute">password</sgmltag> attribute gives the
2489           password used for anonymous access.</para>
2490         </section>
2491
2492         <section id="moduleset-syntax-sources-svnroot">
2493           <title>svnroot</title>
2494
2495           <para>The <sgmltag class="element">svnroot</sgmltag> element
2496           is now deprecated - the
2497           <sgmltag class="element">repository</sgmltag> element should
2498           be used instead.</para>
2499
2500           <para>The <sgmltag class="element">svnroot</sgmltag> element
2501           is used to describe a Subversion repository.</para>
2502
2503           <programlisting>
2504   &lt;svnroot name="<replaceable>rootname</replaceable>"
2505            [ default="<replaceable>yes|no</replaceable>" ]
2506            href="<replaceable>anon-svnroot</replaceable>"/&gt;
2507 </programlisting>
2508
2509           <para>The <sgmltag class="attribute">name</sgmltag> attribute
2510           should be a unique identifier for the Subversion
2511           repository.</para>
2512
2513           <para>If <sgmltag class="attribute">default</sgmltag>
2514           attribute says whether this is the default module source for
2515           this module set file.</para>
2516
2517           <para>The <sgmltag class="attribute">href</sgmltag> attribute
2518           lists the base URL for the repository.  This will probably be
2519           either a <literal>http</literal>, <literal>https</literal> or
2520           <literal>svn</literal> URL.</para>
2521         </section>
2522
2523         <section id="moduleset-syntax-sources-arch-archive">
2524           <title>arch-archive</title>
2525
2526           <para>The <sgmltag class="element">arch-archive</sgmltag> element
2527           is now deprecated - the
2528           <sgmltag class="element">repository</sgmltag> element should
2529           be used instead.</para>
2530
2531           <para>The <sgmltag class="element">arch-archive</sgmltag> element
2532           is used to describe a GNU Arch archive.</para>
2533
2534           <programlisting>
2535   &lt;arch-archive name="<replaceable>archivename</replaceable>"
2536                 [ default="<replaceable>yes|no</replaceable>" ]
2537                 href="<replaceable>mirror-url</replaceable>"/&gt;
2538 </programlisting>
2539
2540           <para>The <sgmltag class="attribute">name</sgmltag> attribute
2541           should be the Arch archive name.</para>
2542
2543           <para>If <sgmltag class="attribute">default</sgmltag>
2544           attribute says whether this is the default module source for
2545           this module set file.</para>
2546
2547           <para>The <sgmltag class="attribute">href</sgmltag> attribute
2548           lists a public mirror URL for the archive.</para>
2549         </section>
2550       </section> <!-- end of deprecated module sources -->
2551
2552       <section>
2553         <title>Deprecated Module Types</title>
2554
2555         <warning>
2556         <para>This section describes deprecated elements, they may still be
2557         used in existing module sets but it is advised not to use them anymore.
2558         </para>
2559         </warning>
2560
2561         <section id="moduleset-syntax-defs-tarball">
2562           <title>tarball</title>
2563
2564           <important>
2565             <para>This deprecated element is just a thin wrapper
2566             around both <sgmltag class="element">autotools</sgmltag> module type
2567             and <sgmltag class="element">tarball</sgmltag> repository type.
2568           </para>
2569           </important>
2570
2571           <para>The <sgmltag class="element">tarball</sgmltag> element
2572           is used to define a module that is to be built from
2573           a tarball.</para>
2574
2575           <programlisting>
2576   &lt;tarball id="<replaceable>modulename</replaceable>"
2577               [ version="<replaceable>version</replaceable>" ]
2578               [ checkourdir="<replaceable>checkoutdir</replaceable>" ]
2579               [ autogenargs="<replaceable>autogenargs</replaceable>" ]
2580               [ makeargs="<replaceable>makeargs</replaceable>" ]
2581               [ autogen-sh="<replaceable>autogen-sh</replaceable>" ]
2582               [ supports-non-srcdir-builds="<replaceable>yes|no</replaceable>" ]&gt;
2583     &lt;source href="<replaceable>source-url</replaceable>"
2584             [ size="<replaceable>source-size</replaceable>" ]
2585             [ hash="<replaceable>source-algo:source-hash</replaceable>" ]
2586             [ md5sum="<replaceable>source-md5sum</replaceable>" ]/&gt;
2587     &lt;patches&gt;
2588       &lt;patch file="<replaceable>filename</replaceable>" strip="<replaceable>level</replaceable>"/&gt;
2589       ...
2590     &lt;/patches&gt;
2591     &lt;dependencies&gt;
2592       &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2593       ...
2594     &lt;/dependencies&gt;
2595     &lt;suggests&gt;
2596       &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
2597       ...
2598     &lt;/suggests&gt;
2599   &lt;/tarball&gt;
2600 </programlisting>
2601           <para>The <sgmltag class="attribute">id</sgmltag> and <sgmltag
2602           class="attribute">version</sgmltag> attributes are used to
2603           identify the module.</para>
2604
2605           <para>The <sgmltag class="element">source</sgmltag> element
2606           specifies the file to download and compile.  The <sgmltag
2607           class="attribute">href</sgmltag> attribute is mandatory, while
2608           the <sgmltag class="attribute">size</sgmltag> and <sgmltag
2609           class="attribute">hash</sgmltag>, as well as the obsolete
2610           <sgmltag class="attribute">md5sum</sgmltag>, attributes are optional.
2611           If these last two attributes are present, they are used to check
2612           that the source package was downloaded correctly.</para>
2613
2614           <para>The <sgmltag class="element">patches</sgmltag> element
2615           is used to specify one or more patches to apply to the source
2616           tree after unpacking, the <sgmltag class="attribute">file</sgmltag>
2617           attribute gives the patch filename, and the <sgmltag
2618           class="attribute">strip</sgmltag> attribute says how
2619           many levels of directories to prune when applying the
2620           patch.</para>
2621
2622           <para>For module sets shipped with JHBuild, the patch files are
2623           looked up in the <filename>jhbuild/patches/</filename> directory;
2624           for module sets referred by URI, the patch files are looked for
2625           in the same directory as the moduleset file, or in its
2626           <filename>patches/</filename> subdirectory.  It is also possible
2627           for the <sgmltag class="attribute">file</sgmltag> attribute to
2628           specify a URI, in which case it will be downloaded from that location.
2629           </para>
2630
2631
2632           <para>
2633             The other attributes and the <sgmltag class="element">dependencies</sgmltag>,
2634             <sgmltag class="element">suggests</sgmltag> and <sgmltag
2635             class="element">after</sgmltag> elements are processed as for <link
2636             linkend="moduleset-syntax-defs-autotools">autotools</link>.
2637           </para>
2638         </section>
2639       </section> <!-- end of deprecated module types -->
2640     </section> <!-- end of deprecated elements -->
2641   </section>
2642
2643   <section id="faq">
2644     <title>Frequently Asked Questions</title>
2645
2646     <qandaset defaultlabel="qanda">
2647       <qandadiv>
2648         <title>General JHBuild Questions</title>
2649         <qandaentry>
2650           <question>
2651             <simpara>The <command>wget</command> command can't
2652             download any tarballs.  How do I get it to work with my
2653             firewall?</simpara>
2654           </question>
2655           <answer>
2656             <para>Create <filename>~/.wgetrc</filename> file.  If an HTTP
2657         proxy is used to access FTP sites, add a line like
2658             the following to the file:</para>
2659             <programlisting>ftp_proxy = http://<replaceable>hostname</replaceable>:<replaceable>port</replaceable>/</programlisting>
2660             <para>If passive FTP connections are required
2661             (sometimes needed with NAT firewalls), add the following
2662             line:</para>
2663             <programlisting>passive_ftp = on</programlisting>
2664           </answer>
2665         </qandaentry>
2666         <qandaentry>
2667           <question>
2668             <simpara>Building is slow.  Is there any way I can
2669             speed it up?</simpara>
2670           </question>
2671           <answer>
2672             <para><ulink url="http://ccache.samba.org/">CCache</ulink>
2673         can speed up compilations, as it caches compilation results.
2674         <command>CCache</command> is available with most distributions.
2675         </para>
2676             <para>Set the cache size with the following command:</para>
2677             <programlisting>ccache -M 2G</programlisting>
2678             <para>(where <literal>2G</literal> is the size the cache).
2679         Create symlinks to <command>CCache</command> for
2680             the compiler in <filename>~/bin</filename>:</para>
2681             <programlisting>cd ~/bin
2682 for cmd in cc gcc c++ g++; do
2683   ln -s /usr/bin/ccache $cmd
2684 done</programlisting>
2685             <para>It is possible to check the status of the cache
2686             including cache hit rates with the following command:</para>
2687             <programlisting>ccache -s</programlisting>
2688           </answer>
2689         </qandaentry>
2690         <qandaentry>
2691           <question>
2692             <simpara>Is there a better way to monitor the status of
2693             the build than looking at terminal window?</simpara>
2694           </question>
2695           <answer>
2696             <para>If Zenity >= 2.9 is installed on your system,
2697             JHBuild will display an icon in the system tray.  The icon
2698             will display the current build stage, and the tooltip will
2699             show the last message from JHBuild.</para>
2700             <para>The icon will also pop up a balloon on error.</para>
2701           </answer>
2702         </qandaentry>
2703       </qandadiv>
2704       <qandadiv>
2705         <title>Building GNOME</title>
2706         <qandaentry>
2707           <question>
2708             <simpara>What other prerequisites are needed to build GNOME
2709             with JHBuild?</simpara>
2710           </question>
2711           <answer>
2712             <para>Some of the packages required include:</para>
2713             <itemizedlist>
2714               <listitem>
2715                 <simpara>DocBook XML DTD and XSLT stylesheets.  These
2716                 need to be registered in the XML catalog
2717                 (<filename>/etc/xml/catalog</filename>).</simpara>
2718               </listitem>
2719               <listitem>
2720                 <simpara>X libraries</simpara>
2721               </listitem>
2722               <listitem>
2723                 <simpara>fam or gamin (used by gnome-vfs for file
2724                 monitoring).</simpara>
2725               </listitem>
2726               <listitem>
2727                 <simpara><filename>libsmbclient</filename> from Samba
2728                 (used for browsing Windows networks).</simpara>
2729               </listitem>
2730               <listitem>
2731               <simpara><filename>libbz2</filename> from
2732                 bzip2.</simpara>
2733               </listitem>
2734               <listitem>
2735                 <simpara><filename>libpng</filename>,
2736                 <filename>libjpeg</filename> and
2737                 <filename>libtiff</filename> (used for image
2738                 loading).</simpara>
2739               </listitem>
2740             </itemizedlist>
2741             <para>If installing distribution packages, and if applicable
2742         for your distribution, install the corresponding
2743         <quote>dev</quote> or <quote>devel</quote> packages.  A list of
2744             <ulink url="http://live.gnome.org/JhbuildDependencies">package
2745             names</ulink> for different distributions is maintained on the
2746             GNOME wiki.</para>
2747           </answer>
2748         </qandaentry>
2749         <qandaentry>
2750           <question>
2751             <simpara>I've built GNOME with JHBuild.  How do I run
2752             it?</simpara>
2753           </question>
2754           <answer>
2755         <para>Two options:</para>
2756             <orderedlist>
2757                   <listitem>
2758                         <para>Without JHBuild <application>HAL</application>
2759             and <application>D-Bus</application>. This method requires
2760             support from the display manager (e.g.
2761             <application>GDM</application>,
2762             <application>KDM</application>,
2763             <application>XDM</application>).
2764             Create a <filename>~/.xsession</filename> file, with the
2765             following contents:</para>
2766                         <programlisting>#!/bin/sh
2767 exec jhbuild run gnome-session</programlisting>
2768                         <para>Set the <filename>~/.xsession</filename> file to be
2769             executable. At log in, set the session to
2770             <guilabel>custom</guilabel>.
2771             If the display manager does not have a
2772             <guilabel>custom</guilabel> option, refer to answer
2773             <xref linkend="faq-built-hal"/> below.
2774             </para>
2775                   </listitem>
2776           <listitem id="faq-built-hal">
2777             <para>With JHBuild <application>HAL</application> and
2778             <application>D-Bus</application>.
2779             <application>HAL</application> and
2780             <application>D-Bus</application> are
2781             daemons provided with your distribution. They are
2782                 most likely already running, but may be unusable by the
2783             GNOME development version as they are too old or
2784             incompatible.</para>
2785             <para>Create a session script that is run
2786             when you log in using a display manager
2787             (e.g. <application>GDM</application>,
2788             <application>KDM</application>,
2789             <application>XDM</application>).
2790             The session script starts <command>hal</command> and
2791             <command>d-bus</command>
2792             from the JHBuild installation in addition to the
2793             system-wide versions.</para>
2794             <programlisting>
2795 GNOME=/opt/gnome2
2796
2797 GDK_USE_XFT=1
2798 #XDG_DATA_DIRS=$XDG_DATA_DIRS:$GNOME/share
2799 #XDG_CONFIG_DIRS=$XDG_CONFIG_DIRS:$GNOME/etc/xdg
2800
2801 DBUS_LAUNCH="$GNOME/bin/dbus-launch --exit-with-session"
2802
2803 sudo su -c "$GNOME/bin/dbus-daemon --system; \
2804                    $GNOME/sbin/hald"
2805
2806 jhbuild run $DBUS_LAUNCH gnome-session</programlisting>
2807             <para> Adjust the variable <varname>GNOME</varname>
2808             to your local settings. Uncomment the
2809             <varname>XDG_</varname> lines for system-wide
2810             program menus in addition to the menus from the JHBuild
2811             GNOME. Save the script as
2812             <filename>/usr/bin/gnome-jhbuild-session</filename> or
2813             any other name of your choosing. Set the
2814             file to be executable.</para>
2815             <para>As the script starts system daemons, root privileges
2816             are required obtained via <command>sudo</command>. The
2817             script requires <command>sudo</command> to be configured
2818             so it doesn't prompt for a password. Run
2819             <command>visudo</command> as root and enter the
2820             following, changing username and paths as appropriate:
2821             </para>
2822             <programlisting>
2823 # Cmnd alias specification
2824 Cmnd_Alias  GNOME =  /opt/gnome2/bin/dbus-daemon, \
2825                      /opt/gnome2/sbin/hald
2826
2827 # User privilege specification
2828 gnometester  ALL = NOPASSWD: GNOME</programlisting>
2829             <para>To add a new session entry in the display
2830             manager, create
2831             <filename>/usr/share/xsessions/gnome-jhbuild.desktop</filename>
2832             and enter:</para>
2833             <programlisting>
2834 [Desktop Entry]
2835 Encoding=UTF-8
2836 Name=GNOME (JHBuild)
2837 Comment=This session logs you into GNOME testing session
2838 Exec=/usr/bin/gnome-jhbuild-session
2839 Icon=
2840 Type=Application</programlisting>
2841             <para>Restart <command>gdm</command> and log into your
2842             JHBuild GNOME. Select the JHBuild session before
2843             entering the login credentials. Using separate user
2844             account is recommended for testing.</para>
2845           </listitem>
2846         </orderedlist>
2847           </answer>
2848         </qandaentry>
2849         <qandaentry>
2850           <question>
2851             <simpara>I built GNOME using JHBuild with
2852             <varname>prefix</varname> set to <filename>/usr</filename>,
2853             and now my system is broken.  What should I do?</simpara>
2854           </question>
2855           <answer>
2856             <para>Don't set <varname>prefix</varname> to
2857             <filename>/usr</filename>.</para>
2858           </answer>
2859         </qandaentry>
2860         <qandaentry>
2861           <question>
2862             <simpara>How do I get
2863             <command>gnome-volume-manager</command> to work when
2864             running JHBuild GNOME?</simpara>
2865           </question>
2866           <answer>
2867             <para>The <command>gnome-volume-manager</command> program
2868             reacts to messages from <command>hald</command> over the
2869             system message bus, which must be running as root.
2870             Assuming that your distribution comes with
2871             <acronym>HAL</acronym>, the main problem is getting
2872             <command>gnome-volume-manager</command> to talk to the
2873             system message bus.</para>
2874             <para>As communication is over a UNIX domain
2875             socket, the easiest way is to create a symlink
2876             from <filename>/var/run/dbus</filename> to
2877             <filename>$prefix/var/run/dbus</filename>:</para>
2878             <programlisting>mkdir -p $prefix/var/run
2879 cd $prefix/var/run
2880 ln -s /var/run/dbus dbus</programlisting>
2881         <para>You may also have trouble building HAL with JHBuild,
2882         since it tries to install some things outside of its build
2883         root.  Running <userinput>make -k install</userinput> in
2884         the hal directory might help here.</para>
2885           </answer>
2886         </qandaentry>
2887       </qandadiv>
2888     </qandaset>
2889   </section>
2890 </article>