Skip to content

cfsdeps

Jump to bottom
felhub edited this page Sep 22, 2025 · 30 revisions

title: CFSDEPS

Writing and Modifying cfsdeps

Module layout

CFS uses CMake ExternalProject to integrate all dependencies. The ExternalProject is defined to contain all desired dependencies, so that they can generically be downloaded, patched, configured, built and copied to the BIN directory.

The configuration is located in 'cfsdeps//External_.cmake', e.g. 'cfsdeps/feast/External_FEAST.cmake' for the FEAST eigensolver.

The source code is automatically downloaded from publicly available online sources and from a backup mirror hosted by the project. The configuration files are included to the cmake project in the file 'cmake_modules/FindCFSDEPS.cmake'. Almost all dependencies are meanwhile switched to the new scheme using kind of a object-orientated approach where steps in the process have macros in 'cmake_modules/DependencyTools.cmake' which can be replaced with local solution for a specific dependecy.

Each download is checked by a md5-checksum. The checked file is placed in 'CFS_DEPS_CACHE_DIR/sources/'. CMake will check these files for subsequent builds, so if the correct file is there, no new download is done. For adding a new dependency, you typically have to create the checksum on your own, e.g., using the tool 'md5sum' on the downloaded '.zip' file of the dependency.

Personal configuration

Note that you can set your personal build instructions and define your personal CFS_DEPS_CACHE_DIR by adding a file with the name .cfs_platform_defaults.cmake to your home directory. The file could look, e.g., like

set(USE_SUITESPARSE_DEFAULT ON)
set(BUILD_TESTING_DEFAULT ON)
set(CFS_DEPS_CACHE_DIR_DEFAULT "~/cfsdepscache")
# debug mode
if(CFS_BINARY_DIR MATCHES "cfs_debug")
  set(DEBUG_DEFAULT ON)
  set(USE_OPENMP_DEFAULT OFF)
endif()

Matrix of template dependencies

Using CMake:

  • examples: arpack, cgal (header only), cgns, dumas, eigen (header only), feast, flann, gidpost, hdf5, metis, muparser, netlib, openblas, scpip, sgp, snopt, suitesparse, superlu, vtk, xerces, zlib, lz4
  • via set_deps_args_default() default CMake options are set (e.g. compiler flags) which can be extended.
  • use_c_and_fortran(ON OFF) controls the compiler name and version in the precompiled dependency zip files (here only C/C++ but not Fortran).

Using configure:

  • examples: hsl, ipopt, libxml2, lis, gmp, mpfr
  • set_configure_default() prepares the variable DEPS_CONFIGURE which is to be extended
  • we need instal via install_dir, see further below

Using some exotic build system:

  • example: boost
  • if e.g. legacy make is used, one might consider to provide a own CMakeLists.txt, see Using CMake not originally or differently further below

Using CMake and setting own compiler options:

  • example: feast, vtk
  • via set_deps_args_default(OFF) the compiler flags are not set automatically

Install via manifest.txt:

  • examples: dumas, feast, gidpost, arpack, hdf5, cgns, vtk, sgp, muparser, scpip
  • each CMake project generates a manifest.txt with the files to install. We build directly to the cfs build dir and from there pack the files for the precompiled zip.
  • set(DEPS_INSTALL "${CMAKE_BINARY_DIR}") and generate_packing_script_manifest()
  • if there are too much files, one can use the install_dir also for CMake projects

Install via install_dir:

  • examples: libxml2, flann, lis, cgal (header only) snopt, boost, metis, superlu, ipopt, eigen (header only), xerces, zlib, hsl, zlib, netlib, openblas, suitesparse
  • let the package install to a temporary dir from where we create the precompiled zip and copy to the cfs build directory
  • set(DEPS_INSTALL "${DEPS_PREFIX}/install") and generate_packing_script_install_dir()
  • also for CMake projects if there are too much files

Patch the package:

  • examples: dumas, feast, flann, arpack, lis, snopt, boost, cgns, xerces, hsl, vtk, scpip, suitesparse, lz4
  • use generate_patches_script() and provide 'arpack-patch.cmake.in'

Perform a post-install-step:

  • examples: superlu, ipopt (Windows)
  • to clean specific files from libs or include
  • use generate_postinstall_script() and provide ipopt-post_install.cmake.in

Using Fortran:

  • examples: arpack, snopt, feast, scpip
  • set use_c_and_fortran(OFF ON)

Use non-standard lib names:

  • examples: boost, hdf5, ipopt, xerces, zlib
  • use either 'set_package_library_list_lib_prefix()' or 'set_package_library_list()'
  • default is set_package_library_default() which adds a library with the package name and standard pre- and postfix.

Header only:

  • examples cgal, eigen
  • uses use_c_and_fortran(OFF OFF)
  • the precompiled package has no compiler in its name

Use externally precompiled binaries:

  • example: ipopt (Windows only)

Have different External_<package>_<system>.cmake:

  • example: ipopt
  • the <package> name needs to be the same

Using CMake not originally or differently:

  • examples: snopt, scpip, feast, dumas
  • here we provide a own CMakeLists.txt by patching the package

Use non-public source:

  • examples: snopt, scpip

Adding a new dependency

  • First build the package locally and manually. For experimental use in cfs you only need to add the includes to the cfs build include and add the lib in the CMakeLists.txt of cfs where you define the calling .cc.

  • To add a new dependency, createa a new folder 'cfsdeps/<new_dependency_name>'. This folder needs a subfolder 'license', where you need to put the license file(s) of the new dependency.

  • Additionally, put your 'External<new_dependency_name>.cmake' file into 'cfsdeps/<new_dependency_name>'. Use the matrix above to find the best suited template.

  • Check for the macros in 'cmake_modules/DependencyTools.cmake' and adapt them or add new ones if necessary.

  • You must also include a new option in the 'CMakeLists.txt' file. These options are later shown in when you call 'ccmake' to configure your build. The options are usually set to a default value. You need to define your default variable in the file 'cmake_modules/platform_defaults.cmake'.

  • Add a file 'include/def_use_<new_dependency_name>.hh.in'. This file is used to set the 'define' in the source code.

  • In 'source/DataInOut/Dependencies.cc', you need to include the dependency and state its version and license.

  • In 'cmake_modules/configure_def_headers.cmake', you need to add a CONFIGURE_FILE(....) for your dependency.

  • Add an entry to 'cmake_modules/FindCFSDEPS.cmake' that includes the new 'External<new_dependency_name>.cmake' file if the dependency is activated (USE_xxx=ON)

Testing a cfsdeps dependency module

You can make/ninja/nmake a single dependency

make arpack

Everything is cleared in the build directory and the also the precompiled zip via

make clean-arpack

You can manually play with the building within the build directory in <build>/cfsdeps/arpack/src/arpack-build

Generating a patch file

to generate a patch file for the to be installed code, do

diff -Nuar <old_file> <new_file>

Do this in the root of the dependency file and have the relative path of the file in the name.

Precompiled cfsdeps

If you enable in cmake CFS_DEPS_PRECOMPILED the packages are precompiled. If enabled and no precompiled files exist, they are created.

Clone this wiki locally