Compiling and installing OwlPS


= Basics =

It is planned to use the ``autotools`` in a near future, but for now,
OwlPS uses a simple set of GNU makefiles to compile and install the
various modules. The top-level makefile will call ``make`` into the
subdirectories for all the modules.

At any level, you can type:

``` make help

to see the usable targets and requirements to compile.

Once you have all the requirements, the easy way is to just call
``make`` from the top-level directory, to build all the modules.


= Compiling =

You can choose the compiler to use by setting the CC variable when
calling ``make``, for example:

    make CC=tcc

By default, ``clang`` will be used for C modules, or ``colorgcc`` if
``clang`` is not installed. If neither ``clang`` or ``colorgcc`` is
installed, CC is left to the ``make`` default.

For OwlPS Positioner (C++), ``colorgcc`` is used, or the default CC if
it is not installed. Please keep in mind that this module requires GCC
4.4 or later.


= Compiling on BSD systems =

Remember to use ``gmake`` instead of ``make``. From the top-level, you
will need to set the MAKE variable, for example:

``` gmake MAKE=gmake

OwlPS Listener will not compile since it still contains some
Linux-specific code. You may want to comment-out the related lines of
the top-level makefile.

You might also need to set some variables, for example CC to force a
specific GCC version to be used.


= Compiling for OpenWrt =

== The OpenWrt toolchain ==

We strongly advise that you download the full OpenWrt source tree
instead of just the pre-compiled SDK, because it will allow you to
easily add the components needed by the OwlPS modules you want to build.
The OpenWrt documentation will help you with that:

- http://wiki.openwrt.org/doc/howto/buildroot.exigence
- http://wiki.openwrt.org/doc/howto/build


In the configuration (``make menuconfig``), you have to:

+ Choose the OpenWrt //Target System// (and possibly //Subtarget//).

+ Select the components needed to build (press the <space> key to have a
  //M// or a //*//). For example:
  - in the //Libraries// menu, select //boost-program_options//,
    //confuse// and //libiw//;
  - in the //Base system// menu, //libpthread//, //librt// and
    //libstdcpp// should now be automatically selected.


== Make options ==

To compile for OpenWrt, you need to set the ``OPENWRT_VERSION`` variable
when calling make, for example:

``` make OPENWRT_VERSION=12.09


You can also specify OPENWRT_ROOT and OPENWRT_TARGET:

- OPENWRT_ROOT defines the path to the base directory in which the
  OpenWrt stuff is (default: $HOME/openwrt).

- OPENWRT_TARGET is the name of the OpenWrt target to build for
  (default: atheros).


The toolchain is assumed to be under the
``$OPENWRT_ROOT/$OPENWRT_TARGET/$OPENWRT_VERSION`` directory.

For maintainability's sake, we don't handle changes of version of the
toolchain's tools, so you have to create symbolic links under this
directory (change the ``*`` with the relevant version numbers and all):

- ``target_uClibc`` pointing on ``staging_dir/target-$ARCH_*_uClibc-*``

- ``toolchain_gcc_uClibc`` pointing on
  ``staging_dir/toolchain-$ARCH_*_gcc-*_uClibc-*``


It might be easier to install your OpenWrt buildroot in a separate
directory, and just use symbolic links to point to the relevant
version (cf. example below).


== Example of OpenWrt set-up ==

We assume here that you want to build for the last OpenWrt development
version (//trunk//), for the //ar71xx// target, and that the OpenWrt
material is in the ``/opt/openwrt`` directory. You will compile with the
following command line:

``` make OPENWRT_VERSION=trunk OPENWRT_TARGET=ar71xx OPENWRT_ROOT=/opt/openwrt

We also assume your trunk OpenWrt source tree is in the
``/opt/openwrt/trunk`` directory. For this to work, you will first
create the ``/opt/openwrt/ar71xx/trunk`` directory, and link the
toolchain's directories from it. As of writing, the following commands
will do what you need:

```
    mkdir -p /opt/openwrt/ar71xx/trunk
    cd /opt/openwrt/ar71xx/trunk
    ln -s ../../trunk/staging_dir
    ln -s staging_dir/target-mips_r2_uClibc-0.9.33.2 target_uClibc
    ln -s staging_dir/toolchain-mips_r2_gcc-4.6-linaro_uClibc-0.9.33.2 \
      toolchain_gcc_uClibc
```

Of course, you will have to update the ``target_uClibc`` and
``toolchain_gcc_uClibc`` symbolic links from time to time, as the
tools' version numbers change in trunk.


= Installing =

At any level, you can install what is installable by typing, as
``root``:

``` make install