How to Set Up New Projects on CMake for Success

• Share on Facebook
• Share on LinkedIn
• Share on X

Choosing the right build system can make or break your project’s success. From handling dependencies to ensuring that your code is compiled and linked correctly, the right build system can save you time and avoid potential headaches.

Among the numerous options available, the CMake build system stands out as a powerhouse, tackling complex, cross-platform projects.

This tutorial covers CMake’s popularity, its basic setup and best practices, and common pitfalls when using it. We also explore advanced topics like code generators and custom targets. By the end, you’ll be ready to leverage CMake effectively, setting your projects up for long-term success.

Why CMake?

CMake isn’t just another build system—it’s a tool for managing the process of building source code that offers unparalleled flexibility and scalability. For intermediate-level software developers, understanding CMake is an essential skill. 

Why is it the go-to choice for many developers and organizations:

• Cross-platform compatibility: CMake abstracts platform-specific details, allowing you to define your build configuration once and generate native build scripts for multiple supported operating systems or IDEs.
• Flexibility: Whether you’re using Linux, Windows, or macOS, CMake has you covered to get your build systems up and running.
• Scalability: CMake can scale to meet your needs, no matter the size of the project.
• Wide adoption: CMake’s popularity means developers enjoy extensive community support, along with numerous framework/solution integrations.

Setting Up a New Project on CMake 

Below, we discuss how to set up CMake for Linux, macOS, and Linux.

Linux

Open a terminal, and then use the sudo apt update command to update your package list.

Next, install CMake by using the command: sudo apt install cmake. Depending on the programming language used, you may need to install compilers too. For example, if developing a program in C++, g++ compilers will have to be installed using:
sudo apt install g++.

macOS via Homebrew 

If you haven’t already installed the Homebrew package manager for macOS, you’ll need to do so. Next, run the command: /bin/bash -c “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)”.

Once this is done, install CMake by running: brew install cmake.

Windows Installation 3

At the official CMake website, download the latest stable release for Windows (using the .msi installer).

Next, run the installer and follow the installation wizard. During this process, add CMake to the system PATH for either the current user or all users.

Sample Project

Let’s walk through an example of a basic C++ CMake project for a Hello World C++ program configured with a simple CMakeLists.txt file. 

First, create a main.cpp file with the following contents in an empty directory named CppHelloWorld: 

// main.cpp

#include <iostream>

int main() {

    std::cout << “Hello, World!” << std::endl;

    return 0;

}

This will output “Hello, World!” on the standard output.

Now, add a CMakeLists.txt file to the CppHelloWorld directory with the following: 

# CMakeLists.txt

# Minimum CMake version required

cmake_minimum_required(VERSION 3.5)

# Project name

project(HelloWorld)

# Add the executable

add_executable(HelloWorld main.cpp)

Here, the file specifies the minimum CMake version, the name of the project, and the source file.

To build the CMake project on a Windows machine, open a command prompt by searching cmd exe file in the Windows search bar. Then, in the command prompt, execute the following commands: 

C:\CppHelloWorld>mkdir build

C:\CppHelloWorld>cd build

C:\CppHelloWorld\build>cmake ..

C:\CppHelloWorld\build>cmake –build .

C:\CppHelloWorld\build>.\Debug\HelloWorld.exe

To build a CMake project on a Linux machine, open a terminal application, and, in the command prompt execute the following commands: 

ubuntu@ubuntu/CppHelloWorld$mkdir build && cd build

ubuntu@ubuntu/CppHelloWorld/build$cmake ..

ubuntu@ubuntu/CppHelloWorld$make

ubuntu@ubuntu/CppHelloWorld$./HelloWorld

Output:

Hello, World!

Here’s what’s happening:

• mkdir build creates a separate build directory and cd enters the build directory
• cmake .. configures the project by generating the appropriate build files for your system.
• cmake –build . or make compiles the project and links the executable.

After this, there should be an executable in the build directory’s debug folder.

Best Practices for a CMake Project Setup

By adhering to the following best practices, you’ll create CMake projects that are easier to maintain, scale, and port across different platforms, plus you’ll facilitate collaboration.

Use a Proper Folder Structure for Scalability

A properly organized folder structure is essential when it comes to building, scaling, and managing a cross-platform C++ project. It will ensure your project remains easy to navigate, allowing new developers to quickly grasp the layout and understand the structure of the codebase.

Example directory structure:

MyProject/

CMakeLists.txt # Top-level CMake configuration file 

src/ # Source files for the project 

main.cpp 

  include/ # Header files (public APIs) 

my_module.h 

tests/ # Unit tests and testing framework configurations 

test_main.cpp 

In the above code: 

• src/ contains the implementation details, while include/ exposes only the public headers, creating a natural separation of concerns.
• tests/ ensures that unit tests are isolated and clearly organized.
• build/ contains build artifacts and configuration files. 

Leverage Modern CMake Features

Modern CMake emphasizes targets and properties over variables and commands. Many new features also enhance the management of your CMake project.

The target_compile_features() sets language standards and compiler features:

add_library(my_library)
target_compile_features(my_library PUBLIC cxx_std_17)

This approach means any target linking to my_library will automatically inherit the C++17 requirement, simplifying project configuration.

The target_include_directories()command allows you to specify include directories for a target, with better control over visibility:

target_include_directories(my_library PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src )

Here, the keyword PUBLIC makes the include directory available to targets that link against my_library, while PRIVATE keeps it internal to the library.

The target_compile_definitions()command adds preprocessor definitions to your target:

target_compile_definitions(my_library
PRIVATE
MY_LIBRARY_INTERNAL
PUBLIC
MY_LIBRARY_API_VERSION=2
)

And lastly, the target_sources()command allows you to add source files to a target after it’s been created:

add_library(my_library)
target_sources(my_library
PRIVATE
src/implementation1.cpp
src/implementation2.cpp
)

You can explore many such features for CMake on its documentation page. 

Manage Third-Party Dependencies

Effective dependency management is critical for project stability. For example, find_package() can locate external libraries and target_link_libraries() to link them:

find_package(Boost REQUIRED COMPONENTS filesystem) target_link_libraries(my_executable PRIVATE Boost::filesystem)

This method cleanly separates dependency resolution from target definition, making your CMakeLists.txt more readable and maintainable.

Properly Implement Version Control 

If you use Git or other version control systems, consider these practices for CMakeLists.txt:

• Always commit CMakeLists.txt files to version control.
• Use relative paths within CMakeLists.txt to ensure portability.
• Avoid hardcoding absolute paths or machine-specific settings.
• Consider using the CMake’s configure_file() command to generate version information from Git tags.
• Document your CMake conventions and use CI/CD pipelines to enforce them, ensuring a uniform build process for all contributors.

That last bullet is key, as maintaining consistent CMake practices across your team is crucial. 

Be Aware of Cross-Platform Differences

CMake excels at managing cross-platform builds. For example, the if/elseif/endif keywords can be used to separate custom platform commands:

if(WIN32)
target_compile_definitions(my_library PRIVATE WIN32_LEAN_AND_MEAN)
elseif(UNIX)
target_link_libraries(my_library PRIVATE pthread)
endif()

Strive to minimize platform-specific code by leveraging CMake’s built-in variables and commands whenever possible. This will enhance portability and lower maintenance overhead. 

Remember that CMake is a powerful tool, and mastering its modern features can significantly improve your development workflow. As your project evolves, regularly revisit and refine your CMake setup to best serve your needs. 

Integrating Code Generators with CMake

Code generators have become invaluable tools, especially for large-scale projects. These utilities automate the creation of repetitive code according to predefined templates or other specifications, enhancing productivity, reducing human error, and maintaining consistency across the codebase. 

Code generators are particularly useful for:

• Creating boilerplate code
• Generating interfaces from data models
• Producing code from interface definition languages (IDLs)
• Automating the generation of repetitive patterns

Combining CMake code generators with CMake custom targets will streamline the build process by automatically generating the required files and making sure dependencies are properly managed. 

Sample Code Generating Commands

CMake provides two key commands for integrating code generators: add_custom_command()and add_custom_target().

The first, add_custom_command()specifies how to generate a file.
For example:

# Generate a simple text file
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/hello.txt
COMMAND ${CMAKE_COMMAND} -E echo “Hello, World!” > ${CMAKE_CURRENT_BINARY_DIR}/hello.txt
COMMENT “Generating hello.txt”
)

In this example, we’re generating a file called hello.txt in the build directory. We use CMake’s built-in command-line tool (${CMAKE_COMMAND} -E) to echo “Hello, World!” into the file. The COMMENT is what you’ll see when this command is executed during the build process.

The second, add_custom_target() creates a target that depends on generated files.
For example:

# Create a custom target that depends on hello.txt
add_custom_target(generate_hello ALL
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/hello.txt
)

Here, we created a custom target named generate_hello. The ALL keyword means this target will be built by default when you build the project. CMake will ensure that the file “hello.txt” is generated before considering this target complete.

Additionally, a common use case for custom commands is generating API documentation using tools like Doxygen.

Code generators offer:

• Consistency: Generated code follows predefined patterns, ensuring consistency across a project.
• Efficiency: Automating repetitive tasks saves developer time and lowers the chance of human error.
• Maintainability: Changes to the code generation process can be used across your entire project.
• Version control: You can version control the generator and its inputs rather than the generated code itself.

Common Pitfalls and How to Avoid Them

While CMake is a powerful tool for managing build processes, it comes with some challenges. 

Following the correct CMake installation steps and configuring your environment carefully will save you significant time and frustration, especially in larger projects.

Below are some of the common misconfigurations, albeit not an exhaustive list:

• Incorrect versions: One frequent issue is specifying incorrect minimum CMake versions or using features not available in the specified version.
  • Solution: Always specify the minimum required CMake version at the top of your root CMakeLists.txt file.
• Library linking issues: Improper linking of libraries can lead to undefined references or runtime errors.
  • Solution: Use target_link_libraries() with the correct visibility specifier.
• Incorrect path handling: Hardcoding paths or incorrect path variables can cause issues across different systems.
  • Solution: Make sure to leverage CMake’s built-in variables and functions for path handling.
• Platform-specific code: Using platform-specific commands or paths can break builds on other systems.
  • Solution: Use CMake’s platform-independent commands and variables.
• Compiler flags: Different compilers may not support the same flags.
  • Solution: Use compiler-specific flags conditionally.
• File system case sensitivity: Windows file systems are typically case-insensitive, while Unix-like systems are case-sensitive.
  • Solution: Always use consistent casing in file names and CMake commands.

Also, the following actions will help you debug some of the above issues:

• Use cmake-gui for a graphical interface to configure CMake projects and help identify configuration issues.
• Enable verbose output to see the exact commands executed during the build. 
• For Makefile generators, implement CMake’s message commands to output debug information.
• Run CMake in debug mode to get more detailed output.
• Follow modern CMake practices, e.g., targets and properties instead of global variables.
• Leverage find_package()to locate dependencies instead of setting the manual path.
• Implement version control for your CMakeLists.txt files; treat them as critical as your source code.
• Regularly update your CMake version and refactor your scripts to use newer, more efficient features.
• Document your CMake setup, especially for complex configurations or custom functions.

Being aware of typical issues and knowing how to address them, you can create more robust, portable, and maintainable CMake-based build systems for your projects.

Security Considerations

Security should never be overlooked in the build process, but when using CMake, developers need to also keep some additional factors in mind:

• File permissions: Ensure your build files and scripts have appropriate permissions to avoid unauthorized modifications.
• Sensitive information: Use environment variables or external configuration files for sensitive data in your CMakeLists.txt (e.g., passwords, API key). Do not hardcode it.
• Cross-platform security flags: When targeting different platforms, identify security flags specific to each OS. For example, on Linux, you can enable position-independent executables (PIE) for added security.

Conclusion

CMake is an incredibly flexible and powerful tool. Properly implemented, it will significantly simplify the process of building complex C++ projects. By following best practices, understanding common pitfalls, and exploring advanced features like code generators and custom targets, you can set up your projects for long-term success.

As you grow more familiar with CMake, don’t hesitate to explore more advanced topics such as cross-compilation, complex dependency management, and advanced toolchains. With practice, you’ll master CMake and confidently tackle even the most challenging C++ projects.

References

1. CMake Documentation: Official CMake Documentation

https://cmake.org/cmake/help/latest/manual/cmake.1.html

2. Preshing on Programming: How to Build a CMake-Based Project

https://preshing.com/20170511/how-to-build-a-cmake-based-project

3. CMake Commands:
   https://cmake.org/cmake/help/latest/manual/cmake-commands.7.html
4. CLion Documentation: Creating a New Project from Scratch

https://www.jetbrains.com/help/clion/creating-new-project-from-scratch.html

5. CMake find_package Command

https://cmake.org/cmake/help/latest/command/find_package.html