mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-06 13:51:33 -06:00
Code Issues Packages Projects Releases Wiki Activity

Apple: Handle generation and comsuption of text-based stubs (.tbd files)

Browse Source 
Fixes: #24123
This commit is contained in:
Marc Chevrier
2023-02-01 17:58:30 +01:00
parent fcbd723a50
commit ede33f30cf
84 changed files with 2054 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
Help/command/install.rst
View File

@@ -158,6 +158,9 @@ that may be installed:
``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``);
* On AIX, the *linker import file* created for executables with
:prop_tgt:`ENABLE_EXPORTS` enabled.
* On macOS, the *linker import file* created for shared libraries with
:prop_tgt:`ENABLE_EXPORTS` enabled (except when marked as ``FRAMEWORK``,
see below).
``LIBRARY``
Target artifacts of this kind include:
@@ -308,6 +311,11 @@ the following additional arguments:
value of ``COMPONENT``. It is an error to use this parameter outside of a
``LIBRARY`` block.
.. versionchanged:: 3.27
This parameter is also usable for an ``ARCHIVE`` block to manage
the linker import file created, on macOS, for shared libraries with
:prop_tgt:`ENABLE_EXPORTS` enabled.
Consider the following example:
.. code-block:: cmake
@@ -342,6 +350,11 @@ the following additional arguments:
option installs nothing. It is an error to use this parameter outside of a
``LIBRARY`` block.
.. versionchanged:: 3.27
This parameter is also usable for an ``ARCHIVE`` block to manage
the linker import file created, on macOS, for shared libraries with
:prop_tgt:`ENABLE_EXPORTS` enabled.
When ``NAMELINK_ONLY`` is given, either ``NAMELINK_COMPONENT`` or
``COMPONENT`` may be used to specify the installation component of the
namelink, but ``COMPONENT`` should generally be preferred.
@@ -355,6 +368,11 @@ the following additional arguments:
installs the library. It is an error to use this parameter outside of a
``LIBRARY`` block.
.. versionchanged:: 3.27
This parameter is also usable for an ``ARCHIVE`` block to manage
the linker import file created, on macOS, for shared libraries with
:prop_tgt:`ENABLE_EXPORTS` enabled.
If ``NAMELINK_SKIP`` is specified, ``NAMELINK_COMPONENT`` has no effect. It
is not recommended to use ``NAMELINK_SKIP`` in conjunction with
``NAMELINK_COMPONENT``.

4
Help/manual/cmake-buildsystem.7.rst
View File

@@ -797,6 +797,10 @@ An *archive* output artifact of a buildsystem target may be:
created by the :command:`add_executable` command when its
:prop_tgt:`ENABLE_EXPORTS` target property is set.
* On macOS: the linker import file (e.g. ``.tbd``) of a shared library target
created by the :command:`add_library` command with the ``SHARED`` option and
when its :prop_tgt:`ENABLE_EXPORTS` target property is set.
The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`
target properties may be used to control archive output artifact locations
and names in the build tree.

251
Help/manual/cmake-generator-expressions.7.rst
View File

@@ -1503,6 +1503,76 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on (see policy :policy:`CMP0112`).
.. genex:: $<TARGET_IMPORT_FILE:tgt>
.. versionadded:: 3.27
Full path to the linker import file. On DLL platforms, it would be the
``.lib`` file. On AIX, for the executables, and on macOS, for the shared
libraries, it could be, respectively, the ``.imp`` or ``.tbd`` import file,
depending of the value of :prop_tgt:`ENABLE_EXPORTS` property.
An empty string is returned when there is no import file associated with the
target.
.. genex:: $<TARGET_IMPORT_FILE_BASE_NAME:tgt>
.. versionadded:: 3.27
Base name of file linker import file of the target ``tgt`` without prefix and
suffix. For example, if target file name is ``libbase.tbd``, the base name is
``base``.
See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`
target properties and their configuration specific variants
:prop_tgt:`OUTPUT_NAME_<CONFIG>` and :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`.
The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target
properties can also be considered.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_IMPORT_FILE_PREFIX:tgt>
.. versionadded:: 3.27
Prefix of the import file of the target ``tgt``.
See also the :prop_tgt:`IMPORT_PREFIX` target property.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_IMPORT_FILE_SUFFIX:tgt>
.. versionadded:: 3.27
Suffix of the import file of the target ``tgt``.
The suffix corresponds to the file extension (such as ".lib" or ".tbd").
See also the :prop_tgt:`IMPORT_SUFFIX` target property.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_IMPORT_FILE_NAME:tgt>
.. versionadded:: 3.27
Name of the import file of the target target ``tgt``.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_IMPORT_FILE_DIR:tgt>
Directory of the import file of the target ``tgt``.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_LINKER_FILE:tgt>
File used when linking to the ``tgt`` target. This will usually
@@ -1510,13 +1580,22 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
but for a shared library on DLL platforms, it would be the ``.lib``
import library associated with the DLL.
.. versionadded:: 3.27
On macOS, it could be the ``.tbd`` import file associated with the shared
library, depending of the value of :prop_tgt:`ENABLE_EXPORTS` property.
This generator expression is equivalent to
:genex:`$<TARGET_LINKER_LIBRARY_FILE>` or
:genex:`$<TARGET_LINKER_IMPORT_FILE>` generator expressions, depending of the
characteristics of the target and the platform.
.. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt>
.. versionadded:: 3.15
Base name of file used to link the target ``tgt``, i.e.
``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example,
if target file name is ``libbase.a``, the base name is ``base``.
:genex:`$<TARGET_LINKER_FILE_NAME:tgt>` without prefix and suffix. For
example, if target file name is ``libbase.a``, the base name is ``base``.
See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`,
and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration
@@ -1570,9 +1649,151 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on (see policy :policy:`CMP0112`).
.. genex:: $<TARGET_LINKER_LIBRARY_FILE:tgt>
.. versionadded:: 3.27
File used when linking o the ``tgt`` target is done using directly the
library, and not an import file. This will usually be the library that
``tgt`` represents (``.a``, ``.so``, ``.dylib``). So, on DLL platforms, it
will be an empty string.
.. genex:: $<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt>
.. versionadded:: 3.27
Base name of library file used to link the target ``tgt``, i.e.
:genex:`$<TARGET_LINKER_LIBRARY_FILE_NAME:tgt>` without prefix and suffix.
For example, if target file name is ``libbase.a``, the base name is ``base``.
See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`,
and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration
specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`,
:prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and
:prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`.
The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target
properties can also be considered.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_LINKER_LIBRARY_FILE_PREFIX:tgt>
.. versionadded:: 3.27
Prefix of the library file used to link target ``tgt``.
See also the :prop_tgt:`PREFIX` target property.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_LINKER_LIBRARY_FILE_SUFFIX:tgt>
.. versionadded:: 3.27
Suffix of the library file used to link target ``tgt``.
The suffix corresponds to the file extension (such as ".a" or ".dylib").
See also the :prop_tgt:`SUFFIX` target property.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_LINKER_LIBRARY_FILE_NAME:tgt>
.. versionadded:: 3.27
Name of the library file used to link target ``tgt``.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_LINKER_LIBRARY_FILE_DIR:tgt>
.. versionadded:: 3.27
Directory of the library file used to link target ``tgt``.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_LINKER_IMPORT_FILE:tgt>
.. versionadded:: 3.27
File used when linking to the ``tgt`` target is done using an import
file. This will usually be the import file that ``tgt`` represents
(``.lib``, ``.tbd``). So, when no import file is involved in the link step,
an empty string is returned.
.. genex:: $<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt>
.. versionadded:: 3.27
Base name of the import file used to link the target ``tgt``, i.e.
:genex:`$<TARGET_LINKER_IMPORT_FILE_NAME:tgt>` without prefix and suffix.
For example, if target file name is ``libbase.tbd``, the base name is ``base``.
See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`,
target properties and their configuration
specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>` and
:prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`.
The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target
properties can also be considered.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_LINKER_IMPORT_FILE_PREFIX:tgt>
.. versionadded:: 3.27
Prefix of the import file used to link target ``tgt``.
See also the :prop_tgt:`IMPORT_PREFIX` target property.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_LINKER_IMPORT_FILE_SUFFIX:tgt>
.. versionadded:: 3.27
Suffix of the import file used to link target ``tgt``.
The suffix corresponds to the file extension (such as ".lib" or ".tbd").
See also the :prop_tgt:`IMPORT_SUFFIX` target property.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_LINKER_IMPORT_FILE_NAME:tgt>
.. versionadded:: 3.27
Name of the import file used to link target ``tgt``.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_LINKER_IMPORT_FILE_DIR:tgt>
.. versionadded:: 3.27
Directory of the import file used to link target ``tgt``.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_SONAME_FILE:tgt>
File with soname (``.so.3``) where ``tgt`` is the name of a target.
.. genex:: $<TARGET_SONAME_FILE_NAME:tgt>
Name of file with soname (``.so.3``).
@@ -1582,11 +1803,35 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
.. genex:: $<TARGET_SONAME_FILE_DIR:tgt>
Directory of with soname (``.so.3``).
Directory of file with soname (``.so.3``).
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on (see policy :policy:`CMP0112`).
.. genex:: $<TARGET_SONAME_IMPORT_FILE:tgt>
.. versionadded:: 3.27
Import file with soname (``.3.tbd``) where ``tgt`` is the name of a target.
.. genex:: $<TARGET_SONAME_IMPORT_FILE_NAME:tgt>
.. versionadded:: 3.27
Name of the import file with soname (``.3.tbd``).
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_SONAME_IMPORT_FILE_DIR:tgt>
.. versionadded:: 3.27
Directory of the import file with soname (``.3.tbd``).
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_PDB_FILE:tgt>
.. versionadded:: 3.1

2
Help/manual/cmake-variables.7.rst
View File

@@ -428,6 +428,7 @@ Variables that Control the Build
/variable/CMAKE_DEPENDS_USE_COMPILER
/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS
/variable/CMAKE_ENABLE_EXPORTS
/variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS
/variable/CMAKE_EXE_LINKER_FLAGS
/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG
/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT
@@ -507,6 +508,7 @@ Variables that Control the Build
/variable/CMAKE_POSITION_INDEPENDENT_CODE
/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY
/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS
/variable/CMAKE_SHARED_LINKER_FLAGS
/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG
/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT

3
Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst
View File

@@ -6,4 +6,7 @@ ARCHIVE_OUTPUT_DIRECTORY
.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: :variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY`
.. include:: XXX_OUTPUT_DIRECTORY.txt
.. |IDEM| replace:: in the same directory
.. include:: MACOS_IMPORT_FILES.txt
See also the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` target property.

3
Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst
View File

@@ -5,4 +5,7 @@ ARCHIVE_OUTPUT_NAME
.. |xxx| replace:: archive
.. include:: XXX_OUTPUT_NAME.txt
.. |IDEM| replace:: with the same name
.. include:: MACOS_IMPORT_FILES.txt
See also the :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` target property.

29
Help/prop_tgt/ENABLE_EXPORTS.rst
View File

@@ -1,7 +1,7 @@
ENABLE_EXPORTS
--------------
Specify whether an executable exports symbols for loadable modules.
Specify whether an executable or a shared library exports symbols.
Normally an executable does not export any symbols because it is the
final program. It is possible for an executable to export symbols to
@@ -28,4 +28,29 @@ varies by platform:
automatically bind symbols when the module is loaded.
This property is initialized by the value of the variable
:variable:`CMAKE_ENABLE_EXPORTS` if it is set when a target is created.
:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` if it is set when an executable
target is created.
.. 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 <XCODE_ATTRIBUTE_<an-attribute>>`
target property or the
:variable:`CMAKE_XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS <CMAKE_XCODE_ATTRIBUTE_<an-attribute>>`
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.

14
Help/prop_tgt/IMPORTED_IMPLIB.rst
View File

@@ -3,7 +3,13 @@ IMPORTED_IMPLIB
Full path to the import library for an ``IMPORTED`` target.
Set this to the location of the ``.lib`` part of a Windows DLL, or on
AIX set it to an import file created for executables that export symbols
(see the :prop_tgt:`ENABLE_EXPORTS` target property).
Ignored for non-imported targets.
This property may be set:
* On DLL platforms, to the location of the ``.lib`` part of the DLL.
* On AIX, to an import file (e.g. ``.imp``) created for executables that export
symbols (see the :prop_tgt:`ENABLE_EXPORTS` target property).
* On macOS, to an import file (e.g. ``.tbd``) created for shared libraries (see
the :prop_tgt:`ENABLE_EXPORTS` target property). For frameworks this is the
location of the ``.tbd`` file symlink just inside the framework folder.
This property is ignored for non-imported targets.

2
Help/prop_tgt/IMPORTED_LOCATION.rst
View File

@@ -27,5 +27,5 @@ selected and its :prop_tgt:`IMPORTED_LOCATION_<CONFIG>` value used.
To get the location of an imported target read one of the :prop_tgt:`LOCATION`
or ``LOCATION_<CONFIG>`` properties.
For platforms with import libraries (e.g. Windows) see also
For platforms with import libraries (e.g. Windows, AIX or macOS) see also
:prop_tgt:`IMPORTED_IMPLIB`.

12
Help/prop_tgt/MACOS_IMPORT_FILES.txt Normal file
View File

@@ -0,0 +1,12 @@
.. note::
On macOS, this property will be ignored for the linker import files (e.g.
``.tbd`` files, see :prop_tgt:`ENABLE_EXPORTS` property for details) when:
* The :prop_tgt:`FRAMEWORK` is set, because the framework layout cannot be
changed.
* The :generator:`Xcode` generator is used, due to the limitations and
constraints of the ``Xcode`` tool.
In both cases, the linker import files will be generated |IDEM| as the shared
library.

6
Help/release/dev/Apple-tbd-files-management.rst Normal file
View File

@@ -0,0 +1,6 @@
Apple-tbd-files-management
--------------------------
* Support for text-based stubs (i.e. ``.tbd`` files) was added on macOS
platform. This capability is managed through the :prop_tgt:`ENABLE_EXPORTS`
property.

4
Help/variable/CMAKE_ENABLE_EXPORTS.rst
View File

@@ -8,3 +8,7 @@ Specify whether executables export symbols for loadable modules.
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.

12
Help/variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS.rst Normal file
View File

@@ -0,0 +1,12 @@
CMAKE_EXECUTABLE_ENABLE_EXPORTS
-------------------------------
.. versionadded:: 3.27
Specify whether executables export symbols for loadable modules.
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 variable supersede the :variable:`CMAKE_ENABLE_EXPORTS` variable.

10
Help/variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS.rst Normal file
View File

@@ -0,0 +1,10 @@
CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS
-----------------------------------
.. versionadded:: 3.27
Specify whether shared library generates an import file.
This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target
property for shared library targets when they are created by calls to the
:command:`add_library` command. See the property documentation for details.