Manual: Remove tabs, indent consistently

[?]

Feb 28, 2012, 2:38 PM

GYPHTT4MZS75JYMQES2DZPV2D47EJW5HTQWYWDYXE7YJ6FFHPAYAC

Dependencies

[2] HN7JDKV3 doc: Mention SQLite.
[3] CPQQFQMZ doc: Reintegrate the intro by Visser & Dolstra from `manual.html'.
[4] W5GW4E22 Don't install hydra-create
[5] NIUHJZPR removed some whitespace
[6] EKNK5AHQ doc: Augment the "Installation" section with material by Visser & Dolstra.
[7] A6EKITA6 Update the docs to reflect the renaming
[8] 3463ZP55 doc: Mention the 3 processes that make up Hydra.
[9] KBW3FDZ2 Merge remote branch 'remotes/origin/master'

Change contents

edit in doc/manual/installation.xml at line 4

[5.375]

[5.375]

<title>Installation</title>
replacement in doc/manual/installation.xml at line 7

[5.376]→[5.376:408](∅→∅)

<title>Installation</title>

[5.376]

[5.0]

<para>
This chapter explains how to install Hydra on your own build farm server.
</para>
edit in doc/manual/installation.xml at line 11

[5.1]

[5.1]

<section>
<title>Prerequisites</title>
replacement in doc/manual/installation.xml at line 14

[5.12]→[5.12:104](∅→∅)

This chapter explains how to install Hydra on your own build farm server.
</para>

[5.12]

[5.408]

To install and use Hydra you need to have installed the following dependencies:
replacement in doc/manual/installation.xml at line 16

[5.409]→[5.409:564](∅→∅)

<section>
<title>Prerequisites</title>
<para>
To install and use Hydra you need to have installed the following dependencies:

[5.409]

[5.105]

<itemizedlist>
<listitem>Nix</listitem>
<listitem>either PostgreSQL or SQLite</listitem>
<listitem>many Perl packages, notably Catalyst, EmailSender,
and NixPerl (see the <link
xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/development/tools/misc/hydra/default.nix">Hydra
expression in Nixpkgs</link> for the complete
list).</listitem>
</itemizedlist>
replacement in doc/manual/installation.xml at line 26

[5.106]→[5.564:588](∅→∅),[5.564]→[5.564:588](∅→∅),[5.588]→[5.107:500](∅→∅),[5.500]→[5.697:722](∅→∅),[5.697]→[5.697:722](∅→∅)

<itemizedlist>
<listitem>Nix</listitem>
<listitem>either PostgreSQL or SQLite</listitem>
<listitem>many Perl packages, notably Catalyst,
EmailSender, and NixPerl (see the <link
xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/development/tools/misc/hydra/default.nix">Hydra
expression in Nixpkgs</link> for the complete
list).</listitem>
</itemizedlist>

[5.106]

[5.501]

At the moment, Hydra runs only on GNU/Linux
(<emphasis>i686-linux</emphasis> and
<emphasis>x86_64_linux</emphasis>).
</para>
replacement in doc/manual/installation.xml at line 31

[5.502]→[5.502:646](∅→∅),[5.646]→[5.862:878](∅→∅),[5.862]→[5.862:878](∅→∅)

At the moment, Hydra runs only on GNU/Linux
(<emphasis>i686-linux</emphasis> and
<emphasis>x86_64_linux</emphasis>).
</para>

[5.502]

[5.647]

<para>
For small projects, Hydra can be run on any reasonably modern
machine. For individual projects you can even run Hydra on a
laptop. However, the charm of a buildfarm server is usually that
it operates without disturbing the developer's working
environment and can serve releases over the internet. In
conjunction you should typically have your source code
administered in a version management system, such as
subversion. Therefore, you will probably want to install a
server that is connected to the internet. To scale up to large
and/or many projects, you will need at least a considerable
amount of diskspace to store builds. Since Hydra can schedule
multiple simultaneous build jobs, it can be useful to have a
multi-core machine, and/or attach multiple build machines in a
network to the central Hydra server.
</para>
replacement in doc/manual/installation.xml at line 48

[5.648]→[5.648:1940](∅→∅)

<para>
For small projects, Hydra can be run on any reasonably
modern machine. For individual projects you can even run
Hydra on a laptop. However, the charm of a buildfarm server
is usually that it operates without disturbing the
developer's working environment and can serve releases over
the internet. In conjunction you should typically have your
source code administered in a version management system,
such as subversion. Therefore, you will probably want to
install a server that is connected to the internet. To scale
up to large and/or many projects, you will need at least a
considerable amount of diskspace to store builds. Since
Hydra can schedule multiple simultaneous build jobs, it can
be useful to have a multi-core machine, and/or attach
multiple build machines in a network to the central Hydra
server.
</para>

<para>
Of course we think it is a good idea to use the <a
href="http://nixos.org/nixos">NixOS</a> GNU/Linux
distribution for your buildfarm server. But this is not a
requirement. The Nix software deployment system can be
installed on any GNU/Linux distribution in parallel to the
regular package management system. Thus, you can use Hydra
on a Debian, Fedora, SuSE, or Ubuntu system.
</para>

[5.648]

[5.878]

<para>
Of course we think it is a good idea to use the <a
href="http://nixos.org/nixos">NixOS</a> GNU/Linux distribution
for your buildfarm server. But this is not a requirement. The
Nix software deployment system can be installed on any GNU/Linux
distribution in parallel to the regular package management
system. Thus, you can use Hydra on a Debian, Fedora, SuSE, or
Ubuntu system.
</para>
replacement in doc/manual/installation.xml at line 58

[5.887]→[5.1941:1956](∅→∅)

</section>

[5.887]

[5.1956]

</section>
replacement in doc/manual/installation.xml at line 60

[5.1957]→[5.1957:2004](∅→∅)

<section>
<title>Getting Nix</title>

[5.1957]

[5.2004]

<section>
<title>Getting Nix</title>
replacement in doc/manual/installation.xml at line 63

[5.2005]→[5.2005:2347](∅→∅),[5.2347]→[5.887:902](∅→∅),[5.887]→[5.887:902](∅→∅)

<para>
If your server runs NixOS you are all set to continue with
installation of Hydra. Otherwise you first need to install
Nix. The latest stable version can be found one <link
xlink:href="http://nixos.org/nix/download.html">the Nix web
site</link>, along with a manual, which includes installation
instructions.
</para>
</section>

[5.2005]

[5.902]

<para>
If your server runs NixOS you are all set to continue with
installation of Hydra. Otherwise you first need to install Nix.
The latest stable version can be found one <link
xlink:href="http://nixos.org/nix/download.html">the Nix web
site</link>, along with a manual, which includes installation
instructions.
</para>
</section>
replacement in doc/manual/installation.xml at line 73

[5.903]→[5.903:953](∅→∅)

<section>
<title>Installation</title>

[5.903]

[5.2348]

<section>
<title>Installation</title>
replacement in doc/manual/installation.xml at line 76

[5.2349]→[5.2349:2398](∅→∅)

<para>
Hydra can be installed using Nixpkgs:

[5.2349]

[5.2398]

<para>
Hydra can be installed using Nixpkgs:
replacement in doc/manual/installation.xml at line 79

[5.2399]→[5.2399:2463](∅→∅)

<screen>
nix-env -Ai hydra -f /path/to/nixpkgs</screen>

[5.2399]

[5.2463]

<screen>
nix-env -Ai hydra -f /path/to/nixpkgs</screen>
replacement in doc/manual/installation.xml at line 82

[5.2464]→[5.2464:2590](∅→∅)

This makes the tools available in your Nix user environment,
<literal>$HOME/.nix-profile</literal> by default.
</para>

[5.2464]

[5.2590]

This makes the tools available in your Nix user environment,
<literal>$HOME/.nix-profile</literal> by default.
</para>
replacement in doc/manual/installation.xml at line 86

[5.2591]→[5.953:968](∅→∅),[5.953]→[5.953:968](∅→∅),[5.968]→[5.2592:2930](∅→∅),[5.2930]→[5.1182:1266](∅→∅),[5.1182]→[5.1182:1266](∅→∅)

<para>
Alternatively, the latest development snapshot can be
installed by visiting the URL
<link xlink:href="http://hydra.nixos.org/view/hydra/unstable"><literal>http://hydra.nixos.org/view/hydra/unstable</literal></link>
and use the one-click install available at one of the build pages. You can also
install Hydra through the channel by performing the following commands:

[5.2591]

[5.1266]

<para>
Alternatively, the latest development snapshot can be installed
by visiting the URL <link
xlink:href="http://hydra.nixos.org/view/hydra/unstable"><literal>http://hydra.nixos.org/view/hydra/unstable</literal></link>
and use the one-click install available at one of the build
pages. You can also install Hydra through the channel by
performing the following commands:
replacement in doc/manual/installation.xml at line 98

[5.1398]→[5.2931:2947](∅→∅)

</para>

[5.1398]

[5.2947]

</para>
replacement in doc/manual/installation.xml at line 100

[5.2948]→[5.2948:3035](∅→∅)

<para>
Command completion should reveal a number of command-line tools from Hydra:

[5.2948]

[5.1398]

<para>
Command completion should reveal a number of command-line tools from Hydra:
replacement in doc/manual/installation.xml at line 103

[5.1399]→[5.3036:3048](∅→∅)

<screen>

[5.1399]

[4.0]

<screen>
replacement in doc/manual/installation.xml at line 106

[4.118]→[5.3255:3264](∅→∅),[5.136]→[5.3255:3264](∅→∅),[5.3255]→[5.3255:3264](∅→∅),[5.3264]→[5.1415:1430](∅→∅),[5.1415]→[5.1415:1430](∅→∅)

</para>
</section>

[4.118]

[5.1430]

</para>
</section>
replacement in doc/manual/installation.xml at line 109

[5.1431]→[5.1431:1445](∅→∅),[5.1445]→[2.0:45](∅→∅),[2.45]→[5.1486:1501](∅→∅),[5.1486]→[5.1486:1501](∅→∅),[5.1501]→[2.46:232](∅→∅)

<section>
<title>Creating the database</title>
<para>
Hydra stores its results in a database, which can be a
PostgreSQL or SQLite database. The latter is easier to
setup, but the former scales better.
</para>

[5.1431]

[2.232]

<section>
<title>Creating the database</title>
<para>
Hydra stores its results in a database, which can be a
PostgreSQL or SQLite database. The latter is easier to setup,
but the former scales better.
</para>

<para>
To setup a PostgreSQL database with <emphasis>hydra</emphasis>
as database name and user name, issue the following commands:
replacement in doc/manual/installation.xml at line 121

[2.233]→[2.233:389](∅→∅),[2.389]→[5.1677:1698](∅→∅),[5.1677]→[5.1677:1698](∅→∅)

<para>To setup a PostgreSQL
database with <emphasis>hydra</emphasis> as database name
and user name, issue the following commands:
<screen>

[2.233]

[5.1698]

<screen>
replacement in doc/manual/installation.xml at line 126

[5.1920]→[2.390:498](∅→∅)

Note that <emphasis>$prefix</emphasis> is the location of
Hydra in the nix store.
</para>

[5.1920]

[2.498]

Note that <emphasis>$prefix</emphasis> is the location of Hydra
in the nix store.
</para>
replacement in doc/manual/installation.xml at line 131

[2.499]→[2.499:591](∅→∅)

<para>
For SQLite, the following command is all it takes to
create the database:

[2.499]

[2.591]

<para>
For SQLite, the following command is all it takes to create the
database:
replacement in doc/manual/installation.xml at line 135

[2.592]→[2.592:705](∅→∅),[2.705]→[5.2014:2030](∅→∅),[5.2014]→[5.2014:2030](∅→∅)

<screen>
cat $prefix/share/hydra/sql/hydra-sqlite.sql | sqlite3 /path/to/hydra.sqlite
</screen>
</para>

[2.592]

[2.706]

<screen>
cat $prefix/share/hydra/sql/hydra-sqlite.sql | sqlite3 /path/to/hydra.sqlite</screen>
</para>
replacement in doc/manual/installation.xml at line 139

[2.707]→[5.2030:2183](∅→∅),[5.2030]→[5.2030:2183](∅→∅)

<para>
To add a user <emphasis>root</emphasis> with <emphasis>admin</emphasis> privileges, execute:
<screen>

[2.707]

[5.2183]

<para>
To add a user <emphasis>root</emphasis> with
<emphasis>admin</emphasis> privileges, execute:
<screen>
replacement in doc/manual/installation.xml at line 144

[5.2341]→[2.708:969](∅→∅)

echo "INSERT INTO UserRoles(userName, role) values('root', 'admin');" | psql hydra
</screen>
For SQLite the same commands can be used, with
<command>psql hydra</command> replaced by
<command>sqlite3 /path/to/hydra.sqlite</command>.
</para>

[5.2341]

[5.2433]

echo "INSERT INTO UserRoles(userName, role) values('root', 'admin');" | psql hydra</screen>

For SQLite the same commands can be used, with <command>psql
hydra</command> replaced by <command>sqlite3
/path/to/hydra.sqlite</command>.
</para>
replacement in doc/manual/installation.xml at line 151

[5.2434]→[2.970:1333](∅→∅)

<para>
Hydra uses an environment variable to know which database
should be used, and a variable which point to a location
that holds some state. To set these variables for a
PostgreSQL database, add the following to the
<filename>.profile</filename> of the user running the
Hydra services.

[5.2434]

[2.1333]

<para>
Hydra uses an environment variable to know which database should
be used, and a variable which point to a location that holds
some state. To set these variables for a PostgreSQL database,
add the following to the <filename>.profile</filename> of the
user running the Hydra services.
replacement in doc/manual/installation.xml at line 158

[2.1334]→[5.2716:2737](∅→∅),[5.2716]→[5.2716:2737](∅→∅)

<screen>

[2.1334]

[5.2737]

<screen>
replacement in doc/manual/installation.xml at line 162

[5.2836]→[2.1335:1668](∅→∅)

Make sure that the <emphasis>HYDRA_DATA</emphasis>
directory exists and is writable for the user which will
run the Hydra services. For a SQLite database, the
<varname>HYDRA_DBI</varname> should be set to something
like <literal>dbi:SQLite:/path/to/hydra.sqlite</literal>

[5.2836]

[2.1668]

Make sure that the <emphasis>HYDRA_DATA</emphasis> directory
exists and is writable for the user which will run the Hydra
services. For a SQLite database, the
<varname>HYDRA_DBI</varname> should be set to something like
<literal>dbi:SQLite:/path/to/hydra.sqlite</literal>
</para>
</section>
replacement in doc/manual/installation.xml at line 170

[2.1669]→[5.2980:3011](∅→∅),[5.2980]→[5.2980:3011](∅→∅)

</para>
</section>

[2.1669]

[5.3011]

<section>
<title>Getting Started</title>
replacement in doc/manual/installation.xml at line 173

[5.3012]→[5.3012:3026](∅→∅),[5.3026]→[5.0:40](∅→∅),[5.40]→[5.3065:3080](∅→∅),[5.3065]→[5.3065:3080](∅→∅),[5.3080]→[5.41:105](∅→∅),[5.105]→[5.3143:3164](∅→∅),[5.3143]→[5.3143:3164](∅→∅)

<section>
<title>Getting Started</title>

<para>
To start the Hydra web server, execute:
<screen>

[5.3012]

[5.137]

<para>
To start the Hydra web server, execute:
<screen>
replacement in doc/manual/installation.xml at line 178

[5.3190]→[5.106:268](∅→∅),[5.268]→[5.3328:3344](∅→∅),[5.3328]→[5.3328:3344](∅→∅),[5.3344]→[5.269:278](∅→∅),[5.278]→[5.160:220](∅→∅),[5.220]→[5.341:411](∅→∅),[5.341]→[5.341:411](∅→∅)

When the server is started, you can browse to
<ulink>http://localhost:3000/</ulink> to start configuring
your Hydra instance.
</para>

<para>
The <command>hydra-server</command> command launches the
web server. There are two other processes that come into
play:

[5.3190]

[5.3359]

When the server is started, you can browse to
<ulink>http://localhost:3000/</ulink> to start configuring
your Hydra instance.
</para>
replacement in doc/manual/installation.xml at line 183

[5.3360]→[5.412:729](∅→∅),[5.729]→[5.221:272](∅→∅),[5.272]→[5.783:1020](∅→∅),[5.783]→[5.783:1020](∅→∅),[5.1020]→[5.273:327](∅→∅),[5.327]→[5.1077:1113](∅→∅),[5.1077]→[5.1077:1113](∅→∅)

<itemizedlist>
<listitem>
The <emphasis>evaluator</emphasis> is responsible for
peridically evaluating job sets, checking out their
dependencies off their version control systems (VCS),
and queueing new builds if the result of the evaluation
changed. It is launched by the
<command>hydra-evaluator</command> command.
</listitem>
<listitem>
The <emphasis>queue runner</emphasis> launches builds
(using Nix) as they are queued by the evaluator,
scheduling them onto the configured Nix hosts. It is
launched using the
<command>hydra-queue-runner</command> command.
</listitem>
</itemizedlist>

[5.3360]

[5.3581]

<para>
The <command>hydra-server</command> command launches the web
server. There are two other processes that come into play:
replacement in doc/manual/installation.xml at line 187

[5.3582]→[5.1114:1303](∅→∅),[5.1303]→[5.3724:3739](∅→∅),[5.3724]→[5.3724:3739](∅→∅)

All three processes must be running for Hydra to be fully
functional, though it's possible to temporarily stop any one
of them for maintenance purposes, for instance.
</para>

</section>

[5.3582]

[5.3739]

<itemizedlist>
<listitem>
The <emphasis>evaluator</emphasis> is responsible for
peridically evaluating job sets, checking out their
dependencies off their version control systems (VCS), and
queueing new builds if the result of the evaluation changed.
It is launched by the <command>hydra-evaluator</command>
command.
</listitem>
<listitem>
The <emphasis>queue runner</emphasis> launches builds (using
Nix) as they are queued by the evaluator, scheduling them
onto the configured Nix hosts. It is launched using the
<command>hydra-queue-runner</command> command.
</listitem>
</itemizedlist>
edit in doc/manual/installation.xml at line 204

[5.3740]

[5.3740]

All three processes must be running for Hydra to be fully
functional, though it's possible to temporarily stop any one of
them for maintenance purposes, for instance.
</para>

</section>
edit in doc/manual/installation.xml at line 212

[5.3753]


replacement in doc/manual/introduction.xml at line 22

[3.779]→[3.779:992](∅→∅)

<listitem> <emphasis>Portability testing</emphasis>: The
software may need to be built and tested on many different
platforms. It is infeasible for each developer to do this
before every commit.
</listitem>

[3.779]

[3.992]

<listitem> <emphasis>Portability testing</emphasis>: The
software may need to be built and tested on many different
platforms. It is infeasible for each developer to do this
before every commit.
</listitem>
replacement in doc/manual/introduction.xml at line 28

[3.993]→[3.993:1186](∅→∅)

<listitem> Likewise, many projects have very large test sets
(e.g., regression tests in a compiler, or stress tests in a
DBMS) that can take hours or days to run to completion.
</listitem>

[3.993]

[3.1186]

<listitem> Likewise, many projects have very large test sets
(e.g., regression tests in a compiler, or stress tests in a
DBMS) that can take hours or days to run to completion.
</listitem>
replacement in doc/manual/introduction.xml at line 33

[3.1187]→[3.1187:1343](∅→∅)

<listitem> Many kinds of static and dynamic analyses can be
performed as part of the tests, such as code coverage runs and
static analyses.
</listitem>

[3.1187]

[3.1343]

<listitem> Many kinds of static and dynamic analyses can be
performed as part of the tests, such as code coverage runs and
static analyses.
</listitem>
replacement in doc/manual/introduction.xml at line 38

[3.1344]→[3.1344:1576](∅→∅)

<listitem> It may also be necessary to build many different
<emphasis>variants</emphasis> of the software. For instance,
it may be necessary to verify that the component builds with
various versions of a compiler.
</listitem>

[3.1344]

[3.1576]

<listitem> It may also be necessary to build many different
<emphasis>variants</emphasis> of the software. For instance,
it may be necessary to verify that the component builds with
various versions of a compiler.
</listitem>
replacement in doc/manual/introduction.xml at line 44

[3.1577]→[3.1577:1860](∅→∅)

<listitem> Developers typically use incremental building to
test their changes (since a full build may take too long), but
this is unreliable with many build management tools (such as
Make), i.e., the result of the incremental build might differ
from a full build.
</listitem>

[3.1577]

[3.1860]

<listitem> Developers typically use incremental building to
test their changes (since a full build may take too long), but
this is unreliable with many build management tools (such as
Make), i.e., the result of the incremental build might differ
from a full build.
</listitem>
replacement in doc/manual/introduction.xml at line 51

[3.1861]→[3.1861:2104](∅→∅)

<listitem> It ensures that the software can be built from the
sources under revision control. Users of version management
systems such as CVS and Subversion often forget to place
source files under revision control.
</listitem>

[3.1861]

[3.2104]

<listitem> It ensures that the software can be built from the
sources under revision control. Users of version management
systems such as CVS and Subversion often forget to place
source files under revision control.
</listitem>
replacement in doc/manual/introduction.xml at line 57

[3.2105]→[3.2105:2467](∅→∅)

<listitem> The machines on which the continuous integration
system runs ideally provides a clean, well-defined build
environment. If this environment is administered through
proper SCM techniques, then builds produced by the system can
be reproduced. In contrast, developer work environments are
typically not under any kind of SCM control.
</listitem>

[3.2105]

[3.2467]

<listitem> The machines on which the continuous integration
system runs ideally provides a clean, well-defined build
environment. If this environment is administered through
proper SCM techniques, then builds produced by the system can
be reproduced. In contrast, developer work environments are
typically not under any kind of SCM control.
</listitem>
replacement in doc/manual/introduction.xml at line 65

[3.2468]→[3.2468:2948](∅→∅)

<listitem> In large projects, developers often work on a
particular component of the project, and do not build and test
the composition of those components (again since this is
likely to take too long). To prevent the phenomenon of ``big
bang integration'', where components are only tested together
near the end of the development process, it is important to
test components together as soon as possible (hence
<emphasis>continuous integration</emphasis>).
</listitem>

[3.2468]

[3.2948]

<listitem> In large projects, developers often work on a
particular component of the project, and do not build and test
the composition of those components (again since this is
likely to take too long). To prevent the phenomenon of ``big
bang integration'', where components are only tested together
near the end of the development process, it is important to
test components together as soon as possible (hence
<emphasis>continuous integration</emphasis>).
</listitem>
replacement in doc/manual/introduction.xml at line 75

[3.2949]→[3.2949:3352](∅→∅)

<listitem> It allows software to be
<emphasis>released</emphasis> by automatically creating
packages that users can download and install. To do this
manually represents an often prohibitive amount of work, as
one may want to produce releases for many different platforms:
e.g., installers for Windows and Mac OS X, RPM or Debian
packages for certain Linux distributions, and so on.
</listitem>

[3.2949]

[3.3352]

<listitem> It allows software to be
<emphasis>released</emphasis> by automatically creating
packages that users can download and install. To do this
manually represents an often prohibitive amount of work, as
one may want to produce releases for many different platforms:
e.g., installers for Windows and Mac OS X, RPM or Debian
packages for certain Linux distributions, and so on.
</listitem>
replacement in doc/manual/introduction.xml at line 95

[3.3644]→[3.3644:3766](∅→∅)

<listitem>It obtains the latest version of the component's
source code from the version management system.
</listitem>

[3.3644]

[3.3766]

<listitem>It obtains the latest version of the component's
source code from the version management system.
</listitem>
replacement in doc/manual/introduction.xml at line 99

[3.3767]→[3.3767:3903](∅→∅)

<listitem> It runs the component's build process (which
presumably includes the execution of the component's test
set).
</listitem>

[3.3767]

[3.3903]

<listitem> It runs the component's build process (which
presumably includes the execution of the component's test
set).
</listitem>
replacement in doc/manual/introduction.xml at line 104

[3.3904]→[3.3904:4052](∅→∅)

<listitem> It presents the results of the build (such as error
logs and releases) to the developers, e.g., by producing a web
page.
</listitem>

[3.3904]

[3.4052]

<listitem> It presents the results of the build (such as error
logs and releases) to the developers, e.g., by producing a web
page.
</listitem>
replacement in doc/manual/introduction.xml at line 117

[5.3934]→[3.4270:5360](∅→∅)

<listitem> They do not manage the <emphasis>build
environment</emphasis>. The build environment consists of the
dependencies necessary to perform a build action, e.g.,
compilers, libraries, etc. Setting up the environment is
typically done manually, and without proper SCM control (so it
may be hard to reproduce a build at a later time). Manual
management of the environment scales poorly in the number of
configurations that must be supported. For instance, suppose
that we want to build a component that requires a certain
compiler X. We then have to go to each machine and install X.
If we later need a newer version of X, the process must be
repeated all over again. An ever worse problem occurs if
there are conflicting, mutually exclusive versions of the
dependencies. Thus, simply installing the latest version is
not an option. Of course, we can install these components in
different directories and manually pass the appropriate paths
to the build processes of the various components. But this is
a rather tiresome and error-prone process.
</listitem>

[5.3934]

[3.5360]

<listitem> They do not manage the <emphasis>build
environment</emphasis>. The build environment consists of the
dependencies necessary to perform a build action, e.g.,
compilers, libraries, etc. Setting up the environment is
typically done manually, and without proper SCM control (so it
may be hard to reproduce a build at a later time). Manual
management of the environment scales poorly in the number of
configurations that must be supported. For instance, suppose
that we want to build a component that requires a certain
compiler X. We then have to go to each machine and install X.
If we later need a newer version of X, the process must be
repeated all over again. An ever worse problem occurs if
there are conflicting, mutually exclusive versions of the
dependencies. Thus, simply installing the latest version is
not an option. Of course, we can install these components in
different directories and manually pass the appropriate paths
to the build processes of the various components. But this is
a rather tiresome and error-prone process.
</listitem>
replacement in doc/manual/introduction.xml at line 137

[3.5361]→[3.5361:6228](∅→∅)

<listitem> They do not easily support <emphasis>variability in software
systems</emphasis>. A system may have a great deal of build-time
variability: optional functionality, whether to build a debug or
production version, different versions of dependencies, and so on.
(For instance, the Linux kernel now has over 2,600 build-time
configuration switches.) It is therefore important that a continuous
integration tool can easily select and test different instances from
the configuration space of the system to reveal problems, such as
erroneous interactions between features. In a continuous integration
setting, it is also useful to test different combinations of versions
of subsystems, e.g., the head revision of a component against stable
releases of its dependencies, and vice versa, as this can reveal
various integration problems.
</listitem>

[3.5361]

[3.6228]

<listitem> They do not easily support <emphasis>variability in software
systems</emphasis>. A system may have a great deal of build-time
variability: optional functionality, whether to build a debug or
production version, different versions of dependencies, and so on.
(For instance, the Linux kernel now has over 2,600 build-time
configuration switches.) It is therefore important that a continuous
integration tool can easily select and test different instances from
the configuration space of the system to reveal problems, such as
erroneous interactions between features. In a continuous integration
setting, it is also useful to test different combinations of versions
of subsystems, e.g., the head revision of a component against stable
releases of its dependencies, and vice versa, as this can reveal
various integration problems.
</listitem>
edit in doc/manual/introduction.xml at line 261

[5.3974]