Setting up an IDE for RevBayes

Last modified on August 1, 2019

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.

Setting up CLion for RevBayes development

CLion is a cross-platform IDE for C and C++ by JetBrains. To work in CLion you need to install CMake.

First follow the install instructions for installing RevBayes from source. First navigate to wherever the revbayes directory is, then go to the projects/cmake directory. Here you should see that there is a build directory, go to that directory.

To set up CLion we need to use a compilation database which has the name compile_commands.json. To make this run cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON in this directory: <your path to revbayes>/revbayes/projects/cmake/build

After running this, within that directory you should have a compile_commands.json file.

Now open Clion, it should look something like this:

(screenshot)

Go to open and then navigate to the compile_commands.json file we just created. Click on open as project

This will open your project but right now on the left it should list all of the .cpp files alphabetically (not ideal).

To fix this, go to Tools -> Compilation Database -> Change Project Root and change that directory to the revbayes directory <your path to revbayes>/revbayes/

Making a build configuration for RevBayes

Open Preferences/Tools -> Build, Execution, Deployment -> Custom Build Targets

Screenshot

Name your configuration and click on the … by Build, then click the + in the window that pops up.

Screenshot

Next to program place the build.sh file found in <your path to revbayes>/revbayes/projects/cmake

In arguments type -boost false -debug true

Next to executeable find the RevBayes executeable which is in <your path to revbayes>/revbayes/projects/cmake.

Click OK

Now the screen should looks like this and it should build if you go to Build and clikc Build Project

screenshot

Running and debugging configurations

We need to set up CLion to run the executeable for debugging to do this do the following:

  1. Go to Run -> Edit Configurations
  2. Click on the + and go to Custom Build Application
  3. For target select the build configuration from above
  4. For executeable find the RevBayes program that was built
  5. For working directory put the revbayes directory
  6. Click Apply and then OK

Now you can run RevBayes by pressing Ctrl + R and set breakpoints and debug with Ctrl + D.

Screenshot

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, simply change these search paths:
      • Header Search Paths: /usr/local/include
      • Library Search Paths: /usr/local/lib
  9. Add the boost linker flag
    • 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 flag -lboost_program_options.

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 LLVM X.X - 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 LLVM X.X - C++ - Language **.
  3. Make sure C++ Language Dialect is set to Compiler Default.
  4. Make sure C++ Standard Library is set to Compiler Default
  5. If you get compile errors with these settings, you might want to change these to:
    • Make sure C++ Language Dialect is set to Gnu++ 98.
    • C++ Standard Library is set to libstdc++(Gnu C++)

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.