From 25e7791dc11d2dc893138782ffb9175a41ea2608 Mon Sep 17 00:00:00 2001 From: Alexander Neundorf Date: Tue, 10 Jan 2023 23:31:08 +0100 Subject: Help: improve docs for INSTALL_RPATH The documentation for INSTALL_RPATH now links to all (or at least most) properties (and variables) related to the install rpath, which should make it easier for users to find out how RPATH works. Also change "True" to "TRUE" --- Help/prop_tgt/INSTALL_RPATH.rst | 21 ++++++++++++++++++--- Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst | 2 +- 2 files changed, 19 insertions(+), 4 deletions(-) diff --git a/Help/prop_tgt/INSTALL_RPATH.rst b/Help/prop_tgt/INSTALL_RPATH.rst index 4549b92..07d7ae6 100644 --- a/Help/prop_tgt/INSTALL_RPATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH.rst @@ -3,10 +3,25 @@ INSTALL_RPATH The rpath to use for installed targets. -A semicolon-separated list specifying the rpath to use in installed +By default, the install rpath is empty. It can be set using this property, +which is a semicolon-separated list specifying the rpath to use in installed targets (for platforms that support it). This property is initialized -by the value of the variable :variable:`CMAKE_INSTALL_RPATH` if it is set when -a target is created. +by the value of the variable :variable:`CMAKE_INSTALL_RPATH` if it is set +when a target is created. +Beside setting the install rpath manually, using the +:prop_tgt:`INSTALL_RPATH_USE_LINK_PATH` target property it can also be +generated automatically by CMake. + +Normally CMake uses the build tree for the RPATH when building executables +etc on systems that use RPATH, see the :prop_tgt:`BUILD_RPATH` target +property. When the software is installed +the targets are edited (or relinked) by CMake (see +:variable:`CMAKE_NO_BUILTIN_CHRPATH`) to have the install RPATH. +This editing during installation can be avoided via +the :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property. + +For handling toolchain-dependent RPATH entries the +:prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` can be used. Because the rpath may contain ``${ORIGIN}``, which coincides with CMake syntax, the contents of ``INSTALL_RPATH`` are properly escaped in the diff --git a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst index d16a7a1..ef859cf 100644 --- a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst @@ -3,7 +3,7 @@ INSTALL_RPATH_USE_LINK_PATH Add paths to linker search and installed rpath. -``INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``True`` +``INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``TRUE`` will append to the runtime search path (rpath) of installed binaries any directories outside the project that are in the linker search path or contain linked library files. The directories are appended after the -- cgit v0.12