README.build.md

   1 Notes about building lws
   2 ========================
   3
   4
   5 @section cm Introduction to CMake
   6
   7 CMake is a multi-platform build tool that can generate build files for many
   8 different target platforms. See more info at http://www.cmake.org
   9
  10 CMake also allows/recommends you to do "out of source"-builds, that is,
  11 the build files are separated from your sources, so there is no need to
  12 create elaborate clean scripts to get a clean source tree, instead you
  13 simply remove your build directory.
  14
  15 Libwebsockets has been tested to build successfully on the following platforms
  16 with SSL support (both OpenSSL/wolfSSL):
  17
  18 - Windows (Visual Studio)
  19 - Windows (MinGW)
  20 - Linux (x86 and ARM)
  21 - OSX
  22 - NetBSD
  23
  24
  25 @section build1 Building the library and test apps
  26
  27 The project settings used by CMake to generate the platform specific build
  28 files is called [CMakeLists.txt](CMakeLists.txt). CMake then uses one of its "Generators" to
  29 output a Visual Studio project or Make file for instance. To see a list of
  30 the available generators for your platform, simply run the "cmake" command.
  31
  32 Note that by default OpenSSL will be linked, if you don't want SSL support
  33 see below on how to toggle compile options.
  34
  35
  36 @section bu Building on Unix:
  37
  38 1. Install CMake 2.8 or greater: http://cmake.org/cmake/resources/software.html
  39    (Most Unix distributions comes with a packaged version also)
  40
  41 2. Install OpenSSL.
  42
  43 3. Generate the build files (default is Make files):
  44 ```
  45         $ cd /path/to/src
  46         $ mkdir build
  47         $ cd build
  48         $ cmake ..
  49 ```
  50
  51 4. Finally you can build using the generated Makefile:
  52 ```
  53         $ make && sudo make install
  54 ```
  55 **NOTE**: The `build/`` directory can have any name and be located anywhere
  56  on your filesystem, and that the argument `..` given to cmake is simply
  57  the source directory of **libwebsockets** containing the [CMakeLists.txt](CMakeLists.txt)
  58  project file. All examples in this file assumes you use ".."
  59
  60 **NOTE2**:
  61 A common option you may want to give is to set the install path, same
  62 as --prefix= with autotools.  It defaults to /usr/local.
  63 You can do this by, eg
  64 ```
  65         $ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr .
  66 ```
  67
  68 **NOTE3**:
  69 On machines that want libraries in lib64, you can also add the
  70 following to the cmake line
  71 ```
  72         -DLIB_SUFFIX=64
  73 ```
  74
  75 **NOTE4**:
  76 If you are building against a non-distro OpenSSL (eg, in order to get
  77 access to ALPN support only in newer OpenSSL versions) the nice way to
  78 express that in one cmake command is eg,
  79 ```
  80         $ cmake .. -DOPENSSL_ROOT_DIR=/usr/local/ssl \
  81                  -DCMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE=/usr/local/ssl \
  82                  -DLWS_WITH_HTTP2=1
  83 ```
  84
  85 When you run the test apps using non-distro SSL, you have to force them
  86 to use your libs, not the distro ones
  87 ```
  88         $ LD_LIBRARY_PATH=/usr/local/ssl/lib libwebsockets-test-server --ssl
  89 ```
  90
  91 To get it to build on latest openssl (2016-04-10) it needed this approach
  92 ```
  93         cmake .. -DLWS_WITH_HTTP2=1 -DLWS_OPENSSL_INCLUDE_DIRS=/usr/local/include/openssl -DLWS_OPENSSL_LIBRARIES="/usr/local/lib64/libssl.so;/usr/local/lib64/libcrypto.so"
  94 ```
  95
  96 **NOTE5**:
  97 To build with debug info and _DEBUG for lower priority debug messages
  98 compiled in, use
  99 ```
 100         $ cmake .. -DCMAKE_BUILD_TYPE=DEBUG
 101 ```
 102
 103 **NOTE6**
 104 To build on Solaris the linker needs to be informed to use lib socket
 105 and libnsl, and only builds in 64bit mode.
 106
 107 ```bash
 108         $ cmake .. -DCMAKE_C_FLAGS=-m64 -DCMAKE_EXE_LINKER_FLAGS="-lsocket -lnsl"
 109 ```
 110
 111 4. Finally you can build using the generated Makefile:
 112
 113 ```bash
 114         $ make
 115  ```
 116
 117 @section cmq Quirk of cmake
 118
 119 When changing cmake options, for some reason the only way to get it to see the
 120 changes sometimes is delete the contents of your build directory and do the
 121 cmake from scratch.
 122
 123
 124 @section cmw Building on Windows (Visual Studio)
 125
 126 1. Install CMake 2.6 or greater: http://cmake.org/cmake/resources/software.html
 127
 128 2. Install OpenSSL binaries. http://www.openssl.org/related/binaries.html
 129
 130    (**NOTE**: Preferably in the default location to make it easier for CMake to find them)
 131
 132    **NOTE2**:
 133    Be sure that OPENSSL_CONF environment variable is defined and points at
 134    <OpenSSL install location>\bin\openssl.cfg
 135
 136 3. Generate the Visual studio project by opening the Visual Studio cmd prompt:
 137
 138 ```
 139         cd <path to src>
 140         md build
 141         cd build
 142         cmake -G "Visual Studio 10" ..
 143 ```
 144
 145    (**NOTE**: There is also a cmake-gui available on Windows if you prefer that)
 146
 147    **NOTE2**:
 148    See this link to find out the version number corresponding to your Visual Studio edition:
 149    http://superuser.com/a/194065
 150
 151 4. Now you should have a generated Visual Studio Solution in  your
 152    `<path to src>/build` directory, which can be used to build.
 153
 154 5. Some additional deps may be needed
 155
 156  - iphlpapi.lib
 157  - psapi.lib
 158  - userenv.lib
 159
 160 6. If you're using libuv, you must make sure to compile libuv with the same multithread-dll / Mtd attributes as libwebsockets itself
 161
 162
 163 @section cmwmgw Building on Windows (MinGW)
 164
 165 1. Install MinGW: http://sourceforge.net/projects/mingw/files
 166
 167    (**NOTE**: Preferably in the default location C:\MinGW)
 168
 169 2. Fix up MinGW headers
 170
 171    a) Add the following lines to C:\MinGW\include\winsock2.h:
 172 ```
 173         #if(_WIN32_WINNT >= 0x0600)
 174
 175         typedef struct pollfd {
 176
 177                 SOCKET  fd;
 178                 SHORT   events;
 179                 SHORT   revents;
 180
 181         } WSAPOLLFD, *PWSAPOLLFD, FAR *LPWSAPOLLFD;
 182
 183         WINSOCK_API_LINKAGE int WSAAPI WSAPoll(LPWSAPOLLFD fdArray, ULONG fds, INT timeout);
 184
 185         #endif // (_WIN32_WINNT >= 0x0600)
 186 ```
 187    b) Create C:\MinGW\include\mstcpip.h and copy and paste the content from following link into it:
 188
 189    http://wine-unstable.sourcearchive.com/documentation/1.1.32/mstcpip_8h-source.html
 190
 191 3. Install CMake 2.6 or greater: http://cmake.org/cmake/resources/software.html
 192
 193 4. Install OpenSSL binaries. http://www.openssl.org/related/binaries.html
 194
 195    (**NOTE**: Preferably in the default location to make it easier for CMake to find them)
 196
 197    **NOTE2**:
 198    Be sure that OPENSSL_CONF environment variable is defined and points at
 199    <OpenSSL install location>\bin\openssl.cfg
 200
 201 5. Generate the build files (default is Make files) using MSYS shell:
 202 ```
 203         $ cd /drive/path/to/src
 204         $ mkdir build
 205         $ cd build
 206         $ cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=C:/MinGW ..
 207 ```
 208    (**NOTE**: The `build/`` directory can have any name and be located anywhere
 209     on your filesystem, and that the argument `..` given to cmake is simply
 210     the source directory of **libwebsockets** containing the [CMakeLists.txt](CMakeLists.txt)
 211     project file. All examples in this file assumes you use "..")
 212
 213    **NOTE2**:
 214    To generate build files allowing to create libwebsockets binaries with debug information
 215    set the CMAKE_BUILD_TYPE flag to DEBUG:
 216 ```
 217         $ cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=C:/MinGW -DCMAKE_BUILD_TYPE=DEBUG ..
 218 ```
 219 6. Finally you can build using the generated Makefile and get the results deployed into your MinGW installation:
 220
 221 ```
 222         $ make
 223         $ make install
 224 ```
 225
 226 @section mbed3 Building on mbed3
 227
 228 MBED3 is a non-posix embedded OS targeted on Cortex M class chips.
 229
 230 https://www.mbed.com/
 231
 232 It's quite unlike any other Posixy platform since the OS is linked statically
 233 in with lws to form one binary.
 234
 235 At the minute server-only is supported and due to bugs in mbed3 network support,
 236 the port is of alpha quality.  However it can serve the test html, favicon.ico
 237 and logo png and may be able to make ws connections.  The binary for that
 238 including the OS, test app, lws and all the assets is only 117KB.
 239
 240 0) Today mbed3 only properly works on FRDM K64F $35 Freescale Dev Board with
 241 1MB Flash, 256KB SRAM and Ethernet.
 242
 243 http://www.freescale.com/products/arm-processors/kinetis-cortex-m/k-series/k6x-ethernet-mcus/freescale-freedom-development-platform-for-kinetis-k64-k63-and-k24-mcus:FRDM-K64F
 244
 245 1) Get a working mbed3 environment with arm-none-eabi-cs toolchain
 246 (available in Fedora, Ubuntu and other distros)
 247
 248 2) Confirm you can build things using yotta by following the getting started guide here
 249
 250 https://docs.mbed.com/docs/getting-started-mbed-os/en/latest/
 251
 252 3)
 253
 254 git clone https://github.com/warmcat/lws-test-server
 255
 256 and cd into it
 257
 258 4) mkdir -p yotta_modules ; cd yotta_modules
 259
 260 5) git clone https://github.com/warmcat/libwebsockets ; mv libwebsockets websockets ; cd ..
 261
 262 6) yotta target frdm-k64f-gcc
 263
 264 7) yotta install
 265
 266 8) yotta build
 267
 268 @section cmco Setting compile options
 269
 270
 271 To set compile time flags you can either use one of the CMake gui applications
 272 or do it via the command line.
 273
 274 @subsection cmcocl Command line
 275
 276 To list available options (omit the H if you don't want the help text):
 277
 278         cmake -LH ..
 279
 280 Then to set an option and build (for example turn off SSL support):
 281
 282         cmake -DLWS_WITH_SSL=0 ..
 283 or
 284         cmake -DLWS_WITH_SSL:BOOL=OFF ..
 285
 286 @subsection cmcoug Unix GUI
 287
 288 If you have a curses-enabled build you simply type:
 289 (not all packages include this, my debian install does not for example).
 290
 291         ccmake
 292
 293 @subsection cmcowg Windows GUI
 294
 295 On windows CMake comes with a gui application:
 296         Start -> Programs -> CMake -> CMake (cmake-gui)
 297
 298
 299 @section wolf wolfSSL/CyaSSL replacement for OpenSSL
 300
 301 wolfSSL/CyaSSL is a lightweight SSL library targeted at embedded systems:
 302 https://www.wolfssl.com/wolfSSL/Products-wolfssl.html
 303
 304 It contains a OpenSSL compatibility layer which makes it possible to pretty
 305 much link to it instead of OpenSSL, giving a much smaller footprint.
 306
 307 **NOTE**: wolfssl needs to be compiled using the `--enable-opensslextra` flag for
 308 this to work.
 309
 310 @section wolf1 Compiling libwebsockets with wolfSSL
 311
 312 ```
 313         cmake .. -DLWS_USE_WOLFSSL=1 \
 314                  -DLWS_WOLFSSL_INCLUDE_DIRS=/path/to/wolfssl \
 315                  -DLWS_WOLFSSL_LIBRARIES=/path/to/wolfssl/wolfssl.a ..
 316 ```
 317
 318 **NOTE**: On windows use the .lib file extension for `LWS_WOLFSSL_LIBRARIES` instead.
 319
 320 @section cya Compiling libwebsockets with CyaSSL
 321
 322 ```
 323         cmake .. -DLWS_USE_CYASSL=1 \
 324                  -DLWS_CYASSL_INCLUDE_DIRS=/path/to/cyassl \
 325                  -DLWS_CYASSL_LIBRARIES=/path/to/wolfssl/cyassl.a ..
 326 ```
 327
 328 **NOTE**: On windows use the .lib file extension for `LWS_CYASSL_LIBRARIES` instead.
 329
 330
 331 @section extplugins Building plugins outside of lws itself
 332
 333 The directory ./plugin-standalone/ shows how easy it is to create plugins
 334 outside of lws itself.  First build lws itself with -DLWS_WITH_PLUGINS,
 335 then use the same flow to build the standalone plugin
 336 ```
 337         cd ./plugin-standalone
 338         mkdir build
 339         cd build
 340         cmake ..
 341         make && sudo make install
 342 ```
 343
 344 if you changed the default plugin directory when you built lws, you must
 345 also give the same arguments to cmake here (eg,
 346 ` -DCMAKE_INSTALL_PREFIX:PATH=/usr/something/else...` )
 347
 348 Otherwise if you run lwsws or libwebsockets-test-server-v2.0, it will now
 349 find the additional plugin "libprotocol_example_standalone.so"
 350 ```
 351         lwsts[21257]:   Plugins:
 352         lwsts[21257]:    libprotocol_dumb_increment.so
 353         lwsts[21257]:    libprotocol_example_standalone.so
 354         lwsts[21257]:    libprotocol_lws_mirror.so
 355         lwsts[21257]:    libprotocol_lws_server_status.so
 356         lwsts[21257]:    libprotocol_lws_status.so
 357 ```
 358 If you have multiple vhosts, you must enable plugins at the vhost
 359 additionally, discovered plugins are not enabled automatically for security
 360 reasons.  You do this using info->pvo or for lwsws, in the JSON config.
 361
 362
 363 @section http2rp Reproducing HTTP2.0 tests
 364
 365 You must have built and be running lws against a version of openssl that has
 366 ALPN / NPN.  Most distros still have older versions.  You'll know it's right by
 367 seeing
 368 ```
 369         lwsts[4752]:  Compiled with OpenSSL support
 370         lwsts[4752]:  Using SSL mode
 371         lwsts[4752]:  HTTP2 / ALPN enabled
 372 ```
 373 at lws startup.
 374
 375 For non-SSL HTTP2.0 upgrade
 376 ```
 377         $ nghttp -nvasu http://localhost:7681/test.htm
 378 ```
 379 For SSL / ALPN HTTP2.0 upgrade
 380 ```
 381         $ nghttp -nvas https://localhost:7681/test.html
 382 ```
 383
 384 @section cross Cross compiling
 385
 386 To enable cross-compiling **libwebsockets** using CMake you need to create
 387 a "Toolchain file" that you supply to CMake when generating your build files.
 388 CMake will then use the cross compilers and build paths specified in this file
 389 to look for dependencies and such.
 390
 391 **Libwebsockets** includes an example toolchain file [cross-arm-linux-gnueabihf.cmake](cross-arm-linux-gnueabihf.cmake)
 392 you can use as a starting point.
 393
 394 The commandline to configure for cross with this would look like
 395 ```
 396         $ cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr \
 397                  -DCMAKE_TOOLCHAIN_FILE=../cross-arm-linux-gnueabihf.cmake \
 398                  -DWITHOUT_EXTENSIONS=1 -DWITH_SSL=0
 399 ```
 400 The example shows how to build with no external cross lib dependencies, you
 401 need to provide the cross libraries otherwise.
 402
 403 **NOTE**: start from an EMPTY build directory if you had a non-cross build in there
 404         before the settings will be cached and your changes ignored.
 405
 406 Additional information on cross compilation with CMake:
 407         http://www.vtk.org/Wiki/CMake_Cross_Compiling
 408
 409 @section mem Memory efficiency
 410
 411 Embedded server-only configuration without extensions (ie, no compression
 412 on websocket connections), but with full v13 websocket features and http
 413 server, built on ARM Cortex-A9:
 414
 415 Update at 8dac94d (2013-02-18)
 416 ```
 417         $ ./configure --without-client --without-extensions --disable-debug --without-daemonize
 418
 419         Context Creation, 1024 fd limit[2]:   16720 (includes 12 bytes per fd)
 420         Per-connection [3]:                      72 bytes, +1328 during headers
 421
 422         .text   .rodata .data   .bss
 423         11512   2784    288     4
 424 ```
 425 This shows the impact of the major configuration with/without options at
 426 13ba5bbc633ea962d46d using Ubuntu ARM on a PandaBoard ES.
 427
 428 These are accounting for static allocations from the library elf, there are
 429 additional dynamic allocations via malloc.  These are a bit old now but give
 430 the right idea for relative "expense" of features.
 431
 432 Static allocations, ARM9
 433
 434 |                                | .text   | .rodata | .data | .bss |
 435 |--------------------------------|---------|---------|-------|------|
 436 | All (no without)               | 35024   | 9940    | 336   | 4104 |
 437 | without client                 | 25684   | 7144    | 336   | 4104 |
 438 | without client, exts           | 21652   | 6288    | 288   | 4104 |
 439 | without client, exts, debug[1] | 19756   | 3768    | 288   | 4104 |
 440 | without server                 | 30304   | 8160    | 336   | 4104 |
 441 | without server, exts           | 25382   | 7204    | 288   | 4104 |
 442 | without server, exts, debug[1] | 23712   | 4256    | 288   | 4104 |
 443
 444 [1] `--disable-debug` only removes messages below `lwsl_notice`.  Since that is
 445 the default logging level the impact is not noticeable, error, warn and notice
 446 logs are all still there.
 447
 448 [2] `1024` fd per process is the default limit (set by ulimit) in at least Fedora
 449 and Ubuntu.  You can make significant savings tailoring this to actual expected
 450 peak fds, ie, at a limit of `20`, context creation allocation reduces to `4432 +
 451 240 = 4672`)
 452
 453 [3] known header content is freed after connection establishment