Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 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 | |
Andy Green | 5c81e80 | 2013-01-20 20:14:42 +0800 | [diff] [blame] | 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 | |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 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 | |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 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 | |
Andy Green | 3182ece | 2013-01-20 17:08:31 +0800 | [diff] [blame] | 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 | |
Andy Green | d636e35 | 2013-01-29 12:36:17 +0800 | [diff] [blame] | 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 | |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 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 | |
Andy Green | 5c81e80 | 2013-01-20 20:14:42 +0800 | [diff] [blame] | 186 | |
| 187 | Memory efficiency |
| 188 | ----------------- |
| 189 | |
Andy Green | ab40eaa | 2013-01-21 13:20:33 +0800 | [diff] [blame] | 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 | |
Andy Green | 5c81e80 | 2013-01-20 20:14:42 +0800 | [diff] [blame] | 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 |