Remote Call Framework 3.4
Building RCF

Table of Contents

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.

RCF does not have any mandatory dependencies on any other libraries. Previous versions of RCF (2.2 and older) required the Boost header files to be available, but as of RCF 3.0, this is no longer the case.

RCF has several optional dependencies (zlib, OpenSSL, Protocol Buffers), which are enabled through the feature defines listed further down.

Let's assume now that you have downloaded RCF to a directory <rcf_distro> on your computer.

To build RCF, follow these steps:

  • Define any relevant RCF build or feature defines.
  • Set <rcf_distro>/include as an include path.
  • Compile <rcf_distro>/src/RCF/RCF.cpp .
  • Link to any relevant third party libraries.

Build Example

The actual details of compiling and linking will vary depending on the particular compiler you are using.

  • If you are using Visual Studio, you will need to set include paths, compiler defines, linker paths, and linker input in the project properties of your Visual C++ project.
  • If you are using command line tools (such as gcc or clang, with some flavor of makefiles), you will need to set include paths, compiler defines, linker paths, and linker input on the relevant command lines.

As an example, let's build the minimal TCP client and server, from the Sample Code section. To get started, create a source file called SampleTcpClientServer.cpp, and copy-paste the sample code into it. Then follow the instructions below:

Visual Studio

  • In the Visual Studio IDE, select New Project -> Visual C++ -> Win32 -> Win32 Console Application
  • In the Application Settings dialog, check the Empty Project checkbox.
  • In the Project Properties dialog for the new project, select C/C++ -> General -> Additional Include Directories.
  • Add the include path to RCF - <rcf_distro>\include.
  • Add the file SampleTcpClientServer.cpp to the project.
  • Add the file <rcf_distro>\src\RCF\RCF.cpp to the project.
  • Select Build -> Build Solution.

gcc

  • From the same directory as SampleTcpClientServer.cpp, run the following command:
g++ SampleTcpClientServer.cpp <rcf_distro>/src/RCF/RCF.cpp -I<rcf_distro>/include -lpthread -ldl -oSampleTcpClientServer

Dynamic and Static Linking

The example above compiled RCF.cpp directly into the same C++ module as SampleTcpClientServer.cpp. You can also compile RCF.cpp into a static or dynamic library.

  • To build a static library, set the relevant compiler switches for creating a static library, and compile RCF.cpp as usual.
  • To build a dynamic library, define RCF_BUILD_DLL in your build, set any relevant compiler switches for creating dynamic libraries, and compile RCF.cpp.

Build Defines

The following table lists RCF build defines.

Build define Meaning
RCF_BUILD_DLL Build a DLL exporting RCF.
RCF_USE_CUSTOM_ALLOCATOR Build with custom memory allocator support.
RCF_USE_CLOCK_MONOTONIC Use clock_gettime() to implement a monotonic clock.
RCF_MAX_METHOD_COUNT=<N> Extends the maximum number of methods allowed in a RCF interface.

Notes

RCF_BUILD_DLL

RCF_BUILD_DLL needs to be defined when building dynamic libraries. It marks public RCF classes and functions as DLL exports.

RCF_USE_CUSTOM_ALLOCATOR

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_USE_CLOCK_MONOTONIC

When RCF_USE_CLOCK_MONOTONIC is defined, RCF will use clock_gettime() with CLOCK_MONOTONIC, for internal clock functionality. Otherwise RCF uses gettimefoday() on POSIX platforms, and GetTickCount() on Windows platforms.

RCF_MAX_METHOD_COUNT=<N>

By default the maximum number of methods allowed in a RCF interface is 100. This limit can be changed by setting the RCF_MAX_METHOD_COUNT to a custom value. The maximum allowable value is 200.

Feature Defines

RCF comes with a set of feature defines, allowing users to build RCF with a specific set of features.

The following table lists all the available feature defines.

Feature define RCF feature Default value
RCF_FEATURE_SSPI Win32 SSPI-based encryption (NTLM, Kerberos, Schannel) 1 on Windows. 0 otherwise.
RCF_FEATURE_FILETRANSFER File transfers 0
RCF_FEATURE_SERVER Non-critical server-side functionality (server-to-client pingbacks, server objects, session timeouts) 1
RCF_FEATURE_PROXYENDPOINT Proxy endpoints 1
RCF_FEATURE_PUBSUB Publish/subscribe 1
RCF_FEATURE_TCP TCP transports 1
RCF_FEATURE_UDP UDP transports . 1
RCF_FEATURE_NAMEDPIPE Win32 named pipe transports 1 on Windows. 0 otherwise.
RCF_FEATURE_LOCALSOCKET Unix local socket transports 0 on Windows. 1 otherwise.
RCF_FEATURE_HTTP HTTP/HTTPS transports 1
RCF_FEATURE_IPV6 IPv6 support 1
RCF_FEATURE_SF RCF internal serialization 1
RCF_FEATURE_LEGACY Backwards compatibility with RCF 1.x and earlier 0
RCF_FEATURE_ZLIB Zlib-based compression. 0
RCF_FEATURE_OPENSSL OpenSSL-based SSL encryption. 0
RCF_FEATURE_PROTOBUF Protocol Buffer support. 0

To use these defines, set them to 0 or 1 depending on whether the feature should be included or not.

For example, to build RCF without HTTP/HTTPS support, define RCF_FEATURE_HTTP=0 in your build.

Notes

RCF_FEATURE_FILETRANSFER

The file transfer feature makes use of the standard C++ <filesystem> library. This library should be available on any compiler supporting the C++17 language update. Note that if you are using gcc or clang, you may need to use the -std=c++17 compiler option to enable C++17 support.

RCF_FEATURE_ZLIB

If you enable this feature by defining RCF_FEATURE_ZLIB=1, you will need to link to Zlib. It is possible to link statically to Zlib by defining RCF_ZLIB_STATIC.

RCF_FEATURE_OPENSSL

If you enable this feature by defining RCF_FEATURE_OPENSSL=1, you will need to link to OpenSSL. It is possible to link statically to OpenSSL by defining RCF_OPENSSL_STATIC.

RCF_FEATURE_PROTOBUF

If you enable this feature by defining RCF_FEATURE_PROTOBUF=1, you will need to link to Protocol Buffers.

Supported Compilers

RCF is written in standard C++ and as such should build on any recent standards-compliant compiler. RCF 3.0 has been tested on the following compilers:

  • Visual C++ 2015 (x86 and x64)
  • Visual C++ 2017 (x86 and x64)
  • gcc 7.0 (x64)
  • clang 4.0 (x64)

Supported Platforms

RCF has been tested on Windows and Linux platforms, but you should be able to use it on any of the following :

  • Windows
  • Linux
  • OS X
  • Solaris
  • FreeBSD