Main Page | Related Pages

# Usage

When invoked, `acgmake` recursively traverses a whole subtree of dirctories, starting at the current one. Each directory containing an `ACGMakefile` will be processed.

`acgmake` assumes that the current directory is part of a larger source code tree and tries to find the top-level directory of that project by going up the hierarchy until a file `ACGMakefile.proj` is found. If this file is found it will be included, so you can place additional project-specific configuration there. Additionally the include and library paths is extended by the parent directory of the project directory. E.g. if you have a directory structure like this

    projects/
    |-- proj_1
    |   |-- ACGMakefile
    |   |-- ACGMakefile.proj
    |   |-- code
    ....
    |-- proj_2
    |   |-- ACGMakefile
    |   |-- ACGMakefile.proj
    |   |-- code
    ...

and you call `acgmake` from the `projects/proj_1/code/` directory, `acgmake` will find `projects/proj_1/` as the project top-level directory and add `projects/` to your include and lib paths. This means you can include files like

    #include <proj_1/some_dir/some_file.hh>
    #include <proj_2/some_other_dir/some_other_file.hh>

and use code/libs from other directories like explained below.

Attention:
  This nice functionality requires that you place a (possibly empty) file named `ACGMakefile.proj` in the top-level directory of your projects.

The make-files named `ACGMakefile` control what to do for these directories (e.g. what modules to apply, see List of Modules), the command line options tell `acgmake` how to do it. E.g., the module `cxx` used for `C++` code generation will build a library from all the `*`.cc files for each directory, files containing a `main()` function will be detected, compiled, and linked to applications.

Usually you call `acgmake` with a list of options and a list of targets. The options controll the code compilation process as well as the linking behaviour. The targets tell `acgmake` what to do, the options tell how to do it.

The options controlling the `C` / `C++` code compilation are:

- `-dbg`: Compile w/o optimization and generate debug information (default).
- `-prf`: Compile w/o optimization and generate profiling information.
- `-opt`: Turn off debugging, turn on optimization.
- `-max`: Use maximum available optimization.
- `-comp=`

: Use a specific compiler. Causes the file `/ACG/acgdev/acgmake/configs/config`. to be included. You can specify compiler specific settings there.

The type of library/executable generation can be set by:

- `-shared`: Build and use a shared library for each processed directory (default).
- `-static`: Build and use a static library for each processed directory. The system libs will still be linked shared.
- `-allstatic`: Like `-static`, but now system libs are also linked statically, i.e. a completely static bindary is build.

Output options:

- `-debug`: Since version 1.1, acgmake hides the command lines it triggers. You can show these lines using the `debug` option.

Other options:

- `-j`: This will cause make to run several compilation jobs at once.
- `-j`

: This will cause make to run <n> compilation jobs at once.

- `-dist`: Distributed compiling using distcc, implies `-j`.
- `-relink`: Forces the relinking of executables, even if dependencies will not require it. This is usefull when linking static libraries, since they are not dealt with by dependencies.

Supported targets are:

- `build:` Recursively do the work for all directories containing an `ACGMakefile`.
- `local-build`: Same as `build`, but only for the current directory.
- `clean:` Recursively clean up everything created by `acgmake`.
- `local-clean`: Same as above, only for the current directory.
- `sysinfo:` Print some system information.

In each directory tp be processed `acgmake` will look for a file named `ACGMakefile`. The syntax will be plain GNU make syntax. A typical makefile looks like this.

    #==  SYSTEM PART -- DON'T TOUCH  ==============================================
    include $(ACGMAKE)/Config
    #==============================================================================

    SUBDIRS = $(call find-subdirs)

    PACKAGES := qt glut opengl x11 math

    PROJ_LIBS = OpenMesh ACG/Scenegraph

    MODULES := uic moc cxx

    #==  SYSTEM PART -- DON'T TOUCH  ==============================================
    include $(ACGMAKE)/Rules
    #==============================================================================

As you see you have to specify only four parameters:

- `SUBDIRS` specifies in what sub-directories to proceed. May be a space-separated list of directories or (the default) value `$(call find-subdirs)`. This function call returns all sub-directories containing a `Makefile`.

- `PACKAGES` tells `acgmake` what 3rd party libraries you want to use for compiling the current directory. In the above example we need OpenGL, the GL utility library `glut`, Trolltech's Qt and some functions from the math library.

- `PROJ_LIBS:` As `acgmake` recursively traverses your source tree it creates a (shared or static) library for each directory. You can use these libraries in the current directory by naming the corresponding directories (relative to the top-level directory). In the example we want to use the `OpenMesh` library and the `Scenegraph` library of the ACG project.

- `MODULES:` This space-separated list specifies what modules to use for the actual compilation. These modules will be applied in the order they are given. In the example the Qt tool `uic` generates C++ header and implementation files from Qt designer files first, the Qt preprocessor `moc` is applied in the second step. After that the `cxx` modules does the C++ compilation.

Attention:
  For the variables PACKAGES, PROJ_LIBS and MODULES the order is important. While the order in wich modules are to apply is quite obvious, a wring order of packages and libraries can lead to undefined symbols during linking. If one package/library depends on one another, the other should be given later in the string, like "glut opengl" instead of "opengl glut". This may only lead to errors when you compile static libs using the `-static` command line option.

In addition any internal (module specific) variables can be overridden. For example if you have specific options for a certain compiler or operating system, you could do something like this:

    ifeq ($(CXX_COMP),g++)
      CXX_DEFS += -ftemplate-depth-100
    endif

    ifeq ($(OS),Linux)
      Some Linux specific stuff
    endif