Back to Introduction. Forward to Getting started. Up to Contents.

RandomLib has been developed under Linux with the g++ compiler (versions 4.0 and later) and under Windows with MS Visual Studio 2005, 2008, and 10 (2010), 11 (2012), and 12 (2013). Earlier versions were tested also under Darwin and Solaris. It should compile on a wide range of other systems. First download either RandomLib-1.10.tar.gz or RandomLib-1.10.zip. Then pick one of the first three options below:

Installation with cmake. This is the preferred installation method as it will work on the widest range of platforms. However it requires that you have cmake installed.
Installation with GNU compiler and Make. This is a simple installation method that works with g++ and Gnu make on Linux and many Unix platforms.
Installation on Windows. This is a simple installation method that works with Visual Studio 2005 and 2008 under Windows. Use cmake if you use Visual Studio 2010.
Maintainer tasks. This describes addition tasks of interest only to the maintainers of this code.

The first installation method uses two important techniques which make software maintenance simpler

Out-of-source builds: This means that you create a separate directory for compiling the code. In the description here the directories are called BUILD and are located in the top-level of the source tree. You might want to use a suffix to denote the type of build, e.g., BUILD-vc9 for Visual Studio 9, or BUILD-shared for a build which creates a shared library. The advantages of out-of-source builds are:
- You don't mess up the source tree, so it's easy to "clean up". Indeed the source tree might be on a read-only file system.
- Builds for multiple platforms or compilers don't interfere with each other.
The library is installed: After compilation, there is a separate install step which copies the headers, libraries, and documentation to a "central" location. You may at this point delete the source and build directories. If you have administrative privileges, you can install RandomLib for the use of all users (e.g., in /usr/local). Otherwise, you can install it for your personal use (e.g., in $HOME/packages).

Installation with cmake

This is the recommended method of installation, however it requires that cmake be installed on your system. This permits RandomLib to be built either as a shared or a static library on a wide variety of systems. cmake can also determine the capabilities of your system and adjust the compilation of the libraries and examples appropriately.

cmake is available for most computer platforms. On Linux systems cmake will typically one of the standard packages and can be installed by a command like

  yum install cmake

(executed as root). On other systems, download a binary installer from http://www.cmake.org click on download, and save and run the appropriate installer. Run the cmake command with no arguments to get help. Other useful tools are ccmake and cmake-gui which offer curses and graphical interfaces to cmake. Building under cmake depends on whether it is targeting an IDE (interactive development environment) or generating Unix-style makefiles. The instructions below have been tested with makefiles and g++ on Linux and with the Visual Studio IDE on Windows.

Here are the steps to compile and install RandomLib:

Unpack the source, running one of

  tar xfpz RandomLib-1.10.tar.gz
  unzip -q RandomLib-1.10.zip

then enter the directory created

  cd RandomLib-1.10

Create a separate build directory and enter it, for example,
```
  mkdir BUILD
  cd BUILD 
```
Run cmake, pointing it to the source directory (..). On Linux, Unix, and MacOSX systems, the command is
```
  cmake .. 
```
For Windows, the command is typically one of
```
  cmake -G "Visual Studio 10" -D CMAKE_INSTALL_PREFIX=C:/pkg-vc10/RandomLib ..
  cmake -G "Visual Studio 9 2008" -D CMAKE_INSTALL_PREFIX=C:/pkg-vc9/RandomLib ..
```
The definitions of CMAKE_INSTALL_PREFIX are optional (see below). The settings given above are recommended to keep versions of RandomLib built with different versions of the compiler separate. If you need to rerun cmake, use
```
  cmake . 
```
possibly including some options via -D (see the next step).
cmake allows you to configure how RandomLib is built and installed by supplying options, for example
```
  cmake -D CMAKE_INSTALL_PREFIX=/tmp/random . 
```
The options you might need to change are
- COMMON_INSTALL_PATH governs the installation convention. If it is on ON (the Linux default), the installation is to a common directory, e.g., /usr/local. If it is OFF (the Windows default), the installation directory contains the package name, e.g., C:/pkg/RandomLib-1.10. The installation directories for the documentation and cmake configuration depend on the variable with deeper paths relative to CMAKE_INSTALL_PREFIX being used when it's ON:
  - documentation: OFF: doc/html; ON: share/doc/RandomLib/html;
  - cmake configuration: OFF cmake; ON: share/cmake/RandomLib;
- CMAKE_INSTALL_PREFIX (default: /usr/local on non-Windows systems, C:/Program Files/RandomLib on Windows systems) specifies where the library will be installed. For windows systems, it is recommended to use a prefix which includes the compiler version, as shown above (and also, possibly, whether this is a 64-bit build, e.g., cmake -G "Visual Studio 10 Win64" -D CMAKE_INSTALL_PREFIX=C:/pkg-vc10-x64/RandomLib ..) If you just want to try the library to see if it suits your needs, pick CMAKE_INSTALL_PREFIX=/tmp/random, for example.
- RANDOMLIB_LIB_TYPE (allowed values: SHARED, STATIC, or BOTH), specifies the types of libraries build. If RandomLib is built and installed with RANDOMLIB_LIB_TYPE=BOTH (the default), then two libraries are available as ${RandomLib_SHARED_LIBRARIES} and ${RandomLib_STATIC_LIBRARIES}.
- DISABLE_VECTOR_OPTIMIZATIONS (default: OFF). cmake determines whether your computer supports vector instructions (SSE2 for Intel or AltiVec for PowerPC). However if you expect to copy the library and executables which link to the library to a platform which does not support these instructions, then you'll need to set this flag to ON.
- DISABLE_BOOST (default: OFF). The boost library is used (optionally) by some of the example programs. Usually, it's OK to let cmake look for the library. However, sometimes it finds a version of boost which is incompatible with your compiler; in this case, set the flag to ON.
- CMAKE_BUILD_TYPE (default: Release). This flags only affects non-IDE compile environments (like make and g++). The default is actually blank, but this is treated as Release. Choose one of
```
    Debug
    Release
    RelWithDebInfo
    MinSizeRel
```
  (With IDE compile environments, you get to select the build type in the IDE.)
- RANDOMLIB_DOCUMENTATION (default: OFF). If set to ON, then html documentation is created from the source files, provided a sufficiently recent version of doxygen can be found. Otherwise, the html documentation will redirect to the appropriate version of the online documentation.
Build and install the software. In non-IDE environments, run
```
  make         # compile the library and the examples
  make test    # run some tests
  make install # as root, if CMAKE_INSTALL_PREFIX is a system directory
```
On IDE environments, run your IDE (e.g., Visual Studio), load RandomLib.sln, pick the build type (e.g., Release), and select "Build Solution". If this succeeds, select "RUN_TESTS" to build; finally, select "INSTALL" to install (RUN_TESTS and INSTALL are in the CMakePredefinedTargets folder). Alternatively, you run the Visual Studio compiler from the command line with
```
  cmake --build . --config Release --target ALL_BUILD
  cmake --build . --config Release --target RUN_TESTS
  cmake --build . --config Release --target INSTALL 
```
For maximum flexibility, it's a good idea to build and install both the Debug and Release versions of the library (in that order). If you use cmake to configure and build your programs, then the right version of the library (debug vs. release) will automatically be used.
The headers and library are installed in the include/RandomLib and lib directories under CMAKE_INSTALL_PREFIX. (dll dynamic libraries are installed in bin.) For documentation, open share/doc/RandomLib/html/index.html in a web browser.

Installation with GNU compiler and Make

This method requires the standard GNU suite of tools, in particular make and g++. This builds a static library and the examples.

Here are the steps to compile and install RandomLib:

Unpack the source, running

  tar xfpz RandomLib-1.10.tar.gz

then enter the directory created

  cd RandomLib-1.10

Edit
```
  include/RandomLib/Config.h 
```
If you are using a moderately new Intel processor include the line
#define HAVE_SSE2 1

If you are using a moderately new Power PC include the line
#define HAVE_ALTIVEC 1

RandomLib will build and run fine with neither of these lines; it'll just run somewhat slower. If your C++ compiler does not recognize the long double type (unlikely), insert
#undef HAVE_LONG_DOUBLE
Build and install the software:
```
  make             # compile the library and the examples
  make install     # as root 
```
If you have boost installed, then running the first command as
```
  make HAVE_BOOST_SERIALIZATION=1 
```
will include boost-specific code in the example RandomSave.cpp. The parallelization example RandomThread.cpp will be compiled using OpenMP by default. To turn this off use
```
  make HAVE_OPENMP=0 
```
The installation is in directories under /usr/local. You can specify a different installation directory with, for example,
```
  make PREFIX=/tmp/random install 
```
The headers and library are installed in the include/RandomLib and lib directories under PREFIX. For documentation, open share/doc/RandomLib/html/index.html in a web browser.

Installation on Windows

This method requires Visual Studio 2008 (or 2005). This builds a static library and the examples. If you only have Visual Studio 2010, use cmake to create the necessary solution file. RandomLib does not compile correctly with Visual Studio 2003.

Unpack the source, running
```
  unzip -q RandomLib-1.10.zip 
```
then enter the directory created
```
  cd RandomLib-1.10 
```
Edit
```
  include/RandomLib/Config.h 
```
If you are using a moderately new Intel processor include the line
#define HAVE_SSE2 1

RandomLib will build and run fine without this line; it'll just run somewhat slower.
Open windows/RandomLib-vc9.sln in Visual Studio 2008 (for Visual Studio 2005, replace -vc9 by -vc8).
Pick the build type (e.g., Release), and select "Build Solution".
The library and the compiled examples are in the windows/Release.
Copy the library windows/Release/RandomLib.lib and the headers in include/RandomLib somewhere convenient. The headers should remain in a directory named RandomLib. For documentation, open doc/html/index.html in a web browser.

Maintainer tasks

Check the code out of git with

  git clone -b master git://git.code.sf.net/p/randomlib/code randomlib

Here the "master" branch is checked out. There are three branches in the git repository:

master: the main branch for code maintenance. Releases are tagged on this branch as, e.g., v1.10.
devel: the development branch; changes made here are merged into master.
release: the release branch created by unpacking the source releases (git is not used to merge changes from the other branches into this branch). This is the default branch of the repository (the branch you get if cloning the repository without specifying a branch). This differs from the master branch in that some administrative files are excluded while some intermediate files are included (in order to aid building on as many platforms as possible). Releases are tagged on this branch as, e.g., r1.10.

In order to build a source distribution, configure with cmake and then run

  make dist

which will package the source tree for distribution as

  RandomLib-1.10.tar.gz
  RandomLib-1.10.zip

Finally,

  make package

or building PACKAGE in Visual Studio will create a binary installer for RandomLib. For Windows, this requires in the installation of NSIS. On Windows, you should configure RandomLib with PACKAGE_DEBUG_LIBS=ON, build both Release and Debug versions of the library and finally build PACKAGE in Release mode. This will get the release and debug versions of the library included in the package. (This has not been tested to any extent. Presumably people using RandomLib will be able to build it from the source.)

The script tests/test-distribution checks out the source from git, verifies that it builds correctly and prepares the release packages.

Back to Introduction. Forward to Getting started. Up to Contents.