In CMake, what do the PRIVATE, PUBLIC and INTERFACE keywords mean in target_link_libraries and target_include_directories?
answer
- two property sets per target
- building it versus using it
- INTERFACE_ prefixed properties
- what the public header includes
basics
~20 sThey decide who receives a setting. PRIVATE applies it only when building the target itself, INTERFACE only to targets that link to it, and PUBLIC to both, so a dependency that a library's public headers include must be PUBLIC.
solid answer
~40 sEvery CMake target carries two sets of properties: its **build specification** (`INCLUDE_DIRECTORIES`, `COMPILE_DEFINITIONS`, `LINK_LIBRARIES`), used to compile and link the target itself, and its **usage requirements** (`INTERFACE_INCLUDE_DIRECTORIES`, `INTERFACE_COMPILE_DEFINITIONS`, `INTERFACE_LINK_LIBRARIES`), handed to whatever links to it. `PRIVATE` writes only the first set, `INTERFACE` only the second, `PUBLIC` both. When `app` runs `target_link_libraries(app PRIVATE core)`, CMake reads `core`'s `INTERFACE_*` properties and appends them to `app`'s. So if `core.hpp` includes a header from `vendor_json`, `core` must link `vendor_json` as `PUBLIC`; with `PRIVATE`, `core` builds but `app` fails with "file not found". A dependency used only in `core.cpp` stays `PRIVATE`, and one used only by `core`'s headers is `INTERFACE`.
code
plaintext · 3 linesFAILED: [code=1] CMakeFiles/app.dir/app.cpp.o
core/include/core/core.hpp:2:10: fatal error: 'vendor_json/json.hpp' file not found
1 error generated.go deeper
Recall the one-line rule: PRIVATE is for me, INTERFACE is for my users, PUBLIC is for both, and show it with a library whose header includes another library.
Explain the two property sets, the INTERFACE_ prefixed usage requirements, and how linking appends a dependency's usage requirements to the consumer, transitively through PUBLIC links.
Show you choose the keyword from where a dependency appears, diagnose a missing-header error in a consumer as a wrong keyword on the library, and push back on blanket PUBLIC.
Frame usage requirements as a library's published contract: what leaks through PUBLIC becomes every consumer's and every package user's dependency, so the keywords are API design.
## Two property sets on every target A CMake **target** is a named thing the build produces or describes: an executable from `add_executable`, a library from `add_library`. Commands such as `target_include_directories`, `target_compile_definitions`, `target_compile_options` and `target_link_libraries` do not touch a global flag list; they write **properties** on one target. Each of these settings exists twice: | Setting | Build specification (used to build the target) | Usage requirement (handed to consumers) | |---|---|---| | Include directories | `INCLUDE_DIRECTORIES` | `INTERFACE_INCLUDE_DIRECTORIES` | | Preprocessor definitions | `COMPILE_DEFINITIONS` | `INTERFACE_COMPILE_DEFINITIONS` | | Compiler options | `COMPILE_OPTIONS` | `INTERFACE_COMPILE_OPTIONS` | | Libraries to link | `LINK_LIBRARIES` | `INTERFACE_LINK_LIBRARIES` | The **usage requirements** are what another target needs in order to compile against and link with this one. The CMake build-system manual stresses that they must be real requirements, not convenient recommendations. ## What each keyword writes The scope keyword in front of each item picks the set: - **`PRIVATE`** populates only the build specification. The target itself compiles with the setting; nobody downstream sees it. - **`INTERFACE`** populates only the usage requirements. The target itself does not get the setting; every consumer does. - **`PUBLIC`** populates both. Propagation happens when a consumer links: `target_link_libraries(app PRIVATE core)` makes CMake read `core`'s `INTERFACE_*` properties and append them to `app`'s own build properties. The keyword `app` uses decides, in turn, whether `core`'s requirements travel further to whoever links `app`. Because `PUBLIC` and `INTERFACE` items of a library become part of its link interface, requirements chain transitively through any number of `PUBLIC` links. ## The worked case: core, an app and a test Take a library `core` whose public header `core/core.hpp` includes `<vendor_json/json.hpp>` from a header-only third-party target `vendor_json`, used by both `app` and `core_tests`: ```cmake add_library(vendor_json INTERFACE) target_include_directories(vendor_json INTERFACE third/include) add_library(core STATIC core/core.cpp) target_include_directories(core PUBLIC core/include) target_link_libraries(core PRIVATE vendor_json) # wrong keyword add_executable(app app.cpp) target_link_libraries(app PRIVATE core) ``` `core` itself compiles, because `PRIVATE` gave it the vendor include path. `app.cpp` includes `core.hpp`, which includes the vendor header, and the include path never reached `app`. Apple clang stops with `fatal error: 'vendor_json/json.hpp' file not found`. Changing the line to `PUBLIC vendor_json` fixes both `app` and `core_tests` without either of them naming `vendor_json`. ## Choosing the keyword A practical rule follows directly from where the dependency appears: 1. Used only in the library's `.cpp` files: **`PRIVATE`**. 2. Used in the library's public headers *and* its implementation (a base class, a member type, an inline call): **`PUBLIC`**. 3. Used only by the headers, never compiled into the library (typical for header-only targets created with `add_library(name INTERFACE)`): **`INTERFACE`**. The same reasoning applies to `target_include_directories`: the directory holding the public headers is `PUBLIC`; a `src/detail` directory only the implementation includes is `PRIVATE`. ## How far a requirement travels The keyword on *each* link in a chain decides whether requirements keep moving. Suppose a second library `engine` sits between `core` and the application: | Link | Keyword | `engine`'s consumers get `core`'s requirements? | |---|---|---| | `target_link_libraries(engine PUBLIC core)` | `PUBLIC` | yes, and through `core`, `vendor_json`'s | | `target_link_libraries(engine PRIVATE core)` | `PRIVATE` | no; only `engine` itself compiles with them | | `target_link_libraries(engine INTERFACE core)` | `INTERFACE` | yes, but `engine` itself does not | So `engine` must link `core` as `PUBLIC` only if `engine`'s own public headers include `core.hpp`. The test executable `core_tests` is a leaf: it links `core` with `PRIVATE`, because nothing links to an executable, and still receives everything `core` publishes. Reading a target's requirements is therefore a walk over the graph, and each library answers only for its own headers. ## Mistakes interviewers listen for - **Everything `PUBLIC`.** It compiles, but every consumer now gets include paths and definitions it never asked for, can silently start including headers it never declared a dependency on, and an exported package then demands those dependencies from every user. - **Consumers repeating paths.** If `app` has to add `core`'s include directory by hand, `core`'s usage requirements are wrong; fix the library, not each consumer. - **Mixing signatures.** `target_link_libraries(core vendor_json)` with no keyword is the older *plain* signature, whose dependencies are transitive. A target must use either all-keyword or all-plain calls; mixing them is a configure error. - **Expecting `PRIVATE` to hide the library entirely.** For a `STATIC` library, a `PRIVATE` link dependency still reaches the final link line, because an archive cannot resolve its own symbols; only its compile requirements stay private.
- What does target_link_libraries(core vendor_json) do without any keyword?That is the plain signature. Its dependencies are transitive by default: they are linked into `core` and recorded in `INTERFACE_LINK_LIBRARIES`, so they propagate to consumers much as `PUBLIC` would. A target cannot mix it with the keyword signature; CMake stops with "The keyword signature for target_link_libraries has already been used with the target". Prefer the keyword form.
- Why not simply make every dependency PUBLIC to avoid missing-header errors?Because usage requirements are a contract. Over-sharing gives every consumer extra include paths, definitions and link items, lets consumers compile against headers they never declared, makes dependency changes ripple through rebuilds, and, once the library is installed and exported, forces every package user to provide those dependencies too.
- PRIVATE hides the library from other targets in the same project
- INTERFACE also applies the setting when compiling the library itself
- The keyword matters for linking only, never for include directories
- Make every dependency PUBLIC so nothing ever fails to compile
- Each consumer should add the library's include directory itself