Installation Instructions
-------------------------


In Brief
~~~~~~~~

The following instructions apply to building libxs from an official release
downloaded from the Crossroads I/O website. For building directly from Git,
see below.

On POSIX platforms, libxs uses the standard autotools build system. To
build and install the library, ensure your system has a C++ compiler
installed, and proceed with the following steps:

1. Run `./configure`, then `make` to build the library.
2. Optionally, run `make test` to run the built in test suite.
3. Run `make install` as root.
4. On Linux or other platforms which use ld.so for dynamic linking, run
   `ldconfig` or equivalent as root to update your systems shared library
   cache.

On Windows, solution files for Visual C++ 2010 are provided in the
`builds/msvc/` subdirectory of the distribution.


Building from Git
~~~~~~~~~~~~~~~~~

If you are building libxs directly from the Git tree, on POSIX platforms
you will need to generate the `configure` script. This requires that you
have `autoconf` and `automake` installed on your system. To generate
`configure`, run `./autogen.sh`.

Note that documentation in UNIX 'man' and HTML formats will only be built
and installed from a Git tree if you have the `asciidoc` package installed
on your system.

Once you have generated `configure` you can follow the brief steps above.


Optional Features
~~~~~~~~~~~~~~~~~

libxs provides several optional features or extensions. These are enabled
using options to `configure`, or special project files for Windows.

Common optional features, and their options to `configure`:

ZeroMQ Compatibility::
   Specify `--enable-libzmq` to enable building and installation of the
   drop-in `libzmq` compatibility library for ZeroMQ applications. Note
   that this will *overwrite* any existing installation of `libzmq` on your
   system. For further details refer to `doc/xs_zmq.html` or 'xs_zmq(7)'.

PGM multicast support::
   Enabled with `--with-pgm` (using the copy of OpenPGM bundled with libxs)
   or `--with-system-pgm` (using your system installation of OpenPGM).
   Refer to `doc/xs_pgm.html` or 'xs_pgm(7)' for details on usage.


Other Common Options
~~~~~~~~~~~~~~~~~~~~

Specifying the installation directory::
   libxs is installed in `/usr/local` by default. To change this, specify
   the `--prefix` option to `configure`.

Selecting a poller implementation::
   libxs will normally pick the correct poller to use on your platform. If
   cross compiling, or building for an older system you may need to
   override this using the `--with-poller` option.

Disabling eventfd for older Linux::
   If building libxs to run on an older Linux kernel you may need to
   disable eventfd support. This can be done with the `--disable-eventfd`
   option.

Disabling building and installing documentation::
   Specifying `--without-documentation` disables any (re-)building or
   installation of the AsciiDoc-generated documentation. 

Refer to `./configure --help` for a full list of supported options, and
more information on settings affecting the build (e.g. cross compiling,
choosing a particular compiler version, and so on).