B. Package Tools

If you are creating a software package that uses the GiNaC library, setting the correct command line options for the compiler and linker can be difficult. GiNaC includes two tools to make this process easier.

B.1 ginac-config

ginac-config is a shell script that you can use to determine the compiler and linker command line options required to compile and link a program with the GiNaC library.

ginac-config takes the following flags:

`--version'

Prints out the version of GiNaC installed.

`--cppflags'

Prints '-I' flags pointing to the installed header files.

`--libs'

Prints out the linker flags necessary to link a program against GiNaC.

`--prefix[=PREFIX]'

If PREFIX is specified, overrides the configured value of $prefix. (And of exec-prefix, unless --exec-prefix is also specified) Otherwise, prints out the configured value of $prefix.

`--exec-prefix[=PREFIX]'

If PREFIX is specified, overrides the configured value of $exec_prefix. Otherwise, prints out the configured value of $exec_prefix.

Typically, ginac-config will be used within a configure script, as described below. It, however, can also be used directly from the command line using backquotes to compile a simple program. For example:

c++ -o simple `ginac-config --cppflags` simple.cpp `ginac-config --libs`

This command line might expand to (for example):

cc -o simple -I/usr/local/include simple.cpp -L/usr/local/lib \
  -lginac -lcln -lstdc++

Not only is the form using ginac-config easier to type, it will work on any system, no matter how GiNaC was configured.

B.2 `AM_PATH_GINAC'

For packages configured using GNU automake, GiNaC also provides a macro to automate the process of checking for GiNaC.

AM_PATH_GINAC([MINIMUM-VERSION, [ACTION-IF-FOUND
              [, ACTION-IF-NOT-FOUND]]])

This macro:

• Determines the location of GiNaC using ginac-config, which is either found in the user's path, or from the environment variable GINACLIB_CONFIG.

• Tests the installed libraries to make sure that their version is later than MINIMUM-VERSION. (A default version will be used if not specified)

• If the required version was found, sets the GINACLIB_CPPFLAGS variable to the output of ginac-config --cppflags and the GINACLIB_LIBS variable to the output of ginac-config --libs, and calls `AC_SUBST()' for these variables so they can be used in generated makefiles, and then executes ACTION-IF-FOUND.

• If the required version was not found, sets GINACLIB_CPPFLAGS and GINACLIB_LIBS to empty strings, and executes ACTION-IF-NOT-FOUND.

This macro is in file `ginac.m4' which is installed in `$datadir/aclocal'. Note that if automake was installed with a different `--prefix' than GiNaC, you will either have to manually move `ginac.m4' to automake's `$datadir/aclocal', or give aclocal the `-I' option when running it.

B.2.1 Configuring a package that uses `AM_PATH_GINAC'

Simply make sure that ginac-config is in your path, and run the configure script.

Notes:

• The directory where the GiNaC libraries are installed needs to be found by your system's dynamic linker. This is generally done by

  editing `/etc/ld.so.conf' and running ldconfig

  or by

  setting the environment variable LD_LIBRARY_PATH,

  or, as a last resort,

  giving a `-R' or `-rpath' flag (depending on your linker) when running configure, for instance:   LDFLAGS=-R/home/cbauer/lib ./configure

• You can also specify a ginac-config not in your path by setting the GINACLIB_CONFIG environment variable to the name of the executable

• If you move the GiNaC package from its installed location, you will either need to modify ginac-config script manually to point to the new location or rebuild GiNaC.

Advanced note:

• configure flags

  --with-ginac-prefix=PREFIX --with-ginac-exec-prefix=PREFIX

  are provided to override the prefix and exec-prefix that were stored in the ginac-config shell script by GiNaC's configure. You are generally better off configuring GiNaC with the right path to begin with.

B.2.2 Example of a package using `AM_PATH_GINAC'

The following shows how to build a simple package using automake and the `AM_PATH_GINAC' macro. The program used here is `simple.cpp':

#include <iostream>
#include <ginac/ginac.h>

int main()
{
    GiNaC::symbol x("x");
    GiNaC::ex a = GiNaC::sin(x);
    std::cout << "Derivative of " << a 
              << " is " << a.diff(x) << std::endl;
    return 0;
}

You should first read the introductory portions of the automake Manual, if you are not already familiar with it.

Two files are needed, `configure.in', which is used to build the configure script:

dnl Process this file with autoconf to produce a configure script.
AC_INIT(simple.cpp)
AM_INIT_AUTOMAKE(simple.cpp, 1.0.0)

AC_PROG_CXX
AC_PROG_INSTALL
AC_LANG_CPLUSPLUS

AM_PATH_GINAC(0.9.0, [
  LIBS="$LIBS $GINACLIB_LIBS"
  CPPFLAGS="$CPPFLAGS $GINACLIB_CPPFLAGS"  
], AC_MSG_ERROR([need to have GiNaC installed]))

AC_OUTPUT(Makefile)

The only command in this which is not standard for automake is the `AM_PATH_GINAC' macro.

That command does the following: If a GiNaC version greater or equal than 0.7.0 is found, then it adds $GINACLIB_LIBS to $LIBS and $GINACLIB_CPPFLAGS to $CPPFLAGS. Otherwise, it dies with the error message `need to have GiNaC installed'

And the `Makefile.am', which will be used to build the Makefile.

## Process this file with automake to produce Makefile.in
bin_PROGRAMS = simple
simple_SOURCES = simple.cpp

This `Makefile.am', says that we are building a single executable, from a single source file `simple.cpp'. Since every program we are building uses GiNaC we simply added the GiNaC options to $LIBS and $CPPFLAGS, but in other circumstances, we might want to specify them on a per-program basis: for instance by adding the lines:

simple_LDADD = $(GINACLIB_LIBS)
INCLUDES = $(GINACLIB_CPPFLAGS)

to the `Makefile.am'.

To try this example out, create a new directory and add the three files above to it.

Now execute the following commands:

$ automake --add-missing
$ aclocal
$ autoconf

You now have a package that can be built in the normal fashion

$ ./configure
$ make
$ make install