diff --git a/Help/variable/CMAKE_DL_LIBS.rst b/Help/variable/CMAKE_DL_LIBS.rst index 50d313d8d1..2574192eb0 100644 --- a/Help/variable/CMAKE_DL_LIBS.rst +++ b/Help/variable/CMAKE_DL_LIBS.rst @@ -1,7 +1,49 @@ CMAKE_DL_LIBS ------------- -Name of library containing ``dlopen`` and ``dlclose``. +This variable contains a name of the dynamic loading library, or a list of +system libraries needed to use the ``dlopen()`` and ``dlclose()`` functions. -The name of the library that has ``dlopen`` and ``dlclose`` in it, usually -``-ldl`` on most UNIX machines. +Few examples of the values this variable is set to: + +``dl`` + On most Unix-like systems. + +``-lld`` + On AIX. + +``dld`` + On HP-UX. + +"" + Empty string value or not set on systems that have ``dl*()`` functions + either in the default library that is implicitly linked (e.g., BSD-like + systems, Haiku, macOS, SunOS, etc.), or on systems that don't provide these + functions (e.g., Windows). + +Examples +^^^^^^^^ + +Example: Linking Dynamic Loading Library +"""""""""""""""""""""""""""""""""""""""" + +Using this variable in a project that uses dynamic loading functionality: + +.. code-block:: cmake + + target_link_libraries(example PRIVATE ${CMAKE_DL_LIBS}) + +Example: Checking Symbols +""""""""""""""""""""""""" + +Checking for symbols with the dynamic loading library linked during the check: + +.. code-block:: cmake + + include(CheckSymbolExists) + include(CMakePushCheckState) + + cmake_push_check_state(RESET) + set(CMAKE_REQUIRED_LIBRARIES ${CMAKE_DL_LIBS}) + check_symbol_exists(dlopen "dlfcn.h" HAVE_DLOPEN) + cmake_pop_check_state()