Group Actions
Engagement
  • Author Author: Jan Cumps
  • Date Created: Date Created
  • Views 681 views
  • Likes 7 likes
  • Comments 1 comment
Related
Recommended

let CMake fetch your build dependencies

Jan Cumps

When you work on a project, you often rely on external libraries and source code. If you use CMake as your build tool: it can download the artifacts for you. And make them available during build. By using FetchContent.

use case: your project needs to invoke a callback handler. This is a common case when you work with interrupts or event driven designs. You want to use an open source module that’s available on GitHub.

You tell CMake that you rely on a resource, and it will take care that the resource is available for your build process. There are a number of services that are supported. In this blog, I’m using a GitHub repository as example.

include(FetchContent)
FetchContent_Declare(callbackmanager
  GIT_REPOSITORY "https://github.com/jancumps/callbackmanager.git"
  GIT_TAG "origin/main"
  SOURCE_SUBDIR =
)

FetchContent_MakeAvailable(callbackmanager)
# sources now available at ${callbackmanager_SOURCE_DIR}

# . . .

target_sources(${CMAKE_PROJECT_NAME}
        PUBLIC
        ${CMAKE_CURRENT_SOURCE_DIR}/main.cpp
)
target_sources(${CMAKE_PROJECT_NAME}
        PUBLIC
        FILE_SET cxx_modules TYPE CXX_MODULES FILES
        ${callbackmanager_SOURCE_DIR}/callbackmanager.cpp
)

# . . .

You can configure how deep the integration with your build is:

  • just download the sources to a known destination,

  • also have CMake expose them in your build process

  • or even let CMake build those dependencies (e.g.: a library) before your build runs.

In this post, I’m using the second option. I retrieve the a GitHub repository right before build, and use the sources in the build process.

The 3rd option, where CMake also builds the fetched content, is used by Google Test. This Unit Test library has advanced integration. They take care that their GitHub repository is not just fetched. But their libraries are built and ready to get linked with your project. It’s a good examle of getting the most out of this construct.

There are many ways to link dependencies to your project. A construct that I have been using, is the GIT submodule. GIT allows you to get the content of other repositories inside your project, by adding them as a submodule of your repo. I tend to use that when the dependencies (libraries) are closely tied to the project, and I want to develop them together with the whole project. Also when I want tight IDE coding support.

CMake FetchContent GIT submodule
downloaded at CMake config time downloaded at checkout
use standard git clone requires git clone --recursive, or actions after cloning
can download archives, URLs, GIT and SVN repos git repos
less support for IDE functions like code completion, definition lookup IDE support as if the dependency code is full part of your repository
works best when you rely on a stable library works better when you are developing the libraries together with your main project, and you edit them in parallel.
on GitHub, not visible in the source code tree on GitHub, visible as part of the code tree, and you can click trough to the submodule's repo
CMake knows about these sources (FetchContent_MakeAvailable) Your CMake file has to tell what to do.
requires that you use CMake as build infra no dependency on build tool
easier if multiple libraries have a dependency on the same repo can get tricky when you have 2 or more assets that depend on the same library (e.g.: error logging infrastructure)
determine what version of the dependency to use (branch, tag, commit reference) in the CMake file determine what version of the dependency to use by checking it out. Always a commit reference.
you may need network at build time, after you did a CMake clean or reconfigure sources are on the local file system
source code tools find your "dependent" code in the source folders. Utilities like doxygen will be able to crawl over the dependencies You may have some more work to make utilities like doxygen aware of where your dependency's sources are. 
Although often you don't want/need such applications accessing the dependency sources...

  • The FetchContent_Declare declaration has this attribute:

    SOURCE_SUBDIR =

    I'm using this, because the GIT repository I want to fetch, has a CMakeLists.txt file in its root. By default, CMake will run that.

    And (in this case) I don't want that. I just want to fetch the sources, and have CMake make the location available for scripting.

    Setting SOURCE_SUBDIR to empty, takes care of that.