README.build.md

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