CMake技术问询：如何将依赖项嵌入静态库交付给客户

Hey there! As a fellow C++ newbie navigating static libraries and CMake, I totally get the frustration of wanting to hand customers a clean package (just .a/.lib + headers) instead of making them chase down dependencies. Let's break down how to fix that linking failure in your playground target and ensure your library is self-contained for clients.

The Root of the Problem #

Static libraries don't automatically bundle their dependencies—by default, CMake only keeps track of link relationships, not the actual code. So when your playground target tries to link ava_engine_client, it doesn't know to pull in the library's underlying dependencies, forcing you (and eventually your customers) to link them manually. Not ideal!

Solution 1: Let CMake Automatically Handle Dependency Propagation #

First, fix your playground's linking issue by properly declaring your library's dependencies in CMake. Use the PUBLIC keyword in target_link_libraries—this tells CMake that any target linking your library should also get access to these dependencies automatically.

Here's how to adjust your CMakeLists.txt:

# Define your static library
add_library(ava_engine_client STATIC
  src/ava_engine_client.cpp
  # Add all your library's source files here
)

# Declare dependencies with PUBLIC to propagate them to linked targets
target_link_libraries(ava_engine_client
  PUBLIC
    dependency_lib_1  # Replace with your actual dependency names
    dependency_lib_2
)

# Make sure clients can find your header files
target_include_directories(ava_engine_client
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/include
)

# Your playground target only needs to link your library now
add_executable(playground
  src/playground.cpp
)

target_link_libraries(playground
  PRIVATE
    ava_engine_client
)

With this setup, your playground will automatically link all of ava_engine_client's dependencies, and any customer using your library via CMake will get the same automatic handling.

Solution 2: Bundle Dependencies Into Your Static Library (For Zero-Customer Setup) #

If you want to go a step further and deliver a completely self-contained static library (so customers don't even need to know about your dependencies), you can merge the dependency static libraries into yours. Use a CMake post-build command to combine them with platform-specific tools:

For Unix/macOS:

add_library(ava_engine_client STATIC
  src/ava_engine_client.cpp
)

# List your dependency static library files (e.g., libfoo.a, libbar.a)
set(DEPENDENCY_LIBS "/path/to/libfoo.a" "/path/to/libbar.a")

# Merge dependencies into your library after building
add_custom_command(TARGET ava_engine_client POST_BUILD
  COMMAND ${CMAKE_AR} rcs $<TARGET_FILE:ava_engine_client> ${DEPENDENCY_LIBS}
  COMMENT "Merging dependency libraries into ava_engine_client"
)

For Windows:

add_library(ava_engine_client STATIC
  src/ava_engine_client.cpp
)

set(DEPENDENCY_LIBS "C:/path/to/foo.lib" "C:/path/to/bar.lib")

add_custom_command(TARGET ava_engine_client POST_BUILD
  COMMAND lib.exe /OUT:$<TARGET_FILE:ava_engine_client> $<TARGET_FILE:ava_engine_client> ${DEPENDENCY_LIBS}
  COMMENT "Merging dependency libraries into ava_engine_client"
)

This creates a single static library that includes all your code and your dependencies' code. Customers only need to link this one library and include your headers—no extra steps required.

Key Notes #

• Make sure all your dependencies are static libraries (.a/.lib) if you want to bundle them. Dynamic libraries (.so/.dll) can't be merged into static libraries, and you'd have to deliver those separately (which defeats your goal).
• Test the final library with a minimal customer-like project: just include your headers and link your .a/.lib—it should compile and run without any missing dependency errors.

内容的提问来源于stack exchange，提问作者Dominic Bou-Samra