configuration.texi 12.2 KB
Newer Older
1 2 3 4 5 6
@c -*-texinfo-*-

@c This file is part of the MORSE Handbook.
@c Copyright (C) 2014 Inria
@c Copyright (C) 2014 The University of Tennessee
@c Copyright (C) 2014 King Abdullah University of Science and Technology
7
@c See the file ../chameleon.texi for copying conditions.
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55

@menu
* Compilation configuration::
* Dependencies detection::
@c * Dependencies compilation::
* Use FxT profiling through StarPU::
* Use simulation mode with StarPU-SimGrid::
@end menu

@c @code{} @option{}
@c @table @code
@c @item truc
@c @item muche
@c @item et zut
@c @c @end table

@node Compilation configuration
@section Compilation configuration

The following arguments can be given to the @command{cmake <path to source 
directory>} script.

In this chapter, the following convention is used:
@itemize @bullet
@item
@option{path} is a path in your filesystem,
@item
@option{var} is a string and the correct value or an example will be given,
@item
@option{trigger} is an CMake option and the correct value is @code{ON} or 
@code{OFF}.
@end itemize

Using CMake there are several ways to give options:
@enumerate
@item directly as CMake command line arguments
@item invoque @command{cmake <path to source directory>} once and then use 
@command{ccmake <path to source directory>} to edit options through a 
minimalist gui (required 
@samp{cmake-curses-gui} installed on a Linux system)
@item invoque @command{cmake-gui} command and fill information about the 
location of the sources and where to build the project, then you have 
access to options through a user-friendly Qt interface (required 
@samp{cmake-qt-gui} installed on a Linux system)
@end enumerate

Example of configuration using the command line 
@example
PRUVOST Florent's avatar
PRUVOST Florent committed
56 57 58 59 60 61 62 63
cmake ~/chameleon/ -DCMAKE_BUILD_TYPE=Debug          \
                   -DCMAKE_INSTALL_PREFIX=~/install  \
                   -DCHAMELEON_USE_CUDA=ON           \
                   -DCHAMELEON_USE_MAGMA=ON          \
                   -DCHAMELEON_USE_MPI=ON            \
                   -DBLA_VENDOR=Intel10_64lp         \
                   -DSTARPU_DIR=~/install/starpu-1.1 \                
                   -DCHAMELEON_USE_FXT=ON 
64 65 66 67 68 69 70 71 72 73
@end example

You can get the full list of options with @option{-L[A][H]} options of 
@command{cmake} command:
@example
cmake -LH <path to source directory>
@end example

@menu
* General CMake options::
74
* CHAMELEON options::
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
@end menu

@node General CMake options
@subsection General CMake options

@table @code

@item -DCMAKE_INSTALL_PREFIX=@option{path} (default:@option{path=/usr/local})
Install directory used by @code{make install} where some headers and libraries 
will be copied.
Permissions have to be granted to write onto @option{path} during @code{make 
install} step.

@item -DCMAKE_BUILD_TYPE=@option{var} (default: @option{Release})
Define the build type and the compiler optimization level.
The possible values for @option{var} are: 
@table @code
@item empty
@item Debug
@item Release
@item RelWithDebInfo
@item MinSizeRel
@end table

@item -DBUILD_SHARED_LIBS=@option{trigger} (default:@option{OFF})
100
Indicate wether or not CMake has to build CHAMELEON static (@option{OFF}) or 
101 102 103 104
shared (@option{ON}) libraries.

@end table

105 106
@node CHAMELEON options
@subsection CHAMELEON options
107

108
List of CHAMELEON options that can be enabled/disabled (value=@code{ON} 
109 110 111
or @code{OFF}):
@table @code

112
@item @option{-DCHAMELEON_SCHED_STARPU}=@option{trigger} (default: @code{ON})
113 114
to link with StarPU library (runtime system)

115
@item @option{-DCHAMELEON_SCHED_QUARK}=@option{trigger} (default: @code{OFF})
116 117
to link with QUARK library (runtime system)

118
@item @option{-DCHAMELEON_USE_CUDA}=@option{trigger} (default: @code{OFF})
119 120 121
to link with CUDA runtime (implementation paradigm for accelerated codes on 
GPUs) and cuBLAS library (optimized BLAS kernels on GPUs), can only be used with 
StarPU
122
@item @option{-DCHAMELEON_USE_MAGMA}=@option{trigger} (default: @code{OFF})
123 124 125
to link with MAGMA library (kernels on GPUs, higher level than cuBLAS), can only 
be used with StarPU

126
@item @option{-DCHAMELEON_USE_MPI}=@option{trigger} (default: @code{OFF})
127 128 129
to link with MPI library (message passing implementation for use of multiple 
nodes with distributed memory), can only be used with StarPU

130
@item @option{-DCHAMELEON_USE_FXT}=@option{trigger} (default: @code{OFF})
131 132 133
to link with FxT library (trace execution of kernels on workers), can only be 
used with StarPU

134 135
@item @option{-DCHAMELEON_SIMULATION=trigger} (default: @code{OFF})
to enable simulation mode, means CHAMELEON will not really execute tasks, 
136 137 138 139 140 141 142
see details in section @ref{Use simulation mode with StarPU-SimGrid}. 
This option must be used with StarPU compiled with  
@uref{http://simgrid.gforge.inria.fr/, SimGrid} allowing to guess the 
execution time on any architecture.
This feature should be used to make experiments on the scheduler behaviors and 
performances not to produce solutions of linear systems.

143
@item @option{-DCHAMELEON_ENABLE_DOCS=trigger} (default: @code{ON})
144
to control build of the documentation contained in @file{docs/} sub-directory
145
@item @option{-DCHAMELEON_ENABLE_EXAMPLE=trigger} (default: @code{ON})
146 147
to control build of the examples executables (API usage) 
contained in @file{example/} sub-directory
148
@item @option{-DCHAMELEON_ENABLE_TESTING=trigger} (default: @code{ON})
149 150
to control build of testing executables (numerical check) contained in 
@file{testing/} sub-directory
151
@item @option{-DCHAMELEON_ENABLE_TIMING=trigger} (default: @code{ON})
152 153 154
to control build of timing executables (performances check) contained in 
@file{timing/} sub-directory

155
@item @option{-DCHAMELEON_PREC_S=trigger} (default: @code{ON})
156
to enable the support of simple arithmetic precision (float in C)
157
@item @option{-DCHAMELEON_PREC_D=trigger} (default: @code{ON})
158
to enable the support of double arithmetic precision (double in C)
159
@item @option{-DCHAMELEON_PREC_C=trigger} (default: @code{ON})
160
to enable the support of complex arithmetic precision (complex in C)
161
@item @option{-DCHAMELEON_PREC_Z=trigger} (default: @code{ON})
162 163 164 165 166 167 168 169 170 171
to enable the support of double complex arithmetic precision (double complex 
in C)

@item @option{-DBLAS_VERBOSE=trigger} (default: @code{OFF})
to make BLAS library discovery verbose
@item @option{-DLAPACK_VERBOSE=trigger} (default: @code{OFF})
to make LAPACK library discovery verbose (automatically enabled if 
@option{BLAS_VERBOSE=@code{ON}})
@end table

172
List of CHAMELEON options that needs a specific value:
173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
@table @code
@item @option{-DBLA_VENDOR=@option{var}} (default: @option{empty})
The possible values for @option{var} are:
@table @code
@item empty
@item all
@item Intel10_64lp
@item Intel10_64lp_seq
@item ACML
@item Apple
@item Generic
@item ...
@end table
to force CMake to find a specific BLAS library, see the full list of BLA_VENDOR 
in @file{FindBLAS.cmake} in @file{cmake_modules/morse/find}.
By default @option{BLA_VENDOR} is empty so that CMake tries to detect all 
possible BLAS vendor with a preference for Intel MKL.
@end table

192
List of CHAMELEON options which requires to give a path:
193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
@table @code
@item @option{-DLIBNAME_DIR=@option{path}} (default: empty)
root directory of the LIBNAME library installation
@item @option{-DLIBNAME_INCDIR=@option{path}} (default: empty)
directory of the LIBNAME library headers installation
@item @option{-DLIBNAME_LIBDIR=@option{path}} (default: empty)
directory of the LIBNAME libraries (.so, .a, .dylib, etc) installation
@end table
LIBNAME can be one of the following: BLAS - CBLAS - FXT - HWLOC - 
LAPACK - LAPACKE - MAGMA - QUARK - STARPU - TMG
See paragraph about @ref{Dependencies detection} for details.

Libraries detected with an official CMake module (see module files in 
@file{CMAKE_ROOT/Modules/}):
@itemize @bullet
@item CUDA
@item MPI
@item Threads
@end itemize

213 214
Libraries detected with CHAMELEON cmake modules (see module files in 
@file{cmake_modules/morse/find/} directory of CHAMELEON sources):
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
@itemize @bullet
@item BLAS
@item CBLAS
@item FXT
@item HWLOC
@item LAPACK
@item LAPACKE
@item MAGMA
@item QUARK
@item STARPU
@item TMG 
@end itemize


@node Dependencies detection
@section 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 :
@enumerate
@item detection of dependencies through environment variables: 
  @itemize @bullet
  @item @env{LD_LIBRARY_PATH} environment variable should contain the list of 
paths 
where to find the libraries:
    @example 
    export @env{LD_LIBRARY_PATH}=$@env{LD_LIBRARY_PATH}:path/to/your/libs
    @end example
  @item @env{INCLUDE} environment variable should contain the list of paths 
where to find the header files of libraries
    @example
    export @env{INCLUDE}=$@env{INCLUDE}:path/to/your/headers
    @end example
  @end itemize

@item detection with user's given paths:
  @itemize @bullet
  @item you can specify the path at cmake configure by invoking 
  @example 
  cmake <path to SOURCE_DIR> -DLIBNAME_DIR=path/to/your/lib 
  @end example
  where LIB stands for the name of the lib to look for, example
  @example
  cmake <path to SOURCE_DIR> -DSTARPU_DIR=path/to/starpudir \
                             -DCBLAS_DIR= ...
  @end example
  @item it is also possible to specify headers and library directories 
separately, example
  @example
PRUVOST Florent's avatar
PRUVOST Florent committed
265
  cmake <path to SOURCE_DIR>                           \
266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291
  -DSTARPU_INCDIR=path/to/libstarpu/include/starpu/1.1 \
  -DSTARPU_LIBDIR=path/to/libstarpu/lib
  @end example
  @item Note BLAS and LAPACK detection can be tedious so that we provide a 
verbose mode. Use @option{-DBLAS_VERBOSE=ON} or @option{-DLAPACK_VERBOSE=ON} to 
enable it.
  @end itemize
  
@end enumerate


@c @node Dependencies compilation
@c @section Dependencies compilation

@node Use FxT profiling through StarPU
@section Use FxT profiling through StarPU

StarPU can generate its own trace log files by compiling it with the 
@option{--with-fxt} 
option at the configure step (you can have to specify the directory where you 
installed FxT by giving @option{--with-fxt=...} instead of @option{--with-fxt} 
alone). 
By doing so, traces are generated after each execution of a program which uses 
StarPU in the directory pointed by the @env{STARPU_FXT_PREFIX} environment 
variable. Example: 
@example
PRUVOST Florent's avatar
PRUVOST Florent committed
292
export @env{STARPU_FXT_PREFIX}=/home/yourname/fxt_files/
293 294
@end example

295 296
When executing a @command{./timing/...} CHAMELEON program, if it has been 
enabled (StarPU compiled with FxT and @option{-DCHAMELEON_USE_FXT=ON}), you 
297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321
can give the option @option{--trace} to tell the program to generate trace log 
files.

Finally, to generate the trace file which can be opened with 
@uref{http://vite.gforge.inria.fr/, Vite} program, you have to use the 
@command{starpu_fxt_tool} executable of StarPU. 
This tool should be in @file{path/to/your/install/starpu/bin}. 
You can use it to generate the trace file like this: 
@itemize @bullet
@item @command{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:
@item @command{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).
@end itemize 


@node Use simulation mode with StarPU-SimGrid
@section Use simulation mode with StarPU-SimGrid

Simulation mode can be enabled by setting the cmake option 
322
@option{-DCHAMELEON_SIMULATION=ON}.
323 324 325
This mode allows you to simulate execution of algorithms with StarPU compiled 
with @uref{http://simgrid.gforge.inria.fr/, SimGrid}.
To do so, we provide some perfmodels in the @file{simucore/perfmodels/} 
326
directory of CHAMELEON sources.
327 328 329 330 331 332 333 334 335 336 337 338 339 340 341
To use these perfmodels, please set the following
@itemize @bullet
@item @env{STARPU_HOME} environment variable to:
  @example
  @code{<path to SOURCE_DIR>/simucore/perfmodels}
  @end example
@item @env{STARPU_HOSTNAME} environment variable to the name of the machine to 
simulate. For example, on our platform (PlaFRIM) with GPUs at Inria Bordeaux
  @example
  @env{STARPU_HOSTNAME}=mirage
  @end example
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.
@end itemize