Getting Started

This page gives you information on how to start with the PUMA library. It covers the following topics.

How to use the binaries

Get the binaries

Please follow the instructions on the download page to download the PUMA library binaries for Linux, Windows, or MacOSX.

The Puma namespace

The PUMA library defines namespace Puma to enclose all its classes, types, constants, and functions. Thus an application may either add

before using any PUMA classes etc., or use full qualified names, like:

Compiling and linking

An application using the PUMA library needs to be compiled and linked with the following compiler options, assuming variable $PUMA points to the root directory of the PUMA installation:

How to compile and install from source

Tools required

The following tools are required to build the library.

  • GNU make – to run the build process
  • GNU compiler collection (g++, gcc) – to compile the source files
  • GNU binutils (ar, strip) – to collect and finish the library
  • AspectC++ compiler (ac++, ag++) – to apply aspects to the source files
  • sed, perl – for some build magic
  • (optional) doxygen – to build the reference manual
Binaries for Windows are cross-compiled using MinGW.

Get the sources

Please follow the instructions on the download page to obtain a fresh copy of the PUMA library sources.
The sources are available in two variants, i.e.

Sources
The source code from the repository. You need an AspectC++ compiler to compile these sources.
Woven Sources
The aspect woven source code. No AspectC++ compiler is needed to compile these sources. This is useful especially to compile the library on platforms for which no AspectC++ compiler is available. This variant can not be compiled with others than the default set of extensions.

Compile the sources

Execute the following command from within the PUMA root directory to weave and compile the library for Linux without debugging information.

Use the following command instead to compile aspect woven sources.

Most of the build steps can run simultaneously. To speed up the build process on multiprocessor systems you can let make run multiple jobs. The following command starts 4 jobs to weave and compile the library.

Supported target platforms

The PUMA library can be built for different target platforms. The variable TARGET specifies the target platform and whether debugging mode is enabled or not. Following targets are supported.

linux Linux debug build
linux-release Linux release build (default)
macosx MacOSX debug build
macosx-release MacOSX release build
win32 Win32 debug build using mingw32
win32-release Win32 release build using mingw32

To make a Linux build of the library including debugging information invoke make like this.

Building PUMA for other target platforms may require changes on the file vars.mk in the root directory of PUMA. Additional build and compilation flags can be set using the following variables.

CPP_OPTFLAGS Target compiler flags
AC_OPTFLAGS AspectC++ compiler flags
Make targets

These are the supported make targets.

all Default target. Build the library without debugging information. Does not build the examples and the doxygen documentation.
generate Build the tools and generate parsers and configurations.
weave Generate the aspect woven library sources. Applies all active extensions.
compile Compile the aspect woven library sources.
compile_after_weave Generate the aspect woven library sources and compile them.
install Install the library.
uninstall Uninstall the library.
examples Build the examples.
examples-clean Remove temporary build files from the examples.
doc Generate the PUMA library reference manual.
docs-clean Remove the generated PUMA library reference manual files.
dry Do nothing but showing the weaver, compiler, and linker options used to build the library.
clean Remove generated and temporary build files. Does not clean the tools and examples.
cleanall Same as clean but also cleans the tools and examples.
libclean Remove the temporary build files. Does not remove generated/woven files.
distclean Same as cleanall.
tools Build the tools in the tools directory.
tools-clean Remove temporary build files from the tools directory.
test Run the tests in the tests directory.
test-clean Remove temporary test result files from the tests directory.
Extensions

The PUMA library can be built with some extensions. These extensions are defined in the file extensions.mk in the PUMA root directory.

gnuext GNU C/C++ language extensions (default)
winext VisualC++ language extensions (default)
cc1xext VisualC++ language extensions (default)
acppext AspectC++ language extensions (default)
tracing Syntax rule tracing
profiling Profiling information
matchexpr AST match expressions

Extensions are enabled by setting variable EXTENSIONS.

This command builds the library including GNU C/C++ language extensions and tracing code. Other extensions are disabled.

Install the binaries

After the library was successfully built it can be installed to /usr/local as follows.

If you like to change the install location for the library, just set variable PREFIX accordingly. Here is an example for installing the library below the user’s home directory.