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