* INSTALL: Remove this file and move its contents... * README: ...here, and... * HACKING: ...here (new file). --- ChangeLog | 8 ++ HACKING | 95 ++++++++++++++++++++++++++ INSTALL | 216 ----------------------------------------------------------- README | 223 +++++++++++++++++++++++++++++++++++++++++++++++++++++++------ 4 files changed, 305 insertions(+), 237 deletions(-) create mode 100644 HACKING delete mode 100644 INSTALL diff --git a/ChangeLog b/ChangeLog index 826eb19..e9622e6 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,13 @@ 2010-03-22 Roland Levillain <roland@lrde.epita.fr> + Move INSTALL's contents to README and HACKING. + + * INSTALL: Remove this file and move its contents... + * README: ...here, and... + * HACKING: ...here (new file). + +2010-03-22 Roland Levillain <roland@lrde.epita.fr> + Remove useless regen actions from bootstrap. * bootstrap (gen_doc_figures): Remove this function, and its uses diff --git a/HACKING b/HACKING new file mode 100644 index 0000000..de4e4a1 --- /dev/null +++ b/HACKING @@ -0,0 +1,95 @@ +Copyright (C) 2009, 2010 EPITA Research and Development Laboratory (LRDE) + +This file is part of Olena. + +Olena is free software: you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free +Software Foundation, version 2 of the License. + +Olena is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with Olena. If not, see <http://www.gnu.org/licenses/>. + +The complete GNU General Public License Notice can also be found in +the 'COPYING' file in the root directory. + + +================= +Developer's Guide +================= + +This file gathers some useful information for Olena developers and +contributors. + + +------------- +Bootstrapping +------------- + +If you are fetching Olena from its Git repository, you will need to +run `bootstrap' to build files that are not recorded in the +repository:: + + ./bootstrap + +By default, `bootstrap' does not regenerate files that are stored on +the repository. If you want to refresh them (e.g., because your +working copy is in a bad state), you can ask boostrap to regenerate +them:: + + ./bootstrap --regen + +On a configured tree, you can also use Make to perform the same task:: + + make regen + + +----------------- +Required Software +----------------- + +In addition to the required packages listed in README, you may need +the following extra programs if you want to work on the Olena project. + + * If you want to make changes anywhere within the project, you will + need: + + - GNU Autoconf 2.61 + + - GNU Automake 1.10 + + - GNU Libtool 1.5.22 + + * If you plan to make changes within Swilena, you must have: + + - SWIG 1.3.36 + + - Python 2.5 + + * If you want to change and/or rebuild the documentation, the + following tools are required: + + - Doxygen 1.5.6 + + - a fairly recent LaTeX distribution + + - the `listings' LaTeX package + + - the `convert' utility from ImageMagick + + - TeX4ht, to compile the LaTeX documentation into HTML + + - dvipng (required by TeX4ht) + + +Note that `bootstrap' checks for the presence of most of these tools. + + + +.. Local Variables: +.. mode: rst +.. End: diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 39196d9..0000000 --- a/INSTALL +++ /dev/null @@ -1,216 +0,0 @@ -================== -Installation Notes -================== - - -This file contains information about the installation process of Olena. - - You can 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 examples: - - - a POSIX shell, like Bash - - - a decent C++ compiler, like GNU C++ - - - a `make' utility, like GNU `make' - -Optional: - - * to (re)compile the documentation: - - - a LaTeX distribution - - - the `listings' TeX package - - - the utility `convert' from ImageMagick - - - `hevea', a TeX to HTML conversion tool - - - latex2html - - * to use various image types: - - - Magick++ - - - libtiff - - - GDCM - - * to develop _within_ Olena: - - - GNU Autoconf 2.61 - - - 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. - - Assuming your Olena distribution is uncompressed in directory -`olena-1.0', follow these steps: - - % 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 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). - - -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> - - -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 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: - - % ../configure CXXFLAGS="<your-favorite-flags>" - - -Additional Components -===================== - -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 --help - -Olena ships with Trimesh, a third-party library that we have been -using to manipulate 3D meshes. Eventually, we will drop Trimesh from -the distribution. - -See README for more information on additional components. - - -Building -======== - -Once your build directory is `configure'd, you can run - - % make - -to recursively build all the selected components. - - - Additionally, you can build and run the test suite with: - - % make check - -However, this process is time- and memory- consuming, and you probably -do not need it except if you are developing/debugging Olena. - - -Compiler Notes -============== - -Olena has been tested on the following configurations: - -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 - - -Installing -========== - -To install the Olena headers and additional files on your system, run: - - % make install - -from the build directory. - - If not overridden with `--prefix', this will install: - - * the headers in `/usr/local/include/mln/', - - * some applications and tools in `/usr/local/bin/', - - * sample images and meshes in `/usr/local/share/olena/images/', - - * the documentation in `/usr/local/share/doc/olena/` - -And optionally: - - * Swilena's Python bindings in `/usr/local/lib/python2.x/site-packages/', - - * Trimesh programs in `/usr/local/bin/', - - * Trimesh libraries in `/usr/local/lib/', - - * Trimesh headers in `/usr/local/share/trimesh/', - - - You can later remove Olena from your system by running - - % 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. diff --git a/README b/README index 41c65cc..cf35e0a 100644 --- a/README +++ b/README @@ -1,4 +1,5 @@ -Copyright (C) 2009 EPITA Research and Development Laboratory (LRDE) +Copyright (C) 2008, 2009, 2010 EPITA Research and Development +Laboratory (LRDE) This file is part of Olena. @@ -27,8 +28,9 @@ Olena_, a platform dedicated to image processing. .. _Olena: http://olena.lrde.epita.fr +-------- Overview -======== +-------- Olena is a platform dedicated to image processing. At the moment it is mainly composed of a C++ library: Milena. This library features many @@ -68,15 +70,46 @@ code or e-mail us. <http://olena.lrde.epita.fr>. -Installation -============ +----------------- +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 `make' + +Optional: + + * to use various image types: + + - Magick++ -To install Olena on your system, create a `build' directory (even + - libtiff + + - GDCM + + +================== +Quick Start Manual +================== + +This section summarizes the installation procedure. For more +information about building and installing Olena, see the next +sections. + +To install Olena on your system, create a `_build' directory (even though it is not mandatory) and type in the classical sequence at the command prompt:: - mkdir build - cd build + mkdir _build + cd _build ../configure make make install (as root) @@ -94,12 +127,94 @@ Between ``make`` and ``make install``, you may also want to run:: Running the test suite may require up several hours. -Please read the INSTALL file for more information about building and -installing Olena. +===================== +Detailed Instructions +===================== + +------------- +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: + + % 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 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). + + +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> + + +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 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: -Additional Features -------------------- + % ../configure CXXFLAGS="<your-favorite-flags>" + + +Additional Components +===================== + +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 --help + +Swilena +------- Swilena is an optional component of Olena exposing Milena to other languages thanks to the Simplified Wrapper and Interface Generator @@ -117,22 +232,32 @@ To enable the installation of this module use:: ./configure --enable-swilena +Tools +----- + Sample tools are shipped with the tarball. To enable the installation of these tools use:: ./configure --enable-tools +Applications +------------ Sample applications are shipped with the tarball. To enable the installation of these applications use:: ./configure --enable-apps -Olena ships with Trimesh, a third-party library that we have been -using to manipulate 3D meshes. Eventually, we will drop Trimesh from -the distribution. To enable it, use:: +Trimesh +------- + +Trimesh, a third-party library that we have been using to manipulate +3D meshes, is shipped with Olena. (We will probably drop Trimesh from +the distribution someday.) To enable it, use:: ./configure --enable-trimesh +Input/output libraries +---------------------- To read/write TIFF images with Olena, libtiff is required. If ``configure`` is unable to find libtiff on your system, you can help @@ -140,7 +265,6 @@ it by specifying the base directory of libtiff, e.g.:: ./configure --with-tiff=/usr/local - To read/write DICOM images with Olena, GDCM is required. Likewise, you can tell ``configure`` where to find it by giving its install prefix, e.g.:: @@ -154,8 +278,67 @@ needed) at configuration time:: ./configure --with-magickxx=/usr/local/ +-------- +Building +-------- + +Once your build directory is `configure'd, you can run + + % make + +to recursively build all the selected components. + + + Additionally, you can build and run the test suite with: + + % make check + +However, this process is time- and memory- consuming, and you probably +do not need it except if you are developing/debugging Olena. + + +---------- +Installing +---------- + +To install the Olena headers and additional files on your system, run: + + % make install + +from the build directory. + + If not overridden with `--prefix', this will install: + + * the headers in `/usr/local/include/mln/', + + * some applications and tools in `/usr/local/bin/', + + * sample images and meshes in `/usr/local/share/olena/images/', + + * the documentation in `/usr/local/share/doc/olena/` + +And optionally: + + * Swilena's Python bindings in `/usr/local/lib/python2.x/site-packages/', + + * Trimesh programs in `/usr/local/bin/', + + * Trimesh libraries in `/usr/local/lib/', + + * Trimesh headers in `/usr/local/share/trimesh/', + + + You can later remove Olena from your system by running + + % 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. + +===================== Layout of the Tarball ---------------------- +===================== The Olena project directory layout is as follows: @@ -166,7 +349,6 @@ build-aux external Sources of Shipped dependencies. - m4 Extra Autoconf macros. @@ -196,16 +378,15 @@ milena demos Demos of Milena. - swilena - python Some Python bindings for Milena. -Requirements -============ +=================== +Supported Platforms +=================== Olena has been tested on the following configurations: -- 1.5.6.5