Preventing Source Pollution with CMake Out-of-Source Builds

The Problem: In-Source Build Pollution

Running CMake directly in your project root creates an "in-source build." This generates a CMakeCache.txt file, a CMakeFiles/ directory, and various object files scattered across your source folders. Once these files are mixed with your code, cleaning the project requires manual deletion of hidden folders or complex scripts, and you risk accidentally committing binary artifacts to your version control system.

The solution is an out-of-source build, where all generated build artifacts are isolated in a dedicated directory. This allows you to maintain a pristine source tree and manage multiple build configurations (such as Debug and Release) simultaneously without them interfering with one another.

Prerequisites

• CMake installed (version 3.10 or later recommended).
• A project directory containing a CMakeLists.txt file in the root.
• Terminal access with write permissions to the project directory.

Implementing the Out-of-Source Workflow

To isolate your build, you must ensure the CMake configuration process occurs inside a folder that is not the source root.

1. Create a build directory: Navigate to your project root and create a folder specifically for the build artifacts. It is common to name this build.
2. Enter the build directory: Change your working directory to the newly created folder.
3. Configure the project: Run the CMake command and point it to the source directory (usually one level up).
4. Build the target: Use the CMake build tool abstraction to compile the code.

# Run these commands from the project root
mkdir build
cd build
cmake ..
cmake --build .

Configuration and Permissions

When running cmake .., the .. tells CMake that the CMakeLists.txt is located in the parent directory. This ensures that all generated files, including the CMakeCache.txt (the file storing your configuration settings), stay within the build/ folder.

Required Permissions: You must have read permissions for the source directory and write permissions for the build directory. Avoid running CMake as root/sudo unless your installation paths specifically require it, as this can lead to permission conflicts in the build folder.

Comparison: In-Source vs. Out-of-Source

Feature	In-Source Build	Out-of-Source Build
Source Tree State	Polluted with binaries/caches	Pristine (code only)
Cleanup Process	Manual deletion of multiple files	rm -rf build/
Multi-Config Support	One config at a time	Parallel folders (e.g., build-debug, build-release)
VCS Risk	High risk of committing binaries	Low (single folder to ignore)

Verification and Diagnostics

To verify that the build is correctly isolated, perform the following checks:

• Root Check: Run ls -a in the project root. You should see your source files and the build/ folder, but no CMakeCache.txt or CMakeFiles/ directory.
• Build Check: Run ls -a build/. All configuration and object files should be contained here.
• Clean State Test: Delete the build directory (rm -rf build/) and verify that your .cpp and .h files remain untouched.

Recovery and Rollback

If you accidentally started an in-source build, you must remove the generated files before attempting an out-of-source build, as CMake may still reference the old cache.

To roll back an in-source build:

1. Delete CMakeCache.txt from the root.
2. Delete the CMakeFiles/ directory from the root.
3. Remove any generated Makefile or project files (e.g., .sln) from the root.

Practical Limitations

While out-of-source builds are the standard, be aware that some legacy CMake projects use absolute paths in their CMakeLists.txt, which can occasionally cause issues when the build directory is moved. Always use CMAKE_CURRENT_SOURCE_DIR and CMAKE_CURRENT_BINARY_DIR variables within your scripts to maintain portability.