Correct way to use third-party libraries in cmake project

by

Answering this question requires to cover few aspects, you will find below two sections:

  • config-file package
  • ExternalProject CMake module

config-file package

If you are looking into integrating libraries that are not built within the scope of your project, the first step is to make sure the libraries all provide a config-file package.

A config-file package usually include files like FooConfig.cmake, FooConfigVersion.cmake and FooTargets.cmake.

Generally speaking, if the library Foo is already using CMake and already provide a config-file package, configuring your project with -DFoo_DIR:PATH=/path/to/build-or-install-dir/ allow you to call find_package(Foo REQUIRED) from your own project. This will import CMake targets that you can link against your own libraries or executables.

Now if the library Foois not already using CMake, there are options:

  • Case 1:

    • (a) library Foo is already using CMake
    • (b) but do NOT provide a config-file package
    • action: I suggest to improve their build system

  • Case 2:

    • (1) library Foo is not using CMake
    • (2) and maintainer of Foo are willing to transition to CMake (or at least have the CMakeLists.txt along side their current build system)
    • action: I suggest to improve their build system

  • Case 3:

    • (1) library Foo is not using CMake
    • (2) and maintainer of Foo do not want to transition to CMake
    • (3) but maintainer are willing to generate config-file package from their current build system
    • action: I suggest to help them. This is for example what was done for Qt5, it now provides a config-file package.

  • Case 4:

    • (1) library Foo is not using CMake

    • (2) and maintainer of Foo do not want (or are not ready) to transition to CMake.

    • (3) and the current build system is not working well, or the library is difficult to build with a wider range of compiler, or does not support cross-compilation

    • action: create a project (ideally on GitHub) named foo-cmake-buildsystem that will allow to build the library by either

      • configuring the project with the path to an existing source tree
      • having the project downloading the source for you
      • this is for example done for CPython. There is a project named python-cmake-buildsystem available on GitHub

  • Case 5:

    • (1) for any reason the maintainer of Foo do not want to transition, or maintaining an alternative build system is not possible, or library is already available on the system
    • action: You could create a FindFoo.cmake that would create imported targets.
      • such file could be specific to your project or could be contributed to CMake directly
      • this is for example the case of FindOpenSSL.cmake, FindGit.cmake, …

To learn more about config-file package, see https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html

ExternalProject CMake module

If the library Foo is:

  • (1) not available on the system:
    • or can’t be installed using package manager
    • or working with the community maintaining packages (debian, conda-forge, chocolatey, …) to have such package is not possible
  • (2) or need to be compiled specially for your project

Then, the ExternalProject CMake module will allow you to download, configure, build … these projects from within your own project.

There are few approaches to make this happen.

Here is one that has been working well: You could setup a 2-level build system that we call: SuperBuild.

To support the SuperBuild approach, your CMakeLists.txt could have the following structure:

project(AwesomeProject)

[...]

option(Awesome_ENABLE_EXTRA "Enable more awesome stuff" OFF)

option(AwesomeProject_SUPERBUILD "Build ${PROJECT_NAME} and the projects it depends on." ON)

[...]

if(AwesomeProject_SUPERBUILD)
  include("${CMAKE_CURRENT_SOURCE_DIR}/SuperBuild.cmake")
  return()
endif()

find_package(Foo REQUIRED)

add_library(AwesomeLib ....)
target_link_libraries(AwesomeLib PUBLIC Foo)

[...]

Then, in the file SuperBuild.cmake you would roughly have these two calls:

ExternalProject_Add(Foo
  GIT_REPOSITORY "git://github.com/Foo/Foo"
  GIT_TAG "123456"
  SOURCE_DIR ${CMAKE_BINARY_DIR}/Foo
  BINARY_DIR ${CMAKE_BINARY_DIR}/Foo-build
  CMAKE_CACHE_ARGS
    -DFOO_ENABLE_BAR:BOOL=1
  INSTALL_COMMAND ""
  )


ExternalProject_Add(AwesomeProject
  SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}
  BINARY_DIR ${CMAKE_BINARY_DIR}/AwesomeProject-build
  DOWNLOAD_COMMAND ""
  UPDATE_COMMAND ""
  CMAKE_CACHE_ARGS
    -Foo_DIR:PATH=${CMAKE_BINARY_DIR}/Foo-build
    -DAwesome_ENABLE_EXTRA:BOOL=${Awesome_ENABLE_EXTRA}
  INSTALL_COMMAND ""
  )

This means that you usual build tree will now be found in the subdirectory AwesomeProject-build.

Note that Foo-build and AwesomeProject-build are two independent build tree, the link between them
is the config-file package discussed above.

This is made possible by configuring AwesomeProject sub project with -Foo_DIR:PATH=${CMAKE_BINARY_DIR}/Foo-build
and the calling find_package(Foo REQUIRED).

If you use tools like VisualStudio you can open the solution file found in any of these sub-directory.

To learn more about external project: https://cmake.org/cmake/help/latest/module/ExternalProject.html

conclusion

There are many more details, but I hope this will allow you to get a better understanding of what is possible.

More Related Contents:

  1. CMake link to external library
  2. Hinting Find.cmake Files with a custom directory
  3. What’s the CMake syntax to set and use variables?
  4. Is it better to specify source files with GLOB or each file individually in CMake?
  5. CMake does not find includes / libraries
  6. CMake + GoogleTest
  7. How to specify a compiler in CMake?
  8. Passing compiler options cmake
  9. What use is find_package() when you need to specify CMAKE_MODULE_PATH?
  10. CMake: Print out all accessible variables in a script
  11. How do I change the working directory for my program
  12. Environment variable used by CMake to detect Visual C++ compiler tools for Ninja
  13. Why add header files into ADD_LIBRARY/ADD_EXECUTABLE command in CMake
  14. CMake : How to get the name of all subdirectories of a directory?
  15. MacOS, CMake and OpenMP
  16. What is CMake equivalent of ‘configure –prefix=DIR && make all install ‘?
  17. cmake: Selecting a generator within CMakeLists.txt
  18. Setting CMAKE_INSTALL_PREFIX from CMakeLists.txt file
  19. Tell CMake to use C++ compiler for C files coming from CMake?
  20. CMake target_link_libraries Interface Dependencies
  21. What is common way to split string into list with CMAKE?
  22. Add external libraries to CMakeList.txt c++
  23. Using CMake, how do I get verbose output from CTest?
  24. How can I add linker flag for libraries with CMake?
  25. How to configure Eclipse CDT for cmake?
  26. Passing compiler options in CMake command line
  27. How to strip trailing whitespace in CMake variable?
  28. Linking GLEW with CMake
  29. How to print all the properties of a target in cmake?
  30. How to add a custom build type to CMake? (targeting make)

Leave a Comment