ccbuild - Strict C++ developer's build utility
is a build utility that will read C++ source. It collects all
source surrounding your local includes and links these to your main program.
Global include statements (#include ) are used to make sure the compiler gets
the` right arguments. The link between com‐ piler arguments and these
global includes is made using configuration files. These files contain lines
with a global header file name and the extra arguments the compiler needs to
find and use this file. The file name and arguments are separated by tab
character(s) or a space. ccbuild reads these configuration files in order.
Only the first men‐ tion of a global header file in these files is
used. Usually only ./ccResolutions
is used, but there are more
possibilities. See the sec‐ tion FILES for more information.
will follow any local include (#include "something.hh")
to try to find more source code to compile. To keep ccbuild
following up on an include statement, separate the #-sign and the include
statement by a single space ("# include").
- build [filename.cc]
- Build everything or the given source.
- lib [filename.cc]
- Collect all objects into an archive. If a version is given,
using --pversion, then a shared library is also build with symbolic links.
This currently forces the -fPIC argument addition. The name of your
library is given the name of the current directory or it's parent when the
current directory is called src.
Example: create an empty .cc file which simply includes all the local libraries,
run ccbuild --pversion 0.0.1 lib that‐ file.cc
- clean [filename.cc]
- Clean everything or the given source.
- Recursively remove all "o" directories after
removing all .md5 and .o files therein. And removes all .gch files.
- deps [filename.cc]
- List all files this source depends on. It lists three lines
separated by empty lines. The first contains the local dependencies, the
second the ignored headers (for the file) and the last contains all global
- dot [filename.cc]
- Generate dot graph files for sources on the stdout. If no
source file name is given, then for all binary targets in the local
directory a .dot file will be created. If the --verbose flag is used the
dot graph will also contain all object file names and their dependencies
and lists of ignored headers. Objects will be coloured light grey, binary
targets light blue, ignored headers by a red line.
- makefile [filename.cc]
- Generate a Makefile on stdout. If no file name is given, an
all rule will be generated. Otherwise only the rules for the given file
- aap [filename.cc]
- Generate an A-A-P file on stdout. If the file name is not
given, an "all" rule will be added and all local binary
tar‐ gets will be listed.
- check [filename.cc]
- Display source status and file name on the stdout. Status
and source path are separated with a tab character. Status is either
"old" or "ok". When the --verbose flag is used,
another tab separated column will be inserted containing a two letter file
type ccbuild identifies it as. This file type is "bt",
"ot", "ih" or "hh" for binary target, object
target, internal header and header respectively.
- icmake [filename.cc]
- icmake slave mode. This will output the used directories
with one directory per line. If a CLASSES file already exists, it will
only output the class directories not mentioned in the CLASSES file. If
--verbose is given, all classes will be listed. The output will not
contain directories with only header files. Updating the CLASSES is
typically done by run‐ ning: ccbuild icmake >> CLASSES
- resolve [filename.cc]
- Print all unresolved globals onto the stdout followed by a
tab character. These can be appended to the ccResolutions file using:
ccbuild resolve >> ccResolutions .
- md5 [filename.cc]
- MD5 sum all sources needed to compile all binary targets,
or the given source on stdout.
Options are used to change the behaviour of the commands. Some options are
useless for some commands.
- -f --force-update
- Update everything by labelling everything as old.
- -h --help
- Get a list of options and commands.
- Touch files part of the GNU software standard. They will be
touched in ../ except when there is a directory called src in the current
directory, then the current directory will be used. This will touch
AUTHORS, NEWS, README, INSTALL, COPYING, TODO and ChangeLog.
- -s --no-act
- Simulate, don't really execute any writing commands.
- --compiler cmd
- Set the compiler command. The default is
- -a --args argument
- Set these default compiler arguments, removing the standard
default arguments ("-Wall -g"). Multiple uses of this option are
concate‐ nated with spaces.
- -C path
- Change directory before anything else.
- -p --precompile-ih
- Pre-compile only internal headers. This requires g++
version 3.4 up.
- Pre-compile both internal headers and normal headers. This
requires g++ version 3.4 up. When you use internal headers, this will only
slow you down. However, when you don't use internal headers, this
pre-compilation is all you've got.
- Continue on compiler errors.
- Use MD5 hashes to check for file changes. The hashes are
store in "o/filename.md5" for every file. These sums are only
stored after a clean exit from ccbuild (last line showing "[WR] MD5
data") or a successful compilation.
- -I path
- Add this path to the local include search path of ccbuild
and the compiler (which will receive the same argument).
- --recursive-include path
- This is just like -I, but for the given path and every
non-empty directory with a name other then "o". Make sure you do
not come to depend on this behaviour, that would be bad practice.
- -l --highlight
- Highlight the output of the compiler using a red terminal
- --xof --exec-on-fail command
- Execute this command when the command (pre)compilation
returns any‐ thing but 0. The first argument given to the command
will be rela‐ tive path to the file the command was executed on
(which is either a C++ source or header). If you don't want to use the
file name, you can append an echo command like "sleep 2;
- --xop --exec-on-pass cmd
- This is the same as --exec-on-fail, except it only works
when the command returns 0. The first argument given to the command will
be the relative path to the file the command was executed on.
- Clear the screen just before executing the command (clear
per com‐ mand).
- --append cmd
- Append this to every command. This can be used to redirect
output or set up pipes for compiler output.
- Loop the system with one second intervals. This only works
for the build command at the moment. All sources who are touched will be
reloaded. If a file is removed, the whole source tree is reloaded.
- Do not read the first line of ./ccResolutions for extra
- Do not load any ccResolutions files outside of
./ccResolutions. This can be used to create a monolithic ccResolutions
file or dis‐ cover your project's dependencies with the resolve
- --addres filename
- Load the given resolution file before any other.
- --pversion version
- Set the program version you are working on to version. This
is cur‐ rently only used for the library command. When defined, the
library command can make a shared object (.so) and symbolic links by using
the version number. It should not contain any file system special
characters like slashes.
- Archive the objects before linking. This should reduce the
binary size because it leaves out unused objects.
- Show commands and produce more output for dot and check
- -V --version
- Output version number on stdout and copyright/license on
- Output in XML where supported. Currently this is only the
- Leave out most warnings.
- Compile a batch of files with one g++ call before any other
compi‐ lation. This effectively disables any multi-threading, but
may speed things up for larger collections of small files. This process
involves creating a temporary directory in /tmp/ccbuild_batch.XXXX. The
exact behaviour of this option may change in the future based on
performance results and user experience.
- -j number_threads
- Set the maximum number of threads used during build. Only
available when OpenMP is enabled.
The ccResolutions file links global headers to compiler arguments. Every line
should be either empty, start with a comment character "#" or
contain a con‐ figuration line. A configuration line contains the name
of the global header, followed by one or more tab characters and then the
additional argu‐ ments needed when a source depends on this global
header. The arguments are POSIX shell expanded.
If the first line of the ccResolutions file starts with "#&", the
rest of this line is shell expanded and used and appended to the argument list
Examples of program use.
- ccbuild resolve >> ccResolutions
- Add any of the unknown global headers to the ccResolutions
file. You can also use --nowarn to keep ccbuild quiet, but you will have
to think twice if you get compilation errors.
- ccbuild --brute
- Get back to development after a distclean. This will update
as much objects as will compile. Which will allow you to focus on the
errors in the next ccbuild call.
- ccbuild -p --compiler 'g++-3.4' --args -Wall --args
- Precompile internal headers using g++-3.4 and highlight all
com‐ piler output (-l). Also give all compiler commands the
parameters "-Wall -Wextra -ansi".
- ccbuild -f --args -O3
- Recompiling your project for benchmarking tests. Forces the
update of all code (-f) and sets the compiler argument to -O3.
ccbuild --verbose dot; dotty *.dot : Graph the dependencies for all programs
with colours. Then view these using dotty. This can help you to discover
irregular depen‐ dencies and what test programs use.
- ccbuild --xof 'gedit'
- Try to compile the program and open the first file that
does not compile correctly. Open all error producing sources in gedit.
Very useful for when you change the interface of a class.
- ccbuild --compiler distcc -j 20
- Use 20 distcc compilers to compile the project.
Configuration files used by ccbuild
- Local configuration which is project specific. It will load
the first existing file of: ./ccResolutions.USERNAME,
./ccResolu‐ tions.HOSTNAME, ./ccResolutions.KERNEL_NAME,
./ccResolu‐ tions.MACHINE, ./ccResolutions. Hostname, kernel name
and machine can be found with uname -nsm.
- Global configuration file.
- The resolution configuration directory. All files in this
directory are considered configuration files.
Do not place any file into o directories, these will be removed when using the
distclean command. Also don't use files with the same basename, but different
C++ extensions, this will give problems with the objects created (for example
"add.cc" and "add.cpp" in the same directory).
Currently there is no way to allow one object file to effect the command-line
parameters of another. This means that if all objects need a flag, you must
use the --args argument and cannot use a global header resolution line.
Exam‐ ples of these flags that need to be defined everywhere are
-pthreads, -mthreads and -threads. Please read the g++ manual for more
information on usage of flags.
ccbuild seems to be incompatible with flex 2.5.4. That version of flex places an
int main function in the resulting scanner and there doesn't seem to be a way
to stop it from mentioning it. The result is that ccbuild will think that the
generated scanner is a test program for your class and won't link it into the
main program. A solution is to move to a newer version of flex or find a way
to remove the int main function from the resulting scanner file.
Report any issue with ccbuild at: https://github.com/bneijt/ccbuild
ccbuild will not follow or act on any include statements with a single space
between the #-sign and the include. So all include statements starting with
"# include" will be ignored, all other combinations will be acted
on. This is a feature, not a bug. In verbose mode (--verbose) these are
mentioned as warnings.
pkg-config(1), dotty(1), make(1), icmake(1), g++(1), aap(1), svn(1)
A. Bram Neijt <firstname.lastname@example.org>.