Instructions for: Linux, Windows or Mac OS
IDE instructions: Eclipse
Speeding up code using external libraries(SSE, IPP, OpenMP): Optimizations

1. Sources via SVN:

   svn co svn://svn.code.sf.net/p/eblearn/code/trunk/ eblearn

2. Binaries: Not yet available.
3. Sources package eblearn_1.2_r2631-src.zip
4. Old Sources packages(1.1): eblearn-1.1-r2350.zip
5. Old Sources packages(1.0): eblearn-1.0-v1860.tgz

1. sudo apt-get install subversion cmake g++ imagemagick

2. cd eblearn/core && make && sudo make install

1. sudo apt-get install subversion cmake g++ libatlas-base-dev libboost-filesystem-dev imagemagick libboost-regex-dev libqt4-core libqt4-dev libqt4-gui libcppunit-dev libxml++2.6-dev doxygen mplayer mencoder

2. cd eblearn/tools && make && sudo make install

3. make test

1. Unit testing:

   ./bin/tester

   Or

   make test

2. Face detection demo:

   ./bin/detect tools/data/face/best.conf

The MNIST handwritten digit database is used by the tester to unit-test the learning algorithms.
The tester offers an automatic download of MNIST (you can also download it manually here. Note: when decompressing the MNIST archives, it happens that a dash is replaced by a point by the extractor. Symply rename the extracted file to its original name, e.g.: 't10k-images.idx3-ubyte' should be 't10k-images-idx3-ubyte').

1. Libraries only:

   make libs

2. All projects in release mode:

   make release

3. All projects in debug mode:

   make debug

4. Specific project(s) in release mode, e.g. train or metarun and metaparse:

   make train

   or

   make metarun metaparse

5. Specific project(s) in debug mode, (append the project name with _debug) e.g. detect:

   make detect_debug

6. To compile the tester and run it:

   make test

7. To exclude some components such as QT or OpenCV from being used, export the following shell variables with 0 or 1: NOBOOST, NOOPENCV, NOXML, NOQT, NOIPP, NOCBLAS. For example to compile without OpenCV:

   make NOOPENCV=1 NOQT=1

   or

   export NOOPENCV=1 && make

8. To add extra flags to the compilation, export the EBLFLAGS variable. For example, to dump the states of each layer, add the __DUMP_STATES__ flag as follow:

   export EBLFLAGS="-D__DUMP_STATES__" && make

1. Use ccache to speed up compilation:

   sudo apt-get install ccache

2. To enable the use of ccache, modify your PATH variable by putting /usr/lib/ccache in front of it, e.g.

   export PATH=/usr/lib/ccache:$PATH

3. To verify if ccache is actually used, you should see an output similar to – Compiler: /usr/lib/ccache/c++

1. To install libraries and headers on your system:

   sudo make install

2. To install libraries and headers in a specific directory:

   make install DIR="your-install-dir"

   or

   export DIR="your-install-dir" && make install

1. Core libraries only, i.e. libeblearn and libidx (tools, testers and some demos may not compile):

   sudo apt-get install cmake g++ libatlas-base-dev imagemagick

2. Tools, demos and tester:

   sudo apt-get install libboost-filesystem-dev libboost-regex-dev libqt4-core libqt4-dev libqt4-gui libcppunit-dev libxml++2.6-dev mplayer mencoder

3. Developers only (tools for bug-free development):

   sudo apt-get install valgrind electric-fence doxygen

1. When installing an external dependency manually, it may be detected automatically by the existing CMake “find” scripts or not.

If not, one can edit the scripts/FindCustom.cmake script which is called by FindAll.cmake. This script is called after every other script, thus can override other dependencies if other non-desired versions were detected. To add a new dependency in the custom script, one usually only needs to specify the include and library paths and set the “found” variable. For example, setting the Intel IPP variables:

SET(IPP_FOUND TRUE) 
INCLUDE_DIRECTORIES("/opt/intel/ipp/current/em64t/include") 
LINK_DIRECTORIES("/opt/intel/ipp/current/em64t/lib") 
MESSAGE(STATUS "Found Intel IPP")

1. The CMake makefiles of your projects will then use the found variable (by convention ”[name]_FOUND”) to compile with or without this library.

To pass a symbol to your code, you can use the following command, for example the __IPP__ symbol to let the code know it should use the IPP related code if given:
SET (CMAKE_CXX_FLAGS “${CMAKE_CXX_FLAGS} -D__IPP__”)

If packages are not available through apt-get or port, one can manually download and install sources. Here is a guide for some of the required packages.

1. wget http://downloads.sourceforge.net/cppunit/cppunit-1.12.1.tar.gz
   
2. tar xzvf cppunit-1.12.1.tar.gz && cd cppunit-1.12.1
   
3. ./configure && make && sudo make install

1. To install cppunit in another directory, do: make install DESTDIR=my_cppunit_directory
   

If you installed cppunit in a non-standard directory, add your path in scripts/FindCustom.cmake as described earlier, e.g:

SET(CPPUNIT_FOUND TRUE)
INCLUDE_DIRECTORIES("my_cppunit_directory/include")
LINK_DIRECTORIES("my_cppunit_directory/lib")
MESSAGE(STATUS "Found CPPUNIT")

1. wget http://sourceforge.net/projects/boost/files/boost/1.43.0/boost_1_43_0.tar.gz/download
   
2. tar xzvf boost_1_43_0.tar.gz && cd boost_1_43_0
   
3. ./bootstrap.sh –prefix=${HOME}/installed/boost && ./bjam install –with-filesystem –with-regex
   

1. If you installed boost in a non-standard directory, add your path in scripts/FindCustom.cmake as described earlier, e.g:

SET(Boost_FOUND TRUE)
SET(Boost_INCLUDE_DIRS "$ENV{HOME}/installed/boost/include")
SET(Boost_LIBRARY_DIRS "$ENV{HOME}/installed/boost/lib")
SET(Boost_MINOR_VERSION 35)

1. The mpidetect project can run multiple detection threads in an MPI environment.
2. To use it, you have to install an mpi implementation and boost-mpi.
3. With ubuntu repositories, you can use

   sudo apt-get install libboost-mpi-dev libopenmpi-dev

4. On other distros, install the libraries libboost-serialization libboost-mpi
   
5. Run it with N cores: mpiexec -np N ./mpidetect

1. The MatIO library can read matlab .mat files.
2. To use it, you have to install the matio library (atleast version 1.5.0) and enable it in FindCustom.cmake
3. With ubuntu repositories, DO NOT USE apt-get versions which are outdated.
4. Download MATIO from their page and extract it to a folder.

   http://sourceforge.net/projects/matio/files/latest/download

5. In the folder, call (using Matlab format 7.3 allows to use matrix files bigger than 2Gb):

   export CC=/usr/bin/gcc
   ./configure --prefix=$HOME/matio --enable-mat73=yes --with-default-file-ver=7.3
   make && make install

6. Note: After the ./configure command, make sure that the compiler is gcc (it is printed out at the end).
7. Edit eblearn/tools/scripts/FindCustom.cmake and add the lines

   SET(MATIO_FOUND TRUE)
   SET(MATIO_INCLUDE_DIR "$ENV{HOME}/matio/include")
   SET(MATIO_LIBRARIES "$ENV{HOME}/matio/lib/libmatio.so")

For sample usage of the wrappers, look at an example usage over here

1. Download and install
   • 32-bit Installer eblearn-1.2_x86-r2631-win32.exe
   • 64-bit Installer eblearn-1.2_x64-r2631-win64.exe
2. Add eblearn/bin directory to your PATH environment variable.
3. Make sure you have read/write rights to the eblearn installation dir (so that tester can read/write files from that directory)
4. You can check if eblearn is working by running the bin/tester.exe

1. Download and extract eblearn-1.1-x86-release.exe
2. Install Microsoft VC++ SP1 Runtime redistributables
3. Install Imagemagick 8-bit binaries and add them to your system path. The check if it was installed correctly, go to a terminal and type “convert –version”. It should say something with the words Imagemagick.

1. eblearn-1.0-r1860-win32.zip (Users reported problems extracting with WinRAR. Please use 7-zip for extraction. You might need pthreads(see below) and QT dlls.)

Note: On windows, eblearn no longer compiles with VS2008 or earlier because of using some implementation features of VC++ 2010 in our new svector class. Hence, ideally, use VS2010 or VS2010 Express editions to compile eblearn from sources.

1. Sources via SVN: Install TortoiseSVN (details below) and use this address: svn:svn.code.sf.net/p/eblearn/code/trunk/ - Sources via self-extracting exe eblearn-1.2_x86-r2631-win32.exe - Old sources (1.1 release) eblearn-1.1-x86-release.exe - Old sources (1.0 release) eblearn-1.0-v1860.tgz ==== Quick install of core ==== - Install CMake (details below). Run it and enter the core source code path (e.g.: C:/Users/pierre/eblearn/core) and the output path (e.g.: C:/Users/pierre/eblearn/bin). - (optional) Install ImageMagick to be able to read images (see procedure below). - In CMake, click 'configure', select the type of project you want to generate (e.g. 'Visual Studio 10' if you work with Visual Studio), then click 'generate'. - Open the generated project in your output path with Visual Studio. - Right-click on the project you want to compile and select 'build'. ==== Quick install of core and tools ==== - Install CMake (details below). Run it and enter the tools source code path (e.g.: C:/Users/pierre/eblearn/tools) and the output path (e.g.: C:/Users/pierre/eblearn/bin). - Install ImageMagick to be able to read images (see procedure below). - (optional) Download and extract MNIST (http://yann.lecun.com/exdb/mnist/) and set variable MNIST_PATH in CMake with 'Add Entry' to your MNIST path (as string). If your path contains '\', be sure to add an extra slash in front '\\', e.g. C:\mnist should be C:\\mnist. - (optional) Install 3rd-party software (see below), such as Qt for graphics, Boost, CPPUNIT for testing, IPP and CBlas for speed, etc. - In CMake, click 'configure', select the type of project you want to generate (e.g. 'Visual Studio 9 2008' if you work with Visual Studio), then click 'generate'. - Open the generated project in your output path with Visual Studio. - Right-click on the project you want to compile and select 'build'. - (optional) Install third-party libraries (see below) depending on which project you want to compile. ==== Execution ==== - To unit-test basic functionalities of the libraries, run the tester in the command line: bin/Release/tester - To test face detection demo, call: bin/Release/detect tools/data/face/best.conf ==== Database installation ==== The MNIST handwritten digit database is used by the tester to unit-test the learning algorithms. You can download MNIST from the following website and specify its path to the tester via the MNIST_PATH variable in CMake: http://yann.lecun.com/exdb/mnist/ Note:when decompressing the MNIST archives, it happens that a dash is replaced by a point by the extractor. Symply rename the extracted file to its original name, e.g.: 't10k-images.idx3-ubyte' should be 't10k-images-idx3-ubyte'. ==== Compilation ==== - To exclude some components such as QT or OpenCV from being used, export the following environment variables with 0 or 1: NOBOOST, NOOPENCV, NOXML, NOQT, NOIPP, NOCBLAS. For example to compile without OpenCV and QT, use NOOPENCV=1 NOQT=1. - To add extra flags to the compilation, export the EBLFLAGS variable. For example, to dump the states of each layer, add the __DUMP_STATES__ flag as follow: EBLFLAGS=”-D__DUMP_STATES__” ==== CMake hints ==== - When installing an external dependency manually, it may be detected automatically by the existing CMake “find” scripts or not. If not, one can edit the scripts/FindCustom.cmake script which is called by FindAll.cmake. This script is called after every other script, thus can override other dependencies if other non-desired versions were detected. - To add a new dependency in the custom script, one usually only needs to specify the include and library paths and set the “found” variable. For example, setting the Intel IPP variables:
   SET(CPPUNIT_FOUND TRUE)
SET(CPPUNIT_INCLUDE_DIR “B:/windows/cppunit-1.12.1/include”)
SET(CPPUNIT_LIBRARY “B:/windows/cppunit-1.12.1/lib/cppunitd.lib”)
MESSAGE(STATUS “Found CPPUNIT”)
   - The CMake makefiles of your projects will then use the found variable (by convention ”[name]_FOUND”) to compile with or without this library. - To pass a symbol to your code, you can use the following command, for example the __IPP__ symbol to let the code know it should use the IPP related code if given: SET (CMAKE_CXX_FLAGS “${CMAKE_CXX_FLAGS} -D__IPP__”) ==== Open-source third-party installation ==== === TortoiseSVN === - Download from http://sourceforge.net/projects/tortoisesvn/ - Install, then click 'export' with the eblearn link (svn:svn.code.sf.net/p/eblearn/code/trunk/) to download the eblearn repository.

1. Download from http://www.cmake.org/cmake/resources/software.html

1. Download the 8-bit version of ImageMagick for Windows: http://www.imagemagick.org/script/binary-releases.php#windows
2. During installation, check both “Add application directory to your system path” and “Install development headers and libraries for C and C++”.
3. Important: verify that your imagemagick was installed correctly by going to a terminal and typing “convert –version”. It should say Imagemagick and tell you the installed version.

1. For multi-thread support (e.g. multi-threaded detection with 'detect' tool), download pthread for Windows: http://sourceware.org/pthreads-win32/
2. Then set pthread paths in eblearn/tools/scripts/FindCustom.cmake:

SET(PTHREAD_FOUND TRUE)
SET(PTHREAD_INCLUDE_DIR “\pthread\Pre-built.2\include”)
SET(PTHREAD_LIBRARY “\pthread\Pre-built.2\lib\pthreadVC2.lib”)

If you are using VC++ 2010 or VC++ 2010 Express,

1. Use the cppunit-1.12.1-VS2010.zip provided here. Thanks to the Original blog entry

   https://skydrive.live.com/redir.aspx?cid=62ec12f129a50654&resid=62EC12F129A50654!205&parid=62EC12F129A50654!130&authkey=!ABmsE09OCIC88Xw

2. Extract the code to the location of you choice.
3. Open the examples/examples.sln
4. Build the projects “cppunit” and “cppunit_dll” in Release mode
5. The resulting libraries can be found in the lib/ directory.
6. Finally add those lines in eblearn/tools/scripts/FindCustom.cmake:

SET(CPPUNIT_FOUND TRUE)
SET(CPPUNIT_INCLUDE_DIR "c:/cppunit-1.12.1/include") 
SET(CPPUNIT_LIBRARY "c:/cppunit-1.12.1/lib/cppunit.lib")
MESSAGE(STATUS "Found CPPUNIT")

For older versions of VC++

1. Download from http://sourceforge.net/projects/cppunit/files/cppunit/1.12.1/
2. Extract the code to the location of your choice and build the library:
3. Open the src/CppUnitLibraries.dsw workspace in VC++.
4. In the 'Build' menu, select 'Batch Build…'
5. In the batch build dialog, select all projects and press the build button.
6. The resulting libraries can be found in the lib/ directory.
7. Finally add those lines in eblearn/tools/scripts/FindCustom.cmake:

SET(CPPUNIT_FOUND TRUE)
SET(CPPUNIT_INCLUDE_DIR “B:/windows/cppunit-1.12.1/include”)
SET(CPPUNIT_LIBRARY “B:/windows/cppunit-1.12.1/lib/cppunitd.lib”)
MESSAGE(STATUS “Found CPPUNIT”)

1. NOTE: if you are compiling 64-bit binaries, you need to compile Qt from source.
2. Download the development files
   1. e.g. for VS2008 at http://qt.nokia.com/downloads/windows-cpp-vs2008
   2. for VS2010 http://qt.nokia.com/downloads/windows-cpp-vs2010
3. After installation, add to your 'PATH' environment variable your Qt bin directory (right-click 'My Computer', then Properties → Advanced System Settings → Environment Variables → System Variables, then add for example ”;C:\Qt\bin” at the end of the existing PATH string).
4. Rerun 'configure' and 'generate' in CMake and make sure the output of CMake mentions “Qt Found”.

1. Download the boost installer: http://www.boostpro.com/download
2. During installation, select the “Multithread DLL” and “Multithread debug DLL” versions then select at least “regex”, “filesystem” and “system”.
3. After installation, add to your 'PATH' environment variable your Boost lib directory (right-click 'My Computer', then Properties → Advanced System Settings → Environment Variables → System Variables, then add for example ”;C:\Program Files\boost\boost_1_42\lib” at the end of the existing PATH string).
4. Add an environment variable called BOOST_ROOT that points to your boost root directory. For example “C:\Program Files\boost\boost_1_47”
5. Note: Due to the way boostpro names files, you might have to rename and prefix your boost .lib files with “lib”. Example, in C:\Program Files\boost\boost_1_47\lib, for each .lib file, you might have to make a copy and add “lib” to the start of the copy. Eg. copy boost_regex-vc100-mt-1_47.lib to a new file and name the file libboost_regex-vc100-mt-1_47.lib

1. Install macports if not present: http://www.macports.org/install.php
2. sudo port install subversion cmake imagemagick boost qt4-mac cppunit doxygen wget
3. svn co svn:svn.code.sf.net/p/eblearn/code/trunk/ eblearn - cd eblearn/tools && make && sudo make install - cd eblearn/tools && make test ==== Download ==== - Sources via SVN: svn co svn:svn.code.sf.net/p/eblearn/code/trunk/ eblearn
4. Binaries: Not yet available.
5. Sources Package: eblearn_1.2_r2631-src.zip
6. Old Sources:
   1. 1.1 eblearn-1.1-r2350.zip
   2. 1.0 eblearn-1.0-v1860.tgz

1. sudo port install subversion cmake imagemagick
2. cd core && make && sudo make install

1. sudo port install subversion cmake imagemagick boost qt4-mac cppunit doxygen wget
2. cd tools && make && sudo make install
3. cd tools && make test

1. Unit testing: ./bin/tester (Or make test)
   
2. Face detection demo: ./bin/detect tools/data/face/best.conf
   

The MNIST handwritten digit database is used by the tester to unit-test the learning algorithms.
The tester offers an automatic download of MNIST (you can also download it manually here. Note: when decompressing the MNIST archives, it happens that a dash is replaced by a point by the extractor. Symply rename the extracted file to its original name, e.g.: 't10k-images.idx3-ubyte' should be 't10k-images-idx3-ubyte').

1. Libraries only:

   make libs

2. All projects in release mode:

   make release

3. All projects in debug mode:

   make debug

4. Specific project(s) in release mode, e.g. train or metarun and metaparse:

   make train

   or

   make metarun metaparse

5. Specific project(s) in debug mode, (append the project name with _debug) e.g. detect:

   make detect_debug

6. To compile the tester and run it:

   make test

7. To exclude some components such as QT or OpenCV from being used, export the following shell variables with 0 or 1: NOBOOST, NOOPENCV, NOXML, NOQT, NOIPP, NOCBLAS. For example to compile without OpenCV:

   make NOOPENCV=1 NOQT=1

   or

   export NOOPENCV=1 && make

8. To add extra flags to the compilation, export the EBLFLAGS variable. For example, to dump the states of each layer, add the __DUMP_STATES__ flag as follow:

   export EBLFLAGS="-D__DUMP_STATES__" && make

1. To install libraries and headers on your system: sudo make install
   
2. To install libraries and headers in a specific directory: make install DIR=“your-install-dir” or export DIR=“your-install-dir” && make install

1. http://www.macports.org/install.php

1. Core libraries only, i.e. libeblearn and libidx (tools, testers and some demos may not compile): sudo port install cmake imagemagick
   
2. Tools, demos and tester: sudo port install boost cppunit qt4-mac
   
3. Developers only (tools for bug-free development): sudo port install valgrind doxygen

1. When installing an external dependency manually, it may be detected automatically by the existing CMake “find” scripts or not.

If not, one can edit the scripts/FindCustom.cmake script which is called by FindAll.cmake. This script is called after every other script, thus can override other dependencies if other non-desired versions were detected. To add a new dependency in the custom script, one usually only needs to specify the include and library paths and set the “found” variable. For example, setting the Intel IPP variables:
SET(IPP_FOUND TRUE)
INCLUDE_DIRECTORIES(”/opt/intel/ipp/current/em64t/include”)
LINK_DIRECTORIES(”/opt/intel/ipp/current/em64t/lib”)
MESSAGE(STATUS “Found Intel IPP”)

1. The CMake makefiles of your projects will then use the found variable (by convention ”[name]_FOUND”) to compile with or without this library.

To pass a symbol to your code, you can use the following command, for example the __IPP__ symbol to let the code know it should use the IPP related code if given:
SET (CMAKE_CXX_FLAGS “${CMAKE_CXX_FLAGS} -D__IPP__”)

If packages are not available through apt-get or port, one can manually download and install sources. Here is a guide for some of the required packages.

1. Get sources (e.g. cmake-2.6.2.tar.gz) from http://www.cmake.org/cmake/resources/software.html.
2. Consult the README.txt in the top level directory and note that the steps to compile and install are ./bootstrap; make; sudo make install

1. Get sources (e.g. Atlas-C++-0.6.1.tar.gz) from http://sourceforge.net/projects/worldforge/
2. The standard configure && make && sudo make install will do.

1. Get sources (e.g. cppunit-1.12.1.tar.gz) from http://apps.sourceforge.net/mediawiki/cppunit/
2. The standard “configure/make/sudo make install” will do.

How to work with eblearn from within Eclipse:

1. Get the Eclipse CDT (C/C++ development tools), version 4.0 or above: http://www.eclipse.org/cdt/
2. Rename any existing eblearn project directories that might get overwritten.
3. Right-click on any existing copies of eblearn and select “rename”.
4. Download Subclipse, the Eclipse plugin for svn: http://subclipse.tigris.org/install.html
5. Make sure to install all suggested packages from subclipse, not just the mandatory ones.
6. Check out the svn repositories from within Eclipse: Right-click in a blank area of the project list, and select “Import”. Select “svn project”.
7. Enter https://sourceforge.net/projects/eblearn/ as the repo address.
8. Import the the repository root. Do not import its subdirectories “eblearn” or “libeblearn” individually.
9. Download the mnist data set if you want to run the unit tests: http://yann.lecun.com/exdb/mnist/
10. Run configure.sh from the new root directory, follow the prompts.
11. Generate eclipse project files from cmake. You may need cmake 2.6 or above. Within the eblearn root directory (eblearn, not eblearn/eblearn), run: cmake -G”Eclipse CDT4 - Unix Makefiles. For more info, see http://www.cmake.org/Wiki/Eclipse_CDT4_Generator
12. Get Eclipse to see the newly generated project metadata files: Within Eclipse, right-click on the eblearn root directory and select “Refresh”.