Building the examples and unit tests

NOTE: this documentation refers to library release 0.3.x

Building the examples and tests are not necessary to start using WebSocket++. You can get a lot of information from the examples without building them. The unit tests can be helpful, however, if you are trying to build a WebSocket++ program on a new platform or with new versions of Boost.

The build system for the examples and tests is Scons. Scons will attempt to build all of the examples and all of the tests that can be built given the available libraries and compiler capabilities. With all options enabled it will build every test both using the C++11 only mode as well as using Boost as a fallback. If the libraries necessary for tls or zlib support are available it will build those tests. There are several environment variables that may be set to change the behavior of the build system. Some are required and some are optional.

The output of the build program is to the build folder within the project repository. Examples are put in build/release/* and tests in build/test/*.

How to build

Set up environment

All commands should be run from the project root directory. Boost is required for building the examples and unit tests.

Variable	Required?	Purpose	Examples
BOOST_ROOT	Yes, unless BOOST_INCLUDES and BOOST_LIB are set	Path to a boost project directory that has been built in place	export BOOST_ROOT=~/Documents/boost_1_51_0
BOOST_INCLUDES and BOOST_LIBS	Yes, unless BOOST_ROOT is set	Path to the include and library directories where boost is installed	export BOOST_INCLUDES=/usr/local/include;export BOOST_LIBS=/usr/local/lib/boost
BOOST_ROOT_CPP11	Yes, for CPP11 builds	Similar to BOOST_ROOT but allows linking to a separate version of Boost compiled against a C++11 STL
BOOST_INCLUDES_CPP11 and BOOST_LIBS_CPP11	Yes, for CPP11 builds where BOOST_ROOT_CPP11 is not set	Similar to BOOST_INCLUDES and BOOST_LIBS but will be used for the C++11 STL builds
CXX	No	Allows changing the default compiler	export CXX=clang++
CXXFLAGS	No	Allows adding arbitrary extra compiler flags
LINKFLAGS	No	Allows adding arbitrary extra linker flags

Build commands

Command	Description
scons	build everything
scons test	build and run all tests
scons examples/echo_server	build a specific example (in this case echo_server)

Build environments confirmed working

Operating System	Compiler	Boost Version	Status
Mac OS X 10.8	XCode 4.5.2/Apple clang version 4.1 (tags/Apple/clang-421.11.66) (based on LLVM 3.1svn)	1.51.0	Builds all examples and all tests pass. Minor hack required to fix a bug in with Apple’s bundled libc++
Mac OS X 10.8	XCode 4.5.2/GCC 4.2 (XCode bundled)	1.51.0	Builds non-C++11 examples and non-C++11 tests pass.
Ubuntu 12.04 LTS	gcc version 4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5)	1.52.0	Builds all examples and all tests pass. boost_regex used to work around libstdc++’s poor C++11 support