From bbac630f6a3c6b6f06e29df2882f367a9a072d11 Mon Sep 17 00:00:00 2001 From: Ben Morgan Date: Wed, 19 Jul 2023 14:25:30 +0100 Subject: [PATCH] Clarify shared/module library linking after RDC update PR #848 taught celeritas_target_link_libraries that MODULE targets are always the final one in any link chain and hence to device link them correctly. Update text on MODULE vs SHARED targets to account for this update. Retain text on explicit linking of final target to cover case of projects that enforce use of SHARED targets for plugins. --- doc/usage.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/usage.rst b/doc/usage.rst index ce382f8e09..6b08ddab43 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -50,18 +50,20 @@ final application whether CPU-only or CUDA enabled:: add_executable(myapplication ...) celeritas_target_link_libraries(myapplication PRIVATE myconsumer) -The two exceptions to this are when your project builds a CMake ``SHARED`` library that: +If your project builds shared libraries that are intended to be loaded at application +runtime (e.g. via ``dlopen``), you should prefer use the the CMake ``MODULE`` target type:: -* will be loaded into an application at runtime (e.g. via ``dlopen``). -* is intended to be linked to by downstream projects that do not use Celeritas + add_library(myplugin MODULE ...) + celeritas_target_link_libraries(myplugin PRIVATE Celeritas::celeritas) -In the first case the CMake target type should be changed to ``MODULE`` for which -CMake and ``celeritas_target_link_libraries`` correctly handle device linking. For -the second case, or if you cannot use ``MODULE``, you must use ``target_link_libraries`` -and link to both the primary Celeritas target and its device code counterpart:: +This is recommended as ``celeritas_target_link_libraries`` understands these as a final +target for which all device symbols require resolving. If you are forced to use the ``SHARED`` +target type for plugin libraries (e.g. via your project), then to correctly link these +for runtime loading you must explicitly link to both the primary Celeritas target and +its device code counterpart:: - add_library(mylibrary SHARED ...) - target_link_libraries(mylibrary PRIVATE Celeritas::celeritas $) + add_library(mybadplugin SHARED ...) + target_link_libraries(mybadplugin PRIVATE Celeritas::celeritas $) Celeritas device code counterpart target names are always the name of the primary target appended with ``_final``. They are only present if Celeritas was built with CUDA