Wt

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.

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:

    # log in on the rpi to install the dependency libraries

    ssh pi@raspberrypi

    sudo apt-get install libboost-all-dev

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:

    # 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

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:

    # 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

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:

    /* 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 ) )

becomes:

    /* 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 ) )

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

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.

    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)

Cross compile Wt

----------------

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

    # 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

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.

Run hello world on the Raspberry Pi

-----------------------------------

    # 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

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