| Introduction to CMake |
| --------------------- |
| |
| CMake is a multi-platform build tool that can generate build files for many |
| different target platforms. See more info at http://www.cmake.org |
| |
| CMake also allows/recommends you to do "out of source"-builds, that is, |
| the build files are separated from your sources, so there is no need to |
| create elaborate clean scripts to get a clean source tree, instead you |
| simply remove your build directory. |
| |
| Libwebsockets has been tested to build successfully on the following platforms |
| with SSL support (both OpenSSL/CyaSSL): |
| |
| - Windows |
| - Linux (x86 and ARM) |
| - OSX |
| - NetBSD |
| |
| Building the library and test apps |
| ---------------------------------- |
| |
| The project settings used by CMake to generate the platform specific build |
| files is called CMakeLists.txt. CMake then uses one of its "Generators" to |
| output a Visual Studio project or Make file for instance. To see a list of |
| the available generators for your platform, simply run the "cmake" command. |
| |
| Note that by default OpenSSL will be linked, if you don't want SSL support |
| see below on how to toggle compile options. |
| |
| Building on Unix: |
| ----------------- |
| |
| 1. Install CMake 2.6 or greater: http://cmake.org/cmake/resources/software.html |
| (Most Unix distributions comes with a packaged version also) |
| |
| 2. Install OpenSSL. |
| |
| 3. Generate the build files (default is Make files): |
| |
| cd /path/to/src |
| mkdir build |
| cd build |
| cmake .. |
| |
| (NOTE: The build/ directory can have any name and be located anywhere |
| on your filesystem, and that the argument ".." given to cmake is simply |
| the source directory of libwebsockets containing the CMakeLists.txt |
| project file. All examples in this file assumes you use "..") |
| |
| NOTE2 |
| A common option you may want to give is to set the install path, same |
| as --prefix= with autotools. It defaults to /usr/local. |
| You can do this by, eg |
| |
| cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr .. |
| |
| NOTE3 |
| On machines that want libraries in lib64, you can also add the |
| following to the cmake line |
| |
| -DLIB_SUFFIX=64 |
| |
| NOTE4 |
| If you are building against a non-distro OpenSSL (eg, in order to get |
| access to ALPN support only in newer OpenSSL versions) the nice way to |
| express that in one cmake command is eg, |
| |
| -DOPENSSL_ROOT_DIR=/usr/local/ssl |
| |
| 4. Finally you can build using the generated Makefile: |
| |
| make |
| |
| |
| Quirk of cmake |
| -------------- |
| |
| When changing cmake options, for some reason the only way to get it to see the |
| changes sometimes is delete the contents of your build directory and do the |
| cmake from scratch. |
| |
| |
| Building on Windows (Visual Studio) |
| ----------------------------------- |
| 1. Install CMake 2.6 or greater: http://cmake.org/cmake/resources/software.html |
| |
| 2. Install OpenSSL binaries. http://www.openssl.org/related/binaries.html |
| (Preferably in the default location to make it easier for CMake to find them) |
| |
| 3. Generate the Visual studio project by opening the Visual Studio cmd prompt: |
| |
| cd <path to src> |
| md build |
| cd build |
| cmake -G "Visual Studio 10" .. |
| |
| (NOTE: There is also a cmake-gui available on Windows if you prefer that) |
| |
| 4. Now you should have a generated Visual Studio Solution in your |
| <path to src>/build directory, which can be used to build. |
| |
| Setting compile options |
| ----------------------- |
| |
| To set compile time flags you can either use one of the CMake gui applications |
| or do it via command line. |
| |
| Command line |
| ------------ |
| To list avaialable options (ommit the H if you don't want the help text): |
| |
| cmake -LH .. |
| |
| Then to set an option and build (for example turn off SSL support): |
| |
| cmake -DLWS_WITH_SSL=0 .. |
| or |
| cmake -DLWS_WITH_SSL:BOOL=OFF .. |
| |
| Unix GUI |
| -------- |
| If you have a curses enabled build you simply type: |
| (not all packages include this, my debian install does not for example). |
| |
| ccmake |
| |
| Windows GUI |
| ----------- |
| On windows CMake comes with a gui application: |
| Start -> Programs -> CMake -> CMake (cmake-gui) |
| |
| CyaSSL replacement for OpenSSL |
| ------------------------------ |
| CyaSSL is a lightweight SSL library targeted at embedded system: |
| http://www.yassl.com/yaSSL/Products-cyassl.html |
| |
| It contains a OpenSSL compatability layer which makes it possible to pretty |
| much link to it instead of OpenSSL, giving a much smaller footprint. |
| |
| NOTE: cyassl needs to be compiled using the --enable-opensslextra flag for |
| this to work. |
| |
| Compiling libwebsockets with CyaSSL |
| ----------------------------------- |
| |
| cmake .. -DLWS_USE_CYASSL=1 \ |
| -DLWS_CYASSL_INCLUDE_DIRS=/path/to/cyassl \ |
| -DLWS_CYASSL_LIB=/path/to/cyassl/cyassl.a .. |
| |
| NOTE: On windows use the .lib file extension for LWS_CYASSL_LIB instead. |
| |
| Cross compiling |
| --------------- |
| To enable cross compiling libwebsockets using CMake you need to create |
| a "Toolchain file" that you supply to CMake when generating your build files. |
| CMake will then use the cross compilers and build paths specified in this file |
| to look for dependencies and such. |
| |
| Libwebsockets includes an example toolchain file cross-arm-linux-gnueabihf.cmake |
| you can use as a starting point. |
| |
| The commandline to configure for cross with this would look like |
| |
| cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr \ |
| -DCMAKE_TOOLCHAIN_FILE=../cross-arm-linux-gnueabihf.cmake \ |
| -DWITHOUT_EXTENSIONS=1 -DWITH_SSL=0 |
| |
| The example shows how to build with no external cross lib dependencies, you |
| need to proide the cross libraries otherwise. |
| |
| NOTE: start from an EMPTY build directory if you had a non-cross build in there |
| before the settings will be cached and your changes ignored. |
| |
| Additional information on cross compilation with CMake: |
| http://www.vtk.org/Wiki/CMake_Cross_Compiling |
| |
| |
| Memory efficiency |
| ----------------- |
| |
| Embedded server-only configuration without extensions (ie, no compression |
| on websocket connections), but with full v13 websocket features and http |
| server, built on ARM Cortex-A9: |
| |
| Update at 8dac94d (2013-02-18) |
| |
| ./configure --without-client --without-extensions --disable-debug --without-daemonize |
| |
| Context Creation, 1024 fd limit[2]: 16720 (includes 12 bytes per fd) |
| Per-connection [3]: 72 bytes, +1328 during headers |
| |
| .text .rodata .data .bss |
| 11512 2784 288 4 |
| |
| This shows the impact of the major configuration with/without options at |
| 13ba5bbc633ea962d46d using Ubuntu ARM on a PandaBoard ES. |
| |
| These are accounting for static allocations from the library elf, there are |
| additional dynamic allocations via malloc. These are a bit old now but give |
| the right idea for relative "expense" of features. |
| |
| Static allocations, ARM9 |
| .text .rodata .data .bss |
| All (no without) 35024 9940 336 4104 |
| without client 25684 7144 336 4104 |
| without client, exts 21652 6288 288 4104 |
| without client, exts, debug[1] 19756 3768 288 4104 |
| without server 30304 8160 336 4104 |
| without server, exts 25382 7204 288 4104 |
| without server, exts, debug[1] 23712 4256 288 4104 |
| |
| [1] --disable-debug only removes messages below lwsl_notice. Since that is |
| the default logging level the impact is not noticable, error, warn and notice |
| logs are all still there. |
| |
| [2] 1024 fd per process is the default limit (set by ulimit) in at least Fedora |
| and Ubuntu. You can make significant savings tailoring this to actual expected |
| peak fds, ie, at a limit of 20, context creation allocation reduces to 4432 + |
| 240 = 4672) |
| |
| [3] known header content is freed after connection establishment |
| |
| |
| |