diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index a72eac1125..8bb9ddef7d 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -1696,6 +1696,9 @@ In the following, the phrase "the ``tgt`` filename" means the name of the section for details. Many :ref:`Find Modules` produce imported targets with the ``UNKNOWN`` type and therefore will be ignored. +On platforms that support runtime paths (``RPATH``), refer to the +:prop_tgt:`INSTALL_RPATH` target property. +On Apple platforms, refer to the :prop_tgt:`INSTALL_NAME_DIR` target property. Export And Install Expressions ------------------------------ diff --git a/Help/prop_tgt/BUILD_RPATH.rst b/Help/prop_tgt/BUILD_RPATH.rst index 1f917a519c..902e2f7af1 100644 --- a/Help/prop_tgt/BUILD_RPATH.rst +++ b/Help/prop_tgt/BUILD_RPATH.rst @@ -3,13 +3,34 @@ BUILD_RPATH .. versionadded:: 3.8 -A :ref:`semicolon-separated list ` specifying runtime path (``RPATH``) -entries to add to binaries linked in the build tree (for platforms that -support it). The entries will *not* be used for binaries in the install -tree. See also the :prop_tgt:`INSTALL_RPATH` target property. +A :ref:`semicolon-separated list ` specifying +runtime path (``RPATH``) entries to add to binaries linked in the +build tree (for platforms that support it). By default, CMake sets +the runtime path of binaries in the build tree to contain search +paths it knows are needed to find the shared libraries they link. +Projects may set ``BUILD_RPATH`` to specify additional search paths. + +The build-tree runtime path will *not* be used for binaries in the +install tree. It will be replaced with the install-tree runtime path +during the installation step. See also the :prop_tgt:`INSTALL_RPATH` +target property. This property is initialized by the value of the variable :variable:`CMAKE_BUILD_RPATH` if it is set when a target is created. This property supports :manual:`generator expressions `. + +Other settings that affect the build-tree runtime path include: + +* The :variable:`CMAKE_SKIP_RPATH` variable completely disables runtime + paths in both the build tree and install tree. + +* The :prop_tgt:`SKIP_BUILD_RPATH` target property disables setting any + runtime path in the build tree. + +* The :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target property causes the + automatically-generated runtime path to use entries relative to ``$ORIGIN``. + +* The :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property causes binaries + in the build tree to be built with the install-tree runtime path. diff --git a/Help/prop_tgt/INSTALL_NAME_DIR.rst b/Help/prop_tgt/INSTALL_NAME_DIR.rst index 47a003774f..84310b9a93 100644 --- a/Help/prop_tgt/INSTALL_NAME_DIR.rst +++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst @@ -6,8 +6,9 @@ Directory name for installed targets on Apple platforms. ``INSTALL_NAME_DIR`` is a string specifying the directory portion of the "install_name" field of shared libraries on Apple platforms for installed targets. When not set, the default directory used is determined -by :prop_tgt:`MACOSX_RPATH`. Policies :policy:`CMP0068` and :policy:`CMP0042` -are also relevant. +by :prop_tgt:`MACOSX_RPATH`. If the :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` +property is set, this will be used already in the build tree. +Policies :policy:`CMP0068` and :policy:`CMP0042` are also relevant. This property is initialized by the value of the variable :variable:`CMAKE_INSTALL_NAME_DIR` if it is set when a target is @@ -16,3 +17,7 @@ created. This property supports :manual:`generator expressions `. In particular, the :genex:`$` generator expression can be used to set the directory relative to the install-time prefix. + +On platforms that support runtime paths (``RPATH``), refer to the +:prop_tgt:`INSTALL_RPATH` target property. +Under Windows, the :genex:`TARGET_RUNTIME_DLLS` generator expression is related. diff --git a/Help/prop_tgt/INSTALL_RPATH.rst b/Help/prop_tgt/INSTALL_RPATH.rst index 4549b92283..e5110b8937 100644 --- a/Help/prop_tgt/INSTALL_RPATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH.rst @@ -3,10 +3,27 @@ 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. +Runtime paths can be disabled completely via the :variable:`CMAKE_SKIP_RPATH` +variable. Because the rpath may contain ``${ORIGIN}``, which coincides with CMake syntax, the contents of ``INSTALL_RPATH`` are properly escaped in the @@ -14,3 +31,6 @@ the contents of ``INSTALL_RPATH`` are properly escaped in the This property supports :manual:`generator expressions `. + +On Apple platforms, refer to the :prop_tgt:`INSTALL_NAME_DIR` target property. +Under Windows, the :genex:`TARGET_RUNTIME_DLLS` generator expression is related. diff --git a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst index d16a7a1c61..ef859cf2d2 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 diff --git a/Help/prop_tgt/SKIP_BUILD_RPATH.rst b/Help/prop_tgt/SKIP_BUILD_RPATH.rst index 7086b1bc46..1fe170ca6b 100644 --- a/Help/prop_tgt/SKIP_BUILD_RPATH.rst +++ b/Help/prop_tgt/SKIP_BUILD_RPATH.rst @@ -4,6 +4,7 @@ SKIP_BUILD_RPATH Should rpaths be used for the build tree. ``SKIP_BUILD_RPATH`` is a boolean specifying whether to skip automatic -generation of an rpath allowing the target to run from the build tree. +generation of an rpath allowing the target to run from the build tree, +see also the :prop_tgt:`BUILD_RPATH` target property. This property is initialized by the value of the variable :variable:`CMAKE_SKIP_BUILD_RPATH` if it is set when a target is created. diff --git a/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst b/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst index 5b59a6ef2c..839771a221 100644 --- a/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst +++ b/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst @@ -9,3 +9,6 @@ installed the executables etc are relinked by CMake to have the install ``RPATH``. If this variable is set to true then the software is always built with the install path for the ``RPATH`` and does not need to be relinked when installed. + +This is used to initialize the :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property +for all targets. diff --git a/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst b/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst index b9b045e7de..483ec5f600 100644 --- a/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst +++ b/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst @@ -10,6 +10,9 @@ a builtin editor to change the runtime search path in the installed copy. If this variable is set to true then CMake will relink the binary before installation instead of using its builtin editor. +For more information on RPATH handling see +the :prop_tgt:`INSTALL_RPATH` and :prop_tgt:`BUILD_RPATH` target properties. + .. versionadded:: 3.20 This variable also applies to XCOFF binaries' LIBPATH. Prior to the diff --git a/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst b/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst index 8da6100300..dd3e2a0485 100644 --- a/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst +++ b/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst @@ -6,5 +6,13 @@ Do not include RPATHs in the build tree. Normally CMake uses the build tree for the RPATH when building executables etc on systems that use RPATH. When the software is installed the executables etc are relinked by CMake to have the -install RPATH. If this variable is set to true then the software is +install RPATH. If this variable is set to ``TRUE`` then the software is always built with no RPATH. + +This is used to initialize the :prop_tgt:`SKIP_BUILD_RPATH` target property +for all targets. For more information on RPATH handling see +the :prop_tgt:`INSTALL_RPATH` and :prop_tgt:`BUILD_RPATH` target properties. + +See also the :variable:`CMAKE_SKIP_INSTALL_RPATH` variable. +To omit RPATH in both the build and install steps, use +:variable:`CMAKE_SKIP_RPATH` instead. diff --git a/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst b/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst index cc0ac21ee3..465fdae58c 100644 --- a/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst +++ b/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst @@ -10,5 +10,10 @@ install RPATH. If this variable is set to true then the software is always installed without RPATH, even if RPATH is enabled when building. This can be useful for example to allow running tests from the build directory with RPATH enabled before the installation step. + +See also the :variable:`CMAKE_SKIP_BUILD_RPATH` variable. To omit RPATH in both the build and install steps, use :variable:`CMAKE_SKIP_RPATH` instead. + +For more information on RPATH handling see the :prop_tgt:`INSTALL_RPATH` +and :prop_tgt:`BUILD_RPATH` target properties. diff --git a/Help/variable/CMAKE_SKIP_RPATH.rst b/Help/variable/CMAKE_SKIP_RPATH.rst index d7ce8e43d7..43f6401cc3 100644 --- a/Help/variable/CMAKE_SKIP_RPATH.rst +++ b/Help/variable/CMAKE_SKIP_RPATH.rst @@ -7,4 +7,8 @@ If this is set to ``TRUE``, then the rpath information is not added to compiled executables. The default is to add rpath information if the platform supports it. This allows for easy running from the build tree. To omit RPATH in the install step, but not the build step, use -:variable:`CMAKE_SKIP_INSTALL_RPATH` instead. +:variable:`CMAKE_SKIP_INSTALL_RPATH` instead. To omit RPATH in the build step, +use :variable:`CMAKE_SKIP_BUILD_RPATH`. + +For more information on RPATH handling see the :prop_tgt:`INSTALL_RPATH` +and :prop_tgt:`BUILD_RPATH` target properties.