Provided by: ccbuild_2.0.7+git20160227.c1179286-2_amd64 
NAME
ccbuild - Strict C++ developer's build utility
SYNOPSIS
ccbuild [options] [command]
DESCRIPTION
ccbuild 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.
ccbuild will follow any local include (#include "something.hh") to try to find more source
code to compile. To keep ccbuild from following up on an include statement, separate the
#-sign and the include statement by a single space ("# include").
COMMANDS
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.
distclean
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 includes needed.
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 are generated.
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
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.
--gnutouch
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 "g++".
-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.
--precompile-all
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.
--brute
Continue on compiler errors.
--md5 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 colour.
--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; echo".
--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.
--clearpc
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 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.
--nodefargs
Do not read the first line of ./ccResolutions for extra arguments.
--nodefres
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 command.
--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.
--ar Archive the objects before linking. This should reduce the binary size because it
leaves out unused objects.
--verbose
Show commands and produce more output for dot and check commands.
-V --version
Output version number on stdout and copyright/license on stderr.
--xml Output in XML where supported. Currently this is only the check command.
--nowarn
Leave out most warnings.
--batch
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.
RESOLUTION CONFIGURATION
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 of ccbuild.
EXAMPLES
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 '-Wextra -ansi'
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.
FILES
Configuration files used by ccbuild
./ccResolutions[.USERNAME,.HOSTNAME,.KERNEL_NAME,.MACHINE,]
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.
~/.ccbuild/ccResolutions
Global configuration file.
~/.ccbuild/ccResolutions.d
The resolution configuration directory. All files in this directory are considered
configuration files.
CAVEATS
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.
REPORTING BUGS
Report any issue with ccbuild at: https://github.com/bneijt/ccbuild
RESTRICTIONS
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.
SEE ALSO
pkg-config(1), dotty(1), make(1), icmake(1), g++(1), aap(1), svn(1)
AUTHORS
A. Bram Neijt <bneijt@gmail.com>.