Project powered by:
Probably the best to way summarize the features of toc is to compare it to its arch-nemesis, the GNU Autotools...
  • toc targets only systems hosting relatively recent versions of GNU tools (GNU make 3.80+, gcc, GNU find, GNU tar, bash, etc.). To-date it has successfully been used on a number of Linux boxes, a few (GNU-updated) Solaris 7/8/9 machines, plus Windows NT 4.0 and XP running the Cygwin environment.
  • Lives entirely in your source tree, so there is no system-wide software to install. This means that changes have no risk of affecting other projects. (Oh, let me count the hours spent fixing my trees after system-wide upgrades of the autotools...) Historically speaking, since its original introduction (2003), toc has never once been broken by a system-wide tools upgrade, whereas Autotools-based trees quite regularly break in that case.
  • Not specifically aimed at source trees: it can just as easily be used for a document repository, e.g., to process SGML or LyX files, find the sgml/lyx/foo converter applications, make distribution tarballs, etc.
  • toc generally integrates easily into existing makefiles without major changes to your project.
  • toc does not create your Makefiles. Instead it creates auxilary makefiles which client Makefiles (indirectly) include. This gives clients the freedom to use their makefiles however they like, and toc will never say "xxx_yyy_zzz is an invalid variable name", as the Autotools sometimes do.
  • Unlike Autotools, which requires that all configuration take place in the configure script, toc can be largely configured at make-time, allowing, e.g., the conditional processing of subdirectories, as determined by make-time tests. This reduces the need to re-run the configure script, which in turn avoids many unnecessary rebuilds.
  • The configure phase is much faster than that of GNU Autotools, normally taking only a few seconds.
  • Most project/directory-specific makefile rules are created at make-time, not configure time, so they adapt quickly as your project changes (without requiring a reconfigure). Rules generation, in bad cases, normally take no longer than a small fraction of a second, so the build time impact is negligible.
  • It is much simpler to maintain (IMO, anyway). For example, configure tests are each maintained in their own file and then loaded via a classloader-like mechanism, which makes them much easier to integrate into or remove from a project than traditional autotools tests, as well as easy to share amongst projects.
  • It's very easy to modify.
  • Provides a way for test writers to add "online help" to their test scripts, available via ./configure --help-testname.
  • Takes full advantage of the power of GNU Make, giving a number of maintenance benefits and additional super-powers over trees limited to compatibility with "fake Makes".
  • Provides a small, shell-code-based framework for running configuration tests. There is no macro language to learn. It also provides an extendable Make-based framework for performing common build tasks (compiling C/C++ code, building libraries, etc.).
  • Transparently provides lightning-fast C/C++ dependency generation.
  • Compared to Automake-driven builds, C++ compile times are cut by as much as 25%, for reasons too complex to summarize here.
  • Possibly not as scalable as Autotools, though this is theoretical and has yet to be proven.
  • Comes with a number of useful test scripts and modular makefile snippets, and adding your own is straightforward.
Here is an overview of the notable "mis-features":
  • toc does not support compilation to a target directory outside of the source tree (that is, to allow read-only source trees). This would be an interesting feature and is on the to-do list but is low priority.
  • toc targets ONLY platforms which host GNU versions of the various common system tools, e.g. GNU find, GNU sed, GNU awk, GNU make 3.8.0+, etc. It does not need any exotic tools, however - all of the tools it needs are installed on any sane *nix system. There are no plans whatsoever to change this limitation.
  • That's about it... toc does everything else i've ever needed a build tree to do. :)