How to build a CMake project (translated)

CMake is a tool that can help you build A/C + + project on almost any platform. Many popular open source projects use CMake, such as LLVM, Qt, KDE, and Blender.

All CMake projects contain a script called CMakelists.txt , which is written to guide how to configure and build CMake projects. This blog will not tell you how to write CMake scripts-and that would be a bit ahead of the story.

For example, I have prepared a CMake project that uses SDL2 and OpenGL to render a 3D logo, and you can build it under Windows, MacOS, or Linux. If you have not installed CMake, you can download the installer or the binary distribution version from the CMake website, or you can download the installation (Unix-like environment) through the system's package management tool.

Source and Binary folders

CMake will generate a build pipeline (builds pipelines) file. A build pipeline file might be a. sln file for Visual Studio, a. xcodeproj file for Xcode, or a UNIX-style Makefile file. Building pipeline files may also appear in other forms.

To build the build pipeline file, CMake needs to know the source directory and binary directory. The source directory will hold the CMakeLists.txt file. Binary directory to store CMake generated build pipeline files. You can put the binary directory anywhere, a common practice is to create a subdirectory named Build under CMakelist.txt as the binary directory.

By separating binary and source directories, you can delete binary directories back and forth in a clean state at any time. You can even create multiple binary directories, each corresponding to a different build system or parameter configuration.

Caching (cache) is also an important concept. It is the binary directory of a file called CMakeCache.txt, which contains cache variables (caches variables). The cache variables include user configuration options-such as the demo_enable_multisample option in Cmakedemo, and the precomputed information used to add the compilation. Binary folders are generally not added to versioning, and it is common practice to rebuild the binary directory each time clone is built.

Configuration (Configure) and build (Generate)

Several different ways to run CMake are described below. But no matter how you run it, CMake performs the following two steps: Configuration (Configure) and build (Generate).

The CMakeLists.txt is executed during the configuration phase. This script is responsible for defining the target file (Targets). Each target file can be an executable file, a library file, or other output from the build pipeline.

If the configuration stage results are complete-that is, the CMakeLists.txt runs successfully-cmake will generate a build pipeline with the CMakeLists.txt defined target file. The type of build pipeline depends on the type of generator (generator), which is explained in detail later in this section.

Depending on the content of the CMakeLists.txt, additional things can happen during the configuration phase. For example, in the Cmakedemo project above, the configuration phase also does the following:

• Find SDL2 and OpenGL header files and libraries
• Generate header file in binary directory demo-config.h-it will be referenced in C + + code

In more complex projects, the configuration phase might also detect whether system functions are available (as the traditional Unix configue scripts do), or define special "install" Target files (in order to create a release package). If you rerun CMake under the binary folder, many slow steps will be skipped because the cache is used.

Run CMake on the command line

Before running CMake, make sure you have dependencies on the project and platform requirements. We often need to tell cmake which generator (generator) You can use to view the generators you can select using CMake--help.

Create a binary directory, CD to the directory, and then run CMake, specifying the path to the source directory on the command line. The generator is specified with the-G option (the default generator is used if not specified).

mkdir BUILDCD buildcmake-g "Visual Studio 15 2017":

If you have a configuration option for the project itself, you can also specify it on the command line. For example, the default value for Demo_enable_multisample in the Cmakedemo project is 0, and you can turn this feature on by making a-ddemo_enable_multisample=1. Modifying the value of Demo_enable_multisample modifies the contents of the demo-config.h. The value of the variable is also stored in the cache so that we can use it in subsequent runs.

Cmake-g "Visual Studio"-ddemo_enable_multisample=1.

If you want to change the Demo_enable_multisample value later, just rerun the cmake. Subsequent re-runs do not need to pass in the source directory path, but simply make a binary directory that already exists. CMake will find the settings in the previous cache in the binary directory and reuse them.

Cmake-ddemo_enable_multisample=0.

You can pass Cmake-l-N. To view the cache variables for the project definition. As shown, you can see that Cmakedemo's demo_enable_multisample option is set back to 0:

Run Cmake-gui

I prefer to use cmake through the command line, but CMake also has a GUI. The GUI provides an interactive way to set cache variables. Again, first make sure you have the dependencies you need to install the project.

Run Cmake-gui to open the graphical interface, fill in the path to the source directory and binary directory, and click Configure.

If the binary directory does not already exist, CMake will ask you if you want to create the folder. Then CMake will let you choose a generator.

After the initial configuration is complete, the GUI displays a list of cache variables-and runs CMAKE-L-N on the command line. The results are similar. The new cache variable is highlighted in red (in which all the cache variables are new). If you click Configure again, the red highlight will disappear because these cache variables are no longer new.

When you have finished setting the cache variable, click Generate. This will generate the build pipeline files in the binary directory, which you can use to build your project.

Run Ccmake

Ccmake is like a Cmake-gui under the command line. Just like the GUI, you can set the cache variables interactively.

Using UNIX makefiles to build

Running CMake in a unix-like environment will generate a UNIX makefile by default. Of course, you can explicitly generate makefiles with the-G option. When generating makefile, you should define Cmake_build_type variables. If the Souce directory is the parent directory of the binary directory:

Cmake-g "Unix makefiles"-dcmake_build_type=debug.

Since the makefiles generated by CMAKE are all single-configuration (single-configuration), you need to define cmake_build_type yourself. Unlike the solution in Visual Studio (solution), you cannot use the same makefile to build multiple configurations such as debug and release. A makefile can only complete one build. The default build types are: Debug,minsizerel,relwithdebinfo and Release. Beware of using Cmake_build_type, if you forget to define Cmake_build_type, you may get a non-optimized build with no debug information. To change the build type, you must rerun CMake and generate a new makefile.

Personally, I found the cmake default Release configuration useless because this configuration does not generate any debug information. If you've ever opened a crash message (crash dump) or fixed a bug in release release, you'll be thankful for the presence of debug information even in the optimization build. So, in my other cmake projects, I often remove the release configuration from CMakeLists.txt and use the Relwithdebinfo configuration.

Once the makefile file is present, you can use the make command to build your project. Make defaults to build each target file defined in CMakeLists.txt. In the case of Cmakedemo, only one target file needs to be built. You can also build a specified target file by passing the name of the target file to make:

Make Cmakedemo

The makefile generated by CMake can automatically detect header file dependencies, so editing a file does not have to be rebuilt into a song project. You can also parallelize the build by passing in-j 4 (or a larger number) to make.

CMake can also use the Ninja generator. Ninja is similar to make, but faster than make. The ninja Generator generates a Build.ninja file-similar to the Makefile file. The Ninja generator is also single-configured. The Ninja-j option automatically adjusts to the number of available CPUs.

Other CMake Features

• You can run the build without specifying a generator at the command line

• CMake--build. --target Cmakedemo--config Debug

• You can use the Cmake_toolchain_file variable to wear a build pipeline for cross-compilation
• You can generate a Compile_commands.json file to use for Clang's libtooling library

Limited to my area of interest, describe the use of CMake under VS, Xcode, Qt for the moment without translation, interested readers can refer to the original (https://preshing.com/20170511/ how-to-build-a-cmake-based-project/).

How to build a CMake project (translated)