INSTALL 6.94 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
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
=====================

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'

Optional:

   * 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)


1.2 Configuration
=================

In order to prepare the build process, you need to configure the source
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).

   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'.


1.2.1 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=<installation prefix>


1.2.2 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 favorite
compiler name to `configure', as follows:

     $ .../configure CXX=<your-favorite-C++-compiler>

   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="<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
==================================================

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 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.



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).


1.4 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.


1.5 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


1.6 Building
============

Once your build directory is `configure'd, you can run

     $ make

   to recursively build all selected components.


   Additionally, you can build and run the testsuite and demonstration
programs with:

     $ make check

   However, this process is very time- and memory- consuming.


1.7 Compiler notes
==================

Olena has been tested on the following configurations :

System                   Compiler
Linux                    g++ 4.0, 4.1, 4.2
MacOS X                  g++ 4.0.1


2.1 Installing
==============

To install the Olena headers and additional files on your system, run:

      $ make install

   from the build directory.

   If not overridden with `--prefix' (see the BUILD file) , this will
install:

   * the headers in `/usr/local/include/mln',

   * sample images in `/usr/local/share/milena',


   You can later remove Olena from your system by running

      $ make uninstall

   from the build directory.