3.2. Out-of-source build

The next important term is “out-of-source build”. “Out-of-source build” is a good practice of keeping separately generated files from binary tree and source files from source tree. CMake do support contrary “in-source build” layout but such approach has no real benefits and unrecommended.

3.2.1. Multiple configurations

Out-of-source build allow you to have different configurations simultaneously without conflicts, e.g. Debug and Release variant:

> cmake -H. -B_builds/Debug -DCMAKE_BUILD_TYPE=Debug
> cmake -H. -B_builds/Release -DCMAKE_BUILD_TYPE=Release

or any other kind of customization, e.g. options:

> cmake -H. -B_builds/feature-on -DFOO_FEATURE=ON
> cmake -H. -B_builds/feature-off -DFOO_FEATURE=OFF

generators:

> cmake -H. -B_builds/xcode -G Xcode
> cmake -H. -B_builds/make -G "Unix Makefiles"

platforms:

> cmake -H. -B_builds/osx -G Xcode
> cmake -H. -B_builds/ios -G Xcode -DCMAKE_TOOLCHAIN_FILE=/.../ios.cmake

3.2.2. VCS friendly

Out-of-source build allow you to ignore temporary binaries by just adding _builds directory to the no-tracking-files list:

# .gitignore

_builds

compare it with similar file for in-source build:

# .gitignore

*.sln
*.vcxproj
*.vcxproj.filters
*.xcodeproj
CMakeCache.txt
CMakeFiles
CMakeScripts
Debug/*
Makefile
Win32/*
cmake_install.cmake
foo
foo.build/*
foo.dir/*
foo.exe
x64/*

3.2.3. Other notes

In-source build at the first glance may looks more friendly for the developers who used to store projects/solution files in VCS. But in fact out-of-source build will remind you one more time that now your workflow changed, CMake is in charge and you should not edit your project settings in IDE.

Another note is that out-of-source mean not only set cmake -B_builds but also remember to put any kind of automatically generated files to _builds. E.g. if you have C++ template myproject.h.in which is used to generate myproject.h, then you need to keep myproject.h.in in source tree and put myproject.h to the binary tree.