README.build

   1 Building the library and test apps
   2 ----------------------------------
   3
   4 You need to regenerate the autotools and libtoolize stuff for your system
   5
   6 $ ./autogen.sh
   7
   8 Then for a Fedora x86_86 box, the following config line was
   9 needed:
  10
  11  ./configure --prefix=/usr --libdir=/usr/lib64 --enable-openssl
  12
  13 For Apple systems, Christopher Baker reported that this is needed
  14 (and I was told separately enabling openssl makes trouble somehow)
  15
  16 ./configure CC="gcc -arch i386 -arch x86_64" CXX="g++ -arch i386 -arch
  17 x86_64" CPP="gcc -E" CXXCPP="g++ -E" --enable-nofork
  18
  19 For mingw build, I did the following to get working build, ping test is
  20 disabled when building this way
  21
  22 1) install mingw64_w32 compiler packages from Fedora
  23 2) additionally install mingw64-zlib package
  24 3) ./configure --prefix=/usr --enable-mingw --host=x86_64-w64-mingw32
  25 4) make
  26
  27 For uClibc, you will likely need --enable-builtin-getifaddrs
  28
  29 For cross-building, here's an example using the Linaro ARM toolchain
  30
  31 ./configure --prefix=/usr --host=arm-linux-gnueabi --without-client --without-extensions
  32
  33 you can build cross with client and extensions perfectly well, but
  34 apart from the size shrink this has the nice characteristic that no
  35 non-toolchain libraries are needed to build it.
  36
  37
  38 otherwise if /usr/local/... and /usr/local/lib are OK then...
  39
  40 $ ./configure
  41 $ make clean
  42 $ make && sudo make install
  43 $ libwebsockets-test-server
  44
  45 should be enough to get a test server listening on port 7861.
  46
  47
  48 Configure script options
  49 ------------------------
  50
  51 There are several other possible configure options
  52
  53 --enable-libcrypto      by default libwebsockets uses its own
  54                         built-in md5 and sha-1 implementation for
  55                         simplicity.  However the libcrypto ones
  56                         may be faster, and in a distro context it
  57                         may be highly desirable to use a common
  58                         library implementation for ease of security
  59                         upgrades.  Give this configure option
  60                         to disable the built-in ones and force use
  61                         of the libcrypto (part of openssl) ones.
  62
  63 --with-client-cert-dir=dir   tells the client ssl support where to
  64                              look for trust certificates to validate
  65                              the remote certificate against.
  66
  67 --enable-noping         Don't try to build the ping test app
  68                         It needs some unixy environment that
  69                         may choke in other build contexts, this
  70                         lets you cleanly stop it being built
  71
  72 --enable-builtin-getifaddrs  if your libc lacks getifaddrs, you can build an
  73                         implementation into the library.  By default your libc
  74                         one is used.
  75
  76 --without-testapps      Just build the library not the test apps
  77
  78 --without-client        Don't build the client part of the library nor the
  79                         test apps that need the client part.  Useful to
  80                         minimize library footprint for embedded server-only
  81                         case
  82
  83 --without-server        Don't build the server part of the library nor the
  84                         test apps that need the server part.  Useful to
  85                         minimize library footprint for embedded client-only
  86                         case
  87
  88 --without-daemonize     Don't build daemonize.c / lws_daemonize
  89
  90 --disable-debug         Remove all debug logging below lwsl_notice in severity
  91                         from the code -- it's not just defeated from logging
  92                         but removed from compilation
  93
  94 --without-extensions    Remove all code and data around protocol extensions.
  95                         This reduces the code footprint considerably but
  96                         you will lose extension features like compression.
  97                         However that may be irrelevant for embedded use and
  98                         the code / data size / speed improvements may be
  99                         critical.
 100
 101 --with-latency          Builds the latency-tracking code into the library...
 102                         this slows your library down a bit but is very useful
 103                         to find the cause of unexpected latencies occurring
 104                         inside the library.  See README.test-apps for more
 105                         info
 106
 107
 108 Externally configurable important constants
 109 -------------------------------------------
 110
 111 You can control these from configure by just setting them as commandline
 112 args throgh CFLAGS, eg
 113
 114 ./configure CFLAGS="-DLWS_MAX_ZLIB_CONN_BUFFER=8192"
 115
 116
 117 They all have reasonable defaults usable for all use-cases except resource-
 118 constrained, so you only need to take care about them if you want to tune them
 119 to the amount of memory available.
 120
 121  - LWS_MAX_HEADER_NAME_LENGTH default 64: max characters in an HTTP header
 122 name that libwebsockets can cope with
 123
 124  - LWS_MAX_HEADER_LEN default 4096: largest HTTP header value string length
 125 libwebsockets can cope with
 126
 127  - LWS_INITIAL_HDR_ALLOC default 256: amount of memory to allocate initially,
 128 tradeoff between taking too much and needless realloc
 129
 130  - LWS_ADDITIONAL_HDR_ALLOC default 64: how much to additionally realloc if
 131 the header value string keeps coming
 132
 133  - MAX_USER_RX_BUFFER default 4096: max amount of user rx data to buffer at a
 134 time and pass to user callback LWS_CALLBACK_RECEIVE or
 135 LWS_CALLBACK_CLIENT_RECEIVE.  Large frames are passed to the user callback
 136 in chunks of this size.  Tradeoff between per-connection static memory
 137 allocation and if you expect to deal with large frames, how much you can
 138 see at once which can affect efficiency.
 139
 140  - MAX_BROADCAST_PAYLOAD default 4096: largest amount of user tx data we can
 141 broadcast at a time
 142
 143  - LWS_MAX_PROTOCOLS default 10: largest amount of different protocols the
 144 server can serve
 145
 146  - LWS_MAX_EXTENSIONS_ACTIVE default 10: largest amount of extensions we can
 147 choose to have active on one connection
 148
 149  - SPEC_LATEST_SUPPORTED default 13: only change if you want to remove support
 150 for later protocol versions... unlikely
 151
 152  - AWAITING_TIMEOUT default 5: after this many seconds without a response, the
 153 server will hang up on the client
 154
 155  - CIPHERS_LIST_STRING default "DEFAULT": SSL Cipher selection.  It's advisable
 156 to tweak the ciphers allowed to be negotiated on secure connections for
 157 performance reasons, otherwise a slow algorithm may be selected by the two
 158 endpoints and the server could expend most of its time just encrypting and
 159 decrypting data, severely limiting the amount of messages it will be able to
 160 handle per second.  For example::
 161
 162     "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
 163
 164  - SYSTEM_RANDOM_FILEPATH default "/dev/urandom": if your random device differs
 165 you can set it here
 166
 167  - LWS_MAX_ZLIB_CONN_BUFFER  maximum size a compression buffer is allowed to
 168 grow to before closing the connection.  Some limit is needed or any connecton
 169 can exhaust all server memory by sending it 4G buffers full of zeros which the
 170 server is expect to expand atomically.  Default is 64KBytes.
 171
 172  - LWS_SOMAXCONN  maximum number of pending connect requests the listening
 173 socket can cope with.  Default is SOMAXCONN.  If you need to use synthetic
 174 tests that just spam hundreds of connect requests at once without dropping
 175 any, you can try messing with these as well as ulimit (see later)
 176 (courtesy Edwin van der Oetelaar)
 177
 178 echo "2048 64512" > /proc/sys/net/ipv4/ip_local_port_range
 179 echo "1" > /proc/sys/net/ipv4/tcp_tw_recycle
 180 echo "1" > /proc/sys/net/ipv4/tcp_tw_reuse
 181 echo "10" > /proc/sys/net/ipv4/tcp_fin_timeout
 182 echo "65536" > /proc/sys/net/core/somaxconn
 183 echo "65536" > /proc/sys/net/ipv4/tcp_max_syn_backlog
 184 echo "262144" > /proc/sys/net/netfilter/nf_conntrack_max
 185
 186
 187 Memory efficiency
 188 -----------------
 189
 190 Update at 35f332bb46464feb87eb
 191
 192 Embedded server-only configuration without extensions (ie, no compression
 193 on websocket connections), but with full v13 websocket features and http
 194 server, built on ARM Cortex-A9:
 195
 196 ./configure --without-client --without-extensions --disable-debug --enable-nofork --without-daemonize
 197
 198 .text   .rodata .data   .bss
 199 11476   2664    288     4
 200
 201 Context Creation, 1024 fd limit[2]: 12288 (12 bytes per fd)
 202 Per-connection [3]: 4400 bytes
 203
 204
 205 This shows the impact of the major configuration with/without options at
 206 13ba5bbc633ea962d46d using Ubuntu ARM on a PandaBoard ES.
 207
 208 These are accounting for static allocations from the library elf, there are
 209 additional dynamic allocations via malloc
 210
 211 Static allocations, ARM9
 212                                 .text   .rodata .data   .bss
 213  All (no without)               35024   9940    336     4104
 214  without client                 25684   7144    336     4104
 215  without client, exts           21652   6288    288     4104
 216  without client, exts, debug[1] 19756   3768    288     4104
 217  without server                 30304   8160    336     4104
 218  without server, exts           25382   7204    288     4104
 219  without server, exts, debug[1] 23712   4256    288     4104
 220
 221 Dynamic allocations: ARM9 (32 bit)
 222
 223  Context Creation, 1024 fd limit[2] in ulimit:  12288  (12 bytes per fd)
 224  Per-connection (excluding headers[3]):          8740
 225
 226 Dynamic allocations: x86_64 (64 bit)
 227
 228  Context Creation, 1024 fd limit[2] in ulimit:  16384  (16 bytes per fd)
 229  Per-connection (excluding headers[3]):          9224
 230
 231 [1] --disable-debug only removes messages below lwsl_notice.  Since that is
 232 the default logging level the impact is not noticable, error, warn and notice
 233 logs are all still there.
 234
 235 [2] 1024 fd per process is the default limit (set by ulimit) in at least Fedora
 236 and Ubuntu.
 237
 238 [3] known headers are retained via additional mallocs for the lifetime of the
 239 connection