build.h

Go to the documentation of this file.

/*
 * build.h
 *
 * Bogus header for doxygen documentation.  Do not use this!
 */

/// \ingroup dev_guide
/// \defgroup build Wavepacket Build System
///
/// The build system used by the Wavepacket family of source repositories
/// (wavepacket-lib, wave-glut, wave-audio, aesop, folium).
///
/// This home-grown build system came out of
/// early attempts to get recursive and dependent builds working, plus my
/// initial stabs at Perl programming.
///
/// Eventually, this system should be replaced by an open source standard
/// build system.  But this is used for now.
///
/// Features of the wavepacket build system:
///  - <b>Separate directories for source and object files.</b>  So when you build,
///     your source directory stays clean.  Object files (and other build
///     artifacts) are put in dedicated directories in a parallel tree.
///
///  - <b>Support for dependent modules.</b>  So if you build an application that
///     depends on multiple libraries, those will be built and linked in
///     the correct dependency order.  Also, the dependencies are recursive.
///     So if you create an application that declares a dependency on library
///     A, and library A declares a dependency on library B, when you build
///     your application the build system will also build and link both
///     libraries.
///
///  - <b>Support for cross-repository builds.</b>  This is necessary because I have
///     multiple projects, each with their own SVN repository, that depend on
///     each other.
///
///  - <b>Support for GNU autoconf packages.</b>  That is, you can use the build
///     system to create distributable tar'd packages that support autoconf
///     and automake.  This is obviously handy to create versioned public
///     releases.
///
/// GNU Autoconf support is primitive for now, but I will update it over time.
///
/// To use the build system, any buildable object (application or library) must
/// supply two files: a config file (named "config") and a Makefile (named
/// "Makefile").  I thought of the names myself.
///
/// A buildable object must be in its own directory.  A given directory can only
/// contain a single object (library or application).
///
/// The build system does make one assumption: all of your repositories are
/// listed as peers in the same parent directory.  For instance, I've got an
/// svn directory that contains both wavepacket-lib and folio as child
/// directories.  As a developer, it is up to you to acquire local versions of
/// necessary repositories.
///
/// The build system will create an "obj" directory within each repository, and
/// all object files and other build output for modules in that repository will
/// be contained in that obj directory.  The obj/bin directory contains
/// "installed" versions of applications (applications and tools will
/// automatically copy their built executable to obj/bin), so
/// it is a clean directory to use for executing built binaries.
///
/// \n
/// It is also possible to build resources into a binary as part of the build
/// system.  See \ref common_resources .
///
/*@{*/

////////////////////////////////////////////////////////////////////////////////
///
/// \defgroup build_Makefile Build System Makefiles
///
/// The Makefile is very basic: it is standard GNU makefile format.  It has to
/// declare three variables:
///  - THIS_REPO: the name of the repository that the given directory is in.
///     Examples are "wavepacket-lib" or "folio".
///  - BUILD_DIR: relative path to the build directory.
///  - MODULE: the module specification (type and name).  Examples are
///     "[LIB]/graph" for a library named "graph", or "[APP]/folium" for an
///     application named "folium".
///
/// There is an additional optional variable the Makefile can declare:
///  - DEPEND_REPOS: other repositories upon which this module depends.  This
///     is a comma-separated list of repository names (no spaces!).
///
/// Finally, the Makefile includes the main build file default.inc (in the
/// build directory), and that does the heavy lifting.
///
/// To build a module (library or application) just cd to the relevant
/// directory, and type:
/// \code
///     % make [target]
/// \endcode
///
/// There are 4 supported build targets:
///  - all : (this is the default).  This makes this module and all
///     dependencies.  If the current module is an application, it will also
///     be linked.
///
///  - clean : a "make clean" will delete all object files for this module.
///
///  - nuke : a "make nuke" will recursively delete all object files for this
///     module and all of its dependencies.
///
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
///
/// \defgroup build_config Build System Config files
///
/// The second file is the config file.  This is purely a data file, it
/// contains only key/value pairs.  (Actually it is a recursive hash, see
/// Hash.pm.  However, the build system doesn't need any of the nested
/// structure, so the file is essentially flat key/value pairs).
///
/// A key value pair must be contained on a single line.  The format is this:
/// \code
///     key     value
/// \endcode
///
/// That is, a key and a value separated by whitespace.  The key will be the
/// first contiguous token found on the line.  The value is everything else,
/// with leading and trailing whitespace removed.
///
/// Common key/value pairs you should declare:
///
/// Source files are declared with the "source" key.
/// \code
///     source          myfile.cpp
/// \endcode
///
/// Dependent packages are declared with the "dependency" key.
/// \code
///     dependency      [LIB]/somelib
///     dependency      [LIB]/some/other/lib
/// \endcode
///
/// If you need to build MOC files (an annoying artifact of the QT library),
/// use the "moc" key.
/// \code
///     moc             myfile.moc
/// \endcode
/// There is an additional messiness with .moc files: you'll need to \#include
/// the .moc file in your .cpp file.  And that means your .cpp file must know
/// about the output object directory.  See vgfx-widget or folium (in the
/// folium project/repository) for examples.
///
////////////////////////////////////////////////////////////////////////////////