Initial steps in LifeV

Filesystem organization

First of all, before starting working on the code, you should design the files/directories organization. LifeV is a C++ library, which is intended to be compiled and installed on your system in order to be included and linked by your software. You can specify the install location, and you can have different versions of the library compiled in different directories (by "different versions" we mean here that you can compile LifeV for instance with different compiler options, or linking different external libraries).

A possible way to organize your directory tree is the following:

$(mylifedirectory)
   |
   |--- (subdir) ---> lifev-src (containing the library source)
   |
   |--- (subdir) ---> lifev-debug (containing the object files and the library compiled with debug symbols)
   |
   |--- (subdir) ---> lifev-opt (containg the object files and the library compiled with compiler optimization flags on)

Additional directories may be added to the previous list, namely

   |
   |--- (subdir) ---> lifev-debug-install
                           |
                           |--- (subdir) ---> include (containing the header files *.hpp and/or *.h)
                           |--- (subdir) ---> lib (containing the library files *.a and/or *.so)

(and analogously lifev-opt-install, etc,). You should however choose the best location for the install directory, according to the organization of your system (some could for instance choose /usr/local instead of $(mylifedirectory) as the parent directory for lifev-debug-install).

As a LifeV user you should probably care most of the location and organization of the install directories. There you will find all the needed files to build your software including LifeV code. The build directories could be in principle removed once the library is installed.

As a LifeV developer you will find useful to keep also the build directories, since you will work on the source code and therefore you will often need to recompile the library. Moreover, you will probably design tests for the code you develop/mantain: these tests are part of the testsuite, and are intended to be built and run inside the build directories.

Obtain the code

Please refer to the LifeV manual for detailed information on this topic.

If you have access to the LifeV CVS repository, you can check out the source code:

$ cd mylifedirectory
$ cvs -z3 -d :ext:username@cmcsforge.epfl.ch/cvsroot/lifev co -d lifev-src lifev

The previous command creates a directory lifev-src on your filesystem, and synchronizes it with the CVS repository, downloading the whole LifeV directory tree.

Build the library

LifeV build system is based on the GNU build system.

Starting from a freshly checked-out version of the source code, you generate the configure script by issuing the following command:

$ cd lifev-src
$ make -f Makefile.cvs

The configure script is used in turn to generate the Makefiles for the library:

$ cd ../lifev-debug
$ ../lifev-src/configure --enable-debug --prefix=LIFEV_INSTALL_DIR

A detailed report of the configuration procedure is dumped into file config.log (in the same directory where the configure script was invoked). In config.log you can see what choices were made by the configure script: where and which libraries were selected, whether any errors were found and in that case exactly what operation caused the exception. Please refer to that file, as a first step, in case you have issues during the library configuration.

At the end of the configuration process, you simply build and install the library:

$ make && make install

Note that you can speed up the compilation process, by exploiting the multiple-core architecture of most CPU available today: just pass the -j option to command make:

$ make -jN

This optimizes the build process for machines able to run N jobs simultaneously (so N should be <= the number of cores available on the machine). You can omit the numeric parameter N: in this case make does not limit the number of simultaneous jobs (be careful, this can heavily slow down your system...).

Test the library

A number of programs are available for testing the library functionalities. You can run them all as a bunch by issuing the following command:

$ cd lifev-debug/testsuite
$ make -jN check

This procedure takes some time, involving the compilation of all the tests and the execution of a demo application for each of them. If you are interested in one specific program (e. g. the Navier-Stokes solver benchmark), you can start working in the corresponding directory:

$ cd lifev-debug/testsuite/test_ethiersteinman
$ make -jN check
$ make link
$ ./test_ethiersteinman

Please note that the previous invokes the serial version of the application. Depending on your installation of the library and of the MPI compilers, you will have to issue the proper command string in order to run a parallel computation.

Please find more detailed information on this subject in the LifeV manual. More specifically, find here a tutorial on how to submit a parallel LifeV job on a cluster (e. g. at EPFL), and here information on how to run LifeV applications at MOX.