more documentation of freebsd install + blas support

2 files changed, 229 insertions, 39 deletions

diff --git a/dokinstall/blas.dok b/dokinstall/blas.dok
new file mode 100644
index 0000000..3bb15a6
--- /dev/null
+++ b/dokinstall/blas.dok
@@ -0,0 +1,153 @@
+====== BLAS and LAPACK ======
+
+There are multiple BLAS and LAPACK libraries out there. Most Linux
+distributions come with pre-compiled BLAS or ATLAS libraries.
+**We strongly discourage you to use those libraries**. According to our experience,
+these libraries are slow. Things have been improved with recent ATLAS
+development versions, but they have still a hard time to catch up with Intel MKL
+or GotoBLAS/OpenBLAS implementations.
+
+We found that on Intel platforms,
+[[http://www.tacc.utexas.edu/tacc-projects/gotoblas2|GotoBLAS]]/[[https://github.com/xianyi/OpenBLAS|OpenBLAS]]
+or [[www.intel.com/software/products/mkl|Intel MKL]] implementations were
+the fastest. The advantage of GotoBLAS and OpenBLAS being that they are
+distributed with a BSD-like license. The choice is yours.
+
+===== Installing OpenBLAS =====
+
+[[http://www.tacc.utexas.edu/tacc-projects/gotoblas2|GotoBLAS]] has been
+extremely well hand-optimized by Kazushige Goto.  The project has been
+released under a BSD-like license. Unfortunately, it is not maintained
+anymore (at this time), but several forks have been released later. Our preference
+goes to [[https://github.com/xianyi/OpenBLAS|OpenBLAS]].
+
+We provide below simple instructions to install OpenBLAS. Similar instructions apply for
+GotoBLAS.
+
+First get the latest OpenBLAS stable code:
+<file>
+git clone git://github.com/xianyi/OpenBLAS.git
+</file>
+
+You will need a Fortran compiler. On most Linux distributions, ''gfortran'' is available.
+For e.g., on Debian,
+<file>
+apt-get install gfortran
+</file>
+If you prefer, you can also install GCC 4.6 which also supports Fortran language.
+
+On FreeBSD, gfortran is not available, so please use GCC 4.6.
+<file>
+pkg_add -r gcc46
+</file>
+
+On MacOS X, you should install one gfortran package provided on
+[[http://gcc.gnu.org/wiki/GFortranBinaries|this GCC webpage]].
+
+You can now go into the OpenBlas directory, and just do ''make''. Read OpenBLAS manual for more details.
+You can use ''CC'' and ''FC'' variables to control the C and Fortran compilers.
+
+On FreeBSD use 'gmake' instead of 'make'. You also have to specify the correct MD5 sum program
+You will probably want to use the following command line:
+<file>
+gmake CC=gcc46 FC=gcc46 MD5SUM='md5 -q'
+</file>
+
+On MacOS X, you will also have to specify the correct MD5SUM program:
+<file>
+make MD5SUM='md5 -q'
+</file>
+
+Be sure to specify MD5SUM correctly, otherwise OpenBLAS might not compile LAPACK properly.
+
+At the end of the compilation, you might want to do a 
+<file>
+make PREFIX=/your_installation_path/ install
+</file>
+to install OpenBLAS at a specific location. You might also want to keep it where you compiled it.
+
+Note that on MacOS X, the generated **dynamic** (''.dylib'') library does not contain LAPACK. Simply remove
+the dylib (keeping the archive ''.a'') such that LAPACK is correctly detected.
+
+==== CMake detection ====
+Make sure that CMake can find your OpenBLAS library. This can be done with
+<file>
+export CMAKE_LIBRARY_PATH=/your_installation_path/lib
+</file>
+before starting cmake command line.
+
+===== Installing Intel MKL =====
+
+[[www.intel.com/software/products/mkl|Intel MKL]] is a closed-source
+library //sold// by Intel. Follow Intel instructions to unpack MKL. Then make
+sure the libraries relevant for your system (e.g. ''em64t'' if you are on a
+64 bits distribution) are available in your ''LD_LIBRARY_PATH''. Both BLAS
+and LAPACK interfaces are readily included in MKL.
+
+==== CMake detection ====
+Make sure that CMake can find your libraries. This can be done with something like
+<file>
+export CMAKE_INCLUDE_PATH=/path/to/mkl/include
+export CMAKE_LIBRARY_PATH=/path/to/mkl/lib/intel64:/path/to/mkl/compiler/lib/intel64
+export LD_LIBRARY_PATH=$CMAKE_LIBRARY_PATH:$LD_LIBRARY_PATH
+</file>
+before starting cmake command line.
+
+Of course, you have to adapt ''/path/to/mkl'' and ''/path/to/mkl/compiler'' to your installation setup. In the above
+case, we also chose the ''intel64'' libraries, which might not be what you need.
+
+A common mistake is to forgot the path to Intel compiler libraries. CMake
+will not be able to detect threaded libraries in that case.
+
+===== CMake and BLAS/LAPACK =====
+
+As mentioned above, you should make sure CMake can find your
+libraries. Carefully watch for libraries found (or not found) in the output
+generated by cmake.
+
+For example, if you see something like:
+<file>
+-- Checking for [openblas - gfortran]
+--   Library openblas: /Users/ronan/open/lib/libopenblas.dylib
+--   Library gfortran: BLAS_gfortran_LIBRARY-NOTFOUND
+</file>
+It means CMake found the OpenBLAS library, but could not make it work
+properly because it did not find the required gfortran library. Make sure
+that CMake can find all the required libraries through CMAKE_LIBRARY_PATH.
+If your libraries are present in LD_LIBRARY_PATH, it should be fine too.
+
+Note that CMake will try to detect various BLAS/LAPACK libraries. If you have several libraries
+installed on your computer (say Intel MKL and OpenBLAS), or if you want to avoid all these checks,
+you might want to select the one you want to use with:
+<file>
+cd torch7/build
+cmake .. -DWITH_BLAS=open
+</file>
+Valid options for WITH_BLAS are ''mkl'' (Intel MKL), ''open'' (OpenBLAS),
+''goto'' (GotoBlas2), ''acml'' (AMD ACML), ''atlas'' (ATLAS),
+''accelerate'' (Accelerate framework on MacOS X), ''vecLib'' (vecLib
+framework on MacOS X) or ''generic''.
+
+Note again that the best choices are probably ''open'' or ''mkl''. For
+consistency reasons, CMake will try to find the corresponding LAPACK
+package (and does not allow mixing up different BLAS/LAPACK versions).
+
+
+===== GotoBLAS/OpenBLAS and MKL threads =====
+
+GotoBLAS/OpenBLAS and MKL are multi-threaded libraries.
+With MKL, the number of threads can be controlled by
+<file>
+export OMP_NUM_THREADS=N
+</file>
+where N is an integer.
+
+With OpenBLAS, you can use
+<file>
+export OPENBLAS_NUM_THREADS=N
+</file>
+or GOTO_NUM_THREADS, or OMP_NUM_THREADS.
+
+Beware that running small problems on a large number of threads reduce
+performance! Multi-threading should be enable only for large-scale
+computations.
diff --git a/dokinstall/index.dok b/dokinstall/index.dok
index 5dd0377..fad74fc 100644
--- a/dokinstall/index.dok
+++ b/dokinstall/index.dok
@@ -31,7 +31,7 @@ If you are a programmer, you might want to produce your own
 
 Torch compilation requires a number of standard packages described below:
   * **Mandatory:**
-    * A ''C/C++'' compiler ([[http://gcc.gnu.org|GNU compiler]] or Intel compiler work fine)
+    * A ''C/C++'' compiler. [[http://clang.llvm.org|CLang]] is great. The [[http://gcc.gnu.org|GNU compiler]] or Intel compiler work fine.
     * [[http://www.cmake.org|CMake]] version 2.6 or later is required.
     * [[http://gnuplot.info|Gnuplot]], version ''4.4'' or later is recommended for best experience.
 
@@ -39,15 +39,30 @@ Torch compilation requires a number of standard packages described below:
     * [[http://tiswww.case.edu/php/chet/readline/rltop.html|GNU Readline]]
     * [[http://git-scm.com/|Git]] to keep up-to-date sources
     * [[http://trolltech.com/products|QT 4.4]] or newer development libraries
-    * CBLAS. Intel MKL library is recommended for that purpose on Intel computers.
-    * LAPACK. Intel MKL library is recommended for that purpose on Intel computers.
+    * BLAS. [[https://github.com/xianyi/OpenBLAS|OpenBLAS]] is recommended for that purpose on Intel computers.
+    * LAPACK. [[https://github.com/xianyi/OpenBLAS|OpenBLAS]] is recommended for that purpose on Intel computers.
 
 The installation of most of these packages should be rather
 straightforward. For ''Ubuntu 10.04 LTS'' system we use the
 ''apt-get'' magic:
 
+For GCC:
 <file>
 sudo apt-get install gcc g++
+</file>
+If you prefer to use CLang:
+<file>
+sudo apt-get install clang
+</file>
+
+CMake reads CC and CXX variables. If you do not want to use the default compiler, just do
+<file>
+export CC=clang
+export CXX=clang++
+</file>
+
+To install the additional packages, do:
+<file>
 sudo apt-get install cmake
 sudo apt-get install libreadline5-dev
 sudo apt-get install git-core
@@ -67,28 +82,8 @@ install it with
 sudo apt-get install libqt4-core libqt4-gui libqt4-dev
 </file>
 
-CBLAS installation is also recommended for speed. If not found, Torch
-will rely on hand-made linear algebra routines. Ubuntu distribution
-provide CBLAS through the ''libblas'' package:
-
-<file>
-sudo apt-get install libblas-dev
-</file>
-
-LAPACK installation is required for anyone who wants to use linear
-algebra operations like [[..:torch:maths#torch.eig|eigenvalue
-computation]], [[..:torch:maths#torch.svd|singular value decomposition]].
-Ubuntu distribution provides LAPACK through ''liblapack'' package.
-
-<file>
-sudo apt-get install liblapack-dev
-</file>
-
-Ultimate speed is achieved using the Intel MKL libraries. Follow Intel
-instructiona to unpack MKL. Then make sure the libraries relevant for
-your system (e.g. ''em64t'' if you are on a 64 bits distribution) are
-available in your ''LD_LIBRARY_PATH''. Both BLAS and LAPACK interfaces are
-readily included in MKL.
+An excellent BLAS/LAPACK implementation is also recommended for speed. See
+our [[blas|BLAS recommendations]].
 
 ==== B. Getting Torch sources ====
 {{anchor:install.sources}}
@@ -245,7 +240,7 @@ Qt options:
 
 Torch compilation requires a number of standard packages described below:
   * **Mandatory:**
-    * A ''C/C++'' compiler ([[http://gcc.gnu.org|GNU compiler]] or Intel compiler work fine)
+    * A ''C/C++'' compiler. [[http://clang.llvm.org|CLang]] is great. The [[http://gcc.gnu.org|GNU compiler]] or Intel compiler work fine.
     * [[http://www.cmake.org|CMake]] version 2.6 or later is required.
     * [[http://gnuplot.info|Gnuplot]], version ''4.4'' or later is recommended for best experience.
 
@@ -253,8 +248,8 @@ Torch compilation requires a number of standard packages described below:
     * [[http://tiswww.case.edu/php/chet/readline/rltop.html|GNU Readline]]
     * [[http://git-scm.com/|Git]] to keep up-to-date sources
     * [[http://trolltech.com/products|QT 4.4]] or newer development libraries
-    * CBLAS. Intel MKL library is recommended for that purpose on Intel computers.
-    * LAPACK. Intel MKL library is recommended for that purpose on Intel computers.
+    * BLAS. [[https://github.com/xianyi/OpenBLAS|OpenBLAS]] is recommended for that purpose on Intel computers.
+    * LAPACK. [[https://github.com/xianyi/OpenBLAS|OpenBLAS]] is recommended for that purpose on Intel computers.
 
 Installation of gcc should be done by installing the
 [[http://developer.apple.com/tools/xcode|the Apple developer
@@ -282,6 +277,9 @@ compile.  Instead, you can
 the binary **DMG** file available on [[http://trolltech.com|Trolltech
 website]] and install it.
 
+An excellent BLAS/LAPACK implementation is also recommended for speed. See
+our [[blas|BLAS recommendations]].
+
 ==== B. Getting Torch sources ====
 
 Same as [[#install.sources|getting sources]] for linux.
@@ -305,7 +303,7 @@ Same as [[#install.run|runnning]] for linux.
 
 Torch compilation requires a number of standard packages described below:
   * **Mandatory:**
-    * A ''C/C++'' compiler ([[http://gcc.gnu.org|GNU compiler]] or Intel compiler work fine)
+    * A ''C/C++'' compiler. [[http://clang.llvm.org|CLang]] is great. The [[http://gcc.gnu.org|GNU compiler]] or Intel compiler work fine.
     * [[http://www.cmake.org|CMake]] version 2.6 or later is required.
     * [[http://gnuplot.info|Gnuplot]], version ''4.4'' or later is recommended for best experience.
 
@@ -313,10 +311,23 @@ Torch compilation requires a number of standard packages described below:
     * [[http://tiswww.case.edu/php/chet/readline/rltop.html|GNU Readline]]
     * [[http://git-scm.com/|Git]] to keep up-to-date sources
     * [[http://trolltech.com/products|QT 4.4]] or newer development libraries
-    * CBLAS. Intel MKL library is recommended for that purpose on Intel computers.
-    * LAPACK. Intel MKL library is recommended for that purpose on Intel computers.
+    * BLAS. [[https://github.com/xianyi/OpenBLAS|OpenBLAS]] is recommended for that purpose on Intel computers.
+    * LAPACK. [[https://github.com/xianyi/OpenBLAS|OpenBLAS]] is recommended for that purpose on Intel computers.
 
-This should be easily installed with
+GCC and CLang come with FreeBSD install. However, only GCC 4.2 is installed by default (for licensing reasons).
+We prefer to use CLang. If you want to stick with GCC, we recommend installing GCC 4.4 or GCC 4.6 instead of using
+GCC 4.2 (poor performance on recent CPUs).
+<file>
+pkg_add -r gcc46
+</file>
+
+CMake reads CC and CXX variables. If you do not want to use the default compiler, just do
+<file>
+export CC=clang
+export CXX=clang++
+</file>
+
+Additional packages can be easily installed with:
 <file>
 pkg_add -r readline
 pkg_add -r cmake
@@ -335,13 +346,20 @@ For installing QT, use also ''pkg_add -r qt4'', followed by ''pkg_add -r qt4-XXX
 XXX is one of the components (or tools) listed on [[http://www.freebsd.org/doc/en/books/porters-handbook/using-qt.html|Qt FreeBSD page]].
 Be sure to install all components and tools listed there.
 
+An excellent BLAS/LAPACK implementation is also recommended for speed. See
+our [[blas|BLAS recommendations]].
+
 ==== B. Getting Torch sources ====
 
 Same as [[#install.sources|getting sources]] for linux.
 
 ==== C. Configuring Torch ====
 
-Same as [[#install.config|configuring]] for linux.
+Same as [[#install.config|configuring]] for linux. Note that dynamic RPATH (related to ''$ORIGIN'') do not work properly
+on my FreeBSD 9. You can deactivate this with the ''WITH_DYNAMIC_RPATH'' option.
+<file>
+cmake .. -DCMAKE_INSTALL_PREFIX=/my/install/path -DWITH_DYNAMIC_RPATH=OFF
+</file>
 
 ==== D. Compiling and Installing ====
 
@@ -368,6 +386,16 @@ could not manage to make QT 4.4 work under Cygwin. Instead prefer
 
 CMake is well documented on [[http://www.cmake.org|http://www.cmake.org]].
 
+====CMake and CLang====
+
+If you like to use [[http://clang.llvm.org|CLang]] for compiling Torch7, assuming a proper
+CLang installation, you only have to do
+<file>
+export CC=clang
+export CXX=clang++
+</file>
+before calling cmake command line.
+
 ====CMake GUI====
 
 Under Windows, CMake comes by default with a GUI. Under Unix system it is
@@ -393,6 +421,21 @@ cmake /path/to/torch/source -DMY_VARIABLE=MY_VALUE
 where ''MY_VARIABLE'' is the name of the variable you want to set and
 ''MY_VALUE'' is its corresponding value.
 
+===Interesting standard CMake variables===
+
+  * ''CMAKE_INSTALL_PREFIX'': directory where Torch is going to be installed
+  * ''CMAKE_BUILD_TYPE'': ''Release'' for optimized compilation, ''Debug'' for debug compilation.
+  * ''CMAKE_C_FLAGS'': add here the flags you want to pass to the C compiler (like ''-Wall'' for e.g.)
+
+=== Notable Torch7 CMake variables ===
+
+  * ''WITH_BLAS'': specify which BLAS you want to use (if you have several on your computers). Can be mkl/open/goto/acml/atlas/accelerate/veclib/generic.
+  * ''WITH_LUA_JIT'': say to CMake to compile Torch7 against LuaJIT instead of Lua. (default is OFF)
+  * ''WITH_QTLUA'': compile QtLua if Qt is found (default is ON)
+  * ''WITH_QTLUA_IDE'': compile QtLua IDE if Qt is found (default is ON)
+  * ''WITH_RPATH'': use RPATH such that you do not need to add Torch7 install library path in LD_LIBRARY_PATH. (default is ON)
+  * ''WITH_DYNAMIC_RPATH'': if used together with WITH_RPATH, will make library paths relative to the Torch7 executable. If you move the install directory, things will still work. This flag does not work on FreeBSD. (default is ON).
+
 ====CMake caches everything====
 
 As soon as CMake performed a test to detect an external library, it saves
@@ -405,12 +448,6 @@ when compiling.
 //In doubt//, if you changed, updated, added some libraries that should be used by Torch, you should
 //erase your build directory and perform CMake configuration again//.
 
-====Interesting standard CMake variables====
-
-  * ''CMAKE_INSTALL_PREFIX'': directory where Torch is going to be installed
-  * ''CMAKE_BUILD_TYPE'': ''Release'' for optimized compilation, ''Debug'' for debug compilation.
-  * ''CMAKE_C_FLAGS'': add here the flags you want to pass to the C compiler (like ''-Wall'' for e.g.)
-
 
 =====  Development Torch packages =====
 {{anchor:DevPackages}}