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.

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.

Warning

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

1) 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.

2) Install the Roadrunner Dependency Package

Install the roadrunner dependency package

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.

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.

3) 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
cd build
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

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

Use the -DBUILD_TESTS=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_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 (D`:roadrunnerbuild` here).

$ ctest .

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