An API for XMPP connectivity.
Documentation for the API is available at https://cisco.github.io/JabberWerxC/
JabberWerxC can be built under Unix, Linux, OS X, or Windows, and has the following dependencies (configured using pkg-config):
- expat version 2.1.0 or later
- c-ares version 1.10 or later
- libevent version 2.0.21 or later
- libcurl version 7.31.0 or later (optional, for BOSH support)
- libidn version 1.28 or later (optional, for stringprep support)
- OpenSSL version 1.0 or later (optional, for TLS support. Latest version strongly recommended)
JabberWerxC uses CMake as its build system, and supports at least Mac OS X and Linux platforms.
JabberWerxC needs the following tools to build:
REQUIRED
- CMake 2.8.11 or later
- gcc 4.2.1 or later (*nix), or Visual Studio 2010 or later (windows)
- pkg-config
OPTIONAL
- Doxygen 1.8.2 or later (optional, for API documentation generation)
- lcov version 1.9 or later (*nix, optional, for code coverage reporting)
- valgrind version 3.8.1 or later (*nix, optional, for memcheck reporting)
On OSX, if you're using Homebrew, you will need to do the following:
brew install expat c-ares libevent libidn opensslbrew link --force openssl expat
The latter command might cause other packages to fail in interesting ways; if so, you can undo it with brew unlink openssl expat.
On Unix and Linux (but not on OS X), valgrind requires debug symbols in system libraries to accurately report errors or, in the case of glibc, to successfully execute. See discussion at:
http://forums.gentoo.org/viewtopic-p-6169375.html?sid=1dec34d64643af26295011dd33711245#6169375
CMake will generate a build system appropriate for your platform. First, install CMake for your platform. Then, (*nix) in the build sub directory of the workspace root, execute:
- (*nix)
./build.sh - (Windows) run the cmake-gui tool and select the workspace root as the
source directory and the
buildsub directory as the binary output directory
You can choose to generate Makefiles, Visual Studio projects, Eclipse projects, or any of the many other output targets that CMake supports. Once you generate the build system for the first time, you should not need to run CMake explicitly again. It will auto-detect when relevant files change and re-generate itself as necessary.
The resulting build system will have the following high-level targets:
| Target | Description |
|---|---|
| build the jabberwerx library and related code; no docs or packaging | |
| test | run unit tests |
| docs | build and generate documentation |
| valgrind | (non-Windows only) run unit tests under valgrind |
| package | builds, tests, documents, and packages into a distributable archive |
There are also a number of options that can be set via ccmake or cmake-gui that affect the build. Their default values are indicated below with a +/- prefix:
| Option | Description |
|---|---|
+build_examples |
build example applications along with the jabberwerx library |
-build_jwcunicode |
build the jwcunicode example, whose additional build requirements are listed in src/examples/jwcunicode/README |
+build_tests |
build unit tests along with the jabberwerx library; they are not run unless the 'test' target is explicitly specified |
+debug_symbols |
keep debug symbols in the built code |
-do_coverage |
create coverage report after the 'test' target completes |
+enable_bosh |
if disabled, creation of BOSH streams will fail with an error code of JW_ERR_NOT_IMPLEMENTED and the curl library will not be built or distributed |
+enable_stringprep |
if disabled, jids are assumed to be ascii and are normalized by simple lowercasing; libidn is not built or distributed |
+enable_tls |
if disabled, connections will fail if starttls is required and TLS-related functions will fail with an error code of JW_ERR_NOT_IMPLEMENTED |
-fatal_warnings |
treat build warnings as errors; should be enabled by developers to ensure high code quality |
-optimized_build |
pass optimization flags to the compiler |
('$' indicates the console prompt):
$ cd path/to/jwc
$ ./build.sh
Windows example:
- run
cmake-gui - select jwc root as source dir
- select
buildsub directory as binary dir - click the Configure button
- select "Visual Studio 11" as the generator (For Visual Studio 2012)
- click the Generate button
- after generation is complete, browse to the
buildsub directory - double-click on the "JabberWerxC" Visual Studio Solution file
- use the Visual Studio GUI to build the project
- run
cmake-guiagain to change build options, if desired - re-run build in Visual Studio
###Notes###
- Xcode appears to crash while building third party code. It is suggested to use the default Makefiles generator on OSX for the time being.
- The Ninja generator does not yet implement implicit dependencies, which the build system uses heavily. However, building the individual targets works just fine. For example, with make, the default 'all' target will build everything, but with ninja you have to build the targets individually:
ninja thirdparty && ninja jabberwerx && ninja examples
Portions created or assigned to Cisco Systems, Inc. are Copyright (c) 2010 Cisco Systems, Inc. All Rights Reserved.
See LICENSE for details.
