owlps/INSTALL.t2t

Compiling and installing OwlPS


= Basics =

The preferred platform to build and run OwlPS is a GNU/Linux system (see
“Compiling on BSD systems” below) with the following development
libraries installed:

- //confuse//
- //pcap//
- the //Boost// C++ libraries, and particularly the ``program_options``
  module
- the //Tween// module of the //Claw// C++ library
- //iwlib// from the Wireless Tools (package``libiw-dev`` on Debian,
  ``wireless-tools-devel`` on Fedora); only for OwlPS Listener's ``-K``
  option


You also need support for POSIX threads, which should be provided by
default by your system in most cases, and the GCC C++ compiler (g++)
version 4.7 or above; the Clang C++ compiler (clang++) version 3.2 or
above should also work. Compilation of the C modules has been tested
with GCC and Clang and should work with older versions of these
compilers.

The following additional tools are recommended:
- ``perl``
- ``pod2man`` (normally provided in the same package as //Perl//)
- ``doxygen``
- ``txt2tags``


If you're missing one or more of the requirements, all the modules will
not be built.

OwlPS uses //CMake// as a build manager. You need to install it (package
``cmake`` on most distributions) as well as the ``make`` tool if not
readily available on your system. You should also install ``ccmake`` if
it is not shipped with the main CMake package (package
``cmake-curses-gui`` on Debian).

It is strongly advised to build out of the source tree, which can be
achieved by typing the following commands from the source tree:

```
    mkdir build
    cd build
    cmake ..
```

CMake will generate a set of Makefiles, and display warnings if
dependencies are missing. After installing a missing dependency, you can
type ``make rebuild_cache`` (assuming CMake did generate the Makefiles
successfully), or re-run ``cmake``.

Once you have all the required libraries installed, the easy way is to
just call ``make`` to build all the modules. The built executables and
libraries will be put in the ``bin`` and ``lib`` directories under the
build directory's root; the manual pages will be generated in the
``man`` directory.

You can then type ``make install`` to install everything (the default is
to install to ``/usr/local``, so you will need to type this as root).


== Tweaking ==

To set the options (compiler, compilation flags, compilation-time
options, installation prefix, etc.), after first running ``cmake``,
assuming everything went well and CMake generated the Makefiles, you
can type:

``` make edit_cache

Or, if ``ccmake`` is not available, use the interactive mode when you
first invoke CMake (``cmake -i``).

Setting a compiler using these methods sometimes doesn't work; in this
case, you can set the CC and/or CXX variables prior to run cmake, for
example (from an empty directory):

``` CC=clang CXX=/usr/pkg/gcc47/bin/g++ cmake ~/owlps


== Compilation-time options ==

Here are the OwlPS-specific switches you can change in the CMake
configuration as explained in the previous section.

- ``OWLPS_CLIENT_RECEIVES_POSITION``: enable/disable OwlPS Client's
  ``-l`` option (which enables receiving the computed position from the
  Positioner).

- ``OWLPS_LISTENER_KEEPS_MONITOR``: enable/disable OwlPS Listener's
  ``-K`` option (which forces the Wi-Fi interface to stay in monitor
  mode).

- ``OWLPS_LISTENER_USES_CONFIG_FILE``: enable/disable reading the
  configuration from a file in OwlPS Listener.

- ``OWLPS_LISTENER_USES_PTHREAD``: enable/disable use of POSIX threads
  in OwlPS Listener; this is required for the autocalibration and also
  if ``OWLPS_LISTENER_KEEPS_MONITOR`` is set.


= Compiling on BSD systems =

We try to write portable code and support BSD systems as much as
possible, but OwlPS is primarily developed and tested on GNU/Linux so
there can be more bugs on BSD (please report them!).

The building procedure is the same as on GNU/Linux systems, but you may
need to edit the configuration (cf. “Tweaking” above), for example to
force a specific GCC version to be used. On OpenBSD, you need to have
the CXX variable set with the ``-fPIE`` flag when calling ``cmake``:

``` CXX="eg++ -fPIE" cmake ../owlps

(``eg++`` is the name of the executable from the package ``g++``, the
``g++`` executable name being reserved for the OpenBSD base system's
C++ compiler.)


= Static compilation =

It is possible to build static executables by calling the target's name
followed by ``.static``. For exemple, to compile a static version of
OwlPS Client, just type ``make owlps-client.static``. If you want to
generate static executables for all the modules, call the ``static``
meta-target (``make static``).

So-called “semistatic” targets are also provided. The semistatic
executables are statically linked to OwlPS libraries (such as libowlps),
but dynamically linked to other libraries. This allows for quick testing
of libraries changes as well as running on systems where you can install
packages but where installation and maintenance of custom shared
libraries is not convenient. To build semistatic executables, use
the regular target's name followed by ``.semistatic`` (for example
``make owlps-client.semistatic``); a ``semistatic`` meta-target is also
provided to generate semistatic executables for all the modules (``make
semistatic``)

To display all the available targets, type:

``` make help


= Running the tests =

To run the unit tests, you will need to install ``cxxtest``. Then use
the ``tests`` target from your build directory:

``` make tests

Currently, only OwlPS Positioner has (partial) unit tests.


= 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 //confuse// and //libiw//;
  - in the //Base system// menu, select //libpthread// and //librt// if
    they were not automatically selected (the latter is only needed for
    OwlPS Positioner).


Note that at the moment, //libclaw_tween// is not provided by the
OpenWrt Buildroot, so if you want to compile OwlPS Positioner you will
need to add it yourself. You will also need to select
//boost-program_options// from the //Libraries// menu, then make sure
//libstdcpp// is selected in the //Base system// menu.


== OpenWrt-specific CMake options ==

To compile for OpenWrt, you need to set the ``CMAKE_TOOLCHAIN_FILE``
CMake variable, using the ``-D`` option, to include the OpenWrt platform
file provided with the OwlPS distribution:

``` cmake -DCMAKE_TOOLCHAIN_FILE=~/owlps/cmake/Toolchains/OpenWrt.cmake ~/owlps


You can also specify the following variables (the same way, i.e. with
the ``-D`` option, cf. example below):

- ``OPENWRT_ROOT``: the path to the base directory in which the OpenWrt
  stuff is (default: ``/opt/openwrt``).

- ``OPENWRT_VERSION``: the version of the OpenWrt Buildroot to use
  (default: ``trunk``).

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

- ``OPENWRT_ARCH``: the target's architecture (default: ``mips``).


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-${OPENWRT_ARCH}_*_uClibc-*``

- ``toolchain_gcc_uClibc`` pointing on
  ``staging_dir/toolchain-${OPENWRT_ARCH}_*_gcc-*_uClibc-*``


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

For more information about cross-compiling with CMake, please visit
http://www.cmake.org/Wiki/CMake_Cross_Compiling


== Example of OpenWrt set-up ==

In this example, we assume that you want to build for OpenWrt //Attitude
Adjustment// (12.09), for the //ar71xx// target, and that the OpenWrt
material is in the ``/opt/openwrt`` directory. You will launch CMake
with a command line such as the following:

```
    cmake -DCMAKE_TOOLCHAIN_FILE=~/owlps/cmake/Toolchains/OpenWrt.cmake \
      -DOPENWRT_TARGET=ar71xx -DOPENWRT_VERSION=12.09 ~/owlps
```

Note that you don't need to use ``-DOPENWRT_ROOT`` because its default
value is already ``/opt/openwrt``. Similarly, you don't have to use
``-DOPENWRT_ARCH``, because its default value is ``mips`` and
//ar71xx// is a MIPS target.

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

```
    mkdir -p /opt/openwrt/ar71xx/12.09
    cd /opt/openwrt/ar71xx/12.09
    ln -s ../../attitude_adjustment/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
```

Please keep in mind that the tools' version numbers evolve as the
OpenWrt project is moving forward, so you will have to update the
``target_uClibc`` and ``toolchain_gcc_uClibc`` symbolic links from time
to time, especially if you're using //trunk//.


== Compiling for OpenWrt ==

The OpenWrt cross-compiler needs to have the ``STAGING_DIR`` variable
defined in its environment; unfortunately, CMake (as of version 2.8) is
unable to export environment variables when building targets. To save
you the effort of setting manually this variable in your environment,
the OpenWrt toolchain file provided generates a script called
``make.sh`` that you can use instead of ``make`` when compiling. After
calling CMake like explained above, type:

``` ./make.sh

Note that you can call this script with arguments just like you would do
with ``make``. For non-building operation, you can also use ``make``
directly (``make help``, ``make rebuild_cache``, ``make edit_cache``,
``make clean``, etc.).


== Installing on OpenWrt ==

To install the OwlPS programs on an OpenWrt box, we suggest building
static or semistatic executables (cf. “Static compilation” above); this
will save you the trouble of installing the OwlPS libraries and ease the
updates. The downside is that you will lose some storage space if you're
using more than one module (for example if you install both OwlPS
Listener and OwlPS Client, the code of libowlps and libowlps-client will
be duplicated in the two executables).

The best compromise is to use semistatic executables, that are very much
lighter than static ones, and to install the external dependencies from
the packages:

``` opkg install libpthread librt libpcap

(Install also ``confuse`` if you enabled support for configuration
files, and ``libiw`` if you enabled the ``-K`` option.)