.. _cmake_find_package_generator:


``cmake_find_package`` generator
================================

This generator is especially useful if you are using ``CMake`` using the ``find_package``
feature to locate the dependencies.

The ``cmake_find_package`` generator creates a file for each requirement specified in the conanfile.


The name of the files follows the pattern ``Find<package_name>.cmake``. So for the ``zlib/1.2.11@conan/stable`` package,
a ``Findzlib.cmake`` file will be generated.


In a conanfile.py
-----------------


.. code-block:: python
   :caption: conanfile.py
   :emphasize-lines: 7

   from conans import ConanFile, tools


   class LibConan(ConanFile):
       ...
       requires = "zlib/1.2.11@conan/stable"
       generators = "cmake_find_package"

       def build(self):
           cmake = CMake(self) # it will find the packages by using our auto-generated FindXXX.cmake files
           cmake.configure()
           cmake.build()

In the previous example, the ``CMake`` build helper will adjust automatically the ``CMAKE_MODULE_PATH`` to the
``conanfile.install_folder``, where the generated ``Find<package_name>.cmake`` are.

In the ``CMakeList.txt`` you do not need to specify or include anything related with Conan at all, just
rely on the ``find_package`` feature:

.. code-block:: cmake
    :caption: CMakeList.txt

    cmake_minimum_required(VERSION 3.0)
    project(helloworld)
    add_executable(helloworld hello.c)
    find_package(Zlib)

    # Global approach
    if(ZLIB_FOUND)
       include_directories(${ZLIB_INCLUDE_DIRS})
       target_link_libraries (helloworld ${ZLIB_LIBRARIES})
    endif()

    # Modern CMake targets approach
    if(TARGET zlib::zlib)
       target_link_libraries(helloworld zlib::zlib)
    endif()


.. code-block:: bash
    :emphasize-lines: 6, 7

    $ conan create . user/channel

      lib/1.0@user/channel: Calling build()
      -- The C compiler identification is AppleClang 9.1.0.9020039
      ...
      -- Conan: Using autogenerated Findzlib.cmake
      -- Found: /Users/user/.conan/data/zlib/1.2.11/conan/stable/package/0eaf3bfbc94fb6d2c8f230d052d75c6c1a57a4ce/lib/libz.a
      lib/1.0@user/channel: Package '72bce3af445a371b892525bc8701d96c568ead8b' created



In a conanfile.txt
------------------

If you are using a ``conanfile.txt`` file in your project, instead of a ``conanfile.py``, this generator
can be used together with the :ref:`cmake_paths <cmake_paths_generator>` generator to adjust the ``CMAKE_MODULE_PATH`` variable automatically
and let CMake to locate the generated ``Find<package_name>.cmake`` files.


With **cmake_paths**:

.. code-block:: text
   :caption: conanfile.txt

   [requires]
   zlib/1.2.11@conan/stable
   ...

   [generators]
   cmake_find_package
   cmake_paths


.. code-block:: cmake
    :caption: CMakeList.txt
    :emphasize-lines: 3

    cmake_minimum_required(VERSION 3.0)
    project(helloworld)
    include(${CMAKE_BINARY_DIR}/conan_paths.cmake)
    add_executable(helloworld hello.c)
    find_package(Zlib)

    # Global approach
    if(ZLIB_FOUND)
       include_directories(${ZLIB_INCLUDE_DIRS})
       target_link_libraries (helloworld ${ZLIB_LIBRARIES})
    endif()

    # Modern CMake targets approach
    if(TARGET zlib::zlib)
       target_link_libraries(helloworld zlib::zlib)
    endif()


.. code-block:: bash
    :emphasize-lines: 4, 5

    $ mkdir build && cd build
    $ conan install ..
    $ cmake .. -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release
      -- Conan: Using autogenerated Findzlib.cmake
      -- Found: /Users/user/.conan/data/zlib/1.2.11/conan/stable/package/0eaf3bfbc94fb6d2c8f230d052d75c6c1a57a4ce/lib/libz.a
      ...

    $ cmake --build .


Or you can also adjust ``CMAKE_MODULE_PATH`` manually.
Without **cmake_paths**, adjusting ``CMAKE_MODULE_PATH`` manually:

.. code-block:: text
   :caption: conanfile.txt

   [requires]
   zlib/1.2.11@conan/stable
   ...

   [generators]
   cmake_find_package

.. code-block:: cmake
    :caption: CMakeList.txt
    :emphasize-lines: 3

    cmake_minimum_required(VERSION 3.0)
    project(helloworld)
    set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR} ${CMAKE_MODULE_PATH})
    add_executable(helloworld hello.c)
    find_package(Zlib)

    # Global approach
    if(ZLIB_FOUND)
       include_directories(${ZLIB_INCLUDE_DIRS})
       target_link_libraries (helloworld ${ZLIB_LIBRARIES})
    endif()

    # Modern CMake targets approach
    if(TARGET zlib::zlib)
       target_link_libraries(helloworld zlib::zlib)
    endif()


.. seealso:: Check the section :ref:`Reference/Generators/cmake_find_package <cmake_cmake_find_package_generator_reference>`
   to read more about this generator and the adjusted CMake variables/targets.