starpu-max/doc/doxygen/chapters/510_configure_options.doxy

/*
 * This file is part of the StarPU Handbook.
 * Copyright (C) 2009--2011  Universit@'e de Bordeaux
 * Copyright (C) 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017  CNRS
 * Copyright (C) 2011, 2012, 2017  INRIA
 * See the file version.doxy for copying conditions.
 */

/*! \page CompilationConfiguration Compilation Configuration

The behavior of the StarPU library and tools may be tuned thanks to
the following configure options.

\section CommonConfiguration Common Configuration

<dl>

<dt>--enable-debug</dt>
<dd>
\anchor enable-debug
\addindex __configure__--enable-debug
Enable debugging messages.
</dd>

<dt>--enable-spinlock-check</dt>
<dd>
\anchor enable-spinlock-check
\addindex __configure__--enable-spinlock-check
Enable checking that spinlocks are taken and released properly.
</dd>

<dt>--enable-fast</dt>
<dd>
\anchor enable-fast
\addindex __configure__--enable-fast
Disable assertion checks, which saves computation time.
</dd>

<dt>--enable-verbose</dt>
<dd>
\anchor enable-verbose
\addindex __configure__--enable-verbose
Increase the verbosity of the debugging messages.  This can be disabled
at runtime by setting the environment variable \ref STARPU_SILENT to
any value. <c>--enable-verbose=extra</c> increase even more the verbosity.

\verbatim
$ STARPU_SILENT=1 ./vector_scal
\endverbatim
</dd>

<dt>--enable-coverage</dt>
<dd>
\anchor enable-coverage
\addindex __configure__--enable-coverage
Enable flags for the coverage tool <c>gcov</c>.
</dd>

<dt>--enable-quick-check</dt>
<dd>
\anchor enable-quick-check
\addindex __configure__--enable-quick-check
Specify tests and examples should be run on a smaller data set, i.e
allowing a faster execution time
</dd>

<dt>--enable-long-check</dt>
<dd>
\anchor enable-long-check
\addindex __configure__--enable-long-check
Enable some exhaustive checks which take a really long time.
</dd>

<dt>--enable-new-check</dt>
<dd>
\anchor enable-new-check
\addindex __configure__--enable-new-check
Enable new testcases which are known to fail.
</dd>

<dt>--with-hwloc</dt>
<dd>
\anchor with-hwloc
\addindex __configure__--with-hwloc
Specify <c>hwloc</c> should be used by StarPU. <c>hwloc</c> should be found by the
means of the tool <c>pkg-config</c>.
</dd>

<dt>--with-hwloc=<c>prefix</c></dt>
<dd>
\anchor with-hwloc
\addindex __configure__--with-hwloc
Specify <c>hwloc</c> should be used by StarPU. <c>hwloc</c> should be found in the
directory specified by <c>prefix</c>
</dd>

<dt>--without-hwloc</dt>
<dd>
\anchor without-hwloc
\addindex __configure__--without-hwloc
Specify <c>hwloc</c> should not be used by StarPU.
</dd>

<dt>--disable-build-doc</dt>
<dd>
\anchor disable-build-doc
\addindex __configure__--disable-build-doc
Disable the creation of the documentation. This should be done on a
machine which does not have the tools <c>doxygen</c> and <c>latex</c>
(plus the packages <c>latex-xcolor</c> and <c>texlive-latex-extra</c>).
</dd>

<dt>--disable-icc</dt>
<dd>
\anchor disable-icc
\addindex __configure__--disable-icc
Disable the usage of the ICC compiler. When found, some specific ICC
examples are compiled.
</dd>

</dl>

Additionally, the script <c>configure</c> recognize many variables, which
can be listed by typing <c>./configure --help</c>. For example,
<c>./configure NVCCFLAGS="-arch sm_20"</c> adds a flag for the compilation of
CUDA kernels, and <c>NVCC_CC=gcc-5</c> allows to change the C++ compiler
used by nvcc.


\section ConfiguringWorkers Configuring Workers

<dl>

<dt>--enable-blocking-drivers</dt>
<dd>
\anchor enable-blocking-drivers
\addindex __configure__--enable-blocking-drivers
By default, StarPU keeps CPU workers awake permanently, for better
reactivity. This option makes StarPU put CPU workers to real sleep when there
are not enough tasks to compute.

Use at most <c>count</c> CPU cores.  This information is then
available as the macro ::STARPU_MAXCPUS.
</dd>

<dt>--enable-maxcpus=<c>count</c></dt>
<dd>
\anchor enable-maxcpus
\addindex __configure__--enable-maxcpus
Use at most <c>count</c> CPU cores.  This information is then
available as the macro ::STARPU_MAXCPUS.
</dd>

<dt>--enable-maxnumanodes=<c>count</c></dt>
<dd>
\anchor enable-maxnumanodes
\addindex __configure__--enable-maxnumanodes
Use at most <c>count</c> NUMA nodes.  This information is then
available as the macro ::STARPU_MAXNUMANODES.
</dd>

<dt>--disable-cpu</dt>
<dd>
\anchor disable-cpu
\addindex __configure__--disable-cpu
Disable the use of CPUs of the machine. Only GPUs etc. will be used.
</dd>

<dt>--enable-maxcudadev=<c>count</c></dt>
<dd>
\anchor enable-maxcudadev
\addindex __configure__--enable-maxcudadev
Use at most <c>count</c> CUDA devices.  This information is then
available as the macro ::STARPU_MAXCUDADEVS.
</dd>

<dt>--disable-cuda</dt>
<dd>
\anchor disable-cuda
\addindex __configure__--disable-cuda
Disable the use of CUDA, even if a valid CUDA installation was detected.
</dd>

<dt>--with-cuda-dir=<c>prefix</c></dt>
<dd>
\anchor with-cuda-dir
\addindex __configure__--with-cuda-dir
Search for CUDA under <c>prefix</c>, which should notably contain the file
<c>include/cuda.h</c>.
</dd>

<dt>--with-cuda-include-dir=<c>dir</c></dt>
<dd>
\anchor with-cuda-include-dir
\addindex __configure__--with-cuda-include-dir
Search for CUDA headers under <c>dir</c>, which should
notably contain the file <c>cuda.h</c>. This defaults to
<c>/include</c> appended to the value given to
\ref with-cuda-dir "--with-cuda-dir".
</dd>

<dt>--with-cuda-lib-dir=<c>dir</c></dt>
<dd>
\anchor with-cuda-lib-dir
\addindex __configure__--with-cuda-lib-dir
Search for CUDA libraries under <c>dir</c>, which should notably contain
the CUDA shared libraries---e.g., <c>libcuda.so</c>.  This defaults to
<c>/lib</c> appended to the value given to
\ref with-cuda-dir "--with-cuda-dir".
</dd>

<dt>--disable-cuda-memcpy-peer</dt>
<dd>
\anchor disable-cuda-memcpy-peer
\addindex __configure__--disable-cuda-memcpy-peer
Explicitly disable peer transfers when using CUDA 4.0.
</dd>

<dt>--enable-maxopencldev=<c>count</c></dt>
<dd>
\anchor enable-maxopencldev
\addindex __configure__--enable-maxopencldev
Use at most <c>count</c> OpenCL devices.  This information is then
available as the macro ::STARPU_MAXOPENCLDEVS.
</dd>

<dt>--disable-opencl</dt>
<dd>
\anchor disable-opencl
\addindex __configure__--disable-opencl
Disable the use of OpenCL, even if the SDK is detected.
</dd>

<dt>--with-opencl-dir=<c>prefix</c></dt>
<dd>
\anchor with-opencl-dir
\addindex __configure__--with-opencl-dir
Search for an OpenCL implementation under <c>prefix</c>, which should
notably contain <c>include/CL/cl.h</c> (or <c>include/OpenCL/cl.h</c>
on Mac OS).
</dd>

<dt>--with-opencl-include-dir=<c>dir</c></dt>
<dd>
\anchor with-opencl-include-dir
\addindex __configure__--with-opencl-include-dir
Search for OpenCL headers under <c>dir</c>, which should notably contain
<c>CL/cl.h</c> (or <c>OpenCL/cl.h</c> on Mac OS).  This defaults to
<c>/include</c> appended to the value given to
\ref with-opencl-dir "--with-opencl-dir".
</dd>

<dt>--with-opencl-lib-dir=<c>dir</c></dt>
<dd>
\anchor with-opencl-lib-dir
\addindex __configure__--with-opencl-lib-dir
Search for an OpenCL library under <c>dir</c>, which should notably
contain the OpenCL shared libraries---e.g. <c>libOpenCL.so</c>. This defaults to
<c>/lib</c> appended to the value given to
\ref with-opencl-dir "--with-opencl-dir".
</dd>

<dt>--enable-opencl-simulator</dt>
<dd>
\anchor enable-opencl-simulator
\addindex __configure__--enable-opencl-simulator
Enable considering the provided OpenCL implementation as a simulator, i.e. use
the kernel duration returned by OpenCL profiling information as wallclock time
instead of the actual measured real time. This requires simgrid support.
</dd>

<dt>--enable-maximplementations=<c>count</c></dt>
<dd>
\anchor enable-maximplementations
\addindex __configure__--enable-maximplementations
Allow for at most <c>count</c> codelet implementations for the same
target device.  This information is then available as the
macro ::STARPU_MAXIMPLEMENTATIONS macro.
</dd>

<dt>--enable-max-sched-ctxs=<c>count</c></dt>
<dd>
\anchor enable-max-sched-ctxs
\addindex __configure__--enable-max-sched-ctxs
Allow for at most <c>count</c> scheduling contexts
This information is then available as the macro
::STARPU_NMAX_SCHED_CTXS.
</dd>

<dt>--disable-asynchronous-copy</dt>
<dd>
\anchor disable-asynchronous-copy
\addindex __configure__--disable-asynchronous-copy
Disable asynchronous copies between CPU and GPU devices.
The AMD implementation of OpenCL is known to
fail when copying data asynchronously. When using this implementation,
it is therefore necessary to disable asynchronous data transfers.
</dd>

<dt>--disable-asynchronous-cuda-copy</dt>
<dd>
\anchor disable-asynchronous-cuda-copy
\addindex __configure__--disable-asynchronous-cuda-copy
Disable asynchronous copies between CPU and CUDA devices.
</dd>

<dt>--disable-asynchronous-opencl-copy</dt>
<dd>
\anchor disable-asynchronous-opencl-copy
\addindex __configure__--disable-asynchronous-opencl-copy
Disable asynchronous copies between CPU and OpenCL devices.
The AMD implementation of OpenCL is known to
fail when copying data asynchronously. When using this implementation,
it is therefore necessary to disable asynchronous data transfers.
</dd>

<dt>--enable-maxmicthreads</dt>
<dd>
\anchor enable-maxmicthreads
\addindex __configure__--enable-maxmicthreads
Specify the maximum number of MIC threads
</dd>

<dt>--disable-asynchronous-mic-copy</dt>
<dd>
\anchor disable-asynchronous-mic-copy
\addindex __configure__--disable-asynchronous-mic-copy
Disable asynchronous copies between CPU and MIC devices.
</dd>

<dt>--disable-asynchronous-mpi-master-slave-copy</dt>
<dd>
\anchor disable-asynchronous-mpi-master-slave-copy
\addindex __configure__--disable-asynchronous-mpi-master-slave-copy
Disable asynchronous copies between CPU and MPI Slave devices.
</dd>

<dt>--enable-maxnodes=<c>count</c></dt>
<dd>
\anchor enable-maxnodes
\addindex __configure__--enable-maxnodes
Use at most <c>count</c> memory nodes.  This information is then available as
the macro ::STARPU_MAXNODES. Reducing it allows to considerably reduce memory
used by StarPU data structures.
</dd>

</dl>

\section ExtensionConfiguration Extension Configuration

<dl>

<dt>--disable-mpi</dt>
<dd>
\anchor disable-mpi
\addindex __configure__--disable-mpi
Disable the build of libstarpumpi. By default, it is enabled when MPI is found.
</dd>

<dt>--with-mpicc=<c>path</c></dt>
<dd>
\anchor with-mpicc
\addindex __configure__--with-mpicc
Use the compiler <c>mpicc</c> at <c>path</c>, for StarPU-MPI.
(\ref MPISupport).
</dd>

<dt>--enable-mpi-pedantic-isend</dt>
<dd>
\anchor enable-mpi-pedantic-isend
\addindex __configure__--enable-mpi-pedantic-isend
Before performing any MPI communication, StarPU-MPI waits for the data
to be available in the main memory of the node submitting the request.
For send communications, data is acquired with the mode ::STARPU_R.
When enabling the pedantic mode, data are instead acquired with the
::STARPU_RW which thus ensures that there is not more than 1
concurrent MPI_Isend calls accessing the data.
</dd>

<dt>--enable-mpi-master-slave</dt>
<dd>
\anchor enable-mpi-master-slave
\addindex __configure__--enable-mpi-master-slave
Enable the MPI Master-Slave support. By default, it is disabled.
</dd>

<dt>--with-mpi-master-slave-multiple-thread</dt>
<dd>
\anchor with-mpi-master-slave-multiple-thread
\addindex __configure__--with-mpi-master-slave-multiple-thread
Create one thread per MPI Slave on the MPI master to manage communications.
</dd>

<dt>--enable-mpi-verbose</dt>
<dd>
\anchor enable-mpi-verbose
\addindex __configure__--enable-mpi-verbose
Increase the verbosity of the MPI debugging messages.  This can be disabled
at runtime by setting the environment variable \ref STARPU_SILENT to
any value. <c>--enable-mpi-verbose=extra</c> increase even more the verbosity.

\verbatim
$ STARPU_SILENT=1 mpirun -np 2 ./insert_task
\endverbatim
</dd>

<dt>--enable-nmad</dt>
<dd>
\anchor enable-nmad
\addindex __configure__--enable-nmad
Enable the NewMadeleine implementation for StarPU-MPI.
</dd>

<dt>--disable-fortran</dt>
<dd>
\anchor disable-fortran
\addindex __configure__--disable-fortran
Disable the fortran extension. By default, it is enabled when a
fortran compiler is found.
</dd>

<dt>--disable-socl</dt>
<dd>
\anchor disable-socl
\addindex __configure__--disable-socl
Disable the SOCL extension (\ref SOCLOpenclExtensions).  By
default, it is enabled when an OpenCL implementation is found.
</dd>

<dt>--disable-starpu-top</dt>
<dd>
\anchor disable-starpu-top
\addindex __configure__--disable-starpu-top
Disable the StarPU-Top interface (\ref StarPU-TopInterface).  By default, it
is enabled when the required dependencies are found.
</dd>

<dt>--disable-gcc-extensions</dt>
<dd>
\anchor disable-gcc-extensions
\addindex __configure__--disable-gcc-extensions
Disable the GCC plug-in (\ref cExtensions).  By default, it is
enabled when the GCC compiler provides a plug-in support.
</dd>

<dt>--with-coi-dir</dt>
<dd>
\anchor with-coi-dir
\addindex __configure__--with-coi-dir
Specify the directory to the COI library for MIC support.
The default value is <c>/opt/intel/mic/coi</c>
</dd>

<dt>--mic-host</dt>
<dd>
\anchor mic-host
\addindex __configure__--mic-host
Specify the precise MIC architecture host identifier.
The default value is <c>x86_64-k1om-linux</c>
</dd>

<dt>--enable-openmp</dt>
<dd>
\anchor enable-openmp
\addindex __configure__--enable-openmp
Enable OpenMP Support (\ref OpenMPRuntimeSupport)
</dd>

</dl>

\section AdvancedConfiguration Advanced Configuration

<dl>

<dt>--enable-perf-debug</dt>
<dd>
\anchor enable-perf-debug
\addindex __configure__--enable-perf-debug
Enable performance debugging through gprof.
</dd>

<dt>--enable-model-debug</dt>
<dd>
\anchor enable-model-debug
\addindex __configure__--enable-model-debug
Enable performance model debugging.
</dd>

<dt>--enable-fxt-lock</dt>
<dd>
\anchor enable-fxt-lock
\addindex __configure__--enable-fxt-lock
Enable additional trace events which describes locks behaviour.
</dd>

<dt>--enable-maxbuffers</dt>
<dd>
\anchor enable-maxbuffers
\addindex __configure__--enable-maxbuffers
Define the maximum number of buffers that tasks will be able to take
as parameters, then available as the macro ::STARPU_NMAXBUFS.
</dd>

<dt>--enable-allocation-cache</dt>
<dd>
\anchor enable-allocation-cache
\addindex __configure__--enable-allocation-cache
Enable the use of a data allocation cache to avoid the cost of it with
CUDA. Still experimental.
</dd>

<dt>--enable-opengl-render</dt>
<dd>
\anchor enable-opengl-render
\addindex __configure__--enable-opengl-render
Enable the use of OpenGL for the rendering of some examples.
// TODO: rather default to enabled when detected
</dd>

<dt>--enable-blas-lib=<c>prefix</c></dt>
<dd>
\anchor enable-blas-lib
\addindex __configure__--enable-blas-lib
Specify the blas library to be used by some of the examples. Librairies available :
- none [default] : no BLAS library is used
- atlas: use ATLAS library
- goto: use GotoBLAS library
- mkl: use MKL library (you may need to set specific CFLAGS and LDFLAGS with --with-mkl-cflags and --with-mkl-ldflags)
</dd>

<dt>--enable-leveldb</dt>
<dd>
\anchor enable-leveldb
\addindex __configure__--enable-leveldb
Enable linking with LevelDB if available
</dd>

<dt>--disable-hdf5</dt>
<dd>
\anchor disable-hdf5
\addindex __configure__--disable-hdf5
Disable building HDF5 support.
</dd>

<dt>--with-hdf5-include-dir=<c>path</c></dt>
<dd>
\anchor with-hdf5-include-dir
\addindex __configure__--with-hdf5-include-dir
Specify the directory where is stored the header hdf5.h.
</dd>

<dt>--with-hdf5-lib-dir=<c>path</c></dt>
<dd>
\anchor with-hdf5-lib-dir
\addindex __configure__--with-hdf5-lib-dir
Specify the directory where is stored the hdf5 library.
</dd>

<dt>--disable-starpufft</dt>
<dd>
\anchor disable-starpufft
\addindex __configure__--disable-starpufft
Disable the build of libstarpufft, even if <c>fftw</c> or <c>cuFFT</c> is available.
</dd>

<dt>--enable-starpufft-examples</dt>
<dd>
\anchor enable-starpufft-examples
\addindex __configure__--enable-starpufft-examples
Enable the compilation and the execution of the libstarpufft examples.
By default, they are neither compiled nor checked.
</dd>

<dt>--with-fxt=<c>prefix</c></dt>
<dd>
\anchor with-fxt
\addindex __configure__--with-fxt
Search for FxT under <c>prefix</c>.
FxT (http://savannah.nongnu.org/projects/fkt) is used to generate
traces of scheduling events, which can then be rendered them using ViTE
(\ref Off-linePerformanceFeedback).  <c>prefix</c> should
notably contain <c>include/fxt/fxt.h</c>.
</dd>

<dt>--with-perf-model-dir=<c>dir</c></dt>
<dd>
\anchor with-perf-model-dir
\addindex __configure__--with-perf-model-dir
Store performance models under <c>dir</c>, instead of the current user's
home.
</dd>

<dt>--with-goto-dir=<c>prefix</c></dt>
<dd>
\anchor with-goto-dir
\addindex __configure__--with-goto-dir
Search for GotoBLAS under <c>prefix</c>, which should notably contain
<c>libgoto.so</c> or <c>libgoto2.so</c>.
</dd>

<dt>--with-atlas-dir=<c>prefix</c></dt>
<dd>
\anchor with-atlas-dir
\addindex __configure__--with-atlas-dir
Search for ATLAS under <c>prefix</c>, which should notably contain
<c>include/cblas.h</c>.
</dd>

<dt>--with-mkl-cflags=<c>cflags</c></dt>
<dd>
\anchor with-mkl-cflags
\addindex __configure__--with-mkl-cflags
Use <c>cflags</c> to compile code that uses the MKL library.
</dd>

<dt>--with-mkl-ldflags=<c>ldflags</c></dt>
<dd>
\anchor with-mkl-ldflags
\addindex __configure__--with-mkl-ldflags
Use <c>ldflags</c> when linking code that uses the MKL library.  Note
that the MKL website
(http://software.intel.com/en-us/articles/intel-mkl-link-line-advisor/)
provides a script to determine the linking flags.
</dd>

<dt>--disable-glpk</dt>
<dd>
\anchor disable-glpk
\addindex __configure__--disable-glpk
Disable the use of libglpk for computing area bounds.
</dd>

<dt>--disable-build-tests</dt>
<dd>
\anchor disable-build-tests
\addindex __configure__--disable-build-tests
Disable the build of tests.
</dd>

<dt>--disable-build-examples</dt>
<dd>
\anchor disable-build-examples
\addindex __configure__--disable-build-examples
Disable the build of examples.
</dd>

<dt>--disable-build-tests</dt>
<dd>
\anchor disable-build-tests
\addindex __configure__--disable-build-tests
Disable the build of tests.
</dd>


<dt>--enable-sc-hypervisor</dt>
<dd>
\anchor enable-sc-hypervisor
\addindex __configure__--enable-sc-hypervisor
Enable the Scheduling Context Hypervisor plugin (\ref SchedulingContextHypervisor).
By default, it is disabled.
</dd>

<dt>--enable-memory-stats</dt>
<dd>
\anchor enable-memory-stats
\addindex __configure__--enable-memory-stats
Enable memory statistics (\ref MemoryFeedback).
</dd>

<dt>--enable-simgrid</dt>
<dd>
\anchor enable-simgrid
\addindex __configure__--enable-simgrid
Enable simulation of execution in simgrid, to allow easy experimentation with
various numbers of cores and GPUs, or amount of memory, etc. Experimental.

The path to simgrid can be specified through the <c>SIMGRID_CFLAGS</c> and
<c>SIMGRID_LIBS</c> environment variables, for instance:

\verbatim
export SIMGRID_CFLAGS="-I/usr/local/simgrid/include"
export SIMGRID_LIBS="-L/usr/local/simgrid/lib -lsimgrid"
\endverbatim

</dd>

<dt>--with-simgrid-dir</dt>
<dd>
\anchor with-simgrid-dir
\addindex __configure__--with-simgrid-dir
Similar to the option \ref enable-simgrid "--enable-simgrid" but also
allows to specify the location to the SimGrid library.
</dd>

<dt>--with-simgrid-include-dir</dt>
<dd>
\anchor with-simgrid-include-dir
\addindex __configure__--with-simgrid-include-dir
Similar to the option \ref enable-simgrid "--enable-simgrid" but also
allows to specify the location to the SimGrid include directory.
</dd>

<dt>--with-simgrid-lib-dir</dt>
<dd>
\anchor with-simgrid-lib-dir
\addindex __configure__--with-simgrid-lib-dir
Similar to the option \ref enable-simgrid "--enable-simgrid" but also
allows to specify the location to the SimGrid lib directory.
</dd>

<dt>--with-smpirun=<c>path</c></dt>
<dd>
\anchor with-smpirun
\addindex __configure__--with-smpirun
Use the smpirun at <c>path</c>
</dd>

<dt>--enable-simgrid-mc</dt>
<dd>
\anchor enable-simgrid-mc
\addindex __configure__--enable-simgrid-mc
Enable the Model Checker in simulation of execution in simgrid, to allow
exploring various execution paths.
</dd>

<dt>--enable-calibration-heuristic</dt>
<dd>
\anchor enable-calibration-heuristic
\addindex __configure__--enable-calibration-heuristic
Allows to set the maximum authorized percentage of deviation
for the history-based calibrator of StarPU. A correct value
of this parameter must be in [0..100]. The default value of
this parameter is 10. Experimental.
</dd>

</dl>

*/