Ramblings on CMake

[Vagabond]

CMake Introduction

I've been spending time learning CMake. A project external to Outpost 2 I’m interested in uses it and there has been some interest expressed in Outpost Universe. Below is a high level overview of what I've digested so far. Keep in mind I'm a complete beginner to CMake and there may be minor errors in my explanation.

CMake is an open source, compiler independent, cross-platform build process manager. It was created and is maintained by Kitware. They seem to accept community commits and make frequent new releases. CMake focuses on integrating with native build environments. This means users can comfortably and simultaneously work with Visual Studio, Eclipse, MakeFiles, XCode, etc.

A good article about the history and overall purpose of Cmake: http://www.aosabook.org/en/cmake.html.

CMake comes bundled with several other closely integrated and open source applications: CTest, CPack, and CDash. Ctest is a testing client. CPack is a cross-platform packaging tool and CDash is a testing dashboard server.

Unfortunately, there seems to be a lack of easy to digest tutorials/articles on CMake. Nor are there any well rated books on the subject, including the book produced by Kitware themselves. The actual documentation is very thorough but does not provide an easy launching-pad for initially learning CMake.

Some of the first tutorials that came up in Google searches were either written for older versions of CMake, spending time working around gaps in CMake that no longer exist. One tutorial was directing the reader to structure their CMakeLists.txt in a way that was specifically discouraged by the CMake documentation.

I did find a decent tutorial here: https://cgold.readthedocs.io/en/latest/index.html. The author's first language is not English, but the material is easy to follow, seems correct, and is using a fairly recent version of CMake.

There are two basic steps in CMake. Configure and Generate. Configure builds an internal representation of the project, runs tests and prepares for the generation of platform specific files. Generate actually creates platform specific build files. You have to run Configure before Generate.

Basic output for a Configuration File:

The C compiler identification is MSVC 19.13.26132.0
The CXX compiler identification is MSVC 19.13.26132.0
Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Tools/MSVC/14.13.26128/bin/Hostx86/x86/cl.exe
Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Tools/MSVC/14.13.26128/bin/Hostx86/x86/cl.exe -- works
Detecting C compiler ABI info
Detecting C compiler ABI info - done
Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Tools/MSVC/14.13.26128/bin/Hostx86/x86/cl.exe
Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Tools/MSVC/14.13.26128/bin/Hostx86/x86/cl.exe -- works
Detecting CXX compiler ABI info
Detecting CXX compiler ABI info - done
Detecting CXX compile features
Detecting CXX compile features - done
Configuring done

Notice that during the configuration stage, among other things CMake is locating the required compilers for the system in use and checking that they are working as expected.

Two types of generators exist:

 * Single-configuration (Like MakeFiles)
 * Multi-configuration (Like Visual Studio)

The Multi-configuration generator will produce a solution for an IDE that contains multiple configurations. The default ones produced for Visual Studio are Debug, MinSizeRel, Release, and RelWithDebInfo (Release with Debug Information)

Artifacts in Visual Studio

When generating for Visual Studio, 1 Visual Studio solution and 3 projects are created. The projects are ALL_BUILD, ZERO_CHECK, and the main project (which is the name of the project provided in CMakeLists.txt). CMakeLists.txt will be contained in both the main project and the ALL_BUILD project. Visual Studio provides syntax highlighting and intellisense support for the CMake scripting language.

As of Visual Studio 2017, CMake files may be loaded directly by Visual Studio. This changes how the generated code appears in Visual Studio and eliminates several of the artifacts created by allowing CMake to complete the generation on its own. I don't have enough experience to really comment on the differences, but I would tend to allow Visual Studio to generate its own files when possible.

Revision Control and CMake

All of the files located in the CMake Build tree are meant to be temporary and not tracked by revision control. In CMake, you would not upload Visual Studio's solution (.sln) and project files. As these files are generated by CMake and should not exist on another machine say running Linux.

Basic CMakeLists.txt file
Assuming a C++ project that is contained within a single file called main.cc.

# Comments (Think of # as // in C/C++)

cmake_minimum_required(VERSION 2.8 FATAL_ERROR)

# Name of the Project. if the LANGUAGES are not included, C and C++ are assumed.
# VERSION allows for setting the project's version number (not related to CMake's version number).
project(TestProject VERSION 1.1.1)

add_executable(TestProject main.cc)

And that is it for a trivial example.

[Hooman]

Interesting. I didn't know about CTest, CPack, and CDash.

I also liked that you started on this. The idea has come up a few times, but it's easier to get traction when people can actually see an example.