| Importing and Exporting Guide | |
| ***************************** | |
| .. only:: html | |
| .. contents:: | |
| Introduction | |
| ============ | |
| In this guide, we will present the concept of :prop_tgt:`IMPORTED` targets | |
| and demonstrate how to import existing executable or library files from disk | |
| into a CMake project. We will then show how CMake supports exporting targets | |
| from one CMake-based project and importing them into another. Finally, we | |
| will demonstrate how to package a project with a configuration file to allow | |
| for easy integration into other CMake projects. This guide and the complete | |
| example source code can be found in the ``Help/guide/importing-exporting`` | |
| directory of the CMake source code tree. | |
| Importing Targets | |
| ================= | |
| :prop_tgt:`IMPORTED` targets are used to convert files outside of a CMake | |
| project into logical targets inside of the project. :prop_tgt:`IMPORTED` | |
| targets are created using the ``IMPORTED`` option of the | |
| :command:`add_executable` and :command:`add_library` commands. No build | |
| files are generated for :prop_tgt:`IMPORTED` targets. Once imported, | |
| :prop_tgt:`IMPORTED` targets may be referenced like any other target within | |
| the project and provide a convenient, flexible reference to outside | |
| executables and libraries. | |
| By default, the :prop_tgt:`IMPORTED` target name has scope in the directory in | |
| which it is created and below. We can use the ``GLOBAL`` option to extended | |
| visibility so that the target is accessible globally in the build system. | |
| Details about the :prop_tgt:`IMPORTED` target are specified by setting | |
| properties whose names begin in ``IMPORTED_`` and ``INTERFACE_``. For example, | |
| :prop_tgt:`IMPORTED_LOCATION` contains the full path to the target on | |
| disk. | |
| Importing Executables | |
| --------------------- | |
| To start, we will walk through a simple example that creates an | |
| :prop_tgt:`IMPORTED` executable target and then references it from the | |
| :command:`add_custom_command` command. | |
| We'll need to do some setup to get started. We want to create an executable | |
| that when run creates a basic ``main.cc`` file in the current directory. The | |
| details of this project are not important. Navigate to | |
| ``Help/guide/importing-exporting/MyExe``, create a build directory, run | |
| :manual:`cmake <cmake(1)>` and build and install the project. | |
| .. code-block:: console | |
| $ cd Help/guide/importing-exporting/MyExe | |
| $ mkdir build | |
| $ cd build | |
| $ cmake .. | |
| $ cmake --build . | |
| $ cmake --install . --prefix <install location> | |
| $ <install location>/myexe | |
| $ ls | |
| [...] main.cc [...] | |
| Now we can import this executable into another CMake project. The source code | |
| for this section is available in ``Help/guide/importing-exporting/Importing``. | |
| In the CMakeLists file, use the :command:`add_executable` command to create a | |
| new target called ``myexe``. Use the ``IMPORTED`` option to tell CMake that | |
| this target references an executable file located outside of the project. No | |
| rules will be generated to build it and the :prop_tgt:`IMPORTED` target | |
| property will be set to ``true``. | |
| .. literalinclude:: Importing/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # Add executable | |
| :end-before: # Set imported location | |
| Next, set the :prop_tgt:`IMPORTED_LOCATION` property of the target using | |
| the :command:`set_property` command. This will tell CMake the location of the | |
| target on disk. The location may need to be adjusted to the | |
| ``<install location>`` specified in the previous step. | |
| .. literalinclude:: Importing/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # Set imported location | |
| :end-before: # Add custom command | |
| We can now reference this :prop_tgt:`IMPORTED` target just like any target | |
| built within the project. In this instance, let's imagine that we want to use | |
| the generated source file in our project. Use the :prop_tgt:`IMPORTED` | |
| target in the :command:`add_custom_command` command: | |
| .. literalinclude:: Importing/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # Add custom command | |
| :end-before: # Use source file | |
| As ``COMMAND`` specifies an executable target name, it will automatically be | |
| replaced by the location of the executable given by the | |
| :prop_tgt:`IMPORTED_LOCATION` property above. | |
| Finally, use the output from :command:`add_custom_command`: | |
| .. literalinclude:: Importing/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # Use source file | |
| Importing Libraries | |
| ------------------- | |
| In a similar manner, libraries from other projects may be accessed through | |
| :prop_tgt:`IMPORTED` targets. | |
| Note: The full source code for the examples in this section is not provided | |
| and is left as an exercise for the reader. | |
| In the CMakeLists file, add an :prop_tgt:`IMPORTED` library and specify its | |
| location on disk: | |
| .. code-block:: cmake | |
| add_library(foo STATIC IMPORTED) | |
| set_property(TARGET foo PROPERTY | |
| IMPORTED_LOCATION "/path/to/libfoo.a") | |
| Then use the :prop_tgt:`IMPORTED` library inside of our project: | |
| .. code-block:: cmake | |
| add_executable(myexe src1.c src2.c) | |
| target_link_libraries(myexe PRIVATE foo) | |
| On Windows, a .dll and its .lib import library may be imported together: | |
| .. code-block:: cmake | |
| add_library(bar SHARED IMPORTED) | |
| set_property(TARGET bar PROPERTY | |
| IMPORTED_LOCATION "c:/path/to/bar.dll") | |
| set_property(TARGET bar PROPERTY | |
| IMPORTED_IMPLIB "c:/path/to/bar.lib") | |
| add_executable(myexe src1.c src2.c) | |
| target_link_libraries(myexe PRIVATE bar) | |
| A library with multiple configurations may be imported with a single target: | |
| .. code-block:: cmake | |
| find_library(math_REL NAMES m) | |
| find_library(math_DBG NAMES md) | |
| add_library(math STATIC IMPORTED GLOBAL) | |
| set_target_properties(math PROPERTIES | |
| IMPORTED_LOCATION "${math_REL}" | |
| IMPORTED_LOCATION_DEBUG "${math_DBG}" | |
| IMPORTED_CONFIGURATIONS "RELEASE;DEBUG" | |
| ) | |
| add_executable(myexe src1.c src2.c) | |
| target_link_libraries(myexe PRIVATE math) | |
| The generated build system will link ``myexe`` to ``m.lib`` when built in the | |
| release configuration, and ``md.lib`` when built in the debug configuration. | |
| Exporting Targets | |
| ================= | |
| While :prop_tgt:`IMPORTED` targets on their own are useful, they still | |
| require that the project that imports them knows the locations of the target | |
| files on disk. The real power of :prop_tgt:`IMPORTED` targets is when the | |
| project providing the target files also provides a CMake file to help import | |
| them. A project can be setup to produce the necessary information so that it | |
| can easily be used by other CMake projects be it from a build directory, a | |
| local install or when packaged. | |
| In the remaining sections, we will walk through a set of example projects | |
| step-by-step. The first project will create and install a library and | |
| corresponding CMake configuration and package files. The second project will | |
| use the generated package. | |
| Let's start by looking at the ``MathFunctions`` project in the | |
| ``Help/guide/importing-exporting/MathFunctions`` directory. Here we have a | |
| header file ``MathFunctions.h`` that declares a ``sqrt`` function: | |
| .. literalinclude:: MathFunctions/MathFunctions.h | |
| :language: c++ | |
| And a corresponding source file ``MathFunctions.cxx``: | |
| .. literalinclude:: MathFunctions/MathFunctions.cxx | |
| :language: c++ | |
| Don't worry too much about the specifics of the C++ files, they are just meant | |
| to be a simple example that will compile and run on many build systems. | |
| Now we can create a ``CMakeLists.txt`` file for the ``MathFunctions`` | |
| project. Start by specifying the :command:`cmake_minimum_required` version and | |
| :command:`project` name: | |
| .. literalinclude:: MathFunctions/CMakeLists.txt | |
| :language: cmake | |
| :end-before: # create library | |
| The :module:`GNUInstallDirs` module is included in order to provide the | |
| project with the flexibility to install into different platform layouts by | |
| making the directories available as cache variables. | |
| Create a library called ``MathFunctions`` with the :command:`add_library` | |
| command: | |
| .. literalinclude:: MathFunctions/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # create library | |
| :end-before: # add include directories | |
| And then use the :command:`target_include_directories` command to specify the | |
| include directories for the target: | |
| .. literalinclude:: MathFunctions/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # add include directories | |
| :end-before: # install the target and create export-set | |
| We need to tell CMake that we want to use different include directories | |
| depending on if we're building the library or using it from an installed | |
| location. If we don't do this, when CMake creates the export information it | |
| will export a path that is specific to the current build directory | |
| and will not be valid for other projects. We can use | |
| :manual:`generator expressions <cmake-generator-expressions(7)>` to specify | |
| that if we're building the library include the current source directory. | |
| Otherwise, when installed, include the ``include`` directory. See the `Creating | |
| Relocatable Packages`_ section for more details. | |
| The :command:`install(TARGETS)` and :command:`install(EXPORT)` commands | |
| work together to install both targets (a library in our case) and a CMake | |
| file designed to make it easy to import the targets into another CMake project. | |
| First, in the :command:`install(TARGETS)` command we will specify the target, | |
| the ``EXPORT`` name and the destinations that tell CMake where to install the | |
| targets. | |
| .. literalinclude:: MathFunctions/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # install the target and create export-set | |
| :end-before: # install header file | |
| Here, the ``EXPORT`` option tells CMake to create an export called | |
| ``MathFunctionsTargets``. The generated :prop_tgt:`IMPORTED` targets have | |
| appropriate properties set to define their | |
| :ref:`usage requirements <Target Usage Requirements>`, such as | |
| :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, | |
| :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and other relevant built-in | |
| ``INTERFACE_`` properties. The ``INTERFACE`` variant of user-defined | |
| properties listed in :prop_tgt:`COMPATIBLE_INTERFACE_STRING` and other | |
| :ref:`Compatible Interface Properties` are also propagated to the | |
| generated :prop_tgt:`IMPORTED` targets. For example, in this case, the | |
| :prop_tgt:`IMPORTED` target will have its | |
| :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property populated with | |
| the directory specified by the ``INCLUDES DESTINATION`` property. As a | |
| relative path was given, it is treated as relative to the | |
| :variable:`CMAKE_INSTALL_PREFIX`. | |
| Note, we have *not* asked CMake to install the export yet. | |
| We don't want to forget to install the ``MathFunctions.h`` header file with the | |
| :command:`install(FILES)` command. The header file should be installed to the | |
| ``include`` directory, as specified by the | |
| :command:`target_include_directories` command above. | |
| .. literalinclude:: MathFunctions/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # install header file | |
| :end-before: # generate and install export file | |
| Now that the ``MathFunctions`` library and header file are installed, we also | |
| need to explicitly install the ``MathFunctionsTargets`` export details. Use | |
| the :command:`install(EXPORT)` command to export the targets in | |
| ``MathFunctionsTargets``, as defined by the :command:`install(TARGETS)` | |
| command. | |
| .. literalinclude:: MathFunctions/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # generate and install export file | |
| :end-before: # include CMakePackageConfigHelpers macro | |
| This command generates the ``MathFunctionsTargets.cmake`` file and arranges | |
| to install it to ``${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions``. The file | |
| contains code suitable for use by downstreams to import all targets listed in | |
| the install command from the installation tree. | |
| The ``NAMESPACE`` option will prepend ``MathFunctions::`` to the target names | |
| as they are written to the export file. This convention of double-colons | |
| gives CMake a hint that the name is an :prop_tgt:`IMPORTED` target when it | |
| is used by downstream projects. This way, CMake can issue a diagnostic | |
| message if the package providing it was not found. | |
| The generated export file contains code that creates an :prop_tgt:`IMPORTED` library. | |
| .. code-block:: cmake | |
| # Create imported target MathFunctions::MathFunctions | |
| add_library(MathFunctions::MathFunctions STATIC IMPORTED) | |
| set_target_properties(MathFunctions::MathFunctions PROPERTIES | |
| INTERFACE_INCLUDE_DIRECTORIES "${_IMPORT_PREFIX}/include" | |
| ) | |
| This code is very similar to the example we created by hand in the | |
| `Importing Libraries`_ section. Note that ``${_IMPORT_PREFIX}`` is computed | |
| relative to the file location. | |
| An outside project may load this file with the :command:`include` command and | |
| reference the ``MathFunctions`` library from the installation tree as if it | |
| were built in its own tree. For example: | |
| .. code-block:: cmake | |
| :linenos: | |
| include(GNUInstallDirs) | |
| include(${INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions/MathFunctionTargets.cmake) | |
| add_executable(myexe src1.c src2.c) | |
| target_link_libraries(myexe PRIVATE MathFunctions::MathFunctions) | |
| Line 2 loads the target CMake file. Although we only exported a single | |
| target, this file may import any number of targets. Their locations are | |
| computed relative to the file location so that the install tree may be | |
| easily moved. Line 4 references the imported ``MathFunctions`` library. The | |
| resulting build system will link to the library from its installed location. | |
| Executables may also be exported and imported using the same process. | |
| Any number of target installations may be associated with the same | |
| export name. Export names are considered global so any directory may | |
| contribute a target installation. The :command:`install(EXPORT)` command only | |
| needs to be called once to install a file that references all targets. Below | |
| is an example of how multiple exports may be combined into a single | |
| export file, even if they are in different subdirectories of the project. | |
| .. code-block:: cmake | |
| # A/CMakeLists.txt | |
| add_executable(myexe src1.c) | |
| install(TARGETS myexe DESTINATION lib/myproj | |
| EXPORT myproj-targets) | |
| # B/CMakeLists.txt | |
| add_library(foo STATIC foo1.c) | |
| install(TARGETS foo DESTINATION lib EXPORTS myproj-targets) | |
| # Top CMakeLists.txt | |
| add_subdirectory (A) | |
| add_subdirectory (B) | |
| install(EXPORT myproj-targets DESTINATION lib/myproj) | |
| Creating Packages | |
| ----------------- | |
| At this point, the ``MathFunctions`` project is exporting the target | |
| information required to be used by other projects. We can make this project | |
| even easier for other projects to use by generating a configuration file so | |
| that the CMake :command:`find_package` command can find our project. | |
| To start, we will need to make a few additions to the ``CMakeLists.txt`` | |
| file. First, include the :module:`CMakePackageConfigHelpers` module to get | |
| access to some helper functions for creating config files. | |
| .. literalinclude:: MathFunctions/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # include CMakePackageConfigHelpers macro | |
| :end-before: # set version | |
| Then we will create a package configuration file and a package version file. | |
| Creating a Package Configuration File | |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| Use the :command:`configure_package_config_file` command provided by the | |
| :module:`CMakePackageConfigHelpers` to generate the package configuration | |
| file. Note that this command should be used instead of the plain | |
| :command:`configure_file` command. It helps to ensure that the resulting | |
| package is relocatable by avoiding hardcoded paths in the installed | |
| configuration file. The path given to ``INSTALL_DESTINATION`` must be the | |
| destination where the ``MathFunctionsConfig.cmake`` file will be installed. | |
| We will examine the contents of the package configuration file in the next | |
| section. | |
| .. literalinclude:: MathFunctions/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # create config file | |
| :end-before: # install config files | |
| Install the generated configuration files with the :command:`install(FILES)` | |
| command. Both ``MathFunctionsConfigVersion.cmake`` and | |
| ``MathFunctionsConfig.cmake`` are installed to the same location, completing | |
| the package. | |
| .. literalinclude:: MathFunctions/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # install config files | |
| :end-before: # generate the export targets for the build tree | |
| Now we need to create the package configuration file itself. In this case, the | |
| ``Config.cmake.in`` file is very simple but sufficient to allow downstreams | |
| to use the :prop_tgt:`IMPORTED` targets. | |
| .. literalinclude:: MathFunctions/Config.cmake.in | |
| The first line of the file contains only the string ``@PACKAGE_INIT@``. This | |
| expands when the file is configured and allows the use of relocatable paths | |
| prefixed with ``PACKAGE_``. It also provides the ``set_and_check()`` and | |
| ``check_required_components()`` macros. | |
| The ``check_required_components`` helper macro ensures that all requested, | |
| non-optional components have been found by checking the | |
| ``<Package>_<Component>_FOUND`` variables for all required components. This | |
| macro should be called at the end of the package configuration file even if the | |
| package does not have any components. This way, CMake can make sure that the | |
| downstream project hasn't specified any non-existent components. If | |
| ``check_required_components`` fails, the ``<Package>_FOUND`` variable is set to | |
| FALSE, and the package is considered to be not found. | |
| The ``set_and_check()`` macro should be used in configuration files instead | |
| of the normal ``set()`` command for setting directories and file locations. | |
| If a referenced file or directory does not exist, the macro will fail. | |
| If any macros should be provided by the ``MathFunctions`` package, they should | |
| be in a separate file which is installed to the same location as the | |
| ``MathFunctionsConfig.cmake`` file, and included from there. | |
| **All required dependencies of a package must also be found in the package | |
| configuration file.** Let's imagine that we require the ``Stats`` library in | |
| our project. In the CMakeLists file, we would add: | |
| .. code-block:: cmake | |
| find_package(Stats 2.6.4 REQUIRED) | |
| target_link_libraries(MathFunctions PUBLIC Stats::Types) | |
| As the ``Stats::Types`` target is a ``PUBLIC`` dependency of ``MathFunctions``, | |
| downstreams must also find the ``Stats`` package and link to the | |
| ``Stats::Types`` library. The ``Stats`` package should be found in the | |
| configuration file to ensure this. | |
| .. code-block:: cmake | |
| include(CMakeFindDependencyMacro) | |
| find_dependency(Stats 2.6.4) | |
| The ``find_dependency`` macro from the :module:`CMakeFindDependencyMacro` | |
| module helps by propagating whether the package is ``REQUIRED``, or | |
| ``QUIET``, etc. The ``find_dependency`` macro also sets | |
| ``MathFunctions_FOUND`` to ``False`` if the dependency is not found, along | |
| with a diagnostic that the ``MathFunctions`` package cannot be used without | |
| the ``Stats`` package. | |
| **Exercise:** Add a required library to the ``MathFunctions`` project. | |
| Creating a Package Version File | |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| The :module:`CMakePackageConfigHelpers` module provides the | |
| :command:`write_basic_package_version_file` command for creating a simple | |
| package version file. This file is read by CMake when :command:`find_package` | |
| is called to determine the compatibility with the requested version, and to set | |
| some version-specific variables such as ``<PackageName>_VERSION``, | |
| ``<PackageName>_VERSION_MAJOR``, ``<PackageName>_VERSION_MINOR``, etc. See | |
| :manual:`cmake-packages <cmake-packages(7)>` documentation for more details. | |
| .. literalinclude:: MathFunctions/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # set version | |
| :end-before: # create config file | |
| In our example, ``MathFunctions_MAJOR_VERSION`` is defined as a | |
| :prop_tgt:`COMPATIBLE_INTERFACE_STRING` which means that it must be | |
| compatible among the dependencies of any depender. By setting this | |
| custom defined user property in this version and in the next version of | |
| ``MathFunctions``, :manual:`cmake <cmake(1)>` will issue a diagnostic if | |
| there is an attempt to use version 3 together with version 4. Packages can | |
| choose to employ such a pattern if different major versions of the package | |
| are designed to be incompatible. | |
| Exporting Targets from the Build Tree | |
| ------------------------------------- | |
| Typically, projects are built and installed before being used by an outside | |
| project. However, in some cases, it is desirable to export targets directly | |
| from a build tree. The targets may then be used by an outside project that | |
| references the build tree with no installation involved. The :command:`export` | |
| command is used to generate a file exporting targets from a project build tree. | |
| If we want our example project to also be used from a build directory we only | |
| have to add the following to ``CMakeLists.txt``: | |
| .. literalinclude:: MathFunctions/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # generate the export targets for the build tree | |
| Here we use the :command:`export` command to generate the export targets for | |
| the build tree. In this case, we'll create a file called | |
| ``MathFunctionsTargets.cmake`` in the ``cmake`` subdirectory of the build | |
| directory. The generated file contains the required code to import the target | |
| and may be loaded by an outside project that is aware of the project build | |
| tree. This file is specific to the build-tree, and **is not relocatable**. | |
| It is possible to create a suitable package configuration file and package | |
| version file to define a package for the build tree which may be used without | |
| installation. Consumers of the build tree can simply ensure that the | |
| :variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the | |
| ``MathFunctions_DIR`` to ``<build_dir>/MathFunctions`` in the cache. | |
| An example application of this feature is for building an executable on a host | |
| platform when cross-compiling. The project containing the executable may be | |
| built on the host platform and then the project that is being cross-compiled | |
| for another platform may load it. | |
| Building and Installing a Package | |
| --------------------------------- | |
| At this point, we have generated a relocatable CMake configuration for our | |
| project that can be used after the project has been installed. Let's try to | |
| build the ``MathFunctions`` project: | |
| .. code-block:: console | |
| mkdir MathFunctions_build | |
| cd MathFunctions_build | |
| cmake ../MathFunctions | |
| cmake --build . | |
| In the build directory, notice that the file ``MathFunctionsTargets.cmake`` | |
| has been created in the ``cmake`` subdirectory. | |
| Now install the project: | |
| .. code-block:: console | |
| $ cmake --install . --prefix "/home/myuser/installdir" | |
| Creating Relocatable Packages | |
| ============================= | |
| Packages created by :command:`install(EXPORT)` are designed to be relocatable, | |
| using paths relative to the location of the package itself. They must not | |
| reference absolute paths of files on the machine where the package is built | |
| that will not exist on the machines where the package may be installed. | |
| When defining the interface of a target for ``EXPORT``, keep in mind that the | |
| include directories should be specified as relative paths to the | |
| :variable:`CMAKE_INSTALL_PREFIX` but should not explicitly include the | |
| :variable:`CMAKE_INSTALL_PREFIX`: | |
| .. code-block:: cmake | |
| target_include_directories(tgt INTERFACE | |
| # Wrong, not relocatable: | |
| $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName> | |
| ) | |
| target_include_directories(tgt INTERFACE | |
| # Ok, relocatable: | |
| $<INSTALL_INTERFACE:include/TgtName> | |
| ) | |
| The :genex:`$<INSTALL_PREFIX>` generator expression may be used as | |
| a placeholder for the install prefix without resulting in a non-relocatable | |
| package. This is necessary if complex generator expressions are used: | |
| .. code-block:: cmake | |
| target_include_directories(tgt INTERFACE | |
| # Ok, relocatable: | |
| $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/include/TgtName> | |
| ) | |
| This also applies to paths referencing external dependencies. | |
| It is not advisable to populate any properties which may contain | |
| paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` or | |
| :prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies. | |
| For example, this code may not work well for a relocatable package: | |
| .. code-block:: cmake | |
| target_link_libraries(MathFunctions INTERFACE | |
| ${Foo_LIBRARIES} ${Bar_LIBRARIES} | |
| ) | |
| target_include_directories(MathFunctions INTERFACE | |
| "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>" | |
| ) | |
| The referenced variables may contain the absolute paths to libraries | |
| and include directories **as found on the machine the package was made on**. | |
| This would create a package with hard-coded paths to dependencies not | |
| suitable for relocation. | |
| Ideally such dependencies should be used through their own | |
| :ref:`IMPORTED targets <Imported Targets>` that have their own | |
| :prop_tgt:`IMPORTED_LOCATION` and usage requirement properties | |
| such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated | |
| appropriately. Those imported targets may then be used with | |
| the :command:`target_link_libraries` command for ``MathFunctions``: | |
| .. code-block:: cmake | |
| target_link_libraries(MathFunctions INTERFACE Foo::Foo Bar::Bar) | |
| With this approach the package references its external dependencies | |
| only through the names of :ref:`IMPORTED targets <Imported Targets>`. | |
| When a consumer uses the installed package, the consumer will run the | |
| appropriate :command:`find_package` commands (via the ``find_dependency`` | |
| macro described above) to find the dependencies and populate the | |
| imported targets with appropriate paths on their own machine. | |
| Using the Package Configuration File | |
| ==================================== | |
| Now we're ready to create a project to use the installed ``MathFunctions`` | |
| library. In this section we will be using source code from | |
| ``Help\guide\importing-exporting\Downstream``. In this directory, there is a | |
| source file called ``main.cc`` that uses the ``MathFunctions`` library to | |
| calculate the square root of a given number and then prints the results: | |
| .. literalinclude:: Downstream/main.cc | |
| :language: c++ | |
| As before, we'll start with the :command:`cmake_minimum_required` and | |
| :command:`project` commands in the ``CMakeLists.txt`` file. For this project, | |
| we'll also specify the C++ standard. | |
| .. literalinclude:: Downstream/CMakeLists.txt | |
| :language: cmake | |
| :end-before: # find MathFunctions | |
| We can use the :command:`find_package` command: | |
| .. literalinclude:: Downstream/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # find MathFunctions | |
| :end-before: # create executable | |
| Create an executable: | |
| .. literalinclude:: Downstream/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # create executable | |
| :end-before: # use MathFunctions library | |
| And link to the ``MathFunctions`` library: | |
| .. literalinclude:: Downstream/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # use MathFunctions library | |
| That's it! Now let's try to build the ``Downstream`` project. | |
| .. code-block:: console | |
| mkdir Downstream_build | |
| cd Downstream_build | |
| cmake ../Downstream | |
| cmake --build . | |
| A warning may have appeared during CMake configuration: | |
| .. code-block:: console | |
| CMake Warning at CMakeLists.txt:4 (find_package): | |
| By not providing "FindMathFunctions.cmake" in CMAKE_MODULE_PATH this | |
| project has asked CMake to find a package configuration file provided by | |
| "MathFunctions", but CMake did not find one. | |
| Could not find a package configuration file provided by "MathFunctions" | |
| with any of the following names: | |
| MathFunctionsConfig.cmake | |
| mathfunctions-config.cmake | |
| Add the installation prefix of "MathFunctions" to CMAKE_PREFIX_PATH or set | |
| "MathFunctions_DIR" to a directory containing one of the above files. If | |
| "MathFunctions" provides a separate development package or SDK, be sure it | |
| has been installed. | |
| Set the ``CMAKE_PREFIX_PATH`` to where MathFunctions was installed previously | |
| and try again. Ensure that the newly created executable runs as expected. | |
| Adding Components | |
| ================= | |
| Let's edit the ``MathFunctions`` project to use components. The source code for | |
| this section can be found in | |
| ``Help\guide\importing-exporting\MathFunctionsComponents``. The CMakeLists file | |
| for this project adds two subdirectories: ``Addition`` and ``SquareRoot``. | |
| .. literalinclude:: MathFunctionsComponents/CMakeLists.txt | |
| :language: cmake | |
| :end-before: # include CMakePackageConfigHelpers macro | |
| Generate and install the package configuration and package version files: | |
| .. literalinclude:: MathFunctionsComponents/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # include CMakePackageConfigHelpers macro | |
| If ``COMPONENTS`` are specified when the downstream uses | |
| :command:`find_package`, they are listed in the | |
| ``<PackageName>_FIND_COMPONENTS`` variable. We can use this variable to verify | |
| that all necessary component targets are included in ``Config.cmake.in``. At | |
| the same time, this function will act as a custom ``check_required_components`` | |
| macro to ensure that the downstream only attempts to use supported components. | |
| .. literalinclude:: MathFunctionsComponents/Config.cmake.in | |
| Here, the ``MathFunctions_NOT_FOUND_MESSAGE`` is set to a diagnosis that the | |
| package could not be found because an invalid component was specified. This | |
| message variable can be set for any case where the ``_FOUND`` variable is set | |
| to ``False``, and will be displayed to the user. | |
| The ``Addition`` and ``SquareRoot`` directories are similar. Let's look at one | |
| of the CMakeLists files: | |
| .. literalinclude:: MathFunctionsComponents/SquareRoot/CMakeLists.txt | |
| :language: cmake | |
| Now we can build the project as described in earlier sections. To test using | |
| this package, we can use the project in | |
| ``Help\guide\importing-exporting\DownstreamComponents``. There's two | |
| differences from the previous ``Downstream`` project. First, we need to find | |
| the package components. Change the ``find_package`` line from: | |
| .. literalinclude:: Downstream/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # find MathFunctions | |
| :end-before: # create executable | |
| To: | |
| .. literalinclude:: DownstreamComponents/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # find MathFunctions | |
| :end-before: # create executable | |
| and the ``target_link_libraries`` line from: | |
| .. literalinclude:: Downstream/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # use MathFunctions library | |
| To: | |
| .. literalinclude:: DownstreamComponents/CMakeLists.txt | |
| :language: cmake | |
| :start-after: # use MathFunctions library | |
| :end-before: # Workaround for GCC on AIX to avoid -isystem | |
| In ``main.cc``, replace ``#include MathFunctions.h`` with: | |
| .. literalinclude:: DownstreamComponents/main.cc | |
| :language: c | |
| :start-after: #include <string> | |
| :end-before: int main | |
| Finally, use the ``Addition`` library: | |
| .. literalinclude:: DownstreamComponents/main.cc | |
| :language: c | |
| :start-after: // calculate sum | |
| :end-before: return 0; | |
| Build the ``Downstream`` project and confirm that it can find and use the | |
| package components. |