Man Linux: Main Page and Category List


       ccbuild — Strict C++ developer’s build utility


       ccbuild [options ]  [command ]


       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").


       build []
                 Build everything or the given source.

       lib []
                 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

       clean []
                 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 []
                 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 []
                 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 []
                 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 []
                 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 []
                 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 []
                 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 []
                 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 []
                 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 "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.

                 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

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

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

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

       -V --version
                 Output  version  number  on  stdout  and copyright/license on

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


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

       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

       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.


       Configuration files used by ccbuild

                 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.

                 Global configuration file.

                 The  resolution  configuration  directory.  All files in this
                 directory are considered configuration files.


       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 "" and "add.cpp" in the same

       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.


       Report any issue with ccbuild at:


       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.


       A. Bram Neijt <>


       pkg-config(1), dotty(1), make(1), icmake(1), g++(1), aap(1), svn(1)