Installing RoadRunner

Python Front End

The recommended way to use roadrunner is by installing the Python front end and writing Python scripts.

$ pip install libroadrunner

Building Roadrunner from Source

You will need:

  • CMake version > 3.14. The build system was developed with version 3.18.4.

  • Visual studio (windows only) with the C++ package installed.

  • git

If you are new to CMake, we recommend you read the cmake tutorial to get the basics before continuing.

The following instructions apply to Windwos, Mac OS and Linux. Where they diverge we will provide the specfic platform instruction.

Note

If at any point you get stuck or encounter an error please first read the Troubleshooting the build page and then if the problem is not resolved, submit a github issue and we’ll be more than willing to help.

On windows, you should use the “x64 Native Tools Command Prompt for VS 2019” shell which you can find by opening the start menu and begin typing “x64 Native Tools Command Prompt for VS 2019”. This will ensure you are building x64 bit application.

If you want to use new Windows Terminal you can set up the same environment by editing the windows terminal settings file: Add Developer Command Prompt

Warning

Failure to use the “X64 Native Tools Command Prompt for VS 2019” shell may result in 32-bit binaries.

1) Where to put Everything

On Windows it is recommended that you place all the files as close to a root on a drive as possible. This is because Windows has a 260 char limit on the length of a path which can be easily exceeded if you have a deep folder structure. One possibility is this. If for example you have a D drive (works equally well with the C drive), create a folder:

cd d:/
mkdir buildroadrunner  # You can call this whatever you like
cd buildroadrunner

Everything we need will go into buildroadrunner.

2) Install LLVM

Install the llvm-6.x dependency.

Note

For those wanting to build roadrunner in Debug mode, remember that you will need to download or build the llvm debug binaries, not release.

If you download the precompiled binaries for LLVM you get a top level folder called something like llvm-6.x-msvc2019-x64-release or llvm-6.x-msvc2019-x64-debug.

Place this folder (which contains all the LLVM code) into your top level directory we crated in step 1) called buildroadrunner.

3) Install the Roadrunner Dependency Package

Install the roadrunner dependency package

See below for the script to use.

Note

In the following set of instructions you can replace every instance of the word “Release” with the word “Debug” (or another configuration) to build roadrunner in Debug mode.

Execute these commands in a windows/linux/mac shell.

Note that the first thing we do is cd to the root folder we created in Step 1, namely buildroadrunner.

cd d:/buildroadrunner
git clone https://github.com/sys-bio/libroadrunner-deps.git --recurse-submodules    # get the dependency package using git
cd libroadrunner-deps
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX="../install-Release" -DCMAKE_BUILD_TYPE="Release" .. # configure the dependency package
cmake --build . --target install --config Release # build the install target
cd ../../ # return to directory containing libroadrunner-deps

Note

Take note of where you put the roadrunner deps install tree (../install-Release here). It is required as argument to -DRR_DEPENDENCIES_INSTALL_PREFIX below.

At this point you will have a folder called buildroadrunner and inside that you’ll have at least two folders, one for the LLVM binaries (two of these if you downloaded the release and debug versions) and the folder libroadrunner-deps. This is shown below.

buildroadrunner | — llvm-6.x-msvc2019-x64-debug | — llvm-6.x-msvc2019-x64-debug | — libroadrunner-deps

4) Install Roadrunner

Install roadrunner using the following commands from a windows/linux/mac shell.

If you have not done so already, download or build llvm-6.x. The folder containing llvm’s bin, include and lib directories is the argument to LLVM_INSTALL_PREFIX below.

.. note::

    The following `cmake` command assumes that you are following these instruction exactly so the relative
    path `-DRR_DEPENDENCIES_INSTALL_PREFIX="../../libroadrunner-deps/install-Release"` will point to
    the `-DCMAKE_INSTALL_PREFIX` argument from step 2, i.e. the libroadrunner-deps cmake command.

git clone https://github.com/sys-bio/roadrunner.git # get roadrunner
cd roadrunner
mkdir build-release
cd build-release
cmake -DCMAKE_INSTALL_PREFIX="../install-Release" \
    -DLLVM_INSTALL_PREFIX="/full/path/to/where/you/put/llvm-6.x-release" \
    -DRR_DEPENDENCIES_INSTALL_PREFIX="../../libroadrunner-deps/install-Release" \
    -DCMAKE_BUILD_TYPE="Release" ..
cmake --build . --target install --config Release

The first cmake line above is quite long and you won’t be able to copy and paste it directly into the windows terminal. To avoid this, copy the long cmake line into an editor (such as notepad) and make it one line long. Then copy and paste into the Windows terminal.

Note: if you want to create a debug version, just swap instances of the phrase Release (or release) for Debug (or debug).

Roadrunner Optional Features

These are controlled by turning on or off desired options in cmake.

Note

Generally speaking, the cmake-gui tool is the best way to get a good oversight of the available options.

Build the Python Bindings

  1. Download SWIG version 3.0.0 for linux, macos or windows. It is just a zip file - decompress it and put it where you want it. SWIG is now installed and the swig executable is under the top level swig directory.

2) Configure or reconfigure cmake using the -DBUILD_PYTHON=ON option. If you installed swig globally or add the swig directory to the PATH environment variable, you will not need the -DSWIG_EXECUTABLE argument as swig.exe will be found automatically. However in most circumstances you will need to provide the path to the swig.exe using -DSWIG_EXECUTABLE. As per the instructions for [FindPython](https://cmake.org/cmake/help/git-stage/module/FindPython.html) you can build for specific Python environments by pointing -DPython_ROOT_DIR to the root of your Python installation. Using Conda environments and this variable makes it easy to build Python wheels for different Python versions.

cmake -DCMAKE_INSTALL_PREFIX="D:\roadrunner\install-msvc2019" \
    -DLLVM_INSTALL_PREFIX="D:\llvm-6.x\llvm\llvm-6.x-msvc-x64-release" \
    -DRR_DEPENDENCIES_INSTALL_PREFIX="D:\libroadrunner-deps\libroadrunner-deps-install" \
    -DCMAKE_BUILD_TYPE="Release" \
    -DBUILD_PYTHON=ON \
    -DPython_ROOT_DIR="/path/to/miniconda/env/root"
    -DSWIG_EXECUTABLE="path/to/swig3.0.0/executable/swig.exe" ..
cmake --build . --target install --config Release

Building the Roadrunner Plugins

To build the plugins use the -DBUILD_RR_PLUGINS=ON. When set to on, the BUILD_RR_PLUGINS option automatically turns on a set of variables. These include:

  • RR_PLUGINS_BUILD_SHARED_LIB

  • RR_PLUGINS_BUILD_C_API

  • RR_PLUGINS_BUILD_PYTHON_API

  • RR_PLUGINS_BUILD_TEST_MODEL_PLUGIN

  • RR_PLUGINS_BUILD_ADD_NOISE_PLUGIN

  • RR_PLUGINS_BUILD_CHISQUARE_PLUGIN

  • RR_PLUGINS_BUILD_AUTO2000_PLUGIN

  • RR_PLUGINS_BUILD_HELLO_PLUGIN

while the RR_PLUGINS_BUILD_STATIC_LIB option remains OFF.

$ cmake -DCMAKE_INSTALL_PREFIX="D:\roadrunner\install-msvc2019" \
    -DLLVM_INSTALL_PREFIX="D:\llvm-6.x\llvm\llvm-6.x-msvc-x64-release" \
    -DRR_DEPENDENCIES_INSTALL_PREFIX="D:\libroadrunner-deps\libroadrunner-deps-install" \
    -DCMAKE_BUILD_TYPE="Release" \
    -DBUILD_RR_PLUGINS=ON
$ cmake --build . --target install --config Release

Building roadrunner tests

I you want the tests compiled you need to add an extra option to the cmake command that was used in step 4 but is repeated here for convenience.

Use the -DBUILD_TESTS=ON option. Remember that in the following script to change Release to Debug is you are creating the debug version.

$ cmake -DCMAKE_INSTALL_PREFIX="../install-Release" \
    -DLLVM_INSTALL_PREFIX="/full/path/to/where/you/put/llvm-6.x-release" \
    -DRR_DEPENDENCIES_INSTALL_PREFIX="../../libroadrunner-deps/install-Release" \
    -DCMAKE_BUILD_TYPE="Release" \
    -DBUILD_TESTS=ON ..
$ cmake --build . --target install --config Release

You can run the tests using ctest on the command line, ensuring you are in the top level of your build tree (e.g D`:\buildroadrunner\roadrunner\build-debug` here).

$ ctest .

This will give you a short summary of the results of the tests. If you want detailed information you need to enter instead:

$ ctest --verbose .

Alternatively you can build the ctest-run target, which is more convenient when you want to run the test from within an IDE since you use the mouse to build the ctest-run target. In the background, this will run the following command, which you may also run manually.

$ cmake --build . --target ctest-run

Packaging Roadrunner

  • Windows: produces a zip file.

  • Linux: produces tar.gz and a debian package.

  • Macos: produces a tar.gz file.

First follow the instructions for installing roadrunner, including options for any other desired options such as tests, plugins or language bindings. Then rerun cmake using using the -DBUILD_PACKAGING=ON option.

$ cmake -DCMAKE_INSTALL_PREFIX="D:\roadrunner\install-msvc2019" \
    -DLLVM_INSTALL_PREFIX="D:\llvm-6.x\llvm\llvm-6.x-msvc-x64-release" \
    -DRR_DEPENDENCIES_INSTALL_PREFIX="D:\libroadrunner-deps\libroadrunner-deps-install" \
    -DCMAKE_BUILD_TYPE="Release" \
    -DBUILD_PACKAGING=ON
$ cmake --build . --target install --config Release
$ cmake --build . --target packaging --config Release