qiBuild documentation

qibuild.xml configuration file syntax

General

There are two configuration files named qibuild.xml

The first one is in .config/qi/qibuild.xml.

It contains settings that will be shared across every worktree.

It is called the “global” configuration file.

The other is always found in the .qi directory at the root of a worktree

Note: the presence of the file is not necessary for qibuild to find a work tree, only the .qi directory is used.

Global configuration file

qibuild global node

The schema of the global xml file looks like this:

<qibuild version="1">
  <defaults>
    <env />
    <cmake />
  </defaults>
  <config name="config1">
    <env />
    <cmake />
  </config>

  <config name="config2">
    <env />
    <cmake />
  </config>

  <ide name="ide1">
  <ide name="ide2">
</qibuild>

Note the version attribute of the qibuild node. It will be used for backward compatibility in case the format changes.

It accepts:

defaults node

The defaults node accepts two kinds of children:

It also accepts a ide attribute, which should match the name attribute of a ide node.

env node

The env node accepts the following attributes:

  • path : A list of paths to be prepended to the PATH environment variable

  • bat_file: A .bat file that will be sourced to get new environment. This makes it possible to use cl.exe from the command line

  • editor : Used by qibuild config --edit

  • It also accepts a list of var children, like this:

    <env>
  <var name="NAME">VALUE</var>
</env>

cmake node

The cmake node accepts the following attributes:

  • generator The CMake generator to use

config node

The config node must contain a name attribute.

It accepts the same kinds of children as the defaults node does:

See Configuration merging to see how the configurations are merged

ide node

The ide node must contain a name attribute.

It accepts the following attributes:

  • path The full path to the IDE. Used by qibuild open

server node

The server node must contain a name attribute.

It accepts a child named access

The access child accepts the following attributes:

  • username
  • password
  • root : When using ftp, this will be the root directory of the ftp server.

For instance to use john username with password p4ssw0rd on ftp://example.com using root pub, you can use

 <server name="example.com">
   <access
    username="john"
    password="p4ssw0rd"
    root="pub"
   />
</server>

This is for instance used by qitoolchain in case you need a login/password to download packages and feeds.

This is also where qisrc stores your gerrit username.

Local Settings

The schema of the local xml file looks like this:

<qibuild version="1">
  <defaults />
  <build />
</qibuild>

Note the version attribute of the qibuild node. It will be used for backward compatibility in case the format syntax changes.

The root element accepts:

local defaults node

The local defaults node accepts the following attributes:

local build node

The local build nodes accepts the following attributes:

  • prefix : Instead of scattering build directories inside each project source directory, create them under the provided directory.

    This enables “out of worktree” builds, and is mandatory if you are using Eclipse CDT.

    For instance, given two projects “hello” and “world” and two build configurations “cross” and “linux”, the default layout would be:

    ~/src/hello/build-cross
~/src/hello/build-linux
~/src/world/build-cross
~/src/world/build-linux

    with prefix="/path/to/build.prefix", it becomes:

    /path/to/build.prefix/build-cross/hello
/path/to/build.prefix/build-cross/world
/path/to/build.prefix/build-linux/hello
/path/to/build.prefix/build-linux/world

Configuration merging

Using “-c” option

You may want to have several configurations for the same work tree, and for instance have a vs2010 and a mingw configuration.

In this case, the CMake generators will be different, so you will need to have something like

<qibuild version="1">
  <defaults>
    <cmake generator="Unix Makefiles" />
  </defaults>

  <config name="vs2010">
    <cmake generator="Visual Studio 10" />
  </config>

  <config name="mingw">
    <cmake generator = "MinGW Makefiles" />
  </config>
</qibuild>

Here are the generators that will be used depending on the configuration specified by the -c option of qibuild:

$ qibuild configure

Using cmake generator: Unix Makefiles
(from 'defaults' section)

$ qibuild configure -c vs2010

Using cmake generator: Visual Studio 10
(from 'vs2010' config)

$ qibuild config -c mingw

Using cmake generator: MinGW Makefiles
(from 'mingw' section)

A default configuration can be specified in the local defaults node if you do not want to have to specify -c for this worktree:

<qibuild version="1">
  <defaults config="vs2010" />
</qibuild>

Environment merging

You may want to use swig in several projects, so you need to have swig.exe in your path, but sometimes you use QtCreator with MinGW, so you need to have c:\QtSdk\Desktop\Qt\bin in your PATH too.

Here is what you could use:

<qibuild version="1">
  <defaults>
    <env path="c:\swig\bin" />
  </defaults>

  <config name="mingw" />
    <env path="C:\QtSDK\bin" />
  </config>

  <config name="vs2010" />
</qibuild>
  • When using -c mingw, %PATH% will look like: c:\swig\bin;C:\QtSDK\bin;...
  • When using -c vs2010, %PATH% will look like: c:\swig\bin;...
  • Other environment variables (set in <var> tags) are simply merged using the update method of Python dictionaries.