---
ChangeLog | 4 +
INSTALL | 225 ++++++++++++++++++++++++-------------------------------------
2 files changed, 92 insertions(+), 137 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 8ff4133..8ebe907 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
2009-07-13 Roland Levillain <roland(a)lrde.epita.fr>
+ * INSTALL: Update.
+
+2009-07-13 Roland Levillain <roland(a)lrde.epita.fr>
+
* README: Update.
2009-07-13 Guillaume Lazzara <lazzara(a)lrde.epita.fr>
diff --git a/INSTALL b/INSTALL
index 946675f..3b62c89 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,53 +1,66 @@
+==================
+Installation Notes
+==================
+
+
This file contains information about the installation process of Olena.
You can read the `README' file for general information about Olena.
-1.1 Required software
-=====================
+
+Required Software
+=================
Here is a non-exhaustive list of required software required to build
Olena successfully.
* to compile the user examples:
+
- a POSIX shell, like Bash
- a decent C++ compiler, like GNU C++
- - a `make' utility, like GNU or BSD `make'
+ - a `make' utility, like GNU `make'
Optional:
- * to compile the documentation:
+ * to (re)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
-
- - latex2html
+ - latex2html
* to use various image types:
- - libMagick++
- - libTiff
+ - Magick++
- - libGdcm
+ - libtiff
- * to develop _in_ Olena:
- - GNU Autotools (Autoconf 2.54, Automake 1.7)
+ - GDCM
- * to develop _in_ Swilena (Python Bindings):
- - Swig
+ * to develop _within_ Olena:
+ - GNU Autoconf 2.61
-1.2 Configuration
-=================
+ - GNU Automake 1.10
+
+ - GNU Libtool 1.5.22
+
+ * to develop _within_ Swilena:
+
+ - SWIG
+
+ - Python
+
+
+Configuration
+=============
In order to prepare the build process, you need to configure the source
tree.
@@ -55,24 +68,24 @@ tree.
Assuming your Olena distribution is uncompressed in directory
`olena-1.0', follow these steps:
- $ mkdir ../build
- $ cd ../build && ../olena-1.0/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).
+ % cd olena-1.0
+ % mkdir _build
+ % cd _build
+ % ../configure
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'.
+variable_: the flags given on the command line to `configure' are not
+propagated to recursive runs by `make distcheck'. Or better: use the
+environment CONFIG_SITE to set up a configuration environment (see
+Autoconf's manual).
-1.2.1 Installation path
------------------------
+Installation Path
+-----------------
By default, Olena is installed in the standard "local" directory of
your system. This is usually `/usr/local' under Unix.
@@ -82,8 +95,8 @@ your system. This is usually `/usr/local' under Unix.
--prefix=<installation prefix>
-1.2.2 Compiler selection and compilation flags
-----------------------------------------------
+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,
@@ -106,151 +119,89 @@ for:
You can override the detection system by passing your favorite
compiler name to `configure', as follows:
- $ .../configure CXX=<your-favorite-C++-compiler>
+ % ../configure CXX=<your-favorite-C++-compiler>
As an alternative, you can also set the environment variable `CXX'.
+ For some compilers (GNU g++ and Intel's icpc to some extent) ,
+`configure' will use default CXXFLAGS. You can override the default
+C++ flags by giving `configure' your selection of flags:
- 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="<your-favorite-flags>"
-
- This is especially useful to solve a number of problems, described
-in the following section.
-
-
-1.3 Using `CXXFLAGS' to solve compilation problems
-==================================================
+ % ../configure CXXFLAGS="<your-favorite-flags>"
-1.3.1 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).
-
-
-1.3.2 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 up to 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'.
-
-
-1.3.3 Debugging flags
----------------------
-
-All over the code, many sanity checks are enabled by default. They are
-convenient since they make sure nothing wrong is passed to the functions.
-However, once the program is stable they may not be necessary anymore.
-Passing `-DNDEBUG' to the CXXFLAGS disable many sanity checks, while providing
-*high* performance improvement.
-
-
-
-1.3.4 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).
+Additional Components
+=====================
-1.4 Speeding up the configuration process
-=========================================
+In additional to Milena, several build targets can be enabled. These
+parts are called "components", and you can obtain a list of them by
+running:
-`configure' can manage a cache of autodetected features and values.
-This cache speeds up `configure' runs and can be activated with the
-`-C' option.
+ % ../configure --help
- _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.
+See README for more information on additional components.
-1.5 Elidable components
-=======================
+Building
+========
-Several build targets can be disabled, in case you are only interested
-in "parts" of the full Olena distribution.
+Once your build directory is `configure'd, you can run
- The elidable parts are so-called "components", and you can obtain a
-list of them by running:
+ % make
- $ .../configure --help
+to recursively build all the selected components.
-1.6 Building
-============
+ Additionally, you can build and run the test suite with:
-Once your build directory is `configure'd, you can run
+ % make check
- $ make
+However, this process is time- and memory- consuming, and you probably
+do not need it except if you are developing/debugging Olena.
- to recursively build all selected components.
+Compiler Notes
+==============
- Additionally, you can build and run the testsuite and demonstration
-programs with:
+Olena has been tested on the following configurations:
- $ make check
+System Compiler
+GNU/Linux on IA-32 g++ (GNU GCC) 3.3, 3.4, 4.0, 4.1, 4.2 and 4.3
+GNU/Linux on IA-32 icpc (Intel C/C++ Compiler) 10.1 and 11.0
+GNU/Linux on AMD64/Intel 64 g++ (GNU GCC) 4.1
+Mac OS X (10.5) on IA-32 g++ (GNU GCC) 4.0.1
- However, this process is very time- and memory- consuming.
+Installing
+==========
-1.7 Compiler notes
-==================
+To install the Olena headers and additional files on your system, run:
-Olena has been tested on the following configurations :
+ % make install
-System Compiler
-Linux g++ 3.3, 3.4, 4.0, 4.1, 4.2
- icc 10.1, 11.0
-Linux-64 g++ 4.1
-MacOS X g++ 4.0.1
+from the build directory.
+ If not overridden with `--prefix', this will install:
-2.1 Installing
-==============
+ * the headers in `/usr/local/include/mln/',
-To install the Olena headers and additional files on your system, run:
+ * some applications and tools in `/usr/local/bin/',
- $ make install
+ * sample images and meshes in `/usr/local/share/olena/images/',
- from the build directory.
+ * the documentation in `/usr/local/share/doc/olena/`
- If not overridden with `--prefix' (see the BUILD file) , this will
-install:
+And optionally:
- * the headers in `/usr/local/include/mln',
+ * Swilena's Python bindings in `/usr/local/lib/python2.x/site-packages/',
- * sample images in `/usr/local/share/milena',
You can later remove Olena from your system by running
- $ make uninstall
-
- from the build directory.
+ % make uninstall
+from the build directory (if you have kept it). We recommend the use
+of GNU Stow (or any similar program) during the installation of Olena,
+to make the uninstallation of Olena easier.
--
1.6.3.1
