path: root/docs/writing-find-modules.md

Writing Find Modules           {#writing-find-modules}
====================

The `find_package` macro from CMake has two ways of finding packages.  If the
package Foo provides a `FooConfig.cmake` file in an appropriate place, CMake
will use that to determine all the necessary information to build against the
package.  Otherwise, if there is a `FindFoo.cmake` file somewhere in
`CMAKE_MODULE_PATH`, that will be used to find whether the package exists and
determine the appropriate information about it if it does.  See
[the CMake documentation][cmake:packages] for more information.

The primary task of a `FindFoo.cmake` file is to determine whether the requested
package exists on the system, and set the `Foo_FOUND` variable to reflect this.
If Foo is a library, it typically sets variables such as `Foo_LIBRARIES`,
`Foo_INCLUDE_DIRS` and `Foo_DEFINITIONS` to provide the necessary information to
build and link against that library.  The `FindFoo.cmake` files in
extra-cmake-modules usually provide imported targets to make using the libraries
even simpler.  The files may also provide additional variables and useful CMake
macros.

We will describe a typical CMake module for finding a library.

[cmake:packages]: http://www.cmake.org/cmake/help/git-master/manual/cmake-packages.7.html


Documentation
-------------

The first thing that is needed is documentation.  Start the file with a simple
statement of what the module does.  In the simplest case, this is just

    # Find the Foo library

but more description may be required for some packages.  If there are caveats or
other details users of the module should be aware of, you can add further
paragraphs below this.  Then you need to document what variables and imported
targets are set by the module, such as

    # This will define the following variables:
    #
    #     Foo_FOUND         - True if the system has the Foo library
    #     Foo_VERSION       - The version of the Foo library which was found
    #
    # and the following imported targets:
    #
    #     Foo::Bar
    #
    # The following compatibility variables will also be defined, although
    # the imported targets should be used instead:
    #
    #     Foo_LIBRARIES      - Link to these to use the Foo library
    #     Foo_INCLUDES_DIRS  - Include directory for the Foo library
    #     Foo_DEFINITIONS    - Compiler flags required to link against the Foo library
    #     Foo_VERSION - The version of the Foo library which was found

Don't forget to add copyright and license notices.  Any module distributed with
extra-cmake-modules must use the BSD 2-clause or 3-clause license:

    # Copyright 2014 Your Name <your@email>
    #
    # Redistribution and use in source and binary forms, with or without
    # modification, are permitted provided that the following conditions
    # are met:
    #
    # 1. Redistributions of source code must retain the copyright
    #    notice, this list of conditions and the following disclaimer.
    # 2. Redistributions in binary form must reproduce the copyright
    #    notice, this list of conditions and the following disclaimer in the
    #    documentation and/or other materials provided with the distribution.
    # 3. The name of the author may not be used to endorse or promote products
    #    derived from this software without specific prior written permission.
    #
    # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
    # IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
    # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
    # IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
    # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
    # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
    # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


Version Requirements
--------------------

The modules provided by extra-cmake-modules typically assume a minimum CMake
version.  This is particularly relevant with imported targets, which are not
supported in old CMake versions.  You can (and should) enforce this in the
following way:


    if(CMAKE_VERSION VERSION_LESS 2.8.12)
        message(FATAL_ERROR "CMake 2.8.12 is required by FindFoo.cmake")
    endif()
    if(CMAKE_MINIMUM_REQUIRED_VERSION VERSION_LESS 2.8.12)
        message(AUTHOR_WARNING "Your project should require at least CMake 2.8.12 to use FindFoo.cmake")
    endif()

This provides developers and users with helpful error messages, rather than the
projects failing for mysterious reasons with old CMake versions.


Finding the Package
-------------------

Now the actual libraries and so on have to be found.  The code here will
obviously vary from module to module (that, after all, is the point of the Find
modules), but there tends to be a common pattern for libraries.

First, we try to use `pkg-config` to find the library.  Note that we cannot rely
on this, as it may not be available, but it provides a good starting point.

    find_package(PkgConfig)
    pkg_check_modules(PC_Foo QUIET Foo)

This should define some variables starting `PC_Foo_` that contain the
information from the `.pc` file.  We can use this to set `Foo_DEFINITIONS`:

    set(Foo_DEFINITIONS ${PC_Foo_CFLAGS_OTHER})

Now we need to find the libraries and include files; we use the information from
`pkg-config` to provide hints to CMake about where to look:

    find_path(Foo_INCLUDE_DIR
        NAMES
            foo.h
        PATHS
            ${PC_Foo_INCLUDEDIR}
            ${PC_Foo_INCLUDE_DIRS}
        PATH_SUFFIXES
            Foo # if you need to put #include <Foo/foo.h> in your code
    )
    find_library(Foo_LIBRARY
        NAMES
            foo
        PATHS
            ${PC_Foo_LIBDIR}
            ${PC_Foo_LIBRARY_DIRS}
    )

If you have a good way of getting the version (from a header file, for example),
you can use that information to set `Foo_VERSION`.  Otherwise, attempt to
use the information from `pkg-config`:

    set(Foo_VERSION ${PC_Foo_VERSION})


Finishing Up
------------

Now we can use `FindPackageHandleStandardArgs` to do most of the rest of the
work for us.

    include(FindPackageHandleStandardArgs)
    find_package_handle_standard_args(Foo
        FOUND_VAR Foo_FOUND
        REQUIRED_VARS
            Foo_LIBRARY
            Foo_INCLUDE_DIR
        VERSION_VAR Foo_VERSION
    )

This will check that the `REQUIRED_VARS` contain values (that do not end in
`-NOTFOUND`) and set `Foo_FOUND` appropriately.  It will also cache those
values.  If `Foo_VERSION` is set, and a required version was passed to
`find_package`, it will check the requested version against the one in
`Foo_VERSION`.  It will also print messages as appropriate; note that if
the package was found, it will print the contents of the first required variable
to indicate where it was found.

We add an imported target for the library.  Note that we do this after calling
`find_package_handle_standard_args` so that we can use the `Foo_FOUND` variable.
Imported targets should be namespaced (hence the `Foo::` prefix); CMake will
recognize that values passed to `target_link_libraries` that contain `::` in
their name are supposed to be imported targets (rather than just library names),
and will produce appropriate diagnostic messages if that target does not exist.

    if(Foo_FOUND AND NOT TARGET Foo::Foo)
        add_library(Foo::Foo UNKNOWN IMPORTED)
        set_target_properties(Foo::Foo PROPERTIES
            IMPORTED_LOCATION "${Foo_LIBRARY}"
            INTERFACE_COMPILE_OPTIONS "${Foo_DEFINITIONS}"
            INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"
        )
    endif()

One thing to note about this is that the `INTERFACE_INCLUDE_DIRECTORIES` and
similar properties should only contain information about the target itself, and
not any of its dependencies.  Instead, those dependencies should also be
targets, and CMake should be told that they are dependencies of this target.
CMake will then combine all the necessary information automatically.

We should also provide some information about the package, such as where to
download it.

    include(FeatureSummary)
    set_package_properties(Foo PROPERTIES
        URL http://www.foo.example.com/
        DESCRIPTION "A library for doing useful things")

Most of the cache variables should be hidden in the `ccmake` interface unless
the user explicitly asks to edit them:

    mark_as_advanced(
        Foo_INCLUDE_DIR
        Foo_LIBRARY
    )

If this module replaces an older version, you should set compatibility variables
to cause the least disruption possible.

    # compatibility variables
    set(Foo_LIBRARIES ${Foo_LIBRARY})
    set(Foo_INCLUDE_DIRS ${Foo_INCLUDE_DIR})
    set(Foo_VERSION_STRING ${Foo_VERSION})

Note that we do not wish to pass `Foo_LIBRARIES` to `find_library`, or
`Foo_INCLUDE_DIRS` to `find_path`, as the variables passed to those commands
will be stored in the cache for the user to override.


Components
----------

If your find module has multiple components, such as a package that provides
multiple libraries, the following pattern can be helpful.  First (after the
version checks), define what components are available:

    set(knownComponents
        Bar
        Baz
    )

Determine which components we need to find.  Note that `Foo_FIND_COMPONENTS` is
defined if `find_package` was passed the `COMPONENTS` option.

    if (Foo_FIND_COMPONENTS)
        set(requiredComponents ${Foo_FIND_COMPONENTS})
    else()
        set(requiredComponents ${knownComponents})
    endif()

Translate component names into names to pass to `pkg-config`, and check for any
unknown components:

    unset(unknownComponents)
    foreach(comp ${requiredComponents})
        list(FIND knownComponents ${comp} index)
        if("${index}" STREQUAL "-1")
            list(APPEND unknownComponents "${comp}")
        endif()
    endforeach()
    
    if(DEFINED unknownComponents)
        set(msgType STATUS)
        if(Foo_FIND_REQUIRED)
            set(msgType FATAL_ERROR)
        endif()
        if(NOT Foo_FIND_QUIETLY)
            message(${msgType} "Foo: requested unknown components ${unknownComponents}")
        endif()
        return()
    endif()

Now we create a macro to handle each component.  The logic is very similar to
that of a Find module without components; in fact, most of it could be replaced
with `find_package` calls that use either other `Find*.cmake` files or
`*Config.make` files.

    include(FindPackageHandleStandardArgs)
    find_package(PkgConfig)

    macro(_foo_handle_component _comp)
        set(_header)
        set(_lib)
        set(_pkgconfig_module)
        if("${_comp}" STREQUAL "Bar")
            set(_header "Foo/bar.h")
            set(_lib "bar")
            set(_pkgconfig_module "foo-bar")
        elseif("${_comp}" STREQUAL "Baz")
            set(_header "Foo/baz.h")
            set(_lib "baz")
            set(_pkgconfig_module "foo-baz")
        endif()

        pkg_check_modules(PC_Foo_${_comp} QUIET ${_pkgconfig_module})

        find_path(Foo_${_comp}_INCLUDE_DIR
            NAMES ${_header}
            HINTS ${PC_Foo_${_comp}_INCLUDE_DIRS}
        )
        find_library(Foo_${_comp}_LIBRARY
            NAMES ${_lib}
            HINTS ${PC_Foo_${_comp}_LIBRARY_DIRS}
        )
        set(Foo_${_comp}_DEFINITIONS ${Foo_${_comp}_CFLAGS_OTHER})

        # compatibility variables
        if(Foo_${_comp}_INCLUDE_DIR AND Foo_${_comp}_LIBRARY)
            list(APPEND Foo_DEFINITIONS ${Foo_${_comp}_DEFINITIONS})
            list(APPEND Foo_INCLUDE_DIRS ${Foo_${_comp}_INCLUDE_DIR})
            list(APPEND Foo_LIBRARIES ${Foo_${_comp}_LIBRARY})
        endif()

        set(Foo_${_comp}_VERSION "${PC_Foo_${_comp}_VERSION}")
        if(NOT Foo_VERSION)
            set(Foo_VERSION ${Foo_${_comp}_VERSION})
        endif()

        find_package_handle_standard_args(Foo_${_comp}
            FOUND_VAR
                Foo_${_comp}_FOUND
            REQUIRED_VARS
                Foo_${_comp}_LIBRARY
                Foo_${_comp}_INCLUDE_DIR
            VERSION_VAR
                Foo_${_comp}_VERSION
        )

        mark_as_advanced(
            Foo_${_comp}_LIBRARY
            Foo_${_comp}_INCLUDE_DIR
        )

        if(Foo_${_comp}_FOUND AND NOT TARGET Foo::${_comp})
            add_library(Foo::${_comp} UNKNOWN IMPORTED)
            set_target_properties(Foo::${_comp} PROPERTIES
                IMPORTED_LOCATION "${Foo_${_comp}_LIBRARY}"
                INTERFACE_COMPILE_OPTIONS "${Foo_${_comp}_DEFINITIONS}"
                INTERFACE_INCLUDE_DIRECTORIES "${Foo_${_comp}_INCLUDE_DIR}"
            )
        endif()
    endmacro()

And finish off with everything else:

    foreach(comp ${requiredComponents})
        _foo_handle_component(${comp})
    endforeach()

    # compatibility variables
    if (Foo_INCLUDE_DIRS)
        list(REMOVE_DUPLICATES Foo_INCLUDE_DIRS)
    endif()
    if (Foo_DEFINITIONS)
        list(REMOVE_DUPLICATES Foo_DEFINITIONS)
    endif()
    set(Foo_VERSION_STRING ${Foo_VERSION})

    find_package_handle_standard_args(Foo
        FOUND_VAR
            Foo_FOUND
        REQUIRED_VARS
            Foo_LIBRARIES
            Foo_INCLUDE_DIRS
        VERSION_VAR
            Foo_VERSION
        HANDLE_COMPONENTS
    )

    include(FeatureSummary)
    set_package_properties(Foo PROPERTIES
        URL http://www.foo.example.com/
        DESCRIPTION "A set of libraries for doing useful things")


Other Macros
------------

Some Find modules will wish to provide useful macros related to the package.
For example, the FindSharedMimeInfo module provides an `update_xdg_mimetypes`
macro.  The main thing to note is that you should probably make this a function,
rather than a macro, to avoid polluting the global namespace with temporary
variables.