mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-11 08:20:18 -06:00
Help: Organize and clarify export() command documentation
Add section headers for each signature, and a synopsis linking to them. Re-order sections to introduce the main `export(TARGETS)` functionality before mentioning the `export(EXPORT)` shorthand, which may be confused with `install(EXPORT)`. Fixes: #23221
This commit is contained in:
Brad King
@@ -1,44 +1,62 @@
|
||||
export
|
||||
------
|
||||
|
||||
Export targets from the build tree for use by outside projects.
|
||||
Export targets or packages for outside projects to use them directly
|
||||
from the current project's build tree, without installation.
|
||||
|
||||
See the :command:`install(EXPORT)` command to export targets from an
|
||||
install tree.
|
||||
|
||||
Synopsis
|
||||
^^^^^^^^
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
export(`TARGETS`_ <target>... [...])
|
||||
export(`EXPORT`_ <export-name> [...])
|
||||
export(`PACKAGE`_ <PackageName>)
|
||||
|
||||
Exporting Targets
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. _`export(TARGETS)`:
|
||||
.. _TARGETS:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
|
||||
export(TARGETS <target>... [NAMESPACE <namespace>]
|
||||
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
|
||||
|
||||
Creates a file ``<filename>`` that may be included by outside projects to
|
||||
import targets from the current project's build tree. This is useful
|
||||
during cross-compiling to build utility executables that can run on
|
||||
the host platform in one project and then import them into another
|
||||
project being compiled for the target platform. If the ``NAMESPACE``
|
||||
option is given the ``<namespace>`` string will be prepended to all target
|
||||
names written to the file.
|
||||
|
||||
Target installations are associated with the export ``<export-name>``
|
||||
using the ``EXPORT`` option of the :command:`install(TARGETS)` command.
|
||||
import targets named by ``<target>...`` from the current project's build tree.
|
||||
This is useful during cross-compiling to build utility executables that can
|
||||
run on the host platform in one project and then import them into another
|
||||
project being compiled for the target platform.
|
||||
|
||||
The file created by this command is specific to the build tree and
|
||||
should never be installed. See the :command:`install(EXPORT)` command to
|
||||
export targets from an installation tree.
|
||||
export targets from an install tree.
|
||||
|
||||
The properties set on the generated IMPORTED targets will have the
|
||||
same values as the final values of the input TARGETS.
|
||||
The options are:
|
||||
|
||||
.. code-block:: cmake
|
||||
``NAMESPACE <namespace>``
|
||||
Prepend the ``<namespace>`` string to all target names written to the file.
|
||||
|
||||
export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
|
||||
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
|
||||
``APPEND``
|
||||
Append to the file instead of overwriting it. This can be used to
|
||||
incrementally export multiple targets to the same file.
|
||||
|
||||
This signature is similar to the ``EXPORT`` signature, but targets are listed
|
||||
explicitly rather than specified as an export-name. If the APPEND option is
|
||||
given the generated code will be appended to the file instead of overwriting it.
|
||||
The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the
|
||||
contents of the properties matching
|
||||
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when
|
||||
policy CMP0022 is NEW. If a library target is included in the export
|
||||
but a target to which it links is not included the behavior is
|
||||
unspecified.
|
||||
``EXPORT_LINK_INTERFACE_LIBRARIES``
|
||||
Include the contents of the properties named with the pattern
|
||||
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``
|
||||
in the export, even when policy :policy:`CMP0022` is NEW. This is useful
|
||||
to support consumers using CMake versions older than 2.8.12.
|
||||
|
||||
This signature requires all targets to be listed explicitly. If a library
|
||||
target is included in the export, but a target to which it links is not
|
||||
included, the behavior is unspecified. See the `export(EXPORT)`_ signature
|
||||
to automatically export the same targets from the build tree as
|
||||
:command:`install(EXPORT)` would from an install tree.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -49,6 +67,50 @@ unspecified.
|
||||
transitive usage requirements of other targets that link to the
|
||||
object libraries in their implementation.
|
||||
|
||||
Exporting Targets to Android.mk
|
||||
"""""""""""""""""""""""""""""""
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
export(TARGETS <target>... ANDROID_MK <filename>)
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
This signature exports cmake built targets to the android ndk build system
|
||||
by creating an ``Android.mk`` file that references the prebuilt targets. The
|
||||
Android NDK supports the use of prebuilt libraries, both static and shared.
|
||||
This allows cmake to build the libraries of a project and make them available
|
||||
to an ndk build system complete with transitive dependencies, include flags
|
||||
and defines required to use the libraries. The signature takes a list of
|
||||
targets and puts them in the ``Android.mk`` file specified by the
|
||||
``<filename>`` given. This signature can only be used if policy
|
||||
:policy:`CMP0022` is NEW for all targets given. A error will be issued if
|
||||
that policy is set to OLD for one of the targets.
|
||||
|
||||
Exporting Targets matching install(EXPORT)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. _`export(EXPORT)`:
|
||||
.. _EXPORT:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
|
||||
|
||||
Creates a file ``<filename>`` that may be included by outside projects to
|
||||
import targets from the current project's build tree. This is the same
|
||||
as the `export(TARGETS)`_ signature, except that the targets are not
|
||||
explicitly listed. Instead, it exports the targets associated with
|
||||
the installation export ``<export-name>``. Target installations may be
|
||||
associated with the export ``<export-name>`` using the ``EXPORT`` option
|
||||
of the :command:`install(TARGETS)` command.
|
||||
|
||||
Exporting Packages
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. _`export(PACKAGE)`:
|
||||
.. _PACKAGE:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
export(PACKAGE <PackageName>)
|
||||
@@ -74,20 +136,3 @@ registry.
|
||||
outside the source and build trees. Set the
|
||||
:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories
|
||||
to the CMake user package registry.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
This signature exports cmake built targets to the android ndk build system
|
||||
by creating an Android.mk file that references the prebuilt targets. The
|
||||
Android NDK supports the use of prebuilt libraries, both static and shared.
|
||||
This allows cmake to build the libraries of a project and make them available
|
||||
to an ndk build system complete with transitive dependencies, include flags
|
||||
and defines required to use the libraries. The signature takes a list of
|
||||
targets and puts them in the Android.mk file specified by the ``<filename>``
|
||||
given. This signature can only be used if policy CMP0022 is NEW for all
|
||||
targets given. A error will be issued if that policy is set to OLD for one
|
||||
of the targets.
|
||||
|
||||
Reference in New Issue
Block a user