start modifying the INSTALL.org

INSTALL.org

+#+TITLE: Installation quick start guide
+#+LANGUAGE:  en
+#+OPTIONS: H:3 num:t \n:nil @:t ::t |:t _:nil ^:nil -:t f:t *:t <:t
+#+OPTIONS: TeX:t LaTeX:t skip:nil d:nil pri:nil tags:not-in-toc html-style:nil
+
+This is a brief discussion about Chameleon installation and usage.
+For more information, please read the document users_guide.
+
+Chameleon is written in C, it provides an interface to be called from
+Fortran and depends on a couple of external libraries that must be
+installed on the system.
+
+* Chameleon prerequisites
+
+To install Chameleon's libraries, header files, and executables, one
+needs:
+- CMake (version 2.8 minimum) : the build system
+- C and Fortran compilers : GNU compiler suite, Clang, Intel or IBM
+  can be used
+- python : to generate files in the different precisions
+- external libraries : this depends on the configuration, by default
+  the required libraries are
+  - StarPU: http://runtime.bordeaux.inria.fr/StarPU/
+  - CBLAS, LAPACKE: these are interfaces and there exist several
+    possible providers that can be used with Chameleon
+    - Intel MKL, Netlib, OpenBlas
+  - BLAS, LAPACK, TMGLIB: there exist several possible providers that can be
+    used with Chameleon
+    - Eigen, Intel MKL, Netlib, OpenBlas
+  - pthread (libpthread)
+  - math (libm)
+
+Optional libraries
+
+quark  : http://icl.cs.utk.edu/quark/
+cuda   : https://developer.nvidia.com/cuda-downloads
+cublas : comes with cuda http://docs.nvidia.com/cuda/cublas/
+mpi    : openmpi http://www.open-mpi.org/
+
+These packages must be installed on the system before trying to
+configure/build chameleon.  Please look at the distrib/ directory
+which gives some hints for the installation of dependencies for Unix
+systems.
+
+We give here some examples for a Debian system:
+#+begin_src
+
+# Update Debian packages list
+sudo apt-get update
+# Install Netlib blas, lapack, tmglib, cblas and lapacke suite
+sudo apt-get install -y liblapack-dev liblapacke-dev
+# Alernatively to Netlib, OpenBLAS could be used (faster kernels)
+sudo apt-get install -y libopenblas-dev liblapacke-dev
+# Install OpenMPI
+sudo apt-get install -y libopenmpi-dev
+# Install hwloc (used by StarPU or QUARK, already a dependency of OpenMPI)
+sudo apt-get install -y libhwloc-dev
+# install FxT, usefull to export some nice execution traces with StarPU
+sudo apt-get install -y libfxt-dev
+# Install cuda and cuBLAS : only if you have a GPU cuda compatible
+sudo apt-get install -y nvidia-cuda-toolkit nvidia-cuda-dev
+
+# Install StarPU (with MPI and FxT enabled)
+mkdir -p $HOME/install
+cd $HOME/install
+wget http://starpu.gforge.inria.fr/files/starpu-1.2.2/starpu-1.2.2.tar.gz
+tar xvzf starpu-1.2.2.tar.gz
+cd starpu-1.2.2/
+./configure --prefix=$HOME/install/starpu --disable-opencl --disable-cuda --with-fxt=/usr/lib/x86_64-linux-gnu/
+make
+make install
+cd $HOME/install
+rm starpu-1.2.2/ starpu-1.2.2.tar.gz -rf
+
+# Install QUARK : to be used in place of StarPU
+cd $HOME/install
+wget http://icl.cs.utk.edu/projectsfiles/quark/pubs/quark-0.9.0.tgz
+tar xvzf quark-0.9.0.tgz
+cd quark-0.9.0/
+sed -i -e "s#prefix=\.\/install#prefix=/builds/install/quark#g" make.inc
+sed -i -e "s#CFLAGS=-O2#CFLAGS=-O2 -fPIC#g" make.inc
+make
+make install
+cd $HOME/install
+rm quark-0.9.0/ quark-0.9.0.tgz -rf
+
+#+end_src
+
+* Build Chameleon
+Compilation of Chameleon libraries and executables are done with CMake
+(http://www.cmake.org/). This version has been tested with CMake
+3.5.1.
+
+Usage: three steps are required to compile and install Chameleon
+
+1. configure :
+   #+begin_src
+   cmake path/to/chameleon -DOPTION1= -DOPTION2= ...
+   see the "Options" section to get list of options
+   see the "Dependencies detection" for details about libraries detection
+   #+end_src
+2. build :
+   #+begin_src
+   make # do not hesitate to use -j[ncores] option to speedup the compilation
+   #+end_src
+3. install (optional) :
+   #+begin_src
+   make install
+   #+end_src
+   Do not forget to specify the install directory with
+   -DCMAKE_INSTALL_PREFIX at configure
+   #+begin_example
+   cmake /home/jdoe/chameleon -DCMAKE_INSTALL_PREFIX=/home/toto/install
+   #+end_example
+
+
+
+** Dependencies detection
+
+   You have different choices to detect dependencies on your system,
+   either by setting some environment variables containing paths to
+   the libs and headers or by specifying them directly at cmake
+   configure. Different cases :
+
+   1) detection of dependencies through environment variables:
+      - LD_LIBRARY_PATH should contain the list of paths where to find
+        the libraries:
+        #+begin_src
+        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:install/path/to/your/lib
+        #+end_src
+      - INCLUDE should contain the list of paths where to find the
+        header files of libraries
+        #+begin_src
+        export INCLUDE=$INCLUDE:install/path/to/your/headers
+        #+end_src
+   2) detection with user's given paths:
+      - you can specify the path at cmake configure by invoking cmake
+        path/to/your/CMakeLists.txt -DLIB_DIR=path/to/your/lib where
+        LIB stands for the name of the lib to look for
+        #+begin_src
+        cmake path/to/your/CMakeLists.txt -DSTARPU_DIR=path/to/starpudir \
+                                          -DCBLAS_DIR= ...
+        #+end_src
+        it is also possible to specify headers and library directories
+        separately
+        #+begin_src
+        cmake path/to/your/CMakeLists.txt -DSTARPU_INCDIR=path/to/libstarpu/include/starpu/1.1 \
+                                          -DSTARPU_LIBDIR=path/to/libstarpu/lib
+        #+end_src
+      - note: BLAS and LAPACK detection can be tedious so that we
+        provide a verbose mode you can set -DBLAS_VERBOSE=ON or
+        -DLAPACK_VERBOSE=ON to activate it
+
+** Options
+
+   You can optionally activate some options at cmake configure (like CUDA, MPI, ...)
+   invoking cmake path/to/your/CMakeLists.txt -DOPTION1= -DOPTION2= ...
+   #+begin_src
+   cmake /home/toto/chameleon/ -DCMAKE_BUILD_TYPE=Debug \
+                               -DCMAKE_INSTALL_PREFIX=/home/toto/install/ \
+                               -DCHAMELEON_USE_CUDA=ON \
+                               -DCHAMELEON_USE_MPI=ON \
+                               -DBLA_VENDOR=Intel10_64lp \
+                               -DSTARPU_DIR=/home/toto/install/starpu-1.2/ \
+                               -DCHAMELEON_ENABLE_TRACING=ON
+   #+end_src
+
+   You can get the full list of options with -L[A][H] options of cmake command
+   #+begin_src
+   cmake -LH /home/toto/chameleon/
+   #+end_src
+
+   You can also set the options thanks to ccmake interface.
+
+
+   Some options (non-exhaustive list) :
+
+   Basic CMake:
+   CMAKE_BUILD_TYPE=Debug|Release
+   CMAKE_INSTALL_PREFIX=path/to/your/install/dir (where headers and libraries will be copied
+                                                  when invoking make install)
+
+   Related to specific modules (find_package):
+   BLA_VENDOR=Intel10_64lp (to use intel mkl for example, see the list of BLA_VENDOR in FindBLAS.cmake in cmake_modules/morse/find)
+   # for the following, see section "Dependencies detection"
+   STARPU_DIR=...
+   STARPU_INCDIR=...
+   STARPU_LIBDIR=...
+   # same idea can be used for some packages, replace STARPU by one of these:
+   BLAS - CBLAS - FXT - HWLOC - LAPACK - LAPACKE - QUARK - TMG
+
+   Chameleon specific:
+   CHAMELEON_USE_MPI=ON|OFF (default OFF)
+   CHAMELEON_USE_CUDA=ON|OFF (default OFF)
+   CHAMELEON_ENABLE_TRACING=ON|OFF (default OFF)
+   CHAMELEON_SCHED_STARPU=ON|OFF (default ON)
+   CHAMELEON_SCHED_QUARK=ON|OFF (default OFF)
+   CHAMELEON_SIMULATION=ON|OFF (default OFF)
+
+   Libraries detected with an official cmake module (see module files in CMAKE_ROOT/Modules/):
+   CUDA - MPI - Threads
+
+   Libraries detected with our cmake modules (see module files in cmake_modules/morse/find/ directory of Chameleon sources):
+   BLAS - CBLAS - FXT - HWLOC - LAPACK - LAPACKE - QUARK - STARPU - TMG
+
+
+* Use FxT profiling through StarPU
+
+  StarPU can generate its own trace log files by compiling it with the
+  --with-fxt option at the configure step (you can have to specify the
+  directory where you installed FxT by giving --with-fxt=... instead
+  of --with-fxt alone).  By doing so, traces are generated after each
+  execution of a program which uses StarPU in the directory pointed by
+  the STARPU_FXT_PREFIX environment variable.  example: export
+  STARPU_FXT_PREFIX=/home/toto/fxt_files/
+
+  When executing a ./timing/... Chameleon program, if it has been
+  enabled (StarPU compiled with FxT and
+  -DCHAMELEON_ENABLE_TRACING=ON), you can give the option --trace to
+  tell the program to generate trace log files.
+
+  Finally, to generate the trace file which can be opened with Vite
+  program (http://vite.gforge.inria.fr/), you have to use the
+  starpu_fxt_tool tool of StarPU.  This tool should be in
+  $STARPU_INSTALL_REPOSITORY/bin.  You can use it to generate the
+  trace file like this: >
+  path/to/your/install/starpu/bin/starpu_fxt_tool -i prof_filename
+  There is one file per mpi processus (prof_filename_0,
+  prof_filename_1 ...).  To generate a trace of mpi programs you can
+  call it like this: > path/to/your/install/starpu/bin/starpu_fxt_tool
+  -i prof_filename* The trace file will be named paje.trace (use -o
+  option to specify an output name).
+
+
+* Use simulation mode with StarPU-SimGrid
+  Simulation mode can be activated by setting the cmake option
+  CHAMELEON_SIMULATION to ON.  This mode allows you to simulate
+  execution of algorithms with StarPU compiled with SimGrid
+  (http://simgrid.gforge.inria.fr/).  To do so, we provide some
+  perfmodels in the simucore/perfmodels/ directory of Chameleon
+  sources.  To use these perfmodels, please set your STARPU_HOME
+  environment variable to
+  path/to/your/chameleon_sources/simucore/perfmodels.  Finally, you
+  need to set your STARPU_HOSTNAME environment variable to the name of
+  the machine to simulate.  For example: STARPU_HOSTNAME=mirage.  Note
+  that only POTRF kernels with block sizes of 320 or 960 (simple and
+  double precision) on mirage machine are available for now.  Database
+  of models is subject to change, it should be enrich in a near
+  future.