Setting up an IDE for RevBayes

Last modified on September 3, 2021

The easiest way to get started developing in RevBayes is to use an IDE such as XCode or Eclipse. You can also use your favorite text editor (e.g. vim or emacs). This page will provide some helpful tips on how to set up these development enviroments. See the Download page for instructions on how to obtain the source code.

Overview

Setting up Visual Studio Code for RevBayes development

Visual Studio Code (or VSCode) is an open-source text editor by Microsoft. You can download and install it here.

Prerequisites

You will first need to install RevBayes from source. Once RevBayes is installed you will need to open VSCode. Once VSCode is open you will need to select the RevBayes folder from wherever you have stored on your computer.

Now you will need to install three extensions to get RevBayes to work nicely. To do this click on the button shown below in VSCode.

Getting RevBayes working

Once here you need to search for the “C/C++ extension” , the “Cmake extension” , and the “CMake tools extension” . Now that these are installed, Cmake tools will prompt in the lower right asking you to locate the file named CMakeLists.txt. Choose the file located in the revbayes/src/CMakeLists.txt location. This will prompt a choice of compiler kit this should work with clang and gcc. This should begin building RevBayes using CMake and a new folder should appear in revbayes called build. This will contain the compiled files and will eventually be added to .gitignore if it is not currently you will need to add this to the .gitignore file. Specifically, add build/** and vscode/** to .gitignore. If the build does not start automatically click the build button (the gear icon) on the blue bar on the bottom of the screen.

Once the Cmake build finishes, you can setup debugging by clicking the triangle with the small beatle in the lower left. Now click on the gear shown below. This will open a new file called launch.json. You need to change the values for the "program:" object to the path where your rb executeable is. For example, "${workspaceFolder}/projects/cmake/rb". In vscode ${workspaceFolder} refers to the root folder of the project you opened. To test a specific rev script, change the value of the "args" object to a location of a Rev script.With that you can use debugging in VSCode by pressing the play button or using the command palette (CTRL/CMD + SHIFT + P) and using the “Cmake: Debug” command.

Setting up Eclipse for RevBayes development

Eclipse is a Java-based, cross-platform IDE with lots of nice features that make it convenient for RevBayes development. First, it’s cross-platform, and unlike Xcode, you can use any compiler you like (not just clang).

Prerequisites

Installing Eclipse CDT

To start writing C++ in Eclipse, you must obtain the Eclipse CDT (C/C++ Development Tooling) package. You can download a distribution of Eclipse that comes prepackaged with CDT from the CDT Downloads page.

If you already have Eclipse installed you can go to Help > Install New Software… and enter the p2 repository URL for your version of eclipse found on the CDT downloads page. Then check the Main Features box, click Next twice, accept the User Agreement, and restart Eclipse.

Important! When you first open Eclipse, you will be asked to choose a location for your workspace. Make sure to choose a location that is not inside the source directory of your project!

Create an Eclipse project for RevBayes

Assuming you have cloned the RevBayes github repository into the directory <revbayes-repo>, you can create a new C++ Eclipse project as follows:

  1. In Eclipse, go to File > New > Makefile Project with Existing Code
  2. Set the Name of the project to revbayes
  3. Select <revbayes-repo>/src as the Existing Code Location
  4. Select Cross GCC in Toolchain for Indexer Settings (you can change this later if you want).
  5. Click Finish

Configure the RevBayes project

You will need to configure your Eclipse project so it correctly compiles the revbayes CMake project.

Configure the PATH environment variable

If you installed the CMake command line tools in the default location :/usr/local/bin, you must add it to the PATH environment variable of your Eclipse project.

  1. In the Project Explorer view, highlight your revbayes project directory

  2. Go to Project > Properties, or right click on the project name and select Properties.
  3. Expand C/C++ Build and click on Environment
  4. Click on the PATH entry, click Edit… and add /usr/local/bin to the end of the Value eclipse-path

Configure the C/C++ build settings

The RevBayes CMake project uses a special build script build.sh to build the RevBayes executable. You must tell your Eclipse project to use this script as a build command.

  1. Click on C/C++ Build
  2. Uncheck Use default build command and in Build command, enter sh build.sh
  3. In Build directory, add ../projects/cmake to the directory path eclipse-build
  4. Click on the Behavior tab
  5. In Build (incremental build), enter -boost false eclipse-behavior
  6. Again, click on C/C++ Build
  7. Click Manage Configurations
  8. Click on New… to create a new configuration, and name it Debug

  9. Configure the Debug configuration by adding -debug true to the Build (incremental build) options eclipse-debug Now, if you set the active configuration to Debug, RevBayes will be compiled with debugger symbols that can be loaded by lldb or gdb. You can also set the active build configuration by going to Project > Build Configurations > Set Active

  10. Click Apply and Close

At this point, C/C++ Indexer will get to work indexing the RevBayes code, during which time Eclipse might appear to be unresponsive.

Configure the project to use spaces instead of tabs

RevBayes code is indented using spaces. However, by default Eclipse uses tabs. Configure your project to automatically insert 4 spaces when you press the Tab key.

  1. Open Eclipse > Preferences
  2. Expand C/C++ > Code Style
  3. Click on Formatter
  4. Click the New… button to create a new profile, name the profile (e.g. “spaces”) then click OK to continue
  5. Click the Indentation tab
  6. Under General Settings set Tab Policy to Spaces only
  7. Click OK and Apply and Close

Build the RevBayes project

The first time you build RevBayes, you will also need to build the included Boost libraries. You only need to do this once. To build the boost libraries, return to step 5 in the build configuration section and enter -boost true instead. Then after you’ve built the libraries, you can disable the Boost build flag by resetting -boost false.

With all the build settings correctly configured, you can build RevBayes by highlighting the project in the Project Explorer view, and then going to Project > Build Project. You can also right click on the project directory and select Build Project.

The Console view should display the progress of the compilation process.

You’re done! Now you can find the rb executable in the <revbayes-repo>/projects/cmake directory.

Tips

Setting up XCode for RevBayes development

XCode is an IDE for Mac OSX. XCode does not keep track of files, so each time you open your RevBayes project in Xcode you must pull the RevBayes master branch from git & remove reference to all of the source. Eclipse Oxygen does a cleaner job of managing the files; you do not need to pull from git each time you work in it.

Set up the XCode Project with an internal build system

  1. Open Xcode and in the Welcome to Xcode window, choose Create a new Xcode project.
  2. Select Command Line Tool and name it rb and click Next.
  3. Click New Folder to create an empty directory and name it whatever you’d like.
  4. Click Create.
  5. Delete all of the files and folders in each of the directories including main.cpp so that RevBayes is empty. You can do this by selecting the folders and files, right clicking and selecting delete. When asked, choose Move to Trash.
  6. Add the source files by selecting the appropriate directory and going to the File pull-down menu and selecting Add Files to rb.
  7. Click on Options at the button of the window, and under the Added Folders heading, select the Create Groups radio button.
    • Select the
      • revbayes/src/revlanguage
      • revbayes/src/core
      • revbayes/src/libs
    • directories and click Add.
    • Note: On some versions of XCode, you may need to click on the “Options” Tab, and choose “Create Groups” for the import to work properly. This is the default behavior on most XCode installs.
  8. Add the boost library to your Xcode project:
    • You have to install boost from another source and point your Xcode project to that version. If you use Homebrew as a package management system on your Mac, you can install boost using brew install boost. This will install the boost libraries in your /usr/local directory. To enable this version in your Xcode project, scroll to the Search Paths section in the Build Settings and add the following paths:
      • Header Search Paths: /usr/local/include
      • Library Search Paths: /usr/local/lib
  9. Add boost linker flags
    • Scroll to the Linking section in the Build Settings
    • Go to Other Linker Flags and double click on the space. This will bring up a box where you can add the following flags: -lboost_program_options, -lboost_filesystem, -lboost_system.

Add the RB_XCODE Preprocessor Macro to your Xcode project

  1. Select the RevBayes project and go to the Build Settings.
  2. Search for or Scroll down to the Apple Clang - Preprocessing heading and find the sub-heading named Preprocessor Macros.
  3. Double click on right hand column, click on the + and enter RB_XCODE. Do not replace the debug flag that is already present.

Check C++ language options

  1. Select the RevBayes project and go to the Build Settings.
  2. Search or scroll to: Apple Clang - Language - C++.
  3. Make sure C++ Language Dialect is set to GNU++17 [-std=gnu++17].

At this point, if everything has been setup correctly, you should be able to build the project. You can try by clicking on Product - Build or by using ⌘+B.

Set up the XCode Project with an external build system

Prerequisites

Create an Xcode project for RevBayes

  1. Open Xcode and in the Welcome to Xcode window, choose Create a new Xcode project.
  2. Click on the Cross-Platform tab at the top
  3. Select External Build System and name it rb (or whatever you’d like)
  4. Under Build Tool type the following directory /<path-to-revbayes>/revbayes/projects/cmake/build.sh
  5. Click Next.

Configure the build

  1. After clicking Next as directed above, you should see a screen that looks like this:
  2. On this screen, under Arguments type $(ACTION) -boost true -debug true, or if you haven’t built the boost libraries in RevBayes already. If you have then type $(ACTION) -boost false -debug true.
  3. Under Directory put /<path-to-revbayes>/revbayes/projects/cmake/.
  4. Add the source files by selecting the appropriate directory and going to the File pull-down menu and selecting **Add Files to **.
  5. This should open a screen that looks like this:
  6. Click on Options at the button of the window, and under the Added Folders heading, select Create as Folder References, and add to the target that was created in Step 2.
    • Select the following directories from the revbayes directory:
      • revbayes/src/revlanguage
      • revbayes/src/core
      • revbayes/src/libs
    • Click Add.
  7. At this point, if everything has been setup correctly, you should be able to build the project. You can try by clicking on Product - Build or by using ⌘+B.
  8. Once revbayes has built go to Product->Scheme->Edit Scheme, it should bring a window like this:
  9. Click on info, then go to executable and locate the newly built revbayes executable.
  10. Now you should be able to click the play button or ⌘+R, and you should see the revbayes command line prompt in the loading screen.

Setting up vim for RevBayes development

Vim is a text editor that some people love. It’s not an IDE, but it can provide useful IDE-like behaviors. If you are reading this, you are probably a vim-lover and already have a set of customizations that you like. Here are some more to consider.

YouCompleteMe

YouCompleteMe is an extremely useful plugin that provides suggestions as you type for function names, prompts about their arguments, etc. There are several steps to get it working.

Install dependencies

This seems to be sufficient on Ubuntu 16.04:

sudo apt-get install build-essential cmake python-dev python3-dev clang

Get the vim code itself

Grab these two plugins:

Put them wherever you put your plugins, e.g., .vim/bundle/ if you’re using Pathogen.

For YCM, you also need to get its submodules:

cd YouCompleteMe/
git submodule update --init --recursive

(If you manage your plugins as git subtrees, note that you probably can’t for YouCompleteMe because it contains submodules itself.)

Compile the YCM plugin

YCM has a compiled component as well as vim code. This may take a few minutes to run.

cd YouCompleteMe/
./install.py --clang-completer

Provide the compilation flags to YCM

The above was to install YCM in general. To use it specifically with RevBayes (or any other project), you need to give it information about the codebase. YCM-Generator is one way to do this.

cd revbayes/  # or wherever you keep revbayes
cd projects/cmake/build/
~/.vim/bundle/YCM-Generator/config_gen.py . # adjust the vim path if necessary

That should take a few seconds to run. Then move the result to the top-level directory:

mv .ycm_extra_conf.py ../../../

Try it out

That should be it. If YCM is working, when you open a revbayes .cpp or .h file, vim will ask Found revbayes/.ycm_extra_conf.py. Load?

If you find that you don’t want YCM operating on all your other filetypes, you can put something like this in your .vimrc.

let g:ycm_filetype_whitelist = { 'cpp': 1, 'c': 1, 'python': 1 }

Debugging with GDB

If you use vim, we recommend debugging in GDB. You’ll need to compile RevBayes with the -debug true flag:

./build.sh -debug true

The you can debug RevBayes with GDB:

gdb rb

See here for more on using GDB.