README.build.md

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