Building and Installing Bear

How is the source code packaged?

The source code for Bear is distributed as a GNU autotools package. This means that the source code is collected in a tar archive along with a configuration script that examines your system in order to find header files, libraries, and values for parameters of the build process. The configuration script is actually a very long shell script created by GNU Autoconf from a description of what is needed to build Bear.

General References

If you are new to building and installing software from source code, you may find it helpful to refer to a general guide that explains the steps in detail along with some background on the process.

The following resources discuss building software from autotools source packages on GNU/Linux, but most of the advice applies to other POSIX operating systems.

• INSTALL, the GNU Autotools generic install instructions, which are also contained in Chapter 13 of the GNU Autoconf Manual. A good starting point, this file should be included with all autotools packages (e.g. Bear).
• configure; make; make install by Willy Smith from the archives of the Linux Gazette. A quick overview of the build process and why the various steps are necessary.
• Learning the GNU development tools, a tutorial aimed at software developers who want to build and package their software with the GNU autotools. This long tutorial covers the details from a programmer's perspective.
• The GNU Autoconf Manual and GNU Automake Manual; these definitive references are intended for software developers.

Supported Environment

Bear is written in C (with an optional component in FORTRAN 77) and developed on GNU/Linux using gcc and the GNU autotools (autoconf and automake). While it is designed to be portable, Bear is more likely to compile and install perfectly in an environment similar to this one.

Bear should build and run successfully in any POSIX-like environment (unix, GNU/Linux, etc.); it is known to build on several GNU/Linux distributions, Mac OS X 10.2 (and probably other OS X releases), FreeBSD 4.8, and Solaris.

Required Libraries and Utilities

Before you can build Bear from the source distribution, you will need two libraries that may or may not be installed on your system by default:

• GSL, the GNU Scientific Library (tested with versions 1.4 and higher). This is used for many of the basical mathematical operations in Bear, such as complex number arithmetic, matrix and vector manipulation, ODE solving, spline interpolation, etc.
• HDF5, the Hierarchical Data Format 5 (tested with versions 1.4.2 and higher). This is a portable binary format for the interchange of structured scientific data. The output files produced by Bear are in HDF5 format.

In each case you can download a source package from the library home page and build it according to the included instructions. The basic requirements for building these libraries are very mild, and it should be possible to build and install them on any POSIX-like platform supporting shared libraries. In the best situation, you need only unpack the source, run 'configure', then 'make', and 'make install'.

If you plan to use Bear, it is a good idea to also build and install Stephen Johnson's h5utils package, which includes a number of utilities for manipulating HDF5 data files. The h5topng command is especially useful, as it can produce Bers slice images from Bear output files.

Unpacking and Configuring

Once you have the necessary libraries, you should unpack the Bear source distribution (which can be downloaded from the Sourceforge project page). For example, if you are building version 0.9.6, you might use a command like:

tar --gzip -xvf bear-0.9.6.tar.gz

This will unpack the source files into a subdirectory, which in this case is called bear-0.9.6. To configure the Bear build process, change to this directory and run

./configure

or a variant of this command with options appropriate for your situation; detailed instructions for running configure can be found in the file 'INSTALL', which is included in the source distribution. The most common configuration option is probably '--prefix', which indicates where Bear should eventually be installed on your system. If you are working on a multi-user system where you can execute commands as the root user, '/usr/local' may be a good choice. The associated configure command would then be:

./configure --prefix=/usr/local

If you do not have root access or only want to install Bear in your own account, you can set the prefix to your home directory, which is usally accomplished by:

./configure --prefix=~

Assuming the configuration suceeds (if it does not, see Common Problems below), you can compile Bear by running make:

make

The build process can take anywhere from a few seconds to a few minutes, and will produce a lot of output. If the build succeeds (i.e. does not stop because of an error), you can then install Bear with

make install

which will copy a number of files created during the build process, including the Bear executable, to subdirectories of the installation prefix (e.g. '/usr/local' in the example above). If you are not the root user, you may not have access to '/usr/local'. Thus, if you want to install Bear in this directory you may need to execute 'make install' as root.

If you have the h5utils package (see Required Libraries and Utilities above), you may also want to run the experimental test suite included with Bear using the command:

make check

This will run a couple of small Bers slice calculations, store the output, and compare it to reference data. If any significant differences are discovered, the test 'fails', though this may or may not indicate a serious problem.

Common Problems

This section covers a few common problems that occur while running 'configure' or 'make' and what to do about them.

When configure fails, it usually produces an error message describing the problem. This is supposed to be enough to determine an appropriate corrective action, but in case it is not, a more detailed log of what happened can be found in the file config.log. This file contains the concatenated output of every command configure (which is itself a very long shell script) runs.

One of the libraries GSL or HDF5 cannot be found

The library may be missing, or it may be installed in a place where configure cannot find it.

If it is missing, you need to install the library and associated header files, either by building it from source or by installing binary packages created for your operating system. (See Installing Bear from a binary package for information on how to install the required libraries for some popular Linux distributions.)

If the library is installed in a place where configure cannot find it, then you may be able to resolve the problem by setting environment variables that configure and the C compiler use when looking for libraries and include files. For example, suppose that GSL is the missing library. We should first locate the GSL shared library files:

locate '*libgsl.*so*'

/usr/local/gsl-1.4/lib/libgsl.so
/usr/local/gsl-1.4/lib/libgsl.so.0
/usr/local/gsl-1.4/lib/libgsl.so.0.7.0

Thus it seems the shared library files for GSL are located in /usr/local/gsl-1.4/lib, a non-standard location that configure could not find. When a library is in a non-standard place, it is likely that the header files are also there, so we should look for those as well. In this case, we look for the GSL header file gsl_math.h:

locate 'gsl_math.h'

/usr/local/gsl-1.4/include/gsl/gsl_math.h

So the header files for GSL appear to be in /usr/local/gsl-1.4/include/gsl; however, GSL headers are expected to be in a subdirectory of an include directory called gsl, so the include directory is just /usr/local/gsl-1.4/include.

To advise configure of these locations, we set the enviroment variables CPPFLAGS (which stands for C preprocessor flags) and LDFLAGS (which tells the dynamic library loader ld where to find things). Using a Bourne-compatible shell (e.g. bash), this can be accomplished as follows:

CPPFLAGS="$CPPFLAGS -I/usr/local/gsl-1.4/include"
LDFLAGS="$LDFLAGS -L/usr/local/gsl-1.4/lib"
./configure

These commands should be executed in the root directory of the Bear source code. The settings above use the directories from our example, but the general scheme is: Note that we include $LDFLAGS in the value of LDFLAGS so that the command adds flags rather than replacing any existing ones. If you need to add several new library directories, the syntax is: And similarly for CPPFLAGS.

Configure or make exits with an error related to the FORTRAN compiler

This should not happen unless you manually enable the LSODE solver (the only part of Bear that uses a FORTRAN compiler) by passing the --enable-lsode option to configure. Since this part of the code is experimental, and portably mixing C and FORTRAN is difficult, you should simply omit this option. For good measure, you can add --disable-lsode which will disable the FORTRAN components even if they are enabled by default at some time in the future.

Running 'make install' results in many 'permission denied' errors

Usually this happens becuase you are attempting to install Bear into a directory in which a normal user cannot create files. You may need to become the superuser (root) to write to this directory, perhaps using the following sequence of commands:

su

Password:

make install
exit

However, if you are not a system administrator on the computer where you want to install Bear, it is better to choose an install directory within your home directory. To do this, add --prefix=~ as an option to configure. After this, you should repeat the 'make', 'make install' sequence.