<?xml version="1.0" standalone="no"?><!--*- mode: nxml -*-->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- process to HTML with: xmlto xhtml-nochunks -m ../custom.xsl index.docbook -->
<article id="index">
  <articleinfo>
    <title>JHBuild Manual</title>
    <authorgroup>
      <author role="maintainer">
        <firstname>James</firstname>
        <surname>Henstridge</surname>
      </author>
      <author>
        <firstname>C.J.</firstname>
        <surname>Adams-Collier</surname>
      </author>
      <author>
        <firstname>Frederic</firstname>
        <surname>Peters</surname>
      </author>
      <author>
        <firstname>David</firstname>
        <surname>Turner</surname>
      </author>
    </authorgroup>
    <copyright>
      <year>2004, 2008</year>
      <holder>James Henstridge</holder>
    </copyright>
    <revhistory>
      <revision>
        <revnumber>JHBuild Manual v0.5</revnumber>
        <date>January 2008</date>
      </revision>
      <revision>
        <revnumber>JHBuild Manual v0.1</revnumber>
        <date>August 2007</date>
      </revision>
    </revhistory>
    <abstract role="description">
      <para>JHBuild is a tool used to build the whole GNOME desktop from the
        version control system. JHBuild can also be customized to build other
        projects too.</para>
    </abstract>
  </articleinfo>

  <section id="introduction">
    <title>Introduction</title>

    <para>JHBuild is a tool designed to ease building collections of source
      packages, called <quote>modules</quote>. JHBuild uses <quote>module
      set</quote> files to describe the modules available to build. The
      <quote>module set</quote> files include dependency information that allows
      JHBuild to discover what modules need to be built and in what order.
    </para>

    <para>JHBuild was originally written for building
      <ulink url="http://www.gnome.org">GNOME</ulink>, but has since been
      extended to be usable with other projects. A <quote>module set</quote>
      file can be hosted on a web server, allowing for build rules independent
      of the JHBuild project.</para>

    <para>JHBuild can build modules from a variety of sources, including
      <ulink url="http://www.cvshome.org/">CVS</ulink>,
      <ulink url="http://subversion.tigris.org/">Subversion</ulink>,
      <ulink url="http://www.bazaar-vcs.org/">Bazaar</ulink>,
      <ulink url="http://darcs.net/">Darcs</ulink>,
      <ulink url="http://git.or.cz/">Git</ulink> and
      <ulink url="http://www.selenic.com/mercurial/">Mercurial</ulink>
      repositories, as well as Tar and Zip archives hosted on web or FTP sites.
      JHBuild can build modules using a variety of build systems, including
      Autotools, CMake, WAF, Python Distutils and Perl Makefiles.</para>

    <para>JHBuild is not intended as a replacement for the distribution's
      package management system. Instead, it makes it easy to build software
      into a separate install prefix without interfering with the rest of the
      system.</para>
  </section>

  <section id="getting-started">
    <title>Getting Started</title>

    <para>JHBuild requires a few set up steps to be run before building
      software. JHBuild requires some prerequisite software, and it is necessary
      to install prerequisite tools needed to obtain and build the software
      modules.</para>

    <section id="getting-started-install">
      <title>Installing JHBuild</title>

      <para>JHBuild requires a Python runtime. Verify Python &gt;= 2.3 is
        installed.</para>

      <para>The recommended way to download JHBuild is via the version control
        system, <command>git</command>. This can be achieved with the following
        command. It is recommended to run the command from a new directory where
        all source code will be installed, for example,
        <filename>~/checkout/gnome</filename>.</para>

<screen><prompt>$</prompt> <userinput>git clone git://git.gnome.org/jhbuild</userinput>
<computeroutput>...</computeroutput>
<prompt>$</prompt></screen>

      <para>This will download JHBuild into a new folder named
        <filename>jhbuild</filename> under the current directory. Now to build
        and install JHBuild:</para>

<screen><prompt>$</prompt> <userinput>cd jhbuild</userinput>
<prompt>$</prompt> <userinput>./autogen.sh</userinput>
<computeroutput>...</computeroutput>
<prompt>$</prompt> <userinput>make</userinput>
<computeroutput>...</computeroutput>
<prompt>$</prompt> <userinput>make install</userinput>
<computeroutput>...</computeroutput>
<prompt>$</prompt></screen>

      <para>If <application>gnome-common</application>,
        <application>yelp-tools</application> and
        <application>autotools</application> are available,
        <filename>autogen.sh</filename> will configure JHBuild to install via
        <application>autotools</application>. If
        <application>gnome-common</application>,
        <application>yelp-tools</application> and
        <application>autotools</application> are not available,
        <filename>autogen.sh</filename> will configure JHBuild to install via a
        plain Makefile. To always use the plain Makefile method pass
        <option>--simple-install</option> to <filename>autogen.sh</filename>.
      </para>

      <para>If the above steps complete successfully, a small shell script
        will be installed in <filename>~/.local/bin</filename> to start JHBuild.
        Add <filename>~/.local/bin</filename> to the <envar>PATH</envar>:</para>

<screen><prompt>$</prompt> <userinput>PATH=$PATH:~/.local/bin</userinput>
<prompt>$</prompt></screen>

      <para>To permanently add <filename>~/.local/bin</filename> to the
        <envar>PATH</envar> variable, run the following command:</para>

<screen>
<prompt>$</prompt> <userinput>echo PATH=$PATH:~/.local/bin >> ~/.bashrc</userinput>
<prompt>$</prompt></screen>

    </section>

    <section id="getting-started-configure">
      <title>Configuring JHBuild</title>

      <para>JHBuild can be configured via a configuration file. The default
        location is <filename>~/.config/jhbuildrc</filename>. If a configuration
        file does not exist, the defaults are used. The configuration file uses
        Python syntax. An example is provided, see
        <filename>examples/sample.jhbuildrc</filename>. Copy
        <filename>examples/sample.jhbuildrc</filename> to
        <filename>~/.config/jhbuildrc</filename> and customize as required.
      </para>

      <para>The sample configuration will make JHBuild build the
        <application>meta-gnome-core</application> and
        <application>meta-gnome-apps-tested</application> modules and
        dependencies from the <systemitem>gnome-apps</systemitem> module set.
        JHBuild will unpack source trees to
        <filename>~/checkout/gnome</filename> and install all files to
        subdirectories of <filename>/opt/gnome</filename>. The two directories
        must be writable.</para>

      <para>Configuration variables are documented in
        <xref linkend="config-reference"/>. The most commonly used variables
        are:</para>

      <variablelist>
<?dbhtml list-presentation="table"?>
        <varlistentry>
          <term>
            <link linkend="cfg-repos"><varname>repos</varname></link>
          </term>
          <listitem>
            <simpara>A dictionary that can be used to specify an alternative
              repository location for a particular repository. This
              configuration variable is useful to a module developer. By
              default, JHBuild will check out code from repositories using an
              anonymous repository location. The dictionary keys are short
              repository names and the values are alternative repository
              location strings. For example:</simpara>

<programlisting>repos['git.gnome.org'] = 'ssh://<replaceable>username</replaceable>@git.gnome.org/git/'</programlisting>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <link linkend="cfg-moduleset"><varname>moduleset</varname></link>
          </term>
          <listitem>
            <simpara>A string or list of strings specifying the name(s) of the
              module set(s) to use. This can either be the filename of a
              moduleset included with JHBuild (excluding the path and
              extension), or a full HTTP URL to an externally managed moduleset.
              HTTP URL modulesets are cached locally. If a module with the same
              name is present in more than one moduleset, the last set listed
              takes priority. Modulesets provided with JHBuild are updated to
              match the current GNOME development release.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <link linkend="cfg-modules"><varname>modules</varname></link>
          </term>
          <listitem>
            <simpara>A list of strings specifying the modules to build. The
              list of modules actually built will be recursively expanded to
              include all the dependencies unless the
              <link linkend="command-reference-buildone">
              <command>buildone</command></link> command is used. Defaults to
              <literal>['meta-gnome-desktop']</literal>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <link linkend="cfg-checkoutroot"><varname>checkoutroot</varname></link>
          </term>
          <listitem>
            <simpara>A string specifying the directory to unpack source trees
              to. Unless <link linkend="cfg-buildroot">
              <varname>buildroot</varname></link> is set, builds will occur in
              this directory too. Defaults to
              <filename>~/checkout/gnome</filename>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <link linkend="cfg-prefix"><varname>prefix</varname></link>
          </term>
          <listitem>
            <simpara>A string specifying the prefix to install modules to.
              <varname>prefix</varname> must be an absolute path. This directory
              must be writable. Defaults to <literal>'/opt/gnome'</literal>.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <link linkend="cfg-autogenargs"><varname>autogenargs</varname></link>
          </term>
          <listitem>
            <simpara>A string containing arguments passed to the
              <command>autogen.sh</command> script of all modules. Can be
              overridden for particular modules using the
              <link linkend="cfg-module-autogenargs">
              <varname>module_autogenargs</varname></link> dictionary.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <link linkend="cfg-makeargs"><varname>makeargs</varname></link>
          </term>
          <listitem>
            <simpara>A string listing additional arguments to be passed to
              <command>make</command>. Defaults to <literal>''</literal>.
            </simpara>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section id="getting-started-bootstrap">
      <title>Build Prerequisites</title>

      <para>Before any modules can be built, it is necessary to have certain
        build tools installed. Common build tools include the GNU Autotools
        (<application>autoconf</application>,
        <application>automake</application>, <application>libtool</application>
        and <application>gettext</application>), The GNU Toolchain
        (<application>binutils</application>, <application>gcc</application>,
        <application>g++</application>), make, pkg-config and Python, depending
        on which modules will be built.</para>

      <para>JHBuild can check the tools are installed using the
        <command>sanitycheck</command> command:</para>

<screen><prompt>$</prompt> <userinput>jhbuild sanitycheck</userinput></screen>

      <para>If this command displays any messages, please install the required
        package from your distribution's repository. A list of
        <ulink url="http://live.gnome.org/JhbuildDependencies">package names
        </ulink> for different distributions is maintained on the GNOME wiki.
        Run the <command>sanitycheck</command> command again after installing
        the distribution's packages to ensure the required tools are present.
      </para>
    </section>

    <section id="getting-started-use">
      <title>Using JHBuild</title>

      <para>After set up is complete, JHBuild can be used to build software.
        To build all the modules selected in the
        <filename>~/.config/jhbuildrc</filename> file, run the following
        command:</para>

<screen><prompt>$</prompt> <userinput>jhbuild build</userinput></screen>

      <para>JHBuild will download, configure, compile and install each of the
        modules. If an error occurs at any stage, JHBuild will present a menu
        asking what to do. The choices include dropping to a shell to fix the
        error, rerunning the build from various stages, giving up on the module,
        or ignore the error and continue.</para>

      <note>
        <simpara>Giving up on a module will cause any modules depending on the
          module to fail.</simpara>
      </note>

      <para>Below is an example of the menu displayed:</para>

<screen>  [1] Rerun phase build
  [2] Ignore error and continue to install
  [3] Give up on module
  [4] Start shell
  [5] Reload configuration
  [6] Go to phase "wipe directory and start over"
  [7] Go to phase "configure"
  [8] Go to phase "clean"
  [9] Go to phase "distclean"
<prompt>choice:</prompt> </screen>

      <para>It is also possible to build a different set of modules and their
        dependencies by passing the module names as arguments to the
        <command>build</command> command. For example, to build gtk+:</para>

<screen><prompt>$</prompt> <userinput>jhbuild build gtk+</userinput></screen>

      <para>If JHBuild is cancelled part way through a build, it is possible
        to resume the build at a particular module using the
        <option>--start-at</option> option:</para>

<screen><prompt>$</prompt> <userinput>jhbuild build --start-at=pango</userinput></screen>

      <para>To build one or more modules, ignoring their dependencies, JHBuild
        provides the <command>buildone</command> command. For the
        <command>buildone</command> command to complete successfully, all
        dependencies must be previously built and installed or provided by
        distribution packages.</para>

<screen><prompt>$</prompt> <userinput>jhbuild buildone gtk+</userinput></screen>

      <para>When actively developing a module, you are likely in a source
        working directory. The <command>make</command> will invoke the build
        system and install the module. This will be a key part of your
        edit-compile-install-test cycle.</para>

<screen><prompt>$</prompt> <userinput>jhbuild make</userinput></screen>

      <para>If JHBuild is cancelled part way through a build, it is possible
        to resume the build at a particular module using the
        <option>--start-at</option> option:</para>

      <para>To get a list of the modules and dependencies JHBuild will build,
        and the order they will be built, use the <command>list</command>
        command:</para>

<screen><prompt>$</prompt> <userinput>jhbuild list</userinput></screen>

      <para>To get information about a particular module, use the
        <command>info</command> command:</para>

<screen><prompt>$</prompt> <userinput>jhbuild info gtk+</userinput></screen>

      <para>To download or update all the software sources without building,
        use the <command>update</command> command. The <command>update</command>
        command provides an opportunity to modify the sources before building
        and can be useful if internet bandwidth varies.</para>

<screen><prompt>$</prompt> <userinput>jhbuild update</userinput></screen>

      <para>Later, JHBuild can build everything without downloading or
        updating the sources:</para>

<screen><prompt>$</prompt> <userinput>jhbuild build --no-network</userinput></screen>

      <para>To run a particular command with the same environment used by
        JHBuild, use the <command>run</command> command:</para>

<screen><prompt>$</prompt> <userinput>jhbuild run <replaceable>program</replaceable></userinput></screen>

      <para>To start a shell with the same environment used by JHBuild, use
        the <command>shell</command> command:</para>

<screen><prompt>$</prompt> <userinput>jhbuild shell</userinput></screen>
    </section>
  </section>

  <section id="jhbuild-and-gnome">
    <title>JHBuild and GNOME</title>

    <para>This section provides guidance on building, installing and running
      GNOME.</para>

    <section id="building-gnome">
      <title>Building GNOME</title>

      <para>To build GNOME some development packages are required. This
        includes:</para>

      <itemizedlist>
        <listitem>
          <simpara>DocBook XML DTD and XSLT stylesheets. These need to be
            registered in the XML catalog
            (<filename>/etc/xml/catalog</filename>).</simpara>
        </listitem>
        <listitem>
          <simpara>X libraries</simpara>
        </listitem>
        <listitem>
          <simpara><filename>libsmbclient</filename> from Samba (used for
            browsing Windows networks).</simpara>
        </listitem>
        <listitem>
          <simpara><filename>libbz2</filename> from bzip2.</simpara>
        </listitem>
        <listitem>
          <simpara><filename>libpng</filename>, <filename>libjpeg</filename>
            and <filename>libtiff</filename> (used for image loading).</simpara>
        </listitem>
      </itemizedlist>

      <para>If installing distribution packages, and if applicable for your
        distribution, install the corresponding <quote>dev</quote> or
        <quote>devel</quote> packages. A list of
        <ulink url="http://live.gnome.org/JhbuildDependencies">package
        names</ulink> for different distributions is maintained on the GNOME
        wiki.</para>
    </section>

    <section id="running-single-application">
      <title>Running a Single GNOME Application</title>

      <para>This section details how to run a single GNOME application. The
        application will run within the current desktop environment. To run the
        application within the complete JHBuild GNOME see
        <xref linkend="running-gnome"/>.</para>

      <para>Launch a JHBuild shell. The JHBuild shell has all the necessary
        environment variables set.</para>

<screen><prompt>$ </prompt><userinput>jhbuild shell</userinput></screen>

      <para>Verify the correct application will be run. For example:</para>

<screen><prompt>$ </prompt><userinput>which gedit</userinput>
/opt/gnome/bin/gedit</screen>

      <para>Run the application:</para>

<screen><prompt>$ </prompt><userinput>gedit &amp;</userinput></screen>

      <para>Alternatively, run the application using the
        <command>run</command> command:</para>

<screen><prompt>$ </prompt><userinput>jhbuild run gedit</userinput></screen>
    </section>

    <section id="running-gnome">
      <title>Running the GNOME Desktop Environment</title>

      <para>Create a new user account to run the JHBuild GNOME. Running
        JHBuild GNOME using different user account is recommended to avoid
        problems caused by user settings stored in the home directory. This
        manual refers to the new account as
        <systemitem class="username">gnomedev</systemitem>.</para>

      <para>Setup JHBuild on the new
        <systemitem class="username">gnomedev</systemitem> account. Copy or
        soft-link <filename>~/.config/jhbuildrc</filename> and
        <filename>~/.local/bin/jhbuild</filename> to
        <systemitem class="username">gnomedev</systemitem> home directory.
      </para>

      <para>Open a terminal as the user
        <systemitem class="username">gnomedev</systemitem>. Permanently add
        <filename>~/.local/bin</filename> to the <envar>PATH</envar> variable,
        run the following command:</para>

<screen><prompt>$</prompt> <userinput>echo PATH=$PATH:~/.local/bin &gt;&gt; ~/.bashrc</userinput></screen>

      <para>Test JHBuild works:</para>

<screen><prompt>$</prompt> <userinput>jhbuild run pkg-config gtk+-2.0 --modversion</userinput>
2.20.1</screen>

      <section>
        <title>Setup GNOME to run from the display manager</title>

        <para>Build and install JHBuild GNOME.</para>

        <para>Enable system services. JHBuild GNOME will use the
          <filename>/usr/bin</filename> system <application>D-Bus</application>
          daemon and the system services within
          <filename>/usr/share/dbus-1/system-services/</filename>. JHBuild GNOME
          will use the JHBuild session <application>D-Bus</application> daemon
          and the services within
          <filename><replaceable>/opt/gnome</replaceable>/share/dbus-1/services/</filename>.
          Replace <filename>/opt/gnome</filename> with GNOME install
          <varname>prefix</varname> in the command below:</para>

<screen><prompt>$ </prompt><userinput>rm -rf <replaceable>/opt/gnome</replaceable>/var/run/dbus</userinput>
<prompt>$ </prompt><userinput>ln -s /var/run/dbus <replaceable>/opt/gnome</replaceable>/var/run/dbus</userinput>
<prompt>$ </prompt><userinput>rm -rf <replaceable>/opt/gnome</replaceable>/var/lib/dbus/machine-id</userinput>
<prompt>$ </prompt><userinput>ln -s /var/lib/dbus/machine-id <replaceable>/opt/gnome</replaceable>/var/lib/dbus/machine-id</userinput></screen>

        <para>Create a GNOME startup script at
          <filename>/usr/bin/gnome-jhbuild-session</filename> with the
          following, replacing <filename>/opt/gnome</filename> with GNOME
          install <varname>prefix</varname>:</para>

<programlisting>#!/bin/sh

GNOME=<replaceable>/opt/gnome</replaceable>
 
GDK_USE_XFT=1
XDG_DATA_DIRS=$XDG_DATA_DIRS:$GNOME/share
XDG_CONFIG_DIRS=$XDG_CONFIG_DIRS:$GNOME/etc/xdg

jhbuild run gnome-session
</programlisting>

        <para>Make the file
          <filename>/usr/bin/gnome-jhbuild-session</filename> executable:</para>

<screen><prompt>$ </prompt><userinput>chmod a+x /usr/bin/gnome-jhbuild-session</userinput></screen>

        <para>To add a new session entry in the display manager, create
          <filename>/usr/share/xsessions/gnome-jhbuild.desktop</filename> and
          enter:</para>

<programlisting>[Desktop Entry]
Name=GNOME (JHBuild)
Comment=This session logs you into GNOME testing session
TryExec=/usr/bin/gnome-jhbuild-session
Exec=/usr/bin/gnome-jhbuild-session
Icon=
Type=Application</programlisting>

        <para>Restart <command>gdm</command>.</para>

        <para></para>
      </section>

      <section>
        <title>Running GNOME from the display manager</title>

        <para>To run the JHBuild GNOME, select the GNOME (JHBuild) session at
          the display manager before entering
          <systemitem class="username">gnomedev</systemitem> login credentials.
          If successful, JHBuild GNOME will be displayed. If unsuccessful, check
          the log within the <filename>~gnomedev/.xsession-errors</filename>
          file.</para>
      </section>
    </section>
  </section>

  <section id="buildbot-integration">
    <title>Buildbot Integration</title>

    <para>Coupled with the <ulink url="http://buildbot.net">Buildbot</ulink>
      project, JHBuild can also function as a continuous integration tool. The
      Buildbot configuration is used by the GNOME project at
      <ulink url="http://build.gnome.org">build.gnome.org</ulink>.</para>

    <section id="buildbot-slave">
      <title>Configuring a Buildbot Slave</title>

      <para>A Buildbot slave is a variation of a normal JHBuild installation
        that serves the requests of a Buildbot master. It is recommended to set
        up JHBuild and complete a build with most modules building successfully
        before adding the Buildbot customizations.</para>

      <para>Buildbot commands are options to the <command>bot</command>
        command. To download and install the extra required software, run the
        following command:</para>

<screen><prompt>$</prompt> <userinput>jhbuild bot --setup</userinput></screen>

      <para>Once this step has completed successfully, three new configuration
        variables are required in <filename>~/.config/jhbuildrc</filename>.
      </para>

      <note>
        <para>It is not possible to use an alternate configuration file, the
          <link linkend="option-file"><option>--file</option></link> will not
          get desired effects.</para>
      </note>

<programlisting>
jhbuildbot_master = 'build.gnome.org:9070'
jhbuildbot_slavename = 'slavename'
jhbuildbot_password = 'password'
</programlisting>

      <para><varname>jhbuildbot_master</varname> is a string specifying the
        Buildbot master server; it defaults to
        <literal>'build.gnome.org:9070'</literal>.
        <varname>jhbuildbot_slavename</varname> and
        <varname>jhbuildbot_password</varname> identify the slave on the master
        server. Contact the Buildbot master administrators to obtain the slave
        name and password.</para>

      <note>
        <para>The administrators of
          <ulink url="http://build.gnome.org">build.gnome.org</ulink> can be
          reached on the <ulink url="mailto:build-brigade-list@gnome.org">Build
          Brigade mailing list</ulink>.</para>
      </note>
    </section>

<!-- TODO: configuring a buildbot master
    <section id="buildbot-master">
      <title>Configuring a Buildbot Master</title>
    </section>
    -->
  </section>

  <section id="command-reference">
    <title>Command Reference</title>

    <para>JHBuild uses a command line syntax similar to tools like CVS:</para>

    <cmdsynopsis><command>jhbuild</command>
      <arg><replaceable>global-options</replaceable></arg>
      <arg choice="plain"><replaceable>command</replaceable></arg>
      <arg><replaceable>command-arguments</replaceable></arg>
    </cmdsynopsis>

    <para>The global JHBuild options are:</para>

    <variablelist>
      <varlistentry>
        <term id="option-file">
          <option>-f</option>, <option>--file</option>
          <replaceable>config</replaceable>
        </term>
        <listitem>
          <simpara>Use an alternative configuration file instead of the
            default <filename>~/.config/jhbuildrc</filename>.</simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-m</option>, <option>--moduleset</option>
          <replaceable>moduleset</replaceable>
        </term>
        <listitem>
          <simpara>Use a module set other than the module set listed in the
            configuration file. This option can be a relative path if the module
            set is located in the JHBuild moduleset folder, or an absolute path
            if located elsewhere.</simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>--no-interact</option>
        </term>
        <listitem>
          <simpara>Do not prompt the user for any input. This option is useful
            if leaving a build unattended, in order to ensure the build is not
            interrupted.</simpara>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Command specific options are listed below.</para>

    <section id="command-reference-autobuild">
      <title>autobuild</title>

      <para>The <command>autobuild</command> command automatically builds the
        modules as specified in the configuration file, and then upload the
        results to JhAutobuild.</para>

      <cmdsynopsis><command>jhbuild autobuild</command>
        <arg>--autogen</arg>
        <arg>--clean</arg>
        <arg>--distcheck</arg>
        <arg rep="repeat">--skip=<replaceable>module</replaceable></arg>
        <arg>--start-at=<replaceable>module</replaceable></arg>
        <arg>--report-url=<replaceable>reporturl</replaceable></arg>
        <arg>--verbose</arg>
      </cmdsynopsis>

      <para>The <option>--autogen</option>, <option>--clean</option>,
        <option>--distcheck</option>, <option>--skip</option> and
        <option>--start-at</option> options are processed as per the
        <link linkend="command-reference-build"><command>build</command></link>
        command.</para>

      <variablelist>
        <varlistentry>
          <term>
            <option>--report-url=<replaceable>reporturl</replaceable></option>,
            <option>-r <replaceable>reporturl</replaceable></option>
          </term>
          <listitem>
            <simpara>This option specifies the JhAutobuild URL to report to.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>--verbose</option>, <option>-v</option>
          </term>
          <listitem>
            <simpara>If specified, JHBuild's output will be more verbose.
            </simpara>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section id="command-reference-bootstrap">
      <title>bootstrap</title>

      <para>The <command>bootstrap</command> command installs a set of build
        utilities. The build utilities include
        <application>autoconf</application>, <application>automake</application>
        and similar utilities. The recommended method to install the build
        utilities is via your distribution's package management system. The
        <command>bootstrap</command> should only be used if the build utilities
        are not provided by your distribution's package management system, for
        example on <systemitem class="osname">Mac OS</systemitem>.</para>

      <cmdsynopsis><command>jhbuild bootstrap</command>
      </cmdsynopsis>

      <para>The <command>bootstrap</command> command builds modules using the
        same method as the <command>build</command> command, but uses the
        <filename>bootstrap.modules</filename> moduleset.</para>

      <para>See the
        <link linkend="command-reference-build"><command>build</command></link>
        command documentation for available options.</para>
    </section>

    <section id="command-reference-build">
      <title>build</title>

      <para>The <command>build</command> command builds one or more packages,
        including their dependencies.</para>

      <cmdsynopsis><command>jhbuild build</command>
        <arg>--autogen</arg>
        <arg>--clean</arg>
        <arg>--check</arg>
        <arg>--dist</arg>
        <arg>--distcheck</arg>
        <arg>--ignore-suggests</arg>
        <arg>--no-network</arg>
        <arg rep="repeat">--skip=<replaceable>module</replaceable></arg>
        <arg>--start-at=<replaceable>module</replaceable></arg>
        <arg>--tags=<replaceable>tags</replaceable></arg>
        <arg>-D <replaceable>date</replaceable></arg>
        <arg>--no-xvfb</arg>
        <arg>--try-checkout</arg>
        <arg>--no-poison</arg>
        <arg>--force</arg>
        <arg>--build-optional-modules</arg>
        <arg>--min-age=<replaceable>time</replaceable></arg>
        <arg>--nodeps</arg>
        <arg rep="repeat">module</arg>
      </cmdsynopsis>

      <para>If no module names are provided on the command line, the
        <link linkend="cfg-modules">modules</link> list from the configuration
        file will be used.</para>

      <variablelist>
        <varlistentry>
          <term>
            <option>-c</option>, <option>--clean</option>
          </term>
          <listitem>
            <simpara>Run <command>make clean</command> before building
              modules.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>--check</option>
          </term>
          <listitem>
            <simpara>Run <command>make check</command> after building modules.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>-d</option>, <option>--dist</option>
          </term>
          <listitem>
            <simpara>Run <command>make dist</command> after building modules.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>--distcheck</option>
          </term>
          <listitem>
            <simpara>Run <command>make distcheck</command> after building
              modules.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>--ignore-suggests</option>
          </term>
          <listitem>
            <simpara>Do not build soft dependencies.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>-n</option>, <option>--no-network</option>
          </term>
          <listitem>
            <simpara>Do not access the network when building modules. This
              will skip download or update stages in a build. If a module can't
              be built without network access, the module build will fail.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>-s</option>,
            <option>--skip</option>=<replaceable>module,...</replaceable>
          </term>
          <listitem>
            <simpara>Do not build the listed modules. Used to skip the
              building of specified dependencies.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>--tags</option>=<replaceable>tag,...</replaceable>
          </term>
          <listitem>
            <simpara>Ignore modules that do not match
              <replaceable>tag</replaceable>. Modules are automatically
              attributed a tag matching the name of the module's module set.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>-t</option>,
            <option>--start-at</option>=<replaceable>module</replaceable>
          </term>
          <listitem>
            <simpara>Start at the named module rather than at the beginning of
              the list. This option is useful if the build was interrupted.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>-D</option> <replaceable>date</replaceable>
          </term>
          <listitem>
            <simpara>If supported by the underlying version control system,
              update the source tree to the specified date before building. An
              ISO date format is required, e.g. <literal>"2009-09-18
              02:32Z"</literal>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>-x</option>, <option>--no-xvfb</option>
          </term>
          <listitem>
            <simpara>Run graphical tests on the actual X server rather than in
              a simulated Xvfb.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>-C</option>, <option>--try-checkout</option>
          </term>
          <listitem>
            <simpara>If the build fails, and if supported by the version
              control system, force a checkout and run
              <command>autogen.sh</command> before retrying the build.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>-N</option>, <option>--no-poison</option>
          </term>
          <listitem>
            <simpara>If one or more of a module's dependencies failed, this
              option forces JHBuild to try to build the module anyway.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>-f</option>, <option>--force</option>
          </term>
          <listitem>
            <simpara>Build the modules even if policy states it is not
              required.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>--build-optional-modules</option>
          </term>
          <listitem>
            <simpara>Modules listed as optional dependencies, may not be
              required to build the module. This option forces JHBuild to build
              optional dependencies.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>--min-age</option>=<replaceable>time</replaceable>
          </term>
          <listitem>
            <simpara>Skip modules installed more recently than the specified
              relative time. The <replaceable>time</replaceable> string format
              is a number followed by a unit. The following units are supported:
              seconds (s), minutes (m), hours (h) and days (d). For example,
              <option>--min-age=2h</option> will skip modules built less than
              two hours ago.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>--nodeps</option>
          </term>
          <listitem>
            <simpara>Ignore missing system dependencies.</simpara>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section id="command-reference-make">
      <title>make</title>

      <para>The <command>make</command> command is for actively developing on
        a particular module. It requires the current directory be a source
        checkout, and does the equivalent of <command>buildone -nf $(basename
        $(pwd))</command>.</para>

      <cmdsynopsis><command>jhbuild make</command>
        <arg>--clean</arg>
        <arg>--check</arg>
        <arg>--distcheck</arg>
        <arg>--quiet</arg>
      </cmdsynopsis>

      <para>The options are the same as those available for the
        <link
      linkend="command-reference-build"><command>buildone</command></link>
        command.</para>
    </section>

    <section id="command-reference-buildone">
      <title>buildone</title>

      <para>The <command>buildone</command> command is similar to
        <command>build</command>, but it does not build the dependent modules.
        It is useful for rebuilding one or more modules.</para>

      <cmdsynopsis><command>jhbuild buildone</command>
        <arg>--clean</arg>
        <arg>--check</arg>
        <arg>--distcheck</arg>
        <arg>--no-network</arg>
        <arg>-D <replaceable>date</replaceable></arg>
        <arg>--no-xvfb</arg>
        <arg>--force</arg>
        <arg>--min-age=<replaceable>time</replaceable></arg>
        <arg>--nodeps</arg>
        <arg choice="plain" rep="repeat">module</arg>
      </cmdsynopsis>

      <para>The <option>--check</option>, <option>--clean</option>,
        <option>-d</option>, <option>--distcheck</option>,
        <option>--no-network</option>, <option>-D</option>, <option>-x</option>
        and <option>--nodeps</option> options are processed as per the
        <link linkend="command-reference-build"><command>build</command></link>
        command.</para>

      <para>At least one module must be listed on the command line.</para>
    </section>

    <section id="command-reference-checkbranches">
      <title>checkbranches</title>

      <para>The <command>checkbranches</command> checks the module's branches
        are defined correctly within the version control system and the branches
        are consistent with the module set.</para>

      <cmdsynopsis><command>jhbuild checkbranches</command>
        <arg rep="repeat">--branch=<replaceable>branch</replaceable></arg>
      </cmdsynopsis>

      <variablelist>
        <varlistentry>
          <term>
            <option>--branch</option>=<replaceable>branch</replaceable>,
            <option>-b</option> <replaceable>branch</replaceable>
          </term>
          <listitem>
            <simpara>The branch to check.</simpara>
          </listitem>
        </varlistentry>
      </variablelist>

<screen><prompt>$</prompt> <userinput>jhbuild -m gnome-2.20 checkbranches</userinput>
libgnomecanvas is missing branch definition for gnome-2-20
<prompt>$</prompt></screen>
    </section>

    <section id="command-reference-clean">
      <title>clean</title>

      <para>The <command>clean</command> command cleans the build directories
        of one or more modules.</para>

      <cmdsynopsis><command>jhbuild clean</command>
        <arg rep="repeat">--skip=<replaceable>module</replaceable></arg>
        <arg>--start-at=<replaceable>module</replaceable></arg>
      </cmdsynopsis>

      <para>If no module names are provided on the command line, the
        <link linkend="cfg-modules">modules</link> list from the configuration
        file will be used.</para>

      <para>See the
        <link linkend="command-reference-build"><command>build</command></link>
        command documentation for a description of available options.</para>
    </section>

    <section id="command-reference-dot">
      <title>dot</title>

      <para>The <command>dot</command> command generates a file describing the
        directed graph formed by the dependencies between a set of modules. This
        file can then be processed using the
        <ulink url="http://www.graphviz.org/">GraphViz</ulink> software to
        produce a diagram.</para>

      <cmdsynopsis><command>jhbuild dot</command>
        <arg>--soft-deps</arg>
        <arg>--clusters</arg>
        <arg rep="repeat">module</arg>
      </cmdsynopsis>

      <para>If no module names are provided on the command line, the
        <link linkend="cfg-modules">modules</link> list from the configuration
        file will be used.</para>

      <para>The <option>--soft-deps</option> option adds dotted lines from the
        modules to the soft dependencies. The <option>--clusters</option> option
        groups modules from
        <link linkend="moduleset-syntax-defs-metamodule">metamodules</link>
        together.</para>

      <para>The output of the dot command can be piped to the dot utility to
        generate a PostScript file:</para>

<screen><prompt>$</prompt> <userinput>jhbuild dot <replaceable>modules</replaceable> | dot -Tps > dependencies.ps</userinput></screen>

      <para>Or a PNG image:</para>

<screen><prompt>$</prompt> <userinput>jhbuild dot <replaceable>modules</replaceable> | dot -Tpng > dependencies.png</userinput></screen>

      <figure id="sample-dot-output">
        <title>Sample JHBuild dot output</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/jhbuild_sample_dot_output.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
    </section>

    <section id="command-reference-gui">
      <title>gui</title>

      <para>The <command>gui</command> command starts a graphical interface to
        JHBuild which can be used to select modules to build and change some
        options.</para>

      <cmdsynopsis><command>jhbuild gui</command>
      </cmdsynopsis>

      <para>The graphical interface is rendered using GTK, so extra support
        libraries are required.</para>
    </section>

    <section id="command-reference-info">
      <title>info</title>

      <para>The <command>info</command> command displays information about one
        or more modules.</para>

      <cmdsynopsis><command>jhbuild info</command>
        <arg choice="plain" rep="repeat">module</arg>
      </cmdsynopsis>

      <para>The command displays the module name, type, dependencies,
        dependent packages, the source directory, and the time it was last
        installed with JHBuild. If available, information specific to the module
        type such as the CVS repository or download URL will also be displayed.
      </para>

      <para>If there is no module specified the command will display
        information about all the modules defined in the module set.</para>
    </section>

    <section id="command-reference-list">
      <title>list</title>

      <para>The <command>list</command> command displays the expanded list of
        modules the <command>build</command> command would build.</para>

      <cmdsynopsis><command>jhbuild list</command>
        <arg>-a</arg>
        <arg>-r</arg>
        <arg>-s</arg>
        <arg>--start-at=<replaceable>module</replaceable></arg>
        <arg>--tags=<replaceable>tags</replaceable></arg>
        <arg>--ignore-suggests</arg>
        <arg>--list-optional-modules</arg>
        <arg rep="repeat">module</arg>
      </cmdsynopsis>

      <para>If no module names are provided on the command line, the
        <link linkend="cfg-modules">modules</link> list from the configuration
        file will be used.</para>

      <para>The <option>--skip</option>, <option>--start-at</option>,
        <option>--tags</option>, and <option>--ignore-suggests</option> options
        are processed as per the
        <link linkend="command-reference-build"><command>build</command></link>
        command.</para>

      <variablelist>
        <varlistentry>
          <term>
            <option>-a</option>, <option>--all-modules</option>
          </term>
          <listitem>
            <simpara>List all the modules from the module set regardless of
              the build dependencies.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>-r</option>, <option>--show-revision</option>
          </term>
          <listitem>
            <simpara>If a module is set to a branch, show the branch name with
              the module name.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>--list-optional-modules</option>
          </term>
          <listitem>
            <simpara>This option forces JHBuild to list optional dependencies.
            </simpara>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section id="command-reference-rdepends">
      <title>rdepends</title>

      <para>The <command>rdepends</command> command displays the reverse
        dependencies of a module.</para>

      <cmdsynopsis><command>jhbuild rdepends</command>
        <arg>module</arg>
      </cmdsynopsis>

      <variablelist>
        <varlistentry>
          <term>
            <option>--dependencies</option>
          </term>
          <listitem>
            <simpara>Show dependency path next to modules.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>--direct</option>
          </term>
          <listitem>
            <simpara>Limit display to modules directly depending on specified
              module.</simpara>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section id="command-reference-run">
      <title>run</title>

      <para>The <command>run</command> command runs the specified command
        using the same environment that JHBuild uses when building modules.
      </para>

      <cmdsynopsis><command>jhbuild run</command>
        <arg>--in-builddir</arg>
        <arg>--in-checkoutdir</arg>
        <arg choice="plain"><replaceable>program</replaceable></arg>
        <arg rep="repeat"><replaceable>argument</replaceable></arg>
      </cmdsynopsis>

      <para>If using JHBuild to build GNOME, this command can be useful in X
        startup scripts.</para>

      <variablelist>
        <varlistentry>
          <term>
            <option>--in-builddir</option>=<replaceable>module</replaceable>
          </term>
          <listitem>
            <simpara>Run the command in the build directory of the specified
              module.</simpara>
          </listitem>
        </varlistentry>
      </variablelist>

      <variablelist>
        <varlistentry>
          <term>
            <option>--in-checkoutdir</option>=<replaceable>module</replaceable>
          </term>
          <listitem>
            <simpara>Run the command in the source directory of the specified
              module.</simpara>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section id="command-reference-sanitycheck">
      <title>sanitycheck</title>

      <para>The <command>sanitycheck</command> command performs a number of
        checks to verify the build environment is okay.</para>

      <cmdsynopsis><command>jhbuild sanitycheck</command>
      </cmdsynopsis>

      <para>Some of the checks include:</para>

      <itemizedlist>
        <listitem>
          <simpara>The checkout and install prefixes are writable.</simpara>
        </listitem>
        <listitem>
          <simpara>The required build tools are installed.</simpara>
        </listitem>
        <listitem>
          <simpara>Some commonly used macros are available in the search paths
            of the <command>aclocal</command> commands associated with the
            various versions of <command>automake</command>.</simpara>
        </listitem>
        <listitem>
          <simpara>The XML catalog contains the DocBook DTD and stylesheets.
          </simpara>
        </listitem>
      </itemizedlist>
    </section>

    <section id="command-reference-shell">
      <title>shell</title>

      <para>The <command>shell</command> command starts the user's shell with
        the same environment as JHBuild uses when building modules.</para>

      <cmdsynopsis><command>jhbuild shell</command>
      </cmdsynopsis>

      <para>This command is equivalent to the following:</para>

<screen><prompt>$</prompt> <userinput>jhbuild run $SHELL</userinput></screen>

      <para>The <envar>UNDER_JHBUILD</envar> environment variable will be set
        to "true" when this shell is active. You can use the presence of that
        variable to customize your shell's prompt to indicate that you indeed
        are under a jhbuild-controlled shell. For example, you may want to put
        this in your <filename>.bashrc</filename>:</para>

<screen>
	if [ -n "$UNDER_JHBUILD" ]; then
	    PS1="[jhbuild] $PS1"
	fi
      </screen>

      <para>This will make your bash shell display
        <literal>[jhbuild]</literal> before your normal prompt, making it easier
        to see which shells are under a jhbuild environment.</para>
    </section>

    <section id="command-reference-sysdeps">
      <title>sysdeps</title>

      <para>The <command>sysdeps</command> command displays:</para>

      <orderedlist>
        <listitem>
          <simpara>a list of installed system packages which will be used
            during the build. JHBuild will not build these modules and opt to
            use the system package instead.</simpara>
        </listitem>
        <listitem>
          <simpara>a list of required packages. To begin a build the packages
            must be provided by your system.</simpara>
        </listitem>
        <listitem>
          <simpara>a list of optional packages. The corresponding system
            package was not found or too old. JHBuild will build the module.
            Optional packages will not be displayed if
            <link linkend="cfg-partial-build"><varname>partial_build</varname></link>
            is <constant>False</constant>.</simpara>
        </listitem>
      </orderedlist>

      <cmdsynopsis><command>jhbuild sysdeps</command>
        <arg>--install</arg>
      </cmdsynopsis>

      <variablelist>
        <varlistentry>
          <term>
            <option>--install</option>
          </term>
          <listitem>
            <simpara>This option installs system packages which are
              dependencies of the moduleset. The system packages are installed
              using <application>PackageKit</application>.</simpara>
          </listitem>
        </varlistentry>
      </variablelist>

      <example>
        <title><command>sysdeps</command> example</title>
<screen><prompt>$</prompt> <userinput>jhbuild sysdeps</userinput>
System installed packages which are new enough:
  speex (required=1.2rc1, installed=1.2rc1)
  libdiscid (required=0.2.2, installed=0.2.2)
  telepathy-farsight (required=0.0.14, installed=0.0.16)
  lcms2 (required=2.2, installed=2.2)
...
Required packages:
  System installed packages which are too old:
    (none)
  No matching system package installed:
    zlib (required=1.2)
Optional packages: (JHBuild will build the missing packages)
  System installed packages which are too old:
    webkitgtk-3.0 (required=1.5.1, installed=1.4.0)
    ...
  No matching system package installed:
    libvala-0.14 (required=0.13.1)
    ...</screen>
      </example>
    </section>

    <section id="command-reference-tinderbox">
      <title>tinderbox</title>

      <para>The <command>tinderbox</command> command is similar to
        <command>build</command>, but writes all terminal output to HTML files
        suitable for publishing on a website. It can be used to set up systems
        similar to Mozilla's Tinderbox, or Debian's Buildd.</para>

      <cmdsynopsis><command>jhbuild tinderbox</command>
        <arg>--clean</arg>
        <arg>--no-network</arg>
        <arg>--output=<replaceable>directory</replaceable></arg>
        <arg rep="repeat">--skip=<replaceable>module</replaceable></arg>
        <arg>--start-at=<replaceable>module</replaceable></arg>
        <arg>-D <replaceable>date</replaceable></arg>
        <arg>-C</arg>
        <arg>-N</arg>
        <arg>-f</arg>
        <arg>--nodeps</arg>
        <arg rep="repeat">module</arg>
      </cmdsynopsis>

      <para>The <option>--clean</option>, <option>--no-network</option>,
        <option>--skip</option>, <option>--start-at</option>,
        <option>-D</option>, <option>-C</option>, <option>-N</option>,
        <option>-f</option> and <option>--nodeps</option> options are processed
        as per the
        <link linkend="command-reference-build"><command>build</command></link>
        command.</para>

      <variablelist>
        <varlistentry>
          <term>
            <option>-o</option>,
            <option>--output</option>=<replaceable>directory</replaceable>
          </term>
          <listitem>
            <simpara>The directory to write the HTML files.</simpara>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section id="command-reference-uninstall">
      <title>uninstall</title>

      <para>The <command>uninstall</command> command uninstalls one or more
        modules.</para>

      <cmdsynopsis><command>jhbuild uninstall</command>
        <arg choice="plain" rep="repeat">module</arg>
      </cmdsynopsis>
    </section>

    <section id="command-reference-update">
      <title>update</title>

      <para>The <command>update</command> command is similar to
        <command>build</command>, but only performs the download or update stage
        for modules without building them.</para>

      <cmdsynopsis><command>jhbuild update</command>
        <arg rep="repeat">--skip=<replaceable>module</replaceable></arg>
        <arg>--start-at=<replaceable>module</replaceable></arg>
        <arg>--tags=<replaceable>tags</replaceable></arg>
        <arg>--ignore-suggests</arg>
        <arg>-D <replaceable>date</replaceable></arg>
        <arg rep="repeat">module</arg>
      </cmdsynopsis>

      <para>The <option>--skip</option>, <option>--start-at</option>,
        <option>--tags</option>, <option>--ignore-suggests</option> and
        <option>-D</option> options are processed as per the
        <link linkend="command-reference-build"><command>build</command></link>
        command.</para>
    </section>

    <section id="command-reference-updateone">
      <title>updateone</title>

      <para>The <command>updateone</command> command is similar to
        <command>update</command>, but it does not update the dependent modules.
        It is useful for updating one or more modules.</para>

      <cmdsynopsis><command>jhbuild updateone</command>
        <arg>-D <replaceable>date</replaceable></arg>
        <arg choice="plain" rep="repeat">module</arg>
      </cmdsynopsis>

      <para>The <option>-D</option> option is processed as per the
        <link linkend="command-reference-build"><command>build</command></link>
        command.</para>

      <para>At least one module must be listed on the command line.</para>
    </section>
  </section>

  <section id="config-reference">
    <title>Configuration File Reference</title>

    <para>The <filename>~/.config/jhbuildrc</filename> file uses standard
      Python syntax. The file is run, and the resulting variables defined in the
      namespace are used to control how JHBuild acts. A set of default values
      are inserted into the namespace before running the user's configuration
      file.</para>

    <para>Boolean configuration variables are set using syntax as demonstrated
      in the following example:</para>

<programlisting>use_local_modulesets = True</programlisting>

    <para>String configuration variables are set using syntax as demonstrated
      in the following example:</para>

<programlisting>autogenargs = '--disable-static --disable-gtk-doc'</programlisting>

    <para>List configuration variables are set using syntax as demonstrated in
      the following example:</para>

<programlisting>skip = ['mozilla', 'pulseaudio']</programlisting>

    <para>Dictionary configuration variables are set using syntax as
      demonstrated in the following example:</para>

<programlisting>repos['git.gnome.org'] = 'ssh://username@git.gnome.org/git/'</programlisting>

    <section id="config-reference-variables">
      <title>Configuration Variables</title>

      <variablelist>
<?dbhtml list-presentation="table"?>
        <varlistentry>
          <term id="cfg-autogenargs">
            <varname>autogenargs</varname>
          </term>
          <listitem>
            <simpara>A string containing arguments passed to the
              <command>autogen.sh</command> script of all modules. Can be
              overridden for particular modules using the
              <varname>module_autogenargs</varname> dictionary.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-branches">
            <varname>branches</varname>
          </term>
          <listitem>
            <simpara>A dictionary specifying which branch to use for specific
              modules. This is useful if you are making some changes on a branch
              of a module and want JHBuild to build that branch instead of the
              one listed in the module set.</simpara>

            <simpara>The definition of branches depends on the module VCS:
            </simpara>

            <itemizedlist>
              <listitem>
                <simpara>CVS: revision. E.g.
                  <literal>'BRANCH-PROJECT-0_8'</literal></simpara>
              </listitem>
              <listitem>
                <simpara>Bazaar: URI of module branch. E.g.
                  <literal>'http://bzr.example.net/project/gnome-2-28'</literal>
                </simpara>
              </listitem>
              <listitem>
                <simpara>Git: tuple, with first part being an optional
                  repository (or the None value) and the second part the name of
                  the branch. E.g. <literal>('git://git.example.net/project',
                  'gnome-2-28')</literal></simpara>

                <example>
                  <title>Simple example</title>
<programlisting>branches['modulename'] = (None, 'branchname')</programlisting>
                </example>
              </listitem>
              <listitem>
                <simpara>Subversion: URI of module branch E.g.
                  <literal>'svn://svn.example.net/project/gnome-2-28'</literal>
                </simpara>
              </listitem>
            </itemizedlist>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-builddir-pattern">
            <varname>builddir_pattern</varname>
          </term>
          <listitem>
            <simpara>A <function>printf</function> style formatting pattern
              used to generate build directory names. This is only used when
              using separate source and build trees. The <literal>%s</literal>
              in the format string will be replaced with
              <varname>checkoutdir</varname>. Defaults to
              <literal>'%s'</literal>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-buildroot">
            <varname>buildroot</varname>
          </term>
          <listitem>
            <simpara>A string specifying the parent directory to place build
              trees. Defaults to <constant>None</constant>, which causes builds
              to be performed within the source trees.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-buildscript">
            <varname>buildscript</varname>
          </term>
          <listitem>
            <simpara>A string specifying which buildscript to use. The
              recommended setting is the default, <literal>terminal</literal>.
              In particular, do not set to <literal>gtk</literal>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cf-build-policy">
            <varname>build_policy</varname>
          </term>
          <listitem>
            <simpara>A string specifying which modules to build. The three
              possible options are <literal>all</literal>, to build all modules
              requested, <literal>updated</literal> to build only modules which
              have changed, or <literal>updated-deps</literal> to build modules
              which have changed or which have dependencies which have changed.
              Defaults to <literal>updated-deps</literal>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-checkoutroot">
            <varname>checkoutroot</varname>
          </term>
          <listitem>
            <simpara>A string specifying the directory to unpack source trees
              to. Unless <varname>buildroot</varname> is set, builds will occur
              in this directory too. Defaults to
              <filename>~/checkout/gnome</filename>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-checkout-mode">
            <varname>checkout_mode</varname>
          </term>
          <listitem>
            <simpara>A string specifying how the checkout is performed for
              directories in version control. Defaults to
              <literal>update</literal>. This can be set per module using
              <varname>module_checkout_mode</varname>. Possible values are
              <literal>update</literal> (update checkout directory),
              <literal>clobber</literal> (wipe out directory before checking out
              the sources), <literal>export</literal> (wipe out directory then
              create an unversioned copy of the sources) and
              <literal>copy</literal> (checkout in a directory different from
              the one it will build).</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-copy-dir">
            <varname>copy_dir</varname>
          </term>
          <listitem>
            <simpara>A string specifying the directory to copy to, if the copy
              <link linkend="cfg-checkout-mode">
              <varname>checkout_mode</varname></link> is in use. Defaults to the
              checkout directory.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-cvs-program">
            <varname>cvs_program</varname>
          </term>
          <listitem>
            <simpara>A string specifying which program to use for CVS support.
              This can be <literal>git-cvsimport</literal>, or
              <literal>cvs</literal>. Defaults to <literal>cvs</literal>.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-dvcs-mirror-dir">
            <varname>dvcs_mirror_dir</varname>
          </term>
          <listitem>
            <simpara>A string specifying a local mirror directory. JHBuild
              will create local mirrors of repositories at the specified
              directory. The mirrors can be shared by multiple repository
              groups, saving space and time because hard-links will be used for
              local clones. The commands <command>update</command> and
              <command>updateone</command> will create the mirrors and fetch new
              commits from the online repositories. This option is only
              supported by Git and Bazaar repositories.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-installprog">
            <varname>installprog</varname>
          </term>
          <listitem>
            <simpara>A string specifying a program to use as replacement for
              <literal>/usr/bin/install</literal>. If available, defaults to the
              <literal>install-check</literal> wrapper provided by JHBuild. The
              <literal>install-check</literal> wrapper optimizes header
              installation to reduce the time taken for rebuilds.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-ignore-suggests">
            <varname>ignore_suggests</varname>
          </term>
          <listitem>
            <simpara>A boolean value specifying whether to ignore soft
              dependencies when calculating the dependency tree. Defaults to
              <constant>False</constant>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-interact">
            <varname>interact</varname>
          </term>
          <listitem>
            <simpara>A boolean value specifying whether to interact with the
              user. Setting this value to <constant>False</constant> is
              equivalent to passing the <option>--no-interact</option> option.
              Defaults to <constant>True</constant>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-makeargs">
            <varname>makeargs</varname>
          </term>
          <listitem>
            <simpara>A string listing additional arguments to be passed to
              <command>make</command>. Defaults to <literal>''</literal>.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-makecheck">
            <varname>makecheck</varname>
          </term>
          <listitem>
            <simpara>A boolean value specifying whether to run <command>make
              check</command> after <command>make</command>. Defaults to
              <constant>False</constant>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-makecheck-advistory">
            <varname>makecheck_advisory</varname>
          </term>
          <listitem>
            <simpara>A boolean value specifying whether failures when running
              <command>make check</command> should be advisory only and not
              cause a build failure. Defaults to <constant>False</constant>.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-makeclean">
            <varname>makeclean</varname>
          </term>
          <listitem>
            <simpara>A boolean value specifying whether to run <command>make
              clean</command> before <command>make</command>. Defaults to
              <constant>False</constant>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-makedist">
            <varname>makedist</varname>
          </term>
          <listitem>
            <simpara>A boolean value specifying whether to run <command>make
              dist</command> after <command>make</command>. Defaults to
              <constant>False</constant>. This setting is equivalent to passing
              the <option>--dist</option> option.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-makedistcheck">
            <varname>makedistcheck</varname>
          </term>
          <listitem>
            <simpara>A boolean value specifying whether to run <command>make
              distcheck</command> after <command>make</command>. Defaults to
              <constant>False</constant>. This setting is equivalent to passing
              the <option>--distcheck</option> option.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-module-autogenargs">
            <varname>module_autogenargs</varname>
          </term>
          <listitem>
            <simpara>A dictionary mapping module names to strings specifying
              the arguments to be passed to <command>autogen.sh</command>. The
              setting in <varname>module_autogenargs</varname> is used instead
              of the global <varname>autogenargs</varname> setting. If a
              particular module isn't listed in the dictionary, the global
              <varname>autogenargs</varname> will be used.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-module-checkout-mode">
            <varname>module_checkout_mode</varname>
          </term>
          <listitem>
            <simpara>A dictionary specifying which checkout mode to use for
              modules. This overrides the global
              <varname>checkout_mode</varname> setting.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-module-makeargs">
            <varname>module_makeargs</varname>
          </term>
          <listitem>
            <simpara>A dictionary mapping module names to strings specifying
              the arguments to pass to <command>make</command>. The setting in
              <varname>module_makeargs</varname> replaces the value of
              <varname>makeargs</varname>. If a particular module isn't listed
              in the dictionary, the global <varname>makeargs</varname> will be
              used.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-module-makecheck">
            <varname>module_makecheck</varname>
          </term>
          <listitem>
            <simpara>A dictionary mapping module names to boolean values
              specifying whether to run <command>make check</command> after
              <command>make</command>. The setting in
              <varname>module_makecheck</varname> replaces the value of
              <varname>makecheck</varname>. If a particular module isn't listed
              in the dictionary, the global <varname>makecheck</varname> will be
              used.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-module-nopoison">
            <varname>module_nopoison</varname>
          </term>
          <listitem>
            <simpara>A dictionary mapping module names to boolean values. If a
              module is set to <constant>True</constant>, JHBuild will attempt
              to build dependent modules even if the specified module failed.
              The setting in <varname>module_nopoison</varname> replaces the
              value of <varname>nopoison</varname>. If a particular module isn't
              listed in the dictionary, the global <varname>nopoison</varname>
              will be used.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-module-extra-env">
            <varname>module_extra_env</varname>
          </term>
          <listitem>
            <simpara>A dictionary mapping module names to dictionaries with
              extra environment variables to pass when executing commands for
              the module.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-modules">
            <varname>modules</varname>
          </term>
          <listitem>
            <simpara>A list of strings specifying the modules to build. The
              list of modules actually built will be recursively expanded to
              include all the dependencies unless the
              <link linkend="command-reference-buildone">
              <command>buildone</command></link> command is used. Defaults to
              <literal>['meta-gnome-desktop']</literal>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-moduleset">
            <varname>moduleset</varname>
          </term>
          <listitem>
            <simpara>A string or list of strings specifying the name(s) of the
              module set(s) to use. This can either be the filename of a
              moduleset included with JHBuild (excluding the path and
              extension), or a full HTTP URL to an externally managed moduleset.
              HTTP URL modulesets are cached locally. If a module with the same
              name is present in more than one moduleset, the last set listed
              takes priority. Modulesets provided with JHBuild are updated to
              match the current GNOME development release.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-modulesets-dir">
            <varname>modulesets_dir</varname>
          </term>
          <listitem>
            <simpara>A string specifying the directory containing the
              modulesets to use. Defaults to the
              <filename>modulesets/</filename> directory in JHBuild sources.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-nice-build">
            <varname>nice_build</varname>
          </term>
          <listitem>
            <simpara>Run builds under the <constant>SCHED_IDLE</constant>
              priority on Linux, <command>nice</command> on other Unix. This can
              dramatically improve desktop interactivity for parallel builds
              while having only a negligible impact on build throughput.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-nobuild">
            <varname>nobuild</varname>
          </term>
          <listitem>
            <simpara>A boolean value, if set to <constant>True</constant>
              JHBuild will not build modules, but just download and unpack the
              sources. The default vale is <constant>False</constant>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-nonetwork">
            <varname>nonetwork</varname>
          </term>
          <listitem>
            <simpara>A boolean value specifying whether to access the network.
              This affects checking out or updating CVS modules, downloading
              tarballs and updating module sets. Setting this to
              <constant>True</constant> is equivalent to passing the
              <option>--no-network</option> option. Defaults to
              <constant>False</constant>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-nonotify">
            <varname>nonotify</varname>
          </term>
          <listitem>
            <simpara>A boolean value specifying whether to emit notifications
              using the notification daemon. If set to
              <constant>False</constant>, notifications are emitted. Defaults to
              <constant>True</constant>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-nopoison">
            <varname>nopoison</varname>
          </term>
          <listitem>
            <simpara>A boolean value, if set to <constant>True</constant>
              JHBuild attempts to build modules even if one or more of the
              module's dependencies failed to build. This option is equivalent
              to the <option>--no-poison</option> argument. The default value is
              <constant>False</constant>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-notrayicon">
            <varname>notrayicon</varname>
          </term>
          <listitem>
            <simpara>A boolean value specifying whether to show an icon in the
              system tray using Zenity. If set to <constant>False</constant>,
              notifications are emitted. Defaults to <constant>True</constant>.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-noxvfb">
            <varname>noxvfb</varname>
          </term>
          <listitem>
            <simpara>A boolean value, if set to <constant>True</constant>
              JHBuild will run any graphical tests on the real X server, rather
              than using <command>Xvfb</command>. This option is equivalent to
              passing <option>--no-xvfb</option>. The default value is
              <constant>False</constant></simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-partial-build">
            <varname>partial_build</varname>
          </term>
          <listitem>
            <simpara>A boolean value, if set to <constant>True</constant>
              JHBuild will not build dependency modules if corresponding system
              packages are installed and sufficient version. Defaults to
              <constant>True</constant>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-prefix">
            <varname>prefix</varname>
          </term>
          <listitem>
            <simpara>A string specifying the prefix to install modules to.
              <varname>prefix</varname> must be an absolute path. This directory
              must be writable. Defaults to <literal>'/opt/gnome'</literal>.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-pretty-print">
            <varname>pretty_print</varname>
          </term>
          <listitem>
            <simpara>A boolean value specifying whether to pretty format the
              subprocess output. Only CVS output supports pretty printing.
              Disable if the pretty printing causes problems. Defaults to
              <literal>True</literal>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-print-command-pattern">
            <varname>print_command_pattern</varname>
          </term>
          <listitem>
            <simpara>A string displayed before JHBuild executes a command.
              <varname>%(command)s</varname> in the string will be replaced with
              the command about to be executed. <varname>%(cwd)s</varname> in
              the string will be replaced with the current working directory.
              Defaults to <literal>'%(command)s'</literal>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-progress-bar">
            <varname>progress_bar</varname>
          </term>
          <listitem>
            <simpara>A boolean value specifying whether to display a progress
              bar during <link linkend="cfg-quiet-mode">quiet mode </link>.
              Defaults to <literal>True</literal>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-quiet-mode">
            <varname>quiet_mode</varname>
          </term>
          <listitem>
            <simpara>A boolean value, if set to <constant>True</constant>
              disables the output of running commands. Defaults to
              <literal>False</literal>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term id="cfg-repos">
            <varname>repos</varname>
          </term>
          <listitem>
            <simpara>A dictionary specifying an alternative repository
              location for a particular repository. This configuration variable
              is useful to a module developer. By default, JHBuild will check
              out code from repositories using an anonymous repository location.
              The dictionary keys are short repository names and the values are
              the alternative repository location strings. For example:
            </simpara>

<programlisting>repos['git.gnome.org'] = 'ssh://username@git.gnome.org/git/'</programlisting>
          </listitem>
        </varlistentry>
        <varlistentry id="cfg-skip">
          <term>
            <varname>skip</varname>
          </term>
          <listitem>
            <simpara>A list of modules to skip. This <option>--skip</option>
              command line option extends the list. This list is empty by
              default.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry id="cfg-sticky-date">
          <term>
            <varname>sticky_date</varname>
          </term>
          <listitem>
            <simpara>A string if set, and if supported by the underlying
              version control system, JHBuild will update the source tree to the
              specified date before building. An ISO date format is required,
              e.g.
              <literal>'<replaceable>yyyy</replaceable>-<replaceable>mm</replaceable>-<replaceable>dd</replaceable>'</literal>.
              Defaults to <constant>None</constant>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry id="cfg-svn-program">
          <term>
            <varname>svn_program</varname>
          </term>
          <listitem>
            <simpara>A string specifying which program to use for subversion
              support. This can be <literal>svn</literal>,
              <literal>git-svn</literal> or <literal>bzr</literal>. Defaults to
              <literal>svn</literal>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry id="cfg-tarballdir">
          <term>
            <varname>tarballdir</varname>
          </term>
          <listitem>
            <simpara>A string if set, tarballs will be downloaded to the
              specified directory instead of <varname>checkoutroot</varname>.
              This is useful if you have multiple JHBuild environments or
              regularly clear out <varname>checkoutroot</varname> and want to
              reduce bandwidth usage.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry id="cfg-tinderbox-outputdir">
          <term>
            <varname>tinderbox_outputdir</varname>
          </term>
          <listitem>
            <simpara>A string specifying the directory to store
              <command>jhbuild tinderbox</command> output. This string can be
              overridden by the <option>--output</option> option. Defaults to
              <constant>None</constant>, so either the command line option must
              be used or this variable must be set in the configuration file.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry id="cfg-trycheckout">
          <term>
            <varname>trycheckout</varname>
          </term>
          <listitem>
            <simpara>A boolean value, if set to <constant>True</constant>
              JHBuild will automatically try to solve failures by 1) running
              <command>autogen.sh</command> again, and 2) checking out a newer
              version of a module from version control. This setting is
              equivalent to passing the <option>--try-checkout</option> option.
            </simpara>
          </listitem>
        </varlistentry>
        <varlistentry id="cfg-use-lib64">
          <term>
            <varname>use_lib64</varname>
          </term>
          <listitem>
            <simpara>A boolean value that specifies whether to install
              libraries to <filename>lib64</filename> directories. If set,
              <literal>--libdir=\${exec_prefix}/lib64</literal> will be passed
              to configure. Defaults to <constant>True</constant> if running on
              <literal>x86_64</literal>, <literal>ppc64</literal> or
              <literal>s390x</literal> Linux, and <constant>False</constant> on
              other systems.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry id="cfg-use-local-modulesets">
          <term>
            <varname>use_local_modulesets</varname>
          </term>
          <listitem>
            <simpara>A boolean value that specifies to use modulesets that
              were checked out along the JHBuild source code; instead of
              downloading them on-the-fly from GNOME version control system.
              Defaults to <constant>False</constant>.</simpara>
          </listitem>
        </varlistentry>
        <varlistentry id="cfg-xvfbargs">
          <term>
            <varname>xvfbargs</varname>
          </term>
          <listitem>
            <simpara>A string listing arguments to pass to
              <command>Xvfb</command> if running graphical tests.</simpara>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section id="config-reference-other">
      <title>Other Configuration File Structures</title>

      <para>In addition to the above variables, there are other settings that
        can be set in the configuration file:</para>

      <variablelist>
        <varlistentry id="cfg-os-environ">
          <term>
            <varname>os.environ</varname>
          </term>
          <listitem>
            <para>A dictionary representing the environment. This environment
              is passed to processes that JHBuild spawns.</para>

            <para>Some influential environment variables include
              <envar>CPPFLAGS</envar>, <envar>CFLAGS</envar>,
              <envar>INSTALL</envar> and <envar>LDFLAGS</envar>. For example:
            </para>

<programlisting>os.environ['CFLAGS'] = '-O0 -g'</programlisting>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <function>addpath</function>(<parameter>envvar</parameter>,
            <parameter>pathname</parameter>)
          </term>
          <listitem>
            <para>This will add a directory to the <envar>PATH</envar>
              environment variable. <function>addpath</function> will correctly
              handle the case when the environment variable is initially empty
              (having a stray colon at the beginning or end of an environment
              variable can have unexpected consequences).</para>

            <para><function>addpath</function> has special handling for the
              <envar>ACLOCAL_FLAGS</envar> environment variable, which expects
              paths to be listed in the form <literal>-I
              <replaceable>pathname</replaceable></literal>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <function>prependpath</function>(<parameter>envvar</parameter>,
            <parameter>pathname</parameter>)
          </term>
          <listitem>
            <para>After processing the configuration file, JHBuild will alter
              some paths based on variables such as <varname>prefix</varname>
              (e.g. adding <literal>$prefix/bin</literal> to the start of
              <envar>PATH</envar>).</para>

            <para>The <function>prependpath</function> function works like
              <function>addpath</function>, except that the environment variable
              is modified after JHBuild has made its changes to the environment.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
  </section>

  <section id="moduleset-syntax">
    <title>Module Set File Syntax</title>

    <para>JHBuild uses XML files to describe the dependencies between modules.
      A RELAX-NG schema and Document Type Definition are included with JHBuild
      in the <filename>modulesets/</filename> directory. The RELAX-NG schema can
      be used to edit module set files using <literal>nxml-mode</literal> in
      Emacs.</para>

    <para>The top-level element in a module set file is
      <sgmltag class="element">moduleset</sgmltag> element. No XML namespace is
      used. The elements below the top-level come in three types: module
      sources, include statements and module definitions.</para>

    <section id="moduleset-syntax-sources">
      <title>Module Sources</title>

      <para>Rather than listing the full location of every module, a number of
        "module sources" are listed in the module set, and then referenced by
        name in the module definitions. As well as reducing the amount of
        redundant information in the module set, it makes it easy for a user to
        specify an alternative source for those modules (for CVS and Subversion,
        it is common for developers and users to use different repository access
        methods).</para>

      <para>The <sgmltag class="element">repository</sgmltag> element is used
        to describe all types of repository. The
        <sgmltag class="element">branch</sgmltag> element is used inside module
        definition to specify additional settings.</para>

<programlisting>
&lt;repository name="<replaceable>name</replaceable>"
  type="<replaceable>type</replaceable>"
  [ default="<replaceable>default</replaceable>" ]
  [ password="<replaceable>password</replaceable>" ]
  [ cvsroot="<replaceable>cvsroot</replaceable>" ]
  [ archive="<replaceable>archive</replaceable>" ]
  [ href="<replaceable>href</replaceable>" ]
  [ server="<replaceable>server</replaceable>" ]
  [ database="<replaceable>database</replaceable>" ]
  [ defbranch="<replaceable>defbranch</replaceable>" ]
  [ trunk-template="<replaceable>trunk-template</replaceable>" ]
  [ branches-template="<replaceable>branches-template</replaceable>" ]
  [ tags-template="<replaceable>tags-template</replaceable>" ]
  [ developer-href-example="<replaceable>developer-href-example</replaceable>" ] /&gt;
</programlisting>

      <para>The <sgmltag class="attribute">name</sgmltag> attribute is a
        unique identifier for the repository.</para>

      <para>The <sgmltag class="attribute">default</sgmltag> attribute
        specifies whether this repository is the default source for this module
        set.</para>

      <para>The <sgmltag class="attribute">type</sgmltag> attribute specifies
        the type of repository. It can be one of: <literal>bzr</literal>,
        <literal>cvs</literal>, <literal>darcs</literal>,
        <literal>fossil</literal>, <literal>git</literal>,
        <literal>hg</literal>, <literal>mnt</literal>, <literal>svn</literal>,
        <literal>tarball</literal>. Other attributes depend on the
        <sgmltag class="attribute">type</sgmltag>, as well as the
        <sgmltag
      class="element">branch</sgmltag> used inside module
        definitions. Those are described below in the repository type
        sub-sections.</para>

      <para>The <sgmltag class="attribute">developer-href-example</sgmltag>
        attribute is used to specify the format of the URL for the repository
        used by developers. This is informational only.</para>

      <para>The <sgmltag class="element">branch</sgmltag> element is used
        inside module definitions.</para>

<programlisting>
&lt;branch
  [ repo="<replaceable>repository</replaceable>" ]
  [ module="<replaceable>module name</replaceable>" ]
  [ checkoutdir="<replaceable>checkoutdir</replaceable>" ]
  [ revision="<replaceable>revision</replaceable>" ]
  [ tag="<replaceable>tag</replaceable>" ]
  [ update-new-dirs="<replaceable>update-new-dirs</replaceable>" ]
  [ override-checkoutdir="<replaceable>override-checkoutdir</replaceable>" ]
  [ subdir="<replaceable>subdir</replaceable>" ]
  [ branch="<replaceable>branch</replaceable>" ]
  [ version="<replaceable>version</replaceable>" ]
  [ size="<replaceable>size</replaceable>" ]
  [ source-subdir="<replaceable>source-subdir</replaceable>" ]
  [ hash="<replaceable>hash</replaceable>" ]/&gt;
</programlisting>

      <para>All atributes have sensible defaults and depend on the module and
        repository definitions. Common attributes are described here.</para>

      <para>The <sgmltag class="attribute">repo</sgmltag> attribute is used to
        specify non-default repository name.</para>

      <para>The <sgmltag class="attribute">module</sgmltag> attribute is used
        to specify module name to checkout from the repository. Defaults to
        module id.</para>

      <para>The <sgmltag class="attribute">checkoutdir</sgmltag> attribute is
        used to specify the checkout directory name. Defaults to module id.
      </para>

      <para>Other attributes are described below</para>

      <section id="moduleset-syntax-sources-bzr">
        <title>Bazaar</title>

        <para>This repository type is used to define a Bazaar repository. It
          is recommended to have Bazaar 1.16 or higher.</para>

<programlisting>
&lt;repository type="bzr" name="launchpad.net"
      href="lp:"/&gt;
        </programlisting>

        <para>Additional attributes are:
          <sgmltag class="attribute">trunk-template</sgmltag> (defaults to
          <literal>"%(module)s"</literal>) and
          <sgmltag class="attribute">branches-template</sgmltag> (defaults to
          <literal>"%(module)s/%(branch)s</literal>"). These attributes are used
          to specify templates for constructing URL. A
          <sgmltag class="element">branch</sgmltag> element in the module
          definitions can specify <sgmltag class="attribute">branch</sgmltag>
          and <sgmltag class="attribute">user</sgmltag> attributes. These values
          will be substitued in the templates. If either of those are defined
          <sgmltag class="attribute">branches-template</sgmltag> is used,
          otherwise <sgmltag class="attribute">trunk-template</sgmltag> is used.
          This way you can ovveride repository to build modules from your
          personal branch or build many modules fron a repository with
          non-standard layout.</para>

        <para>An addition <sgmltag class="element">branch</sgmltag> element
          accepts <sgmltag class="attribute">revspec</sgmltag> attibute to
          anchor on a particular revision. Any valid <literal>bzr
          revspec</literal> is accepted, for example <literal>date:yesterday,
          -5, tag:0.1</literal> to get first revision since yesterday, 5 commits
          behind the tip or tag "0.1". See <literal>bzr help
          revisionspec</literal> for all possible values.</para>

        <para>For example repository with
          <sgmltag class="attribute">template</sgmltag> attributes defined:
        </para>

<programlisting>
&lt;repository type="bzr" name="launchpad.net"
      href="lp:"
      trunk-template="~bzr-pqm/%(module)s/bzr.dev"
      branches-template="~bzr-pqm/%(module)s/%(branch)s"/&gt;
        </programlisting>

        <para>Example <sgmltag class="element">branch</sgmltag> elements for
          the above repository:</para>

<programlisting>
&lt;branch repo="launchpad.net"
      module="bzr"
      checkoutdir="bzr-next"/&gt;
        </programlisting>

<programlisting>
&lt;branch repo="launchpad.net"
      module="bzr"
      branch="2.2"
      checkoutdir="bzr-beta"/&gt;
        </programlisting>
      </section>

      <section id="moduleset-syntax-sources-cvs">
        <title>CVS</title>

        <para>This repository type is used to define a CVS repository.</para>

        <para>The <sgmltag class="attribute">password</sgmltag> attribute is
          used to specify the password to the repository.</para>

        <para>The <sgmltag class="attribute">cvsroot</sgmltag> attribute is
          used to specify the root of the repository.</para>

<programlisting>
&lt;repository type="cvs" name="tango.freedesktop.org"
    cvsroot=":pserver:anoncvs@anoncvs.freedesktop.org:/cvs/tango"
    password=""/&gt;
        </programlisting>

<!-- TODO describe these attributes -->

        <para>Additional attributes are:
          <sgmltag class="attribute">revision</sgmltag>,
          <sgmltag class="attribute">update-new-dirs</sgmltag> and
          <sgmltag class="attribute">override-checkoutdir</sgmltag>.</para>
      </section>

      <section id="moduleset-syntax-sources-darcs">
        <title>Darcs</title>

        <para>This repository type is used to define a Darcs repository.
        </para>

<programlisting>
&lt;repository type="darcs" name="telepathy.freedesktop.org"
      href="http://projects.collabora.co.uk/darcs/telepathy/"/&gt;
</programlisting>
      </section>

      <section id="moduleset-syntax-sources-git">
        <title>Git</title>

        <para>This repository type is used to define a Git repository.</para>

<programlisting>
&lt;repository type="git" name="git.freedesktop.org"
    href="git://anongit.freedesktop.org/git/"/&gt;
        </programlisting>

        <para>It allows the following attributes on the
          <sgmltag
        class="element">branch</sgmltag> element:</para>

        <para>The <sgmltag class="attribute">revision</sgmltag> attribute is
          used to specify a local or remote-tracking branch to switch to in the
          update phase. It defaults to 'master'. It is possible to override this
          attribute with the <varname>branches</varname> configuration variable.
          The switch will only be performed, if the current branch is tracking a
          remote branch, to not disturb your own work.</para>

        <para>The <sgmltag class="attribute">tag</sgmltag> attribute is used
          to specify a revision to unconditionally check out in the update
          phase. It overrides the <sgmltag class="attribute">revision</sgmltag>
          attribute.</para>

<!-- TODO I can't say much about the subdir attribute. In the
        end it will just be appended to checkoutdir.
        https://bugzilla.gnome.org/show_bug.cgi?id=342846
        -->

<programlisting>
&lt;branch repo="git.freedesktop.org" module="swfdec/swfdec"
        checkoutdir="swfdec"
        revision="<replaceable>local-or-remote-branch</replaceable>"
        tag="<replaceable>tree-ish</replaceable>"/&gt;
        </programlisting>
      </section>

      <section id="moduleset-syntax-sources-hg">
        <title>Mercurial</title>

        <para>This repository type is used to define a Mercurial repository.
        </para>

<programlisting>
&lt;repository type="hg" name="hg.gtk-vnc"
    href="http://gtk-vnc.codemonkey.ws/hg/" /&gt;
</programlisting>

<programlisting>
&lt;branch repo="hg.gtk-vnc" module="outgoing.hg" checkoutdir="gtk-vnc"/&gt;
</programlisting>
      </section>

      <section id="moduleset-syntax-sources-mtn">
        <title>Monotone</title>

        <para>This repository type is used to define a Monotone repository.
        </para>

        <para>The <sgmltag class="attribute">server</sgmltag> attribute is
          used to specify the repository server.</para>

        <para>The <sgmltag class="attribute">database</sgmltag> attribute is
          used to specify the database to use for the repository.</para>

        <para>The <sgmltag class="attribute">defbranch</sgmltag> attribute is
          used specify the branch of the repository to use.</para>

<programlisting>
&lt;repository type="mtn" name="pidgin.im"
    server="pidgin.im" database="pidgin.im.mtn"
    defbranch="im.pidgin.pidgin"/&gt;
</programlisting>
      </section>

      <section id="moduleset-syntax-sources-svn">
        <title>Subversion</title>

        <para>This repository type is used to define a Subversion repository.
        </para>

<programlisting>
&lt;repository type="svn" name="svn.gnome.org" default="yes"
    href="http://svn.gnome.org/svn/"/&gt;
        </programlisting>

<!-- So how do I checkut out branch at a specific revision? -->

        <para>It allows a <sgmltag class="attribute">revision</sgmltag> on the
          <sgmltag class="element">branch</sgmltag> element. This attribute
          defines the branch to checkout or, if it is a number, a specific
          revision to checkout.</para>

<programlisting>
&lt;branch revision="gnome-2-20"/&gt;
        </programlisting>

        <para>It is possible to specify custom <literal>svn</literal> layout
          using <sgmltag class="attribute">trunk-template</sgmltag> (defaults to
          "%(module)s/trunk"),
          <sgmltag class="attribute">branches-template</sgmltag> (defaults to
          "%(module)s/branches/%(branch)s") and
          <sgmltag class="attribute">tags-template</sgmltag> (defaults to
          "%(module)s/tags/%(tag)s")</para>
      </section>

      <section id="moduleset-syntax-sources-system">
        <title>System</title>

        <para>This repository type is used to define a fake system repository.
          A system repository is required to create
          <link linkend="moduleset-syntax-defs-systemmodule"><sgmltag class="element">systemmodules</sgmltag></link>.
        </para>

<programlisting>
&lt;repository type="system" name="system"/&gt;
</programlisting>
      </section>

      <section id="moduleset-syntax-sources-tarball">
        <title>Tarballs</title>

        <para>This repository type is used to define a tarball repository.
        </para>

<programlisting>
&lt;repository type="tarball" name="dbus/dbus-python"
    href="http://dbus.freedesktop.org/releases/dbus-python/"/&gt;
</programlisting>

        <para>It allows the following attributes on the
          <sgmltag
	class="element">branch</sgmltag> element:</para>

        <para>The <sgmltag class="attribute">module</sgmltag> attribute
          specifies the file to download and compile, the
          <sgmltag
	class="attribute">version</sgmltag> attribute specifies the
          module version.</para>

        <para>The <sgmltag class="attribute">size</sgmltag> and
          <sgmltag class="attribute">hash</sgmltag>, as well as the obsolete
          <sgmltag class="attribute">md5sum</sgmltag>, attributes are optional.
          If these attributes are present, they are used to check that the
          source package was downloaded correctly.</para>

        <para>Any number of <sgmltag class="element">patch</sgmltag> elements
          may be nested inside the <sgmltag class="element">branch</sgmltag>
          element. These patches are applied, in order, to the source tree after
          unpacking. The <sgmltag class="attribute">file</sgmltag> attribute
          gives the patch filename, and the
          <sgmltag class="attribute">strip</sgmltag> attribute says how many
          levels of directories to prune when applying the patch.</para>

        <para>For module sets shipped with JHBuild, the patch files are looked
          up in the <filename>jhbuild/patches/</filename> directory; for module
          sets referred by URI, the patch files are looked for in the same
          directory as the moduleset file, or in its
          <filename>patches/</filename> subdirectory. It is also possible for
          the <sgmltag class="attribute">file</sgmltag> attribute to specify a
          URI, in which case it will be downloaded from that location.</para>

<programlisting>
&lt;branch module="dbus-python-0.80.2.tar.gz" version="0.80.2"
    repo="dbus/dbus-python"
    hash="md5:2807bc85215c995bd595e01edd9d2077" size="453499"&gt;
  &lt;patch file="dbus-glib-build.patch" strip="1" /&gt;
&lt;/branch&gt;
</programlisting>

        <para>A tarball <sgmltag class="element">branch</sgmltag> element may
          also contain <sgmltag class="element">quilt</sgmltag> elements which
          specify nested <sgmltag class="element">branch</sgmltag> to import.
        </para>
      </section>
    </section>

    <section id="moduleset-syntax-includes">
      <title>Including Other Module Sets</title>

      <para>JHBuild allows one module set to include the contents of another
        by reference using the <sgmltag class="element">include</sgmltag>
        element.</para>

<programlisting>
&lt;include href="<replaceable>uri</replaceable>"/&gt;
</programlisting>

      <para>The <sgmltag class="attribute">href</sgmltag> is a URI reference
        to the module set to be included, relative to the file containing the
        <sgmltag class="element">include</sgmltag> element.</para>

      <para>Only module definitions are imported from the referenced module
        set - module sources are not. Multiple levels of includes are allowed,
        but include loops are not (there isn't any code to handle loops at the
        moment).</para>
    </section>

    <section id="moduleset-syntax-defs">
      <title>Module Definitions</title>

      <para>There are various types of module definitions that can be used in
        a module set file, and the list can easily be extended. Only the most
        common ones will be mentioned here.</para>

      <para>They are all basically composed of a
        <sgmltag class="element">branch</sgmltag> element describing how to get
        the module and <sgmltag class="element">dependencies</sgmltag>,
        <sgmltag class="element">suggests</sgmltag> and
        <sgmltag class="element">after</sgmltag> elements to declare the
        dependencies of the module.</para>

      <para>Any modules listed in the
        <sgmltag class="element">dependencies</sgmltag> element will be added to
        the module list for <command>jhbuild build</command> if it isn't already
        included, and make sure the dependent modules are built first.</para>

      <para>After generating the modules list, the modules listed in the
        <sgmltag class="element">suggests</sgmltag> element will be used to
        further sort the modules list (although it will not pull any additional
        modules). This is intended for cases where a module has an optional
        dependency on another module.</para>

      <section id="moduleset-syntax-defs-autotools">
        <title>autotools</title>

        <para>The <sgmltag class="element">autotools</sgmltag> element is used
          to define a module which is compiled using the GNU Autotools build
          system.</para>

<programlisting>
&lt;autotools id="<replaceable>id</replaceable>"
	      [ autogenargs="<replaceable>autogenargs</replaceable>" ]
	      [ makeargs="<replaceable>makeargs</replaceable>" ]
	      [ makeinstallargs="<replaceable>makeinstallargs</replaceable>" ]
	      [ autogen-sh="<replaceable>autogen-sh</replaceable>" ]
	      [ makefile="<replaceable>makefile</replaceable>" ]
	      [ skip-autogen="<replaceable>skip-autogen</replaceable>" ]
	      [ skip-install="<replaceable>skip-install</replaceable>" ]
	      [ autogen-template="<replaceable>autogen-template</replaceable>" ]
	      [ check-target="<replaceable>check-target</replaceable>" ]
	      [ supports-non-srcdir-builds="<replaceable>supports-non-srcdir-builds</replaceable>" ]&gt;

  &lt;branch [ ... ] &gt;
    [...]
  &lt;/branch&gt;

  &lt;dependencies&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/dependencies&gt;
  &lt;after&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/after&gt;

&lt;/autotools&gt;
</programlisting>

        <para>The <sgmltag class="attribute">autogenargs</sgmltag> and
          <sgmltag class="attribute">makeargs</sgmltag> and
          <sgmltag class="attribute">makeinstallargs</sgmltag> attributes are
          used to specify additional arguments to pass to
          <command>autogen.sh</command>, <command>make</command> and
          <command>make install</command> respectively.</para>

        <para>The <sgmltag class="attribute">autogen-sh</sgmltag> attribute
          specifies the name of the autogen.sh script to run. The value
          <literal>autoreconf</literal> can be used if your module has no
          <command>autogen.sh</command> script equivalent. In that case, JHBuild
          will run <command>autoreconf -i</command>, followed by the proper
          <command>configure</command>.
          <sgmltag class="attribute">skip-autogen</sgmltag> chooses whether or
          not to run autogen.sh, it is a boolean with an extra
          <literal>never</literal> value to tell JHBuild to never skip running
          <command>autogen.sh</command>.
          <sgmltag class="attribute">skip-install</sgmltag> is a boolean
          attribute specifying whether to skip <command>make install</command>
          command on the module. <sgmltag class="attribute">makefile</sgmltag>
          specifies the filename of the makefile to use.</para>

        <para>The
          <sgmltag class="attribute">supports-non-srcdir-builds</sgmltag>
          attribute is used to mark modules that can't be cleanly built using a
          separate source directory.</para>

        <para>The <sgmltag class="attribute">autogen-template</sgmltag>
          attribute can be used if you need finer control over the autogen
          command line. It is a python format string, which will be substituted
          with the following variables: <varname>srcdir</varname>,
          <varname>autogen-sh</varname>, <varname>prefix</varname>,
          <varname>libdir</varname>, and <varname>autogenargs</varname>. For
          example, here is the default autogen-template:</para>

<programlisting>
%(srcdir)s/%(autogen-sh)s --prefix %(prefix)s --libdir %(libdir)s %(autogenargs)s
</programlisting>

        <para>The <sgmltag class="attribute">check-target</sgmltag> attribute
          must be specified (with false as value) for modules that do not have a
          <command>make check</command> target.</para>
      </section>

      <section id="moduleset-syntax-defs-cmake">
        <title>cmake</title>

        <para>The <sgmltag class="element">cmake</sgmltag> element is used to
          define a module which is built using the CMake build system.</para>

<programlisting>
&lt;cmake id="<replaceable>modulename</replaceable>"&gt;
  &lt;branch [ ... ] &gt;
    [...]
  &lt;/branch&gt;

  &lt;dependencies&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/dependencies&gt;
  &lt;after&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/after&gt;
&lt;/cmake&gt;
</programlisting>
      </section>

      <section id="moduleset-syntax-defs-distutils">
        <title>distutils</title>

        <para>The <sgmltag class="element">distutils</sgmltag> element is used
          to define a module which is built using python's distutils</para>

<programlisting>
&lt;distutils id="<replaceable>modulename</replaceable>"
            [ supports-non-srcdir-builds="<replaceable>yes|no</replaceable>" ]&gt;
  &lt;branch [ ... ] &gt;
    [...]
  &lt;/branch&gt;

  &lt;dependencies&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/dependencies&gt;
  &lt;after&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/after&gt;
&lt;/distutils&gt;
</programlisting>
      </section>

      <section id="moduleset-syntax-defs-linux">
        <title>linux</title>

        <para>The <sgmltag class="element">linux</sgmltag> element defines a
          module used to build a linux kernel. In addition, a separate kernel
          configuration can be chosen using the
          <sgmltag class="element">kconfig</sgmltag> subelement.</para>

<programlisting>
&lt;linux id="<replaceable>id</replaceable>"
	  [ makeargs="<replaceable>makeargs</replaceable>" ]&gt;

  &lt;branch [ ... ] &gt;
    [...]
  &lt;/branch&gt;

  &lt;dependencies&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/dependencies&gt;
  &lt;after&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/after&gt;

  &lt;kconfig [ repo="<replaceable>repo</replaceable>" ]
	    version="<replaceable>version</replaceable>"
	    [ module="<replaceable>module</replaceable>" ]
	    [ config="<replaceable>config</replaceable>" ] /&gt;

&lt;/linux&gt;
</programlisting>
      </section>

      <section id="moduleset-syntax-defs-perl">
        <title>perl</title>

        <para>The <sgmltag class="element">perl</sgmltag> element is used to
          build perl modules.</para>

        <para>The <sgmltag class="attribute">makeargs</sgmltag> attribute is
          used to specify additional arguments to pass to
          <command>make</command>.</para>

<programlisting>
&lt;perl id="<replaceable>modulename</replaceable>"
	 [ makeargs="<replaceable>makeargs</replaceable>" ]&gt;

  &lt;branch [ ... ] &gt;
    [...]
  &lt;/branch&gt;

  &lt;dependencies&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/dependencies&gt;
  &lt;after&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/after&gt;

&lt;/perl&gt;
</programlisting>
      </section>

      <section id="moduleset-syntax-defs-systemmodule">
        <title>systemmodule</title>

        <para>The <sgmltag class="element">systemmodule</sgmltag> element is
          used to specify modules that must be provided by the system. The
          module should be installed by your distributions package management
          system.</para>

<programlisting>
&lt;systemmodule id="<replaceable>modulename</replaceable>"&gt;
  &lt;pkg-config&gt;<replaceable>pkg-config</replaceable>.pc&lt;/pkg-config&gt;

  &lt;branch repo="<replaceable>pkg-config</replaceable>" version="<replaceable>version</replaceable>" [ ... ] &gt;
    [...]
  &lt;/branch&gt;
&lt;/systemmodule&gt;
</programlisting>
      </section>

      <section id="moduleset-syntax-defs-waf">
        <title>waf</title>

        <para>The <sgmltag class="element">waf</sgmltag> element is used to
          define a module which is built using the Waf build system.</para>

        <para>The <sgmltag class="attribute">waf-command</sgmltag> attribute
          is used to specify the waf command script to use; it defaults to
          <command>waf</command>.</para>

<programlisting>
&lt;waf id="<replaceable>modulename</replaceable>"&gt;
	 [ waf-command="<replaceable>waf-command</replaceable>" ]&gt;
  &lt;branch [ ... ] &gt;
    [...]
  &lt;/branch&gt;

  &lt;dependencies&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/dependencies&gt;
  &lt;after&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/after&gt;
&lt;/waf&gt;
</programlisting>
      </section>

      <section id="moduleset-syntax-defs-testmodule">
        <title>testmodule</title>

        <para>The <sgmltag class="element">testmodule</sgmltag> element is
          used to create a module which runs a suite of tests using LDTP or
          Dogtail.</para>

<programlisting>
&lt;testmodule id="<replaceable>id</replaceable>"
	       type="<replaceable>type</replaceable>"&gt;

  &lt;branch [ ... ] &gt;
    [...]
  &lt;/branch&gt;

  &lt;dependencies&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/dependencies&gt;
  &lt;after&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/after&gt;

  &lt;testedmodules&gt;
    &lt;tested package="<replaceable>package</replaceable>" /&gt;
  &lt;/testedmodules&gt;

&lt;/testmodule&gt;
</programlisting>

        <para>The <sgmltag class="attribute">type</sgmltag> attribute gives
          the type of tests to be run in the module. 'dogtail' uses python to
          invoke all .py files. 'ldtp' invokes 'ldtprunner run.xml'.</para>

        <para>Unless the noxvfb configuration option is set, an Xvfb server is
          started to run the tests in</para>
      </section>

      <section id="moduleset-syntax-defs-metamodule">
        <title>metamodule</title>

        <para>The <sgmltag class="element">metamodule</sgmltag> element
          defines a module that doesn't actually do anything. The only purpose
          of a module of this type is its dependencies.</para>

        <para>For example, meta-gnome-desktop depends on all the key
          components of the GNOME desktop, therefore telling JHBuild to install
          it actually installs the full desktop.</para>

<programlisting>
&lt;metamodule id="<replaceable>modulename</replaceable>"&gt;
  &lt;dependencies&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/dependencies&gt;
  &lt;suggests&gt;
    &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
    ...
  &lt;/suggests&gt;
&lt;/metamodule&gt;
</programlisting>

        <para>The <sgmltag class="attribute">id</sgmltag> attribute gives the
          name of the module. The child elements are handled as for
          <link linkend="moduleset-syntax-defs-autotools"><sgmltag class="element">autotools</sgmltag></link>.
        </para>
      </section>
    </section>

    <section id="moduleset-deprecated-elements">
      <title>Deprecated Elements</title>

      <section id="moduleset-deprecated-elements-syntax-sources">
        <title>Module Sources</title>

        <section id="moduleset-syntax-sources-cvsroot">
          <title>cvsroot</title>

          <para>The <sgmltag class="element">cvsroot</sgmltag> element is now
            deprecated - the <sgmltag class="element">repository</sgmltag>
            element should be used instead.</para>

          <para>The <sgmltag class="element">cvsroot</sgmltag> element is used
            to describe a CVS repository.</para>

<programlisting>
  &lt;cvsroot name="<replaceable>rootname</replaceable>"
           [ default="<replaceable>yes|no</replaceable>" ]
           root="<replaceable>anon-cvsroot</replaceable>"
           password="<replaceable>anon-password</replaceable>"/&gt;
</programlisting>

          <para>The <sgmltag class="attribute">name</sgmltag> attribute should
            be a unique identifier for the CVS repository.</para>

          <para>The <sgmltag class="attribute">default</sgmltag> attribute
            says whether this is the default module source for this module set
            file.</para>

          <para>The <sgmltag class="attribute">root</sgmltag> attribute lists
            the CVS root used for anonymous access to this repository, and the
            <sgmltag class="attribute">password</sgmltag> attribute gives the
            password used for anonymous access.</para>
        </section>

        <section id="moduleset-syntax-sources-svnroot">
          <title>svnroot</title>

          <para>The <sgmltag class="element">svnroot</sgmltag> element is now
            deprecated - the <sgmltag class="element">repository</sgmltag>
            element should be used instead.</para>

          <para>The <sgmltag class="element">svnroot</sgmltag> element is used
            to describe a Subversion repository.</para>

<programlisting>
  &lt;svnroot name="<replaceable>rootname</replaceable>"
           [ default="<replaceable>yes|no</replaceable>" ]
           href="<replaceable>anon-svnroot</replaceable>"/&gt;
</programlisting>

          <para>The <sgmltag class="attribute">name</sgmltag> attribute should
            be a unique identifier for the Subversion repository.</para>

          <para>If <sgmltag class="attribute">default</sgmltag> attribute says
            whether this is the default module source for this module set file.
          </para>

          <para>The <sgmltag class="attribute">href</sgmltag> attribute lists
            the base URL for the repository. This will probably be either a
            <literal>http</literal>, <literal>https</literal> or
            <literal>svn</literal> URL.</para>
        </section>
      </section>

<!-- end of deprecated module sources -->

      <section>
        <title>Deprecated Module Types</title>

        <warning>
          <para>This section describes deprecated elements, they may still be
            used in existing module sets but it is advised not to use them
            anymore.</para>
        </warning>

        <section id="moduleset-syntax-defs-tarball">
          <title>tarball</title>

          <important>
            <para>This deprecated element is just a thin wrapper around both
              <sgmltag class="element">autotools</sgmltag> module type and
              <sgmltag class="element">tarball</sgmltag> repository type.</para>
          </important>

          <para>The <sgmltag class="element">tarball</sgmltag> element is used
            to define a module that is to be built from a tarball.</para>

<programlisting>
  &lt;tarball id="<replaceable>modulename</replaceable>"
              [ version="<replaceable>version</replaceable>" ]
              [ checkourdir="<replaceable>checkoutdir</replaceable>" ]
              [ autogenargs="<replaceable>autogenargs</replaceable>" ]
              [ makeargs="<replaceable>makeargs</replaceable>" ]
              [ autogen-sh="<replaceable>autogen-sh</replaceable>" ]
              [ supports-non-srcdir-builds="<replaceable>yes|no</replaceable>" ]&gt;
    &lt;source href="<replaceable>source-url</replaceable>"
            [ size="<replaceable>source-size</replaceable>" ]
            [ hash="<replaceable>source-algo:source-hash</replaceable>" ]
            [ md5sum="<replaceable>source-md5sum</replaceable>" ]/&gt;
    &lt;patches&gt;
      &lt;patch file="<replaceable>filename</replaceable>" strip="<replaceable>level</replaceable>"/&gt;
      ...
    &lt;/patches&gt;
    &lt;dependencies&gt;
      &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
      ...
    &lt;/dependencies&gt;
    &lt;suggests&gt;
      &lt;dep package="<replaceable>modulename</replaceable>"/&gt;
      ...
    &lt;/suggests&gt;
  &lt;/tarball&gt;
</programlisting>

          <para>The <sgmltag class="attribute">id</sgmltag> and
            <sgmltag class="attribute">version</sgmltag> attributes are used to
            identify the module.</para>

          <para>The <sgmltag class="element">source</sgmltag> element
            specifies the file to download and compile. The
            <sgmltag class="attribute">href</sgmltag> attribute is mandatory,
            while the <sgmltag class="attribute">size</sgmltag> and
            <sgmltag class="attribute">hash</sgmltag>, as well as the obsolete
            <sgmltag class="attribute">md5sum</sgmltag>, attributes are
            optional. If these last two attributes are present, they are used to
            check that the source package was downloaded correctly.</para>

          <para>The <sgmltag class="element">patches</sgmltag> element is used
            to specify one or more patches to apply to the source tree after
            unpacking, the <sgmltag class="attribute">file</sgmltag> attribute
            gives the patch filename, and the
            <sgmltag class="attribute">strip</sgmltag> attribute says how many
            levels of directories to prune when applying the patch.</para>

          <para>For module sets shipped with JHBuild, the patch files are
            looked up in the <filename>jhbuild/patches/</filename> directory;
            for module sets referred by URI, the patch files are looked for in
            the same directory as the moduleset file, or in its
            <filename>patches/</filename> subdirectory. It is also possible for
            the <sgmltag class="attribute">file</sgmltag> attribute to specify a
            URI, in which case it will be downloaded from that location.</para>

          <para>The other attributes and the
            <sgmltag class="element">dependencies</sgmltag>,
            <sgmltag class="element">suggests</sgmltag> and
            <sgmltag class="element">after</sgmltag> elements are processed as
            for
            <link linkend="moduleset-syntax-defs-autotools">autotools</link>.
          </para>
        </section>
      </section>

<!-- end of deprecated module types -->
    </section>

<!-- end of deprecated elements -->
  </section>
</article>
