Owl Positioning System: a Wi-Fi-based, infrastructure-centred indoor positioning system. http://owlps.pu-pm.univ-fcomte.fr/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

311 lines
11 KiB

  1. Compiling and installing OwlPS
  2. = Basics =
  3. The preferred platform to build and run OwlPS is a GNU/Linux system (see
  4. “Compiling on BSD systems” below) with the following development
  5. libraries installed:
  6. - //confuse//
  7. - //pcap//
  8. - the //Boost// C++ libraries, and particularly the ``program_options``
  9. module
  10. - the //Tween// module of the //Claw// C++ library
  11. - //iwlib// from the Wireless Tools (package``libiw-dev`` on Debian,
  12. ``wireless-tools-devel`` on Fedora); only for OwlPS Listener's ``-K``
  13. option
  14. You also need support for POSIX threads, which should be provided by
  15. default by your system in most cases, and the GCC C++ compiler (g++)
  16. version 4.7 or above; the Clang C++ compiler (clang++) version 3.2 or
  17. above should also work. Compilation of the C modules has been tested
  18. with GCC and Clang and should work with older versions of these
  19. compilers.
  20. The following additional tools are recommended:
  21. - ``perl``
  22. - ``pod2man`` (normally provided in the same package as //Perl//)
  23. - ``doxygen``
  24. - ``txt2tags``
  25. If you're missing one or more of the requirements, all the modules will
  26. not be built.
  27. OwlPS uses //CMake// as a build manager. You need to install it (package
  28. ``cmake`` on most distributions) as well as the ``make`` tool if not
  29. readily available on your system. You should also install ``ccmake`` if
  30. it is not shipped with the main CMake package (package
  31. ``cmake-curses-gui`` on Debian).
  32. It is strongly advised to build out of the source tree, which can be
  33. achieved by typing the following commands from the source tree:
  34. ```
  35. mkdir build
  36. cd build
  37. cmake ..
  38. ```
  39. CMake will generate a set of Makefiles, and display warnings if
  40. dependencies are missing. After installing a missing dependency, you can
  41. type ``make rebuild_cache`` (assuming CMake did generate the Makefiles
  42. successfully), or re-run ``cmake``.
  43. Once you have all the required libraries installed, the easy way is to
  44. just call ``make`` to build all the modules. The built executables and
  45. libraries will be put in the ``bin`` and ``lib`` directories under the
  46. build directory's root; the manual pages will be generated in the
  47. ``man`` directory.
  48. You can then type ``make install`` to install everything (the default is
  49. to install to ``/usr/local``, so you will need to type this as root).
  50. == Tweaking ==
  51. To set the options (compiler, compilation flags, compilation-time
  52. options, installation prefix, etc.), after first running ``cmake``,
  53. assuming everything went well and CMake generated the Makefiles, you
  54. can type:
  55. ``` make edit_cache
  56. Or, if ``ccmake`` is not available, use the interactive mode when you
  57. first invoke CMake (``cmake -i``).
  58. Setting a compiler using these methods sometimes doesn't work; in this
  59. case, you can set the CC and/or CXX variables prior to run cmake, for
  60. example (from an empty directory):
  61. ``` CC=clang CXX=/usr/pkg/gcc47/bin/g++ cmake ~/owlps
  62. == Compilation-time options ==
  63. Here are the OwlPS-specific switches you can change in the CMake
  64. configuration as explained in the previous section.
  65. - ``OWLPS_CLIENT_RECEIVES_POSITION``: enable/disable OwlPS Client's
  66. ``-l`` option (which enables receiving the computed position from the
  67. Positioner).
  68. - ``OWLPS_LISTENER_KEEPS_MONITOR``: enable/disable OwlPS Listener's
  69. ``-K`` option (which forces the Wi-Fi interface to stay in monitor
  70. mode).
  71. - ``OWLPS_LISTENER_USES_CONFIG_FILE``: enable/disable reading the
  72. configuration from a file in OwlPS Listener.
  73. - ``OWLPS_LISTENER_USES_PTHREAD``: enable/disable use of POSIX threads
  74. in OwlPS Listener; this is required for the autocalibration and also
  76. = Compiling on BSD systems =
  77. We try to write portable code and support BSD systems as much as
  78. possible, but OwlPS is primarily developed and tested on GNU/Linux so
  79. there can be more bugs on BSD (please report them!).
  80. The building procedure is the same as on GNU/Linux systems, but you may
  81. need to edit the configuration (cf. “Tweaking” above), for example to
  82. force a specific GCC version to be used. On OpenBSD, you need to have
  83. the CXX variable set with the ``-fPIE`` flag when calling ``cmake``:
  84. ``` CXX="eg++ -fPIE" cmake ../owlps
  85. (``eg++`` is the name of the executable from the package ``g++``, the
  86. ``g++`` executable name being reserved for the OpenBSD base system's
  87. C++ compiler.)
  88. = Static compilation =
  89. It is possible to build static executables by calling the target's name
  90. followed by ``.static``. For exemple, to compile a static version of
  91. OwlPS Client, just type ``make owlps-client.static``. If you want to
  92. generate static executables for all the modules, call the ``static``
  93. meta-target (``make static``).
  94. So-called “semistatic” targets are also provided. The semistatic
  95. executables are statically linked to OwlPS libraries (such as libowlps),
  96. but dynamically linked to other libraries. This allows for quick testing
  97. of libraries changes as well as running on systems where you can install
  98. packages but where installation and maintenance of custom shared
  99. libraries is not convenient. To build semistatic executables, use
  100. the regular target's name followed by ``.semistatic`` (for example
  101. ``make owlps-client.semistatic``); a ``semistatic`` meta-target is also
  102. provided to generate semistatic executables for all the modules (``make
  103. semistatic``)
  104. To display all the available targets, type:
  105. ``` make help
  106. = Running the tests =
  107. To run the unit tests, you will need to install ``cxxtest``. Then use
  108. the ``tests`` target from your build directory:
  109. ``` make tests
  110. Currently, only OwlPS Positioner has (partial) unit tests.
  111. = Compiling for OpenWrt =
  112. == The OpenWrt toolchain ==
  113. We strongly advise that you download the full OpenWrt source tree
  114. instead of just the pre-compiled SDK, because it will allow you to
  115. easily add the components needed by the OwlPS modules you want to build.
  116. The OpenWrt documentation will help you with that:
  117. - http://wiki.openwrt.org/doc/howto/buildroot.exigence
  118. - http://wiki.openwrt.org/doc/howto/build
  119. In the configuration (``make menuconfig``), you have to:
  120. + Choose the OpenWrt //Target System// (and possibly //Subtarget//).
  121. + Select the components needed to build (press the <space> key to have a
  122. //M// or a //*//). For example:
  123. - in the //Libraries// menu, select //confuse// and //libiw//;
  124. - in the //Base system// menu, select //libpthread// and //librt// if
  125. they were not automatically selected (the latter is only needed for
  126. OwlPS Positioner).
  127. Note that at the moment, //libclaw_tween// is not provided by the
  128. OpenWrt Buildroot, so if you want to compile OwlPS Positioner you will
  129. need to add it yourself. You will also need to select
  130. //boost-program_options// from the //Libraries// menu, then make sure
  131. //libstdcpp// is selected in the //Base system// menu.
  132. == OpenWrt-specific CMake options ==
  133. To compile for OpenWrt, you need to set the ``CMAKE_TOOLCHAIN_FILE``
  134. CMake variable, using the ``-D`` option, to include the OpenWrt platform
  135. file provided with the OwlPS distribution:
  136. ``` cmake -DCMAKE_TOOLCHAIN_FILE=~/owlps/cmake/Toolchains/OpenWrt.cmake ~/owlps
  137. You can also specify the following variables (the same way, i.e. with
  138. the ``-D`` option, cf. example below):
  139. - ``OPENWRT_ROOT``: the path to the base directory in which the OpenWrt
  140. stuff is (default: ``/opt/openwrt``).
  141. - ``OPENWRT_VERSION``: the version of the OpenWrt Buildroot to use
  142. (default: ``trunk``).
  143. - ``OPENWRT_TARGET``: the name of the OpenWrt target to build for
  144. (default: ``atheros``).
  145. - ``OPENWRT_ARCH``: the target's architecture (default: ``mips``).
  146. The toolchain is assumed to be under the
  148. For maintainability's sake, we don't handle changes of version of the
  149. toolchain's tools, so you have to create symbolic links under this
  150. directory (change the ``*`` with the relevant version numbers and all):
  151. - ``target_uClibc`` pointing on
  152. ``staging_dir/target-${OPENWRT_ARCH}_*_uClibc-*``
  153. - ``toolchain_gcc_uClibc`` pointing on
  154. ``staging_dir/toolchain-${OPENWRT_ARCH}_*_gcc-*_uClibc-*``
  155. It might be easier to install your OpenWrt buildroot in a separate
  156. directory, and to just use symbolic links to point to the relevant
  157. version (cf. example below).
  158. For more information about cross-compiling with CMake, please visit
  159. http://www.cmake.org/Wiki/CMake_Cross_Compiling
  160. == Example of OpenWrt set-up ==
  161. In this example, we assume that you want to build for OpenWrt //Attitude
  162. Adjustment// (12.09), for the //ar71xx// target, and that the OpenWrt
  163. material is in the ``/opt/openwrt`` directory. You will launch CMake
  164. with a command line such as the following:
  165. ```
  166. cmake -DCMAKE_TOOLCHAIN_FILE=~/owlps/cmake/Toolchains/OpenWrt.cmake \
  167. -DOPENWRT_TARGET=ar71xx -DOPENWRT_VERSION=12.09 ~/owlps
  168. ```
  169. Note that you don't need to use ``-DOPENWRT_ROOT`` because its default
  170. value is already ``/opt/openwrt``. Similarly, you don't have to use
  171. ``-DOPENWRT_ARCH``, because its default value is ``mips`` and
  172. //ar71xx// is a MIPS target.
  173. We also assume your OpenWrt source tree is in the
  174. ``/opt/openwrt/attitude_adjustment`` directory. For the toolchain file
  175. to work, you will first create the ``/opt/openwrt/ar71xx/12.09``
  176. directory, and link the toolchain's directories from it, as explained
  177. above. As of writing, the following commands will do what you need:
  178. ```
  179. mkdir -p /opt/openwrt/ar71xx/12.09
  180. cd /opt/openwrt/ar71xx/12.09
  181. ln -s ../../attitude_adjustment/staging_dir
  182. ln -s staging_dir/target-mips_r2_uClibc- target_uClibc
  183. ln -s staging_dir/toolchain-mips_r2_gcc-4.6-linaro_uClibc- \
  184. toolchain_gcc_uClibc
  185. ```
  186. Please keep in mind that the tools' version numbers evolve as the
  187. OpenWrt project is moving forward, so you will have to update the
  188. ``target_uClibc`` and ``toolchain_gcc_uClibc`` symbolic links from time
  189. to time, especially if you're using //trunk//.
  190. == Compiling for OpenWrt ==
  191. The OpenWrt cross-compiler needs to have the ``STAGING_DIR`` variable
  192. defined in its environment; unfortunately, CMake (as of version 2.8) is
  193. unable to export environment variables when building targets. To save
  194. you the effort of setting manually this variable in your environment,
  195. the OpenWrt toolchain file provided generates a script called
  196. ``make.sh`` that you can use instead of ``make`` when compiling. After
  197. calling CMake like explained above, type:
  198. ``` ./make.sh
  199. Note that you can call this script with arguments just like you would do
  200. with ``make``. For non-building operation, you can also use ``make``
  201. directly (``make help``, ``make rebuild_cache``, ``make edit_cache``,
  202. ``make clean``, etc.).
  203. == Installing on OpenWrt ==
  204. To install the OwlPS programs on an OpenWrt box, we suggest building
  205. static or semistatic executables (cf. “Static compilation” above); this
  206. will save you the trouble of installing the OwlPS libraries and ease the
  207. updates. The downside is that you will lose some storage space if you're
  208. using more than one module (for example if you install both OwlPS
  209. Listener and OwlPS Client, the code of libowlps and libowlps-client will
  210. be duplicated in the two executables).
  211. The best compromise is to use semistatic executables, that are very much
  212. lighter than static ones, and to install the external dependencies from
  213. the packages:
  214. ``` opkg install libpthread librt libpcap
  215. (Install also ``confuse`` if you enabled support for configuration
  216. files, and ``libiw`` if you enabled the ``-K`` option.)