INSTALL

Installation instructions for distcc                  -*- indented-text -*-

distcc is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version. distcc comes with ABSOLUTELY NO WARRANTY,
for details see the licence.

Please report any problems to distcc@lists.samba.com.


QUICK SUMMARY
=============

0. Install prerequisites.  For example, on Debian or Ubuntu, you could use

      sudo apt-get install gcc make python3 python3-dev libiberty-dev

1. Build and install

      ./autogen.sh              # If "configure" does not already exist.
      ./configure
      make
      make check                # Optional! Should have python >= 3.1 installed.
      make install              # You may need to use "sudo" for this command.
      make installcheck         # Optional! Should have python >= 3.1 installed.
      update-distcc-symlinks    # Needs "sudo". Run this again if you install/remove compilers

   Repeat installation for each server machine.

2. Run distccd on each server machine,
   with --allow options to limit access.

3. On your client machine, set DISTCC_POTENTIAL_HOSTS to the list
   of distcc server machines:

      export DISTCC_POTENTIAL_HOSTS='localhost red green blue'

4. Build your software using distcc:

      cd ~/my_sources/my_project
      pump make -j40 CC="distcc gcc" <your target>

5. If you run into problems it is highly recommended to use DISTCC_VERBOSE=1
   on the client and "--log-level debug" on the server.

DETAILED INSTRUCTIONS
=====================

Prerequisites
-------------

To build distcc you need

   GNU Make
   A C compiler
   GNU libiberty (distributed with GNU Binutils and GCC)

It is also highly desirable to have

   Python >=3.1

     To use "pump" mode, or to run the full test suite with "make check",
     or to run the benchmarks.

If you have any version of Python installed, then you need to have
the corresponding Python.h file installed (e.g. sudo apt-get install python-dev).

You can optionally have

   libpopt

     If this is not found on your system, the popt version that is part of
     the distcc distribution will be statically linked in.

   linuxdoc SGML tools

     To rebuild the documentation from its SGML source.

   autoconf >=2.5

     To rebuild the configure scripts if you edit configure.ac.

To build the optional GNOME monitor (--with-gnome), you need the
GNOME2 development libraries, and in particular

  gtk+ >=2.0
  libgnome >=2.0
  libgnomeui >= 2.0
  libglade >= 2.0
  libpango

The monitor can also be built without GNOME desktop integration
(--with-gtk), in which case you need only

  gtk+ >=2.0
  libglade >= 2.0


Preliminaries
-------------

distcc can be installed and used without requiring root access.
Adjust directories appropriately when installing.


Configuring distcc
------------------

Note that the default GNU "sysconfdir" is /usr/local/etc.  You may
want to change this to /etc.

  $ ./configure --sysconfdir=/etc

You can set an installation prefix if you want to put distcc in /opt:

  $ ./configure --prefix=/opt/distcc/

distcc needs to be installed on all client and server machines.

If you would like a graphical client-side monitor to show running
jobs, you can choose either --with-gnome or --with-gtk.

If you would like to try running distcc over IPv6, use
--enable-rfc2553.  You must have a reasonably recent operating system
or this is likely to fail in complex ways.


Building distcc
---------------

The simple way to build distcc is to just do

  ./autogen.sh    # if "configure" does not already exist in this directory
  ./configure && make

but the recommended way is to build in a different directory tree
than the source tree:

  mkdir obj
  cd obj
  ../autogen.sh
  ../configure && make

You can optionally run "make check" afterwards to verify that everything
built OK.


Installing distcc
-----------------

If your system supports RPM packages, you can build RPMs with "make rpm"
and then install them with "rpm -i packaging/*.rpm".

If your system supports Debian packages, you can build them with "make deb"
and then install them with "make install-deb".

Otherwise, you can use the regular "make install".  But it is preferable
to install via an RPM or Debian package if possible, because those
methods will do a bit more of the setup work.

You can optionally run "make installcheck" afterwards to verify that
was installed OK.  This works regardless of which installation method
you used.


Starting the daemon
-------------------

This stage is only required if you want to run distcc over TCP
sockets, rather than SSH connections.  TCP is faster but less secure
and should only be used on trusted networks.

In TCP mode distccd can run either from inetd or as a standalone
daemon.  Running standalone is recommended.

If you installed via the debian or RPM package, then the daemon will be
installed as a service, running as a standalone daemon, and it should get
started up automatically, so you can skip the rest of this section
"Starting the daemon".  The rest of this section only applies if you
installed via "make install".

To run standalone, run a command like this, either from the command
line or from the system startup scripts.

  distccd --daemon

If the daemon is started from an rc script, then make sure that it
sees a PATH setting which can find any compilers installed in
nonstandard directories.

You should create a "distcc" account on server machines so that distcc
can run with minimal privilege.  It is not necessary for this account
to own any files or have a home directory.  If this account doesn't
exist, distccd uses the "nobody" account.

By default distccd writes messages to the "daemon" syslog, which
typically ends up in /var/log/messages or /var/log/daemon.

You can set IP-based access control using the --allow and --listen
options, in either inetd or daemon mode:

  distccd --allow 10.4.20.0/24

distccd does not need to run on machines that will only act as
clients.

See the manual for more information.


Editing the daemon configuration files
--------------------------------------

If you installed via the RPM or Debian package, then you
will have an /etc/init.d/distcc script which reads several
configuration files to decide if and how to invoke distccd.
These configuration files are

   /etc/default/distcc
   /etc/distcc/clients.allow
   /etc/distcc/commands.allow.sh

If you installed via the RPM or Debian package, then you
should edit those configuration files, especially the
clients.allow file.

If you installed via "make install", then those configuration
files will be installed, but they will NOT be used, unless
you manually install the init.d/distcc script from
packaging/RedHat/init.d/distcc and tailor it for your system.

If you start distccd manually, rather than via the init.d/distcc script,
then distccd won't use any configuration files; the allowed client IP
addresses will be determined by the --allow options that you pass to
distccd and the allowed commands will be determined by the DISTCC_CMDLIST
environment variable; see the distccd(1) man page for details.

See also the doc/example directory and its README file, which
has examples of the configuration files that you need.


Setting up the host list
------------------------

On the client machines, store a list of servers names in
~/.distcc/hosts or /etc/hosts, or in the DISTCC_HOSTS
environment variable.

If you're using TCP connections, it should look like
this:

  localhost red green blue

For SSH connections

  localhost @red @green @blue

The hosts should be listed in descending order of speed.  localhost
should normally be first, unless it is significantly slower than
another machine.  If you many hosts (say ten or more), it's probably
better to leave localhost out of the list.

The host list also needs ",cpp,lzo" after each host if you're using
pump mode - see README.pump for details.  Another alternative if you're
using pump mode is to set the DISTCC_POTENTIAL_HOSTS environment
variable; in that case, the pump script will use "lsdistcc" to
set DISTCC_HOSTS, automatically eliminating hosts that are down
or inaccessible or that don't have distccd running.

See the distcc(1) manual and the pump(1) manual for more information.


Using distcc
------------

Distcc will only improve performance if your build is parallelized.
So you need to use the "-j" option to make, or its equivalent with
your build tools.  If your build contains too many sequential steps,
e.g. if your Makefile contains

   all:
            for subdir in $(SUBDIRS); do make -C $$subdir all; done

then you may need to rewrite your Makefile to get better parallelism.
This is especially important if you're using pump mode.


Using pump mode
---------------

To use pump mode, invoke your build command via the "pump" script, e.g.

      export DISTCC_POTENTIAL_HOSTS="localhost red blue green"
      cd ~/my_sources/my_project
      pump make -j40 CC="distcc gcc" my_target

Pump mode assumes that source files are not modified during the build.
If this assumption does not hold, you should not use pump mode.
You can disable pump mode by not using the pump script.
In that case, you need to set DISTCC_HOSTS rather than
DISTCC_POTENTIAL_HOSTS.

      export DISTCC_HOSTS="localhost red blue green"
      cd ~/my_sources/my_project
      make -j40 CC="distcc gcc" my_target


Creating the masquerade directories
-----------------------------------

The easiest way to use distcc is in "masquerade" mode, where it is
installed on the PATH to "catch" calls to the compiler and redirect
them over the network.  Other options are discussed in the manual.

For instance, you could create the directory named /usr/lib/distcc
and populate it with links.

# mkdir /usr/lib/distcc
# cd /usr/lib/distcc
# ln -s /usr/bin/distcc gcc
# ln -s /usr/bin/distcc cc
# ln -s /usr/bin/distcc g++
# ln -s /usr/bin/distcc c++

If you installed via the RedHat or Debian package, then this masquerade
directory is already set up automatically in /usr/lib/distcc.
Do this for all compiler names that you use.

Then, to use distcc, a user just needs to put the directory
/usr/lib/distcc/bin early in the PATH and distcc will handle the rest.

  export PATH=/usr/lib/distcc/bin:$PATH


Use with ccache
---------------

The best way to use is to set up a similar masquerade directory for
ccache and put it on the PATH before distcc.

NOTE: This use of ccache is incompatible with use of distcc's "pump" mode.

(If you're using "pump" mode, it might be possible to use ccache on
the distcc server machines. But we haven't tried that setup.)


Complete the survey
-------------------

Once you have distcc working for your own application, please complete
and mail in the survey in survey.txt.