What is disabling in-source builds in CMake?
The best practice for organizing and managing the build process of a CMake-based project in a separate directory from the source code itself is disabling in-source builds in CMake. This approach means the build process is kept in a different directory from the main source code. CMake usually allows projects to be built in the same directory as the source code itself. Various complications can result, and this approach compromises the construction process’s reliability and ease of maintenance. A separate directory (often referred to as the “build directory”) will need to be created If the decision is made to disable in-source building, where CMake can be run to generate the required build files and allow the project to continue to be built.
Reasons to disable in-source builds
Here are some reasons why it is recommended to disable in-source building:
Maintain clean source code: The source directory is kept clean and not cluttered with build-related files by keeping the build artifacts separate from the source code.
Isolation: Accidental overwriting or modification of source files during the build process can lead to in-source builds. This kind of interference is prevented by keeping the build files separate.
Build configurations: Separate build directories can easily be managed for different configurations (e.g., Debug, Release). This allows for simpler switching between configurations without affecting the source files.
Version control: Artifacts shouldn’t be stored in version control systems. A separate build directory prevents build files from being accidentally committed into our version control repository.
Build reproducibility: Developers can easily replicate builds on other systems without affecting the source files by ensuring the build process is separate from the source code.
Using CMAKE_DISABLE_IN_SOURCE_BUILD in CMake
The CMake variable CMAKE_DISABLE_IN_SOURCE_BUILD determines whether a CMake project should be built directly in the source directory or a separate build directory. By default, CMake recommends creating a separate build directory outside of the source directory to keep the source directory clean and prevent it from becoming cluttered with build-related files.
Here’s how CMAKE_DISABLE_IN_SOURCE_BUILD works:
-
If
TRUEis set forCMAKE_DISABLE_IN_SOURCE_BUILD, the practice of out-of-source builds is enforced. This means errors or warnings will be generated when building the project in the source folder.set(CMAKE_DISABLE_IN_SOURCE_BUILD TRUE) -
If
CMAKE_DISABLE_IN_SOURCE_BUILDis set toFALSE(or not set at all), CMake can build the project in the source directory. However, this is generally not recommended as it can cause build artifacts to be mixed with source code.set(CMAKE_DISABLE_IN_SOURCE_BUILD FALSE)
Try it yourself
We need to run the following commands to run the CMake program:
-
The command to compile and link the program in-source:
cmake -B . .The compilation and linking command generates an error message because we are configured in the source directory.
-
The command to compile and link the program out-of-source:
cmake -B buildNo error message is generated during the compilation and linking process because we have configured it for an out-of-source directory.
-
The command to build the program:
cmake --build build/ -
The command to execute the program:
./build/bin/MyExecutable
Now let’s practice the above commands and see the CMake output by clicking the “Run” button:
#include <iostream>
int main() {
std::cout << "Thank you for taking the time to read this article." << std::endl;
return 0;
}Code explanation
Lines 1–2: We set the minimum required CMake version to 3.25.1 and initialize a CMake project named “MyProject.”
Lines 5–6: CMake commands set options to prevent building or making changes to the source directory during the build process.
Line 9: We set the output directory for compiled runtime files to a subdirectory named bin within the build directory using the CMake build system.
Lines 12–14: We check that the source directory is the same as the binary directory, and if an attempt is made to build in the source directory, a fatal error is thrown, instructing the user to create and build a separate directory.
Line 17: An executable named "MyExecutable" is created from the main.cpp source file.
Conclusion
Organization and management of the build process of a CMake-based project in a separate directory from the source code are considered best practices that offer several benefits. By disabling in-source builds and enforcing the utilization of a separate build directory, a clean source code directory can be maintained, accidental interference with source files can be prevented, different build configurations can be effectively managed, version control issues can be avoided, and build reproducibility across different systems can be ensured. The utilization of the CMAKE_DISABLE_IN_SOURCE_BUILD variable in CMake provides a straightforward means of enforcing this separation, guiding developers toward the maintenance of a structured and dependable development environment.
Free Resources