One of the goals of our build configuration is to have it be portable. The dream is to write one CMakeLists.txt file, and have any developer on any machine - Windows, macOS, or Linux- be able to build the project with a few simple commands.

In the , we took a major step toward this by using generator expressions, which let us handle different build configurations in a portable way.

Now, we'll tackle the next layer of complexity: handling differences between operating systems and compilers. C++ code is often portable, but the environment it builds and runs in is not. File paths, compiler flags, and system libraries all have platform-specific quirks.

This lesson will cover the main tools to write a universal CMakeLists.txt. We'll learn how to detect the host system and compiler, and how to use that information to conditionally include source files, set compiler flags, and link against the correct libraries for the target platform.

Working With Paths

A path written for one OS will break on another:

1# Bad: Windows-specific backslashes
2set(MY_SOURCES "src\\main.cpp")

Instead, always use forward slashes (/) for paths. CMake will automatically convert them to the native format (\\) on Windows.

1# Good: Use / by default
2set(MY_SOURCES "src/main.cpp")

More importantly, using exact absolute path to where things are on your hard drive will not work for people storing the project in a different location:

1target_include_directories(MyTarget PUBLIC
2  # Bad: Absolute path
3  "/usr/greg/my-project/include"
4)

Instead, always construct paths that are relative to the project structure. The CMake variables we covered earlier in the course, such as PROJECT_SOURCE_DIR, can help with this:

1target_include_directories(MyTarget PUBLIC
2  # Good: Relative Path
3  "${PROJECT_SOURCE_DIR}/include"
4)

Detecting the Operating System

CMake automatically defines a set of boolean variables that tell you which platform you're configuring for. These variables allow you to create conditional blocks that execute only on a specific OS. The three most important are:

WIN32: True on all versions of Windows, including 64-bit.
APPLE: True on all Apple operating systems, including macOS and iOS.
UNIX: True on all UNIX-like systems, which notably includes both Linux and macOS (APPLE systems are also UNIX).

The most common pattern is to check for Windows first, and then treat everything else as Unix-like.

Example: Platform-Specific Source Files

Let's expand on an example from a previous lesson. Imagine our GreeterLib needs to display the current operating system, which requires calling a platform-specific API.

First, we'll define a common interface in our public header.

greeter/include/greeter/Greeter.h

1#pragma once
2#include <string>
3
4std::string get_greeting();
5std::string get_os_string(); // New function

Next, we'll provide two different implementations for this function.

Files

greeter

Select a file to view its content

Finally, in greeter/CMakeLists.txt, we use an if() block to choose which source file to compile into our library.

greeter/CMakeLists.txt

1cmake_minimum_required(VERSION 3.16)
2
3set(LIB_SOURCES src/Greeter.cpp) 
4
5if(WIN32) 
6  list(APPEND LIB_SOURCES src/platform_win.cpp) 
7else() # We assume anything not Windows is Unix-like 
8  list(APPEND LIB_SOURCES src/platform_nix.cpp) 
9endif() 
10
11add_library(GreeterLib ${LIB_SOURCES})
12
13target_include_directories(GreeterLib PUBLIC
14  "${CMAKE_CURRENT_SOURCE_DIR}/include"
15)

Now, the GreeterLib target will be built with the correct implementation file for the host OS, while the interface (Greeter.h) remains consistent for all consumers. We no longer need to perform this platform check in our code - out build system is taking care of it:

app/src/main.cpp

1#include <iostream>
2#include <greeter/Greeter.h>
3
4int main() {
5  std::cout << get_greeting();
6  std::cout << '\n' << get_os_string();
7  return 0;
8}

1Hello from the modular greeter library!
2This is Windows!

Abstract Away Platform Details

In addition to removing platform-specific logic from our code, a good goal is to minimize the amount of platform-specific logic even in our build scripts.

For example, the following approach duplicates platform logic to link SomeLibrary to targets, but only on Windows:

1# App1 needs a windows-specific library
2if(WIN32) 
3  target_link_libraries(App1 PRIVATE SomeLibrary) 
4endif() 
5
6# Bad: App2 duplicates the same logic
7if(WIN32) 
8  target_link_libraries(App2 PRIVATE SomeLibrary) 
9endif()

Instead of scattering WIN32 checks everywhere, you might create an INTERFACE target that encapsulates the platform-specific detail:

1# Create an INTERFACE target to represent platform dependencies
2add_library(PlatformLibs INTERFACE) 
3
4# In one place, add the windows library to the interface
5if(WIN32) 
6  target_link_libraries(PlatformLibs INTERFACE SomeWindowsLibrary) 
7endif()

Consumers now link to the abstraction - no further Win32 checks needed:

1target_link_libraries(App1 PRIVATE PlatformLibs) 
2target_link_libraries(App2 PRIVATE PlatformLibs)

Example: Linking System Libraries

The most common cross-platform challenge is linking against system libraries, which often have different names or don't exist at all on other platforms.

For example, Windows applications that use networking sockets often need to link against the ws2_32.lib library. On Linux and macOS, this functionality is part of the standard library and doesn't require an explicit link.

Let's create a Networking library that implements this platform-specific dependency.

networking/CMakeLists.txt

1cmake_minimum_required(VERSION 3.16)
2
3add_library(Networking INTERFACE)
4
5# On Windows, we need to link the sockets library.
6if(WIN32) 
7  target_link_libraries(Networking INTERFACE ws2_32) 
8endif()

In our root CMakeLists.txt, we can add this new subdirectory.

CMakeLists.txt

1add_subdirectory(greeter)
2add_subdirectory(app)
3add_subdirectory(networking)

Now, any target in our project that needs networking can simply link against our abstract Networking target:

app/CMakeLists.txt

1cmake_minimum_required(VERSION 3.16)
2
3add_executable(GreeterApp src/main.cpp)
4target_link_libraries(GreeterApp GreeterLib)
5target_link_libraries(GreeterApp Networking)

Again, note that the consumer - GreeterApp in this case - does not need to perform any platform checks here. It doesn't need to know why or how networking works; it just needs to state its requires networking support, expressed by linking to the Networking interface.

If this project is configured on Windows, the Networking target will carry the ws2_32 link dependency with it, and SomeOtherTarget will be correctly linked. If configured on Linux, the Networking target will have no link dependencies, and nothing extra will be added to the link line.

Detecting the Compiler

Just as with the operating system, CMake detects the compiler being used and sets several variables accordingly. This is helpful for setting compiler-specific flags or working around compiler-specific bugs.

The most common variables for checking the compiler family are:

MSVC: True if the compiler is Microsoft Visual C++ (or a compatible front-end like clang-cl).
GNU: True for the GNU Compiler Collection (GCC).
Clang: True for the Clang compiler.

Example: Compiler-Specific Warning Flags

In a previous lesson, we created an INTERFACE library called StrictWarnings to apply a set of warning flags. However, the flags we used (-Wall, -Wextra) were specific to GCC and Clang. They will cause an error if used with MSVC.

We can make our StrictWarnings target portable by detecting the compiler and setting the appropriate flags for each one.

CMakeLists.txt

1cmake_minimum_required(VERSION 3.16)
2project(Greeter VERSION "1.0")
3
4add_library(StrictWarnings INTERFACE)
5
6if(MSVC) 
7  # Use Microsoft-specific warning level 4 
8  target_compile_options(StrictWarnings INTERFACE /W4) 
9else() 
10  # Assume GCC/Clang-compatible flags for others 
11  target_compile_options(StrictWarnings INTERFACE 
12    -Wall 
13    -Wextra 
14    -Wpedantic 
15  ) 
16endif() 
17
18add_subdirectory(greeter)
19add_subdirectory(app)

Now, our StrictWarnings target is a portable abstraction. Any internal target can link against it and receive the correct, most stringent warning level for whatever compiler is being used, without the target needing to know any of the compiler-specific details.

1target_link_libraries(MyTarget PRIVATE StrictWarnings)

Summary

Writing portable CMake scripts is about abstracting away platform differences. By using CMake's introspection variables, you can create a CMakeLists.txt that correctly assembles the right source files, compiler flags, and library links for any environment.

Stay Portable: Avoid hardcoded paths and platform-specific commands. Use CMake's variables (${PROJECT_SOURCE_DIR}) and commands (target_link_libraries) to express your intent.
Detect the OS: Use if(WIN32), if(APPLE), and if(UNIX) to create conditional blocks for OS-specific logic.
Detect the Compiler: Use if(MSVC), if(GNU), and if(Clang) to set compiler-specific flags or work around compiler differences.
Abstract Dependencies: When dealing with platform-specific libraries or source files, create an INTERFACE target to represent the abstract dependency. Consumers can then link to this portable target, and the platform-specific details will be handled automatically.

Cross-Platform Configurations

Working With Paths

Detecting the Operating System

Example: Platform-Specific Source Files

greeter/include/greeter/Greeter.h

Files

greeter/CMakeLists.txt

app/src/main.cpp

Abstract Away Platform Details

Example: Linking System Libraries

networking/CMakeLists.txt

CMakeLists.txt

app/CMakeLists.txt

Detecting the Compiler

Example: Compiler-Specific Warning Flags

CMakeLists.txt

Summary

Managing C++ Projects Using CMake