.. Generated by qibuild/doc/tools/gen_cmake_doc.py
.. DO NOT EDIT

.. highlight:: cmake

Functions to find libaries and include directories
====================================================

The qibuild CMake framework contains several ``-config.cmake`` files
when upstream ``Find-.cmake`` files are not correct or missing.


For instance, the canonical ``FindFoo.cmake`` looks like::

  include(FindPackageHandleStandardArgs.cmake)

  find_path(FOO_INCLUDE_DIR foo/foo.h)
  find_library(FOO_LIBRARY foo)

  find_package_handle_standard_args(FOO
   DEFAULT_MSG
    FOO_INCLUDE_DIR
    FOO_LIBRARY
  )

  mark_as_advanced(FOO_LIBRARY FOO_INCLUDE_DIR)

  if(FOO_FOUND)
    set(FOO_LIBRARIES    ${FOO_LIBRARY})
    set(FOO_INCLUDE_DIRS ${FOO_INCLUDE_DIR})
  endif()

There is a lot of boilerplate code here, and it's not easy
to know the names of the variables (is it ``FOO_INCLUDE_DIR`` or ``FOO_INCLUDE_DIRS`` ?)

For qibuild, we use the concept of ``PREFIX`` and exported variables will always
be ``${${PREFIX}_INCLUDE_DIRS}`` and ``${${PREFIX}_LIBRARIES}``

Thus, ``foo-config.cmake`` can simply be rewritten as::

  clean(FOO)
  fpath(FOO foo/foo.h)
  flib(FOO  foo)
  export(FOO)

Note that the exported variables will always be
all upper-case, will contain no version number and will have
the plural form.

 * ``FOO_INCLUDE_DIRS``
 * ``FOO_LIBRARIES``

Also note that ``FOO_LIBRARIES`` will equal either::

 "general;/path/to/foo.so"

if ``flib()`` was called with no specific argument
or::

 "debug;/path/to/foo_d.lib;optimized;/path/to/foo.lib"

if both ``flib(FOO OPTIMIZED ...)`` and ``flib(FOO DEBUG ...)``
have been called.

So this variable can be used directly in the ``target_link_libraries()`` call

.. seealso:
 :ref:`writing-a-config-cmake` section for a detailed tutorial on how to write a ``-config.cmake`` file.



.. _clean:

clean
-----

.. cmake:function:: clean(prefix)

    :arg prefix: The prefix of the variables to clean

    
    Cleanup variables related to a library/executable/source-only library
    Use this at the start of the ``${prefix}-config.cmake`` file
    



.. _fpath:

fpath
-----

.. cmake:function:: fpath(prefix path [<remaining args> ...])

    :arg prefix: The prefix of the exported variables. Must match the argument of ``clean()`` and ``export_lib()`` (or ``export_header`` for a header-only library) calls.
    :arg path: The path of one of the headers inside the include directory.
    :arg remaining args: The remaining arguments will be passed to ``find_path`` 

    
    Search for an include directory
    
    A small example, assuming ``/usr/local/include/foo/foo.h``
    exists.
    
    If you use::
    
      fpath(FOO foo/foo.h)
    
    ``FOO_INCLUDE_DIRS`` will equal ``/usr/local/include``, so you will
    have to use
    
    .. code-block:: cpp
    
       #include <foo/foo.h>
    
    Whereas if you use ::
    
      fpath(FOO foo.h PATH_SUFFIXES foo)
    
    ``FOO_INCLUDE_DIRS`` will equal ``usr/local/include/foo``, so you
    will have to use
    
    .. code-block:: cpp
    
       #include <foo.h>
    
    



.. _flib:

flib
----

.. cmake:function:: flib(prefix name [DEBUG] [OPTIMIZED] [<remaining args> ...])

    :arg prefix: The prefix of the exported variables. Must match the argument of ``clean()`` and ``export()`` calls.
    :arg name: The name of the library
    :arg DEBUG: find a library that will be used for a debug build
    :arg OPTIMIZED: find a library that will be used for an optimized build
    :arg remaining args: The remaining arguments will be passed to ``find_library`` 

    
    Search for a library
    
    Note: if the library has a different name in debug and in release,
    you should use::
    
      flib(foo DEBUG     foo_d)
      flib(foo OPTIMIZED foo)
    



.. _fprogram:

fprogram
--------

.. cmake:function:: fprogram(prefix)

    :arg prefix: Prefix of the variables to export. Must match the calls to ``clean()`` and ``export_bin()`` calls.

    
    Search for an executable
    



.. _export_lib:

export_lib
----------

.. cmake:function:: export_lib(prefix)

    :arg prefix: The prefix of the exported variables

    
    Export the variables related to a library
    
    Use this at the end of the ``${prefix}-config.cmake``
    ``find_package_handle_standard_args`` will be called to make
    sure ``${prefix}_LIBRARIES`` and ``${prefix}_INCLUDE_DIRS`` have
    been found.
    



.. _export_lib_pkgconfig:

export_lib_pkgconfig
--------------------

.. cmake:function:: export_lib_pkgconfig()


    
    Helper function to use with pkgconfig.
    
    Usage, assuming ``foo-1.0.pc`` is somewhere
    in ``PKG_CONFIG_PATH`` ::
    
      clean(FOO)
      find_package(PkgConfig)
      pkg_check_modules(FOO foo-1.0)
      export_lib_pkgconfig(FOO)
    



.. _export_bin:

export_bin
----------

.. cmake:function:: export_bin(prefix)

    :arg prefix: The prefix of the variables to export 

    
    Export the variables related to an executable
    
    Use at the end of ``foo-config.cmake`` ::
    
      fprogram(FOO RELEASE foo)
      fprogram(FOO OPTIMIZED foo_d)
      export_bin(FOO)
    
    Here, ``FOO_EXECUTABLE`` will be set to
    '/path/to/foo.exe', and ``FOO_EXECUTABLE_DEBUG``
    to 'path/to/foo_d.exe'
    



.. _export_header:

export_header
-------------

.. cmake:function:: export_header(prefix)

    :arg prefix: The prefix of the variables to export 

    
    Export the variables related to an header-only
    library
    
    Use at the end of ``foo-config.cmake`` ::
    
      clean(FOO)
      fpath(FOO foo/foo.h)
      export_header(FOO)