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 Mac users have reported
  97
  98 ```
  99  $ export OPENSSL_ROOT_DIR=/usr/local/Cellar/openssl/1.0.2k; cmake ..; make -j4
 100 ```
 101
 102 worked for them when using "homebrew" OpenSSL
 103
 104 **NOTE5**:
 105 To build with debug info and _DEBUG for lower priority debug messages
 106 compiled in, use
 107 ```
 108         $ cmake .. -DCMAKE_BUILD_TYPE=DEBUG
 109 ```
 110
 111 **NOTE6**
 112 To build on Solaris the linker needs to be informed to use lib socket
 113 and libnsl, and only builds in 64bit mode.
 114
 115 ```bash
 116         $ cmake .. -DCMAKE_C_FLAGS=-m64 -DCMAKE_EXE_LINKER_FLAGS="-lsocket -lnsl"
 117 ```
 118
 119 4. Finally you can build using the generated Makefile:
 120
 121 ```bash
 122         $ make
 123  ```
 124
 125 @section cmq Quirk of cmake
 126
 127 When changing cmake options, for some reason the only way to get it to see the
 128 changes sometimes is delete the contents of your build directory and do the
 129 cmake from scratch.
 130
 131
 132 @section cmw Building on Windows (Visual Studio)
 133
 134 1. Install CMake 2.6 or greater: http://cmake.org/cmake/resources/software.html
 135
 136 2. Install OpenSSL binaries. http://www.openssl.org/related/binaries.html
 137
 138    (**NOTE**: Preferably in the default location to make it easier for CMake to find them)
 139
 140    **NOTE2**:
 141    Be sure that OPENSSL_CONF environment variable is defined and points at
 142    <OpenSSL install location>\bin\openssl.cfg
 143
 144 3. Generate the Visual studio project by opening the Visual Studio cmd prompt:
 145
 146 ```
 147         cd <path to src>
 148         md build
 149         cd build
 150         cmake -G "Visual Studio 10" ..
 151 ```
 152
 153    (**NOTE**: There is also a cmake-gui available on Windows if you prefer that)
 154
 155    **NOTE2**:
 156    See this link to find out the version number corresponding to your Visual Studio edition:
 157    http://superuser.com/a/194065
 158
 159 4. Now you should have a generated Visual Studio Solution in  your
 160    `<path to src>/build` directory, which can be used to build.
 161
 162 5. Some additional deps may be needed
 163
 164  - iphlpapi.lib
 165  - psapi.lib
 166  - userenv.lib
 167
 168 6. If you're using libuv, you must make sure to compile libuv with the same multithread-dll / Mtd attributes as libwebsockets itself
 169
 170
 171 @section cmwmgw Building on Windows (MinGW)
 172
 173 1. Install MinGW: http://sourceforge.net/projects/mingw/files
 174
 175    (**NOTE**: Preferably in the default location C:\MinGW)
 176
 177 2. Fix up MinGW headers
 178
 179    a) If still necessary, sdd the following lines to C:\MinGW\include\winsock2.h:
 180 ```
 181         #if(_WIN32_WINNT >= 0x0600)
 182
 183         typedef struct pollfd {
 184
 185                 SOCKET  fd;
 186                 SHORT   events;
 187                 SHORT   revents;
 188
 189         } WSAPOLLFD, *PWSAPOLLFD, FAR *LPWSAPOLLFD;
 190
 191         WINSOCK_API_LINKAGE int WSAAPI WSAPoll(LPWSAPOLLFD fdArray, ULONG fds, INT timeout);
 192
 193         #endif // (_WIN32_WINNT >= 0x0600)
 194 ```
 195
 196        Update crtdefs.h line 47 to say:
 197
 198 ```
 199         typedef __int64 ssize_t;
 200 ```
 201
 202    b) Create C:\MinGW\include\mstcpip.h and copy and paste the content from following link into it:
 203
 204    https://github.com/Alexpux/mingw-w64/blob/master/mingw-w64-headers/include/mstcpip.h
 205
 206 3. Install CMake 2.6 or greater: http://cmake.org/cmake/resources/software.html
 207
 208 4. Install OpenSSL binaries. http://www.openssl.org/related/binaries.html
 209
 210    (**NOTE**: Preferably in the default location to make it easier for CMake to find them)
 211
 212    **NOTE2**:
 213    Be sure that OPENSSL_CONF environment variable is defined and points at
 214    <OpenSSL install location>\bin\openssl.cfg
 215
 216 5. Generate the build files (default is Make files) using MSYS shell:
 217 ```
 218         $ cd /drive/path/to/src
 219         $ mkdir build
 220         $ cd build
 221         $ cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=C:/MinGW ..
 222 ```
 223    (**NOTE**: The `build/`` directory can have any name and be located anywhere
 224     on your filesystem, and that the argument `..` given to cmake is simply
 225     the source directory of **libwebsockets** containing the [CMakeLists.txt](CMakeLists.txt)
 226     project file. All examples in this file assumes you use "..")
 227
 228    **NOTE2**:
 229    To generate build files allowing to create libwebsockets binaries with debug information
 230    set the CMAKE_BUILD_TYPE flag to DEBUG:
 231 ```
 232         $ cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=C:/MinGW -DCMAKE_BUILD_TYPE=DEBUG ..
 233 ```
 234 6. Finally you can build using the generated Makefile and get the results deployed into your MinGW installation:
 235
 236 ```
 237         $ make
 238         $ make install
 239 ```
 240
 241 @section optee Building for OP-TEE
 242
 243 OP-TEE is a "Secure World" Trusted Execution Environment.
 244
 245 Although lws is only part of the necessary picture to have an https-enabled
 246 TA, it does support OP-TEE as a platform and if you provide the other
 247 pieces, does work very well.
 248
 249 Select it in cmake with `-DLWS_PLAT_OPTEE=1`
 250
 251
 252 @section cmco Setting compile options
 253
 254 To set compile time flags you can either use one of the CMake gui applications
 255 or do it via the command line.
 256
 257 @subsection cmcocl Command line
 258
 259 To list available options (omit the H if you don't want the help text):
 260
 261         cmake -LH ..
 262
 263 Then to set an option and build (for example turn off SSL support):
 264
 265         cmake -DLWS_WITH_SSL=0 ..
 266 or
 267         cmake -DLWS_WITH_SSL:BOOL=OFF ..
 268
 269 @subsection cmcoug Unix GUI
 270
 271 If you have a curses-enabled build you simply type:
 272 (not all packages include this, my debian install does not for example).
 273
 274         ccmake
 275
 276 @subsection cmcowg Windows GUI
 277
 278 On windows CMake comes with a gui application:
 279         Start -> Programs -> CMake -> CMake (cmake-gui)
 280
 281
 282 @section wolf wolfSSL/CyaSSL replacement for OpenSSL
 283
 284 wolfSSL/CyaSSL is a lightweight SSL library targeted at embedded systems:
 285 https://www.wolfssl.com/wolfSSL/Products-wolfssl.html
 286
 287 It contains a OpenSSL compatibility layer which makes it possible to pretty
 288 much link to it instead of OpenSSL, giving a much smaller footprint.
 289
 290 **NOTE**: wolfssl needs to be compiled using the `--enable-opensslextra` flag for
 291 this to work.
 292
 293 @section wolf1 Compiling libwebsockets with wolfSSL
 294
 295 ```
 296         cmake .. -DLWS_USE_WOLFSSL=1 \
 297                  -DLWS_WOLFSSL_INCLUDE_DIRS=/path/to/wolfssl \
 298                  -DLWS_WOLFSSL_LIBRARIES=/path/to/wolfssl/wolfssl.a ..
 299 ```
 300
 301 **NOTE**: On windows use the .lib file extension for `LWS_WOLFSSL_LIBRARIES` instead.
 302
 303 @section cya Compiling libwebsockets with CyaSSL
 304
 305 ```
 306         cmake .. -DLWS_USE_CYASSL=1 \
 307                  -DLWS_CYASSL_INCLUDE_DIRS=/path/to/cyassl \
 308                  -DLWS_CYASSL_LIBRARIES=/path/to/wolfssl/cyassl.a ..
 309 ```
 310
 311 **NOTE**: On windows use the .lib file extension for `LWS_CYASSL_LIBRARIES` instead.
 312
 313 @section esp32 Building for ESP32
 314
 315 Step 1, get ESP-IDF with lws integrated as a component
 316
 317 ```
 318     $ git clone --int --recursive https://github.com/lws-team/lws-esp-idf
 319 ```
 320
 321 Step 2: Get Application including the test plugins
 322
 323 ```
 324     $ git clone https://github.com/lws-team/lws-esp32
 325 ```
 326
 327 Set your IDF_PATH to point to the esp-idf you downloaded in 1)
 328
 329 There's docs for how to build the lws-esp32 test app and reproduce it in the README.md here
 330
 331 https://github.com/lws-team/lws-esp32/blob/master/README.md
 332
 333
 334 @section extplugins Building plugins outside of lws itself
 335
 336 The directory ./plugin-standalone/ shows how easy it is to create plugins
 337 outside of lws itself.  First build lws itself with -DLWS_WITH_PLUGINS,
 338 then use the same flow to build the standalone plugin
 339 ```
 340         cd ./plugin-standalone
 341         mkdir build
 342         cd build
 343         cmake ..
 344         make && sudo make install
 345 ```
 346
 347 if you changed the default plugin directory when you built lws, you must
 348 also give the same arguments to cmake here (eg,
 349 ` -DCMAKE_INSTALL_PREFIX:PATH=/usr/something/else...` )
 350
 351 Otherwise if you run lwsws or libwebsockets-test-server-v2.0, it will now
 352 find the additional plugin "libprotocol_example_standalone.so"
 353 ```
 354         lwsts[21257]:   Plugins:
 355         lwsts[21257]:    libprotocol_dumb_increment.so
 356         lwsts[21257]:    libprotocol_example_standalone.so
 357         lwsts[21257]:    libprotocol_lws_mirror.so
 358         lwsts[21257]:    libprotocol_lws_server_status.so
 359         lwsts[21257]:    libprotocol_lws_status.so
 360 ```
 361 If you have multiple vhosts, you must enable plugins at the vhost
 362 additionally, discovered plugins are not enabled automatically for security
 363 reasons.  You do this using info->pvo or for lwsws, in the JSON config.
 364
 365
 366 @section http2rp Reproducing HTTP2.0 tests
 367
 368 You must have built and be running lws against a version of openssl that has
 369 ALPN / NPN.  Most distros still have older versions.  You'll know it's right by
 370 seeing
 371 ```
 372         lwsts[4752]:  Compiled with OpenSSL support
 373         lwsts[4752]:  Using SSL mode
 374         lwsts[4752]:  HTTP2 / ALPN enabled
 375 ```
 376 at lws startup.
 377
 378 For non-SSL HTTP2.0 upgrade
 379 ```
 380         $ nghttp -nvasu http://localhost:7681/test.htm
 381 ```
 382 For SSL / ALPN HTTP2.0 upgrade
 383 ```
 384         $ nghttp -nvas https://localhost:7681/test.html
 385 ```
 386
 387 @section cross Cross compiling
 388
 389 To enable cross-compiling **libwebsockets** using CMake you need to create
 390 a "Toolchain file" that you supply to CMake when generating your build files.
 391 CMake will then use the cross compilers and build paths specified in this file
 392 to look for dependencies and such.
 393
 394 **Libwebsockets** includes an example toolchain file [cross-arm-linux-gnueabihf.cmake](cross-arm-linux-gnueabihf.cmake)
 395 you can use as a starting point.
 396
 397 The commandline to configure for cross with this would look like
 398 ```
 399         $ cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr \
 400                  -DCMAKE_TOOLCHAIN_FILE=../cross-arm-linux-gnueabihf.cmake \
 401                  -DLWS_WITHOUT_EXTENSIONS=1 -DLWS_WITH_SSL=0
 402 ```
 403 The example shows how to build with no external cross lib dependencies, you
 404 need to provide the cross libraries otherwise.
 405
 406 **NOTE**: start from an EMPTY build directory if you had a non-cross build in there
 407         before the settings will be cached and your changes ignored.
 408
 409 Additional information on cross compilation with CMake:
 410         http://www.vtk.org/Wiki/CMake_Cross_Compiling
 411
 412 @section mem Memory efficiency
 413
 414 Embedded server-only configuration without extensions (ie, no compression
 415 on websocket connections), but with full v13 websocket features and http
 416 server, built on ARM Cortex-A9:
 417
 418 Update at 8dac94d (2013-02-18)
 419 ```
 420         $ ./configure --without-client --without-extensions --disable-debug --without-daemonize
 421
 422         Context Creation, 1024 fd limit[2]:   16720 (includes 12 bytes per fd)
 423         Per-connection [3]:                      72 bytes, +1328 during headers
 424
 425         .text   .rodata .data   .bss
 426         11512   2784    288     4
 427 ```
 428 This shows the impact of the major configuration with/without options at
 429 13ba5bbc633ea962d46d using Ubuntu ARM on a PandaBoard ES.
 430
 431 These are accounting for static allocations from the library elf, there are
 432 additional dynamic allocations via malloc.  These are a bit old now but give
 433 the right idea for relative "expense" of features.
 434
 435 Static allocations, ARM9
 436
 437 |                                | .text   | .rodata | .data | .bss |
 438 |--------------------------------|---------|---------|-------|------|
 439 | All (no without)               | 35024   | 9940    | 336   | 4104 |
 440 | without client                 | 25684   | 7144    | 336   | 4104 |
 441 | without client, exts           | 21652   | 6288    | 288   | 4104 |
 442 | without client, exts, debug[1] | 19756   | 3768    | 288   | 4104 |
 443 | without server                 | 30304   | 8160    | 336   | 4104 |
 444 | without server, exts           | 25382   | 7204    | 288   | 4104 |
 445 | without server, exts, debug[1] | 23712   | 4256    | 288   | 4104 |
 446
 447 [1] `--disable-debug` only removes messages below `lwsl_notice`.  Since that is
 448 the default logging level the impact is not noticeable, error, warn and notice
 449 logs are all still there.
 450
 451 [2] `1024` fd per process is the default limit (set by ulimit) in at least Fedora
 452 and Ubuntu.  You can make significant savings tailoring this to actual expected
 453 peak fds, ie, at a limit of `20`, context creation allocation reduces to `4432 +
 454 240 = 4672`)
 455
 456 [3] known header content is freed after connection establishment