Several steps must be follow to download, compile and use the libraries of the R project. All the source code is available through our subversion server svn.otlet-institute.org.

1 The R project

The R project (which is not related to the R programming language) was initiated around 1998. Its goal was to provide a set of open source cross platform C++ classes to facilitate the development of research oriented applications (in particular in the field of NP-hard optimization problems). The classes of the R project cover a wide range of functions : ordered containers of objects, text and XML file manipulation, basic matrix and graph operations, multiple genetic algorithms, etc.

At that time, the standard template library (STL) was not implemented by all compilers. Despite the availability of several open source libraries, the R project continued to be extended. Today, it is used by several research projects (such as the GALILEI platform) and industrial applications.

2 The libraries

Actually, the R project provides three libraries:

rcore The R Core library provides several basic classes to develop C++ applications.

rmath The R Math library provides a few classes implementing mathematical tools, in particular matrices.

roptimization The R Optimization library implements several genetic algorithms and the PROMETHEE multi-criteria decision method.

All the classes are defined in the R namespace.

3 The dependencies

The R libraries depend from two cross platform open source libraries:

libiconv (it is used to manipulate Unicode characters, in particular to handle text files).
libcurl (it is used to “open” a file that is only available on Internet).
POSIX Threads (for some very basic thread support).

In addition, the R libraries provides some optional support for a few other libraries:

SQLite client library (for a support of the SQLite database).
MySQL client library (for a support of the MySQL database).
PostgreSQL client library (for a support of the PostgreSQL database).
The Qt toolkit to use some graphical widgets (for example to display a XML structure).

4 Download and compile

The source code can downloaded from the GitHub repository:

https://github.com/pfrancq/r

The R libraries are managed through cmake. To build a given project, you must go to the root directory, create a sub-directory (for example ’build’) and go into it. In this latest directory, you must type:

cmake .. [OPTIONS] 
make or make VERBOSE=1

The most interesting options are:

-DCMAKE_BUILD_TYPE=Debug This option generates all the necessary debugging symbols.

-Ddisable-mysql=true This option disables the support for MySQL.

-Ddisable-sqlite=true This option disables the support for SQLite.

-Ddisable-postgres=true This option disables the support for PostgreSQL.

-Ddisable-qt=true This option disables the support for Qt.

For example, to compile a version of R without support for dabatases and Qt, type the following cmake command:

cmake .. -Ddisable-mysql=true -Ddisable-sqlite=true -Ddisable-postgres=true -Ddisable-qt=true

When the error ’Could NOT find PostgreSQL (missing: PostgreSQL_TYPE_INCLUDE_DIR)’ appears when you try to compile with the PostgreSQL support, this means that there is something wrong with the ’FindPostgreSQL.cmake’ file (stored in a directory such as ’/usr/share/cmake-2.8/Modules’ under Linux). A solution is to edit the file and add the following lines just before the instruction find_path(PostgreSQL_TYPE_INCLUDE_DIR):

if ( PostgreSQL_TYPE_INCLUDE_DIR )
else ( PostgreSQL_TYPE_INCLUDE_DIR) 
   set ( PostgreSQL_TYPE_INCLUDE_DIR ${PostgreSQL_INCLUDE_DIR}) 
endif ( PostgreSQL_TYPE_INCLUDE_DIR )

Then, when you relaunch the cmake command, it works.

For Windows

General

To download the R libraries on a Windows system, you need a svn client. TortoiseSVN provides a solution. It is a Windows shell extension that allows to manipulate svn repositories..

To compile the R libraries on a Windows system, the simplest approach is to first install MinGW which “provides a complete Open Source programming tool set which is suitable for the development of native MS-Windows applications”. It proposes a port of several tool of the GNU system (including the gcc compiler family). Let us suppose that you choose ’C:\MinGW’ as installation directory. Then, you install cmake and libiconv (libiconv is provided by MinGW). Finally, you must install libcurl (the “libcurl” or “devel” version).

Several environment variables should be created/modified to ensure that all programs, libraries and includes files are founded. The easiest way to do it, is to change them trough the menu “Properties” of the “Computer” icon (“Advanced System Parameters”\SpecialChar menuseparator“Environment Variables”). If you use Windows and MinGW, you must use / as separator in paths used by cmake rather than \ as usual for Windows.

The following environment variables must be extended with the values shown:

CMAKE_INCLUDE_DIR C:/MinGW/include

CMAKE_LIBRARY_DIR C:/MinGW/lib

CMAKE_C_COMPILER C:/MinGW/bin/cc

CMAKE_CXX_COMPILER C:/MinGW/bin/g++

PATH C:\MinGW\bin

Finally, when you run the cmake command, you must add the following option:

-G”MinGW Makefiles”

It is sometimes necessary to also specify the paths where cmake searches the libraries and the include files. By default, cmake will look in the directory ’C:\curl’. If you have install libcurl in another directory (for example ’C:\mycurl’), you must add the following options:

-Dcurl-include=”C:/mycurl/include” -Dcurl-library=”C:/mycurl/lib”

Once cmake has done its job, you must type at the command line:

mingw32-make

MySQL

For MySQL, it is only necessary to install the MySQL Connector C. If you install it in the directory ’C:\Program Files\MySQL\MySQL Connector C 6.1’, you must add the following options:

-Dmysql-library=”C:/Program Files/MySQL/MySQL Connector C 6.1/lib/vs11” \begin_inset Separator latexpar\end_inset

-Dmysql-include=”C:/Program Files/MySQL/MySQL Connector C 6.1/include”

where vs11 is the directory containing the library mysqlclient.lib. If cmake doesn’t find the headers, it is necessary to copy the file ’mysql.h’ in the directory ’C:\Program Files\MySQL\MySQL Connector C 6.1\include\mysql’.

Qt

If you want to work with Qt, you must install the version compiled MinGW. Once installed, it is a good idea to create an environment variable QTDIR pointing to the root directory containing Qt (such as ’C:/Qt/4.8.6’). It allows cmake to find the right Qt library you want to use.

For OS X

General

To download the R libraries on a OS X system, you need a svn client. One solution is to download and install the MacPorts Project. It provides a svn client.

To compile the R libraries on a OS X system, the simplest approach is to first install Xcode, Apple’s toolset for building applications. cmake proposes a GUI to generate the makefiles. Ideally, you should create a sub-directory (for example ’build’) where the compilation will be done. You can disable the different options (such as the support for some databases). Use Xcode as target. Once the makefiles are generate, you must type at the command line:

xcodebuild

Qt

You can install the Qt package for OS X provided.

MySQL

For MySQL, it is only necessary to install the MySQL Connector C. In the GUI of cmake, you have to specify the path for MySQL. If you install it in the directory ’/usr/local/mysql-connector-C-6.1.5-osx10.7-x86_64’, you must add the following options:

MYSQLCLIENT_INCLUDE_PATH /usr/local/mysql-connector-C-6.1.5-osx10.7-x86_64/include

MYSQLCLIENT_LIB_PATH /usr/local/mysql-connector-C-6.1.5-osx10.7-x86_64/lib/libmysqlclient.dylib

5 Using the R libraries

The R libraries can be used in two different ways:

The libraries and the include files are installed (for example in /usr/include/r and /usr/lib). This can be done after the compilation with the command:\begin_inset Separator latexpar\end_inset
```
sudo make install
```
The libraries can be used without to be installed. You may create an environment variable R_LIB pointing to the root directory containing the R libraries.If you use Windows and MinGW, you must use / as separator in paths used by cmake rather than \ as usual for Windows.

The simplest method to include the R libraries in your application is to use cmake for its management. First, copy the files in “cmake” sub-directory of the R project in the root directory of your application. Secondly, create in your root directory a file named “prj.cmake” which contains, at least, the following lines:

PROJECT(testr CXX)
R_LOAD_DEPENDENCY("R" "R_LIB" "r")
SET(SUB_PROJECT testr)
ADD_SUBDIRECTORY(src)

In this example, we suppose that your application is called “testr” and that the code sub-directory is “src”. In the code sub-directory, create a file called “CMakeLists.txt”. Such a file contains typically the following lines:

PROJECT(testr)
INCLUDE_DIRECTORIES(.)
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_BINARY_DIR})
ADD_EXECUTABLE(testr testr.cpp)
TARGET_LINK_LIBRARIES(testr rcore rmath roptimization)

After that, you create a sub-directory (for example ’build’) in root directory. To compile your application, go to that directory and type:

cmake .. [OPTIONS] 
make or make VERBOSE=1

You can add the option -DCMAKE_BUILD_TYPE=Debug to add the debugging symbols to your application.

For Windows

As for compiling the R libraries, you must add an option to cmake:

-G”MinGW Makefiles”

Then run the command line:

mingw32-make

To execute a Windows application, it it necessary to copy several Dynamic-link libraries (DLLs) in the same directory than the executable generated. The DLLs to copy depend from which packages you use in MinGW (and eventually in Qt). Typical examples are:

Use MinGW ’libgcc_s_dw2-1.dll’, ’libiconv-2.dll’, ’libstdc++-6.dll’ and ’libwinpthread-1.dll’.

Use Qt4 At least ’QtCore4.dll’ and ’QtGui4.dll’.

For OS X

In the GUI of cmake, you have to specify the path for R. If you install it in the directory ’/User/pascal/prj/r’, you must add the following options:

r-libs /User/pascal/prj/r