INSTALL.txt 8.23 KB
Newer Older
PRUVOST Florent's avatar
PRUVOST Florent committed
1 2 3
****************************************************
   Some instructions about CHAMELEON installation
****************************************************
4

5 6 7
This is a brief discussion about CHAMELEON usage.
For more information, please read the document users_guide.

8
Compilation of CHAMELEON libraries and executables are done with CMake 
9 10
(http://www.cmake.org/). This version has been tested with CMake 2.8.8.

11
Usage: three steps are required to compile and install CHAMELEON 
12 13

1) configure : 
14
> cmake path/to/chameleon -DOPTION1= -DOPTION2= ... 
15 16 17 18 19 20 21 22 23 24
see the "Options" section to get list of options
see the "Dependencies detection" for details about libraries detection

2) build : 
> make 
do not hesitate to use -j[ncores] option to speedup the compilation

3) install (optional) :
> make install
do not forget to specify the install directory with -DCMAKE_INSTALL_PREFIX at configure
25
example : cmake /home/toto/chameleon -DCMAKE_INSTALL_PREFIX=/home/toto/install
26 27 28


-------------------------------------------
29
* List of libraries CHAMELEON depends on *
30 31 32 33
-------------------------------------------

threads : pthread

PRUVOST Florent's avatar
PRUVOST Florent committed
34 35 36 37 38
blas    : netlib, openblas, eigen or intel mkl
cblas   : netlib, openblas or intel mkl
lapack  : netlib, openblas, eigen or intel mkl
lapacke : netlib, openblas or intel mkl
tmg     : netlib, openblas or intel mkl
39 40 41 42 43 44 45 46 47 48

runtime : quark (http://icl.cs.utk.edu/quark/) or 
          starpu (http://runtime.bordeaux.inria.fr/StarPU/)
hwloc   : (http://www.open-mpi.org/projects/hwloc/)


optional libraries

cuda   : (https://developer.nvidia.com/cuda-downloads)
cublas : comes with cuda (http://docs.nvidia.com/cuda/cublas/)
PRUVOST Florent's avatar
PRUVOST Florent committed
49
magma  : (http://icl.cs.utk.edu/magma/) (version 1.6.2 recommended)
50 51 52
mpi    : openmpi (http://www.open-mpi.org/)
FxT    : linux package (libfxt) or releases here http://download.savannah.gnu.org/releases/fkt/

PRUVOST Florent's avatar
PRUVOST Florent committed
53 54
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.
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

-----------------------------------------

-------------------------------------------
* 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:
        * export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:install/path/to/your/lib
    - INCLUDE should contain the list of paths where to find the header files of libraries
        * export INCLUDE=$INCLUDE:install/path/to/your/headers

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
        * example: cmake path/to/your/CMakeLists.txt -DSTARPU_DIR=path/to/starpudir \
                                                     -DCBLAS_DIR= ...
      it is also possible to specify headers and library directories separately
        * example: cmake path/to/your/CMakeLists.txt -DSTARPU_INCDIR=path/to/libstarpu/include/starpu/1.1 \
                                                     -DSTARPU_LIBDIR=path/to/libstarpu/lib
    - 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= ...
91
example: cmake /home/toto/chameleon/ -DCMAKE_BUILD_TYPE=Debug \
92
                                      -DCMAKE_INSTALL_PREFIX=/home/toto/install/ \
93 94 95
                                      -DCHAMELEON_USE_CUDA=ON \ 
                                      -DCHAMELEON_USE_MAGMA=ON \
                                      -DCHAMELEON_USE_MPI=ON \
96 97
                                      -DBLA_VENDOR=Intel10_64lp \ 
                                      -DSTARPU_DIR=/home/toto/install/starpu-1.1/build/include/starpu/1.1/ \
98
                                      -DCHAMELEON_ENABLE_TRACING=ON 
99 100

You can get the full list of options with -L[A][H] options of cmake command
101
example: cmake -LH /home/toto/chameleon/
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124

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 - MAGMA - QUARK - TMG

125
CHAMELEON specific:
126
--------------------
127 128 129
CHAMELEON_USE_MPI=ON|OFF (default OFF)
CHAMELEON_USE_CUDA=ON|OFF (default OFF) 
CHAMELEON_USE_MAGMA=ON|OFF (default OFF)
130
CHAMELEON_ENABLE_TRACING=ON|OFF (default OFF)
131 132 133
CHAMELEON_SCHED_STARPU=ON|OFF (default ON)
CHAMELEON_SCHED_QUARK=ON|OFF (default OFF)
CHAMELEON_SIMULATION=ON|OFF (default OFF)
134 135 136 137

Libraries detected with an official cmake module (see module files in CMAKE_ROOT/Modules/):
CUDA - MPI - Threads 

138
Libraries detected with our cmake modules (see module files in cmake_modules/morse/find/ directory of CHAMELEON sources):
139 140 141 142 143 144 145 146 147 148 149 150 151 152
BLAS - CBLAS - FXT - HWLOC - LAPACK - LAPACKE - MAGMA - 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/

153
When executing a ./timing/... CHAMELEON program, if it has been enabled 
154
(StarPU compiled with FxT and -DCHAMELEON_ENABLE_TRACING=ON), you can give the option --trace 
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170
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 *
-------------------------------------------
171
Simulation mode can be activated by setting the cmake option CHAMELEON_SIMULATION to ON.
172
This mode allows you to simulate execution of algorithms with StarPU compiled with SimGrid (http://simgrid.gforge.inria.fr/).
173 174
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.
175 176 177 178
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.