Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 1 | Introduction |
| 2 | ------------ |
| 3 | Libwebsockets can be built using two different build systems |
| 4 | autoconf or CMake. autoconf only works on Unix systems, or mingw/cygwin |
| 5 | on Windows. CMake works differently and can generate platform specific |
| 6 | project files for most popular IDEs and build systems. |
| 7 | |
| 8 | ################################### Autoconf ################################### |
| 9 | |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 10 | Building the library and test apps |
| 11 | ---------------------------------- |
| 12 | |
| 13 | You need to regenerate the autotools and libtoolize stuff for your system |
| 14 | |
| 15 | $ ./autogen.sh |
| 16 | |
Andy Green | 16ab318 | 2013-02-10 18:02:31 +0800 | [diff] [blame] | 17 | Then, |
Andy Green | a2156aa | 2013-02-02 18:10:29 +0800 | [diff] [blame] | 18 | |
| 19 | ------Fedora x86_64 |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 20 | |
| 21 | ./configure --prefix=/usr --libdir=/usr/lib64 --enable-openssl |
| 22 | |
Andy Green | a2156aa | 2013-02-02 18:10:29 +0800 | [diff] [blame] | 23 | ------Apple |
| 24 | |
| 25 | Christopher Baker reported that this is needed |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 26 | |
| 27 | ./configure CC="gcc -arch i386 -arch x86_64" CXX="g++ -arch i386 -arch |
| 28 | x86_64" CPP="gcc -E" CXXCPP="g++ -E" --enable-nofork |
| 29 | |
Andy Green | a2156aa | 2013-02-02 18:10:29 +0800 | [diff] [blame] | 30 | ------mingw |
| 31 | |
| 32 | I did the following to get working build, ping test is disabled when |
| 33 | building this way |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 34 | |
| 35 | 1) install mingw64_w32 compiler packages from Fedora |
| 36 | 2) additionally install mingw64-zlib package |
| 37 | 3) ./configure --prefix=/usr --enable-mingw --host=x86_64-w64-mingw32 |
| 38 | 4) make |
| 39 | |
Andy Green | a2156aa | 2013-02-02 18:10:29 +0800 | [diff] [blame] | 40 | ------MIPS cross-build using OpenWRT |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 41 | |
Andy Green | a2156aa | 2013-02-02 18:10:29 +0800 | [diff] [blame] | 42 | ./configure --prefix=/usr --without-extensions --host mips-openwrt-linux |
| 43 | |
| 44 | I did not try building the extensions since they need cross-zlib, but it |
| 45 | should also be workable. |
| 46 | |
| 47 | ------Other uClibc |
| 48 | |
| 49 | you may need --enable-builtin-getifaddrs if your toolchain |
| 50 | doesn't have it - openWRT uclibc has it so you don't need this option. |
| 51 | |
| 52 | ------ARM cross-build |
Andy Green | 5c81e80 | 2013-01-20 20:14:42 +0800 | [diff] [blame] | 53 | |
| 54 | ./configure --prefix=/usr --host=arm-linux-gnueabi --without-client --without-extensions |
| 55 | |
| 56 | you can build cross with client and extensions perfectly well, but |
| 57 | apart from the size shrink this has the nice characteristic that no |
| 58 | non-toolchain libraries are needed to build it. |
| 59 | |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 60 | |
| 61 | otherwise if /usr/local/... and /usr/local/lib are OK then... |
| 62 | |
| 63 | $ ./configure |
| 64 | $ make clean |
| 65 | $ make && sudo make install |
| 66 | $ libwebsockets-test-server |
| 67 | |
| 68 | should be enough to get a test server listening on port 7861. |
| 69 | |
| 70 | |
| 71 | Configure script options |
| 72 | ------------------------ |
| 73 | |
| 74 | There are several other possible configure options |
| 75 | |
Andy Green | 23c5f2e | 2013-02-06 15:43:00 +0900 | [diff] [blame] | 76 | --enable-openssl Builds in the SSL support |
| 77 | |
| 78 | --with-cyassl Use cyassl instead of OpenSSL... you will need CyaSSL |
| 79 | to have been configured with --enable-opensslExtra |
| 80 | \ when it was built. |
| 81 | |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 82 | --enable-libcrypto by default libwebsockets uses its own |
| 83 | built-in md5 and sha-1 implementation for |
| 84 | simplicity. However the libcrypto ones |
| 85 | may be faster, and in a distro context it |
| 86 | may be highly desirable to use a common |
| 87 | library implementation for ease of security |
| 88 | upgrades. Give this configure option |
| 89 | to disable the built-in ones and force use |
| 90 | of the libcrypto (part of openssl) ones. |
| 91 | |
| 92 | --with-client-cert-dir=dir tells the client ssl support where to |
| 93 | look for trust certificates to validate |
| 94 | the remote certificate against. |
| 95 | |
| 96 | --enable-noping Don't try to build the ping test app |
| 97 | It needs some unixy environment that |
| 98 | may choke in other build contexts, this |
| 99 | lets you cleanly stop it being built |
| 100 | |
| 101 | --enable-builtin-getifaddrs if your libc lacks getifaddrs, you can build an |
| 102 | implementation into the library. By default your libc |
| 103 | one is used. |
| 104 | |
| 105 | --without-testapps Just build the library not the test apps |
| 106 | |
| 107 | --without-client Don't build the client part of the library nor the |
| 108 | test apps that need the client part. Useful to |
| 109 | minimize library footprint for embedded server-only |
| 110 | case |
| 111 | |
| 112 | --without-server Don't build the server part of the library nor the |
| 113 | test apps that need the server part. Useful to |
| 114 | minimize library footprint for embedded client-only |
| 115 | case |
| 116 | |
| 117 | --without-daemonize Don't build daemonize.c / lws_daemonize |
| 118 | |
| 119 | --disable-debug Remove all debug logging below lwsl_notice in severity |
| 120 | from the code -- it's not just defeated from logging |
| 121 | but removed from compilation |
| 122 | |
Andy Green | 3182ece | 2013-01-20 17:08:31 +0800 | [diff] [blame] | 123 | --without-extensions Remove all code and data around protocol extensions. |
| 124 | This reduces the code footprint considerably but |
| 125 | you will lose extension features like compression. |
| 126 | However that may be irrelevant for embedded use and |
| 127 | the code / data size / speed improvements may be |
| 128 | critical. |
| 129 | |
Andy Green | d636e35 | 2013-01-29 12:36:17 +0800 | [diff] [blame] | 130 | --with-latency Builds the latency-tracking code into the library... |
| 131 | this slows your library down a bit but is very useful |
| 132 | to find the cause of unexpected latencies occurring |
| 133 | inside the library. See README.test-apps for more |
| 134 | info |
| 135 | |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 136 | |
| 137 | Externally configurable important constants |
| 138 | ------------------------------------------- |
| 139 | |
| 140 | You can control these from configure by just setting them as commandline |
| 141 | args throgh CFLAGS, eg |
| 142 | |
| 143 | ./configure CFLAGS="-DLWS_MAX_ZLIB_CONN_BUFFER=8192" |
| 144 | |
| 145 | |
| 146 | They all have reasonable defaults usable for all use-cases except resource- |
| 147 | constrained, so you only need to take care about them if you want to tune them |
| 148 | to the amount of memory available. |
| 149 | |
| 150 | - LWS_MAX_HEADER_NAME_LENGTH default 64: max characters in an HTTP header |
Andy Green | 16ab318 | 2013-02-10 18:02:31 +0800 | [diff] [blame] | 151 | name that libwebsockets can cope with, if a header arrives bigger than this |
| 152 | it's ignored until the next header is seen |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 153 | |
Andy Green | 16ab318 | 2013-02-10 18:02:31 +0800 | [diff] [blame] | 154 | - LWS_MAX_HEADER_LEN default 1024: allocated area to copy http headers that |
| 155 | libwebsockets knows about into. You only need to think about increasing this |
| 156 | if your application might have monster length URLs for example, or some other |
| 157 | header that lws cares about will be abnormally large (headers it does not |
| 158 | know about are skipped). |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 159 | |
Andy Green | 16ab318 | 2013-02-10 18:02:31 +0800 | [diff] [blame] | 160 | - LWS_MAX_PROTOCOLS default 5: largest amount of different protocols the |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 161 | server can serve |
| 162 | |
Andy Green | 16ab318 | 2013-02-10 18:02:31 +0800 | [diff] [blame] | 163 | - LWS_MAX_EXTENSIONS_ACTIVE default 3: largest amount of extensions we can |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 164 | choose to have active on one connection |
| 165 | |
| 166 | - SPEC_LATEST_SUPPORTED default 13: only change if you want to remove support |
| 167 | for later protocol versions... unlikely |
| 168 | |
| 169 | - AWAITING_TIMEOUT default 5: after this many seconds without a response, the |
| 170 | server will hang up on the client |
| 171 | |
| 172 | - CIPHERS_LIST_STRING default "DEFAULT": SSL Cipher selection. It's advisable |
| 173 | to tweak the ciphers allowed to be negotiated on secure connections for |
| 174 | performance reasons, otherwise a slow algorithm may be selected by the two |
| 175 | endpoints and the server could expend most of its time just encrypting and |
| 176 | decrypting data, severely limiting the amount of messages it will be able to |
| 177 | handle per second. For example:: |
| 178 | |
| 179 | "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL" |
| 180 | |
| 181 | - SYSTEM_RANDOM_FILEPATH default "/dev/urandom": if your random device differs |
| 182 | you can set it here |
| 183 | |
| 184 | - LWS_MAX_ZLIB_CONN_BUFFER maximum size a compression buffer is allowed to |
| 185 | grow to before closing the connection. Some limit is needed or any connecton |
| 186 | can exhaust all server memory by sending it 4G buffers full of zeros which the |
| 187 | server is expect to expand atomically. Default is 64KBytes. |
| 188 | |
| 189 | - LWS_SOMAXCONN maximum number of pending connect requests the listening |
| 190 | socket can cope with. Default is SOMAXCONN. If you need to use synthetic |
| 191 | tests that just spam hundreds of connect requests at once without dropping |
| 192 | any, you can try messing with these as well as ulimit (see later) |
| 193 | (courtesy Edwin van der Oetelaar) |
| 194 | |
| 195 | echo "2048 64512" > /proc/sys/net/ipv4/ip_local_port_range |
| 196 | echo "1" > /proc/sys/net/ipv4/tcp_tw_recycle |
| 197 | echo "1" > /proc/sys/net/ipv4/tcp_tw_reuse |
| 198 | echo "10" > /proc/sys/net/ipv4/tcp_fin_timeout |
| 199 | echo "65536" > /proc/sys/net/core/somaxconn |
| 200 | echo "65536" > /proc/sys/net/ipv4/tcp_max_syn_backlog |
| 201 | echo "262144" > /proc/sys/net/netfilter/nf_conntrack_max |
| 202 | |
Andy Green | 5c81e80 | 2013-01-20 20:14:42 +0800 | [diff] [blame] | 203 | |
| 204 | Memory efficiency |
| 205 | ----------------- |
| 206 | |
Andy Green | ab40eaa | 2013-01-21 13:20:33 +0800 | [diff] [blame] | 207 | Update at 35f332bb46464feb87eb |
| 208 | |
| 209 | Embedded server-only configuration without extensions (ie, no compression |
| 210 | on websocket connections), but with full v13 websocket features and http |
| 211 | server, built on ARM Cortex-A9: |
| 212 | |
| 213 | ./configure --without-client --without-extensions --disable-debug --enable-nofork --without-daemonize |
| 214 | |
| 215 | .text .rodata .data .bss |
| 216 | 11476 2664 288 4 |
| 217 | |
| 218 | Context Creation, 1024 fd limit[2]: 12288 (12 bytes per fd) |
| 219 | Per-connection [3]: 4400 bytes |
| 220 | |
| 221 | |
Andy Green | 5c81e80 | 2013-01-20 20:14:42 +0800 | [diff] [blame] | 222 | This shows the impact of the major configuration with/without options at |
| 223 | 13ba5bbc633ea962d46d using Ubuntu ARM on a PandaBoard ES. |
| 224 | |
| 225 | These are accounting for static allocations from the library elf, there are |
| 226 | additional dynamic allocations via malloc |
| 227 | |
| 228 | Static allocations, ARM9 |
| 229 | .text .rodata .data .bss |
| 230 | All (no without) 35024 9940 336 4104 |
| 231 | without client 25684 7144 336 4104 |
| 232 | without client, exts 21652 6288 288 4104 |
| 233 | without client, exts, debug[1] 19756 3768 288 4104 |
| 234 | without server 30304 8160 336 4104 |
| 235 | without server, exts 25382 7204 288 4104 |
| 236 | without server, exts, debug[1] 23712 4256 288 4104 |
| 237 | |
| 238 | Dynamic allocations: ARM9 (32 bit) |
| 239 | |
| 240 | Context Creation, 1024 fd limit[2] in ulimit: 12288 (12 bytes per fd) |
| 241 | Per-connection (excluding headers[3]): 8740 |
| 242 | |
| 243 | Dynamic allocations: x86_64 (64 bit) |
| 244 | |
| 245 | Context Creation, 1024 fd limit[2] in ulimit: 16384 (16 bytes per fd) |
| 246 | Per-connection (excluding headers[3]): 9224 |
| 247 | |
| 248 | [1] --disable-debug only removes messages below lwsl_notice. Since that is |
| 249 | the default logging level the impact is not noticable, error, warn and notice |
| 250 | logs are all still there. |
| 251 | |
| 252 | [2] 1024 fd per process is the default limit (set by ulimit) in at least Fedora |
| 253 | and Ubuntu. |
| 254 | |
| 255 | [3] known headers are retained via additional mallocs for the lifetime of the |
| 256 | connection |
Joakim Soderberg | 7df9908 | 2013-02-07 20:24:19 +0800 | [diff] [blame] | 257 | |
| 258 | |
| 259 | #################################### CMake #################################### |
| 260 | |
| 261 | CMake is a multi-platform build tool that can generate build files for many |
| 262 | different target platforms. See more info at http://www.cmake.org |
| 263 | |
| 264 | CMake also allows/recommends you to do "out of source"-builds, that is, |
| 265 | the build files are separated from your sources, so there is no need to |
| 266 | create elaborate clean scripts to get a clean source tree, instead you |
| 267 | simply remove your build directory. |
| 268 | |
| 269 | Libwebsockets has been tested to build successfully on the following platforms |
| 270 | with SSL support (both OpenSSL/CyaSSL): |
| 271 | |
| 272 | - Windows |
| 273 | - Linux (x86 and ARM) |
| 274 | - OSX |
| 275 | - NetBSD |
| 276 | |
| 277 | Building the library and test apps |
| 278 | ---------------------------------- |
| 279 | |
| 280 | The project settings used by CMake to generate the platform specific build |
| 281 | files is called CMakeLists.txt. CMake then uses one of its "Generators" to |
| 282 | output a Visual Studio project or Make file for instance. To see a list of |
| 283 | the available generators for your platform, simply run the "cmake" command. |
| 284 | |
| 285 | Note that by default OpenSSL will be linked, if you don't want SSL support |
| 286 | see below on how to toggle compile options. |
| 287 | |
| 288 | Building on Unix: |
| 289 | ----------------- |
| 290 | |
| 291 | 1. Install CMake 2.6 or greater: http://cmake.org/cmake/resources/software.html |
| 292 | (Most Unix distributions comes with a packaged version also) |
| 293 | |
| 294 | 2. Install OpenSSL. |
| 295 | |
| 296 | 3. Generate the build files (default is Make files): |
| 297 | |
| 298 | cd /path/to/src |
| 299 | mkdir build |
| 300 | cd build |
| 301 | cmake .. |
| 302 | |
| 303 | (NOTE: The build/ directory can have any name and be located anywhere |
| 304 | on your filesystem, and that the argument ".." given to cmake is simply |
| 305 | the source directory of libwebsockets containing the CMakeLists.txt project |
| 306 | file. All examples in this file assumes you use "..") |
| 307 | |
| 308 | 4. Finally you can build using the generated Makefile: |
| 309 | |
| 310 | make |
| 311 | |
| 312 | Building on Windows (Visual Studio) |
| 313 | ----------------------------------- |
| 314 | 1. Install CMake 2.6 or greater: http://cmake.org/cmake/resources/software.html |
| 315 | |
| 316 | 2. Install OpenSSL binaries. http://www.openssl.org/related/binaries.html |
| 317 | (Preferably in the default location to make it easier for CMake to find them) |
| 318 | |
| 319 | 3. Generate the Visual studio project by opening the Visual Studio cmd prompt: |
| 320 | |
| 321 | cd <path to src> |
| 322 | md build |
| 323 | cd build |
| 324 | cmake -G "Visual Studio 10" .. |
| 325 | |
| 326 | (NOTE: There is also a cmake-gui available on Windows if you prefer that) |
| 327 | |
| 328 | 4. Now you should have a generated Visual Studio Solution in your |
| 329 | <path to src>/build directory, which can be used to build. |
| 330 | |
| 331 | Setting compile options |
| 332 | ----------------------- |
| 333 | |
| 334 | To set compile time flags you can either use one of the CMake gui applications |
| 335 | or do it via command line. |
| 336 | |
| 337 | Command line |
| 338 | ------------ |
| 339 | To list avaialable options (ommit the H if you don't want the help text): |
| 340 | |
| 341 | cmake -LH .. |
| 342 | |
| 343 | Then to set an option and build (for example turn off SSL support): |
| 344 | |
| 345 | cmake -DWITH_SSL=0 .. |
| 346 | or |
| 347 | cmake -DWITH_SSL:BOOL=OFF .. |
| 348 | |
| 349 | Unix GUI |
| 350 | -------- |
| 351 | If you have a curses enabled build you simply type: |
| 352 | (not all packages include this, my debian install does not for example). |
| 353 | |
| 354 | ccmake |
| 355 | |
| 356 | Windows GUI |
| 357 | ----------- |
| 358 | On windows CMake comes with a gui application: |
| 359 | Start -> Programs -> CMake -> CMake (cmake-gui) |
| 360 | |
| 361 | CyaSSL replacement for OpenSSL |
| 362 | ------------------------------ |
| 363 | CyaSSL is a lightweight SSL library targeted at embedded system: |
| 364 | http://www.yassl.com/yaSSL/Products-cyassl.html |
| 365 | |
| 366 | It contains a OpenSSL compatability layer which makes it possible to pretty |
| 367 | much link to it instead of OpenSSL, giving a much smaller footprint. |
| 368 | |
| 369 | NOTE: At the time of writing this the current release of CyaSSL contains a |
| 370 | crash bug due to some APIs libwebsocket uses. To be able to use this you will |
| 371 | need to use the current HEAD in their official repository: |
| 372 | https://github.com/cyassl/cyassl |
| 373 | |
| 374 | NOTE: cyassl needs to be compiled using the --enable-opensslExtra flag for |
| 375 | this to work. |
| 376 | |
| 377 | Compiling libwebsockets with CyaSSL |
| 378 | ----------------------------------- |
| 379 | |
| 380 | cmake -DUSE_CYASSL=1 |
| 381 | -DCYASSL_INCLUDE_DIRS=/path/to/cyassl |
| 382 | -DCYASSL_LIB=/path/to/cyassl/cyassl.a .. |
| 383 | |
| 384 | NOTE: On windows use the .lib file extension for CYASSL_LIB instead. |
| 385 | |
| 386 | Cross compiling |
| 387 | --------------- |
| 388 | To enable cross compiling libwebsockets using CMake you need to create |
| 389 | a "Toolchain file" that you supply to CMake when generating your build files. |
| 390 | CMake will then use the cross compilers and build paths specified in this file |
| 391 | to look for dependencies and such. |
| 392 | |
| 393 | Below is an example of how one of these files might look like: |
| 394 | |
| 395 | # |
| 396 | # CMake Toolchain file for crosscompiling on ARM. |
| 397 | # |
| 398 | # This can be used when running cmake in the following way: |
| 399 | # cd build/ |
| 400 | # cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/this/file/TC_arm-linux-gcc.cmake |
| 401 | # |
| 402 | |
| 403 | set(CROSS_PATH /path/to/cross_environment/uClibc) |
| 404 | |
| 405 | # Target operating system name. |
| 406 | set(CMAKE_SYSTEM_NAME Linux) |
| 407 | |
| 408 | # Name of C compiler. |
| 409 | set(CMAKE_C_COMPILER "${CROSS_PATH}/bin/arm-linux-uclibc-gcc") |
| 410 | set(CMAKE_CXX_COMPILER "${CROSS_PATH}/bin/arm-linux-uclibc-g++") |
| 411 | |
| 412 | # Where to look for the target environment. (More paths can be added here) |
| 413 | set(CMAKE_FIND_ROOT_PATH "${CROSS_PATH}") |
| 414 | |
| 415 | # Adjust the default behavior of the FIND_XXX() commands: |
| 416 | # search programs in the host environment only. |
| 417 | set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) |
| 418 | |
| 419 | # Search headers and libraries in the target environment only. |
| 420 | set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) |
| 421 | set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) |
| 422 | |
| 423 | Additional information on cross compilation with CMake: |
| 424 | http://www.vtk.org/Wiki/CMake_Cross_Compiling |