Ubuntu Manpage: ccbuild — Strict C++ developer's build utility

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 useful 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>