JabberWerxC
JabberWerxC copied to clipboard
cisco
A C API for XMPP connectivity
JabberWerxC
An API for XMPP connectivity.
Documentation
Documentation for the API is available at https://cisco.github.io/JabberWerxC/
Dependencies
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)
Building
JabberWerxC uses CMake as its build system, and supports at least Mac OS X and Linux platforms.
Prerequisites
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)
Setting up Mac OS X
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.
Setting up Unix/Linux
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
Generating the Build Environment
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.
Performing Builds
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 |
Build Example (*nix)
('$' indicates the console prompt):
$ cd path/to/jwc
$ ./build.sh
Build Example (Windows)
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
Copyrights
Portions created or assigned to Cisco Systems, Inc. are Copyright (c) 2010 Cisco Systems, Inc. All Rights Reserved.
See LICENSE for details.
cisco