ccbuild is a C++ source scanning build utility for code distributed over directories. Like a dynamic Makefile, ccbuild finds all programs in the current directory (containing "int main") and builds them. For this, it reads the C++ sources and looks at all local and global includes. All C++ source files in the same directories of the local includes are considered objects for the main program. The global includes lead to extra compiler arguments using a configuration file. Next to running g++ it can create simple Makefiles, A-A-P files, and graph dependencies using DOT (Graphviz) graphs.


When developing C++ programs according to a standard of "a file per function, a directory per class" your filesystem will be in constant turmoil. When you use the GNU autotools you will have to edit your for every function and sometimes let the tools re-evaluate your whole system!
This, of course, will not do. So, I set out to create a tool to aid me in my development phase. Mind you, the autotools has been proven to be good for portability and distribution, but during development they kept me editting scripts. ccbuild is for development only, distribution and protability still relies on larger and more complex systems (like GNU autotools, A-A-P, etc.).

Currently the program is able to find it's own way using your source code and a file containing information about compilation parameters that are needed when a specific global include ("#include <filename>") is used. Because it can find it's own way through your code, you can even keep it in memory during your code editting. When hitting return, ccbuild wil scan and build your source again (not rescanning unchanged files): faster then anything that has to come from disk.

The main difference with other build tools is that, ccbuild's goal is to be able to find it's own way:

no part of the build should have to be scripted

This is also why ccbuild configuration is very system specific, can't be used for distribution and the sourcecode has to adhere to a few strict rules. However this also makes it very easy to learn and use while staying unintrusive (ccbuild won't lock you into using only ccbuild).

Although ccbuild uses mostly standard C++ it also uses a few POSIX specific function. So it should run on all GNU/Linux distributions (and hopfully any other platform that looks like it). If unsure, get the latest ccbuild and give it a try. If you don't want to use your own sources, use ccbuilds.

If you don't like ccbuild, you'll probably describe it as a rigid GNU/Linux C++ hobbyist tool.


The features currently include:

Strictness ccbuild depends on

Because the program needs to understand your code, the following currently need to be true.

How it works

When run without any options ccbuild will issue the command "build". For every C++ source file in the local directory: if it contains an "int main" function, it will be seen as a binary target.

For every binary target, ccbuild will follow it's includes to other directories and see all C++ source files in those directories as objects (if they don't contain an "int main" function). It will then compile the object, keeping any linker options back for the binary target.

To know what options to use, it reads a few configuration files which describe compiler options needed when a specific global include is done. See Resolution for more information.


To be able to link and compile the binaries, the compiler needs to know what libraries to link to and of course what include paths need to be added. The ccbuild utility assumes that for all extra compiler argument, there is a global include that can indicate it's needed. When a global include is encountered ("#include <something>") it will try to resolve it by looking it up in it's table, issuing a warning if it is not found in the resolution table.

This table, which contains the extra compiler arguments for every global header, already contains all ANSI-C++ headers (like string, iostream) and is prepended with the information from tab separated configuration files. These files are loaded in the order: "./ccResolutions", "~/.ccbuild/ccResolutions" and then "~/.ccbuild/ccResolutions.d/*".

An example configuration file wich currently is useful is (notice the tab(s) between "png.h" and "-lstdc++ -lpng -lz"):

#& -l --md5 -p
# Example of ccResolutions configuration file for ccbuild 0.7.0 and up (# denotes a comment)
#The first line is special: If started with "#&""
# ccbuild will prepend these arguments to the commandline
# arguments it gets. In this case, running ccbuild without
# arguments and this configuration will be equal to
# running: ccbuild -l --md5 -p
# Please note: values must be seperated with at least one tab character.

png.h		-lstdc++ -lpng -lz
sqlite3.h	-lsqlite3
gtkmm.h		`/usr/bin/pkg-config --cflags --libs gtkmm-2.4`

When you have a nice ccResolutions file, you can move it to ~/.ccbuild/ccResolutions.d so you don't have to copy it to every program or testcase you ccbuild. Single lines of configuration are best added to the .ccbuild/ccResolutions file, which superseeds (overrides) configuration lines from the ccResolutions.d/* files.

If you just started on your project, you might want to use ccbuild resolve >> ccResolutions to add all unresolved globals to your ccResolutions file. Then you can add the needed arguments to the file.

What it can't do

Before you think I'm trying to sell you a miracle, the following are things ccbuild can't deal with at the moment (very probably not a complete list)


For compile-time dependencies see


GNU GPL: GNU General Public License

See also

Don't forget to take a look at:

Copyright 2009 (C) A. Bram Neijt
Last update: 07th 2016f February 2016