Setting up an IDE for RevBayes

Last modified on March 12, 2018

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 Software page for instructions on how to obtain the source code.

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

  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 - There are currently two options for doing this:
    1. Using the boost library packaged with RevBayes
      • Select the RevBayes project and go to the Build Settings.
      • Search for or Scroll down to the Search Paths heading and find the sub-heading named Header Search Paths.
        • Double click the heading, click the +, and add the value: <path to revbayes repository>/revbayes/boost_1_60_0.
        • where <path to revbayes repository> = the location of the revbayes repository on your machine.
      • Now do the same for the Library Search Paths, but make sure that you add the path to the lib directory in boost <path to revbayes repository>/revbayes/boost_1_60_0/stage/lib
    2. Using the boost library from Homebrew (or alternative install)
      • You can install boost from another source and point your Xcode project to that version. It is likely that this will be the way RevBayes will use boost in the near future. 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.

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