Wt

h1. Cross compile Wt on Raspberry Pi

While the Raspberry Pi looks is a complete computer with a full debian distribution, it has a slow flash disk, limited memory, and CPU power under it's hood. Compiling Wt on the device itself is not recommended unless you have a lot of time. The method described here allowed us to cross compile Wt for Raspbian GNU/Linux 7. This guide assumes that Raspbian is installed on your raspberry pi.

Note that wt packages are available on the raspbian, so you don't even have to cross-compile Wt is you're ok with the version of Wt included in your raspbian distribution. Just apt-get install it: @apt-get install witty witty-dev witty-doc witty-dbg witty-examples@

For embedded deployment, we highly recommend to cross-compile Wt. Wt supports cross-compilation, and we were successful in cross-compiling Wt on the Raspberry Pi using the method described below.

The general idea is to install a cross-compiler on your host, and the development libraries on the raspberry. Using sshfs, we will compile on the host, using the cross compiler on the host, and the header files on the raspberry pi. The resulting executables can then be copied to the raspberry pi and executed there.

The instructions below can be used to cross-compile anything that uses cmake, not just Wt. It's also recommended to cross-compile your own applications, you'll notice that it's much faster than compiling on the device itself.

h2. Install prerequisites on the raspberry pi

Log in on your raspberry pi and install the desired dependencies. To build Wt, boost is actually the only required dependency:

<pre>

# log in on the rpi to install the dependency libraries

ssh pi@raspberrypi

sudo apt-get install libboost-all-dev

</pre>

h2. Install cross compilation tool chain:

Ideally, raspbian should distribute cross-compilers for their distribution, but as far as I know, they don't. Building a correct, working cross compilation from scratch, even with tools like crosstool-ng, is a challenge in itself and many guides on the internet are either out-dated, flawed, or fail to produce the tools. We did not easily succeed to use crosstool-ng to generate a cross-compilation environment for the same gcc and glibc version as installed on our raspberry pi.

We finally used a pre-built cross compilation tool chain for a slightly different version of gcc and libc:

<pre>

# make sure that you've logged out from your rpi, execute these commands in on your host computer:

mkdir ~/rpi

git clone https://github.com/raspberrypi/tools.git

</pre>

h2. Make raspberry pi development files (header files, libraries) available on the host

On your cross compilation host, use sshfs to mount your complete raspberry pi:

<pre>

# make sure that you've logged out from your rpi, execute these commands in on your host computer:

mkdir ~/mnt_rpi

sshfs pi@rspberrypi:/ ~/mnt_rpi/ -o transform_symlinks

</pre>

The @-o transform_symlinks@ is required to transform absolute symlinks on the rpi to relative ones, so that a link on the rpi filesystem to /lib/libabc.so actually still points to the same file, and not to /lib/libabc.so on the host filesystem.

*Imporant note:* on the raspbian distribution we used, we ran into a second form of 'links' to absolute paths that prevented linking to work out of the box (resulting in link errors for libpthread, libc, libc_nonshared, ...). The files @/usr/lib/arm-linux-gnueabihf/libc.so@ and @/usr/lib/arm-linux-gnueabihf/libpthread.so@ are actually linker scripts that refer to absolute paths, which are not correct when cross compiling. Our solution was to remove the absolute path from the linker script.

For example:

<pre>

/* GNU ld script

   Use the shared library, but some functions are only in

   the static library, so try that secondarily.  */

OUTPUT_FORMAT(elf32-littlearm)

GROUP ( /lib/arm-linux-gnueabihf/libc.so.6 /usr/lib/arm-linux-gnueabihf/libc_nonshared.a  AS_NEEDED ( /lib/arm-linux-gnueabihf/ld-linux-armhf.so.3 ) )

</pre>

becomes:

<pre>

/* GNU ld script

   Use the shared library, but some functions are only in

   the static library, so try that secondarily.  */

OUTPUT_FORMAT(elf32-littlearm)

GROUP ( libc.so.6 libc_nonshared.a  AS_NEEDED ( ld-linux-armhf.so.3 ) )

</pre>

This modification solves the problem and is, as far as we know, otherwise harmless.

h2. Make a cmake toolchain file for cross compilation

Create the file below, and save it on your host computer as @~/rpi-toolchain.cmake@.

Replace @/home/me@ in the file below by your own home directory.

<pre>

SET(CMAKE_SYSTEM_NAME Linux)

SET(CMAKE_SYSTEM_VERSION 1)

SET(CMAKE_C_COMPILER

/home/me/rpi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf-gcc)

SET(CMAKE_CXX_COMPILER

/home/me/rpi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf-g++)

# where is the target environment - we mounted it using sshfs

SET(CMAKE_FIND_ROOT_PATH /home/me/mnt_rpi)

# search for programs in the build host directories

SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)

# for libraries and headers in the target directories

SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)

SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

</pre>

h2. Cross compile Wt

Once the cross compilation environment is set up, compiling Wt is straight forward:

<pre>

# make sure that you've logged out from your rpi, execute these commands in on your host computer:

# untar wt: tar xvzf wt-x.y.z.tar.gz

cd wt-x.y.z

mkdir build-rpi

cd build-rpi

cmake ../wt -DCMAKE_TOOLCHAIN_FILE=~/rpi_toolchain.cmake -DSHARED_LIBS=OFF

make -j 8

cd examples

make -j 8

</pre>

The SHARED_LIBS=OFF option makes the Wt libraries static. This is not required, but easier for deployment: you can simply copy the example executables to your raspberry pi without having to worry about the shared libraries.

h2. Run hello world on the Raspberry Pi

<pre>

# log in on the rpi and execute hello world

scp examples/hello/hello.wt pi@raspberrypi:

ssh pi@raspberrypi

chmod +x hello.wt

./hello.wt --docroot . --http-address 0.0.0.0 --http-port 8080

</pre>

Now surf to your raspberrypi (http://raspberrypi:8080/) from your host computer and you should see the hello world application!