Help/command/export.rst

   1 export
   2 ------
   3
   4 Export targets or packages for outside projects to use them directly
   5 from the current project's build tree, without installation.
   6
   7 See the :command:`install(EXPORT)` command to export targets from an
   8 install tree.
   9
  10 Synopsis
  11 ^^^^^^^^
  12
  13 .. parsed-literal::
  14
  15   export(`TARGETS`_ <target>... [...])
  16   export(`EXPORT`_ <export-name> [...])
  17   export(`PACKAGE`_ <PackageName>)
  18
  19 Exporting Targets
  20 ^^^^^^^^^^^^^^^^^
  21
  22 .. _`export(TARGETS)`:
  23 .. _TARGETS:
  24
  25 .. code-block:: cmake
  26
  27   export(TARGETS <target>... [NAMESPACE <namespace>]
  28          [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]
  29          [CXX_MODULES_DIRECTORY <directory>])
  30
  31 Creates a file ``<filename>`` that may be included by outside projects to
  32 import targets named by ``<target>...`` from the current project's build tree.
  33 This is useful during cross-compiling to build utility executables that can
  34 run on the host platform in one project and then import them into another
  35 project being compiled for the target platform.
  36
  37 The file created by this command is specific to the build tree and
  38 should never be installed.  See the :command:`install(EXPORT)` command to
  39 export targets from an install tree.
  40
  41 The options are:
  42
  43 ``NAMESPACE <namespace>``
  44   Prepend the ``<namespace>`` string to all target names written to the file.
  45
  46 ``APPEND``
  47   Append to the file instead of overwriting it.  This can be used to
  48   incrementally export multiple targets to the same file.
  49
  50 ``EXPORT_LINK_INTERFACE_LIBRARIES``
  51   Include the contents of the properties named with the pattern
  52   ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``
  53   in the export, even when policy :policy:`CMP0022` is NEW.  This is useful
  54   to support consumers using CMake versions older than 2.8.12.
  55
  56 ``CXX_MODULES_DIRECTORY <directory>``
  57
  58   .. note ::
  59
  60     Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
  61
  62   Export C++ module properties to files under the given directory. Each file
  63   will be named according to the target's export name (without any namespace).
  64   These files will automatically be included from the export file.
  65
  66 This signature requires all targets to be listed explicitly.  If a library
  67 target is included in the export, but a target to which it links is not
  68 included, the behavior is unspecified.  See the `export(EXPORT)`_ signature
  69 to automatically export the same targets from the build tree as
  70 :command:`install(EXPORT)` would from an install tree.
  71
  72 .. note::
  73
  74   :ref:`Object Libraries` under :generator:`Xcode` have special handling if
  75   multiple architectures are listed in :variable:`CMAKE_OSX_ARCHITECTURES`.
  76   In this case they will be exported as :ref:`Interface Libraries` with
  77   no object files available to clients.  This is sufficient to satisfy
  78   transitive usage requirements of other targets that link to the
  79   object libraries in their implementation.
  80
  81 Exporting Targets to Android.mk
  82 """""""""""""""""""""""""""""""
  83
  84 .. code-block:: cmake
  85
  86   export(TARGETS <target>... ANDROID_MK <filename>)
  87
  88 .. versionadded:: 3.7
  89
  90 This signature exports cmake built targets to the android ndk build system
  91 by creating an ``Android.mk`` file that references the prebuilt targets. The
  92 Android NDK supports the use of prebuilt libraries, both static and shared.
  93 This allows cmake to build the libraries of a project and make them available
  94 to an ndk build system complete with transitive dependencies, include flags
  95 and defines required to use the libraries. The signature takes a list of
  96 targets and puts them in the ``Android.mk`` file specified by the
  97 ``<filename>`` given. This signature can only be used if policy
  98 :policy:`CMP0022` is NEW for all targets given. A error will be issued if
  99 that policy is set to OLD for one of the targets.
 100
 101 Exporting Targets matching install(EXPORT)
 102 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 103
 104 .. _`export(EXPORT)`:
 105 .. _EXPORT:
 106
 107 .. code-block:: cmake
 108
 109   export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]
 110          [CXX_MODULES_DIRECTORY <directory>])
 111
 112 Creates a file ``<filename>`` that may be included by outside projects to
 113 import targets from the current project's build tree.  This is the same
 114 as the `export(TARGETS)`_ signature, except that the targets are not
 115 explicitly listed.  Instead, it exports the targets associated with
 116 the installation export ``<export-name>``.  Target installations may be
 117 associated with the export ``<export-name>`` using the ``EXPORT`` option
 118 of the :command:`install(TARGETS)` command.
 119
 120 Exporting Packages
 121 ^^^^^^^^^^^^^^^^^^
 122
 123 .. _`export(PACKAGE)`:
 124 .. _PACKAGE:
 125
 126 .. code-block:: cmake
 127
 128   export(PACKAGE <PackageName>)
 129
 130 Store the current build directory in the CMake user package registry
 131 for package ``<PackageName>``.  The :command:`find_package` command may consider the
 132 directory while searching for package ``<PackageName>``.  This helps dependent
 133 projects find and use a package from the current project's build tree
 134 without help from the user.  Note that the entry in the package
 135 registry that this command creates works only in conjunction with a
 136 package configuration file (``<PackageName>Config.cmake``) that works with the
 137 build tree. In some cases, for example for packaging and for system
 138 wide installations, it is not desirable to write the user package
 139 registry.
 140
 141 .. versionchanged:: 3.1
 142   If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable
 143   is enabled, the ``export(PACKAGE)`` command will do nothing.
 144
 145 .. versionchanged:: 3.15
 146   By default the ``export(PACKAGE)`` command does nothing (see policy
 147   :policy:`CMP0090`) because populating the user package registry has effects
 148   outside the source and build trees.  Set the
 149   :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories
 150   to the CMake user package registry.