CMake构建自定义CUDA库链接异常问题排查

现有配置存在3个核心错误，直接导致动态库核函数无输出、静态库链接失败：

• 编译标志位置错误：CMAKE_CUDA_FLAGS配置放在了add_library/add_executable声明之后，CMake中全局编译标志必须在编译目标声明前设置才会生效，直接导致库和测试程序的编译选项不匹配。
• 静态库开启-rdc=true（可重定位设备代码）后未做设备链接：开启RDC后CUDA需要单独整合跨编译单元的设备代码，缺失这一步就会触发__cudaRegisterLinkedBinary未定义的链接错误。
• 动态库未开启位置无关代码，且和测试程序编译选项不匹配，导致CUDA核函数注册逻辑失效，运行时核函数无法正常启动，因此无打印输出。

1. 库构建阶段（lib/CMakeLists.txt）修正 #

将编译配置前置，补充静态库设备链接配置、动态库PIC配置，修正后内容如下：

# 建议升级CMake到3.18以上版本，对CUDA的原生支持更稳定
cmake_minimum_required (VERSION 3.18)
project (generate_lib LANGUAGES CUDA CXX)

# 所有编译配置必须放在编译目标声明之前
set (SCRIPT_ROOT $ENV{HOME}/Desktop/cuda_custom_lib_test)
set(CMAKE_CUDA_ARCHITECTURES 60) # 替代旧的-arch=sm_60写法，由CMake原生处理
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CUDA_STANDARD 17)
set(CMAKE_POSITION_INDEPENDENT_CODE ON) # 动态库必须开启位置无关代码
set (CMAKE_VERBOSE_MAKEFILE TRUE)

# CUDA编译选项
set (CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -Xcudafe --display_error_number")
set (CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -Xcudafe --diag_suppress=3057")
set (CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -Xcudafe --diag_suppress=1301")
set (CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -Xcudafe --diag_suppress=3059")
set (CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -rdc=true")

include_directories(${SCRIPT_ROOT}/include)
file(GLOB_RECURSE SRC_CU_PATH ${SCRIPT_ROOT}/src/*.cu)
set (LIBRARY_OUTPUT_PATH ${PROJECT_SOURCE_DIR})

# 构建动态库
add_library (CUDA_CUSTOM_LIB_TEST_shared SHARED ${SRC_CU_PATH})
set_target_properties(CUDA_CUSTOM_LIB_TEST_shared PROPERTIES OUTPUT_NAME "cuda_custom_lib_test")
target_link_libraries( CUDA_CUSTOM_LIB_TEST_shared PRIVATE ${CUDA_LIBRARIES})

# 构建静态库
add_library(CUDA_CUSTOM_LIB_TEST_static STATIC ${SRC_CU_PATH})
set_target_properties(CUDA_CUSTOM_LIB_TEST_static PROPERTIES OUTPUT_NAME "cuda_custom_lib_test")
set_target_properties(CUDA_CUSTOM_LIB_TEST_static PROPERTIES CUDA_SEPARABLE_COMPILATION ON)
# 关键配置：自动处理静态库的设备链接步骤，解决注册函数未定义错误
set_target_properties(CUDA_CUSTOM_LIB_TEST_static PROPERTIES CUDA_RESOLVE_DEVICE_SYMBOLS ON)
target_link_libraries( CUDA_CUSTOM_LIB_TEST_static PRIVATE ${CUDA_LIBRARIES})

2. 测试程序阶段（Test/CMakeLists.txt）修正 #

同样将编译配置前置，保持和库一致的编译选项，修正后内容如下：

cmake_minimum_required (VERSION 3.18)
project (MAIN_TEST LANGUAGES CUDA CXX)

# 编译配置前置
set (SCRIPT_ROOT $ENV{HOME}/Desktop/cuda_custom_lib_test)
set(CMAKE_CUDA_ARCHITECTURES 60)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CUDA_STANDARD 17)
set (EXECUTABLE_OUTPUT_PATH ${PROJECT_SOURCE_DIR}/bin)

set (CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -Xcudafe --display_error_number")
set (CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -Xcudafe --diag_suppress=3057")
set (CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -Xcudafe --diag_suppress=1301")
set (CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -Xcudafe --diag_suppress=3059")
# 链接开启RDC的静态库必须加该配置，链接动态库时建议保持一致也加上
set (CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -rdc=true")

include_directories(${SCRIPT_ROOT}/include)
set (SRC_LIST ${PROJECT_SOURCE_DIR}/src/main.cu)

# 查找库文件，自动匹配.so/.a格式，禁止搜索系统默认路径避免找错版本
find_library(LIBTEST 
    NAMES cuda_custom_lib_test
    HINTS ${SCRIPT_ROOT}/lib
    NO_DEFAULT_PATH
)

add_executable(main ${SRC_LIST})
# 注意链接顺序：自定义库放在CUDA系统库之前
target_link_libraries(main PRIVATE ${LIBTEST} ${CUDA_LIBRARIES})

3. 额外注意事项 #

• 如果你的代码不需要跨.cu文件调用核函数/设备函数（比如当前示例的简单代码），可以直接删掉两个CMakeLists里的-rdc=true配置，静态库也不需要设置CUDA_RESOLVE_DEVICE_SYMBOLS，编译链接流程会更简单。
• 重新编译前必须删除两个build目录下的所有缓存文件，避免旧的错误配置残留影响构建结果。
• 运行动态库链接的可执行文件时如果提示找不到库，需要把库路径加入环境变量：

  export LD_LIBRARY_PATH=/home/你的用户名/Desktop/cuda_custom_lib_test/lib:$LD_LIBRARY_PATH
  

内容的提问来源于stack exchange，提问作者ZaohuiZHANG