In CMake, why is target_compile_options preferred over directory-wide commands such as add_compile_options and include_directories?
answer
- scope: one target or a directory
- order of commands matters
- subdirectories inherit silently
- usage requirements travel, directory flags do not
basics
~20 sDirectory-wide commands affect every target in a directory and its subdirectories, depending on call order, and never reach consumers in other directories. target_* commands state each target's requirements explicitly and let PUBLIC and INTERFACE requirements propagate to whoever links it.
solid answer
~40 s`add_compile_options`, `add_compile_definitions`, `include_directories` and `link_libraries` write **directory properties** that seed targets in that directory and every subdirectory. That has three costs. Scope is implicit: a flag meant for one library lands on tests, tools and fetched dependencies added below. Order matters, and not uniformly: `add_compile_options` affects only targets created after the call, while `include_directories` also updates targets already defined in the same `CMakeLists.txt`. And nothing reaches consumers: a target in a sibling directory that links your library does not inherit your directory's include path, so the requirement is repeated or forgotten. `target_compile_options`, `target_include_directories`, `target_compile_definitions` and `target_link_libraries` attach the setting to one named target, and their `PUBLIC` and `INTERFACE` forms carry it to dependents. The manuals for these commands say the same: prefer the `target_*` form.
code
cmake · 8 linescmake_minimum_required(VERSION 3.25...4.4)
project(dirw CXX)
add_executable(early main.cpp)
add_compile_options(-DLATE_OPTION)
include_directories(${CMAKE_SOURCE_DIR}/inc)
add_executable(late main.cpp)
# compile_commands.json: early gets -I.../inc but not -DLATE_OPTION;
# late gets bothgo deeper
Recall the pairs, add_compile_options versus target_compile_options and include_directories versus target_include_directories, and that the target form is the modern default.
Explain directory properties versus target properties, how subdirectories inherit, and why order of calls changes which targets get a directory-wide setting.
Trace a leaked flag or a missing include path to directory-wide commands, and refactor them into target requirements or an INTERFACE settings target.
Make target-centric style a reviewable rule so dependencies stay unaffected and exported packages carry complete requirements.
## Two ways to say the same thing CMake has two families of commands that put flags, definitions and include paths on the compiler's command line: | Directory-wide command | Target-centric equivalent | |---|---| | `add_compile_options` | `target_compile_options` | | `add_compile_definitions` (and the older `add_definitions`) | `target_compile_definitions` | | `include_directories` | `target_include_directories` | | `link_libraries` | `target_link_libraries` | | `add_link_options` | `target_link_options` | The directory-wide commands write **directory properties** such as `COMPILE_OPTIONS` and `INCLUDE_DIRECTORIES`. The target-centric commands write properties of **one named target**. Modern CMake style, and the CMake manuals themselves, favour the second family; the `include_directories` page ends with a note to prefer `target_include_directories`, and the `link_libraries` page says `target_link_libraries` should be preferred whenever possible. ## Problem 1: the scope is implicit A directory property applies to targets in that directory **and every subdirectory**. A top-level `add_compile_options(-Werror)` is inherited by: - the library you meant it for; - its tests and benchmark executables; - code generators and small tools; - third-party projects added with `add_subdirectory`, including those that `FetchContent` adds. The last group is where it hurts: a dependency that compiles cleanly on its own suddenly fails with warnings promoted to errors. ## Problem 2: the result depends on call order Directory properties seed target properties, and the commands do not behave alike. Reproduced with CMake 4.4: ```cmake add_executable(early main.cpp) add_compile_options(-DLATE_OPTION) include_directories(${CMAKE_SOURCE_DIR}/inc) add_executable(late main.cpp) ``` The compile commands show that `early` does **not** get `-DLATE_OPTION` but **does** get the include directory, while `late` gets both. That matches the documentation: `add_compile_options` affects targets created afterwards, whereas `include_directories` also appends to the `INCLUDE_DIRECTORIES` property of each target already defined in the current `CMakeLists.txt`. Reordering lines therefore changes builds in ways a reviewer cannot see. ## Problem 3: requirements do not travel A library `ledger` in `src/ledger/` whose public header needs `include/` must make that path available to every consumer. With `include_directories` in `src/ledger/CMakeLists.txt`, the path applies only inside that directory tree; an application in `apps/` that links `ledger` does not receive it and fails with a missing header. The usual repair is a second `include_directories` in `apps/`, which is exactly the duplication the target model avoids. With `target_include_directories(ledger PUBLIC include)`, the path becomes a **usage requirement** of `ledger`; anything that links `ledger` receives it, wherever it lives in the source tree. The keyword semantics are their own topic; here the point is that only target commands have a way to propagate at all. ## Where directory-wide settings still fit A few settings genuinely belong to everything in a directory tree, and teams sometimes still use the directory form for them: 1. a project-wide definition such as a platform macro required by every translation unit; 2. flags a toolchain file supplies through `CMAKE_CXX_FLAGS_INIT`, which reach every target without any command in the project's own files; 3. quick experiments that are not meant to be committed. Even then, an `INTERFACE` library that carries the shared options, linked by the targets that want them, keeps the opt-in explicit and avoids leaking into dependencies. ## Migrating an existing project Large projects rarely switch in one change. A sequence that keeps every step reviewable: 1. List the directory-wide calls with a search for `add_compile_options`, `add_definitions`, `include_directories` and `link_libraries`. 2. For each, decide which targets actually need the setting, and whether consumers need it too. 3. Move per-target needs into `target_*` calls on those targets, choosing the visibility that matches who needs it. 4. Collect genuinely shared settings, such as the warning set, into an `INTERFACE` library that targets link explicitly. 5. Compare `compile_commands.json` before and after (`CMAKE_EXPORT_COMPILE_COMMANDS`), so any flag that disappeared or appeared is visible in review. ## A target-centric rewrite ```cmake add_library(project_warnings INTERFACE) target_compile_options(project_warnings INTERFACE -Wall -Wextra) add_library(ledger src/ledger.cpp) target_include_directories(ledger PUBLIC include) target_link_libraries(ledger PRIVATE project_warnings) ``` Every requirement is attached to a named target, the warnings reach only targets that link `project_warnings`, and fetched dependencies are untouched. This is also what makes an exported package usable, because only target properties can be exported to other projects.
- A top-level add_compile_options(-Werror) breaks a dependency added with FetchContent. Why, and what is the fix?FetchContent adds the dependency with `add_subdirectory`, so when the `add_compile_options` call comes before `FetchContent_MakeAvailable`, the dependency's targets inherit the top-level directory's `COMPILE_OPTIONS`. Move the flag onto your own targets with `target_compile_options`, or onto an `INTERFACE` warnings target they link, so the dependency compiles with its own settings.
- Does add_compile_options affect a target created earlier in the same CMakeLists.txt?No. It adds to the directory's `COMPILE_OPTIONS`, which initializes targets created afterwards in that directory and below. `include_directories` behaves differently: it also appends to targets already defined in the current `CMakeLists.txt`, so the two commands are order-sensitive in different ways.
- include_directories makes the path available to every target that links the library, anywhere
- add_compile_options also changes targets defined earlier in the same file
- Directory-wide flags stay out of subprojects added with add_subdirectory
- Target commands and directory commands are interchangeable apart from style