build-config controls every step of the compilation, pseudo-installation, and packaging process. It is component-based: each project is considered as an independent entity, which has requirements and dependencies on other components (other projects, or system libraries). build-config is an extensible tool: you can create new projects and manage them using build-config.

The most common use of build-config is for compiling existing projects. The standard use of is is:

build-config [global-options] \
    component1 [component1-options] [component2 [component2-options] ...]

A compilation process involves several steps, some of them being optional:

Dependencies are handled by build-config: here if, for instance, component2 depends on other component3 and component4 components, then component3 and component4 will be added to the list of components to build, and processed/built before component2 is processed. So you don't need to specify them on the commandline: only highest-level terminal components are required explicitly (but it is not a mistake to specify them all, of course).

Some commandline options can control whether and how these steps are done. By default, only detection, configuration and compilation steps are performed. There is also another step meant exclusively for developers: version change, and when requested, is executed just after the component detection step.

Commandline options are either global, or targetted at one or more components. All options passed before the first component is named are considered to be global, and are applied to all components. To aim an option to only a specific component, use it just after this component is named on the commandline. For instance:

build-config --buildMode release cartodata --verbose 1

Boolean options, like the --verbose option, have no value if they are passed as global options, but must always have a value if they are passed as component-specific options. This is for technical reasons, because components options types are not known at the moment the commandline is parsed. For instance, you say:

build-config --verbose cartodata

build-config cartodata --verbose 1

At the moment, build-config and the other compilation tools need a sh or bash-like Unix shell. This does not mean that it cannot run on Windows systems: it does actually work on Windows, but in a shell. So on Windows you have to install either MSys and MinGW or Cygwin.

With the previous restrictions, build-config and the other tools work on the following platforms:

To build anatomist on a Linux system, follow the following steps:

To get the classical commandline help, use the -h (or --help) option:

build-config -h

Here is a list of the most common options:

A component represents a software bundle: either a system library (with corresponding include files), a langage (such as python), or a project directory tree designed for build-config. Each component has corresponding files on the disk that build-config has to find and identify. Each component is searched in a specific path list. The default path list contains the current working directory (the directory from which you run build-config), plus some standard system paths such as /usr and /usr/local. Some specific system components can follow their own search rules: for instance the Qt library is searched first by looking at the QTDIR environment variable.

Because the current working directory is the first path to look for components, it is generally convenient to run build-config from the directory containing the projects sources:

gargamel:appli% pwd
/home/appli
gargamel:appli% ls
cartobase-3.1/
cartobase-main/
cartodata-3.1/
cartodata-main/
gargamel:appli% build-config --version 3.1 cartodata

If you have libraries or build-config projects in "non-standard" locations, you can specify the search paths using the --sources commandline option:

build-config --sources /usr/local/software:/home/toto/devel cartodata

build-config --sources "C:\Program Files;C:\mingw;D:\devel" cartodata

For build-config specific projects, it may be a little bit more complex if you have several versions of the same project: then build-config will not be able to guess by itself which one you wish to use and compile. In this case you have to specify a version option:

build-config --version 3.1 cartodata

build-config --version 3.1 cartodata cartobase --version 4.0

Version information can be specified either as a numeric value, this value is read from the VERSION file in the root of projects directories, or as a symbolic extension to the projects directories names: in the previous example, "main" is a possible value for the version passed to build-config:

build-config --version main cartodata

Dependencies between components are taken into account by build-config: some components may depend on others. Dependencies may be either strong (if a dependency component is missing, then the dependent component cannot be built) or optional. Optional dependencies typically handle plugins that can be absent, or parts of a project that can be condidionally compiled.

This step and corresponding commandline options are meant only for us. Don't use them.

The configuration step creates the build tree and the needed subdirectories in the build tree. For projects with a compilation step (C and C++ projects), a configuration file is processed and written in the build tree. This configuration file is meant for maker and summaries in project file variables all the compilation options, including libraries the project depends on, optional compilation flags and macros, etc. Then configure is called to generate appropriate Makefiles.

Once done and up to date, the configuration step can be avoided: use the --no-configure commandline option to disable it. To re-enable it (for a specific component, for instance), use the --configure option.

The compilation step is normally merely a matter of running make in the build subtree of each component. This step can be done by hand by experts without the help of build-config, once the configuration is done and up to date, to recompile a sub-part of the programs.

The compilation step can be disabled: to do so, use the --no-build commandline option. To re-enable it (for a specific component, for instance), use the --build option.

The documentation step is not performed by default. To enable it, use the --doc commandline option. To disable it again (for a specific component, for instance), use the --no-doc option.

For now, three different documentation tools are known and used by build-config if they are detected on the building system:

All documentation is generated in the build tree, in the share/doc directory. Subdirectories are created there for each project.

Packaging consists in copying all files of the required components in an installable directory tree, and making it ready to use. A setup program is bundled with the package. The packaging step is (of course) not performed in normal use, and is triggered via the --pack option.

The package directory is normally created in the current directory, but build-config can create it anywhere else if the --packdir option is used (for instance: --packdir /tmp.

Other options control some aspects of packaging: