Installing RTags

There are a few prerequisites you need to have in order to build RTags

• LLVM/Clang >= 3.3

  On Linux you may be able to use your distribution package manager to install this. On OS X you can use Homebrew or possibly other package managers, though see below for details if you plan to tag projects that use C++11 features (such as RTags itself). Alternatively you can grab the sources from llvm.org and build it yourself.

• GCC/Clang >= 4.9/3.3

  A modern compiler to build RTags. RTags makes extensive use of C++11 features such as variadic templates and threading utility classes from the C++ standard library.

• cmake >= 2.8

  The meta-built system used by RTags.

---

• Optional
  • emacs >= 24.3 is recommended

    RTags might very well work with much older emacs versions but the oldest version we have tested with is 24.3. There’s no particular effort made to support older versions, but patches that make it work are welcome. Having said that, completion (ac, company) as well as Flycheck integration only works, and has been tested with emacs >= 24.3.

    NOTE: Emacs is no real prerequisite. That implies you can compile RTags without emacs installed. This may be of interest to you, if you want use RTags as back-end for a different editor like vim, see section Support for other editors. You explicitly can tell cmake to ignore the elisp files by passing -DRTAGS_NO_ELISP_FILES=1 to cmake.

  • pkg-config and bash-completion

    RTags comes with bash completion support. If you want the bash completion files to be installed, you either have to make sure that pkg-config and bash-completion package is installed or you can manually force the installation by setting the variable FORCE_BASH_COMPLETION_INSTALLATION to TRUE or ON.

    The default installation path is CMAKE_INSTALL_PREFIX/share/bash-completion/completions. You can adjust the path with the cmake variable BASH_COMPLETION_COMPLETIONSDIR variable. However, if the bash completions files are not installed in the default completion path, i.e. /usr/share/bash-completion/completions on GNU/Linux, you have to make sure the RTags bash completion file gets sourced to get completion support.

  • ZLIB
  • OpenSSL

Installing requirements on OS X

If you plan to tag projects using C++11 features on OS X then you’ll need a libclang linked with LLVM’s libc++. For LLVM 3.9 the following works:

brew install llvm --with-libcxx --with-clang --without-assertions --with-rtti

Note that unless you link llvm

brew link llvm

You’ll likely have to tell cmake where to find llvm-config.

E.g.

$ PATH=/usr/local/Cellar/llvm/3.9.1/bin/:$PATH cmake /path/to/rtags
$ make

or you can install clang and llvm from mac ports

sudo port install clang-3.5

Building and installing RTags

• Get the code

  To build RTags, you need to checkout RTags and the repository’s sub-modules, this can be done in one step. After that, you need to run cmake, make and make install, in that order.

  git clone --recursive https://github.com/Andersbakken/rtags.git
      

  RTags releases are available for download under the releases page.

  The Source code (zip) and Source code (tar.gz) contain just the bare bone RTags source code. You need to download the rtags-VERSION.tar.bz2 or rtags-VERSION.tar.gz archive, to be able to build RTags.

• Building RTags

  We recommend building in a separate directory to keep the build files separate from the source, but you can run cmake in the source tree if you prefer.

  cd rtags
  mkdir build
  cd build
  cmake ..
  make
  make install
      

  TIP: You can run ccmake (CMake with an ncurses UI) instead of cmake to interactively configure the RTags build.

  Note that if you’re trying to test RTags by indexing RTags’ own source code you shouldn’t build it in tmp since RTags will refuse to index files in tmp

Installing RTags with the Emacs rtags.el package

You can install the Emacs Lisp part of RTags using package.el. For this you would need to add the MELPA/MELPA-Stable repository to the `package-archives` list.

• Adding MELPA source to the `package-archives` list

  (push '("melpa" . "https://melpa.org/packages/") package-archives))
      

• Installing rtags.el using package.el

  M-x package-install RET rtags RET
      

• Compile and install the binaries

  Once you have rtags.el installed from melpa you can use `rtags-install` to build and install the binaries of RTags. You still need to have a working compiler, LLVM/Clang and cmake installed.

  M-x rtags-install RET
      

  You may have to pass additional arguments to cmake for this to work. E.g. passing the cmake flag `-DRTAGS_NO_ELISP_FILES` to cmake. By the way, if you prefer to install the Emacs Lisp packages using package.el, you don’t need to byte-compile and install the packages. Than, this is the flag you would need to pass to cmake.

  M-: (rtags-install nil "-DRTAGS_NO_ELISP_FILES=1") RET
      

Finding clang

Use your System’s version

Unless you define RTAGS_BUILD_CLANG in cmake (or configure), the build system will try to locate the required LLVM/Clang libraries and options automatically from what is installed on your system.

RTags needs three pieces of information about libclang. All of these can be provided to cmake by way of an environment variable or a cmake variable. If not provided we will try to find llvm-config and interrogate it for the information. You can tell RTags which llvm-config to use like this:

LIBCLANG_LLVM_CONFIG_EXECUTABLE=/path/to/llvm-config cmake .

or

cmake -DLIBCLANG_LLVM_CONFIG_EXECUTABLE=/path/to/llvm-config .

If you don’t, we will look for variations of the llvm-config executable name in your $PATH. If llvm is installed at a different place, you could set the cmake variable CMAKE_PREFIX_PATH to the install prefix path of llvm.

The three things we need are:

1. LIBCLANG_CXXFLAGS

   Usually something like this:

   $ llvm-config --cxxflags
   # Max OS X
   -I/usr/local/Cellar/llvm36/3.6.0/lib/llvm-3.6/include  -DNDEBUG -D_GNU_SOURCE -D__STDC_CONSTANT_MACROS -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -O3  -std=c++11 -fvisibility-inlines-hidden -fno-exceptions -fno-common -Woverloaded-virtual -Wcast-qual
   # Fedora 23 64 bit
   -I/usr/include -DNDEBUG -D_GNU_SOURCE -D__STDC_CONSTANT_MACROS -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -O3  -std=c++11 -fvisibility-inlines-hidden -fno-exceptions -fno-common -Woverloaded-virtual -Wcast-qual
       

2. LIBCLANG_LIBDIR

   Usually something like this:

   $ llvm-config --libdir
   # Mac OS X
   /usr/local/Cellar/llvm36/3.6.0/lib/llvm-3.6/lib
   # Fedora 23 64 bit
   /usr/lib64/llvm
       

   We need this to locate clang’s system headers, and we will assume that they are located in: ${LIBCLANG_LIBDIR}/clang/CLANG_VERSION_STRING/include (/usr/local/Cellar/llvm36/3.6.0/lib/llvm-3.6/lib/clang/3.6.0/include). There should be headers like stdarg.h and limits.h in this directory.

3. LIBCLANG_LIBRARIES

   Usually something like this:

   # Mac OS X
   /usr/local/Cellar/llvm36/3.6.0/lib/llvm-3.6/lib/libclang.so
   # Fedora 23 64 bit
   /usr/lib64/llvm/libclang.so
       

   Unless otherwise specified, we will try to find the clang library using cmake’s find_library feature and/or assuming that they there will be a libclang.(so|dylib) in ${LIBCLANG_LIBDIR}

Like with LIBCLANG_LLVM_CONFIG_EXECUTABLE these variables can be overwritten as a cmake variable (cmake -DLIBCLANG_LIBDIR =...) or an environment variable (LIBCLANG_LIBDIR =... cmake)

Let the Build System download and Compile LLVM/Clang

By default, cmake searches for a system libclang. If you want it to download and build the required llvm/clang libraries, either call cmake with -DRTAGS_BUILD_CLANG=1 or configure with –build-clang

Note that if you use ninja to build RTags you might run into the following error:

ninja: error: '/usr/local/rtags-llvmclang/lib/libclang.dylib', needed by 'bin/rdm', missing and no known rule to make it

In that case you need to do this:

ninja llvmclang && ninja && ninja install