9  The standalone Rmath library

The routines supporting the distribution and special¹ functions in R and a few others are declared in C header file Rmath.h. These can be compiled into a standalone library for linking to other applications. (Note that they are not a separate library when R is built, and the standalone version differs in several ways.)

¹ e.g. Bessel, beta and gamma functions

The makefiles and other sources needed are in directory src/nmath/standalone, so the following instructions assume that is the current working directory (in the build directory tree on a Unix-alike if that is separate from the sources).

Rmath.h contains R_VERSION_STRING, which is a character string containing the current R version, for example "4.4.0".

There is full access to R’s handling of NaN, Inf and -Inf via special versions of the macros and functions

    ISNAN, R_FINITE, R_log, R_pow and R_pow_di

and (extern) constants R_PosInf, R_NegInf and NA_REAL.

There is no support for R’s notion of missing values, in particular not for NA_INTEGER nor the distinction between NA and NaN for doubles.

A little care is needed to use the random-number routines. You will need to supply the uniform random number generator

    double unif_rand(void)

or use the one supplied (and with a shared library or DLL you may have to use the one supplied, which is the Marsaglia-multicarry with an entry point

    set_seed(unsigned int, unsigned int)

to set its seeds).

The facilities to change the normal random number generator are available through the constant N01_kind. This takes values from the enumeration type

typedef enum {
    BUGGY_KINDERMAN_RAMAGE,
    AHRENS_DIETER,
    BOX_MULLER,
    USER_NORM,
    INVERSION,
    KINDERMAN_RAMAGE
} N01type;

(and USER_NORM is not available).

9.1 Unix-alikes

If R has not already been made in the directory tree, configure must be run as described in the main build instructions.

Then (in src/nmath/standalone)

make

will make standalone libraries libRmath.a and libRmath.so (libRmath.dylib on macOS): make static and make shared will create just one of them.

To use the routines in your own C or C++ programs, include

#define MATHLIB_STANDALONE
#include <Rmath.h>

and link against -lRmath (and -lm if needed on your OS). The example file test.c does nothing useful, but is provided to test the process (via make test). Note that you will probably not be able to run it unless you add the directory containing libRmath.so to the LD_LIBRARY_PATH environment variable (libRmath.dylib, DYLD_FALLBACK_LIBRARY_PATH on macOS).

The targets

make install
make uninstall

will (un)install the header Rmath.h and shared and static libraries (if built). Both prefix= and DESTDIR are supported, together with more precise control as described for the main build.

make install installs a file for pkg-config to use by e.g.

$(CC) `pkg-config --cflags libRmath` -c test.c
$(CC) `pkg-config --libs libRmath` test.o -o test

On some systems make install-strip will install a stripped shared library.

9.2 Windows

You need to set up² almost all the tools to make R and then run (in a Unix-like shell)

² including copying MkRules.dist to MkRule.local and selecting the architecture.

(cd ../../gnuwin32; make MkRules)
(cd ../../include; make -f Makefile.win config.h Rconfig.h Rmath.h)
make -f Makefile.win

Alternatively, in a cmd.exe shell use

cd ../../include
make -f Makefile.win config.h Rconfig.h Rmath.h
cd ../nmath/standalone
make -f Makefile.win

This creates a static library libRmath.a and a DLL Rmath.dll. If you want an import library libRmath.dll.a (you don’t need one), use

make -f Makefile.win shared implib

To use the routines in your own C or C++ programs using MinGW-w64, include

#define MATHLIB_STANDALONE
#include <Rmath.h>

and link against -lRmath. This will use the first found of libRmath.dll.a, libRmath.a and Rmath.dll in that order, so the result depends on which files are present. You should be able to force static or dynamic linking via

-Wl,-Bstatic -lRmath -Wl,Bdynamic
-Wl,-Bdynamic -lRmath

or by linking to explicit files (as in the test target in Makefile.win: this makes two executables, test.exe which is dynamically linked, and test-static.exe, which is statically linked).

It is possible to link to Rmath.dll using other compilers, either directly or via an import library: if you make a MinGW-w64 import library as above, you will create a file Rmath.def which can be used (possibly after editing) to create an import library for other systems such as Visual C++.

If you make use of dynamic linking you should use

#define MATHLIB_STANDALONE
#define RMATH_DLL
#include <Rmath.h>

to ensure that the constants like NA_REAL are linked correctly. (Auto-import will probably work with MinGW-w64, but it is better to be sure. This is likely to also work with VC++, Borland and similar compilers.)

Footnotes