# qiBuild documentation

# Using toolchains

In this tutorial, you will learn how to build your projects using pre-compiled packages.

## Using Aldebaran toolchains

Aldebaran C++ SDKs and cross-toolchains are, by definition, toolchains.

Using them is done with

    $ qitoolchain create <name> /path/to/toolchain.xml

See also

Using qibuild with Aldebaran C++ SDKs

## Adding packages to a toolchain

### Requirements

The requirements for this tutorial are the same as in the Managing dependencies between projects tutorial.

You should have:

- a properly configured qiBuild worktree
- two projects, world and hello, with hello depending on the world library.

You can find these two projects here `helloworld.zip`

The goal of this tutorial is to manage to compile `hello`, using a pre-compiled binary of `world`.

### Creating the world package

Generating a package for the `world` project is done with:

    $ qibuild package world

This will create a package named `world.tar.gz` in `QI_WORK_TREE/package/world.tar.gz` (or `world.tar.gz` on windows)

Inside the package, you will have:

    include
      |__ world
          |__ world.hpp
    lib
          |__ libworld.so
    share
       cmake
          |__ world-config.cmake
    package.xml

Note

The archive generated by qibuild does not contain a top directory, so be careful if you extract the archive by hand. Use `qitoolchain extract-package` to put the extracted files in a properly named directory

The LFS hierarchy is still preserved, and it is the same as in `build/sdk`.

The `world-config.cmake` is a standard CMake file, but it can be used even after installing the world package, because it only uses relative paths.

So the world package is usable anywhere.

Note

The world-config.cmake does not even requires qibuild to be used by an other CMake project, all it does is calling standard CMake functions.

### Create a toolchain from scratch

If you are already using a Aldebaran toolchain, you can skip this section.

Otherwise, you have to create a toolchain from scratch for qibuild to use:

    $ qitoolchain create <TOOLCHAIN_NAME>

You are free to choose any name for your toolchain, but it is advised to pick one from this set of configurations:

- linux32
- linux64
- mac32
- mac64
- win32-vs2008
- win32-vs2010
- mingw

Here we will assume you chose `linux32`.

This will create a directory looking like: `~/.local/share/qi/toolchains/linux32/` where every packages will be put.

You can check that your toolchain has been created with:

    $ qitoolchain info

    Toolchain linux32
    No feed
    No packages

### Adding the world package to the toolchain

Now you can use:

    $ qitoolchain add-package -c linux32 /path/to/worktree/package/world.tar.gz

You can check that your package has been added with:

    $ qitoolchain info

    Toolchain linux32
    No feed
      Packages:
        world
          in /home/user/.local/share/qi/toolchains/linux32/world

This will simply:

- copy the `world` package somewhere in you toolchain directory.
- configure some files so that qibuild knows that the `linux32` toolchain can provide the `world` package

When resolving dependencies of the `hello` project, qibuild will see that you use a toolchain called `linux32` and that this toolchain provides the `world` project, so it’s enough to set `CMAKE_MODULE_PATHS` to `path/to/linux/toolchain/world`

The next step is to create a build config that matches the toolchain for qibuild to use:

    qibuild add-config linux32 --toolchain linux32

You can now remove the project `world` from your worktree, and configure `hello` using the `linux32` build config:

    qisrc remove world
    qibuild configure -c linux32 hello

## Creating toolchain feeds

Now, that you have a nice local toolchain, and a `world` package, you may want other people to be able to use the `world` package, without them having to recompile it from source.

So here we are going to create a remote configuration file, so that other developers can simply download the `world` package from a server.

We will assume you have access to a FTP or a HTTP sever.

First, upload the world package, so that is accessible with the url: `http://example.com/packages/world.tar.gz`

Next, create a `feed.xml` accessible with the url: `http://example.com/feed.xml`, looking like

    <toolchain>

      <package
        name="world"
        url = "http://example.com/packages/world.tar.gz"
      />

    </toolchain>

Then, from an other machine, run

    $ qitoolchain create linux32 http://example.com/feed.xml

    Getting package world from http://example.com/packages/world.tar.gz
    Toolchain linux32: adding package world

You can see that the feed has been stored in your qibuild configuration:

    $ qitoolchain info

    Toolchain linux32
    Using feed from http://example.com/feed.xml
      Packages:
        foo
          in /home/user/.local/share/qi/toolchains/linux32/world

Note: if you HTTP or FTP server is protected by a password, you can put the username and password in the `.config/qi/qibuild.xml` configuration file.

See the section qibuild.xml configuration file syntax for details.

You can also add the Aldebaran C++ SDKs or cross toolchains as if they were packages. (This sound a bit weird, but it works)

For instance, assuming you were using the atom cross-toolchain and cross-compiled the world package, you can create a feed looking like

     <toolchain>
      <package name="atom-ctc"  url="http://example.com/packages/aldebaran-ctc.tar.gz"
        toolchain_file="cross-config.cmake" />

      <package name="hello"  url="http://example.com/packages/world.tar.gz" />
    </toolchain>

Don’t forget the `toolchain_file` attribute of the `atom-ctc` package, though.

## Full feed.xml specification

The full specification can be found in the Toolchain feed syntax section

## Just for fun

You can always add something like

    <?xml version="1.0" encoding="utf-8"?>
    <?xml-stylesheet type="text/xsl" href="../xsl/toolchain.xsl"?>

With an xsl looking like

    <html xsl:version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml">
      <body >
        <h2> Packages </h2>
        <ul>
          <xsl:for-each select="toolchain/package">
          <li>
            <a>
            <xsl:attribute name="href">
              <xsl:value-of select="@url" />
            </xsl:attribute>
            <xsl:value-of select="@name" />
            </a>
          </li>
          </xsl:for-each>
        </ul>
        <h2> Feeds </h2>
        <ul>
          <xsl:for-each select="toolchain/feed">
          <li>
            <a>
            <xsl:attribute name="href">
              <xsl:value-of select="@url" />
            </xsl:attribute>
            <xsl:value-of select="@url" />
            </a>
          </li>
          </xsl:for-each>
        </ul>
      </body>
    </html>

Changelog CMake index Python index Index