Skip to content

Building from Source

Jump to bottom Edit New page
Andrew Briand edited this page Aug 22, 2019 · 120 revisions

This guide assumes basic familiarity with git and command line. Please consult other tutorials if you need more information on these tools.

Other ways to obtain the software

  • Unless you want to contribute to RoadRunner's development, you may wish to take the easier option of simply installing via PyPI:
pip install libroadrunner

Preliminaries

  • This guide assumes familiarity with the following tools:
    • Git
    • CMake (you can use any front-end, e.g. GUI or console)
    • Since these instructions are platform-generic, you should have experience with your target toolchain. For example, if you are building using Visual Studio, you should know how to build the "INSTALL" target. Roadrunner supports three different toolchains (Visual Studio, Xcode, and Makefiles).

Release Builds

You may want to build the release version without the Visual Studio or other IDE setup that CMake gives you or because other tools like Ninja can parallelize builds faster. On windows this can be a tiny bit tricky if you want to use the MSVC toolchain.

If you run CMake from the command line, like with

cmake -G Ninja ..\..\source\libroadrunner-deps

CMake won't be able to find tools like mc and cl. You can't just add them to your path either because their path includes the Visual Studio version number, so when you upgrade you will still be using the old tooling (or worse).

Instead, run that same command under the Developer Command Line. You need to make sure that it's the correct command line for your target. So, if you're on a 64-bit, you need to run the x64 Native Developer Command Line. You can achieve the same thing by just running vcvarsall.bat with the appropriate argument (e.g. x64), which will set the appropriate environment variables. It's just a batch script that sets up environment variables with the correct versions of MSVC tools. Then run the CMake build command:

cmake --build . --config Release

Visual Studio Requirements

  • You must have the message compiler mc.exe somewhere on your system. It is most likely under C:\Program Files (x86)\Windows Kits, so do a search there and be prepared to use the file path to that executable when building dependencies.

  • The CMAKE_BUILD_TYPE parameter will only work on the latest version of Visual Studio 2017 or higher

Common Errors

  • If you get error LNK 2038: mismatch detected for '_ITERATOR_DEBUG_LEVEL'... it's probably because one of the projects was built in Debug mode, and another in Release mode. 2 is debug, and 0 is release. You probably want everything on Release mode. They have different implementations of STL structures, so they are incompatible.

RR directory

You will want to create a directory to house the entire roadrunner build, including not just this repo but also the libroadrunner-deps repo and LLVM. You should start by creating this file structure somewhere not admin-locked

<root>
├── build
│   ├── llvm
│   ├── libroadrunner-deps
│   └── roadrunner
├── install
│   ├── llvm
│   └── roadrunner
└── source
    ├── llvm
    ├── libroadrunner-deps
    └── roadrunner

<root> is the path to the folder that you put all of this in. We will refer back to it when needed.

You may want to create separate debug and release build and install folders if you are planning to use both build types, for example "build_debug" and "build_release" instead of just "build"

Note: install libroadrunner-deps to '$PREFIX/install/roadrunner' not '$PREFIX/install/libroadrunner-deps'

Space requirements

Building LLVM can take over 25 GB for both Release and Debug build files

Building the entire project: LLVM, roadrunner, and its dependencies for Debug and Release takes about 35 GB in total including source, build files, and installation directory

If you want to have separate build and install directories for debug vs release versions, that can easily go over 40-45 GB. In order to mitigate this, you can build & install the debug/release versions of libroadrunner-deps, since it changes so infrequently, then delete the build files.

Cloning the repositories

There are three repositories: roadrunner, libroadrunner-deps, and llvm. Each of these should live in their respective folders under <prefix>/source. For now there will be nothing under build or install. Later we will put the CMake generated build files in build, and after compiling some components will be installed to install.

If you don't know how to clone a repository from Github, now is a perfect time to learn. Here is a good introduction to command line and Git

Building libroadrunner's dependencies

  • Roadrunner has two sets of dependencies: LLVM and non-LLVM. LLVM can be built via a single CMake script. We also provide a single CMake script for building the rest of the dependencies.

LLVM

Note, this wiki is in the process of being updated, but LLVM 6.0 support is coming. Word of advice, if you need to build LLVM, start with release because it's much faster

Here are pre-built windows LLVM-6 libraries: llvm-release.tar.gz (233MB) llvm-release.7z (130 MB) llvm-debug.tar.gz (288MB) llvm-debug.7z (439MB)

  • Right now, only an edited version of LLVM 3.5.2 is supported. There are just a few small fixes to the LLVM source to get it to compile on Visual Studio greater than 2013. You can either download it here or you can read about the three lines of changes in this issue (460)
  • First, make sure that you have an up-to date version of CMake that has generators that correspond to the development environment that you will be using. For example, if you use Visual Studio 2017, you will need CMake at least above 3.0
    • Fun note: If you do need to install a newer version of CMake, it won't uninstall the older version, so make sure you're not just using the old version again.
  • Make sure that you are using the same generators and compilers for all of the build process
  • (We recommend using CMake to do an out-of-source build of LLVM. Install it to a non-system-wide directory. The Roadrunner team never uses Autotools to compile LLVM.)
  • In CMake, change the CMAKE_INSTALL_PREFIX to <root>/install/llvm
  • After you have generated the build files for LLVM, build the INSTALL project.
  • Once it is finished compiling, check <root>/install/llvm/bin and verify that llvm-config is there

Checklist

  • CMAKE_INSTALL_PREFIX set to <prefix>/install/llvm
  • LLVM_TARGETS_TO_BUILD set to X86

Non-LLVM

  • All dependencies other than LLVM are hosted in their own repository: https://github.com/sys-bio/libroadrunner-deps
  • In the directory <root>/source, run git clone https://github.com/sys-bio/libroadrunner-deps.git
  • This will create a directory <root>/source/libroadrunner-deps. Change to this directory.
  • Run CMake with your desired generator and options. Select <root>/source/libroadrunner-deps as your source directory and <root>/build/libroadrunner-deps as your build directory. Valid generates are Visual Studio 2015 64- or 32-bit, Xcode, and Unix Makefiles. Refer to the CMake manual on how to set options. The required options are as follows:
CMAKE_BUILD_TYPE=Release
CMAKE_INSTALL_PREFIX=<root>/install/roadrunner
  • Set LLVM_CONFIG to the path to the llvm-config executable, which should be under <prefix>/install/llvm/bin
  • If you are on Windows, you will need to pass in the path to your mc.exe You can find it under C:\Program Files(x86)\Windows Kits\ in one of the directories. Try searching, and you should find it.
CMAKE_MC_COMPILER=C:/Program Files (x86)/Windows Kits/[SOME OS NUMBER]/bin/x64/mc.exe
  • Build and install the project. For Visual Studio, run the INSTALL target. For Xcode, select the install target and hit run. For a Makefile build, run make install.

Checklist

  • LLVM_CONFIG set to the appropriate path (see above)
  • CMAKE_INSTALL_PREFIX set to <prefix>/install/roadrunner
  • CMAKE_BUILD_TYPE set to Release
  • CMAKE_MC_COMPILER properly set if on Windows

Note: when generating for Visual Studio on release mode, set VS to Release mode if it is not already. It may not be by default even if CMAKE_BUILD_TYPE is set to Release

Building Roadrunner

  • Navigate to <root>/source and run git clone [email protected]:sys-bio/roadrunner.git
  • This will create a directory <root>/build/roadrunner. Run CMake with your desired generator (Makefiles, XCode, or Visual Studio). The generator should be the same as the one used for the dependencies. Select <root>/source/roadrunner as your source directory. Select `/build/roadrunner as your build directory. Set the following options: 
CMAKE_BUILD_TYPE=Release (or Debug for a debug build)
CMAKE_INSTALL_PREFIX=<root>/install/roadrunner
LLVM_CONFIG_EXECUTABLE=/path/to/llvm-3.5.2/bin/llvm-config
THIRD_PARTY_INSTALL_FOLDER=<root>/install/roadrunner
RR_USE_CXX11=OFF
USE_TR1_CXX_NS=ON for Linux, OFF otherwise
LIBSBML_LIBRARY=<absolute-path-to-libsbml>               # May need to be set manually
LIBSBML_STATIC_LIBRARY=<absolute-path-to-static-libsbml> # May need to be set manually

Generate, then open the solution and build INSTALL for a VS build. Run make install for a Makefile build.

Note: when generating for Visual Studio on release mode, set VS to Release mode if it is not already. It may not be by default even if CMAKE_BUILD_TYPE is set to Release

Building Python

  • To build the Python wrapper, add the following options. These paths will, in general, be different across systems. Therefore, please make note of how your specific Python installation is configured and substitute the appropriate paths for the interpreter, library, and include directory below. If you are using Python3, this information may be easily obtained from the sysconfig module.
  • Note that each of the Python paths must be linked to the same installation, even if they are both 2.7 or 3.4, if you have multiple Python installations, please verify that these paths have the same prefix.
  • You will also have to install the SWIG executable and link to it in CMake. Specifically, set:
SWIG_DIR=<swig-main-folder>/Lib
SWIG_EXECUTABLE=<swig-main-folder>/swig.exe
  • Building the Python wrapper in Debug mode is difficult because it wants to look for Python debug libraries and you may not have those
  • Sometimes you may have some trouble with your specific installation of Python, but if you have Spyder for Tellurium installed you can always compile against Tellurium's Python installation and you probably won't get Tellurium specific errors
BUILD_PYTHON=ON
PYTHON_EXECUTABLE=/path/to/python-interp (python.exe)
PYTHON_LIBRARY=/path/to/python-lib (the lib that includes the version number, i.e. python36.lib for Python 3.6)
PYTHON_INCLUDE_DIR=/path/to/python/include/dir
  • Build and install the project. For Visual Studio, run the INSTALL target. For Xcode, select the install target and hit run. For a Makefile build, run make install.
  • You can verify that your roadrunner.py and _roadrunner.pyd were correctly compiled, using a pre-built Spyder for Tellurium distribution. If you look in the Tellurium install directory under, python-2.7.13.amd64/Lib/site-packages/roadrunner, you should find those two files. Save a copy of them, and copy your compiled versions into that directory. If you start Tellurium, and can run a model fine, then you have correctly built the Python wrapper.
Add a custom footer
Clone this wiki locally