What is Ratchet?
================

The purpose of the ratchet library is to provide a generic socket control
mechanism for large numbers of sockets without using threads or losing the ease
of synchronous socket programming. Implementations of standard Berkeley sockets
are provided, as well as rudimentary support for ZeroMQ sockets, provided
versions greater than or equal to 2.1.0 are installed. The polling mechanism is
written on top of libevent (http://monkey.org/~provos/libevent/).

The ratchet library provides and manages a blend of libevent event loops and
Lua coroutines to provide the effect of synchronous socket programming. Each
call to a blocking socket (or DNS or ZeroMQ) method actually yields execution
until the action is ready to be taken. Ratchet coroutines may also wait for each
other. Any application protocol (text-based or binary) can be implemented.
Currently, example HTTP and SMTP client and server implementations are provided,
see docs for details.

The project itself is built using autotools for portability, though it depends
on several GNU/Linux features. The project provides a suite of post-build tests
which double as sample usages, executed with "make check".

Build Information
=================

Lua 5.2+ is required to build, as this is a Lua library. Other than that, it
should work on most modern GNU/Linux systems with kernel 2.6+ and glibc2. If
your distribution or custom install added a suffixes to differentiate Lua
versions, you can use the configure option:

    --with-lua-suffix=ARG  Gives suffix for Lua binary and library files.

Many distributions do not yet include Lua 5.2 in package management. To avoid
blowing away an existing Lua 5.1 install, you might want to install Lua 5.2
somewhere unique. Let's say you installed in /opt/lua-5.2:

    PATH="/opt/lua-5.2/bin:$PATH" \
    CFLAGS="$CFLAGS -I/opt/lua-5.2/include" \
    LDFLAGS="$LDFLAGS -I/opt/lua-5.2/lib" \
    ./configure

If the paths to C and Lua module installation directories are not available from
pkg-config, they may need to be manually specified with:

    --with-lua-cpath=CPATH  Install Lua C modules to CPATH
    --with-lua-lpath=LPATH  Install Lua modules to LPATH

There are two different ways to use this library: from C or from Lua. By
default, both options are made available. If you don't need to use the library
from the Lua interpreter, you can choose to disable that with the configure
option:

    --disable-module       Disable the Lua module.

Similarly, if your Lua installation is custom, or the path to install Lua C
modules is not available in pkg-config, you can define a custom installation
path for the Lua module with a configure option:

    --enable-module=PATH   Install the Lua module ratchet.so to PATH.

If you do not need the developement libraries and headers installed, you can
choose to disable them with the configure option:

    --disable-devel        Disable developement headers and libraries.

By default, ratchet attempts to build with ZeroMQ (2.1.0+ is required). If you
do not need access to ZeroMQ sockets or do not meet the version requirement,
you can disable that portion of the library with a configure option:

    --disable-zeromq       Disable usage of ZeroMQ libraries.

By default, ratchet uses dns.c to provide enhanced DNS querying. If you do not
need access to DNS queries whatsoever, you can disable that portion of the build
with the configure option below. Note, however, that currently there is no
built-in method to build the data required for BSD sockets without this feature.

    --disable-dns          Disable usage of dns.c libraries.

To encrypt socket channels, ratchet can tie in to the OpenSSL suite. This is
important, for example, to implement HTTPS or the STARTTLS SMTP command. If
included in the build, the OpenSSL global state will be initialized every time
a program using the ratchet library is started, regardless of if/when
encryption is used (see `SSL_library_init()` and `SSL_load_error_strings()`).
OpenSSL will not be included in the build if the following configure option is
given:

    --disable-openssl      Disable usage of OpenSSL libraries.

For Linux users (see version requirements below), there is access to the
timerfd (man page `timerfd_create()`) routines for intelligent time keeping and
time-based triggers. If the requirements can't be met, this feature can be
disabled with a configure option:

    --disable-timerfd      Disabe usage of timerfd calls.

If, for any reason, you do not need access to BSD sockets (for example you only
need ZeroMQ, timers, or thread management), you can disable inclusion of these
features with another configure option:

    --disable-socket       Disable usage of BSD sockets.

Example protocol implementations, installed to the Lua module path, can be
disabled with the following configure options:

    --disable-http         Do not install HTTP protocol implementation.
    --disable-smtp         Do not install SMTP protocol implementation.

To increase the size of the buffer used when the size of a piece of data is
unknown, you can also use the following configure variable. Currently, it only
controls the size of the buffer used in `recv()` system calls.

    BUFSIZ    The size of the intermediate buffers used when building large
              Lua strings.

All other configure options are standard from GNU autotools.

Dependencies
============

* Lua 5.2+ (http://www.lua.org)
* libevent 2+ (http://libevent.org/)

* Without --disable-zeromq:  ZeroMQ 2.1.0+ (http://www.zeromq.org)
* Without --disable-timerfd: Linux kernel 2.6.25+, Glibc 2.8+
* Without --disable-openssl: OpenSSL (http://www.openssl.org/)