mcy
/
owlps
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update INSTALL.t2t with new instructions for CMake

This commit is contained in:
Matteo Cypriani 2013-05-23 13:01:17 -04:00
parent 9aa9099e6a
commit eed0db4a4f
1 changed files with 198 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

262
INSTALL.t2t
View File

@ -3,50 +3,134 @@ Compiling and installing OwlPS
= Basics = = Basics =
It is planned to use the ``autotools`` in a near future, but for now, To fully build OwlPS, you need a GNU/Linux system (see “Compiling on BSD
OwlPS uses a simple set of GNU makefiles to compile and install the systems” below) with the following development libraries installed:
various modules. The top-level makefile will call ``make`` into the
subdirectories for all the modules.
At any level, you can type: - //confuse//
- //pcap//
``` make help - the //Boost// C++ libraries, and particularly the ``program_options``
module
to see the usable targets and requirements to compile. - //iwlib// from the Wireless Tools (package``libiw-dev`` on Debian,
``wireless-tools-devel`` on Fedora); only for OwlPS Listener's ``-K``
Once you have all the requirements, the easy way is to just call option
``make`` from the top-level directory, to build all the modules.
= 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 If you miss one or more of the requirements, the concerned modules will
calling ``make``, for example: 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 It is strongly advised to build out of the source tree, which can be
``clang`` is not installed. If neither ``clang`` or ``colorgcc`` is achieved by typing for instance (assuming OwlPS' source files are in
installed, CC is left to the ``make`` default. ``~/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 mkdir ~/owlps-build
4.4 or later. 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 = = Compiling on BSD systems =
Remember to use ``gmake`` instead of ``make``. From the top-level, you The procedure is the same as on GNU/Linux systems, but keep in mind that
will need to set the MAKE variable, for example: 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 ``` CXX="eg++ -fPIE" cmake ../owlps
Linux-specific code. You may want to comment-out the related lines of
the top-level makefile.
You might also need to set some variables, for example CC to force a (``eg++`` is the name of the executable from the package ``g++``, the
specific GCC version to be used. ``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 = = Compiling for OpenWrt =
@ -74,21 +158,28 @@ In the configuration (``make menuconfig``), you have to:
//libstdcpp// should now be automatically selected. //libstdcpp// should now be automatically selected.
== Make options == == OpenWrt-specific CMake options ==
To compile for OpenWrt, you need to set the ``OPENWRT_VERSION`` variable To compile for OpenWrt, you need to set the ``CMAKE_TOOLCHAIN_FILE``
when calling make, for example: 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_ROOT``: the path to the base directory in which the OpenWrt
OpenWrt stuff is (default: $HOME/openwrt). stuff is (default: ``/opt/openwrt``).
- OPENWRT_TARGET is the name of the OpenWrt target to build for - ``OPENWRT_VERSION``: the version of the OpenWrt Buildroot to use
(default: atheros). (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 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 toolchain's tools, so you have to create symbolic links under this
directory (change the ``*`` with the relevant version numbers and all): 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 - ``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 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). 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 == == Example of OpenWrt set-up ==
We assume here that you want to build for the last OpenWrt development In this example, we assume that you want to build for OpenWrt //Attitude
version (//trunk//), for the //ar71xx// target, and that the OpenWrt Adjustment// (12.09), for the //ar71xx// target, and that the OpenWrt
material is in the ``/opt/openwrt`` directory. You will compile with the material is in the ``/opt/openwrt`` directory. You will launch CMake
following command line: with a command line such as the following:
``` 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:
``` ```
mkdir -p /opt/openwrt/ar71xx/trunk cmake -DCMAKE_TOOLCHAIN_FILE=~/owlps/cmake/Toolchains/OpenWrt.cmake \
cd /opt/openwrt/ar71xx/trunk -DOPENWRT_TARGET=ar71xx -DOPENWRT_VERSION=12.09 ~/owlps
ln -s ../../trunk/staging_dir ```
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/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 \ ln -s staging_dir/toolchain-mips_r2_gcc-4.6-linaro_uClibc-0.9.33.2 \
toolchain_gcc_uClibc toolchain_gcc_uClibc
``` ```
Of course, you will have to update the ``target_uClibc`` and Please keep in mind that the tools' version numbers evolve as the
``toolchain_gcc_uClibc`` symbolic links from time to time, as the OpenWrt project is moving forward, so you will have to update the
tools' version numbers change in trunk. ``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 The OpenWrt cross-compiler needs to have the ``STAGING_DIR`` variable
``root``: 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.)