From 099292f123717b33c8f64350e68dedb571b55499 Mon Sep 17 00:00:00 2001 From: Alexander Neundorf Date: Tue, 10 Jan 2023 22:54:42 +0100 Subject: Help: improve docs for rpath-related variables Now all RPATH-related variables link to the related RPATH-related variables. Some also link to the INSTALL_RPATH and BUILD_RPATH target properties. --- Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst | 3 +++ Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst | 3 +++ Help/variable/CMAKE_SKIP_BUILD_RPATH.rst | 10 +++++++++- Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst | 5 +++++ Help/variable/CMAKE_SKIP_RPATH.rst | 6 +++++- 5 files changed, 25 insertions(+), 2 deletions(-) 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. -- cgit v0.12 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 From 66ad61ba797f7062224788b3ab578b5ed87370d5 Mon Sep 17 00:00:00 2001 From: Alexander Neundorf Date: Wed, 11 Jan 2023 23:42:41 +0100 Subject: Help: improve documentation for BUILD_RPATH Now all properties related to BUILD_RPATH are linked from the documentation for BUILD_RPATH. SKIP_BUILD_RPATH now also refers to BUILD_RPATH. --- Help/prop_tgt/BUILD_RPATH.rst | 26 ++++++++++++++++++++++---- Help/prop_tgt/SKIP_BUILD_RPATH.rst | 3 ++- 2 files changed, 24 insertions(+), 5 deletions(-) diff --git a/Help/prop_tgt/BUILD_RPATH.rst b/Help/prop_tgt/BUILD_RPATH.rst index 1f917a5..e546dcc 100644 --- a/Help/prop_tgt/BUILD_RPATH.rst +++ b/Help/prop_tgt/BUILD_RPATH.rst @@ -3,13 +3,31 @@ 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 :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/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. -- cgit v0.12 From f784c21567772012caa5cec77be055b496e1232c Mon Sep 17 00:00:00 2001 From: Alexander Neundorf Date: Wed, 11 Jan 2023 23:46:16 +0100 Subject: Help: mention CMAKE_SKIP_RPATH in the RPATH docs CMAKE_SKIP_RPATH is now mentioned in the docs for the BUILD_RPATH and INSTALL_RPATH target properties. --- Help/prop_tgt/BUILD_RPATH.rst | 3 +++ Help/prop_tgt/INSTALL_RPATH.rst | 2 ++ 2 files changed, 5 insertions(+) diff --git a/Help/prop_tgt/BUILD_RPATH.rst b/Help/prop_tgt/BUILD_RPATH.rst index e546dcc..902e2f7 100644 --- a/Help/prop_tgt/BUILD_RPATH.rst +++ b/Help/prop_tgt/BUILD_RPATH.rst @@ -23,6 +23,9 @@ This property supports 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. diff --git a/Help/prop_tgt/INSTALL_RPATH.rst b/Help/prop_tgt/INSTALL_RPATH.rst index 07d7ae6..dd6bf89 100644 --- a/Help/prop_tgt/INSTALL_RPATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH.rst @@ -22,6 +22,8 @@ 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 -- cgit v0.12 From 434be1256e8bb7915d0abaf87688548151f2b5b8 Mon Sep 17 00:00:00 2001 From: Alexander Neundorf Date: Thu, 12 Jan 2023 23:55:58 +0100 Subject: Help: improve docs for INSTALL_NAME_DIR INSTALL_NAME_DIR now mentions BUILD_WITH_INSTALL_NAME_DIR. The INSTALL_NAME_DIR, INSTALL_RPATH and $ documentation now mention the other two platforms respectively, to make it easier for developers who are not familiar with all three platforms, --- Help/manual/cmake-generator-expressions.7.rst | 3 +++ Help/prop_tgt/INSTALL_NAME_DIR.rst | 9 +++++++-- Help/prop_tgt/INSTALL_RPATH.rst | 3 +++ 3 files changed, 13 insertions(+), 2 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/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 `. 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 dd6bf89..e5110b8 100644 --- a/Help/prop_tgt/INSTALL_RPATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH.rst @@ -31,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. -- cgit v0.12