CCONTROL: Control your compiles
===============================

Distcc is great, so is ccache.  But they are a PITA to control, as you
need to change environment variables and/or set CC, add -j to make
lines, etc.  Explicit control of which compiler you want to use is
hard.

Enter ccontrol: it takes over invocations of make(1), gcc(1), cc(1),
g++(1), c++(1) and ld(1), and decides intelligently what to do, based
on a config file in the .ccontrol subdirectory of your home directory.
In particular, it allows different options depending on which
directory it is run in: you can suppress parallel builds for projects
(or particular make targets) which don't have correctly-working
Makefiles, use a different compiler, or not use ccache or distcc,
depending on where you are.

GETTING STARTED
---------------

I recommend installing dietlibc if you can; the resulting (static)
binary is smaller and cuts a few percent off compile times.

If you want to install ccontrol in your home directory (eg. ~/bin),
use "./configure --bindir=$HOME/bin".  Otherwise, a simple
"./configure" will place the binaries in /usr/local/lib/ccontrol,
which you will have to put in your PATH.

The type "make" and "make install".  Now run "./ccontrol-init" to
create your ".ccontrol/default" file.  If you want to avoid probing
for distcc hosts on the local network, set DISTCC_HOSTS first, eg:

	DISTCC_HOSTS="one two three" ./ccontrol-init

MORE FUN
--------

You can read the ccontrol(1) man page and configure your
.ccontrol/default file (often a symlink if you have multiple different
environments).

HACKING
-------

Feedback on documentation, problems you had, and distribution
variations gratefully accepted!

Changes to ccontrol code will only be accepted with an accompanying
testcase or a really good excuse.  To make changes, install the
following packages:

	asciidoc	(to regenerate the manpages)
	xmlto		(to regenerate the manpages)
	gperf		(to regenerate the keyword list)

And I recommend the following:
	mercurial	(to view and commit changes)
	valgrind	(to improve testsuite thoroughness)

After your changes, configure with "./configure --enable-debug" and
run "make check".  Testcases are fairly simple to write: the comments
at the top control how the test is activated, and the output expected.
Use "hg bundle" to send a convenient ball of changes back to me for
merging.

Happy hacking!
Rusty Russell <rusty@rustcorp.com.au>
