forked from warmcat/libwebsockets
/
README.build
209 lines (146 loc) · 6.67 KB
/
README.build
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
Introduction to CMake
---------------------
CMake is a multi-platform build tool that can generate build files for many
different target platforms. See more info at http://www.cmake.org
CMake also allows/recommends you to do "out of source"-builds, that is,
the build files are separated from your sources, so there is no need to
create elaborate clean scripts to get a clean source tree, instead you
simply remove your build directory.
Libwebsockets has been tested to build successfully on the following platforms
with SSL support (both OpenSSL/CyaSSL):
- Windows
- Linux (x86 and ARM)
- OSX
- NetBSD
Building the library and test apps
----------------------------------
The project settings used by CMake to generate the platform specific build
files is called CMakeLists.txt. CMake then uses one of its "Generators" to
output a Visual Studio project or Make file for instance. To see a list of
the available generators for your platform, simply run the "cmake" command.
Note that by default OpenSSL will be linked, if you don't want SSL support
see below on how to toggle compile options.
Building on Unix:
-----------------
1. Install CMake 2.6 or greater: http://cmake.org/cmake/resources/software.html
(Most Unix distributions comes with a packaged version also)
2. Install OpenSSL.
3. Generate the build files (default is Make files):
cd /path/to/src
mkdir build
cd build
cmake ..
(NOTE: The build/ directory can have any name and be located anywhere
on your filesystem, and that the argument ".." given to cmake is simply
the source directory of libwebsockets containing the CMakeLists.txt
project file. All examples in this file assumes you use "..")
NOTE2
A common option you may want to give is to set the install path, same
as --prefix= with autotools. It defaults to /usr/local.
You can do this by, eg
cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr
NOTE3
On machines that want libraries in lib64, you can also add the
following to the cmake line
-DLIB_SUFFIX=64
4. Finally you can build using the generated Makefile:
make
Building on Windows (Visual Studio)
-----------------------------------
1. Install CMake 2.6 or greater: http://cmake.org/cmake/resources/software.html
2. Install OpenSSL binaries. http://www.openssl.org/related/binaries.html
(Preferably in the default location to make it easier for CMake to find them)
3. Generate the Visual studio project by opening the Visual Studio cmd prompt:
cd <path to src>
md build
cd build
cmake -G "Visual Studio 10" ..
(NOTE: There is also a cmake-gui available on Windows if you prefer that)
4. Now you should have a generated Visual Studio Solution in your
<path to src>/build directory, which can be used to build.
Setting compile options
-----------------------
To set compile time flags you can either use one of the CMake gui applications
or do it via command line.
Command line
------------
To list avaialable options (ommit the H if you don't want the help text):
cmake -LH ..
Then to set an option and build (for example turn off SSL support):
cmake -DLWS_WITH_SSL=0 ..
or
cmake -DLWS_WITH_SSL:BOOL=OFF ..
Unix GUI
--------
If you have a curses enabled build you simply type:
(not all packages include this, my debian install does not for example).
ccmake
Windows GUI
-----------
On windows CMake comes with a gui application:
Start -> Programs -> CMake -> CMake (cmake-gui)
CyaSSL replacement for OpenSSL
------------------------------
CyaSSL is a lightweight SSL library targeted at embedded system:
http://www.yassl.com/yaSSL/Products-cyassl.html
It contains a OpenSSL compatability layer which makes it possible to pretty
much link to it instead of OpenSSL, giving a much smaller footprint.
NOTE: cyassl needs to be compiled using the --enable-opensslextra flag for
this to work.
Compiling libwebsockets with CyaSSL
-----------------------------------
cmake .. -DLWS_USE_CYASSL=1 \
-DLWS_CYASSL_INCLUDE_DIRS=/path/to/cyassl \
-DLWS_CYASSL_LIB=/path/to/cyassl/cyassl.a ..
NOTE: On windows use the .lib file extension for LWS_CYASSL_LIB instead.
Cross compiling
---------------
To enable cross compiling libwebsockets using CMake you need to create
a "Toolchain file" that you supply to CMake when generating your build files.
CMake will then use the cross compilers and build paths specified in this file
to look for dependencies and such.
Libwebsockets includes an example toolchain file cross-arm-linux-gnueabihf.cmake
you can use as a starting point.
The commandline to configure for cross with this would look like
cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr \
-DCMAKE_TOOLCHAIN_FILE=../cross-arm-linux-gnueabihf.cmake \
-DWITHOUT_EXTENSIONS=1 -DWITH_SSL=0
The example shows how to build with no external cross lib dependencies, you
need to proide the cross libraries otherwise.
NOTE: start from an EMPTY build directory if you had a non-cross build in there
before the settings will be cached and your changes ignored.
Additional information on cross compilation with CMake:
http://www.vtk.org/Wiki/CMake_Cross_Compiling
Memory efficiency
-----------------
Embedded server-only configuration without extensions (ie, no compression
on websocket connections), but with full v13 websocket features and http
server, built on ARM Cortex-A9:
Update at 8dac94d (2013-02-18)
./configure --without-client --without-extensions --disable-debug --without-daemonize
Context Creation, 1024 fd limit[2]: 16720 (includes 12 bytes per fd)
Per-connection [3]: 72 bytes, +1328 during headers
.text .rodata .data .bss
11512 2784 288 4
This shows the impact of the major configuration with/without options at
13ba5bbc633ea962d46d using Ubuntu ARM on a PandaBoard ES.
These are accounting for static allocations from the library elf, there are
additional dynamic allocations via malloc. These are a bit old now but give
the right idea for relative "expense" of features.
Static allocations, ARM9
.text .rodata .data .bss
All (no without) 35024 9940 336 4104
without client 25684 7144 336 4104
without client, exts 21652 6288 288 4104
without client, exts, debug[1] 19756 3768 288 4104
without server 30304 8160 336 4104
without server, exts 25382 7204 288 4104
without server, exts, debug[1] 23712 4256 288 4104
[1] --disable-debug only removes messages below lwsl_notice. Since that is
the default logging level the impact is not noticable, error, warn and notice
logs are all still there.
[2] 1024 fd per process is the default limit (set by ulimit) in at least Fedora
and Ubuntu. You can make significant savings tailoring this to actual expected
peak fds, ie, at a limit of 20, context creation allocation reduces to 4432 +
240 = 4672)
[3] known header content is freed after connection establishment