cmake(1)¶
The cmake executable is the command-line interface of the cross-platform buildsystem generator CMake. The above Synopsis lists various actions the tool can perform as described in sections below.
To build a software project with CMake, Generate a Project Buildsystem. Optionally use cmake to Build a Project, Install a Project or just run the corresponding build tool (e.g. make ) directly. cmake can also be used to View Help.
The other actions are meant for use by software developers writing scripts in the CMake language to support their builds.
For graphical user interfaces that may be used in place of cmake, see ccmake and cmake-gui . For command-line interfaces to the CMake testing and packaging facilities, see ctest and cpack .
For more information on CMake at large, see also the links at the end of this manual.
Introduction to CMake Buildsystems¶
A buildsystem describes how to build a project’s executables and libraries from its source code using a build tool to automate the process. For example, a buildsystem may be a Makefile for use with a command-line make tool or a project file for an Integrated Development Environment (IDE). In order to avoid maintaining multiple such buildsystems, a project may specify its buildsystem abstractly using files written in the CMake language . From these files CMake generates a preferred buildsystem locally for each user through a backend called a generator.
To generate a buildsystem with CMake, the following must be selected:
The top-level directory containing source files provided by the project. The project specifies its buildsystem using files as described in the cmake-language(7) manual, starting with a top-level file named CMakeLists.txt . These files specify build targets and their dependencies as described in the cmake-buildsystem(7) manual.
The top-level directory in which buildsystem files and build output artifacts (e.g. executables and libraries) are to be stored. CMake will write a CMakeCache.txt file to identify the directory as a build tree and store persistent information such as buildsystem configuration options.
To maintain a pristine source tree, perform an out-of-source build by using a separate dedicated build tree. An in-source build in which the build tree is placed in the same directory as the source tree is also supported, but discouraged.
This chooses the kind of buildsystem to generate. See the cmake-generators(7) manual for documentation of all generators. Run cmake —help to see a list of generators available locally. Optionally use the -G option below to specify a generator, or simply accept the default CMake chooses for the current platform.
When using one of the Command-Line Build Tool Generators CMake expects that the environment needed by the compiler toolchain is already configured in the shell. When using one of the IDE Build Tool Generators , no particular environment is needed.
Generate a Project Buildsystem¶
Run CMake with one of the following command signatures to specify the source and build trees and generate a buildsystem:
Uses as the build tree and as the source tree. The specified paths may be absolute or relative to the current working directory. The source tree must contain a CMakeLists.txt file. The build tree will be created automatically if it does not already exist. For example:
Uses the current working directory as the build tree, and as the source tree. The specified path may be absolute or relative to the current working directory. The source tree must contain a CMakeLists.txt file and must not contain a CMakeCache.txt file because the latter identifies an existing build tree. For example:
$ mkdir build ; cd build $ cmake ../src
Uses as the build tree, and loads the path to the source tree from its CMakeCache.txt file, which must have already been generated by a previous run of CMake. The specified path may be absolute or relative to the current working directory. For example:
In all cases the may be zero or more of the Options below.
The above styles for specifying the source and build trees may be mixed. Paths specified with -S or -B are always classified as source or build trees, respectively. Paths specified with plain arguments are classified based on their content and the types of paths given earlier. If only one type of path is given, the current working directory (cwd) is used for the other. For example:
Understanding The Basics
To illustrate what makefile does, we first create a project folder (I named it CMakeTuto here).
Then use VSCode to open the folder.
mkdir CMakeTuto
cd CMakeTuto/
code .
Note here makefile do not accept spaces. It only accept tabs.
#include
int main(){
std::cout «Hello World!\n»;
return 0;
}
Now your CMakeTuto directory should be like this:
So what a makefile does?
Use the make command to run the makefile
make command basically run the command in makefile . (that is g++ main.cpp -o out in this case. )
Now a out file should appear. Run the out file.
It should print the “Hello World!”.
The concept of CMake
CMake makes your makefile.
now we can first delete our makefile and out in the previous section.
First check our cmake version
You can also use the command cmake to check the usage.
Common usage: cmake [options]
Create a file CMakeLists.txt , leave the file blank.
Now your directory should be:
Lets create a directory build.
Note if you want to use cmake command, you need to go to the build directory (which is build ).
Now your directory should be like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
.
├── build
│ ├── CMakeCache.txt
│ ├── CMakeFiles
│ │ ├── 3.10.2
│ │ │ ├── CMakeCCompiler.cmake
│ │ │ ├── CMakeCXXCompiler.cmake
│ │ │ ├── CMakeDetermineCompilerABI_C.bin
│ │ │ ├── CMakeDetermineCompilerABI_CXX.bin
│ │ │ ├── CMakeSystem.cmake
│ │ │ ├── CompilerIdC
│ │ │ │ ├── a.out
│ │ │ │ ├── CMakeCCompilerId.c
│ │ │ │ └── tmp
│ │ │ └── CompilerIdCXX
│ │ │ ├── a.out
│ │ │ ├── CMakeCXXCompilerId.cpp
│ │ │ └── tmp
│ │ ├── cmake.check_cache
│ │ ├── CMakeDirectoryInformation.cmake
│ │ ├── CMakeOutput.log
│ │ ├── CMakeTmp
│ │ ├── feature_tests.bin
│ │ ├── feature_tests.c
│ │ ├── feature_tests.cxx
│ │ ├── Makefile2
│ │ ├── Makefile.cmake
│ │ ├── progress.marks
│ │ └── TargetDirectories.txt
│ ├── cmake_install.cmake
│ └── Makefile
├── CMakeLists.txt
└── main.cpp
8 directories, 24 files
Notice now the Makefile is generated.
If You look into that Makefile and you will see it just build what our CMakeLists.txt require.
(Note we haven’t write anything into CMakeLists.txt yet)
We won’t teach those generated files.
Edit your CMakeLists.txt
Now write into your CMakeLists.txt .
cmake_minimum_required(VERSION 3.9.0)
project(HelloWorld) #replace «HelloWorld» with your project name
add_executable(${PROJECT_NAME} main.cpp)
run the cmake command in your build folder again.
If You look into that Makefile again and you will see it just build what our CMakeLists.txt require.
Lets run the Makefile using make command.
You should see this outcome:
Scanning dependencies of target HelloWorld
[ 50%] Building CXX object CMakeFiles/HelloWorld.dir/main.cpp.o
[100%] Linking CXX executable HelloWorld
[100%] Built target HelloWorld
And now you should see a HelloWorld executable is in the build folder.
Lets run the HelloWorld executable.
Now you know the basics of cmake.
Another Example — Linking more than 1 file
.
├── adder.cpp
├── CMakeLists.txt
└── main.cpp
float add(float a, float b)
{
return a+b;
}
cmake_minimum_required(VERSION 3.9.0)
project(HelloWorld) #replace «HelloWorld» with your project name
add_executable(${PROJECT_NAME} main.cpp adder.cpp) #add the files here
//function prototype
float add(float a, float b);
#include
int main(){
std::cout add(6.9, 13.2)
return 0;
}
Build and run the program
mkdir build
cd build
cmake ..
make
./HelloWorld
Libraries and Subdirectories
Levels and Libraries
In practical situations we often put our files into a folder.
We need to put a sublevel CMakeLists.txt in each subfolder.
.
├── Adder
│ ├── adder.cpp
│ ├── adder.h
│ └── CMakeLists.txt
├── CMakeLists.txt
└── main.cpp
1 directory, 5 files
#include «adder.h»
float add(float a, float b)
{
return a+b;
}
#include
#include «Adder/adder.h»
int main(){
std::cout add(6.9, 13.2)
return 0;
}
cmake_minimum_required(VERSION 3.9.0)
project(HelloWorld) #replace «HelloWorld» with your project name
add_executable(${PROJECT_NAME} main.cpp) #build the main
add_subdirectory(Adder) #build the libraries
target_include_directories(${PROJECT_NAME} PUBLIC Adder)
#—uncomment this if your cmake version >3.13.0
#—target_link_directories(${PROJECT_NAME} PRIVATE Adder)
target_link_libraries(${PROJECT_NAME} adder) #links the libraries to core project
the sublevel Adder/CMakeLists.txt
add_library(adder adder.cpp) #build as a library in the most simplistic way possible
Build and run the program
mkdir build && cd build
cmake ..
make
./HelloWorld