diff --git a/INSTALL.t2t b/INSTALL.t2t index a5ec166..015e5a0 100644 --- a/INSTALL.t2t +++ b/INSTALL.t2t @@ -3,50 +3,134 @@ 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. +To fully build OwlPS, you need a GNU/Linux system (see “Compiling on BSD +systems” below) with the following development libraries installed: -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. +- //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 -= Compiling = +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. -You can choose the compiler to use by setting the CC variable when -calling ``make``, for example: +If you miss one or more of the requirements, the concerned modules will +not be built, but the others can still be. - make CC=tcc +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). -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. +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``): -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. +``` + 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 = -Remember to use ``gmake`` instead of ``make``. From the top-level, you -will need to set the MAKE variable, for example: +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.) -``` gmake MAKE=gmake +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``: -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. +``` CXX="eg++ -fPIE" cmake ../owlps -You might also need to set some variables, for example CC to force a -specific GCC version to be used. +(``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 = @@ -74,21 +158,28 @@ In the configuration (``make menuconfig``), you have to: //libstdcpp// should now be automatically selected. -== Make options == +== OpenWrt-specific CMake options == -To compile for OpenWrt, you need to set the ``OPENWRT_VERSION`` variable -when calling make, for example: +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: -``` make OPENWRT_VERSION=12.09 +``` cmake -DCMAKE_TOOLCHAIN_FILE=~/owlps/cmake/Toolchains/OpenWrt.cmake ~/owlps -You can also specify OPENWRT_ROOT and OPENWRT_TARGET: +You can also specify the following variables (the same way, i.e. with +the ``-D`` option, cf. example below): -- OPENWRT_ROOT defines the path to the base directory in which the - OpenWrt stuff is (default: $HOME/openwrt). +- ``OPENWRT_ROOT``: the path to the base directory in which the OpenWrt + stuff is (default: ``/opt/openwrt``). -- OPENWRT_TARGET is the name of the OpenWrt target to build for - (default: atheros). +- ``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 @@ -98,49 +189,92 @@ 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-*`` +- ``target_uClibc`` pointing on + ``staging_dir/target-${OPENWRT_ARCH}_*_uClibc-*`` - ``toolchain_gcc_uClibc`` pointing on - ``staging_dir/toolchain-$ARCH_*_gcc-*_uClibc-*`` + ``staging_dir/toolchain-${OPENWRT_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 +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 == -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: +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: ``` - mkdir -p /opt/openwrt/ar71xx/trunk - cd /opt/openwrt/ar71xx/trunk - ln -s ../../trunk/staging_dir + 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 ``` -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. +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//. -= Installing = +== Compiling for OpenWrt == -At any level, you can install what is installable by typing, as -``root``: +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 install +``` ./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.)