Brief tour to demonstrate concepts/capabilities

Objectives

Get a feel for how CMake looks.
See 2-3 use cases where CMake shines (environment/library discovery, code generation, testing, modular code structure, Fortran 90 support).
The goal here is not to focus on syntax or details but rather the big picture and the potential.

Note

To follow-along in your terminal you can clone or download the tutorial repository (https://github.com/coderefinery/cmake-workshop):

$ git clone https://github.com/coderefinery/cmake-workshop.git

You find the example in the content/examples/calculator/ folder.

We will discuss an example project “calculator” which can add and subtract and is a mixed Fortran-C++ project with the following layout:

calculator/
├── CMakeLists.txt
├── src
│   ├── add.f90
│   ├── calculator.h
│   ├── CMakeLists.txt
│   ├── git-version.cmake
│   ├── main.cpp
│   ├── subtract.f90
│   └── version-template.h
└── test
    ├── calculator.cpp
    ├── CMakeLists.txt
    └── driver.cpp

Before we have a closer look we open up the top-level CMakeLists.txt and for the moment comment out the part with the testing. We will bring it back later:

# stop if CMake version is below 3.0
cmake_minimum_required(VERSION 3.0 FATAL_ERROR)

# project name and supported languages
project(example VERSION 1.0.0 LANGUAGES CXX Fortran)

# require C++11
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_EXTENSIONS OFF)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# specify where to place binaries and libraries
# so they end up in standard places with "make install"
include(GNUInstallDirs)
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR})
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR})
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_BINDIR})

# process src/CMakeLists.txt
add_subdirectory(src)

# enable testing
enable_testing()

# process test/CMakeLists.txt
add_subdirectory(test)

Now we build the project and observe what it means to build out of source.
```
$ cmake -S. -Bbuild
$ cmake --build build
```
But many people (especially CMake old-timers like the presenter) do this instead with Unix Makefiles:
```
$ mkdir build
$ cd build
$ cmake ..
$ make
```

We also run the compiled binary:

$ ./bin/calculator.x

Running calculator version v1.0.0
Configure-time Git hash: fca3425

2 + 3 = 5
2 - 3 = -1

We browse and discuss the main CMakeLists.txt and also src/CMakeLists.txt.

We discuss how the Git hash ends up in the generated version.h with the help of:

# in case Git is not available, we default to "unknown"
set(GIT_HASH "unknown")

# find Git and if available set GIT_HASH variable
find_package(Git QUIET)

if(GIT_FOUND)
  execute_process(
    COMMAND ${GIT_EXECUTABLE} --no-pager show -s --pretty=format:%h -n 1
    OUTPUT_VARIABLE GIT_HASH
    OUTPUT_STRIP_TRAILING_WHITESPACE
    WORKING_DIRECTORY
      ${PROJECT_SOURCE_DIR}
    ERROR_QUIET
    )
endif()

Then we re-activate the testing, reconfigure from scratch (this is not needed but it shows the moment better when the external library is downloaded):

# enable FetchContent
include(FetchContent)

# declare where to find the dependency
FetchContent_Declare(GoogleTest
  GIT_REPOSITORY https://github.com/google/googletest.git
  GIT_TAG        release-1.11.0
  )

# bring the dependency into scope
FetchContent_MakeAvailable(GoogleTest)

# build and link the unit_tests executable
add_executable(unit_tests)
target_sources(
  unit_tests
  PRIVATE
    calculator.cpp
    driver.cpp
  )
target_link_libraries(
  unit_tests
  PRIVATE
    calculator
    gtest_main  # this target is not here, we fetch it from the web (above)
  )

# define tests
add_test(
  NAME adding
  COMMAND $<TARGET_FILE:unit_tests> --gtest_filter=calculator.add
  )
add_test(
  NAME subtracting
  COMMAND $<TARGET_FILE:unit_tests> --gtest_filter=calculator.subtract
  )

We build and run the test set:
```
$ ctest
```
We also run the test set (consisting of two tests) in parallel:
```
$ ctest -j 2
```
For the Fortran folks we create one more Fortran module and “use” it in add.f90 and demonstrate that the order does not matter and CMake figures it out.

We try the install target:

$ mkdir build
$ cd build
$ cmake -D CMAKE_INSTALL_PREFIX=/tmp/calculator-example
$ make
$ make test
$ make install