The build system

CLAM provides a quite automated Build System that allows to generate and maintain, with little effort, GNU Makefiles and VisualC++ project files to build large volumes of source files. Note that this build system is specialized on building CLAM distribution binaries and CLAM based applications and although it could be surely be adapted to other kind of projects it has not been used outside the framework.

In any project it is difficult to deal with a complex source files dependency graph. Without a build system helper you have to add by hand each .cxx file into the Project IDE or build script in order to compile it. CLAM Build System is able to do this task with little supervision: srcdeps is a small and smart application that is able to deduce the source files that need to be compiled following the following simple rule:

        'If main.cxx must be compiled and includes both blue.hxx and green.hxx

        then blue.cxx and green.cxx must be also compiled'

This rule to is based on the hypothesis that for each header named Foo.hxx a Foo.cxx file exists somewhere, a thing that may or may not be true. Also there can be additional .cxx not related to any .hxx that should be compiled. In both cases, you can provide additional starting points to look for dependencies.

The CLAM build system is designed to be used to build CLAM examples, libraries and tests that are inside the CLAM source tree. But it also provides facilities to anybody building their own applications with CLAM. In order to use CLAM internal build system for building your App you must consider the source tree structure suggested in the documentation and use the following configuration files: defaults.cfg, settings.cfg, clam-location.cfg, system.cfg, and system-win.cfg or system-linux.cfg. Out of these, three need to be edited: the particular path to clam must be introduced into clam-location.cfg, the default global configuration variables must be edited into defaults.cfg and the settings related to the particular project must be entered into settings.cfg.

There are two main kinds of config variables depending on the values they may take: Boolean variables - these can only have values of 0 or 1. Usually 0 means that the variable effect is disabled, and 1 that it is enabled; and Textual variables - they are a string, for instance, a relative path to some file. Also depending on the effect, there are three kinds of variables: Build System variables - variables whose value just affects the CLAM build system behavior while naming binaries or searching for certain files; External Libraries variables - variables whose value determines whether the build system will make your application link or not to some ( or any ) of CLAM external libraries; and CLAM internal variables - these variables are mainly compile-time flags that activate/deactivate certain framework features or change some framework behavior.

Build system variables reference include the following:

TOP (Textual) - Should contain the relative path from the settings.cfg file to the 'top' of the project source tree

PROGRAM (Textual) - Should contain the name for the program binary

PRJ_SEARCH_INCLUDES (Textual) - Should contain the lists relative paths, from settings.cfg location, to folders where you want srcdeps to look for binary dependencies, usually the folders where you have your sources. Note that srcdeps *will not* perform a recursively descent search on these folders.

PRJ_SEARCH_RECURSE_INCLUDES (Textual) - Should contain the list relative paths, from settings.cfg location, to folders where you want srcdeps to look for binary dependencies, usually the folders where you have your sources. Note that srcdeps *will* perform a recursively descent search on these folders.

SOURCES (Textual) - Should contain the source file that contains the application entry point. While building library binaries or not following for some reason the rule 'for each header file there exists a source file with the same name' then you should add the source relative paths, from current settings.cfg location.

CLAM configuration variables include:

CLAM_DOUBLE(Boolean) - This variable controls whether CLAM::TData datatype is either a single precision floating-point number ( ANSI C++ float type ) or a double precision floating-point number ( ANSI C++ double type ).

CLAM_USE_XML(Boolean) - This variable controls whether CLAM code is built with XML-based Object External Storage support. Disabling it could improve compiling speed as well as reduce code size.

CLAM_DISABLE_CHECKS(Boolean) - This variable controls whether CLAM internal precondition, postcondition and invariant verification checks are performed or not. Deactivating it could improve code speed in spite of robustness.

CLAM_USE_RELEASE_ASSERTS(Boolean) - This variable controls whether CLAM Asserts behave equally in "debug" and "not debug" mode.

And finally external libraries variables are:

USE_ALSA(Boolean) - Tells the build system to make applications to link against ALSA. Note that this variable can only have effect on GNU/Linux systems.

USE_FFTW(Boolean) - Tells the build system to make applications to link against the FFTW library.

USE_FLTK(Boolean) - Tells the build system to make applications to link against FLTK.

USE_DIRECTX(Boolean) - Tells the build system to make applications to link against DirectX SDK. Note that this variable only has effect on Microsoft Windows(c) systems.

USE_PORTMIDI(Boolean) - Tells the build system to make applications to link against Portmidi. Note that this variable only has effect on Microsoft Windows(c) systems.

USE_RTAUDIO(Boolean) - Tells the build system to make applications to link against RtAudio. Note that this variable only has effect on Microsoft Windows(c) systems.

USE_PTHREADS(Boolean) - Tells the build system to make applications to link against pthreads (POSIX threads library). Note that this variable only has effect on Microsoft Windows(c) systems.

USE_QT(Boolean) - Tells the build system to make applications to link against Qt Toolkit.

USE_CPPUNIT(Boolean) - Tells the build system to make applications to link against cppUnit library.