diff --git a/integrations/cmake.rst b/integrations/cmake.rst index 24ba9224204..ad1ddd9674b 100644 --- a/integrations/cmake.rst +++ b/integrations/cmake.rst @@ -13,6 +13,7 @@ Conan can be integrated with CMake using generators, build helpers and custom *f cmake/cmake_multi_generator cmake/cmake_paths_generator cmake/cmake_find_package_generator + cmake/cmake_find_package_multi_generator cmake/build_automation cmake/find_packages diff --git a/integrations/cmake/cmake_find_package_multi_generator.rst b/integrations/cmake/cmake_find_package_multi_generator.rst new file mode 100644 index 00000000000..be3d4213d81 --- /dev/null +++ b/integrations/cmake/cmake_find_package_multi_generator.rst @@ -0,0 +1,39 @@ + +.. _cmake_find_package_multi_generator: + + +``cmake_find_package_multi`` +============================ + + +.. warning:: + + This is an **experimental** feature subject to breaking changes in future releases. + +This generator is similar to the :ref:`cmake_find_package` generator but it allows to work with +multi-configuration projects like ``Visual Studio`` with both ``Debug`` and ``Release``. But there are some differences: + +- Only works with CMake > 3.0 +- It doesn't generate ``FindXXX.cmake`` modules but ``XXXConfig.cmake`` files. +- The "global" approach is not supported, only "modern" CMake by using targets. + + +Usage +----- + +.. code-block:: bash + + $ conan install . -g cmake_find_package_multi -s build_type=Debug + $ conan install . -g cmake_find_package_multi -s build_type=Release + +These commands will generate several files for each dependency in your graph, including a ``XXXConfig.cmake`` that can be located +by the CMake `find_package(XXX) `_ command, being XXX the package name. + +The name of the files follows the pattern ``Config.cmake``. So for the ``zlib/1.2.11@conan/stable`` package, +a ``zlibConfig.cmake`` file will be generated. + + +.. seealso:: + + Check the section :ref:`cmake_find_package_multi_generator_reference` to read more about this generator and the adjusted CMake + variables/targets. diff --git a/reference/generators.rst b/reference/generators.rst index 4a76cdd1ef3..90ad942a841 100644 --- a/reference/generators.rst +++ b/reference/generators.rst @@ -21,6 +21,7 @@ Available generators: generators/cmakemulti generators/cmake_paths generators/cmake_find_package + generators/cmake_find_package_multi generators/visualstudio generators/visualstudiomulti generators/visualstudiolegacy diff --git a/reference/generators/cmake_find_package_multi.rst b/reference/generators/cmake_find_package_multi.rst new file mode 100644 index 00000000000..5e8ee2002b5 --- /dev/null +++ b/reference/generators/cmake_find_package_multi.rst @@ -0,0 +1,65 @@ +.. _cmake_find_package_multi_generator_reference: + + +`cmake_find_package_multi` +========================== + +.. warning:: + + This is an **experimental** feature subject to breaking changes in future releases. + +.. container:: out_reference_box + + This is the reference page for ``cmake_find_package_multi`` generator. + Go to :ref:`Integrations/CMake` if you want to learn how to integrate your project or recipes with CMake. + + +Generated files +--------------- + +For each conan package in your graph, it will generate 2 files and 1 more per different ``build_type``. +Being {name} the package name: + ++------------------------------------+--------------------------------------------------------------------------------------+ +| NAME | CONTENTS | ++====================================+======================================================================================+ +| {name}Config.cmake | It includes the {name}Targets.cmake and call find_dependency for each dep | ++------------------------------------+--------------------------------------------------------------------------------------+ +| {name}Targets.cmake | It includes the following files | ++------------------------------------+--------------------------------------------------------------------------------------+ +| {name}Targets-debug.cmake | Specific information for the Debug configuration | ++------------------------------------+--------------------------------------------------------------------------------------+ +| {name}Targets-release.cmake | Specific information for the Release configuration | ++------------------------------------+--------------------------------------------------------------------------------------+ +| {name}Targets-relwithdebinfo.cmake | Specific information for the RelWithDebInfo configuration | ++------------------------------------+--------------------------------------------------------------------------------------+ +| {name}Targets-minsizerel.cmake | Specific information for the MinSizeRel configuration | ++------------------------------------+--------------------------------------------------------------------------------------+ + +Targets +------- + +A target named ``{name}::{name}`` target is generated with the following properties adjusted: + +- ``INTERFACE_INCLUDE_DIRECTORIES``: Containing all the include directories of the package. +- ``INTERFACE_LINK_LIBRARIES``: Library paths to link. +- ``INTERFACE_COMPILE_DEFINITIONS``: Definitions of the library. + +The targets contains multi-configuration properties, for example, the compile options property +is declared like this: + +.. code-block:: cmake + + set_property(TARGET {name}::{name} + PROPERTY INTERFACE_COMPILE_OPTIONS + $<$:${{{name}_COMPILE_OPTIONS_RELEASE_LIST}}> + $<$:${{{name}_COMPILE_OPTIONS_RELWITHDEBINFO_LIST}}> + $<$:${{{name}_COMPILE_OPTIONS_MINSIZEREL_LIST}}> + $<$:${{{name}_COMPILE_OPTIONS_DEBUG_LIST}}>) + +The targets are also transitive. So, if your project depends on a packages ``A`` and ``B``, and at the same time +``A`` depends on ``C``, the ``A`` target will contain automatically the properties of the ``C`` dependency, so +in your `CMakeLists.txt` file you only need to ``find_package(A)`` and ``find_package(B)``. + +The `{name}Config.cmake` file will be found by the cmake ``find_package(XXX)`` function if the directory where the file is generated +is listed in the `CMAKE_PREFIX_PATH `_.