Update INSTALL.t2t with new instructions for CMake
This commit is contained in:
Matteo Cypriani
parent
9aa9099e6a
commit
eed0db4a4f
262
INSTALL.t2t
262
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.)
|
||||
|
|
|
|||
Loading…
Reference in New Issue