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 separate the generated files of the binary tree from the source files of the source tree. CMake does support the contrary “in-source build” layout, but such an approach has no real benefit and is not recommended.
3.2.1. Multiple configurations¶
An out-of-source build allows you to have different configurations simultaneously without conflicts, e.g. Debug and Release variants:
> 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
> cmake -H. -B_builds/xcode -G Xcode > cmake -H. -B_builds/make -G "Unix Makefiles"
> cmake -H. -B_builds/osx -G Xcode > cmake -H. -B_builds/ios -G Xcode -DCMAKE_TOOLCHAIN_FILE=/.../ios.cmake
3.2.2. VCS friendly¶
An out-of-source build allows you to ignore temporary binaries by just adding
_builds directory to the no-tracking-files list:
# .gitignore _builds
compare it with the entries required for an 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¶
An in-source build at first glance may look more friendly for developers who are used to storing project/solution files in VCS. But in fact an out-of-source build will remind you one more time that now your workflow has changed, CMake is in charge and you should not edit your project settings in your IDE.
Another note is that using an out-of-source build means that not only do you
need to set
cmake -B_builds but also remember that you have to put any
kind of automatically generated files into
E.g. if you have a C++ template
myproject.h.in which is used to generate
myproject.h, then you need to keep
myproject.h.in in the source tree
myproject.h in the binary tree.