Crosscompile Guide: Libwebsockets API

The Libwebsockets API (“LWS”) covers a lot of interesting features for people making embedded servers or clients:

• HTTP(S) serving and client operation
• HTTP/2 support for serving
• WS(S) serving and client operation
• HTTP(S) apis for file transfer and upload
• HTTP 1 + 2 POST form handling (including multipart / file upload)
• cookie-based sessions
• account management (including registration, email verification, lost pw etc)
• strong SSL / TLS PFS support (A+ on SSLlabs test)
• ssh server integration
• serving gzipped files directly from inside zip files, without conversion
• support for linux, bsd, windows etc… and very small non-linux targets like ESP32Here’s how to crosscompile it – first the easy way, and then for advanced users:

Crosscompiling made easy

1. git clone https://libwebsockets.org/repo/libwebsockets
2. cd libwebsockets
3. mkdir build
4. cd build
5. source /home/ow/SDK/FW1.1/environment-setup-cortexa9t2hf-neon-pxc-linux-gnueabi
6. cmake $CFLAGS -DCMAKE_INSTALL_PREFIX:PATH=../../Install ..
7. make # -> if this fails with CMake Error: cmake_symlink_library: System Error: Operation not supported make sure to use a drive that supports symlinks
8. make install

Check results

1. execute file libwebsocket.* to check if it is an Arm 32 / ELF Binary ->ELF 32-bit LSB shared object, ARM,
2. arm-pxc-linux-gnueabi-objdump -p ~/CrossCompiling/Install/lib/libwebsockets.so.13 | grep NEEDED

  NEEDED               libssl.so.1.0.0
  NEEDED               libcrypto.so.1.0.0
  NEEDED               libcap.so.2
  NEEDED               libpthread.so.0
  NEEDED               libc.so.6

CrossCompiling with all dependencies

There is a good guide at /libwebsockets/READMEs/README.build.md

The following description simply has been adapted to the Phoenix Contact (PxC) toolchain and the AXC F 2152 controller. FW 1.1 already has libz that is used by libwebsockets. We could include MBEDTLS but won´t because of memory usage and speed. We still need to crosscompile LIBUV.

Compiling LIBUV

Overview

libuv is a multi-platform support library with a focus on asynchronous I/O. It was primarily developed for use by Node.js, but it’s also used by Luvit, Julia, pyuv, and others.

• MIT License

Feature highlights

• Full-featured event loop backed by epoll, kqueue, IOCP, event ports
• Asynchronous TCP and UDP sockets
• Asynchronous DNS resolution
• Asynchronous file and file system operations
• File system events
• ANSI escape code controlled TTY
• IPC with socket sharing, using Unix domain sockets or named pipes (Windows)
• Child processes
• Thread pool
• Signal handling
• High resolution clock
• Threading and synchronization primitives

1/3: Building libuv cross:

1. git clone https://github.com/libuv/libuv.git get libuv
2. cd libuv
3. source /home/ow/SDK/FW1.1/environment-setup-cortexa9t2hf-neon-pxc-linux-gnueabi
4. ./autogen.sh+ libtoolize --copy libtoolize: putting auxiliary files in '.'. libtoolize: copying file './ltmain.sh' libtoolize: putting macros in AC_CONFIG_MACRO_DIRS, 'm4'. libtoolize: copying file 'm4/libtool.m4' libtoolize: copying file 'm4/ltoptions.m4' libtoolize: copying file 'm4/ltsugar.m4' libtoolize: copying file 'm4/ltversion.m4' libtoolize: copying file 'm4/lt~obsolete.m4' + aclocal -I m4 + autoconf + automake --add-missing --copy configure.ac:38: installing './ar-lib' configure.ac:25: installing './compile' configure.ac:22: installing './config.guess' configure.ac:22: installing './config.sub' configure.ac:21: installing './install-sh' configure.ac:21: installing './missing' Makefile.am: installing './depcomp'If it has problems, you will need to install automake, libtool etc.
5. ./configure --host=arm-linux-gnueabihf --prefix=/home/ow/CrossCompiling/Install
6. make && make install
7. file /home/ow/CrossCompiling/Install/lib/libuv.* Check if it’s really built for ARM

2/3: Building zlib cross

FW 1.1 already has libz that is used by libwebsocket. You can find it in the SDK /sysroots/cortexa9t2hf-neon-pxc-linux-gnueabi/lib and the headers at /sysroots/cortexa9t2hf-neon-pxc-linux-gnueabi/usr/include

Or compile it again with:

1. git clone https://github.com/madler/zlib.git
2. source /home/ow/SDK/FW1.1/environment-setup-cortexa9t2hf-neon-pxc-linux-gnueabi
3. ./configure --prefix=~/CrossCompiling/Install
4. file ~/CrossCompiling/Install/libz.*

3/3: Building libwebsockets with everything

Prepare the CMake toolchain file

For crosscompiling we need a CMake toolchain file. Here we use the file supplied by Bjoern Sauer, ready for download.

{jd_file onlinelayout==Simple File List}{jd_file file==57}

Here’s an instruction how to make it yourself.

Crosscompile

1. cd /CrossCompiling
2. git clone ssh://git@github.com/warmcat/libwebsockets
3. cd libwebsockets ; mkdir build ; cd build
4. cmake .. -DCMAKE_TOOLCHAIN_FILE=../../axcf2152.cmake \ -DTOOLCHAIN_ROOT=/home/ow/SDK/FW1.1 \ -DTOOLCHAIN_PREFIX=~/CrossCompiling/Install \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX:PATH=../../Install \ -DLWS_WITH_LWSWS=ON \ -DLWS_LIBUV_LIBRARIES=~/CrossCompiling/Install/lib/libuv.so \ -DLWS_LIBUV_INCLUDE_DIRS=~/CrossCompiling/Install/include \ -DLWS_ZLIB_LIBRARIES=~/CrossCompiling/Install/lib/libz.so \ -DLWS_ZLIB_INCLUDE_DIRS=~/CrossCompiling/Install/include (this all is one line on the commandline)
5. make && make install
6. file ~/CrossCompiling/Install/lib/libwebsockets.*
7. rm-pxc-linux-gnueabi-objdump -p ~/CrossCompiling/Install/lib/libwebsockets.so.13 | grep NEEDEDConfirm that the LWS library was linked against everything we expect (libm / libc are provided by your toolchain) NEEDED libssl.so.1.0.0 NEEDED libcrypto.so.1.0.0 NEEDED libuv.so.1 NEEDED libcap.so.2 NEEDED libpthread.so.0 NEEDED libc.so.6

• you will also find the LWS test apps in ~/CrossCompiling/Install/bin…
• to run LWS on the target, copy the related things from ~/CrossCompiling/Install…
• copy them to the ‘/usr/local/” directory in the PLC

4/3: Building mbedtls cross (optional)

1. cd /tmp
2. git clone https://github.com/ARMmbed/mbedtls.git
3. cd mbedtls ; mkdir build ; cd build
4. cmake .. \ -DCMAKE_TOOLCHAIN_FILE=../../axcf2152.cmake \ -DTOOLCHAIN_ROOT=/home/ow/SDK/FW1.1 \ -DTOOLCHAIN_PREFIX=~/CrossCompiling/Install \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX:PATH=../../Install \ -DUSE_SHARED_MBEDTLS_LIBRARY=1
5. make && make install
6. file ../../Install/lib/libmbed*