diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 3 | ||||
| -rw-r--r-- | Help/prop_tgt/BUILD_RPATH.rst | 29 | ||||
| -rw-r--r-- | Help/prop_tgt/INSTALL_NAME_DIR.rst | 9 | ||||
| -rw-r--r-- | Help/prop_tgt/INSTALL_RPATH.rst | 26 | ||||
| -rw-r--r-- | Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst | 2 | ||||
| -rw-r--r-- | Help/prop_tgt/SKIP_BUILD_RPATH.rst | 3 | ||||
| -rw-r--r-- | Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst | 3 | ||||
| -rw-r--r-- | Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst | 3 | ||||
| -rw-r--r-- | Help/variable/CMAKE_SKIP_BUILD_RPATH.rst | 10 | ||||
| -rw-r--r-- | Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst | 5 | ||||
| -rw-r--r-- | Help/variable/CMAKE_SKIP_RPATH.rst | 6 |
11 files changed, 86 insertions, 13 deletions
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index a72eac1..8bb9dde 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 1f917a5..902e2f7 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 <CMake Language Lists>` 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 <CMake Language Lists>` 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 <cmake-generator-expressions(7)>`. + +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 47a0037..84310b9 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 <cmake-generator-expressions(7)>`. In particular, the :genex:`$<INSTALL_PREFIX>` 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 4549b92..e5110b8 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 <cmake-generator-expressions(7)>`. + +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 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 diff --git a/Help/prop_tgt/SKIP_BUILD_RPATH.rst b/Help/prop_tgt/SKIP_BUILD_RPATH.rst index 7086b1b..1fe170c 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 5b59a6e..839771a 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 b9b045e..483ec5f 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 8da6100..dd3e2a0 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 cc0ac21..465fdae 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 d7ce8e4..43f6401 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. |