Preface

Author: $Author: paul $
Version: $Revision: 2373 $
Location: $URL: svn+ssh://[email protected]/home/svn/repo/campcaster/trunk/campcaster/doc/developmentEnvironment/buildEnvironment.html $

Scope

This document describes the build environment for components of the Campcaster project.

Introduction

As seen in the directory structure description, each component is contained in its own directory, and has the same general directory layout, which includes a configure script on the top of the directory. This script is responsible for gathering compilation and installation information, and for creating a Makefile in the top directory. All components are built by using GNU make working on that Makefile.

This document describes details about the configure script, the targets for the generated Makefile, and related files involved with the installation of the component.

Parts of this document are inspired by the GNU Coding Standards Makefile Conventions Standard targets.

The `configure` script and generated files

`configure` options

The configure script should honor the generic directory settings passed to it:

Installation directories:
  --prefix=PREFIX         install architecture-independent files in PREFIX
                          [/usr/local]
  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
                          [PREFIX]

Fine tuning of the installation directories:
  --bindir=DIR           user executables [EPREFIX/bin]
  --sbindir=DIR          system admin executables [EPREFIX/sbin]
  --libexecdir=DIR       program executables [EPREFIX/libexec]
  --datadir=DIR          read-only architecture-independent data [PREFIX/share]
  --sysconfdir=DIR       read-only single-machine data [PREFIX/etc]
  --sharedstatedir=DIR   modifiable architecture-independent data [PREFIX/com]
  --localstatedir=DIR    modifiable single-machine data [PREFIX/var]
  --libdir=DIR           object code libraries [EPREFIX/lib]
  --includedir=DIR       C header files [PREFIX/include]
  --oldincludedir=DIR    C header files for non-gcc [/usr/include]
  --infodir=DIR          info documentation [PREFIX/info]
  --mandir=DIR           man documentation [PREFIX/man]

Other configuration-time options should be processed using --with-XXX arguments, using the AC_ARG_WITH autoconf macro.

Note: when writing etc/configure.ac, the input for the configure script, the Autoconf Macro Archive can provide quite useful.

generated files

The main file generated by the configure script will the the Makefile. The input for the Makefile, etc/Makefile.in, can refer to the variables substituted by configure in the following way:

prefix = @prefix@
some_other_var = @some_other_var@

Because these variables might need to be overwritten when running the Makefile, make sure to use the same name for the variable inside the Makefile as was used by the configure script (as in the above example). For example:

# these are wrong!
PREFIX = @prefix@
myvar = @some_other_var@

# these are correct, and have the same desired effect:
prefix = @prefix@
some_other_var = @some_other_var@
PREFIX = ${prefix}
myvar = ${some_other_var}

Using the same names will make it possible to overwrite the values substituted by configure when invoking the Makefile, for example:

make prefix=/foo/bar install

will cause installation under the prefix /foo/bar, irrespective of the prefix supplied to configure.

Make targets

The following make targets are required for all components to support:

all
clean
depclean
doc
dist
check
install

all

Compile all source files for this component. As a result, the component is ready to be run (if an executable) or linked to (if a library).
This target traverses the dependent modules, and executes the all target on them, if their targets do not exist.

clean

Delete all files generated by the all target, but only for this module (e..g. no files for dependent modules are deleted).

depclean

Delete all the dependent target files. Executing the depclean target with an all target afterwards results in a full recompilation of all the dependent modules.

doc

Generate the documentation for this component. This would include processing info pages, or using tools to generate documentation based on comments in the source code (like javadoc).

dist

Create a distribution package for this component. This involves possibly compiling, document generation and other tasks, and results in an archive containing the distribution.

check

Run all tests, especially unit tests, for the component. This usually results in a generated test-report.

install

Installs the component into the specified prefix. (See the Installation document for details.)