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 <something>) are used to
make sure the compiler gets the right arguments. The link between
compiler 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 mention of a global header file in these files is
used. Usually only ./ccResolutions is used, but there are more
possibilities. See the section 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
thatfile.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
targets will be listed.
check [filename.cc]
Dsplay 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
running: 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 concatenated 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 anything but 0. The first argument given to the
command will be relative 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
command).
--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 discover 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 currently 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
compilation. 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 configuration line. A configuration line contains the
name of the global header, followed by one or more tab characters and
then the additional arguments 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
compiler 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 dependencies 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 usefull for when you change the interface of a
class.
ccbuild --compiler distcc -j 20
Use 20 distcc compilers to compile the project.
ccbuild --nodefargs -f --args ’-Wall -Werror’ && svn commit -m
’buildable backup’
If all the sources are buildable without any warnings, commit
everything to the repository using subversion.
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,
./ccResolutions.HOSTNAME, ./ccResolutions.KERNEL_NAME,
./ccResolutions.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
Don’t 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. Examples 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: http://www.logfish.net/pr/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.
AUTHOR
A. Bram Neijt <bneijt@gmail.com>
SEE ALSO
pkg-config(1), dotty(1), make(1), icmake(1), g++(1), aap(1), svn(1)
ccbuild(1)