This file contains information about the build process of Olena. Please read the `README' file for general information about Olena. Required software ================= Here is a non-exhaustive list of required software required to build Olena successfully. * to compile the user tools: - a POSIX shell, like Bash - a decent C++ compiler, like GNU C++ - a `make' utility, like GNU or BSD `make' * to compile the documentation: - a LaTeX distribution - the `listings' TeX package - the utility `convert' from ImageMagick - GNU Autogen - `hevea', a TeX to HTML conversion tool - the `texinfo' utilities from GNU * to develop _in_ Olena: - GNU Autotools (Autoconf 2.54, Automake 1.7) Configuration ============= In order to prepare the build process, you need to configure the source tree. Assuming your Olena distribution is uncompressed in directory `oln-0.8', follow these steps: $ mkdir ../build $ cd ../build && ../oln-0.8/configure CXXFLAGS='' *Note:* take care to set `CXXFLAGS' always when running `configure', for the default value computed by `configure' may yield to compilation issues (conflicts between optimization and debugging). The build process can be altered by a number of options you can pass to the `configure' script. The following sections describe them. Additionally, if you are an Olena maintainer (a person who runs `make distcheck'), _prefer setting `CXXFLAGS' as an environment variable_: the flags given on the commandline to `configure' are not propagated to recursive runs by `make distcheck'. Installation path ----------------- By default, Olena is installed in the standard "local" directory of your system. This is usually `/usr/local' under Unix. You can change this path with the following flag: --prefix= Compiler selection and compilation flags ---------------------------------------- By default, `configure' will try to use the first C++ compiler it encounters on your system. If `CXX' is not set, it will look, in order, for: - the value of the `CCC' environment variable, - the GNU C++ compiler (`g++'), - the `c++' or `gpp' commands on your system, - `aCC', the HP-UX standard C++ compiler, - the `CC', `cxx', `cc++' or `cl' commands on your system, - KAI's C++ compiler (`KCC'), - `RCC', `xlC_r' or `xlC'. You can override the detection system by passing your favourite compiler name to `configure', as follows: $ .../configure CXX= As an alternative, you can also set the environment variable `CXX'. For most compilers, `configure' will select debugging and minimal optimization (`-g -O2' with g++), which is wrong. You should override the default C++ flags by giving `configure' your selection of flags: $ .../configure CXXFLAGS="" This is especially useful to solve a number of problems, described in the following section. Using `CXXFLAGS' to solve compilation problems ============================================== Olena needs C99 --------------- While Olena is written in C++, it uses a number of features (math functions) from ISO C99. However most C++ compilers do not enable these features by default. If your compilation fails with (e.g.) undefined references to `roundf', but you know what flags can activate these functions, add them to `CXXFLAGS'. In case your system does not provide some math functions necessary for Olena, you can force the use of a local, overloaded, implementation, by using macros of the form `-DOLN_NEED_xxx', where `xxx' stands for the name of the missing function, in uppercase. For example, on Darwin (MacOS X), the flag `-DOLN_NEED_SQRTF' is needed (but `configure' should add it anyway). Olena needs deep template recursion ----------------------------------- The C++ design patterns used in Olena use deep template nesting and recursion. However, the C++ standard specifies that C++ compiler need only handle template recursion upto 19 levels, which is insufficient for Olena. This is a problem for GCC 2.95 and probably other compilers. Hopefully, `configure' tries to fix this automatically by adding `-ftemplate-depth-NN' when necessary, but other compilers than GCC may need other flags. If you know these flags, add them to `CXXFLAGS'. Debugging flags make Olena slow ------------------------------- Because Olena depends on C++ optimizations to provide the best performance, and enabling debugging flags often disable optimizations, you are advised to override the `CXXFLAGS_OPTIMIZE' with any options that gives the best optimization/conformance tradeoff. However, note that passing `-DNDEBUG' disable many sanity checks, while providing only a poor performance improvement. Speeding up the compilation --------------------------- When using GCC, by default separate phases of the compilation of each file are run sequentially (compilation then assembly). Using `-pipe' in `CXXFLAGS' allows GCC to fork processes and run compilation phases in parallel, which brings a compilation speedup on multiprocessor machines or machines with slow storage access (when using `-pipe', no intermediary data is saved). Speeding up the configuration process ===================================== `configure' can manage a cache of autodetected features and values. This cache speeds up `configure' runs and can be activated with the `-C' option. _NOTE_: the effects of many of the flags passed to `configure' are stored in the cache. If you decide to re-run `configure' with other flags, delete the `config.cache' file first. Optional Features ================= Using external libraries ------------------------ Several parts of Olena can make use of the Zlib compression library (in Olena I/O) and the FFTW fast Fourier transforms library (in Olena fft transforms). By default, `configure' will try to autodetect their presence. However, if your version of any of these libraries is located in a non-standard path, you should specify it as follows: --with-fftw= --with-zlib= Additionally, if for a reason or another you need to prevent Olena from using any of these libraries, you can disable their use with the following flags: --without-fftw --without-zlib Elidable components ------------------- Several build targets can be disabled, in case you are only interested in "parts" of the full Olena distribution. The elidable parts are so-called "components", and you can obtain a list of them by running: $ .../configure --help Building ======== Once your build directory is `configure'd, you can run $ make to recursively build all selected components. Additionnally, you can build and run the testsuite and demonstration programs with: $ make check However, this process is very time- and memory- consuming. It takes up to 25mn and 250-300Mb of virtual memory on a Debian GNU/Linux 2.54GHz bi-Xeon machine. You can now proceed after reading the `INSTALL' file. Compiler notes ============== Olena has been tested on the following configurations : *System* *Compiler* Linux g++ 3.0 and 3.2 Linux icc (Intel's C++ Compiler) v7 MacOS X g++ 3.1 NetBSD 1.6 g++ 3.2 Cygwin g++ 3.2 Olena used to be compatible with g++ 2.95 for performance reasons. With g++ 3.2, this constraint is becoming obsolete. Moreover, it has many annoying issues, here are the two more important ones: - g++ 2.95 rejects valid expressions, often implying ugly workarounds; - under various circumstances, optimizations sometimes generates invalid code, especially with intensive inlining. Actually Olena yet compiles with g++ 2.95, but some wrong code might be generated with data types. Compilation time may have important differences between compilers, the following benchmark gives an idea of the time needed to complete a `make check'. The tests have been run on a Bi-Xeon 2.4Ghz machine. *Compiler* *Time* g++-2.95 16m42s g++-3.0 23m20s g++-3.2 20m03s icc-7 12m52s These tests include compilation and running time, the following ones just show the runtime benchmarks for the `extrkiller' test: *Compiler* *Options* *Time* g++-2.95 `-O3 -finline-limit-1500' 3m14s g++-3.0 `-O3 -finline-limit-1500' 2m08s g++-3.2 `-O3 -finline-limit-1500' 1m50s icc-7 `-O3' 5m41s