In CMake, core is a STATIC library that links the compress library PRIVATE, so why does libcompress.a still appear on the app's link line?
answer
- an archive is never linked
- unresolved symbols travel downstream
- link-only, not compile requirements
- compare with a SHARED core
basics
~20 sA static library is an archive, not a linked binary, so its references into compress are resolved only when app links. CMake therefore records the private dependency as $<LINK_ONLY:compress>: on the link line, but without compress's compile requirements.
solid answer
~40 s`PRIVATE` controls usage requirements, and for a `STATIC` library CMake has to split them. An archive is a bundle of object files that is never linked by itself, so the undefined symbols `core.cpp` takes from `compress` can only be resolved when the final binary links. CMake therefore adds the private dependency to `core`'s `INTERFACE_LINK_LIBRARIES` wrapped as `$<LINK_ONLY:compress>`: consumers get it on their link line but none of its include directories or definitions. In a configure run, `core`'s `INTERFACE_LINK_LIBRARIES` held `$<LINK_ONLY:compress>` when `core` was `STATIC` and no `compress` entry when it was `SHARED`, where `libcore.dylib` had already resolved `compress` and the app linked only `libcore.dylib`. A follow-on effect: installing a static `core` for others also means installing and exporting `compress`.
code
plaintext · 2 lines-- core INTERFACE_LINK_LIBRARIES = vendor_json;$<LINK_ONLY:compress>
: && /usr/bin/c++ ... CMakeFiles/app.dir/app.cpp.o -o app libcore.a libcompress.a && :go deeper
Recall that a static library is an archive of object files that is never linked by itself.
Explain why a static library's dependencies must be resolved when the final binary links, and what LINK_ONLY keeps and drops.
Read link lines and INTERFACE_LINK_LIBRARIES to diagnose undefined symbols or surprise dependencies, and predict how switching a library to SHARED changes them.
Weigh static versus shared for a library family: static spreads its private dependencies to every consumer and every exported package, shared contains them at a deployment cost.
## What a static library is A **static library** (`libcore.a`, `core.lib`) is an archive: a container of object files with an index. Producing it involves no linking at all, so any function `core.cpp` calls from another library stays an **undefined reference** inside the archive. Those references are resolved only when something that *is* linked, an executable or a shared library, pulls `core`'s objects in. The CMake build-system manual states it directly: since static libraries are archives rather than linked binaries, CMake records their link dependencies for transitive use when linking consuming binaries. A **shared library**, in contrast, is linked when it is built. Its dependencies are resolved, or recorded as run-time dependencies, at that point, so consumers do not need to repeat them. ## What CMake records Take this project: ```cmake add_library(compress STATIC compress/compress.cpp) add_library(core STATIC core/core.cpp) target_link_libraries(core PUBLIC vendor_json PRIVATE compress) add_executable(app app.cpp) target_link_libraries(app PRIVATE core) ``` Printing `core`'s `INTERFACE_LINK_LIBRARIES` at configure time gives: | `core` kind | `INTERFACE_LINK_LIBRARIES` | app's link line (Apple clang, Ninja) | |---|---|---| | `STATIC` | `vendor_json;$<LINK_ONLY:compress>` | `libcore.a libcompress.a` | | `SHARED` | `vendor_json` | `libcore.dylib` | `$<LINK_ONLY:...>` is a generator expression documented for exactly this purpose: it keeps a private link dependency on the consumer's link line while contributing nothing to the consumer's include directories, compile definitions or compile options. ## What PRIVATE still guarantees The keyword keeps working where it matters for the code: - `app` does **not** get `compress`'s include directories, so `app.cpp` cannot quietly include `compress` headers; - `app` does **not** get `compress`'s compile definitions or options; - `app` **does** get `libcompress.a` on its link line, after `libcore.a`, so the linker can resolve `core`'s references. So "PRIVATE" on a static library means *private for compilation, still needed for linking*. Nothing is broken; the build would fail with undefined symbols otherwise. ## Walking through the final link When the linker builds `app`, it reads `app.cpp.o` and collects the symbols it still needs, among them `core::load`. It then scans `libcore.a`, extracts the object that defines `core::load`, and adds that object's own undefined symbols, such as `compress_level`, to the list. Nothing inside the archive can satisfy that new reference, so the linker needs `libcompress.a` later on the same command line. If CMake had left `compress` off, the link would stop with an undefined-symbol error naming a function `app.cpp` never calls, which is a confusing message to receive from a dependency marked `PRIVATE`. The `$<LINK_ONLY:compress>` entry is what prevents that error, and it is also why the order CMake chooses matters. ## Consequences in practice 1. **Link order.** CMake emits dependencies after their dependents (`libcore.a libcompress.a`), which is what single-pass linkers need. Hand-written `-l` flags in a consumer can break that order; letting the target graph drive the link line avoids it. 2. **Switching the kind changes the link line.** Building the same project with `-DBUILD_SHARED_LIBS=ON` or `SHARED` makes `compress` disappear from `app`'s line, because the shared `core` resolved it already. If `compress` is static, its objects are now inside `libcore`. 3. **Installing and exporting.** When a static `core` is exported for other projects, the exported link interface still names `compress`, so it must be installed and exported too; CMake refuses to generate an export that requires a target not in any export set. 4. **The object-library exception.** An `OBJECT` library linked *directly* into a static library is the one case the CMake manual names where objects are copied into the archive itself; every other dependency is left for the final link. ## How to inspect it - Print the property: `get_target_property(v core INTERFACE_LINK_LIBRARIES)` followed by `message()` shows the raw list, `$<LINK_ONLY:...>` included. - Read the real command: `ninja -t commands app` or a verbose build (`cmake --build build -v`) shows the final link line. - Compare a `STATIC` and a `SHARED` configure of the same tree to see which dependencies move.
- Does app gain access to compress's headers because compress is on its link line?No. `$<LINK_ONLY:compress>` contributes only the link item. Compile usage requirements such as `INTERFACE_INCLUDE_DIRECTORIES` and `INTERFACE_COMPILE_DEFINITIONS` from `compress` are not applied to `app`, so `app.cpp` including a `compress` header still fails unless `app` links `compress` itself.
- Why must compress be exported when a static core is installed for other teams?The exported `core` still lists `compress` in its link interface, because consumers' linkers must resolve `core`'s references to it. CMake therefore refuses to generate the export when `compress` is in no export set; install and export it alongside `core`, or make `core` shared.
- PRIVATE means the dependency never reaches any consumer's link line
- CMake copies compress's objects into libcore.a when linking it PRIVATE
- app now also gets compress's include directories
- The fix is to make the dependency INTERFACE instead