Resource to Learn CMake

• An Introduction to Modern CMake

Starting Template

1cmake_minimum_required(VERSION 3.22)
2
3set(This SuperHelloWorld)
4
5project(
6    ${This}
7    VERSION 1.0.0
8    LANGUAGES C CXX
9)
10
11list(APPEND CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR})
12list(APPEND CMAKE_PREFIX_PATH ${CMAKE_BINARY_DIR})
13
14set(CMAKE_CXX_STANDARD 20)
15set(CMAKE_CXX_STANDARDCONFIGURED_FILE_INCLUDE_DIR_REQUIRED ON)
16set(CMAKE_CXX_EXTENSIONS OFF)
17
18set(LIBRARY_MY_LIB my_lib)
19set(EXE_APP app)
20
21# include(FetchContent)
22add_subdirectory(src)
23
24# message("Using FetchContent")
25# FetchContent_Declare(
26#     nlohmann_json
27#     GIT_REPOSITORY https://github.com/nlohmann/json.git
28#     GIT_TAG v3.11.2
29#     GIT_SHALLOW TRUE
30# )
31# FetchContent_MakeAvailable(nlohmann_json)

Common Commands

• 1add_library(one two.cpp three.h)

  • Declare a target called one that refers to the current directory, and list all sources files to be compiled. Only the compilation unit two.cpp will be compiled, we include the headers for IDE only.

• 1add_executable(${THIS}_exe main.cpp)

  • Same as add_library, it adds a target that refers to the current directory, and that target points to an executable.

  • We cannot use add_library and add_target at the same time. In other words, we should separate main.cpp and "source files" in separate folder.

  • For example, we can separate like

    • some_proj/app/main.cpp and
    • some_proj/src/some_lib/some_file.cpp Then write
    • some_proj/app/CMakeLists.txt
    • some_proj/src/CMakeLists.txt
    • some_proj/src/some_lib/CMakeLists.txt separately. Note that some_proj/src/CMakeLists.txt can be as simple as just one line

    1add_subdirectory(some_lib)

    as it helps point out which directory contains a CMakeLists.txt to look at.

• 1add_subdirectory(src)

  • It tells cmake compiler which directory to look for and execute a CMakeLists.txt. If the directory src contains no CMakeLists.txt file, cmake will give an exception.

• 1# src/one/CMakeLists.txt
  2target_include_directories(one PUBLIC ../../include)

  • It tells cmake our source files in the target one have included header files in other diectory such as ../../include.

  • We don't need to include it again in other target that links to one, by simply target_link_libraries (we introduce it right below) we can directly include header files in source code that one have already included.

  • If the include dir contains include/four/five.h, then we can include four/five.h in our source code.

    Note that the string to include our header file is independent of the target name we name in cmake.

  • In general, target_include_directories is used when the header files are from other directory.

• 1target_link_libraries(another PUBLIC one)

  • This is to build dependency between different targets. Which means that the target another and its downstream linkers will need library one in the compilation process.

  • Ya we have included the include directory but very likely it just contains function declarations, we need the function body definitions by linking those libraries linking the source files.

  • if PUBLIC is replaced by PRIVATE, it indicates that the downstream linkers of another do not need the library one, and another is the only target that needs one.

• 1target_compile_definitions(one PRIVATE SOME_CONSTANT="${SOME_CONSTANT}")

  • Target library one we have a constant SOME_CONSTANT defined by using #define in the header.

• 1target_compile_features(one INTERFACE cxx_std_20)

  • Require specific feature for a target.

• 1set(
  2  SOME_CONSTANT
  3  ""  # <value>
  4  CACHE
  5  STRING
  6  "Description of the cached constant"
  7)

  • SOME_CONSTANT is the variable name.

  • We set "" as a default value.

  • The value <value> can also be passed by -D argument:

    1cmake -B build -DSOME_CONSTANT=ABCDEFG

  • STRING defined the data type of the cached value <value>.

• 1if(SOME_CONSTANT STREQUAL "")
  2  message(SEND_ERROR "SOME_CONSTANT" must not be empty)
  3endif()

  • This is a standard if statement.

• 1option(COMPILE_EXECUTABLE "Whether to compile to executable" OFF)

  • It defines a boolean for cmake files to use.
  • We can pass this variable in command line by

    1cmake .. -DCOMPILE_EXECUTABLE=ON

Include Predefined CMake Functions

Usually every cmake project contains a cmake/ folder that contains custom cmake script:

1# project_root/CMakeLists.txt
2set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake/")
3include(AddGitSubModule)

• CMAKE_MODULE_PATH points to that cmake folder
• include is used to include the cmake file cmake/AddGitSubmodule.cmake. Exmaple of a .cmake file:

1# project_root/cmake/AddGitSubmodule.cmake
2function(add_git_submodule install_destination)
3    find_package(Git REQUIRED)
4
5    if (NOT EXISTS ${install_destination}/CMakeLists.txt)
6        execute_process(COMMAND ${GIT_EXECUTABLE}
7            submodule update --init --recursive -- ${install_destination}
8            WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
9        )
10    endif()
11
12    add_subdirectory(${dir})
13endfunction(add_git_submodule)

Which Folder to Create CMakeLists.txt?

• Root directory.
  • Set all necessary variables and add appropriate add_subdirectory's to look for CMakeLists.txt.
• Source file directory src.
  • It can consists of simply the add_subdirectory commands.
• Source file subdirectories src/one, src/two, ....
  • Each of the subdirectory should consists of add_library for linkage and target_include_directories to include corresponding header files.
  • If the project structure is simpler, the rules to src/<lib_name>/CMakeLists.txt can be moved down to src/CMakeLists.txt.
• Directory that does not need CMakeLists.txt.
  • Directory that contains just header files needs no CMakeLists.txt, as they will be included in target_include_directories somewhere else once needed.

Show all Constants in a CMake Project

1cmake -LAH

Special Functions to Check Variables in CMakeLists.txt

1cmake_minimum_required(VERSION 3.22)
2
3project(CMakeTutorial LANGUAGES CXX)
4set(FOO "test")
5
6add_executable(CMakeTutorial main.cpp)
7
8function(print)
9  foreach(var ${ARGN})
10    message("[${var}]: ${${var}}")
11  endforeach()
12endfunction()
13
14function(print_env)
15  foreach(var ${ARGN})
16    message("[${var}]: $ENV{${var}}")
17  endforeach()
18endfunction()
19
20print(PROJECT_NAME FOO)

• The print function will print defined constant and print_env will print the defined environment variable.

Graph Visualization of Dependencies Between cmake Files

Install graphviz

For windows we can download a .msi file for installation HERE. For mac we run brew install graphviz.

MakeFile

Scrips

We create a file called MakeFile:

1# MakeFile
2dependency:
3	cd build && cmake .. --graphviz=graph.dot && \
4    dot -Tpng graph.dot -o ../dep_graph.png
5prepare:
6	rm -rf build
7	mkdir build

and run cmake dependency.

The prepare script is also included here, it is a default command that can be run by simply calling cmake.

From my own experience on a simple hello-world project I have:

Cmake Erorr: incompatible versions of the cygwin DLL

It is a known problem in windows, go to C:\Program Files\Git\usr\bin and rename msys-2.0.dll to _msys-2.0.dll to temporarily mitigate the problem.

Later you may need to rename it back since it affects commands such as npm and yarn.

Cross Platform Built Command

Source of Study

• An Introduction to Mdern CMake

How to Build a CMake Project

1mkdir build
2cd build
3cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Debug
4VERBOSE=1 cmake --build .

How to Know Which Generator (specified by -G) is Available?

By

1cmake --help

apart from the list of available arguments, it also prints a list of available generators for us.

In my case, I get

1  Visual Studio 17 2022        = Generates Visual Studio 2022 project files.
2                                 Use -A option to specify architecture.
3  Visual Studio 16 2019        = Generates Visual Studio 2019 project files.
4                                 Use -A option to specify architecture.
5  Visual Studio 15 2017 [arch] = Generates Visual Studio 2017 project files.
6                                 Optional [arch] can be "Win64" or "ARM".
7  Visual Studio 14 2015 [arch] = Generates Visual Studio 2015 project files.
8                                 Optional [arch] can be "Win64" or "ARM".
9  Visual Studio 12 2013 [arch] = Generates Visual Studio 2013 project files.
10                                 Optional [arch] can be "Win64" or "ARM".
11  Visual Studio 11 2012 [arch] = Generates Visual Studio 2012 project files.
12                                 Optional [arch] can be "Win64" or "ARM".
13  Visual Studio 10 2010 [arch] = Deprecated.  Generates Visual Studio 2010
14                                 project files.  Optional [arch] can be
15                                 "Win64" or "IA64".
16  Visual Studio 9 2008 [arch]  = Generates Visual Studio 2008 project files.
17                                 Optional [arch] can be "Win64" or "IA64".
18  Borland Makefiles            = Generates Borland makefiles.
19  NMake Makefiles              = Generates NMake makefiles.
20  NMake Makefiles JOM          = Generates JOM makefiles.
21  ...

External Library (CMake Project)

By Direct Cloning

1git submodule add https://target/repo.git external/some_name

and then add_subdirectory(external/some_name) to seek for and execute the CMakeLists.txt.

By FetchContent

By adding include(FetchContent) in our CMakeLists.txt we can import functions

• FetchContent_Declare
• FetchContent_MakeAvailable

For example, suppose that we want to import the following CMake projects hosted in github:

1include(FetchContent)
2
3FetchContent_Declare(
4    nlohmann_json
5    GIT_REPOSITORY https://github.com/nlohmann/json.git
6    GIT_TAG v3.11.2
7    GIT_SHALLOW TRUE
8)
9FetchContent_Declare(
10    fmt
11    GIT_REPOSITORY https://github.com/fmtlib/fmt
12    GIT_TAG 9.1.0
13    GIT_SHALLOW TRUE
14)
15FetchContent_Declare(
16    spdlog
17    GIT_REPOSITORY https://github.com/gabime/spdlog
18    GIT_TAG v1.11.0
19    GIT_SHALLOW TRUE
20)
21FetchContent_Declare(
22    cxxopts
23    GIT_REPOSITORY https://github.com/jarro2783/cxxopts
24    GIT_TAG v3.0.0
25    GIT_SHALLOW TRUE
26)
27FetchContent_Declare(
28    Catch2
29    GIT_REPOSITORY https://github.com/catchorg/Catch2
30    GIT_TAG v2.13.9
31    GIT_SHALLOW TRUE
32)
33
34FetchContent_MakeAvailable(nlohmann_json)
35FetchContent_MakeAvailable(fmt)
36FetchContent_MakeAvailable(spdlog)
37FetchContent_MakeAvailable(cxxopts)
38FetchContent_MakeAvailable(Catch2)

where the GIT_TAG can be found in the release page of the corresponding repository. These library will be downloaded in build/_deps directory when we execute cmake build command.

To let our target (executable target or library target) link to these library, we run

1target_link_libraries(
2    ${LIBRARY_MY_LIB}
3PUBLIC
4    cxxopts::cxxopts
5    nlohmann_json::nlohmann_json
6    fmt::fmt
7    spdlog::spdlog
8    Catch2::Catch2
9)

The naming convention of the target is

• <project_name>:<library_name> The <project_name> and <library_name> can be traced by looking the CMakeLists.txt of the repo.

Now our target LIBRARY_MY_LIB or any target that links to it can run the following preprocessor directives:

1#include "nlohmann/json.hpp"
2#include "cxxopts.hpp"
3#include "fmt/format.h"
4#include "spdlog/spdlog.h"
5#include "catch2/catch.hpp"

By conan

Files to Create

Create a virtual environment in Python, which I name it conan, then conda activate conan and pip install conan.

As if requirements.txt in Python we have an analog in conan, we create a text file conanfile.txt in project root and add the following content:

• project_root/conanfile.txt

  1[requires]
  2nlohmann_json/3.11.2
  3fmt/9.1.0
  4spdlog/1.11.0
  5catch2/2.13.9
  6cxxopts/3.0.0
  7
  8[generators]
  9cmake_find_package
  10cmake_paths

• project_root/CMakeLists.txt

  1message("Using Conan")
  2include(${CMAKE_BINARY_DIR}/conan_paths.cmake)
  3find_package(nlohmann_json)
  4find_package(fmt)
  5find_package(spdlog)
  6find_package(Catch2)
  7find_package(cxxopts)

In Makefile of project root directory we add

1ifeq '$(findstring ;,$(PATH))' ';'
2  CONAN_FLAGS = -s compiler='Visual Studio' -s compiler.version=17 -s cppstd=20 --build missing
3else
4  CONAN_FLAGS = -s cppstd=17 --build missing
5endif
6
7prepare_conan:
8	rm -rf build
9	mkdir build
10	cd build && conan install .. $(CONAN_FLAGS)

and run make prepare_conan.

Remarks to conan

I myself fail to work with conan in windows, maybe unix based system can make it work.

In general the database of conan usually lag behind to the latest release for at least half year, it is suggested not to use it when FetchContent suffices to serve the purpose.

CMake Examples

ChatClient TCP Server

Repo and Video

The whole project implementes a chatting function between multiple clients.

• Repo Link
• Video Link

This blog post focuses on the CMakeLists.txt files.

Outermost CMakeLists.txt, the Project Level

1cmake_minimum_required(VERSION 3.22.2)
2set(CMAKE_CXX_STANDARD 20)
3
4add_subdirectory(MOYFNetworking)
5add_subdirectory(MOYFClient)
6add_subdirectory(MOYFServer)

The Main Library: Networking

1cmake_minimum_required(VERSION 3.22.2)
2project(MOYFNetworking)
3
4set(CMAKE_CXX_STANDARD 20)
5
6set(BOOST_ROOT "C:\\Users\\user\\Repos\\C++Libraries\\boost_1_80_0")
7
8
9find_package(Boost REQUIRED)
10file(GLOB_RECURSE SOURCES src/*.cpp)
11add_library(${PROJECT_NAME} ${SOURCES})
12
13# this says when building ${PROJECT_NAME} library, what follows must also be included
14target_include_directories(
15  ${PROJECT_NAME}
16  PUBLIC
17    $<INSTALL_INTERFACE:include>
18    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
19    ${Boost_INCLUDE_DIRS}
20  PRIVATE
21)
22
23# PRIVATE means downstream linkers that link to ${PROJECT_NAME}
24# library will not have access to ${Boost_LIBRARIES}
25# in other words, ${Boost_LIBRARIES} is
26# only used by the library ${PROJECT_NAME}.
27
28# If PRIVATE is replaced by PUBLIC, the downstream linkers that links
29# ${PROJECT_NAME} will be able to use those libraries (${Boost_LIBRARIES} in this case).
30target_link_libraries(
31  ${PROJECT_NAME} PRIVATE
32  ${Boost_LIBRARIES}
33)

NetClient

1cmake_minimum_required(VERSION 3.22.2)
2project(MOYFClient)
3
4set(CMAKE_CXX_STANDARD 20)
5
6add_executable(${PROJECT_NAME} main.cpp)
7
8target_include_directories(
9  ${PROJECT_NAME} PUBLIC
10    MOYFNetworking
11)
12target_link_libraries(
13  ${PROJECT_NAME} PUBLIC
14    MOYFNetworking
15)

NetServer

1cmake_minimum_required(VERSION 3.22.2)
2project(MOYFServer)
3
4set(CMAKE_CXX_STANDARD 20)
5
6add_executable(${PROJECT_NAME} main.cpp)
7
8target_include_directories(
9  ${PROJECT_NAME} PUBLIC
10  MOYFNetworking
11)
12target_link_libraries(
13  ${PROJECT_NAME} PUBLIC
14  MOYFNetworking
15  ws2_32
16)

Examples from Other Project

Sockets

Repo. https://github.com/rhymu8354/SocketTutorial

This is a CMakeLists.txt file inside a directory called Sockets.

1set(This Sockets)
2set(Sources
3    include/Sockets/ClientSocket.hpp
4    include/Sockets/DatagramSocket.hpp
5    include/Sockets/ServerSocket.hpp
6    src/Abstractions.hpp
7    src/ClientSocket.cpp
8    src/Connection.hpp
9    src/Connection.cpp
10    src/DatagramSocket.cpp
11    src/ServerSocket.cpp
12)
13if(MSVC)
14    list(APPEND Sources
15        src/AbstractionsWin32.cpp
16    )
17else()
18    list(APPEND Sources
19        src/AbstractionsPosix.cpp
20        src/PipeSignal.cpp
21        src/PipeSignal.hpp
22    )
23endif()
24
25add_library(${This} ${Sources})
26set_target_properties(${This} PROPERTIES FOLDER Libraries)
27target_include_directories(${This} PUBLIC include)
28if(UNIX)
29    target_link_libraries(${This} PUBLIC pthread)
30endif(UNIX)

From the section The-Main-Library:-Networking we have read a use case

1file(GLOB_RECURSE SOURCES src/*.cpp)

and plugged this into add_library. However, the Do's and Don'ts states that Don't GLOB files because:

Make or another tool will not know if you add files without rerunning CMake. Note that CMake 3.12 adds a CONFIGURE_DEPENDS flag that makes this far better if you need to use it.

In other words, listing the source files explicitly will be a better practice.