CCONTROL(1) CCONTROL(1) NAME ccontrol - wrapper to control distcc, ccache and more SYNOPSIS gcc ... cc ... c++ ... make ... ld ... ccontrol [--section=
] ... ccontrol [--section=
] DESCRIPTION The ccontrol(1) program takes over the roles of the compiler and linker, and reads a configuration file to decide what to do before invoking them. This is particularly useful for centralized control over commands and options, such as enabling distcc(1) and ccache(1). When ccontrol(1) is invoked under its own name with no arguments, it prints out the settings which apply in this directory (unless --section is specified). Versions are named after the last person to report a bug. OPTIONS Normally ccontrol(1) is invoked as a symboling link to cc, make, etc, so it can identify what is being invoked by examining its own name. It can also be invoked under its own name, in which case ccontrol-specific arguments can be supplied. The first non-option argument will be used to identify the invocation, eg. "ccontrol gcc ...". The following options are supported, when invoked as ccontrol: --section=
This is treated as the "current directory" for the purposes of evaluating the configuration file. As all real directories must begin with a "/" using an argument which does not, is a good way of overriding configuration for this particular invocation. CONFIGURATION FILE ccontrol$-1òùs configuration file is $HOME/.ccontrol/default. If this canòð not be read (and written), your compilations will all fail. It is nor$-1òð mal to have several different configuration files in this directory, and make default a symbolic link. SYNTAX A configuration file consists of sections, led by a "[path]" header and followed by indented "name = value" entries. The first section is usu$-1òð ally labelled "[*]" to set up the defaults. At the very least, you must set the "cc", "c++", "make" and "ld" values. ccontrol will read every section which matches the current directory, so you can override values on a per-directory basis. The "[path]" header of each section is a shell-style wildcard (see glob(7)) which indicates the directory or directories it applies to. Usually this will end in a "*" to include all subdirectories. The following settings are available: cc Followed by = specifies the full path of the compiler to be invoked when ccontrol is invoked as "cc" or "gcc". ccontrol will fail to compile C programs if this is not set. c++ Followed by = specifies the full path of the compiler to be invoked when ccontrol is invoked as "c++" or "g++". ccontrol will fail to compile C++ programs if this is not set. ld Followed by = specifies the full path of the linker to be invoked when ccontrol is invoked as "ld". ccontrol will fail to link programs if this is not set. make Followed by = specifies the full path of the binary to be invoked when ccontrol is invoked as "make". ccontrol will fail to make if this is not set. ccache Followed by = specifies the full path of "ccache", and indicates that ccache is to be used where appropriate. If this is not set, or set to off, ccache will not be used. distcc Followed by = specifies the full path of "distcc", and indicates that distcc is to be used where appropriate. If this is not set, or set to off, or distcc-hosts is not set, distcc will not be used. distcc-hosts Followed by = specifies the distcc servers to use, as per the DISTCC_HOSTS environment variable in distcc(1). You can set it to off to disable distcc. Set it to "off/4" if you have a machine called "off". distc++-hosts The same as distcc-hosts, but only applies to C++ compilations. If not set, distcc-hosts is used. You can thus disable distcc for C++ compilations by setting "distc++-hosts = off". cpus Followed by = and a number of CPUs, set to the number of CPUs you have (the default is "1"). ccontrol uses this to tune the degree of parallelism. no-parallel By itself, suppresses parallel make. Followed by "=" and a space-separated list of wildcards, suppresses parallel make for any make target matching one of those. This option is needed because ccontrol(1) usually forces make(1) to perform all actions in parallel, but this can be confusing when an error occurs, and breaks poorly-written makefiles. parallel By itself, enables parallel make (the default). This is useful only to override no-parallel, which uses an environment variable to disable parallelism for all its children. Sometimes a partic$-1òð ular makefile target cannot be parallel, but children can, such as certain subdirectories. include Followed by = specifies a file to include at the current point. The effect is exactly as if the contents of the included file were literally inserted. Can be used at file level to include sections. Can also be used within sections to include section fragments. add make Followed by = specifies an argument to be added to each invoca$-1òð tion of make. This can be specified multiple times to add multi$-1òð ple arguments. add env Followed by = specifies an environment variable to be set, such as "add env = CCACHE_DIR=/tmp". This can be specified multiple times to set multiple environment variables. verbose By itself, indicates that ccontrol(1) is to spit lots of crap out to standard error about what it$-1òùs doing to your innocent command line. EXAMPLES This is the minimal configuration file: [*] cc = /usr/bin/gcc c++ = /usr/bin/g++ ld = /usr/bin/ld make = /usr/bin/make If you have multiple locations (such as a laptop) it is common to have a "global" file which is included from every configuration file, like so: # Configuration file for when I$-1òùm at work. Lots of distcc hosts! include /home/rusty/.ccontrol/global [*] distcc-hosts = snab swarm1 swarm3 swarm4 swarm5 fandango2 mingo distc++-hosts = snab mingo Here is a complete configuration file with several common scenarios: [*] cc = /usr/bin/gcc-4.0 c++ = /usr/bin/g++-4.0 ld = /usr/bin/ld make = /usr/bin/make # Comment this back in for debugging # verbose distcc = /usr/bin/distcc distcc-hosts = snab swarm1 swarm3 swarm4 swarm5 fandango2 mingo distc++-hosts = snab mingo ccache = /usr/bin/ccache # make check should not generally be run in parallel no-parallel = check # Wesnoth doesn$-1òùt compile with g++ 4.0 [*wesnoth*] c++ = /usr/bin/g++-3.4 # Stupid third-party modules don$-1òùt build in parallel. [/usr/src/modules/*] no-parallel # Using distcc when testingnge effects. [*module-init-tools*/tests/*] distcc = off BUGS The .ccontrol/default file must be writable: ccontrol(1) needs to get an exclusive write lock on it, which means it needs to open the file for writing. Use include to include read-only files. ccontrol will not immediately notice a change in included files, only in the toplevel file (ccontrol re-reads the config file if it changed while ccontrol was trying to grab a lock). The Linux cpufreq ondemand governor (common on laptops) will not increase CPU speed when using ccontrol(1), because ccontrol re-nices compilations. This can make builds 2-3 times slower. Either use another governor, or tell ondemand to ignore nice values: echo 1 > /sys/devices/system/cpu/cpu0/cpufreq/ondemand/ignore_nice If your code doesn$-1òùt compile, ccontrol can only make it not compile faster. AUTHOR Written by Rusty Russell LICENSE Copyright © 2005 Rusty Russell. Free use of this software is granted under the terms of the GNU General Public License (GPL). SEE ALSO make(1), cc(1), c++(1), ld(1), distcc(1), ccache(1), glob(7), cpufreq-set(1) CCONTROL(1)