Compiling and installing OwlPS = Basics = To fully build OwlPS, you need 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 - //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. If you miss one or more of the requirements, the concerned modules will not be built, but the others can still be. OwlPS uses //CMake// as a build manager. You need to install it (package ``cmake`` on most distributions), and you should install ``ccmake`` as well 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 for instance (assuming OwlPS' source files are in ``~/owlps``): ``` mkdir ~/owlps-build cd ~/owlps-build cmake ~/owlps ``` 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. 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_DEBUG``: enable/disable debug code (some more tests and informational messages). - ``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 = The procedure is the same as on GNU/Linux systems, but keep in mind that OwlPS Listener is deactivated on BSD, since it still contains some Linux-specific code. (The positive effect is that you won't have to install libpcap, heh.) You may also 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``. 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``). To display all the available targets, type: ``` make help = 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 //boost-program_options//, //confuse// and //libiw//; - in the //Base system// menu, //libpthread//, //librt// and //libstdcpp// should now be automatically selected. == 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.)