# qiBuild documentation

# qiBuild CMake framework design

## General design decisions

qiBuild CMake framework is designed around a few principles:

- Staying close to the standards
- Trying to follow CMake best practices (from CMake wiki or in /usr/share/cmake-2.8/Modules/readme.txt)
- Do not get into the developer’s way
- Play nice with other build frameworks:
  - Every custom CMake function is prefixed with `qi_`
  - Every custom CMake files is in a `qibuild` subdirectory
  - Generated CMake code is always pure, standard CMake code
  - Absolutely NO environment variable is required, except for `PATH` and `PYTHONPATH`

## qiBuild CMake Concepts

SDK
  A directory containing files used to compile other code. A SDK always has a layout, following POSIX and cmake conventions.

Here is an example of a SDK containing the `bar` executable, a `bar.cfg` configuration file for `bar,` a `foo` library with the `foo-config.cmake` file, and the `foo.h` header:

      <sdk>
      |__ include
          |__ foo
               |__ foo.h
      |__ lib
          |__  libfoo.a
          |__  libfoo.a
          |__  foo.lib
      |__ bin
          |__ bar
          |__ foo.dll
          |__ bar.exe
      |__ cmake
          |__ foo
              |__ foo-config.cmake
      |__ etc
             |__ bar
                 |__ bar.cfg

    The root of a SDK can safely be added to ``CMAKE_FIND_ROOT_PATH``
    variable.

package

  A package is simply an archive containing the one or several SDKs. If always has a `.tar.gz` extension on UNIX, and a `.zip` extension on windows.

  All files are in the same top dir, so it is safe to extract it everywhere.

  Some packages may also need a toolchain file.

toolchain file
  Usually, your are supposed to use a toolchain file when cross-compiling with CMake, with the `CMAKE_TOOLCHAIN_FILE` variable.

For qiBuild, we extend the usage of the toolchain file a little bit.

In a toolchain file, you may:

- Force a compiler (which is the main purpose of a toolchain file)
- Set some CMake flags (for instance CMAKE_OSX_ARCHITECTURES)
- Or set some CMake variables like CMAKE_FIND_ROOT_PATH

A package can be associated to a toolchain file.

For instance, you may have a simple package `foobar` containing the result of the installation of the `bar` executable and the `foo libaray`, requiring no toolchain file at all, or a complex package name `geode-ctc` containing some libs in `ctc/sysroot/usr/lib`, and a cross-compiler in `ctc/cross`, and a toolchain file forcing the compiler to be `ctc/cross/bin/gcc`, and setting CMAKE_FIND_ROOT_PATH to `ctc/sysroot`.

toolchain
  A toolchain is simply a collection of packages
feed
  A feed is a simple XML file describing a toolchain: its location, and the packages that are in it.

## Overviews

You can read the following sections if you want to understand deeply how qibuild works, under the hood.

- Managing dependencies with qiBuild: an overview
- Search order
- Managing shared libraries

Changelog CMake index Python index Index