CMake Black Technology: Unifying Windows/Linux/Mac Development Environments with a Single Script

In cross-platform development, developers are often hindered by build scripts: Linux uses Makefile, Windows requires Visual Studio solutions, and macOS needs to accommodate Xcode. If the project team includes both Windows developers and those accustomed to Linux, the environmental differences can be quite troublesome.

The value of CMake lies in its ability to generate project configurations for different platforms using a single script. By writing a CMakeLists.txt, you can generate a .sln file for Windows, a Makefile for Linux, and an Xcode Project for macOS. This article combines some commonly used techniques to demonstrate how to truly achieve “one script to rule them all”.

📚 The C++ Knowledge Base has launched on ima! The current content covered by the knowledge base is shown in the image below👇👇👇

📌 Students interested in the knowledge base can add the assistant vx (chuzi345) with the note 【Knowledge Base】 or click 👉 C++ Knowledge Base (tap to jump) to view the complete introduction to the knowledge base～

1. Basic Project Structure

Assuming we want to write a cross-platform demo project, the structure is roughly as follows:

project-root/
│── src/
│   └── main.cpp
│── include/
│   └── hello.h
│── CMakeLists.txt

The simplest CMakeLists.txt can be written as follows:

cmake_minimum_required(VERSION 3.16)
project(CrossPlatformDemo LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(demo src/main.cpp)
target_include_directories(demo PRIVATE include)

On Windows, execute cmake -G "Visual Studio 17 2022" .., and on Linux/macOS, execute cmake .. && make, which will generate the corresponding executable file demo. At this point, the basic cross-platform build is established.

2. Handling Platform Differences

In real projects, it is often necessary to write platform-specific code. A common approach is to use preprocessor macros, but in CMake, we can elegantly control compilation options using platform variables.

if(WIN32)
    target_compile_definitions(demo PRIVATE PLATFORM_WINDOWS)
elseif(APPLE)
    target_compile_definitions(demo PRIVATE PLATFORM_MACOS)
elseif(UNIX)
    target_compile_definitions(demo PRIVATE PLATFORM_LINUX)
endif()

Then in the code:

#include "hello.h"
#include &lt;iostream&gt;

int main() {
#ifdef PLATFORM_WINDOWS
    std::cout &lt;&lt; "Running on Windows\n";
#elif defined(PLATFORM_MACOS)
    std::cout &lt;&lt; "Running on macOS\n";
#elif defined(PLATFORM_LINUX)
    std::cout &lt;&lt; "Running on Linux\n";
#endif
    return 0;
}

This ensures that all three platforms use the same script for building, but the output varies according to the platform.

3. Cross-Platform Third-Party Libraries

Another common issue is third-party dependencies. For example, on Linux, we might use pthread, while on Windows, we rely on the Win32 API. Using CMake’s find_package can mask these differences:

find_package(Threads REQUIRED)
target_link_libraries(demo PRIVATE Threads::Threads)

This way, on Linux/macOS, it will automatically link -lpthread, and on Windows, it will link to the corresponding implementation. For more complex libraries, such as OpenSSL, it can be written as:

find_package(OpenSSL REQUIRED)
target_link_libraries(demo PRIVATE OpenSSL::SSL OpenSSL::Crypto)

As long as OpenSSL is correctly installed on the system, all three platforms can build uniformly.

4. Output Directories and Installation Rules

In team collaboration, the installation paths for binaries and header files need to be unified; otherwise, each person’s build directory will be different. CMake can specify output paths uniformly:

set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)

The installation rules can be specified using install:

install(TARGETS demo DESTINATION bin)
install(DIRECTORY include/ DESTINATION include)

Executing cmake --install build will install the executable files and header files to a unified directory, maintaining consistency across platforms.

5. Configuration Options and Feature Toggles

In complex projects, we often need to enable features on demand, such as whether to enable logging modules or certain experimental features. CMake provides a configuration option mechanism:

option(ENABLE_LOGGING "Enable logging feature" ON)

if(ENABLE_LOGGING)
    target_compile_definitions(demo PRIVATE ENABLE_LOGGING)
endif()

Developers can freely toggle this during the build:

cmake -DENABLE_LOGGING=OFF ..

This type of “toggle” functionality is especially important for cross-platform teams, avoiding script divergence across different platforms.

6. Cross-Platform Compiler Options

Sometimes, different compiler parameters need to be set for different platforms. CMake provides the variable CMAKE_CXX_COMPILER_ID to determine the compiler:

if(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
    target_compile_options(demo PRIVATE /W4 /O2)
else()
    target_compile_options(demo PRIVATE -Wall -Wextra -O2)
endif()

This way, we can enable /W4 under MSVC and -Wall under GCC/Clang, ensuring consistent warning levels for team members.

7. Packaging and Distribution

For release versions, CMake comes with cpack for one-click packaging. Just add the following to your CMakeLists.txt:

include(CPack)

Executing cpack will generate .tar.gz, .zip, and even Windows .msi or macOS .dmg installation packages. This step can greatly simplify the cross-platform distribution process.

8. Practical Implementation Suggestions

When I used this method in projects, I had several practical experiences:

All team members build through CMake, and handwritten platform-specific project files are no longer allowed.
CMakeLists.txt should remain clean, with complex logic split into the cmake/Modules directory.
Try to use target_* series commands (such as target_link_libraries, target_compile_definitions), to avoid global variable pollution.

This ensures both cross-platform consistency and ease of long-term maintenance.

Using CMake to abstract the differences between Windows/Linux/macOS can greatly enhance team collaboration efficiency. Although writing a clean CMakeLists.txt requires some initial investment, once set up, new members can join development with almost zero learning cost.

If the language itself determines whether the business can run, then the build system often determines whether the project can thrive smoothly. For cross-platform development, a maintainable CMake script is that seemingly inconspicuous yet crucial infrastructure.