# qiBuild documentation

# qiproject.xml syntax

## General

The `qiproject.xml` file should always be at the top of a project registered in a worktree

It can optionally contains paths to subfolders, so that you can have nested projects.

    <project version="3" />
      <project src="subfolder" />
    </project>

This is the basis for every qiBuild tool. (Note that the `version=3` is not the project version, it’s just that the syntax was introduced in qibuild 3.0)

Each tool then parses the same file using its associated tags, ignoring the rest.

This helps having loosely coupled dependencies between the various tools.

The `qiproject`.xml` should contain the list of maintainers, like so

    <project version="3">
      <maintainer email="jdoe@company.com">John Doe</maintainer>
    </project>

If the project is no longer maintained, specify it like so:

    <project version="3">
      <maintainer>ORPHANED</maintainer>
    </project>

## qibuild

There can only be one qibuild project per source.

The `CMakeLists.txt` must be next to the `qiproject.xml`

The `qiproject.xml` must contain a `qibuild` element.

The `qibuild` element must contain a `name` attribute.

The name of the project must be unique in the worktree.

The list of dependencies is given as a white space separated name list in a `names` attribute (note the plural form).

The names can be other projects in the same work tree, or the name of packages in a toolchain.

The dependencies can be of four sorts:

- buildtime: a dependency that is required when using the package for compiling, used when installing the project and generating re-distributable packages
- runtime: a dependency that is required when running the executables of the package, used when installing the package.
- testtime: a dependency that is required for testing the package
- host: a dependency containing host tools. See Using host tools for cross compilation

You can mix them using the `buildtime="true"` and `runtime="true"` attributes:

For instance

    <project version="3" >
      <qibuild name="hello">
        <depends buildtime="true" runtime="true" names="foo bar" />
        <depends runtime="true" names="spam" />
        <depends host="true" names="eggs" />
      </qibuild>
    </project>

Here runtime dependencies are `foo,` `bar` and `spam`, and buildtime dependencies are just `foo` and `bar`. There is a host dependency on `eggs`.

## qilinguist

This is the configuration for adding translations to your source code. This configuration is used by `qilinguist` to generate translation files and install rules.

The file will look like:

    <project version="3" >
      <qilinguist name="hello" linguas="fr_FR en_US" tr="gettext" />
    </project>

Tags definitions:

- name: The name of the generated dictionary.
- linguas: A list of all locales supported.
- tr: Defined if you use `gettext` or `Qt Linguist` internationalization (value can be: `gettext` or `qt`).

## qipy

This is used to configure Python projects.

Assuming you have a layout looking like:

    foobarspam
      qiproject.xml
      lib
        bar.py
        foo
           __init__.py
      bin
        eggs

Here is what the `qiproject.xml` should look like:

    <project version="3">
      <qipython name="foobarspam">
        <module name="bar" src="lib" />
        <package name="foo" src="lib" />
        <script name="eggs" src="bin/eggs" />
      </qipython>
    </projct>

Note that you can also write a `setup.py` file. In this case, specify `<setup with_distutils="true">` in the `qiproject.xml`.

    <project  version="3">
      <qipython name="foobarspam">
        <setup with_distutils="true" />
      </qipython>
    </project>

## qidoc

This is used by `qidoc`

Doc projects can be of three type `sphinx`, `doxygen` or `template`.

Here is what the `qiproject.xml` looks like for each type.

    <project version="3">
      <!-- for sphinx projects -->
      <qidoc name="foo" type="sphinx" dest="lib/foo" />
      <!-- for doxygen projects -->
      <qidoc name="bar" type="doxygen" dest="lib/bar" />
      <!-- for template project -->
      <qidoc type="template"/>
    </project>

There should be zero or one `template` by worktree.

Names of `sphinx` and `doxygen` projects should be unique.

A project can have a list of dependencies, which is specified in a `depends` tag, like this:

    <qidoc type="sphinx" name="hello">
      <depends name="world" />
    </qidoc>

Doc projects can have a `dest` attribute. For instance, assuming that `world` is a dependency of `hello`, and you have the following `qiproject.xml` files:

    <!-- in hello/qiproject.xml -->
    <project version="3">
      <qidoc type="sphinx" name="hello">
        <depends name="world" />
      </qidoc>
    </project>

    <!-- in world/qiproject.xml -->
    <project version="3">
      <qidoc type="sphinx" name="world" dest="lib/world" />
    </project>

Then when building `hello` documentation, `world` documentation will be built, and put in a `lib/world` subfolder.

You can also specify a Python script to be run before building anything:

    <project version="3">
      <qidoc type="sphinx" name="hello">
        <prebuild script="gen_rst.py" />
      </qidoc>
    </project>

Lastly, you can specify examples for Sphinx projects. For each example, the `src` folder will be zipped and made available as a `..download` directive:

    hello
      index.rst
      samples
        foo
          foo.cpp
          CMakeLists.txt
        bar
          bar.py
          setup.py

    <project version="3">
      <qidoc type="sphinx" name="hello">
        <examples>
          <example src="samples/foo" />
          <example src="samples/bar" />
        </examples>
      </qidoc>

    .. In index.rst

    Download the full sources of the ``foo`` example:
    :download:`foo.zip <../foo.zip>`

Changelog CMake index Python index Index