214 lines
6.9 KiB
Text
214 lines
6.9 KiB
Text
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 -DWITH_SSL=0 ..
|
|
or
|
|
cmake -DWITH_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: At the time of writing this the current release of CyaSSL contains a
|
|
crash bug due to some APIs libwebsocket uses. To be able to use this you will
|
|
need to use the current HEAD in their official repository:
|
|
https://github.com/cyassl/cyassl
|
|
|
|
NOTE: cyassl needs to be compiled using the --enable-opensslExtra flag for
|
|
this to work.
|
|
|
|
Compiling libwebsockets with CyaSSL
|
|
-----------------------------------
|
|
|
|
cmake -DUSE_CYASSL=1
|
|
-DCYASSL_INCLUDE_DIRS=/path/to/cyassl
|
|
-DCYASSL_LIB=/path/to/cyassl/cyassl.a ..
|
|
|
|
NOTE: On windows use the .lib file extension for 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
|
|
|
|
|
|
|