Andy Green | 0097a99 | 2013-03-09 13:06:37 +0800 | [diff] [blame] | 1 | Introduction to CMake |
| 2 | --------------------- |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 3 | |
| 4 | CMake is a multi-platform build tool that can generate build files for many |
| 5 | different target platforms. See more info at http://www.cmake.org |
| 6 | |
| 7 | CMake also allows/recommends you to do "out of source"-builds, that is, |
| 8 | the build files are separated from your sources, so there is no need to |
| 9 | create elaborate clean scripts to get a clean source tree, instead you |
| 10 | simply remove your build directory. |
| 11 | |
| 12 | Libwebsockets has been tested to build successfully on the following platforms |
| 13 | with SSL support (both OpenSSL/CyaSSL): |
| 14 | |
| 15 | - Windows |
| 16 | - Linux (x86 and ARM) |
| 17 | - OSX |
| 18 | - NetBSD |
| 19 | |
| 20 | Building the library and test apps |
| 21 | ---------------------------------- |
| 22 | |
| 23 | The project settings used by CMake to generate the platform specific build |
| 24 | files is called CMakeLists.txt. CMake then uses one of its "Generators" to |
| 25 | output a Visual Studio project or Make file for instance. To see a list of |
| 26 | the available generators for your platform, simply run the "cmake" command. |
| 27 | |
| 28 | Note that by default OpenSSL will be linked, if you don't want SSL support |
| 29 | see below on how to toggle compile options. |
| 30 | |
| 31 | Building on Unix: |
| 32 | ----------------- |
| 33 | |
| 34 | 1. Install CMake 2.6 or greater: http://cmake.org/cmake/resources/software.html |
| 35 | (Most Unix distributions comes with a packaged version also) |
| 36 | |
| 37 | 2. Install OpenSSL. |
| 38 | |
| 39 | 3. Generate the build files (default is Make files): |
| 40 | |
| 41 | cd /path/to/src |
| 42 | mkdir build |
| 43 | cd build |
| 44 | cmake .. |
| 45 | |
| 46 | (NOTE: The build/ directory can have any name and be located anywhere |
| 47 | on your filesystem, and that the argument ".." given to cmake is simply |
Andy Green | 0097a99 | 2013-03-09 13:06:37 +0800 | [diff] [blame] | 48 | the source directory of libwebsockets containing the CMakeLists.txt |
| 49 | project file. All examples in this file assumes you use "..") |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 50 | |
Andy Green | 975423c | 2013-02-26 11:58:45 +0800 | [diff] [blame] | 51 | NOTE2 |
Andy Green | 799ecbf | 2013-02-19 10:26:39 +0800 | [diff] [blame] | 52 | A common option you may want to give is to set the install path, same |
| 53 | as --prefix= with autotools. It defaults to /usr/local. |
| 54 | You can do this by, eg |
| 55 | |
| 56 | cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr |
| 57 | |
Andy Green | 975423c | 2013-02-26 11:58:45 +0800 | [diff] [blame] | 58 | NOTE3 |
| 59 | On machines that want libraries in lib64, you can also add the |
| 60 | following to the cmake line |
| 61 | |
| 62 | -DLIB_SUFFIX=64 |
| 63 | |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 64 | 4. Finally you can build using the generated Makefile: |
| 65 | |
| 66 | make |
| 67 | |
| 68 | Building on Windows (Visual Studio) |
| 69 | ----------------------------------- |
| 70 | 1. Install CMake 2.6 or greater: http://cmake.org/cmake/resources/software.html |
| 71 | |
| 72 | 2. Install OpenSSL binaries. http://www.openssl.org/related/binaries.html |
| 73 | (Preferably in the default location to make it easier for CMake to find them) |
| 74 | |
| 75 | 3. Generate the Visual studio project by opening the Visual Studio cmd prompt: |
| 76 | |
| 77 | cd <path to src> |
| 78 | md build |
| 79 | cd build |
| 80 | cmake -G "Visual Studio 10" .. |
| 81 | |
| 82 | (NOTE: There is also a cmake-gui available on Windows if you prefer that) |
| 83 | |
| 84 | 4. Now you should have a generated Visual Studio Solution in your |
| 85 | <path to src>/build directory, which can be used to build. |
| 86 | |
| 87 | Setting compile options |
| 88 | ----------------------- |
| 89 | |
| 90 | To set compile time flags you can either use one of the CMake gui applications |
| 91 | or do it via command line. |
| 92 | |
| 93 | Command line |
| 94 | ------------ |
| 95 | To list avaialable options (ommit the H if you don't want the help text): |
| 96 | |
| 97 | cmake -LH .. |
| 98 | |
| 99 | Then to set an option and build (for example turn off SSL support): |
| 100 | |
Andy Green | 1ea84e7 | 2014-02-21 18:45:45 +0800 | [diff] [blame] | 101 | cmake -DLWS_WITH_SSL=0 .. |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 102 | or |
Andy Green | 1ea84e7 | 2014-02-21 18:45:45 +0800 | [diff] [blame] | 103 | cmake -DLWS_WITH_SSL:BOOL=OFF .. |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 104 | |
| 105 | Unix GUI |
| 106 | -------- |
| 107 | If you have a curses enabled build you simply type: |
| 108 | (not all packages include this, my debian install does not for example). |
| 109 | |
| 110 | ccmake |
| 111 | |
| 112 | Windows GUI |
| 113 | ----------- |
| 114 | On windows CMake comes with a gui application: |
| 115 | Start -> Programs -> CMake -> CMake (cmake-gui) |
| 116 | |
| 117 | CyaSSL replacement for OpenSSL |
| 118 | ------------------------------ |
| 119 | CyaSSL is a lightweight SSL library targeted at embedded system: |
| 120 | http://www.yassl.com/yaSSL/Products-cyassl.html |
| 121 | |
| 122 | It contains a OpenSSL compatability layer which makes it possible to pretty |
| 123 | much link to it instead of OpenSSL, giving a much smaller footprint. |
| 124 | |
John Clark | 388dc7d | 2014-03-01 22:24:47 -0500 | [diff] [blame] | 125 | NOTE: cyassl needs to be compiled using the --enable-opensslextra flag for |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 126 | this to work. |
| 127 | |
| 128 | Compiling libwebsockets with CyaSSL |
| 129 | ----------------------------------- |
| 130 | |
John Clark | 388dc7d | 2014-03-01 22:24:47 -0500 | [diff] [blame] | 131 | cmake .. -DLWS_USE_CYASSL=1 \ |
| 132 | -DLWS_CYASSL_INCLUDE_DIRS=/path/to/cyassl \ |
| 133 | -DLWS_CYASSL_LIB=/path/to/cyassl/cyassl.a .. |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 134 | |
John Clark | 388dc7d | 2014-03-01 22:24:47 -0500 | [diff] [blame] | 135 | NOTE: On windows use the .lib file extension for LWS_CYASSL_LIB instead. |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 136 | |
| 137 | Cross compiling |
| 138 | --------------- |
| 139 | To enable cross compiling libwebsockets using CMake you need to create |
| 140 | a "Toolchain file" that you supply to CMake when generating your build files. |
| 141 | CMake will then use the cross compilers and build paths specified in this file |
| 142 | to look for dependencies and such. |
| 143 | |
Andy Green | 5b479ac | 2013-03-30 10:30:03 +0800 | [diff] [blame] | 144 | Libwebsockets includes an example toolchain file cross-arm-linux-gnueabihf.cmake |
| 145 | you can use as a starting point. |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 146 | |
Andy Green | 5b479ac | 2013-03-30 10:30:03 +0800 | [diff] [blame] | 147 | The commandline to configure for cross with this would look like |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 148 | |
Andy Green | 5b479ac | 2013-03-30 10:30:03 +0800 | [diff] [blame] | 149 | cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr \ |
| 150 | -DCMAKE_TOOLCHAIN_FILE=../cross-arm-linux-gnueabihf.cmake \ |
| 151 | -DWITHOUT_EXTENSIONS=1 -DWITH_SSL=0 |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 152 | |
Andy Green | 5b479ac | 2013-03-30 10:30:03 +0800 | [diff] [blame] | 153 | The example shows how to build with no external cross lib dependencies, you |
| 154 | need to proide the cross libraries otherwise. |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 155 | |
Andy Green | 5b479ac | 2013-03-30 10:30:03 +0800 | [diff] [blame] | 156 | NOTE: start from an EMPTY build directory if you had a non-cross build in there |
| 157 | before the settings will be cached and your changes ignored. |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 158 | |
| 159 | Additional information on cross compilation with CMake: |
| 160 | http://www.vtk.org/Wiki/CMake_Cross_Compiling |
Andy Green | 0097a99 | 2013-03-09 13:06:37 +0800 | [diff] [blame] | 161 | |
| 162 | |
| 163 | Memory efficiency |
| 164 | ----------------- |
| 165 | |
| 166 | Embedded server-only configuration without extensions (ie, no compression |
| 167 | on websocket connections), but with full v13 websocket features and http |
| 168 | server, built on ARM Cortex-A9: |
| 169 | |
| 170 | Update at 8dac94d (2013-02-18) |
| 171 | |
| 172 | ./configure --without-client --without-extensions --disable-debug --without-daemonize |
| 173 | |
| 174 | Context Creation, 1024 fd limit[2]: 16720 (includes 12 bytes per fd) |
| 175 | Per-connection [3]: 72 bytes, +1328 during headers |
| 176 | |
| 177 | .text .rodata .data .bss |
| 178 | 11512 2784 288 4 |
| 179 | |
| 180 | This shows the impact of the major configuration with/without options at |
| 181 | 13ba5bbc633ea962d46d using Ubuntu ARM on a PandaBoard ES. |
| 182 | |
| 183 | These are accounting for static allocations from the library elf, there are |
| 184 | additional dynamic allocations via malloc. These are a bit old now but give |
| 185 | the right idea for relative "expense" of features. |
| 186 | |
| 187 | Static allocations, ARM9 |
| 188 | .text .rodata .data .bss |
| 189 | All (no without) 35024 9940 336 4104 |
| 190 | without client 25684 7144 336 4104 |
| 191 | without client, exts 21652 6288 288 4104 |
| 192 | without client, exts, debug[1] 19756 3768 288 4104 |
| 193 | without server 30304 8160 336 4104 |
| 194 | without server, exts 25382 7204 288 4104 |
| 195 | without server, exts, debug[1] 23712 4256 288 4104 |
| 196 | |
| 197 | [1] --disable-debug only removes messages below lwsl_notice. Since that is |
| 198 | the default logging level the impact is not noticable, error, warn and notice |
| 199 | logs are all still there. |
| 200 | |
| 201 | [2] 1024 fd per process is the default limit (set by ulimit) in at least Fedora |
| 202 | and Ubuntu. You can make significant savings tailoring this to actual expected |
| 203 | peak fds, ie, at a limit of 20, context creation allocation reduces to 4432 + |
| 204 | 240 = 4672) |
| 205 | |
| 206 | [3] known header content is freed after connection establishment |
| 207 | |
| 208 | |
| 209 | |