************ Installation ************ CMake ===== The simplest method to install the library and build the examples is to use CMake. For the default install, we suggest the following. First, extract the source :: tar -zxvf yee_crbc_lib.tar.gz We suggest building the library in a separate directory. For this example we will call the directory 'build'. Then, we simply have to invoke CMake. :: mkdir build cd build cmake ../yee_crbc_lib make make install This will install the library and build the examples. The library uses some functionality of C++11. For most modern compilers, we have found that it is not necessary to include any special compiler flags to use these features (e.g. Intel 15+, GNU 4.8+). However, some compilers do require we specifically tell it to use C++11. At this time it appears that CMake only identifies these flags correctly for the GNU compilers, so it may be necessary to tell CMake to include the appropriate flag. For example: :: cmake ../yee_crbc_lib -DCMAKE_CXX_FLAGS:STRING=-std=c++11 The correct flag varies by compiler. Also note that if your compiler uses the GNU STL implementation, it is necessary that the GNU library version be >=4.8. Options ------- There are additional options that can be enabled. Shared Library ^^^^^^^^^^^^^^ To build the shared version of the library use the command :: -DBUILD_SHARED="ON" Install Path ^^^^^^^^^^^^ The default install places the library file in ``/usr/local/lib`` and places the header files in ``/usr/local/include/yeecrbc``, although this behavior can vary from system to system. The install can be changed to place the library in ``/usr/lib`` and the headers in ``/usr/include/yeecrbc``, for example, by adding the following CMake option. :: -DCMAKE_INSTALL_PREFIX:PATH=/usr Example Locations ^^^^^^^^^^^^^^^^^ By default the examples are built in the build directory, so they can be found in /build/examples. They can be built at another location by setting the ``example_dir`` variable. From the command line you can change by adding the option :: -Dexample_dir:STRING="" Index and Data Types ^^^^^^^^^^^^^^^^^^^^ The defaults are to use the ``int`` type for indexing and the ``double`` type for the field data type and coefficient data type. In the C interfaces, the indexing type can be changed to the ``long int`` or ``long long`` data type by adding the following command line options to the CMake invocation :: -DINDEX_TYPE:STRING="long int" or :: -DINDEX_TYPE:STRING="long long" Similarly, the data type we use for a majority of the computations can be changed from the default type of ``double`` to ``float`` by adding the following :: -DUSE_CRBC_SCALAR_FLOAT="ON" and the coefficient data type can be changed from ``double`` to ``float`` with :: -DUSE_CRBC_COEF_FLOAT="ON" Note that the underlying C++ code and interfaces is templated on the index and data types, so these commands only affect the C interfaces. Save and Restart ^^^^^^^^^^^^^^^^ The library includes the optional ability to save the state of the boundary updater and restart from a previously saved state. This functionality requires the use of the HDF5 library. To enable this function from the command line add the following to the CMake invocation :: -DUSE_HDF5_RESTARTS=ON Threading ^^^^^^^^^ Another option is to enable OpenMP threading. To do this, add :: -DUSE_OPENMP=ON Debugging ^^^^^^^^^ To build in Debug mode, add :: -DCMAKE_BUILD_TYPE=Debug Some additionaly error checking and messages can be enabled with the option :: -DENABLE_EXTRA_DEBUG="ON" Note that builds with these options enabled significantly degrades performance. Linking ------- CMake Linking ^^^^^^^^^^^^^ In order to link with Cmake, a ``CMakeLists.txt`` file should include :: find_package(yeecrbc REQUIRED) target_link_libraries(foo yeecrbc) Depending on the install location Cmake may or may not be able to locate the libraries configuration file. If it is not found, the variable ``yeecrbc_DIR`` needs to be set to the install location. Using the default install settings this can be done with the following CMake command :: -Dyeecrbc_DIR=/usr/local/lib Alternatively, this can be set in the ``CMakeLists.txt`` file by adding :: set(yeecrbc_DIR "/usr/local/lib") Manual Linking ^^^^^^^^^^^^^^ To link to the library, add ``-lyeecrbc`` to the compile string. If the library was not installed in a standard path, it is necessary to provide the path to the library and the header files. For example, using the typical default install settings :: -L/usr/local/lib -lyeecrbc -I/usr/local/include/yeecrbc Since the majority of the library is written in C++, ``-lstdc++`` is often needed to compile. If the HDF5 restart capability is enabled, the HDF library also needs to be included in the linking. Typically, this is done with ``-lhdf5``. If the threading is enabled, the appropriate OpenMP compiler flag needs to be included. For the GNU compilers, the flag is ``-fopenmp``; for Intel compilers, the flag is ``-openmp``; and for Portland Group compilers, the flag is ``-mp``. Running Dynamically Linked Executables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When using the shared version of the library, it may be necessary to provide the path to the library when executing a program. There are a number of way to do this, but the easiest way to do this is to specify the LD_LIBRARY_PATH. For example (in bash) :: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib Uninstalling ============ To uninstall the library, simply delete the file ``/usr/local/lib/libyeecrbc.a`` and the folder ``/usr/local/include/yeecrbc``. Note that the location of the include folder and the library file may vary from system to system and depends on the install configurations. In general the paths are ``/lib/libyeecrbc.a`` and ``/include/crbc``.