# qiBuild documentation

# Writing a custom -config.cmake module file

Let use assume you want to use the `foo` library, and no `FindFoo.cmake` for `foo-config.cmake` exist.

(Because it is not known enough to be in standard CMake modules, or because the `foo` project does not use CMake as a build system, or for whatever reason)

In any case, if you do have access to a `foo-config.cmake` of a `FindFoo.cmake`, please just use it!

Note that `qi_use_lib(foo)` does not need a specific `foo-config.cmake` to work.

It is only necessary that the `foo-config.cmake` code exports `FOO_INCLUDE_DIRS` and `FOO_LIBRARIES`.

## Simplest case

Here we assume that the `foo` library only needs an include directory, and the name of the library is the same in debug and in release.

The canonical `foo-config.cmake` should look like

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

Here we assume that the library is named `foo.lib` for Visual Studio, `libfoo.a` or `libfoo.so` for Linux, or `libfoo.a` or `libfoo.dylib` for Mac.

We also assume that the library is in a /lib directory and the header in a include directory, and from a prefix where CMake can find it, either because:

- foo is in a package in a toolchain following the sdk layout
- foo is installed on the system, so the prefix is `/usr/` or `/usr/local`.

This should cover 90% of the use cases.

If the `foo` library is open source, do not hesitate to submit a patch to integrate `foo-config.cmake` with other qibuild cmake modules.

If not, you can simply add `foo-config.cmake` inside your project, for instance in `src/bar/cmake/modules/foo-config.cmake`, and modify `src/bar/CMakeLists.txt` too look like:

    cmake_minimum_required(VERSION 2.8)
    project(bar)
    find_package(qibuild)

    list(APPEND CMAKE_FIND_ROOT_PATH
     ${CMAKE_SOURCE_DIR}/cmake/modules)

    qi_create_bin(bar bar.cpp)
    qi_use_lib(bar foo)

## Finding libraries with different names

You could have to handle the case where the library is named `libfoo-1.2` on linux

In this case, simply add some calls to `flib`

    flib(FOO foo)
    if (UNIX)
      flib(FOO foo-1.12)
    endif()

If the `foo` library depends on other libraries, for instance `foo-base`, `foo-client` , `foo-server`, you can use

    flib(FOO foo foo-base foo-client foo-server)

Note: here we assume that `libfoo.so`, `libfoo-base.so`, `libfoo-client.so` and `libfoo-server.so` are part of the same package.

If `foo` depends on an library from an other package (say `spam`), you should write a `spam-config.cmake` and use something like

    clean(FOO)
    # calling flib, fpath as usual
    qi_persistent_set(FOO_DEPENDS spam)
    export_lib(FOO)

## Finding include directories with prefixes

Assuming `foo.h` is in `/usr/local/include/foo/foo.h`, you can use either:

    fpath(FOO foo/foo.h)

In this case, `FOO_INCLUDE_DIRS` will equal `/usr/local/include`, so you will have to use

    #include <foo/foo.h>

Or you can use:

    fpath(FOO foo.h PATH_SUFFIXES foo)

In this case, `FOO_INCLUDE_DIRS` will equal `usr/local/include/foo`, so you will have to use

    #include <foo.h>

## Headers-only libraries

Some libraries are only made of headers! Let’s assume this is the case for foo.

What you have to do here is:

    fpath(FOO foo/foo.h)
    export_header(FOO)

In a nutshell:

- No `flib` needed.
- `export_header` instead of `export_lib`

## Finding in non standards paths

Sometimes want you want to find is not under a standard location, such as `/usr/local/include` or `/usr/include`.

So, for instance let’s assume the foo library is in `/opt/bar/lib/libfoo.so` and the header in `/opt/bar/include/foo/foo.h`

All you have to do is to specify PATHS as you would do if you used the normal `find_path` CMake method.

So in our case

    fpath(FOO foo/foo.h PATHS /opt/bar/include)
    flib(FOO NAMES foo PATHS /opt/bar/lib)

## Finding pkg-config libraries

If the `foo` library comes with a `foo-1.0.pc` file, you should use the `PkgConfig` module from CMake, like this

    clean(FOO)
    find_package(PkgConfig)
    pkg_check_modules(FOO foo-1.0)
    export_lib_pkgconfig(FOO)

Changelog CMake index Python index Index