CMake Target-Based Dependencies and External Package Interoperability

Answer to the Core Question

The most maintainable way to expose an external Config‑mode package to internal targets while keeping build‑time paths out of the install tree is to link the imported target directly and, if necessary, wrap it in an interface alias that replaces absolute paths with generator expressions. The imported target’s INTERFACE_* properties are automatically propagated to any target that links to it, so downstream consumers see only what the imported package declares.

Why this works

• target_link_libraries on a target that links to an imported target automatically copies the imported target’s INTERFACE_INCLUDE_DIRECTORIES, INTERFACE_COMPILE_DEFINITIONS, and other interface properties.
• When the imported target was created by a Config‑mode find_package, it typically uses $ and $ generator expressions. CMake replaces the BUILD_INTERFACE part with the absolute build‑time path and the INSTALL_INTERFACE part with a relative path that is resolved at install time.
• By wrapping the imported target with an ALIAS target you can rename it, add custom properties, or replace absolute paths with the correct generator expressions without touching the original imported target.

Step‑by‑Step Implementation

1. Locate the imported target created by find_package (e.g., ExternalLib::External).

2. Optionally create an alias that will be used in the rest of the project:

   add_library(MyProject::External ALIAS ExternalLib::External)
   

3. For targets that need the library, link directly to the alias:

   add_library(myapp src/main.cpp)
   target_link_libraries(myapp PRIVATE MyProject::External)
   

4. Ensure the alias target does not modify the imported target’s interface properties. If you need to adjust include directories or definitions, set them on the alias with generator expressions that reference only install‑time paths:

   target_include_directories(MyProject::External INTERFACE
       $)
   

5. When installing, export the internal target and its interface:

   install(TARGETS myapp EXPORT MyAppTargets)
   install(EXPORT MyAppTargets
       NAMESPACE MyProject::
       DESTINATION lib/cmake/MyProject)
   

6. Verify that the exported file contains only relative paths. Run:

   cmake --install . --prefix /tmp/install
   cat /tmp/install/lib/cmake/MyProject/MyAppTargets.cmake
   

   Look for INTERFACE_INCLUDE_DIRECTORIES entries that use $<INSTALL_INTERFACE:…> rather than absolute paths.

7. Test from a consumer project:

   find_package(MyProject REQUIRED)
   add_executable(consumer src/consumer.cpp)
   target_link_libraries(consumer PRIVATE MyProject::myapp)
   

   Run with VERBOSE=1 to confirm the compiler sees only the install‑time include directory.

Managing INTERFACE Properties to Avoid Path Leakage

• Never set INTERFACE_INCLUDE_DIRECTORIES to absolute paths on a wrapper target. Use generator expressions or let the imported target provide the correct values.
• If you must add directories, always wrap them:

target_include_directories(MyProject::External INTERFACE
    $
    $)

• For compile definitions, use the same pattern with INTERFACE_COMPILE_DEFINITIONS.
• Do not use include_directories or global variables; keep everything inside target_* commands.

Conclusion

Linking directly to the imported target, optionally wrapped by an alias, and relying on CMake’s interface propagation ensures that only the intended interface properties reach downstream consumers. By using generator expressions you keep the install tree free from build‑time absolute paths, satisfying both strict separation of build‑time and install‑time requirements.