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
orQt Linguist
internationalization (value can be:gettext
orqt
).
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>`