diff --git a/reference/tools/cmake/cmakedeps.rst b/reference/tools/cmake/cmakedeps.rst index 959035f2fdce..085cb4f79a67 100644 --- a/reference/tools/cmake/cmakedeps.rst +++ b/reference/tools/cmake/cmakedeps.rst @@ -70,7 +70,7 @@ Generated files - **Other necessary *.cmake**: files like version, flags and directory data or configuration. -Note that it will also generate a **conandeps_legacy.cmake** file. This is a file that provides a behavior similar to the Conan 1 ``cmake`` generator, allowing to include this file with ``include(${CMAKE_BINARY_DIR}/generators/conandeps_legacy.cmake)``, and providing a single CMake ``CONANDEPS_LEGACY`` variable that allows to link with all the direct and transitive dependencies without explicitly enumerating them like: ``target_link_libraries(app ${CONANDEPS_LEGACY})``. This is a convenience provided for Conan 1.X users to upgrade to Conan 2 without changing their overall developer flow, but it is not recommended otherwise, and using the CMake canonical flow of explicitly using ``find_package()`` and ``target_link_libraries(... pkg1::pkg1 pkg2::pkg2)`` with targets is the correct approach. +Note that it will also generate a **conandeps_legacy.cmake** file. This is a file that provides a behavior similar to the Conan 1 ``cmake`` generator, allowing to include this file with ``include(${CMAKE_BINARY_DIR}/generators/conandeps_legacy.cmake)``, and providing a single CMake ``CONANDEPS_LEGACY`` variable that allows to link with all the direct and transitive dependencies without explicitly enumerating them like: ``target_link_libraries(app ${CONANDEPS_LEGACY})``. This is a convenience provided for Conan 1.X users to upgrade to Conan 2 without changing their overall developer flow, but it is not recommended otherwise, and using the CMake canonical flow of explicitly using ``find_package()`` and ``target_link_libraries(... pkg1::pkg1 pkg2::pkg2)`` with targets is the correct approach. Customization @@ -239,6 +239,7 @@ The following properties affect the CMakeDeps generator: - ``config``: The CMakeDeps generator will create config scripts for the dependency. - ``module``: Will create module config (FindXXX.cmake) scripts for the dependency. - ``both``: Will generate both config and modules. + - ``copy``: Will copy generated config scripts for the dependency. Uses generated target files. - ``none``: Won't generate any file. It can be used, for instance, to create a system wrapper package so the consumers find the config files in the CMake installation config path and not in the generated by Conan (because it has been skipped). - **cmake_module_file_name**: Same as **cmake_file_name** but when generating modules with ``cmake_find_mode=module/both``. If not specified it will default to **cmake_file_name**. @@ -363,6 +364,34 @@ component separated by a double colon (`::`). Here's an example: ... +.. _Copy Project Generated CMake Configuration Files: + +Copy Project Generated CMake configuration files ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Some projects may want to have ``CMakeDeps`` copy the project generated CMake files for downstream +consumers. This can be done by settings ``cmake_find_mode`` to ``copy``. The project will likely +need to add the installed locations of these configuration files in the ``exports_sources`` attribute +of the ``conanfile``. + +This method is especially useful if the project manages non-Conan dependencies or the Cmake configuration +files define additional variables imported by the project. It also functions correctly with multi-configuration +generators. + +This method only copies the Config.cmake and ConfigVersion.cmake files. The target files are +still generated by Conan. + +Example: + +.. code-block:: python + + def package(self): + ... + cmake.install() + + def package_info(self): + self.cpp_info.set_property("cmake_find_mode", "copy") # Copy cmake config files that are generated by project. + .. _Disable CMakeDeps For Installed CMake imports: Disable CMakeDeps For Installed CMake configuration files @@ -391,12 +420,12 @@ Map from project configuration to imported target's configuration As mentioned above, ``CMakeDeps`` provides support for multiple configuration environments (Debug, Release, etc.) This is achieved by populating properties on the imported targets according to the ``build_type`` setting -when installing dependencies. When a consumer project is configured with a single-configuration CMake generator, however, +when installing dependencies. When a consumer project is configured with a single-configuration CMake generator, however, it is necessary to define the ``CMAKE_BUILD_TYPE`` with a value that matches that of the installed dependencies. If the consumer CMake project is configured with a different build type than the dependencies, it is necessary to -tell CMake how to map the configurations from the current project to the imported targets by setting the -``CMAKE_MAP_IMPORTED_CONFIG_`` CMake variable. +tell CMake how to map the configurations from the current project to the imported targets by setting the +``CMAKE_MAP_IMPORTED_CONFIG_`` CMake variable. .. code-block:: bash