# qiBuild documentation

# Using qi_install functions

`qi_install` functions are simply wrappers for `install` upstream CMake functions.

Here are a few concepts you need to understand to properly use `qi_install` functions

## Components

The various qi_install_* function deals with the components and respect the SDK layout for you.

There are 3 sort of dependencies in qibuild, which match 3 install components:

- `build`: the dependencies required to build the software. (headers, statics libraries, CMake files). You will need that if you want to generate a package containing a pre-compiled library for other people to link with, for instance.
- `runtime`: the dependencies required to run the software. (executable, dynamic libraries, data, config files)
- `test` : the dependencies required to test the software (the gtest library, some test executables, ...)

## Using `qibuild install`

By default `qibuild install <project> <destination>` install the `build` and `runtime` components.

If you want to install the `test` component too, use `qibuild install --with-tests`.

If you only want the `runtime` component, use `qibuild install --runtime`.

Note that by default `CMAKE_INSTALL_PREFIX` is set to `/`.

To install directly to `/usr/local` do:

    sudo qibuild install --prefix /usr/local /

## Install functions, destination, components

Note that the `qi_create_*` and the `qi_stage_lib` functions create correct install rules for you by default.

function | component | destination
--- | --- | ---
qi_create_bin | runtime | bin/
qi_create_lib(SHARED) | runtime | lib/ on UNIX, bin/ on windows
qi_install_conf | runtime | etc/
qi_install_data | runtime | share/
qi_create_lib(STATIC) | build | lib/
qi_stage_lib(foo) | build | share/cmake/modules/foo/foo-config.cmake
qi_install_header | build | include/
qi_create_test_helper | test | bin/

## Other use cases

If you don’t want the executable to be installed (because it’s just used at build time, for instance), you can use:

    qi_create_bin(foo NO_INSTALL)

If you want to install an executable that is NOT the result of a compilation (for instance a script), you can use `qi_install_program`

If you want to install something in your development install that does not fit in these destinations (say, an example), you can use the generic `qi_install` function with `DESTINATION` and `COMPONENT` arguments.

## Special features

`qi_install` ends up calling regular install() CMake functions, but there are some differences, here are a few

### Check of arguments

If you try to install a file that does not exist, using install() will exit during installation, but qi_install will exit during configuration. This does no prevent you from installing generated files, but you have to make sure the are generated before creating the install rule.

    # Always generate files in cmake build dir:
    set(_out ${CMAKE_CURRENT_BINARY_DIR}/foobar)
    configure_file(foobar.in "${_out}")
    qi_install("${_out}"
      DESTINATION /etc/init.d/
      )

    # Note the trailing "/" at the end of the DESTINATION argument.

    # Do NOT use:
    qi_install("${_out}"
      DESTINATION /etc/init.d/foobar
      )

    # or you'll end up with /etc/init.d/foobar/foobar ...

### Support of glob and directories

Please not that on top of this, you can use directories, globbing expressions and list of files as arguments on all qi_install_* functions.

For instance

    qi_install(foo/bar/ *.txt spam.cfg eggs.cfg DESTINATION "prefix")

will install:

- directory foo/bar to “prefix/bar”
- every .txt file in current directory to “prefix”
- the spam and eggs cfg file to “prefix”

Note the glob is not recursive by default.

If you really need it, just use:

    qi_install(foo/*.hpp RECURSE)

### “IF” keyword

Instead of using

    if(FOO)
      qi_install(.... )
    endif()

you can use

    qi_install(.... IF FOO)

### SUBFOLDER and KEEP_RELATIVE_PATHS keywords

`qi_install` functions accept either a `SUBFOLDER` or a `KEEP_RELATIVE_PATHS` keyword.

It is easier to understand the meaning of these keywords by an example.

#### Using SUBFOLDER

You should use this for instance with headers in several different folders (a bit like an autotools project):

    sources:                      destination
      foo                          include
      |__ include                  |__ foo
          |__ foo.h                       |__ foo.h
          |__ bar.h                       |__ bar.h
      config.h (generated)                |__ config.h

    qi_install_header(foo/include/foo.h
                      foo/include/bar.h
                      ${CMAKE_BUILD_DIR}/config.h
                      SUBFOLDER foo)

`qi_install_header` will set DESTINATION “include” for you, but you need ‘SUBFOLDER foo’ argument to tell CMake to install files to include/foo, regardless their original path.

#### Using KEEP_RELATIVE_PATHS

You should you this for instance with headers following the exact same hierarchy in the source tree and when installed (a bit like boost):

    sources                         destination
      libfoo                        include
      |__ foo                       |__ foo
          |__ foo.h                     |__ foo.h
          bar                           bar
          |__ bar.h                     |__ bar.h
              baz                           baz
              |__ baz.h                     |__ baz.h

    qi_install_header(foo/foo.h
                      bar/bar.h
                      bar/baz/baz.h
                      KEEP_RELATIVE_PATHS)

`qi_install_header` will set DESTINATION “include” for you, and you do not need `SUBFOLDER` because `KEEP_RELATIVE_PATHS` is set.

Changelog CMake index Python index Index