.. _cpp-tutos-using-qibuild:

Using qiBuild with Aldebaran packages
=====================================


Requirements
------------

Python 2.7 is the preferred version, but qiBuild should work fine on python
2.6, too. Note that to prepare a possible conversion to python3, python2.5 is
*not* supported.

CMake version 2.8.3 is the preferred version, but you should not have any
problem with CMake 2.6. On Windows and Mac, choose to add CMake to your ``PATH``.

On Windows, to use scripts written in Python, you have to put C:\Python2.x and
c:\Python2.x\Scripts in your ``PATH``.

On Mac and Linux, it is advised you use a recent version of ``QtCreator``


Installation
------------

Linux, mac
++++++++++

Simply run::

  ./install-qibuild.sh

And make sure ~/.local/bin is in your PATH

Windows
+++++++

Just run install-qibuild.bat::

  c:\path\to\qibuild> install-qibuild.bat


Creating a work tree
--------------------

First you need to chose a qibuild "worktree".

This path will be the root from where qiBuild searches to find the sources of
your projects.

In the following document, we will use the notation ``QI_WORK_TREE`` to refer
to this path.


Then go to this directory and run:

.. code-block:: console

  $ qibuild init --interactive


If you want, you can also create a worktree inside the SDK, so that you will
be able to easily compile all our examples.

to do so, simply run:

.. code-block:: console

   $ cd /path/to/sdk/doc/examples
   $ qibuild init --interactive

You will be asked to choose a ``CMake Generator``

**Warning:** Although qiBuild supports many platforms and configurations, only
a few ones are supported in the current C++ SDK:

* Unix Makefiles  (for Linux and Mac)
* Visual Studio 9 2008
* Visual Studio 10



Using qiBuild with the C++ SDK
------------------------------


Here you should tell ``qibuild`` to use a ``toolchain``.

Simply run:

.. code-block:: console

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

You can choose whatever name you want for the toolchain (for instance
'linux32' on linux)

This will tell ``qibuild`` that you have a new toolchain, and ``CMake``
will look for packages in the same directory the ``toolchain.xml`` resides.

If everything goes well, you should see:

.. code-block:: console

   $ qitoolchain create linux32 /path/to/cpp/sdk/toolchain.xml --default

   Now using toolchain linux32 by default

   $ qitoolchain status
   Toolchain linux32
      Packages:
        naoqi-sdk
          in /path/to/cpp/sdk


Now you can either:

* Create a new project form scratch, then configure and build it with:

.. code-block:: console

   $ qibuild create foo
   $ qibuild configure foo
   $ qibuild make foo


* Or, if you choose to create a worktree inside doc examples:

.. code-block:: console

  $ qibuild configure helloworld
  $ qibuild make helloworld



Note that a build directory has been created for you by qibuild,
in ``build-<name>``, where ``<name>`` is the name you pass to the
qitoolchain command.

On Unix and Mac, you can open the root ``CMakeLists`` with ``QtCreator``
and tell it to use the build folder created by qibuild.

On Windows, a ``.sln`` should have been generated for you in the build directory.


In any case, you can open the correct IDE by using

.. code-block:: console

   $ qibuild open <project_name>



Finally, note that on Unix, qibuild will build your project on debug, to build in
release, use

.. code-block:: console

   $ qibuild configure --release <project_name>
   $ qibuild make --release <project_name>


You will note that qibuild will use a **different** build directory.
(``build-<toolchain-name>-release``)




Using qiBuild with a cross-toolchain
------------------------------------

You just have to tell ``qibuild`` to use an other toolchain.

Simply run

.. code-block:: console

   $ qitoolchain create opennao-geode /path/to/geode-ctc/toolchain.xml

for instance.

You can now cross-compile by using

.. code-block:: console

   $ qibuild configure -c opennao-geode
   $ qibuild make -c opennao-geode

And of course, cross-compile in release is done with:



.. code-block:: console

   $ qibuild configure -c opennao-geode --release
   $ qibuild make -c opennao-geode --release


Going further
-------------


If you want to discover the full power of the ``qiBuild`` framework, you
can read more about it in the :ref:`qiBuild documentation <qibuild-documentation>`