Setup

Requirements

To build the library, you'll need at minimum:

Optionally, you'll need:

Note that:

  • The C++11 thread support library, available along with any C++11 compiler on OSX/Windows/most-linux-distributions, is used for multithreading.

  • A findR.cmake looks for R and VineCopula in the default locations for linux and osx, but problems might occur with versions installed from R/RStudio. Therefore, prior to building the library, it is recommended to use:

    sudo Rscript -e 'install.packages(c("VineCopula"), lib="/usr/lib/R/library",
repos="http://cran.rstudio.com/")'

How to build the library

By default, vinecopulib is header-only. It means that we use the CMake build system, but only to build the documentation and unit-tests, and to automate installation (i.e., place headers in the usual location). If you just want to use vinecopulib, you can use the header files (located in theincludesfolder) right away.

The unix one liner (from the root folder):

mkdir build && cd build && cmake .. && make && make doc &&
sudo make install && bin/test_all

Alternatively, we provide an option to precompile compiled the library in order to save building time (and memory) via the CMake option VINECOPULIB_SHARED_LIB. In this case, source files are generated from header files and the CMake build system additionally allows to install the .dylib/.so/.dll object.

The unix one liner (from the root folder):

mkdir build && cd build && cmake .. -DVINECOPULIB_SHARED_LIB=ON && make &&
make doc && sudo make install && bin/test_all
StepShell command
Create a build foldermkdir build
Move to the created foldercd build
Create the MakeFile via cmakecmake .. (or cmake .. -DVINECOPULIB_SHARED_LIB=ON for the compiled version)
Compile the librarymake or make -j n where n is the number of cores
Build the documentation (optional)make doc
Install the library on linux/OSX (optional)sudo make install
Run unit tests (optional)bin/[test_executable]

How to install the library

To install the library without unit tests, the MakeFile can be created via cmake .. -DBUILD_TESTING=OFF. Additionally, a Debug mode is available via cmake .. -DCMAKE_BUILD_TYPE=Debug; to enable strict compiler warnings, use -DSTRICT_COMPILER=ON. Finally, note that using -DCMAKE_EXPORT_COMPILE_COMMANDS=ON is useful if one is interested in using autocomplete or linting when working with the library.

On Windows, CMake will generate Visual Studio files instead of Makefiles, the following sequence of commands can be used to perform compilation using the command prompt:

md build
cd build
cmake ..
cmake --build . --config Debug
cmake --build . --config Release
cmake --build . --config Release --target install

Instead of the cmake --build commands, the generated vinecopulib.sln file can be open in the Visual Studio GUI. Furthermore, as for linux systems, the third line can be replaced by cmake .. -DVINECOPULIB_SHARED_LIB=ON to generate the source files in order to compile vinecopulib in non-header-only mode.

The following CMake flags (given with example values) will likely come handy:

-DBOOST_ROOT=c:\local\boost_1_63_0
-DEIGEN3_INCLUDE_DIR=c:\local\eigen-eigen-da9b4e14c255
-DCMAKE_INSTALL_PREFIX=c:\local\vinecopulib-install
-DCMAKE_GENERATOR_PLATFORM=x64
-DBOOST_DEBUG=1

How to include the library in other projects

As a header only library

The library can be included header only by simply copying the files in your project.

Using a system install

Using make install, vinecopulib is installed in the usual location of the system, namely

  • <prefix>/include/ (for the headers),
  • <prefix>/lib/ (for the shared library when VINECOPULIB_SHARED_LIB=ON is used),
  • <prefix>/lib/cmake/vinecopulib (to allow cmake to find the library with find_package),

where <prefix> is e.g. /usr/ or /usr/local. Note that make install only copies vinecopulib.hpp in <prefix>/include/ and puts the other headers in a subfolder <prefix>/include/vinecopulib, but using #include <vinecopulib.hpp> is enough to load both bivariate and vine functions.

In a CMake project

The easiest way to include vinecopulib in another project (and to avoid writing makefiles) is to use CMake. For instance, an example projet where the source code to be linked could contain

  • a CMakeLists.txt file for the project's setup,
  • a subfolder src for the source code, containing
    • the source code,
    • another CMakeLists.txt file for the project libraries and executables.

The top-level CMakeLists.txt could be:

cmake_minimum_required(VERSION 3.2)

set(CMAKE_CXX_STANDARD 11)

project (Example)

# Setting default folders
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/bin)

# C++ compile flags
if (NOT WIN32)
 set(CMAKE_CXX_FLAGS "-std=gnu++11 -Wextra -Wall -Wno-delete-non-virtual-dtor -Werror=return-type -O2 -DNDEBUG")
endif()

# Find vinecopulib package and dependencies
find_package(vinecopulib                  REQUIRED)
find_package(Boost 1.56                   REQUIRED)
include(cmake/findEigen3.cmake            REQUIRED)
find_package(Threads                      REQUIRED)

# Set required variables for includes and libraries
# In the second line
#   * VINECOPULIB_LIBRARIES is needed if vinecopulib has been built as a
#     shared lib (does nothing otherwise).
#   * CMAKE_THREAD_LIBS_INIT is needed for some linux systems
#     (but does nothing on OSX/Windows).
set(external_includes ${VINECOPULIB_INCLUDE_DIR} ${EIGEN3_INCLUDE_DIR} ${Boost_INCLUDE_DIRS})
set(external_libs ${VINECOPULIB_LIBRARIES} ${CMAKE_THREAD_LIBS_INIT})

# Include subdirectory with project sources
add_subdirectory(src)

Assuming a single main.cpp source file (with #include <vinecopulib.hpp> at the top), the CMakeLists.txt file in /src/ could then be:

# Include header files
include_directories(${external_includes})

# Add main executable
add_executable(main main.cpp)

# Link to vinecopulib if vinecopulib has been built as a shared lib
# and to pthreads on some linux systems (does nothing otherwise)
target_link_libraries(main ${VINECOPULIB_LIBRARIES} ${CMAKE_THREAD_LIBS_INIT})