[jhbuild] Refer to sample.jhbuildrc, remove old svn refs & improve consistency.
- From: Frederic Peters <fpeters src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [jhbuild] Refer to sample.jhbuildrc, remove old svn refs & improve consistency.
- Date: Wed, 23 Sep 2009 14:43:35 +0000 (UTC)
commit 50832d9e94f266432492fe14b5eebcfecff1b834
Author: Craig Keogh <cskeogh adam com au>
Date: Sun Sep 20 17:59:43 2009 +0930
Refer to sample.jhbuildrc, remove old svn refs & improve consistency.
doc/C/jhbuild.xml | 1192 ++++++++++++++++++++++++++---------------------------
sample.jhbuildrc | 2 +-
2 files changed, 589 insertions(+), 605 deletions(-)
---
diff --git a/doc/C/jhbuild.xml b/doc/C/jhbuild.xml
index 876b4f2..7b36fe9 100644
--- a/doc/C/jhbuild.xml
+++ b/doc/C/jhbuild.xml
@@ -40,9 +40,9 @@
</revhistory>
<abstract role="description">
- <para>JHBuild is a tool used to build the whole GNOME desktop from the
- SVN source, however, it can be used to build other projects by
- creating a moduleset for it.</para>
+ <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>
@@ -50,68 +50,71 @@
<title>Introduction</title>
<para>JHBuild is a tool designed to ease building collections of
- source packages (also known as modules). It uses <quote>module
- set</quote> files to describe the modules available to build.
- These files include dependency information that allows JHBuild to
- work out what modules need to be built and in what order to build
- what the user requested.</para>
+ 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 make it usable with other projects. A <quote>module
- set</quote> file can be hosted on a web server, allowing people to
- provide build rules independent of JHBuild.</para>
+ 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://subversion.tigris.org/";>Subversion,</ulink>
<ulink url="http://wiki.gnuarch.org/";>Arch</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 archives hosted on web or FTP sites;
- and using a variety of build systems, including Autotools, CMake,
- WAF, Ant, Python Distutils and Perl Makefiles.
- </para>
+ 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, Ant, 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 everything into a separate install prefix so that it
- doesn't interfere with the rest of the system.</para>
+ 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 takes a bit of work to set up on a system. As well
- as installing JHBuild's prerequisites, it is necessary to install
- the prerequisite tools needed to obtain and build the software
- sources.</para>
+ <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>Before downloading JHBuild, you should make sure you have
- a copy of Python >= 2.0 installed on your system. It is also
- essential that the Expat XML parser extension is installed.
- This will be the case if you are using Python >= 2.3, or had
- expat installed when building Python. You can check whether
- this is the case by running the following simple command from
- the Python interpreter:</para>
-
- <screen><prompt>>>></prompt> <userinput>import xml.parsers.expat</userinput>
+ <para>Before downloading JHBuild, verify a copy of Python
+ >= 2.0 is installed. It is essential that the Expat XML
+ parser extension is installed. Expat XML is supplied with Python
+ >= 2.3. To verify Expat XML is installed run the following
+ commands:</para>
+
+ <screen><prompt>#</prompt> <userinput>python</userinput>
+Python 2.6.2+ (release26-maint, Sep 13 2009, 21:26:06)
+[GCC 4.4.1] on linux2
+Type "help", "copyright", "credits" or "license" for more information.
+<prompt>>>></prompt> <userinput>import xml.parsers.expat</userinput>
<prompt>>>></prompt></screen>
- <para>If this completes without an exception, then it is
- installed correctly.</para>
+ <para>If the above completes without an exception, then Expat
+ XML is installed correctly.</para>
- <para>At the moment, the only way to download JHBuild is via
- Subversion. This can be achieved with the following commands. They
- should be run in the directory where JHBuild will be installed
- (for example, <filename>~/checkout/gnome2</filename>).</para>
+ <para>The only 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/gnome2</filename>.</para>
<screen><prompt>$</prompt> <userinput>git clone git://git.gnome.org/jhbuild</userinput>
<computeroutput>...</computeroutput>
@@ -119,7 +122,7 @@
<para>This will download JHBuild into a new folder named
<filename>jhbuild</filename> under the current
- directory. Now to build and install it:</para>
+ directory. Now to build and install JHBuild:</para>
<screen><prompt>$</prompt> <userinput>cd jhbuild</userinput>
<prompt>$</prompt> <userinput>./autogen.sh</userinput>
@@ -130,9 +133,8 @@
<computeroutput>...</computeroutput>
<prompt>$</prompt></screen>
- <para>Alternatively, if your work environment doesn't have autotools or
- gnome-doc-utils installed you can also build and install JHBuild that
- way:</para>
+ <para>Alternatively, if autotools or gnome-doc-utils is not
+ installed, install JHBuild as follows:</para>
<screen><prompt>$</prompt> <userinput>cd jhbuild</userinput>
<prompt>$</prompt> <userinput>make -f Makefile.plain</userinput>
@@ -141,26 +143,25 @@
<computeroutput>...</computeroutput>
<prompt>$</prompt></screen>
- <para>If these steps complete successfully, a small shell script
- should be installed in <filename>~/.local/bin</filename> to start
- JHBuild. If this directory is not in the <envar>PATH</envar>,
- it will need to be added. This can be done with the command:</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>This command will need to be run every time you login and
- want to use JHBuild. In order to permanently add
- <filename>~/.local/bin</filename> to your <envar>PATH</envar> variable,
- run the following command:</para>
+ <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>
- <para>Before JHBuild can be run, it is necessary to set up a
- configuration file, located at <filename>~/.jhbuildrc</filename>.
- This file specifies JHBuild will behave.</para>
+ <para>Before running JHBuild, it is necessary to set up a
+ configuration file located at <filename>~/.jhbuildrc</filename>.
+ </para>
</section>
@@ -168,110 +169,102 @@
<title>Configuring JHBuild</title>
<para>The <filename>~/.jhbuildrc</filename> file uses Python
- syntax to set a number of configuration variables for JHBuild.
- A minimal configuration file might look something like
- this:</para>
-
- <programlisting>
-moduleset = 'gnome-2.22'
-modules = [ 'meta-gnome-desktop' ]
-checkoutroot = os.path.join(os.environ['HOME'], 'checkout', 'gnome2')
-prefix = os.path.join(os.environ['HOME'], 'prefix')
-</programlisting>
+ syntax to set configuration variables for JHBuild. An example is
+ provided within the jhbuild directory, see
+ <filename>sample.jhbuildrc</filename>. Copy
+ <filename>sample.jhbuildrc</filename> to
+ <filename>~/.jhbuildrc</filename> and customize as required.
+ </para>
- <para>This will make JHBuild build the
+ <para>The sample configuration will make JHBuild build the
<application>meta-gnome-desktop</application> module and its
- dependencies from the <systemitem>gnome-2.22</systemitem> module
- set. It will unpack source trees to
+ dependencies from the <systemitem>gnome-2.28</systemitem> module
+ set. JHBuild will unpack source trees to
<filename>~/checkout/gnome2</filename> and install all files to
- subdirectories of <filename>~/prefix</filename>.</para>
+ subdirectories of <filename>/opt/gnome2</filename>. The two
+ directories must be writable.</para>
<para>Configuration variables are documented in <xref
- linkend="config-reference"/>, here are some of the most commonly used
- ones:</para>
+ 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. If a module set name is a fully
- qualified URL, then the module set will be cached locally
- and regularly updated. If a module with the same name is
- present in more than one module set, the last set listed
- takes priority.</simpara>
+ 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 giving the modules you want to
+ <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 <command>buildone</command> is used.</simpara>
+ 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>The base directory where all source modules
- are unpacked or checked out of revision control.</simpara>
+ <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/gnome2</filename>.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="cfg-prefix"><varname>prefix</varname></link></term>
<listitem>
- <simpara>The directory prefix to install modules
- to. You must have write permissions to this directory, or
- JHBuild will be unable to install files.</simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><varname>os.environ</varname></term>
- <listitem>
- <simpara>A dictionary representing the environment. This
- can be used to set or get environment variable values as
- shown in the example configuration above.</simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><link linkend="cfg-skip"><varname>skip</varname></link></term>
- <listitem>
- <simpara>A list of module names to exclude when deciding
- what to build. One use of this variable is to use the
- version of a package included with the distribution
- instead of building it.</simpara>
+ <simpara>A string specifying the prefix to install modules to.
+ This directory must be writable. Defaults to
+ <literal>'/opt/gnome2'</literal>.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="cfg-autogenargs"><varname>autogenargs</varname></link></term>
<listitem>
- <simpara>A string listing additional arguments to pass
- to the <command>autogen.sh</command> or
- <command>configure</command> scripts for modules.</simpara>
+ <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 arguments to be pass
- to the <command>make</command> command.</simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><link linkend="cfg-repos"><varname>repos</varname></link></term>
- <listitem>
- <simpara>By default, JHBuild will check out code from
- repositories using an anonymous repository location. This
- dictionary is used to tell JHBuild to use an alternative
- repository location for a particular repository (a developer
- would probably want to do this). This variable is a
- dictionary where the keys are short repository names (for
- example,
- <systemitem class="systemname">svn.gnome.org</systemitem>
- is used for the GNOME SVN repository), and the values are the
- alternative repository location strings.</simpara>
+ <simpara>A string listing additional arguments to be
+ passed to <command>make</command>. Defaults to
+ <literal>''</literal>.</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -281,8 +274,8 @@ prefix = os.path.join(os.environ['HOME'], 'prefix')
<title>Build Prerequisites</title>
<para>Before any modules can be built, it is necessary to have
- certain build tools installed. These can include the GNU Autotools
- (<application>autoconf</application>,
+ 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
@@ -291,118 +284,132 @@ prefix = os.path.join(os.environ['HOME'], 'prefix')
<application>g++</application>), pkg-config and
Python, depending on which modules will be built.</para>
- <para>JHBuild can check if your system has these tools installed
- using the <command>sanitycheck</command> command:</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 prints any messages, these can be fixed in
- one of two ways:</para>
+ <para>If this command displays any messages, the errors can be
+ fixed in one of two ways:</para>
<orderedlist>
<listitem>
<simpara>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.
- The <command>sanitycheck</command> command
- should be run again afterwards to make sure required tools
- are present.</simpara>
+ 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.</simpara>
</listitem>
<listitem>
<simpara>Run the <command>bootstrap</command> command to
- install the build prerequsites.</simpara>
- </listitem>
- </orderedlist>
-
- <para>The <command>bootstrap</command> command can be invoked
- like so:</para>
-
+ download, build and install the build prerequisites:</simpara>
<screen><prompt>$</prompt> <userinput>jhbuild bootstrap</userinput></screen>
-
- <para>This will download and install all the build
- prerequisites. Once it is finished, the
- <command>sanitycheck</command> command should be rerun to verify
- that everything is in place.</para>
+ <para>When complete, run the
+ <command>sanitycheck</command> command to verify the required
+ tools are present.</para>
<note>
- <para>The <command>bootstrap</command> command does not build
- all the packages required by these tools. If your distribution
- does not provide those packages, then they will need to be built
- separately.</para>
-
- <para>Some packages to check for include
- <application>m4</application>, <application>perl</application>
- and a C compiler (For example, <application>gcc</application>).</para>
+ <para>The <command>bootstrap</command> command does not build
+ all the package dependencies required by the build tools. If
+ your distribution does not provide the required packages, they
+ will need to be built outside of the JHBuild environment.
+ </para>
+
+ <para>The build tools dependencies include
+ <application>m4</application>, <application>perl</application>
+ and a C compiler (for example, <application>gcc</application>).
+ </para>
</note>
+
+ </listitem>
+ </orderedlist>
</section>
<section id="getting-started-use">
<title>Using JHBuild</title>
- <para>Now that everything is set up, JHBuild can be used to
- build some software. To build all the modules selected in the
+ <para>After set up is complete, JHBuild can be used to build
+ software. To build all the modules selected in the
<filename>~/.jhbuildrc</filename> file, run the following command:</para>
<screen><prompt>$</prompt> <userinput>jhbuild build</userinput></screen>
- <para>This 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. These choices
- include dropping to a shell to fix the error, rerunning the build
- from various stages, giving up on the module (which will also
- cause any modules depending on it to fail), or ignore the error and
+ <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 their names as arguments to
- the <command>build</command> command, for example, to build gtk+:</para>
+ 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 you exit JHBuild part way through a build for some
- reason, it is possible to pick up a build at a particular
- module using the <option>--start-at</option> option:</para>
+ <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,
- the <command>buildone</command> command can be used. This command
- should only be used if you have manually installed all dependencies,
- else the build will fail.</para>
+ 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>To get a list of the modules and dependencies jhbuild will
- build, and the order in which they will be built, use the
+ <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, the
- <command>info</command> command can be used:</para>
+ <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>If your internet bandwidth varies, or you wish to modify the
- sources before building them, you can download or update all the
- software sources without actually building them:</para>
+ <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 on, you can tell JHBuild to build everything without
- downloading or updating the sources:</para>
+ <para>Later, JHBuild can build everything without downloading or
+ updating the sources:</para>
<screen><prompt>$</prompt> <userinput>jhbuild build --no-network</userinput></screen>
- <para>If you want to run a particular command with the same
- environment variables set that JHBuild uses, use the
- <command>run</command> command:</para>
+ <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 environment used by JHBuild, use the
- <command>shell</command> command:</para>
+ <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>
@@ -414,41 +421,40 @@ prefix = os.path.join(os.environ['HOME'], 'prefix')
<para>
Coupled with the <ulink url="http://buildbot.net";>Buildbot</ulink>
- project, JHBuild can also help as a continuous integration tool. Such a
- configuration is used by the GNOME project at <ulink
- url="http://build.gnome.org";>build.gnome.org</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 just a variation of a normal JHBuild installation,
- the difference is mostly it will serve the requests of the Buildbot
- master instead of your own. Thus it is generally advised to get
- JHBuild running and performing correctly (a full run with most
- modules building fine is a good test) before adding the few special
- Buildbot bits.
+ 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>
- All Buildbot-related commands are options of the
- <command>bot</command>, downloading and installing the extra required
- software is done like this:
+ 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 been run successfully, there are three new
- configuration variables to define in <filename>~/.jhbuildrc</filename>.
+ Once this step has completed successfully, three new
+ configuration variables are required in <filename>~/.jhbuildrc</filename>.
</para>
<note>
<para>
- It is currently not possible to use an alternate configuration file,
- the <option>--file</option> will not get desired effects.
- </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>
@@ -458,13 +464,13 @@ jhbuildbot_password = 'password'
</programlisting>
<para>
- <varname>jhbuildbot_master</varname> is a string pointing to the
+ <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; you should contact the Buildbot master administrators to
- get them.
+ master server. Contact the Buildbot master administrators to
+ obtain the slave name and password.
</para>
<note>
@@ -503,11 +509,11 @@ jhbuildbot_password = 'password'
<variablelist>
<varlistentry>
- <term><option>-f</option>, <option>--file</option>
+ <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>~/.jhbuildrc</filename>.</simpara>
+ <simpara>Use an alternative configuration file instead of
+ the default <filename>~/.jhbuildrc</filename>.</simpara>
</listitem>
</varlistentry>
@@ -515,19 +521,19 @@ jhbuildbot_password = 'password'
<term><option>-m</option>, <option>--moduleset</option>
<replaceable>moduleset</replaceable></term>
<listitem>
- <simpara>Use a module set other than the one listed in the
- configuration file. This should be a relative path if the
+ <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 it is located elsewhere.</simpara>
+ 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 is useful
- when leaving a build unattended, in order to ensure it is not
- interrupted.</simpara>
+ <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>
@@ -537,8 +543,8 @@ jhbuildbot_password = 'password'
<section id="command-reference-autobuild">
<title>autobuild</title>
- <para>The <command>autobuild</command> command is used to
- automatically build the modules specified in the configuration
+ <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>
@@ -553,7 +559,8 @@ jhbuildbot_password = 'password'
<para>The <option>--autogen</option>, <option>--clean</option>,
<option>--skip</option> and <option>--start-at</option> options
- are processed in the same way as for the <command>build</command>
+ are processed as per the
+ <link linkend="command-reference-build"><command>build</command></link>
command.</para>
<variablelist>
@@ -561,16 +568,16 @@ jhbuildbot_password = 'password'
<term><option>--report-url=<replaceable>reporturl</replaceable></option>,
<option>-r <replaceable>reporturl</replaceable></option></term>
<listitem>
- <simpara>This option specifies the JhAutobuild URL which
- JHBuild should report to</simpara>
+ <simpara>This option specifies the JhAutobuild URL to report
+ to.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose</option>, <option>-v</option></term>
<listitem>
- <simpara>This option causes JHBuild's output to be more
- verbose</simpara>
+ <simpara>If specified, JHBuild's output will be more
+ verbose.</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -580,19 +587,21 @@ jhbuildbot_password = 'password'
<section id="command-reference-bootstrap">
<title>bootstrap</title>
- <para>The <command>bootstrap</command> command is used to
- install a set of build utilities required to build most modules
- (eg. autoconf, automake, etc).</para>
+ <para>The <command>bootstrap</command> command installs a set of
+ build utilities required to build most modules (e.g.
+ <application>autoconf</application>,
+ <application>automake</application>, etc).</para>
<cmdsynopsis>
<command>jhbuild bootstrap</command>
</cmdsynopsis>
- <para>Internally, <command>bootstrap</command> is implemented
- using the same code as <command>build</command>, using the
- <filename>bootstrap.modules</filename> moduleset.</para>
+ <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>Look at the <link linkend="command-reference-build">build</link>
+ <para>See the
+ <link linkend="command-reference-build"><command>build</command></link>
command documentation for available options.</para>
</section>
@@ -600,8 +609,8 @@ jhbuildbot_password = 'password'
<section id="command-reference-build">
<title>build</title>
- <para>The <command>build</command> command is used to build one
- or more packages, including their dependencies.</para>
+ <para>The <command>build</command> command builds one or more
+ packages, including their dependencies.</para>
<cmdsynopsis>
<command>jhbuild build</command>
@@ -624,8 +633,9 @@ jhbuildbot_password = 'password'
<arg rep="repeat">module</arg>
</cmdsynopsis>
- <para>If no module names are given on the command line, then the
- module list found in the configuration file will be used.</para>
+ <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>
@@ -634,8 +644,8 @@ jhbuildbot_password = 'password'
<simpara>Always run <command>autogen.sh</command>
before building modules. By default,
<command>autogen.sh</command> will only be called if the
- toplevel makefile is missing. Otherwise, it relies on the
- package's makefiles to detect if configure needs to be
+ top-level makefile is missing. Otherwise, JHBuild relies on
+ the package's makefiles to detect if configure needs to be
rebuilt or rerun.</simpara>
</listitem>
</varlistentry>
@@ -676,8 +686,8 @@ jhbuildbot_password = 'password'
<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, it will
- fail.</simpara>
+ module can't be built without network access, the module build
+ will fail.</simpara>
</listitem>
</varlistentry>
@@ -685,9 +695,8 @@ jhbuildbot_password = 'password'
<term><option>-s</option>,
<option>--skip</option>=<replaceable>module,...</replaceable></term>
<listitem>
- <simpara>Ignore the named modules when following
- dependencies to expand the list of modules to be
- built.</simpara>
+ <simpara>Do not build the listed modules. Used to skip
+ the building of specified dependencies.</simpara>
</listitem>
</varlistentry>
@@ -695,11 +704,10 @@ jhbuildbot_password = 'password'
<term>
<option>--tags</option>=<replaceable>tag,...</replaceable></term>
<listitem>
- <simpara>Ignore modules that do not match any of
- <replaceable>tag</replaceable> when following dependencies
- to expand the list of modules to be built.</simpara>
- <simpara>At the moment modules are automatically attributed a tag
- with the name of the module set they sit in.</simpara>
+ <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>
@@ -707,10 +715,9 @@ jhbuildbot_password = 'password'
<term><option>-t</option>,
<option>--start-at</option>=<replaceable>module</replaceable></term>
<listitem>
- <simpara>After expanding the list of modules to build,
- start at the named module rather than at the beginning of
- the list. This is useful if the build was interrupted for
- some reason.</simpara>
+ <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>
@@ -718,10 +725,10 @@ jhbuildbot_password = 'password'
<term><option>-D</option>
<replaceable>date</replaceable></term>
<listitem>
- <simpara>If the underlying version control system supports
- it, try to update the source tree to its state at the
- given date before building. The date string should be in
- ISO format.</simpara>
+ <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>
@@ -729,7 +736,7 @@ jhbuildbot_password = 'password'
<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>
+ than in a simulated Xvfb.</simpara>
</listitem>
</varlistentry>
@@ -737,8 +744,8 @@ jhbuildbot_password = 'password'
<term><option>-C</option>,
<option>--try-checkout</option></term>
<listitem>
- <simpara>If the build fails, and the version control system
- supports it, force a checkout and run
+ <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>
@@ -756,32 +763,32 @@ jhbuildbot_password = 'password'
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem>
- <simpara>Build the modules even if policy tells it is
+ <simpara>Build the modules even if policy states it is
not required.</simpara>
- </listitem>
+ </listitem>
</varlistentry>
<varlistentry>
<term><option>--build-optional-modules</option></term>
<listitem>
- <simpara>Some modules, listed as optional dependencies, may not be
- required to build the target module, this option includes them
- nevertheless.</simpara>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--min-time</option>=<replaceable>time</replaceable></term>
- <listitem>
- <simpara>Skip modules installed more recently than the given
- relative time; the <replaceable>time</replaceable> string format
- is a number followed by a unit, with the following units being
- supported: seconds (s), minutes (m), hours (h) and days (d).
- </simpara>
- <simpara>Example: <option>--min-time=2h</option> will skip
- modules that have been built less than two hours ago.</simpara>
- </listitem>
- </varlistentry>
+ <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-time</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-time=2h</option> will skip modules built less
+ than two hours ago.</simpara>
+ </listitem>
+ </varlistentry>
</variablelist>
@@ -791,9 +798,8 @@ jhbuildbot_password = 'password'
<title>buildone</title>
<para>The <command>buildone</command> command is similar to
- <command>build</command>, but it does not use dependency
- information to expand the module list. It is useful for quickly
- rebuilding one or more modules.</para>
+ <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>
@@ -811,21 +817,21 @@ jhbuildbot_password = 'password'
<para>The <option>--autogen</option>, <option>--clean</option>,
<option>-d</option>, <option>--distcheck</option>,
<option>--no-network</option>, <option>-D</option> and
- <option>-x</option> options are processed in the same way as for the
- <command>build</command> command.</para>
+ <option>-x</option> options are processed as per the
+ <link linkend="command-reference-build"><command>build</command></link>
+ command.</para>
- <para>Unlike the <command>build</command> command, at least one
- module must be listed on the command line.</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 modules in
- GNOME Subversion have the correct branch definition. For example,
- if modules are marked as not having branched, JHBuild checks
- this is true.</para>
+ <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>
@@ -836,7 +842,7 @@ jhbuildbot_password = 'password'
<varlistentry>
<term><option>--branch</option>=<replaceable>branch</replaceable>, <option>-b</option> <replaceable>branch</replaceable></term>
<listitem>
- <simpara>Specify the branch to check</simpara>
+ <simpara>The branch to check.</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -850,7 +856,7 @@ libgnomecanvas is missing branch definition for gnome-2-20
<section id="command-reference-clean">
<title>clean</title>
- <para>The <command>clean</command> command is used to clean the build
+ <para>The <command>clean</command> command cleans the build
directories of one or more modules.</para>
<cmdsynopsis>
@@ -859,10 +865,12 @@ libgnomecanvas is missing branch definition for gnome-2-20
<arg>--start-at=<replaceable>module</replaceable></arg>
</cmdsynopsis>
- <para>If no module names are given on the command line, then the module
- list found in the configuration file will be used.</para>
+ <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>Look at the <link linkend="command-reference-build">build</link>
+ <para>See the
+ <link linkend="command-reference-build"><command>build</command></link>
command documentation for a description of available options.</para>
</section>
@@ -874,7 +882,7 @@ libgnomecanvas is missing branch definition for gnome-2-20
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 nice diagram.</para>
+ to produce a diagram.</para>
<cmdsynopsis>
<command>jhbuild dot</command>
@@ -883,18 +891,18 @@ libgnomecanvas is missing branch definition for gnome-2-20
<arg rep="repeat">module</arg>
</cmdsynopsis>
- <para>If no module names are given on the command line, then the
- module list found in the configuration file will be used.</para>
+ <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 will add dotted lines from
- the modules to their soft dependencies. The <option>--clusters</option>
- option will group modules from <link
+ <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 this command can easily be piped to the
- <command>dot</command> utility to generate a PostScript
- file:</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>
@@ -926,15 +934,14 @@ libgnomecanvas is missing branch definition for gnome-2-20
<command>jhbuild gui</command>
</cmdsynopsis>
- <para>The <command>gui</command> graphical interface is
- rendered using GTK, so some extra support libraries will be
- required</para>
+ <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 is used to display
+ <para>The <command>info</command> command displays
information about one or more modules.</para>
<cmdsynopsis>
@@ -942,27 +949,24 @@ libgnomecanvas is missing branch definition for gnome-2-20
<arg choice="plain" rep="repeat">module</arg>
</cmdsynopsis>
- <para>The command prints the module name, type, dependencies,
+ <para>The command displays the module name, type, dependencies,
dependent packages, and the time it was last installed with
- JHBuild. It may also print some information specific to the
- module type, such as the CVS repository or download URL.</para>
+ 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 print information
- about all the modules defined in the module set.</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 is used to show the
+ <para>The <command>list</command> command displays the
expanded list of modules the <command>build</command> command
would build.</para>
- <para>Run with the <option>-a</option> option, this command will
- list all the modules known from your moduleset configuration
- regardless of the build dependency.</para>
-
<cmdsynopsis>
<command>jhbuild list</command>
<arg>-a</arg>
@@ -975,15 +979,24 @@ libgnomecanvas is missing branch definition for gnome-2-20
<arg rep="repeat">module</arg>
</cmdsynopsis>
- <para>If no module names are given on the command line, then the
- module list found in the configuration file will be used.</para>
+ <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>, <option>--start-at</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</simpara>
+ <simpara>List all the modules from the module set regardless of
+ the build dependencies.</simpara>
</listitem>
</varlistentry>
@@ -991,57 +1004,18 @@ libgnomecanvas is missing branch definition for gnome-2-20
<term><option>-r</option>,
<option>--show-revision</option></term>
<listitem>
- <simpara>If a particular module is being checked out on a
- branch, show the branch tag name with the module
- name.</simpara>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>s</option>,
- <option>--skip</option>=<replaceable>module,...</replaceable>
- </term>
- <listitem>
- <simpara>Ignore the named modules when following
- dependencies to expand the list of modules.</simpara>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-t</option>,
- <option>--start-at</option>=<replaceable>module</replaceable></term>
- <listitem>
- <simpara>Show only the modules listed after the given
- <replaceable>module</replaceable>.</simpara>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>--tags</option>=<replaceable>tag,...</replaceable></term>
- <listitem>
- <simpara>Ignore modules that do not match any of
- <replaceable>tag</replaceable> when following dependencies
- to expand the list of modules to be displayed.</simpara>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--list-optional-modules</option></term>
- <listitem>
- <simpara>Some modules, listed as optional dependencies, may not be
- required to get to the target module, this option includes them
- nevertheless.</simpara>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--ignore-suggests</option></term>
- <listitem>
- <simpara>Do not list soft dependencies.</simpara>
+ <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>
@@ -1049,8 +1023,8 @@ libgnomecanvas is missing branch definition for gnome-2-20
<section id="command-reference-rdepends">
<title>rdepends</title>
- <para>The <command>rdepends</command> command is used to show the
- reverse-dependencies of a module.</para>
+ <para>The <command>rdepends</command> command displays the
+ reverse dependencies of a module.</para>
<cmdsynopsis>
<command>jhbuild rdepends</command>
@@ -1068,8 +1042,8 @@ libgnomecanvas is missing branch definition for gnome-2-20
<varlistentry>
<term><option>--direct</option></term>
<listitem>
- <simpara>Limit display to modules directly depending on given
- module.</simpara>
+ <simpara>Limit display to modules directly depending on
+ specified module.</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -1078,9 +1052,9 @@ libgnomecanvas is missing branch definition for gnome-2-20
<section id="command-reference-run">
<title>run</title>
- <para>The <command>run</command> command is used to run an
- arbitrary command using the same environment that JHBuild uses
- when building modules.</para>
+ <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>
@@ -1108,8 +1082,7 @@ libgnomecanvas is missing branch definition for gnome-2-20
<title>sanitycheck</title>
<para>The <command>sanitycheck</command> command performs a
- number of checks to see whether the build environment is
- okay.</para>
+ number of checks to verify the build environment is okay.</para>
<cmdsynopsis>
<command>jhbuild sanitycheck</command>
@@ -1119,21 +1092,20 @@ libgnomecanvas is missing branch definition for gnome-2-20
<itemizedlist>
<listitem>
- <simpara>That the checkout and install prefixes are
- writable.</simpara>
+ <simpara>The checkout and install prefixes are writable.
+ </simpara>
</listitem>
<listitem>
- <simpara>That some of the required build tools are
- installed.</simpara>
+ <simpara>The required build tools are installed.</simpara>
</listitem>
<listitem>
- <simpara>That some commonly used macros are available in the
+ <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>That the XML catalog contains the DocBook DTD and
+ <simpara>The XML catalog contains the DocBook DTD and
stylesheets.</simpara>
</listitem>
</itemizedlist>
@@ -1151,8 +1123,7 @@ libgnomecanvas is missing branch definition for gnome-2-20
<command>jhbuild shell</command>
</cmdsynopsis>
- <para>This command is roughly equivalent to the
- following:</para>
+ <para>This command is equivalent to the following:</para>
<screen><prompt>$</prompt> <userinput>jhbuild run $SHELL</userinput></screen>
</section>
@@ -1185,15 +1156,16 @@ libgnomecanvas is missing branch definition for gnome-2-20
<option>--no-network</option>, <option>--skip</option>,
<option>--start-at</option>, <option>-D</option>,
<option>-C</option>, <option>-N</option> and <option>-f</option>
- options are processed the same as for <command>build</command>.</para>
+ 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 build
- logs.</simpara>
+ <simpara>The directory to write the HTML files.</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -1203,8 +1175,8 @@ libgnomecanvas is missing branch definition for gnome-2-20
<section id="command-reference-uninstall">
<title>uninstall</title>
- <para>The <command>uninstall</command> command is used to uninstall
- one or more modules.</para>
+ <para>The <command>uninstall</command> command uninstalls one or
+ more modules.</para>
<cmdsynopsis>
<command>jhbuild uninstall</command>
@@ -1232,8 +1204,9 @@ libgnomecanvas is missing branch definition for gnome-2-20
<para>The <option>--skip</option>, <option>--start-at</option>,
<option>--tags</option>, <option>--ignore-suggests</option> and
- <option>-D</option> options are processed the same as for
- <command>build</command>.</para>
+ <option>-D</option> options are processed as per the
+ <link linkend="command-reference-build"><command>build</command></link>
+ command.</para>
</section>
@@ -1241,9 +1214,8 @@ libgnomecanvas is missing branch definition for gnome-2-20
<title>updateone</title>
<para>The <command>updateone</command> command is similar to
- <command>update</command>, but it does not use dependency
- information to expand the module list. It is useful for quickly
- updating one or more modules.</para>
+ <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>
@@ -1251,11 +1223,12 @@ libgnomecanvas is missing branch definition for gnome-2-20
<arg choice="plain" rep="repeat">module</arg>
</cmdsynopsis>
- <para>The <option>-D</option> option is processed the same as
- for <command>update</command>.</para>
+ <para>The <option>-D</option> option is processed as per the
+ <link linkend="command-reference-build"><command>build</command></link>
+ command.</para>
- <para>Unlike the <command>update</command> command, at least one
- module must be listed on the command line.</para>
+ <para>At least one module must be listed on the command line.
+ </para>
</section>
</section>
@@ -1335,7 +1308,7 @@ libgnomecanvas is missing branch definition for gnome-2-20
<varlistentry>
<term id="cfg-buildroot"><varname>buildroot</varname></term>
<listitem>
- <simpara>A string giving the parent directory to place
+ <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>
@@ -1345,8 +1318,8 @@ libgnomecanvas is missing branch definition for gnome-2-20
<term id="cfg-buildscript"><varname>buildscript</varname></term>
<listitem>
<simpara>A string specifying which buildscript to use.
- This should probably be left as the default,
- <literal>terminal</literal>. In particular, do not
+ The recommended setting is the default,
+ <literal>terminal</literal>. In particular, do not
set to <literal>gtk</literal>.</simpara>
</listitem>
</varlistentry>
@@ -1365,16 +1338,16 @@ libgnomecanvas is missing branch definition for gnome-2-20
<varlistentry>
<term id="cfg-checkoutroot"><varname>checkoutroot</varname></term>
<listitem>
- <simpara>A string giving the directory to unpack source
+ <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>~/cvs/gnome2</filename>.</simpara>
+ <filename>~/checkout/gnome2</filename>.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term id="cfg-checkout-mode"><varname>checkout_mode</varname></term>
<listitem>
- <simpara>A string specifying how the checkout is done for
+ <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
@@ -1391,8 +1364,9 @@ libgnomecanvas is missing branch definition for gnome-2-20
<term id="cfg-copy-dir"><varname>copy_dir</varname></term>
<listitem>
<simpara>A string specifying the directory to copy to, if
- the copy checkout mode is in use. Defaults to the
- checkout directory.</simpara>
+ the copy <link linkend="cfg-checkout-mode">
+ <varname>checkout_mode</varname></link> is in use. Defaults to
+ the checkout directory.</simpara>
</listitem>
</varlistentry>
<varlistentry>
@@ -1405,11 +1379,12 @@ libgnomecanvas is missing branch definition for gnome-2-20
<varlistentry>
<term id="cfg-installprog"><varname>installprog</varname></term>
<listitem>
- <simpara>A string specifying which program to use as
- replacement for <literal>/usr/bin/install</literal>; if available
- it defaults to the <literal>install-check</literal> wrapper provided
- by JHBuild, which handles installation of headers differently,
- in order to reduce the time taken for rebuilds.
+ <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>
@@ -1428,7 +1403,7 @@ libgnomecanvas is missing branch definition for gnome-2-20
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>
+ <constant>True</constant>.</simpara>
</listitem>
</varlistentry>
<varlistentry>
@@ -1489,13 +1464,12 @@ libgnomecanvas is missing branch definition for gnome-2-20
<term id="cfg-module-autogenargs"><varname>module_autogenargs</varname></term>
<listitem>
<simpara>A dictionary mapping module names to strings
- giving arguments to be passed to
+ 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
- instead.</simpara>
+ global <varname>autogenargs</varname> will be used.</simpara>
</listitem>
</varlistentry>
<varlistentry>
@@ -1510,12 +1484,12 @@ libgnomecanvas is missing branch definition for gnome-2-20
<term id="cfg-module-makeargs"><varname>module_makeargs</varname></term>
<listitem>
<simpara>A dictionary mapping module names to strings
- giving arguments to be passed 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
- instead.</simpara>
+ 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>
@@ -1530,28 +1504,32 @@ libgnomecanvas is missing branch definition for gnome-2-20
<varlistentry>
<term id="cfg-modules"><varname>modules</varname></term>
<listitem>
- <simpara>A list of module names to build. This list will
- be expanded using the dependency information found in the
- module set. Defaults to <literal>[ 'meta-gnome-desktop'
- ]</literal>.</simpara>
+ <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 giving the name 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 refer to an externally managed
- module set. It is usually updated as GNOME development
- progresses to match the current GNOME development release.
- </simpara>
+ <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 giving the directory containing the
+ <simpara>A string specifying the directory containing the
modulesets to use. Defaults to the
<filename>modulesets/</filename> directory in JHBuild sources.
</simpara>
@@ -1560,22 +1538,21 @@ libgnomecanvas is missing branch definition for gnome-2-20
<varlistentry>
<term id="cfg-nobuild"><varname>nobuild</varname></term>
<listitem>
- <simpara>A boolean value which, if set to
- <constant>True</constant> causes JHBuild to not actually
- modules, but just download and unpack the sources. The
- default vale is <constant>False</constant>.</simpara>
+ <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 or not. This affects checking out or updating CVS
+ 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 to
- JHBuild. Defaults to
- <constant>False</constant>.</simpara>
+ passing the <option>--no-network</option> option. Defaults to
+ <constant>False</constant>.</simpara>
</listitem>
</varlistentry>
<varlistentry>
@@ -1591,12 +1568,11 @@ libgnomecanvas is missing branch definition for gnome-2-20
<varlistentry>
<term id="cfg-nopoison"><varname>nopoison</varname></term>
<listitem>
- <simpara>A boolean value which, if set to
- <constant>True</constant> causes JHBuild to try 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>
+ <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>
@@ -1612,76 +1588,74 @@ libgnomecanvas is missing branch definition for gnome-2-20
<varlistentry>
<term id="cfg-noxvfb"><varname>noxvfb</varname></term>
<listitem>
- <simpara>A boolean value which, if set to
- <constant>True</constant> causes JHBuild to 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>
+ <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-prefix"><varname>prefix</varname></term>
<listitem>
- <simpara>A string giving the prefix to install modules to.
- Defaults to <literal>'/opt/gnome2'</literal>.</simpara>
+ <simpara>A string specifying the prefix to install modules to.
+ This directory must be writable. Defaults to
+ <literal>'/opt/gnome2'</literal>.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term id="cfg-pretty-print"><varname>pretty_print</varname></term>
<listitem>
- <simpara>A boolean value that can be used to disable
- pretty formatting of subprocess output. Currently there is
- only support for pretty printing CVS output. You probably
- only want to disable this if the pretty printing causes
- problems. Defaults to <literal>True</literal>.</simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term id="cfg-progress-bar"><varname>progress_bar</varname></term>
- <listitem>
- <simpara>A boolean value that can be used to display a progress bar
- when running in quiet mode (see below). Defaults to
- <literal>True</literal>.</simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term id="cfg-quiet-mode"><varname>quiet_mode</varname></term>
- <listitem>
- <simpara>A boolean value that can be used to disable
- output of running commands. Defaults to
- <literal>False</literal>.</simpara>
- </listitem>
- </varlistentry>
+ <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-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 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 the alternative repository location strings. For example:
- </simpara>
+ <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 when expanding the list
- of modules to build. This is similar to the
- <option>--skip</option> option (in fact, the
- <option>--skip</option> option extends this list). This
- list is empty by default.</simpara>
+ <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, JHBuild will attempt to check out modules
- as they existed at the given date. The date should be
- given in the form
+ <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>
@@ -1698,18 +1672,17 @@ libgnomecanvas is missing branch definition for gnome-2-20
<varlistentry id="cfg-tarballdir">
<term><varname>tarballdir</varname></term>
<listitem>
- <simpara>A string if set, tarballs will be downloaded to this
- directory instead of <varname>checkoutroot</varname>.
+ <simpara>A string if set, tarballs will be downloaded the
+ specified directory instead of <varname>checkoutroot</varname>.
This is useful if you have multiple JHBuild environments
- or regularly clear out your
- <varname>checkoutroot</varname> and want to reduce
- bandwidth usage.</simpara>
+ 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 giving the directory to store
+ <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
@@ -1720,13 +1693,12 @@ libgnomecanvas is missing branch definition for gnome-2-20
<varlistentry id="cfg-trycheckout">
<term><varname>trycheckout</varname></term>
<listitem>
- <simpara>A boolean value which if set to
- <constant>True</constant>, causes JHBuild to automatically
+ <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 (then running <command>autogen.sh</command>.
- This option is equivalent to passing
- <option>--try-checkout</option>.</simpara>
+ control. This setting is equivalent to passing the
+ <option>--try-checkout</option> option.</simpara>
</listitem>
</varlistentry>
<varlistentry id="cfg-use-lib64">
@@ -1734,8 +1706,7 @@ libgnomecanvas is missing branch definition for gnome-2-20
<listitem>
<simpara>A boolean value that specifies whether to install
libraries to <filename>lib64</filename> directories. If
- this is set,
- <literal>--libdir=\${exec_prefix}/lib64</literal> will be
+ 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
@@ -1748,8 +1719,8 @@ libgnomecanvas is missing branch definition for gnome-2-20
<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 Subversion repository.
- Defaults to <constant>False</constant>.
+ of downloading them on-the-fly from GNOME version control
+ system. Defaults to <constant>False</constant>.
</simpara>
</listitem>
</varlistentry>
@@ -1757,8 +1728,7 @@ libgnomecanvas is missing branch definition for gnome-2-20
<term><varname>xvfbargs</varname></term>
<listitem>
<simpara>A string listing arguments to pass to
- <command>Xvfb</command> if running graphical tests using
- it.</simpara>
+ <command>Xvfb</command> if running graphical tests.</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -1767,34 +1737,33 @@ libgnomecanvas is missing branch definition for gnome-2-20
<section id="config-reference-other">
<title>Other Configuration File Structures</title>
- <para>In addition to the above variables, there are some other
- things that can be set in the configuration file:</para>
+ <para>In addition to the above variables, there are other
+ settings that can be set in the configuration file:</para>
<variablelist>
- <varlistentry>
+ <varlistentry id="cfg-os-environ">
<term><varname>os.environ</varname></term>
<listitem>
- <para>This is dictionary represents the environment of the
- process (which also gets passed on to processes that
- JHBuild spawns).</para>
- <para>Some environment variables you may want to set
- include <envar>CFLAGS</envar>, <envar>INSTALL</envar> (to
- use the more efficient <command>install-check</command>
- program included with JHBuild) and
- <envar>LDFLAGS</envar>.</para>
+ <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'</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><function>addpath</function>(<parameter>envvar</parameter>,
<parameter>pathname</parameter>)</term>
<listitem>
- <para>This will add a directory to a
- <envar>PATH</envar>-style environment variable. It 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>This function has special handling for the
+ <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>
@@ -1806,7 +1775,7 @@ libgnomecanvas is missing branch definition for gnome-2-20
<listitem>
<para>After processing the configuration file, JHBuild
will alter some paths based on variables such as
- <varname>prefix</varname> (eg. adding
+ <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
@@ -1828,11 +1797,10 @@ libgnomecanvas is missing branch definition for gnome-2-20
directory. The RELAX-NG schema can be used to edit module
set files using <literal>nxml-mode</literal> in Emacs.</para>
- <para>The toplevel element in a module set file is <sgmltag
- class="element">moduleset</sgmltag> element. Currently no XML
- namespace is used, but in the future this might change. The
- elements below the toplevel come in three types: module sources,
- include statements and module definitions.</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>
@@ -2050,7 +2018,7 @@ libgnomecanvas is missing branch definition for gnome-2-20
many levels of directories to prune when applying the
patch.</para>
- <para>For module sets shipped with JHuild, the patch files are
+ <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
@@ -2656,42 +2624,37 @@ libgnomecanvas is missing branch definition for gnome-2-20
firewall?</simpara>
</question>
<answer>
- <para>This can be fixed by creating or editing a
- <filename>~/.wgetrc</filename> file. If you need to go
- through an HTTP proxy to access FTP sites, add a line like
+ <para>Create <filename>~/.wgetrc</filename> file. If an HTTP
+ proxy is used to access FTP sites, add a line like
the following to the file:</para>
<programlisting>ftp_proxy = http://<replaceable>hostname</replaceable>:<replaceable>port</replaceable>/</programlisting>
- <para>If you just need to use passive FTP connections
+ <para>If passive FTP connections are required
(sometimes needed with NAT firewalls), add the following
line:</para>
<programlisting>passive_ftp = on</programlisting>
- <para>This will fix all uses of the
- <command>wget</command> command.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
- <simpara>Building stuff is slow. Is there any way I can
+ <simpara>Building is slow. Is there any way I can
speed it up?</simpara>
</question>
<answer>
- <para>Other than buying a faster CPU, hard disk or getting
- more memory, you might want to install <ulink
- url="http://ccache.samba.org/";>CCache</ulink>, which can
- cache compilation results for you. It is available with
- most distributions.</para>
- <para>After installing CCache, set the cache size with the
- following command:</para>
+ <para><ulink url="http://ccache.samba.org/";>CCache</ulink>
+ can speed up compilations, as it caches compilation results.
+ <command>CCache</command> is available with most distributions.
+ </para>
+ <para>Set the cache size with the following command:</para>
<programlisting>ccache -M 2G</programlisting>
- <para>(replace <literal>2G</literal> with the size you
- want for your cache). Then create symlinks to CCache for
- your compiler in <filename>~/bin</filename>:</para>
+ <para>(where <literal>2G</literal> is the size the cache).
+ Create symlinks to <command>CCache</command> for
+ the compiler in <filename>~/bin</filename>:</para>
<programlisting>cd ~/bin
for cmd in cc gcc c++ g++; do
ln -s /usr/bin/ccache $cmd
done</programlisting>
- <para>You can check the status of your cache (such as
- cache hit rates) with the following command:</para>
+ <para>It is possible to check the status of the cache
+ including cache hit rates with the following command:</para>
<programlisting>ccache -s</programlisting>
</answer>
</qandaentry>
@@ -2701,7 +2664,7 @@ done</programlisting>
the build than looking at terminal window?</simpara>
</question>
<answer>
- <para>If you have Zenity >= 2.9 installed on your system,
+ <para>If Zenity >= 2.9 is installed on your system,
JHBuild will display an icon in the system tray. The icon
will display the current build stage, and the tooltip will
show the last message from JHBuild.</para>
@@ -2717,8 +2680,7 @@ done</programlisting>
with JHBuild?</simpara>
</question>
<answer>
- <para>Some of the packages you will need on your system
- include:</para>
+ <para>Some of the packages required include:</para>
<itemizedlist>
<listitem>
<simpara>DocBook XML DTD and XSLT stylesheets. These
@@ -2747,10 +2709,12 @@ done</programlisting>
loading).</simpara>
</listitem>
</itemizedlist>
- <para>If you are installing distro packages, you may need
- to install corresponding "dev" or "devel" packages. Note
- that this list is just a starting point - not a
- comprehensive list.</para>
+ <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>
</answer>
</qandaentry>
<qandaentry>
@@ -2759,27 +2723,45 @@ done</programlisting>
it?</simpara>
</question>
<answer>
- <para>(a) You will want to create a
- <filename>~/.xsession</filename> file, which is run by the
- display manager when you log in. This file should look
- something like this:</para>
- <programlisting>#!/bin/sh
+ <para>Two options:</para>
+ <orderedlist>
+ <listitem>
+ <para>Without JHBuild <application>HAL</application>
+ and <application>D-Bus</application>. This method requires
+ support from the display manager (e.g.
+ <application>GDM</application>,
+ <application>KDM</application>,
+ <application>XDM</application>).
+ Create a <filename>~/.xsession</filename> file, with the
+ following contents:</para>
+ <programlisting>#!/bin/sh
exec jhbuild run gnome-session</programlisting>
- <para>Finally, you should make sure that the
- <filename>~/.xsession</filename> file is executable.</para>
- <para>(b) Use a more sophisticated session script that is run
- when you log in using a graphical login manager (gdm
- /kdm/xdm). The problem with D-Bus and HAL is that
- these daemons come with your distribution and are
- most likely already running, but may be unusable by the
- Gnome development version (i.e. they are too old or
- incompatible). The session script just starts hal and d-bus
- from the jhbuild installation in addition to the system-wide
- versions. Put the following script as e.g.
- <filename>/usr/bin/gnomesvn-session</filename> and
- make sure you adjust <userinput>GNOME</userinput>
- to your local settings:
- </para>
+ <para>Set the <filename>~/.xsession</filename> file to be
+ executable. At log in, set the session to
+ <guilabel>custom</guilabel>.
+ If the display manager does not have a
+ <guilabel>custom</guilabel> option, refer to answer
+ <xref linkend="faq-built-hal"/> below.
+ </para>
+ </listitem>
+ <listitem id="faq-built-hal">
+ <para>With JHBuild <application>HAL</application> and
+ <application>D-Bus</application>.
+ <application>HAL</application> and
+ <application>D-Bus</application> are
+ daemons provided with your distribution. They are
+ most likely already running, but may be unusable by the
+ GNOME development version as they are too old or
+ incompatible.</para>
+ <para>Create a session script that is run
+ when you log in using a display manager
+ (e.g. <application>GDM</application>,
+ <application>KDM</application>,
+ <application>XDM</application>).
+ The session script starts <command>hal</command> and
+ <command>d-bus</command>
+ from the JHBuild installation in addition to the
+ system-wide versions.</para>
<programlisting>
GNOME=/opt/gnome2
@@ -2793,20 +2775,21 @@ sudo su -c "$GNOME/bin/dbus-daemon --system; \
$GNOME/sbin/hald"
jhbuild run $DBUS_LAUNCH gnome-session</programlisting>
- <para>Uncomment the XDG_ lines if you want the system-wide
- program menus from your distribution in addition to the
- entries from the jhbuild GNOME. Make sure the file is
- executable:
+ <para> Adjust the variable <varname>GNOME</varname>
+ to your local settings. Uncomment the
+ <varname>XDG_</varname> lines for system-wide
+ program menus in addition to the menus from the JHBuild
+ GNOME. Save the script as
+ <filename>/usr/bin/gnome-jhbuild-session</filename> or
+ any other name of your choosing. Set the
+ file to be executable.</para>
+ <para>As the script starts system daemons, root privileges
+ are required obtained via <command>sudo</command>. The
+ script requires <command>sudo</command> to be configured
+ so it doesn't prompt for a password. Run
+ <command>visudo</command> as root and enter the
+ following, changing username and paths as appropriate:
</para>
- <programlisting>chmod a+x /usr/bin/gnomesvn-session</programlisting>
- <para>Because you need to start
- system daemons, you
- will need root privileges which are obtained by sudo. Note
- that you need to configure sudo so that it won't ask for a
- password! Run <userinput>visudo</userinput> as root
- and enter (don't forget to
- change your username and the paths):
- </para>
<programlisting>
# Cmnd alias specification
Cmnd_Alias GNOME = /opt/gnome2/bin/dbus-daemon, \
@@ -2814,23 +2797,24 @@ Cmnd_Alias GNOME = /opt/gnome2/bin/dbus-daemon, \
# User privilege specification
gnometester ALL = NOPASSWD: GNOME</programlisting>
- <para>In order to get a new session entry in the login manager, create
- <filename>/usr/share/xsessions/gnomesvn.desktop</filename> and put this or
- something similar:
- </para>
+ <para>To add a new session entry in the display
+ manager, create
+ <filename>/usr/share/xsessions/gnomesvn.desktop</filename>
+ and enter:</para>
<programlisting>
[Desktop Entry]
Encoding=UTF-8
-Name=Gnome svn (jhbuild)
-Comment=This session logs you into Gnome testing session
-Exec=/usr/bin/gnomesvn-session
+Name=GNOME (JHBuild)
+Comment=This session logs you into GNOME testing session
+Exec=/usr/bin/gnome-jhbuild-session
Icon=
Type=Application</programlisting>
- <para>Now you can restart gdm and log into your jhbuild GNOME.
- Make sure you select the jhbuild session before entering
- the login credentials. Advice: Use a separate user account
- for testing!
- </para>
+ <para>Restart <command>gdm</command> and log into your
+ JHBuild GNOME. Select the JHBuild session before
+ entering the login credentials. Using separate user
+ account is recommended for testing.</para>
+ </listitem>
+ </orderedlist>
</answer>
</qandaentry>
<qandaentry>
@@ -2848,7 +2832,7 @@ Type=Application</programlisting>
<question>
<simpara>How do I get
<command>gnome-volume-manager</command> to work when
- running in a prefix?</simpara>
+ running JHBuild GNOME?</simpara>
</question>
<answer>
<para>The <command>gnome-volume-manager</command> program
@@ -2858,17 +2842,17 @@ Type=Application</programlisting>
<acronym>HAL</acronym>, the main problem is getting
<command>gnome-volume-manager</command> to talk to the
system message bus.</para>
- <para>Since communication is done over a UNIX domain
- socket, the easiest way to do this is to create a symlink
+ <para>As communication is over a UNIX domain
+ socket, the easiest way is to create a symlink
from <filename>/var/run/dbus</filename> to
<filename>$prefix/var/run/dbus</filename>:</para>
<programlisting>mkdir -p $prefix/var/run
cd $prefix/var/run
ln -s /var/run/dbus dbus</programlisting>
- <para>You may also have trouble building HAL with JHBuild,
- since it tries to install some things outside of its build
- root. Running <userinput>make -k install</userinput> in
- the hal directory might help here.</para>
+ <para>You may also have trouble building HAL with JHBuild,
+ since it tries to install some things outside of its build
+ root. Running <userinput>make -k install</userinput> in
+ the hal directory might help here.</para>
</answer>
</qandaentry>
</qandadiv>
diff --git a/sample.jhbuildrc b/sample.jhbuildrc
index 0b80cc4..71bb780 100644
--- a/sample.jhbuildrc
+++ b/sample.jhbuildrc
@@ -8,7 +8,7 @@
# what module set should be used. The default at the moment is 'gnome-2.26',
# but it can be any of the files in the modulesets directory, or even
# the URL of a module set file on a web server.
-# moduleset = 'gnome-2.26'
+# moduleset = 'gnome-2.28'
# A list of the modules to build. Defaults to the Gnome Desktop and
# developer platform.
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
