## Appendix - Building RCF

RCF is provided as source code, and is intended to be compiled along with the rest of the source code that comprises your application. To compile RCF, you only compile a single file - `RCF.cpp`, located in the distribution at `src/RCF/RCF.cpp`.

You can compile `RCF.cpp` directly into the same module as your own sources, or you can compile it into a static or dynamic library and subsequently link it into your application.

The Boost header files are RCF's only mandatory dependency. Other dependencies (zlib, OpenSSL, JSON-Spirit, Boost.FileSystem, Boost.Serialization, Protocol Buffers) are optional, and are enabled through the configuration macros listed further down.

In summary, to build RCF, you need to:

1. Make sure a version of the Boost library is available.
2. Make sure any relevant third party libraries are available.
3. Define any relevant configuration macros.
4. Compile RCF.cpp .
5. Link to any relevant third party libraries.

The actual details of compiling and linking depend on the compiler toolset you are using. If you are using Visual Studio, you will need to set include paths, compiler defines, linker paths, linker input in the project properties of your Visual C++ project. If you are using command line tools (in particular gcc, with some flavor of makefiles), you will need to set include paths, compiler defines, linker paths, and linker input on the relevant command lines.

For a simple example of building with Visual Studio 2010 and gcc, please see the Tutorial.

### Configuration

The following table lists all RCF build configuration macros:

Macro | Meaning | Requires linking to
--- | --- | ---
`RCF_USE_OPENSSL` | Build with OpenSSL support. | OpenSSL
`RCF_USE_ZLIB` | Build with zlib support. | Zlib
`RCF_USE_SF_SERIALIZATION` | Build with SF serialization support (defined by default). |
`RCF_USE_BOOST_SERIALIZATION` | Build with Boost.Serialization support. | Boost.Serialization
`RCF_USE_BOOST_FILESYSTEM` | Build with Boost.Filesystem support (required for file transfer support). | Boost.Filesystem
`RCF_USE_PROTOBUF` | Build with Protocol Buffer support. | Protocol Buffers
`RCF_USE_JSON` | Build with JSON Spirit (required for JSON-RPC support). |
`RCF_USE_IPV6` | Build with IPv6 support. |
`RCF_USE_CUSTOM_ALLOCATOR` | Build with custom allocator support. |
`RCF_BUILD_DLL` | Build a DLL exporting RCF. |
`RCF_AUTO_INIT_DEINIT` | Enable automatic RCF initialization and deinitialization. |

Building RCF without any of the configuration macros defined, is equivalent to building RCF with the `RCF_USE_SF_SERIALIZATION` define. If you build RCF with `RCF_USE_BOOST_SERIALIZATION` defined, `RCF_USE_SF_SERIALIZATION` is automatically not defined, and needs to be manually defined if you intend to use both Boost and SF serialization in the same build.

Make sure that all modules that will be linked together are compiled with the same set of RCF configuration macros, as some of the configuration macros are not ABI compatible with each other.

`RCF_USE_CUSTOM_ALLOCATOR` is used to customize memory allocation for network send and receive buffers. If you define `RCF_USE_CUSTOM_ALLOCATOR`, you will need to implement the following two functions:

    namespace RCF {
        void * RCF_new(std::size_t bytes);
        void RCF_delete(void * ptr);
    } // namespace RCF

`RCF_new()` and `RCF_delete()` will be called by RCF whenever allocating or deallocating memory for buffers of data that are being sent or received.

`RCF_BUILD_DLL` needs to be defined when building dynamic libraries, and will mark RCF classes and functions as DLL exports.

The `RCF_AUTO_INIT_DEINIT` define is provided, for users who want to preserve the automatic initialization and deinitialization behavior of earlier versions of RCF. With `RCF_AUTO_INIT_DEINIT` defined, a static object in RCF will automatically call `RCF::init()` when RCF is loaded, and `RCF::deinit()` when RCF is unloaded.

In RCF 2.0 and later, you are expected to initialize RCF explicitly, by calling `RCF::init()`.

RCF initialization is reference counted, which means RCF won't be deinitialized until you have called `RCF::deinit()` as many times as you have called `RCF::init()`. The `RCF::RcfInitDeinit` class will call `RCF::init()` from its constructor, and `RCF::deinit()` from its destructor, and can be used to make sure all calls to `RCF::init()` are matched with a subsequent call to `RCF::deinit()`.

### Third party library versions

For reference, these are versions of third party libaries RCF has been tested against. Newer versions of these libraries should also be fine to use.

Library | Version
--- | ---
Boost | 1.35.0 - 1.50.0
OpenSSL | 0.9.8d
Zlib | 1.2.1
Protocol Buffers | 2.1.0
JSON Spirit | 4.05

### Compilers

RCF has been tested against the following compilers:

- Visual C++ - any version newer than and including Visual C++ 7.1 (Visual Studio 2003).
- gcc - any version newer than and including gcc 3.4.

In addition, RCF will generally compile, possibly with minor modifications, on standard compliant compilers on most platforms. However, RCF releases are only tested against the compilers listed above.

### Platforms

RCF has been tested on the following platforms:

- Windows
- Linux
- Solaris
- FreeBSD
- OS X