Building your first project
Now, it's time to get your hands dirty and see whether your installation worked. We have provided an example of a simple
hello world project that you can download and build right away. Open a console, type in the following, and you'll be ready to go:
git clone https://github.com/PacktPublishing/CMake-Best- Practices.git cd CMake-Best-Practices/chapter_1 mkdir build cd build cmake .. cmake -–build .
This will result in an executable called
Chapter_1 that prints out
Welcome to CMake Best Practices on the console.
Let's have a detailed look at what happened here:
- First, the example repository is checked out using Git and then the
buildfolder is created. The file structure of the example CMake project will look like this before the build:
. ├── CMakeLists.txt └── build └── src └── main.cpp
Apart from the folder containing the source code, there is a file called
CMakeLists.txt. This file contains the instructions for CMake on how to create build instructions for the project and how to build it. Every CMake project has a
CMakeLists.txt file at the root of the project, but there might be many files with that name in various subfolders.
- After cloning the repository, the build process is started with
cmake. CMake's build process is a two-stage process. The first step, which is usually called configuration, reads the
CMakeLists.txtfile and generates an instruction for the native build toolchain of the system. In the second step, these build instructions are executed and the executables or libraries are built.
During the configuration step, the build requirements are checked, the dependencies are resolved, and the build instructions are generated.
- Configuring a project also creates a file called
CMakeCache.txtthat contains all the information that's needed to create the build instructions. The next call to
cmake --build .executes the build by internally calling CMake; if you are on Windows, it does so by invoking the Visual Studio compiler. This is the actual step for compiling the binaries. If everything went well, there should be an executable named
For brevity, we cd'd into the build directory in the previous examples and used relative paths to find the source folders. This is often convenient, but if you want to call CMake from somewhere else, you can use the
--S option to select the source file and the
--B option to select the
cmake -S /path/to/source -B /path/to/build cmake -build /path/to/build
Explicitly passing the build and source directories often comes in handy when using CMake in a continuous integration environment since being explicit helps with maintainability. It is also helpful if you want to create different build directories for different configurations, such as when you're building cross-platform software.
A minimal CMakeLists.txt file
cmake_minimum_required(VERSION 3.21) project( "chapter1" VERSION 1.0 DESCRIPTION "A simple project to demonstrate basic CMake usage" LANGUAGES CXX) add_executable(Chapter1) target_sources(Chapter1 PRIVATE src/main.cpp)
Let's understand these instructions in a bit more detail:
- The first line defines the minimum version of CMake that's required to build this project. Every
CMakeLists.txtfile starts with this directive. This is used to warn the user if the project uses features of CMake that are only available from a certain version upward. Generally, we recommend setting the version to the lowest version that supports the features that are used in the project.
- The next directive is the name, version, and description of the project to be built, followed by the programming languages that are used in the project. Here, we use
CXXto mark this as a C++ project.
add_executabledirective tells CMake that we want to build an executable (as opposed to a library or a custom artifact, which we will cover later in this book).
target_sourcesstatement tells CMake where to look for the sources for the executable called
Chapter1and that the visibility of the sources is limited to the executable. We will go into the specifics of the single commands later in this book.