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, use the ``test`` target: ``` make test 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 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.)