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 (for OpenSSL/wolfSSL/BoringSSL):
  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 optee Building for OP-TEE
 269
 270 OP-TEE is a "Secure World" Trusted Execution Environment.
 271
 272 Although lws is only part of the necessary picture to have an https-enabled
 273 TA, it does support OP-TEE as a platform and if you provide the other
 274 pieces, does work very well.
 275
 276 Select it in cmake with `-DLWS_PLAT_OPTEE=1`
 277
 278
 279 @section cmco Setting compile options
 280
 281 To set compile time flags you can either use one of the CMake gui applications
 282 or do it via the command line.
 283
 284 @subsection cmcocl Command line
 285
 286 To list available options (omit the H if you don't want the help text):
 287
 288         cmake -LH ..
 289
 290 Then to set an option and build (for example turn off SSL support):
 291
 292         cmake -DLWS_WITH_SSL=0 ..
 293 or
 294         cmake -DLWS_WITH_SSL:BOOL=OFF ..
 295
 296 @subsection cmcoug Unix GUI
 297
 298 If you have a curses-enabled build you simply type:
 299 (not all packages include this, my debian install does not for example).
 300
 301         ccmake
 302
 303 @subsection cmcowg Windows GUI
 304
 305 On windows CMake comes with a gui application:
 306         Start -> Programs -> CMake -> CMake (cmake-gui)
 307
 308
 309 @section wolf wolfSSL/CyaSSL replacement for OpenSSL
 310
 311 wolfSSL/CyaSSL is a lightweight SSL library targeted at embedded systems:
 312 https://www.wolfssl.com/wolfSSL/Products-wolfssl.html
 313
 314 It contains a OpenSSL compatibility layer which makes it possible to pretty
 315 much link to it instead of OpenSSL, giving a much smaller footprint.
 316
 317 **NOTE**: wolfssl needs to be compiled using the `--enable-opensslextra` flag for
 318 this to work.
 319
 320 @section wolf1 Compiling libwebsockets with wolfSSL
 321
 322 ```
 323         cmake .. -DLWS_USE_WOLFSSL=1 \
 324                  -DLWS_WOLFSSL_INCLUDE_DIRS=/path/to/wolfssl \
 325                  -DLWS_WOLFSSL_LIBRARIES=/path/to/wolfssl/wolfssl.a ..
 326 ```
 327
 328 **NOTE**: On windows use the .lib file extension for `LWS_WOLFSSL_LIBRARIES` instead.
 329
 330 @section cya Compiling libwebsockets with CyaSSL
 331
 332 ```
 333         cmake .. -DLWS_USE_CYASSL=1 \
 334                  -DLWS_CYASSL_INCLUDE_DIRS=/path/to/cyassl \
 335                  -DLWS_CYASSL_LIBRARIES=/path/to/wolfssl/cyassl.a ..
 336 ```
 337
 338 **NOTE**: On windows use the .lib file extension for `LWS_CYASSL_LIBRARIES` instead.
 339
 340
 341 @section extplugins Building plugins outside of lws itself
 342
 343 The directory ./plugin-standalone/ shows how easy it is to create plugins
 344 outside of lws itself.  First build lws itself with -DLWS_WITH_PLUGINS,
 345 then use the same flow to build the standalone plugin
 346 ```
 347         cd ./plugin-standalone
 348         mkdir build
 349         cd build
 350         cmake ..
 351         make && sudo make install
 352 ```
 353
 354 if you changed the default plugin directory when you built lws, you must
 355 also give the same arguments to cmake here (eg,
 356 ` -DCMAKE_INSTALL_PREFIX:PATH=/usr/something/else...` )
 357
 358 Otherwise if you run lwsws or libwebsockets-test-server-v2.0, it will now
 359 find the additional plugin "libprotocol_example_standalone.so"
 360 ```
 361         lwsts[21257]:   Plugins:
 362         lwsts[21257]:    libprotocol_dumb_increment.so
 363         lwsts[21257]:    libprotocol_example_standalone.so
 364         lwsts[21257]:    libprotocol_lws_mirror.so
 365         lwsts[21257]:    libprotocol_lws_server_status.so
 366         lwsts[21257]:    libprotocol_lws_status.so
 367 ```
 368 If you have multiple vhosts, you must enable plugins at the vhost
 369 additionally, discovered plugins are not enabled automatically for security
 370 reasons.  You do this using info->pvo or for lwsws, in the JSON config.
 371
 372
 373 @section http2rp Reproducing HTTP2.0 tests
 374
 375 You must have built and be running lws against a version of openssl that has
 376 ALPN / NPN.  Most distros still have older versions.  You'll know it's right by
 377 seeing
 378 ```
 379         lwsts[4752]:  Compiled with OpenSSL support
 380         lwsts[4752]:  Using SSL mode
 381         lwsts[4752]:  HTTP2 / ALPN enabled
 382 ```
 383 at lws startup.
 384
 385 For non-SSL HTTP2.0 upgrade
 386 ```
 387         $ nghttp -nvasu http://localhost:7681/test.htm
 388 ```
 389 For SSL / ALPN HTTP2.0 upgrade
 390 ```
 391         $ nghttp -nvas https://localhost:7681/test.html
 392 ```
 393
 394 @section cross Cross compiling
 395
 396 To enable cross-compiling **libwebsockets** using CMake you need to create
 397 a "Toolchain file" that you supply to CMake when generating your build files.
 398 CMake will then use the cross compilers and build paths specified in this file
 399 to look for dependencies and such.
 400
 401 **Libwebsockets** includes an example toolchain file [cross-arm-linux-gnueabihf.cmake](cross-arm-linux-gnueabihf.cmake)
 402 you can use as a starting point.
 403
 404 The commandline to configure for cross with this would look like
 405 ```
 406         $ cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr \
 407                  -DCMAKE_TOOLCHAIN_FILE=../cross-arm-linux-gnueabihf.cmake \
 408                  -DLWS_WITHOUT_EXTENSIONS=1 -DLWS_WITH_SSL=0
 409 ```
 410 The example shows how to build with no external cross lib dependencies, you
 411 need to provide the cross libraries otherwise.
 412
 413 **NOTE**: start from an EMPTY build directory if you had a non-cross build in there
 414         before the settings will be cached and your changes ignored.
 415
 416 Additional information on cross compilation with CMake:
 417         http://www.vtk.org/Wiki/CMake_Cross_Compiling
 418
 419 @section mem Memory efficiency
 420
 421 Embedded server-only configuration without extensions (ie, no compression
 422 on websocket connections), but with full v13 websocket features and http
 423 server, built on ARM Cortex-A9:
 424
 425 Update at 8dac94d (2013-02-18)
 426 ```
 427         $ ./configure --without-client --without-extensions --disable-debug --without-daemonize
 428
 429         Context Creation, 1024 fd limit[2]:   16720 (includes 12 bytes per fd)
 430         Per-connection [3]:                      72 bytes, +1328 during headers
 431
 432         .text   .rodata .data   .bss
 433         11512   2784    288     4
 434 ```
 435 This shows the impact of the major configuration with/without options at
 436 13ba5bbc633ea962d46d using Ubuntu ARM on a PandaBoard ES.
 437
 438 These are accounting for static allocations from the library elf, there are
 439 additional dynamic allocations via malloc.  These are a bit old now but give
 440 the right idea for relative "expense" of features.
 441
 442 Static allocations, ARM9
 443
 444 |                                | .text   | .rodata | .data | .bss |
 445 |--------------------------------|---------|---------|-------|------|
 446 | All (no without)               | 35024   | 9940    | 336   | 4104 |
 447 | without client                 | 25684   | 7144    | 336   | 4104 |
 448 | without client, exts           | 21652   | 6288    | 288   | 4104 |
 449 | without client, exts, debug[1] | 19756   | 3768    | 288   | 4104 |
 450 | without server                 | 30304   | 8160    | 336   | 4104 |
 451 | without server, exts           | 25382   | 7204    | 288   | 4104 |
 452 | without server, exts, debug[1] | 23712   | 4256    | 288   | 4104 |
 453
 454 [1] `--disable-debug` only removes messages below `lwsl_notice`.  Since that is
 455 the default logging level the impact is not noticeable, error, warn and notice
 456 logs are all still there.
 457
 458 [2] `1024` fd per process is the default limit (set by ulimit) in at least Fedora
 459 and Ubuntu.  You can make significant savings tailoring this to actual expected
 460 peak fds, ie, at a limit of `20`, context creation allocation reduces to `4432 +
 461 240 = 4672`)
 462
 463 [3] known header content is freed after connection establishment