ccbuild(1)

📦
version 2.0.11 · 2 versions
, in ubuntu resolute, ubuntu stonking

okay so bestie, you opened ccbuild(1) and honestly? iconic of you. this is the manual page for ccbuild, the strict C++ developer's build utility, and we're gonna get through it together. part 1 of 2, so buckle up, we are NOT done yet 💅

✨ NAME ✨

ccbuild — Strict C++ developer’s build utility

🦋 SYNOPSIS 🦋

ccbuild options [command]

🌸 DESCRIPTION 🌸

okay so here's the vibe: ccbuild is a build utility that reads your C++ source. it collects all the source surrounding your local includes and links all of that to your main program. the global include statements (you know, the #include ones) are what it uses to make sure the compiler gets the right arguments. no cap.

the link between compiler arguments and those global includes is made using configuration files. those files contain lines with a global header file name plus the extra arguments the compiler needs to find and use that file. the file name and the 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 — go check the FILES section for the tea.

ccbuild will follow any local include (#include "something.hh") to try to find more source code to compile. now, if you want to keep ccbuild from following up on an include statement? separate the # sign and the include statement with a single space (# include). that's it, that's the trick 🫶

👑 COMMANDS 👑

build [filename.cc]

Build everything, or just the given source.

lib [filename.cc]

Collect all objects into an archive. if a version is given (via --pversion), then a shared library is also built, with symbolic links. heads up: this currently forces the -fPIC argument addition. the name of your library is given the name of the current directory — or its parent, when the current directory is called src.

Example: create an empty .cc file which simply includes all the local libraries, then 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 it removes all .gch files. bye bye 🧹

deps [filename.cc]

List all files this source depends on. it lists three lines, separated by empty lines:

  1. the local dependencies
  2. the ignored headers (for the file)
  3. all global includes needed

dot [filename.cc]

Generate dot graph files for sources on 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, plus lists of ignored headers. objects get coloured light grey, binary targets light blue, and ignored headers get a red line. cute little diagram moment 🌈

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]

Display source status and file name on 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 that ccbuild identifies it as. that 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, 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 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 — yeah, it's giving "read the room" energy, but they're all still here.

  • -f, --force-update — update everything by labelling everything as old. gaslight the whole tree into thinking it's stale 💀
  • -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, in which case the current directory will be used. this touches AUTHORS, NEWS, README, INSTALL, COPYING, TODO and ChangeLog.
  • -s, --no-act — simulate, don't really execute any writing commands. pretend build, no cap 🙈
  • --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. stubborn queen energy 👑
  • --md5 — use MD5 hashes to check for file changes. the hashes are stored 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 than o. > make sure you do not come to depend on this behaviour, that would be bad practice. fr fr, don't do it.
  • -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 the 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). aesthetic ✨
  • --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 lib 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. so keep it cute and slash-free bestie.
  • --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. so like, don't get too attached.
  • -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.

and 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. sneaky little bonus line, iykyk 💜

✨ EXAMPLES ✨

Okay bestie, this is the part where it gets fun. Real talk, these are actual ways people use ccbuild in the wild, and honestly? Some of these are lowkey genius.

  • ccbuild resolve >> ccResolutions — this one adds every unknown global header to the ccResolutions file. You can also toss in --nowarn to keep ccbuild quiet about it, but heads up: you're gonna have to think twice if you start getting compilation errors. 🙈
  • ccbuild --brute — the "I just ran distclean and I'm in the pit of despair" move. This updates as many objects as will actually compile, which means you can focus on the errors in your next ccbuild call instead of drowning. main character recovery arc. 💅
  • ccbuild -p --compiler g++-3.4' --args -Wall --args -Wextra -ansi' — precompiles internal headers using g++-3.4 and highlights all compiler output (-l). Also hands every compiler command the parameters "-Wall -Wextra -ansi". Chef's kiss. ✨
  • ccbuild -f --args -O3 — recompiling your whole project for benchmarking tests. Forces the update of all code (-f) and sets the compiler argument to -O3. go off, optimizer. 🔥
  • ccbuild --verbose dot; dotty *.dot — graphs the dependencies for all programs, with colours, then you view them with dotty. This helps you spot irregular dependencies and figure out what your test programs are actually using. It's giving detective era. 🕵️
  • **ccbuild --xof gedit'** — tries to compile the program and opens the *first* file that doesn't compile correctly. It opens all error-producing sources in gedit`. Super useful when you change the interface of a class and everything explodes at once. 😭
  • ccbuild --compiler distcc -j 20 — use 20 distcc compilers to compile the project. twenty. twenty compilers. iconic. 👑

🌸 FILES 🌸

Configuration files used by ccbuild, bestie. These are the little guys that hold your settings.

  • ./ccResolutions[.USERNAME,.HOSTNAME,.KERNEL_NAME,.MACHINE,] — the local configuration, and it's project specific. It loads the first existing file out of: ./ccResolutions.USERNAME, ./ccResolutions.HOSTNAME, ./ccResolutions.KERNEL_NAME, ./ccResolutions.MACHINE, ./ccResolutions. You can find the hostname, kernel name and machine with uname -nsm.
  • ~/.ccbuild/ccResolutions — the global configuration file. 🌍
  • ~/.ccbuild/ccResolutions.d — the resolution configuration directory. Every single file in this directory counts as a configuration file. no cap. 📂

💀 CAVEATS 💀

Okay so this is the part where I hold your hand and tell you the scary things. Please actually read this one.

Do not put any file into o directories. These will be removed when you use the distclean command. Gone. Poof. bye bestie 💀

Also, don't use files with the same basename but different C++ extensions — that gives you problems with the objects created. Like, for example, add.cc and add.cpp in the same directory? That's a no from me.

Currently there is no way to allow one object file to affect the command-line parameters of another. Which means: if all objects need a flag, you must use the --args argument and you can not 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. (I know, I know. go read the other manual. it's giving homework.)

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? ccbuild will think the generated scanner is a test program for your class and won't link it into the main program. The 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 🐛

Found something cursed? 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, and all other combinations will be acted on.

And before you @ me: this is a feature, not a bug. periodt. 💅 In verbose mode (--verbose) these get 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>

and that's the whole page, bestie 🫶 this one came out of the General Commands Manual and it's dated August 8, 2014 — so it's basically vintage, and vintage is always iconic. now go compile something cute. 💖✨🎀

📦 where this page comes from