Install from source files#

After downloading XLiFE++ from the Download XLiFE++ page, you have to unzip the archive at any place you choose in the file system. Then, you follow configuration procedure by setting at least a C++ compiler, paths to Gmsh and Paraview and eventually paths to external libraries BLAS, LAPACK, Arpack and UmfPack. When done, you will have to compile XLiFE++ source code.

How XLiFE++ sources are organized#

XLiFE++ sources are organized with several directories, described as follows for the main ones:

bin: contains the xlifepp_project_setup.exe for Windows and the user scripts xlifepp.sh and xlifepp.bat. This will be explained later.
etc: contains a lot of stuff such as templates for installation, the multilingual files, …
examples: contains example files ready to compile and use.
ext: contains source files for external dependencies, such as Arpack, Eigen, Amos libraries
src: contains all C++ sources of the XLiFE++ library
tests: contains all unitary and system tests to check your installation
lib: will contain the static libraries of XLiFE++, after the compilation step.
usr: contains the user files to write and compile a C++ program using XLiFE++

You also have a very important file CMakeLists.txt, that is the Cmake compilation script.

How to configure installation process#

Caution

In the following, we will consider Cmake used in command-line mode, from a build directory directly inside sources so that the path to CMakeLists.txt file is ..

Installation options that will be explained can be set directly through GUI applications.

Important

cmake options are cache entries, that is to say entries being stored in CMakeCache.txt. As a result, you can re-run cmake without setting the same options again. With GUI applications, you just have to set them.

cmake .. [options]
cmake ..

The default build configuration is to use Eigen and Amos libraries, as they are provided directly by XLiFE++, and multi-threading with OpenMP, if the compiler is compatible with it (for instance, clang++ on macOS is not).

So, the first thing to do is to run/set cmake by eventually using one or several options among the following:

CMAKE_CXX_COMPILER:: to define the C++ compiler
CMAKE_Fortran_COMPILER:: to define the FORTRAN compiler, used for the compilation of Amos, and eventually Arpack, … Please notice the spelling, as Cmake is case-sensitive!!
CMAKE_BUILD_TYPE:: to define the build type: Release (the default), Debug or RelWithDebInfo
-G:: to define the generator name. The default generator is Unix Makefiles on Unix/Linux and macOS computers, and MinGW Makefiles on Windows, but it can have a wide range of possible values. For instance, if you want to generate a CodeBlocks project on Unix/Linux computer, you may choose Codeblocks - Unix Makefiles. To know what you can do, please consult Cmake help by running cmake –help. At the end, you will see the full list of available generators.

$ cmake .. [-G"<generator-name">] [-DCMAKE_BUILD_TYPE=<build-type>] [-DCMAKE_CXX_COMPILER=<your-compiler>] [-DCMAKE_Fortran_COMPILER=<your-compiler>]

Attention

When we say “run”, we say that neither you truly run the cmake nor you set the cache entries and wait to set the other before truly running cmake

In the following, we will focus on cache entries you may have to set to configure XLiFE++.

Hint

When Cmake is running, it stores values of cache entries in a cache file CMakeCache.txt in the build directory. As a result, when you run again Cmake, you are not forced to give already given options.

To activates all dependencies, you can type the following:

$ cmake .. [other_options] -DXLIFEPP_DEPS=ENABLE_ALL

XLIFEPP_DEPS: Default value is “DEFAULT”. Other possible values are “ENABLE_ALL” or “DISABLE_ALL”.

Tip

When you use Cmake GUI application, option XLIFEPP_DEPS is useless, as the list of specific options discussed in the following warning are displayed as checkboxes.

For every external dependency, Cmake search files in standard environment paths and in specific paths defined in Cmake configuration script. So if external dependencies are installed by package managers, Cmake will find them.

If it is not the case, or if the library found is not the one you want to use, you can tell Cmake where to find them, as we will see in the following.

Hint

If you don’t want to activate every external dependency, but only some of them, you may use a subset of the following options (default behavior in bold):

XLIFEPP_ENABLE_ARPACK: To enable/disable use of Arpack. Possible values are ON or OFF.
XLIFEPP_ENABLE_UMFPACK: To enable/disable use of UmfPack. Possible values are ON or OFF.
XLIFEPP_ENABLE_AMOS: To enable/disable use of Amos. Possible values are ON or OFF.
XLIFEPP_ENABLE_OPENCASCADE: To enable/disable use of OpenCASCADE. Possible values are ON or OFF.
XLIFEPP_ENABLE_OMP: To enable/disable use of OpenMP. Possible values are ON or OFF.
XLIFEPP_ENABLE_EIGEN: To enable/disable use of Eigen. Possible values are ON or OFF. Default is the same as XLIFEPP_ENABLE_OMP, as Eigen needs OpenMP.
XLIFEPP_ENABLE_MAGMA: To enable/disable use of Magma. Possible values are ON or OFF.

Configuring paths to Gmsh and Paraview executables#

To set paths to Gmsh and Paraview executables, you may use the following options:

XLIFEPP_GMSH_EXECUTABLE:: to set the full path to Gmsh executable
XLIFEPP_PARAVIEW_EXECUTABLE:: to set the full path to Paraview executable

macOS

You have to set the full path to Gmsh/Paraview executables and not applications (.app files). Executables are inside applications. If application names are Gmsh.app and paraview.app and are located in the Applications directory, Gmsh and Paraview executables will be correctly detected.

So your call to Cmake will look like:

$ cmake .. [other_options] -DXLIFEPP_GMSH_EXECUTABLE=path/to/gmsh/executable -DXLIFEPP_PARAVIEW_EXECUTABLE=path/to/paraview/executable

Configuring dependency on FORTRAN library#

IF you want to set dependency on BLAS, LAPACK, Arpack and/or UmfPack, you will have to set the path to FORTRAN library.

If you use g++, you have nothing to do as it is provided by gcc suite. The same goes for Intel compiler.

macOS

First, FORTRAN library is not installed by default. SO you have to install it with your favourite package manager, such as brew, by installing gcc itself.

Then, clang++ is not able to find FORTRAN library. To do so, you just have to use the option XLIFEPP_FORTRAN_LIB_DIR:

$ cmake .. [other_options] -DXLIFEPP_FORTRAN_LIB_DIR=path/to/gfortran/library/directory

Attention

Setting the directory is sufficient only if the FORTRAN library name is standard, such as libgfortran.a, libgfortran.so, libgfortran.dylib, libgfortran.dll, gfortran.lib, … If ever it is not the case, prefer using option XLIFEPP_FORTRAN_LIB instead, to set the full path to FORTRAN library

Configuring dependency on BLAS and LAPACK libraries#

Normally, BLAS and LAPACK are automatically detected if they are installed. But if they are not found, in order to tell to Cmake where to find BLAS library, you just have to set the directories containing BLAS and LAPACK libraries, with the options XLIFEPP_BLAS_LIB_DIR and XLIFEPP_LAPACK_LIB_DIR

So your call to Cmake will look like:

$ cmake .. [other_options] -DXLIFEPP_BLAS_LIB_DIR=path/to/blas/library/directory -DXLIFEPP_LAPACK_LIB_DIR=path/to/lapack/library/directory

Attention

Setting the directory is sufficient only if the BLAS library name is standard, such as libblas.a, libblas.so, libblas.dylib, libblas.dll, blas.lib, … (the same goes for LAPACK) If ever it is not the case (meaning that BLAS and/or LAPACK are not installed properly, for instance with a version number as a suffix), prefer using options XLIFEPP_BLAS_LIB and XLIFEPP_LAPACK_LIB instead, to set the full path to BLAS and LAPACK libraries

Windows

If you downloaded binary libraries of BLAS and LAPACK provided by the XLiFE++ website, as recommended in Third-party extensions, it will be something like (if you downloaded 64bits binaries):

$ cmake .. [other_options] -DXLIFEPP_BLAS_LIB_DIR="C:/.../lapack-3.5.0_64" -DXLIFEPP_LAPACK_LIB_DIR="C:/.../lapack-3.5.0_64"

Configuring dependency on Arpack library#

First, you have to choose if you want to use the internal Arpack distribution of XLiFE++, or an external one. Of course, the one provided by XLiFE++ is detected automatically. To select the rightful mode, you have to set the option:

XLIFEPP_SYSTEM_ARPACK: To choose an external distribution of Arpack or the one provided by XLiFE++. Possible values are ON or OFF. Default is OFF, to use the distribution provided by XLiFE++

If you choose to use an external distribution of Arpack, you now have to tell Cmake where to find Arpack library. To do so, you just have to set the directory containing the Arpack library, with the option XLIFEPP_ARPACK_LIB_DIR:

$ cmake .. [other_options] -DXLIFEPP_BLAS_LIB_DIR=path/to/blas/library/directory

Attention

Setting the directory is sufficient only if the Arpack library name is standard, such as libarpack.a, libarpack.so, libarpack.dylib, libarpack.dll, arpack.lib, … If ever it is not the case (meaning that Arpack is not installed properly, for instance with a version number as a suffix), prefer using option XLIFEPP_ARPACK_LIB instead, to set the full path to Arpack library

Windows

If you downloaded binary libraries of Arpack provided by the XLiFE++ website, as recommended in Third-party extensions, it will be something like (if you downloaded 64bits binaries):

$ cmake .. [other_options] -DXLIFEPP_ARPACK_LIB_DIR="C:/.../ARPACK_64/lib_mingw64"

Configuring dependency on UmfPack libraries#

UmfPack is a part of SuiteSparse distribution (that also contains amd, colamd, camd, ccolamd, cholmod, metis, and suitesparseconfig, …).

To tell to Cmake where to find UmfPack library/SuiteSparse distribution, you just have to set the home directory containing the SuiteSparse distribution, with the option XLIFEPP_SUITESPARSE_HOME_DIR:

$ cmake .. [other_options] -DXLIFEPP_SUITESPARSE_HOME_DIR=path/to/suitesparse/home/directory

windows

If you downloaded binary libraries provided by the XLiFE++ website, as recommended in Third-party extensions, it will be something like (if you downloaded 64bits binaries):

$ cmake .. [other_options] -DXLIFEPP_SUITESPARSE_HOME_DIR="C:/.../SuiteSparse_64"

Hint

Metis is not always installed when installing SuiteSparse, so this dependency is not necessary when setting UmfPack. In this case, XLiFE++ installation process will tell you Metis is not found by this has no consequence.

Hint

If setting XLIFEPP_SUITESPARSE_HOME_DIR is not enough to find every library of SuiteSparse distribution, you can use specific options of the form:

XLIFEPP_XXX_INCLUDE_DIR: to specify the XXX header, where XXX can be AMD, COLAMD, CAMD, CCOLAMD, CHOLMOD, METIS, SUITESPARSECONFIG or UMFPACK.
XLIFEPP_XXX_LIB_DIR: to specify the XXX library, where XXX can be AMD, COLAMD, CAMD, CCOLAMD, CHOLMOD, METIS, SUITESPARSE (only on macOS), SUITESPARSECONFIG or UMFPACK.

Setting the directories is sufficient only if the SuiteSparse library names are standard, such as libamd.a, libamd.so, libamd.dylib, libamd.dll, amd.lib, … (the same goes for the other libraries) If ever it is not the case (meaning that SuiteSparse is not installed properly, for instance with a version number as a suffix), prefer using option XLIFEPP_XXX_LIB instead, to set the full path to SuiteSparse libraries, where XXX can be AMD, COLAMD, CAMD, CCOLAMD, CHOLMOD, METIS, SUITESPARSE (only on macOS), SUITESPARSECONFIG or UMFPACK.

Configuring dependency on Magma library#

To tell to Cmake where to find Magma library, you just have to set the directory containing the Magma library, with the option XLIFEPP_MAGMA_LIB_DIR and the directory containing the Magma header files, with the option XLIFEPP_MAGMA_INCLUDE_DIR:

$ cmake .. [other_options] -DXLIFEPP_MAGMA_LIB_DIR=path/to/magma/library/directory -DXLIFEPP_MAGMA_INCLUDE_DIR=path/to/magma/include/directory