Diagnosing Missing Transitive Link Dependencies in Modern CMake

Problem Statement

Build systems built with CMake 3.11+ often compile cleanly yet fail at link time with errors such as undefined reference to ‘foo()’. The symbols should be provided by a library you listed in target_link_libraries, but the linker never sees that library. The root cause is usually a mismatch between how the dependency is declared and how it propagates to the consuming target.

Recognizable Condition

• Compilation succeeds; linker fails with undefined references.
• Source files that use the missing symbol are part of the target that reported the error.
• Running VERBOSE=1 make (or the equivalent in Ninja or your IDE) shows the linker command but the expected library is absent.

Cause & Diagnostic Table

Cause	Diagnostic Check	Fix
Link scope mismatch (PRIVATE instead of PUBLIC/INTERFACE)	Inspect target_link_libraries for the target that uses the symbol.	Change scope to PUBLIC or INTERFACE as needed.
Missing INTERFACE library definition	Verify that the dependency target is an INTERFACE library and has INTERFACE_LINK_LIBRARIES set.	Add add_library(foo INTERFACE) and target_link_libraries(foo INTERFACE bar).
Generator expression evaluates to empty	Print the expression value during configure: message(STATUS \"expr: ${expr}\").	Correct the condition or provide a fallback value.
find_package silently fails or returns wrong targets	Check the find_package result and the package‑config file.	Specify an explicit version or adjust PATHS and NO_DEFAULT_PATH.

Ordered Checks

1. Verify Link Scopes
   

   get_target_property(LINKS myapp LINK_LIBRARIES)
   message(STATUS \"myapp LINK_LIBRARIES: ${LINKS}\")

   Look for PRIVATE or PRIVATE qualifiers. If the library that provides the missing symbol is marked PRIVATE, consumers will not get it.

2. Inspect Target Type
   

   get_target_property(TYPE mylib TYPE)
   message(STATUS \"mylib TYPE: ${TYPE}\")

   INTERFACE libraries must use INTERFACE_LINK_LIBRARIES. For SHARED or STATIC, the library itself is linked, but its interface may still need to be propagated.

3. Check Generator Expressions
   

   message(STATUS \"${MY_EXPR}\")

   Run CMake with --trace-expand to see how expressions are resolved. Empty results often cause missing libraries.

4. Confirm find_package Success
   

   if(NOT TARGET OpenSSL::SSL)
     message(FATAL_ERROR \"OpenSSL not found\")
   endif()

   Make sure the requested version is available and that the package’s config file exports the correct targets.

5. Verify Generated Link Command
   

   VERBOSE=1 make

   Check that the library appears on the command line. If it’s missing, the problem lies in propagation.

Concrete Example

Suppose app uses a helper library mylib, and mylib itself relies on libfoo. The following minimal CMakeLists.txt demonstrates a common pitfall:

# app/CMakeLists.txt
add_executable(app main.cpp)
# Wrong: PRIVATE hides libfoo from consumers
add_library(mylib STATIC src/mylib.cpp)
# libfoo is only linked to mylib, not to app
target_link_libraries(mylib PRIVATE libfoo)
# app links mylib but does not see libfoo
target_link_libraries(app PRIVATE mylib)

During link, app fails with undefined references to symbols from libfoo. The fix is to propagate libfoo as a public requirement:

target_link_libraries(mylib PUBLIC libfoo)
# or, if mylib is an INTERFACE library
add_library(mylib INTERFACE)
target_link_libraries(mylib INTERFACE libfoo)

Now app automatically links against libfoo because the dependency is public.

Escalation Criteria

1. If after correcting scopes, types, expressions, and find_package the linker still reports undefined symbols, run VERBOSE=1 make and capture the exact link command.
2. Cross‑check that the library file exists at the path shown. A missing file can be caused by a wrong CMAKE_LIBRARY_OUTPUT_DIRECTORY or a missing install step.
3. If the library is present but still not linked, inspect the target’s INTERFACE_LINK_LIBRARIES property with:

   get_target_property(LINKS mylib INTERFACE_LINK_LIBRARIES)
   message(STATUS \"mylib INTERFACE_LINK_LIBRARIES: ${LINKS}\")

4. When all of the above checks pass, consider posting a minimal reproducible example on the CMake mailing list or filing a bug. Include the CMake version, the output of --trace-expand, and the linker command.

Common Pitfalls & Tips

• Policy CMP0003: Mixing link_directories() with modern target_link_libraries() can hide transitive dependencies. Prefer the target‑based API exclusively.
• INTERFACE Libraries: They do not appear in the link line unless they have INTERFACE_LINK_LIBRARIES. Always set this property if the interface needs to bring in other libraries.
• Generator Expressions: They are evaluated at generate time. Debugging requires inspecting the build system, not the CMakeCache.txt.
• find_package: A silent failure can happen if the requested version is not available. Use REQUIRED or check the TARGET existence to catch this early.

Verification Checklist

• Run cmake -DCMAKE_VERBOSE_MAKEFILE=ON .. and confirm the linker command contains all expected libraries.
• Use get_target_property to inspect INTERFACE_LINK_LIBRARIES and LINK_LIBRARIES for each target.
• For IDE users, regenerate the project and inspect the link inputs in the project settings.
• Verify that the library files (.lib, .a, .so, .dll) exist in the output directories.

Limitations

This guide assumes CMake 3.11 or newer and a typical build system (Make, Ninja, or an IDE). It does not cover cross‑platform nuances such as Windows subsystem differences or static vs. dynamic runtime libraries. If you encounter platform‑specific linker errors, consult the platform’s documentation or the CMake FAQ.

Conclusion

Missing transitive link dependencies are almost always caused by an incorrect link scope, a mis‑declared INTERFACE library, or a generator expression that resolves to nothing. By following the ordered checks and applying the targeted fixes, most projects can resolve the undefined reference errors quickly. When the problem persists, a verbose build log and a minimal reproducible example are your best tools for escalation.