extra-cmake-modules/modules/ECMUseFindModules.cmake

0001 # SPDX-FileCopyrightText: 2011 Alexander Neundorf <neundorf@kde.org>
0002 #
0003 # SPDX-License-Identifier: BSD-3-Clause
0004
0005 #[=======================================================================[.rst:
0006 ECMUseFindModules
0007 -----------------
0008
0009 Selectively use some of the find modules provided by extra-cmake-modules.
0010
0011 This module is automatically available once extra-cmake-modules has been
0012 found, so it is not necessary to ``include(ECMUseFindModules)`` explicitly.
0013
0014 ::
0015
0016   ecm_use_find_modules(DIR <dir>
0017                        MODULES module1.cmake [module2.cmake [...]]
0018                        [NO_OVERRIDE])
0019
0020 This allows selective use of the find modules provided by ECM, including
0021 deferring to CMake's versions of those modules if it has them.  Rather than
0022 adding ``${ECM_FIND_MODULE_DIR}`` to ``CMAKE_MODULE_PATH``, you use
0023 ``ecm_use_find_modules()`` to copy the modules you want to a local (build)
0024 directory, and add that to ``CMAKE_MODULE_PATH``.
0025
0026 The find modules given to ``MODULES`` will be copied to the directory given by ``DIR``
0027 (which should be located in ``${CMAKE_BINARY_DIR}`` and added to
0028 ``CMAKE_MODULE_PATH``).  If ``NO_OVERRIDE`` is given, only modules not also
0029 provided by CMake will be copied.
0030
0031 Example:
0032
0033 .. code-block:: cmake
0034
0035   find_package(ECM REQUIRED)
0036   ecm_use_find_modules(
0037       DIR ${CMAKE_BINARY_DIR}/cmake
0038       MODULES FindEGL.cmake
0039       NO_OVERRIDE
0040   )
0041   set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)
0042
0043 This example will make ``FindEGL.cmake`` available in your project, but only
0044 as long as it is not yet part of CMake. Calls to ``find_package(EGL)`` will
0045 then make use of this copied module (or the CMake module if it exists).
0046
0047 Another possible use for this macro is to take copies of find modules that can
0048 be installed along with config files if they are required as a dependency (for
0049 example, if targets provided by the find module are in the link interface of a
0050 library).
0051
0052 Since pre-1.0.0.
0053 #]=======================================================================]
0054
0055 function(ecm_use_find_modules)
0056    set(_options NO_OVERRIDE )
0057    set(_oneValueArgs DIR )
0058    set(_multiValueArgs MODULES )
0059    cmake_parse_arguments(EUFM "${_options}" "${_oneValueArgs}" "${_multiValueArgs}" ${ARGN} )
0060    if(NOT EUFM_DIR)
0061       message(FATAL_ERROR "No DIR specified for ecm_use_find_modules() !")
0062    endif()
0063
0064    if(NOT IS_ABSOLUTE "${EUFM_DIR}")
0065       set(EUFM_DIR "${CMAKE_CURRENT_BINARY_DIR}/${EUFM_DIR}")
0066    endif()
0067    file(MAKE_DIRECTORY "${EUFM_DIR}")
0068
0069    foreach(file ${EUFM_MODULES})
0070       if(NOT EXISTS ${ECM_FIND_MODULE_DIR}/${file} )
0071          message(FATAL_ERROR "File ${file} not found in ${ECM_FIND_MODULE_DIR} !")
0072       endif()
0073       if(NOT EXISTS "${CMAKE_ROOT}/Modules/${file}" OR NOT EUFM_NO_OVERRIDE)
0074          configure_file("${ECM_FIND_MODULE_DIR}/${file}" "${EUFM_DIR}/${file}" COPYONLY)
0075       endif()
0076    endforeach()
0077    # This is required by some of the find modules
0078    file(WRITE "${EUFM_DIR}/ECMFindModuleHelpersStub.cmake"
0079         "include(\"${ECM_MODULE_DIR}/ECMFindModuleHelpers.cmake\")")
0080
0081 endfunction()