From 1285fe27ff545cfbbe37f8be8d67bae1692847a5 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sun, 6 Aug 2023 18:22:51 +1000 Subject: Help: Improve formatting and fix wording for ENABLE_EXPORTS --- Help/prop_tgt/ENABLE_EXPORTS.rst | 53 ++++++++++++++++++---------------- Help/variable/CMAKE_ENABLE_EXPORTS.rst | 7 +++-- 2 files changed, 32 insertions(+), 28 deletions(-) diff --git a/Help/prop_tgt/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst index 3e9b285..e34c649 100644 --- a/Help/prop_tgt/ENABLE_EXPORTS.rst +++ b/Help/prop_tgt/ENABLE_EXPORTS.rst @@ -27,30 +27,33 @@ varies by platform: referencing the executable since the dynamic loader will automatically bind symbols when the module is loaded. -This property is initialized by the value of the variable -:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` if it is set when an executable -target is created. +This property is initialized by the value of the +:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` variable, if it is set when an +executable target is created. If :variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` +is not set, the :variable:`CMAKE_ENABLE_EXPORTS` variable is used to initialize +the property instead for backward compatibility reasons. +See below for alternative initialization behavior for shared library targets. .. versionadded:: 3.27 - On macOS, to link with a shared library (standard one as well as framework), - a linker import file (e.g. a text-based stubs file, with ``.tbd`` extension) - can be used instead of the shared library itself. - -The generation of these linker import files, as well as the consumption, is -controlled by this property. When this property is set to true, CMake will -generate a ``.tbd`` file for each shared library created by -:command:`add_library` command. This allow other targets to use this ``.tbd`` -file to link to the library with the :command:`target_link_libraries` -command. - -.. note:: - - For compatibility purpose, this property will be ignored if - :prop_tgt:`XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS >` - target property or the - :variable:`CMAKE_XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS >` - variable is set to ``NO``. - -This property is initialized by the value of the variable -:variable:`CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS` if it is set when a shared -library target is created. + On Apple platforms, to link with a shared library (either a bare library or a + framework), a linker import file can be used instead of the actual shared + library. These linker import files are also known as text-based stubs, and + they have a ``.tbd`` file extension. + + The generation of these linker import files, as well as their consumption, is + controlled by this property. When this property is set to true on a shared + library target, CMake will generate a ``.tbd`` file for the library. + Other targets that link to the shared library target will then use this + ``.tbd`` file when linking rather than linking to the shared library binary. + + .. note:: + + For backward compatibility reasons, this property will be ignored if the + :prop_tgt:`XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS >` + target property or the + :variable:`CMAKE_XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS >` + variable is set to false. + + For shared library targets, this property is initialized by the value of the + :variable:`CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS` variable, if it is set when + the target is created. diff --git a/Help/variable/CMAKE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_ENABLE_EXPORTS.rst index d2c5ed0..da23342 100644 --- a/Help/variable/CMAKE_ENABLE_EXPORTS.rst +++ b/Help/variable/CMAKE_ENABLE_EXPORTS.rst @@ -9,6 +9,7 @@ This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target property for executable targets when they are created by calls to the :command:`add_executable` command. See the property documentation for details. -This command has been superseded by the -:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` command. It is provided for -compatibility with older CMake code. +This variable has been superseded by the +:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` variable. It is provided for +backward compatibility with older CMake code, but should not be used in new +projects. -- cgit v0.12