Executable

$ cmake [options] (<path-to-source> | <path-to-existing-build>)

Assuming that the directory contains

.
├── CMakeLists.txt
└── main.cpp

#include <iostream>
using namespace std;
int main () {
  cout << "Hello world" << endl;
  return 0;
}

The minimal CMakeLists.txt file contains

cmake_minimum_required (VERSION 2.6)
project(Hello)
add_executable(${PROJECT_NAME} main.cpp)

Running cmake . creates a Makefile in the same directory whose recipes are cross platform commands, CMake’s documentation suggest that the build is separated from the source

$ mkdir build
$ cd build
$ cmake ..

Running the default target in the makefile creates the executable Hello, note that this is done on the ./build/ directory

$ make
Scanning dependencies of target Hello
[ 50%] Building CXX object CMakeFiles/Hello.dir/main.cc.o
[100%] Linking CXX executable Hello
[100%] Built target Hello
$ ./Hello
Hello world

• set(<variable> <value>) sets a normal variable available to the current function or directory scope, variables can be accessed with ${variable}
• project(<PROJECT-NAME> [LANGUAGES] [<language-name>...]), sets the following variables
  • PROJECT_NAME, same as <PROJECT-NAME>
  • PROJECT_SOURCE_DIR same as /path/to/project/
  • PROJECT_BINARY_DIR same as /path/to/project/build/
• add_executable(<name> source1 [source2 ...]) adds an executable target called name to be built from the source files listed

Useful variables

• CMAKE_SOURCE_DIR - path to the top level of the source tree (default value ./)
• CMAKE_BINARY_DIR - path to the top level of the build tree (default value ./build/)
• CMAKE_RUNTIME_OUTPUT_DIRECTORY - path to the executable (usually set to ${CMAKE_BINARY_DIR}/bin/)
• CMAKE_ARCHIVE_OUTPUT_DIRECTORY - path to the static libraries (code from static libraries is included in the executable, usually set to ${CMAKE_BINARY_DIR}/lib/)
• CMAKE_LIBRARY_OUTPUT_DIRECTORY - path to the shared libraries (additional code required by the executable, usually set to ${CMAKE_BINARY_DIR}/lib/)

Project structure and organization

. project
├── build
├── include
│   └── project
│       └── World.hpp
└── src
    ├── World.cpp
    └── main.cpp

The CMakeLists.txt file should do the following

• add the ./include path to compiler include search path
• create an executable file from main.cpp into ./build/bin/
• create an static/dynamic library (in the example is World.cpp) into ./build/lib/
• link the library with the executable

cmake_minimum_required(VERSION 3.0)

project(runner)

set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")

# the -I flag in gcc
include_directories(
  ${PROJECT_SOURCE_DIR}/include/
)

set(APP_SOURCES src/main.cpp)
set(LIB_SOURCES src/World.cpp)

# creates ./build/bin/runner
add_executable(${PROJECT_NAME} ${APP_SOURCES})

# shared library
set(LIBRARY_NAME World)
add_library(${LIBRARY_NAME} SHARED ${LIB_SOURCES})
target_link_libraries(${PROJECT_NAME} ${LIBRARY_NAME})

• include_directories(dir) - add the given directories to those the compiler uses to search for include files (gcc -I dir)
• add_library(library_name [STATIC | SHARED | MODULE] source1 [source2...]) - adds a library called library_name to be built from the source files listed
  • STATIC - archives of object files .a (archive)
  • SHARED - libraries dynamically linked at runtime .so (shared object)
• target_link_libraries(target item), specify libraries/flags to use when linking a given target

Complex CMake configuration

A complex CMake configuration will have multiple CMakeLists.txt files per directory

• ./CMakeLists.txt - configures dependencies, platform specifics and output paths
• ./src/CMakeLists.txt - configures the library to build