[[https://travis-ci.org/Andersbakken/rtags][https://travis-ci.org/Andersbakken/rtags.svg?branch=master]]

• Introduction
  RTags is a client/server application that indexes C/C++ code and keeps
  a persistent file-based database of references, declarations,
  definitions, symbolnames etc. There's also limited support for
  ObjC/ObjC++. It allows you to find symbols by name (including nested
  class and namespace scope). Most importantly we give you proper
  follow-symbol and find-references support. We also have neat little
  things like rename-symbol, integration with clang's "fixits"
  (http://clang.llvm.org/diagnostics.html). We also integrate with
  flymake using clang's vastly superior errors and warnings. Since
  RTags constantly will reindex "dirty" files you get live updates of
  compiler errors and warnings. Since we already know how to compile
  your sources we have a way to quickly bring up the preprocessed output
  of the current source file in a buffer.

While existing taggers like gnu global, cscope, etags, ctags etc do a
decent job for C they often fall a little bit short for C++. With its
incredible lexical complexity, parsing C++ is an incredibly hard task
and we make no bones about the fact that the only reason we are able
to improve on the current tools is because of clang
(http://clang.llvm.org/). RTags is named RTags in recognition of
Roberto Raggi on whose C++ parser we intended to base this project but
he assured us clang was the way to go. The name stuck though.

• TLDR Quickstart
  Build RTags, start rdm, index some files, (rtags-follow-symbol-at-point)
  #+BEGIN_SRC
  $ cd rtags
  $ cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=1
  $ make
  $ rdm &
  $ rc -J .
  $ # wait for rdm to be silent
  $ emacs src/rdm.cpp
  (require 'rtags)

Go to /Users/abakken/dev/rtags-master/src/rdm.cpp:30:34 if (Server *server = Server::instance())

/|\

|

(rtags-follow-symbol-at-point)

Your location is now on the definition of Server::instance()

#+END_SRC

• Installing RTags
  ** Prerequisites
  There are a few prerequisites you need to have in order to build RTags

1. libclang, preferrably 3.2 or higher, on Linux you may be able to
   use your distro 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
   [[http://llvm.org/releases/download.html][llvm.org]] and build it yourself.
2. A modern compiler. This means GCC >= 4.7 or Clang >= 3.2. RTags
   makes extensive use of C++11 features such as variadic templates
   and threading utility classes from the C++ standard library.
3. CMake (>= 2.8), the build system used by RTags.
4. RTags might very well work with much older emacsen but the oldest
   version we test with is 24.3.1. There's no particular effort made
   to support older versions but patches that make it work are
   welcome.

** C++11 on OS X

If you plan to tag projects using C++11 features on OS X then you'll
need a custom libclang, the default one built through homebrew does
not support using LLVM's [[http://libcxx.llvm.org/][libc++]]. You'll need to install one from
homebrew-versions instead and explicitly tell it to enable libc++. For
LLVM 3.6 the following works:

#+BEGIN_SRC
$ brew tap homebrew/versions
$ brew install llvm36 --with-libcxx --with-clang --without-assertions --rtti
#+END_SRC

or you can install clang and llvm from macports

#+BEGIN_SRC
sudo port install clang-3.5
#+END_SRC

** Building RTags
To build RTags, you need to checkout the repository's submodules, and
run CMake.

#+BEGIN_SRC
$ git submodule init
$ git submodule update
#+END_SRC

You can also download the sources from here:

https://github.com/Andersbakken/rtags-releases/raw/gh-pages/rtags.tar.bz2

or

https://github.com/Andersbakken/rtags-releases/raw/gh-pages/rtags.tar.gz

(I know this isn't how gh-pages are supposed to work but I couldn't
figure out the .io thing).

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.
#+BEGIN_SRC
$ mkdir build
$ cd build
$ cmake ..
$ make
$ make install
#+END_SRC
If you want to configure the build interactively, run =ccmake= (CMake
with an ncurses UI) instead of =cmake=.

• Finding clang
  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:
  #+BEGIN_SRC
  LLVM_CONFIG=/path/to/llvm-config cmake .
  #+END_SRC
  or
  #+BEGIN_SRC
  cmake -DLLVM_CONFIG=/path/to/llvm-config .
  #+END_SRC
  If you don't we will look for variations of the llvm-config
  executable name in your $PATH.

  The three things we need are:

  1. CLANG_CXXFLAGS
     Usually something like this:
     #+BEGIN_SRC
     $ llvm-config --cxxflags
     -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
     #+END_SRC

  2. CLANG_LIBDIR
     Usually something like this:
     #+BEGIN_SRC
     $ llvm-config --libdir
     /usr/local/Cellar/llvm36/3.6.0/lib/llvm-3.6/lib
     #+END_SRC
     We need this to locate clang's system headers and we will assume
     that they are located in:
     ${CLANG_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. CLANG_LIBS
     Usually something like this:
     #+BEGIN_SRC
     -L/usr/local/Cellar/llvm36/3.6.0/lib/llvm-3.6/lib -lclang
     #+END_SRC
     Unless specified we will take try to find these libraries using
     cmake's find_library features and/or assuming that they there
     will be a libclang.(so|dylib) in ${CLANG_LIBDIR}

Like with LLVM_CONFIG these variables can be override as a cmake
variable (cmake -DCLANG_LIBDIR=...) or an environment variable
(CLANG_LIBDIR=... cmake)

RTags uses C++11 features and requires a relatively new
compiler. Gcc version >= 4.8 or clang >= 3.2 works.

We also require the following libraries:

• libclang (Not sure what the minimum version is but >= 3.5 is
  recommended)
• libcurses (for some reason clang requires this)

• Setup

  rdm runs in the background and monitors all your indexed files for
  changes and reindexes when a source file or one of its dependencies
  is modified. Since clang is a fully compliant compiler it needs
  specific information about how your sources are compiled to be able
  to properly index them. This is done through telling rdm about the
  compile line like this:

#+BEGIN_SRC
$ rc -c gcc -I... -fsomeflag -c foobar.c
$ rc -J /path/to/a/directory/containing/compile_commands.json
#+END_SRC

• Normally one achieves this in one of these ways:

• Make the build system output all compilation commands. E.g. if
  you're using ninja (http://martine.github.io/ninja/) you can do
  something like this:

#+BEGIN_SRC
$ ninja -t commands | rc -c -
#+END_SRC

After this command rdm will index all the sources in your project.

If you're using cmake you can do this:

#+BEGIN_SRC
cmake . -DCMAKE_EXPORT_COMPILE_COMMANDS=1
rc -J .
#+END_SRC

This will produce a compile_commands.json which, if used with rc -J,
will index all your soures.

There are very likely similar things you can do with other build
systems that we're unfamiliar with.

• The other approach to getting your files indexed is to
  man-in-the-middle your compiler.

This can be done like this:

#+BEGIN_SRC

$ ln -s /path/to/rtags/bin/gcc-rtags-wrapper.sh /somewhere/that/is/in/your/path/before/usr/bin/gcc
$ ln -s /path/to/rtags/bin/gcc-rtags-wrapper.sh /somewhere/that/is/in/your/path/before/usr/bin/c++
$ ln -s /path/to/rtags/bin/gcc-rtags-wrapper.sh /somewhere/that/is/in/your/path/before/usr/bin/cc
$ ln -s /path/to/rtags/bin/gcc-rtags-wrapper.sh /somewhere/that/is/in/your/path/before/usr/bin/g++

#+END_SRC
E.g.
#+BEGIN_SRC

$ which -a gcc | xargs file
/home/abakken/bin/gcc: symbolic link to /home/abakken/dev/rtags/bin/gcc-rtags-wrapper.sh' /usr/bin/gcc: symbolic link to gcc-4.7'

#+END_SRC

Now every time you compile a file with which gcc rc will get its
grubby hands all over your command line and make sure RTags knows
about it.

RTags will group source files into projects based on some heuristics.

Essentially it will look for certain files/dirs (like
configure/CMakeLists.txt/scons.1/.git) etc to try to determine the
likely project root for each source file. For generated source files
that end up in the build dir we try to find the source root based on
similar heuristics around config.status/CMakeCache.txt etc. Usually
this works out reasonably well.

RTags' only gives you information about current project when you ask
for things by name. You can explicitly change the current project using:
#+BEGIN_SRC
$ rc -w foobar
#+END_SRC

We try to do it automatically for you by passing along information
about the current buffer when we call rc from elisp so that rdm can
update its current project on demand.

RTags keeps a cache of indexed data so you don't have to reindex
everything if you restart it.

The location of this data is by default ~/.rtags but can be overridden
by passing =--data-dir /other/dir= to rdm or putting something like
this in your ~/.rdmrc:

#+BEGIN_SRC
$ cat ~/.rdmrc
--data-dir=/other/dir
#+END_SRC

** Integration with =launchd= /(Mac OS X)/

On Mac OS X, you can set =rdm= can be run on demand, on your behalf,
by =launchd=, and have it exit cleanly after a period of inactivity.
This isn't quite plug-and-play, but should be worth the small amount
of effort.

1. Create a file, e.g., in emacs, with the following contents:

   #+BEGIN_SRC

Label com.andersbakken.rtags.agent ProgramArguments sh -c $RDM -v --launchd --inactivity-timeout 300 --log-file ~/Library/Logs/rtags.launchd.log Sockets Listener SockPathName $HOME/.rdm #+END_SRC

2. Replace =$HOME= with the absolute path to your home folder. Replace
   =$RDM= with the path to your copy of =rdm=, and add any command
   line parameters you might usually use.

   (The =SockPathName= entry relates to the name of the domain socket
   that =rdm= uses. The settings above are for the default value; if
   your command line options direct it to use some other name, please
   modify it to suit. Unfortunately =launchd='s configuration files
   are a bit naff, so you'll have to repeat yourself.)

3. Save the result as
   =~/Library/LaunchAgents/com.andersbakken.rtags.agent.plist=.

4. Run the following command from the terminal:

   : launchctl load ~/Library/LaunchAgents/com.andersbakken.rtags.agent.plist

   (This will happen automatically next time you log back in.)

5. Try using rtags, and you should find =rdm= will spring into life!

*** Notes

• =rdm= will automatically quit after 5 minutes of inactivity (this is
  what the =--inactivity-timeout 300= command line option is for), so
  it won't stick around hogging memory. But =launchd= will still be
  watching its socket for activity, and will relaunch it if necessary.

• You can watch =launchd='s logging by tailing
  =~/Library/Logs/rtags.launchd.log=.

• Usage

  Now that your files are indexed you can start using rtags. Normally
  you would do this from your editor but the way to extract this
  information from rdm is to use the command line tool rc.

  E.g.
  #+BEGIN_SRC
  $ rdm &
  $ ninja -t commands | rc -c
  $ rc --follow-location Job.cpp:20:10
  /home/abakken/dev/rtags/src/Job.h:10:18 List *mPathFiltersRegExp;
  #+END_SRC

  A location has the format of file:line:column.

  For Emacs we maintain a set of elisp bindings that allows you to
  control rtags from your editor. There are projects that provide
  integration for other editors out there.

  Vim: https://github.com/lyuts/vim-rtags and https://github.com/shaneharper/vim-rtags

  Sublime Text: https://github.com/rampage644/sublime-rtags

  rc has a vast number of commands and options and we intend to write a
  man page at some point. Most users will have limited interest in ever
  calling them manually and would rather just use the interactive elisp
  functions.

• Elisp
  There are lots of interactive functions to call:

#+BEGIN_SRC
(rtags-find-symbol-at-point)
#+END_SRC

Follow symbol under cursor. For references this goes to the definition
(or declaration if no definition is known of the symbol. For
declarations it goes to the definition and vice versa. For definitions
of variables/parameters with constructors it goes to the constructor
in question. If you pass a prefix argument, limit to current source
file, if you pass a prefix argument and have narrowed the current
file, limit to the narrowed region. This prefix argument is the same
for: =rtags-find-references-at-point=, =rtags-find-symbol=,
=rtags-find-references=

#+BEGIN_SRC
(rtags-find-references-at-point)
#+END_SRC
Find all references to symbol under cursor. If symbol is itself a
reference it will find all references to the referenced symbol

#+BEGIN_SRC
(rtags-find-symbol)
#+END_SRC
Prompt for name of symbol to go to. Imagine the following code:
#+BEGIN_SRC

namespace N
{
class C
{
public:
int func(int);
};
};

using namespace N;
int C::func(int val)
{
return val * 2;
}
#+END_SRC
int N::C::func(int) will now be accessible by the following names:

• func
• func(int)
• C::func(int)
• C::func
• N::C::func(int)
• N::C::func

#+BEGIN_SRC
(rtags-find-references)
#+END_SRC

Prompt for name of symbol to find references to. Same as above but
find references to symbol rather than declarations and definitions.

#+BEGIN_SRC
(rtags-diagnostics)
#+END_SRC

Start an async process in a buffer to receive warnings/errors from
clang whenever a file gets reindexed. It integrates with flymake to
put highlighting on code with warnings and errors

#+BEGIN_SRC
(rtags-enable-standard-keybindings)
#+END_SRC
Sets up a ton of standard keybindings under C-x r (we try to avoid
crashing with the register shortcuts). If you pass a mode to the
function it will set it up on that mode, otherwise it will use
c-mode-base-map).

#+BEGIN_SRC
(rtags-find-file)
#+END_SRC

Lets you jump to file by name (partial or full, concept kinda stolen
from gtags.el) with completion in the project. This includes all files
under what we determine to be the root of the project, not just source
files.

#+BEGIN_SRC
(rtags-find-virtuals-at-point)
#+END_SRC
For virtual functions, show the various reimplementations of the
function at point

#+BEGIN_SRC
(rtags-fixit)
#+END_SRC
Apply clang's automatic fixits in current file. If you pass a
prefix arg use ediff to apply it. See
(http://clang.llvm.org/diagnostics.html) for more info.

#+BEGIN_SRC
(rtags-imenu)
#+END_SRC
Provices an ido-based imenu like interface to a subset of the
symbols in the current file. Note that it does not actually use
imenu infrastructure.

#+BEGIN_SRC
(rtags-location-stack-back)
(rtags-location-stack-forward)
#+END_SRC

Whenever RTags jumps somewhere it pushes a location onto its
stack. Jump back and forward in this stack

#+BEGIN_SRC
(rtags-next-match)
(rtags-previous-match)
#+END_SRC

For functions that return more than one match, jump to the
next/previous one.

#+BEGIN_SRC
(rtags-preprocess-file)
#+END_SRC
Preprocess current file according to known C(XX)Flags and show the
result in a buffer. If region is active only display the
preprocessed output for that region.

#+BEGIN_SRC
(rtags-print-symbol-info)
#+END_SRC
Print some info about symbol under cursor

#+BEGIN_SRC
(rtags-symbol-type)
#+END_SRC
Print the type of the symbol under cursor.

#+BEGIN_SRC
(rtags-print-dependencies)
#+END_SRC
Open a buffer showing files that depend on current file/files that
current file depends on.

#+BEGIN_SRC
(rtags-print-enum-value-at-point)
#+END_SRC
Print integral value of enum value at point

#+BEGIN_SRC
(rtags-quit-rdm)
#+END_SRC
Shut down rdm

#+BEGIN_SRC
(rtags-rename-symbol)
#+END_SRC
Rename symbol under cursor. Make sure all files are saved and fully
indexed before using.

#+BEGIN_SRC
(rtags-reparse-file)
#+END_SRC
Explicitly trigger a reparse of current file. Mostly for
debugging. Unless we have bugs it should not be necessary.

#+BEGIN_SRC
(rtags-show-rtags-buffer)
#+END_SRC
Switch to =RTags= buffer. This is the buffer where a number of
functions display their alternatives when they have more than one
match.

Variables:

#+BEGIN_SRC
rtags-path
#+END_SRC
Path to rc/rdm if they're not in =$PATH=.

#+BEGIN_SRC
rtags-jump-to-first-match
#+END_SRC
Similar to =compilation-auto-jump-to-first-error=. Whether to jump to
the first match automatically when there's more than one.

#+BEGIN_SRC
rtags-find-file-case-insensitive
#+END_SRC
Whether to match files case-insensitively

#+BEGIN_SRC
rtags-find-file-prefer-exact-match
#+END_SRC
Whether to exclude partial matches for file names when an exact
match is found. E.g.
=/foobar.cpp=
=/bar.cpp=
If =rtags-find-file-prefer-exact-match= is =t= a query for =bar.cpp=
would only return =/bar.cpp=, otherwise both =foobar.cpp= and =bar.cpp=
would be returned.

• Fall back to other taggers:
  You can do something like the following to fall back to e.g. gtags
  if RTags doesn't have a certain project indexed:

#+BEGIN_SRC
(defun use-rtags (&optional useFileManager)
(and (rtags-executable-find "rc")
(cond ((not (gtags-get-rootpath)) t)
((and (not (eq major-mode 'c++-mode))
(not (eq major-mode 'c-mode))) (rtags-has-filemanager))
(useFileManager (rtags-has-filemanager))
(t (rtags-is-indexed)))))

(defun tags-find-symbol-at-point (&optional prefix)
(interactive "P")
(if (and (not (rtags-find-symbol-at-point prefix)) rtags-last-request-not-indexed)
(gtags-find-tag)))
(defun tags-find-references-at-point (&optional prefix)
(interactive "P")
(if (and (not (rtags-find-references-at-point prefix)) rtags-last-request-not-indexed)
(gtags-find-rtag)))
(defun tags-find-symbol ()
(interactive)
(call-interactively (if (use-rtags) 'rtags-find-symbol 'gtags-find-symbol)))
(defun tags-find-references ()
(interactive)
(call-interactively (if (use-rtags) 'rtags-find-references 'gtags-find-rtag)))
(defun tags-find-file ()
(interactive)
(call-interactively (if (use-rtags t) 'rtags-find-file 'gtags-find-file)))
(defun tags-imenu ()
(interactive)
(call-interactively (if (use-rtags t) 'rtags-imenu 'idomenu)))

(define-key c-mode-base-map (kbd "M-.") (function tags-find-symbol-at-point))
(define-key c-mode-base-map (kbd "M-,") (function tags-find-references-at-point))
(define-key c-mode-base-map (kbd "M-;") (function tags-find-file))
(define-key c-mode-base-map (kbd "C-.") (function tags-find-symbol))
(define-key c-mode-base-map (kbd "C-,") (function tags-find-references))
(define-key c-mode-base-map (kbd "C-<") (function rtags-find-virtuals-at-point))
(define-key c-mode-base-map (kbd "M-i") (function tags-imenu))

(define-key global-map (kbd "M-.") (function tags-find-symbol-at-point))
(define-key global-map (kbd "M-,") (function tags-find-references-at-point))
(define-key global-map (kbd "M-;") (function tags-find-file))
(define-key global-map (kbd "C-.") (function tags-find-symbol))
(define-key global-map (kbd "C-,") (function tags-find-references))
(define-key global-map (kbd "C-<") (function rtags-find-virtuals-at-point))
(define-key global-map (kbd "M-i") (function tags-imenu))

#+END_SRC

• Videos
  Here are some videos demonstrating how to use RTags with Emacs though
  some of these may be outdated:

[[http://www.youtube.com/watch?v=Z4g05SjkQzM&list=PLAL6K6Ycnt4IwjIjWcYV9bFgcTG_4T1Y_&index=10][Set up RTags]]

[[http://www.youtube.com/watch?v=J2B-z0LBL_s&list=PLAL6K6Ycnt4IwjIjWcYV9bFgcTG_4T1Y_&index=6][Set up symlinks and run the daemon]]

[[http://www.youtube.com/watch?v=bD6Rlycn1RU&list=PLAL6K6Ycnt4IwjIjWcYV9bFgcTG_4T1Y_&index=5][Project setup using make]]

[[http://www.youtube.com/watch?v=Zivoc5DH_II&list=PLAL6K6Ycnt4IwjIjWcYV9bFgcTG_4T1Y_&index=9][Project setup using ninja]]

[[http://www.youtube.com/watch?v=IfenCEuOqOs&list=PLAL6K6Ycnt4IwjIjWcYV9bFgcTG_4T1Y_&index=2][Navigation/references]]

[[http://www.youtube.com/watch?v=wVoaE3Pj4oU&list=PLAL6K6Ycnt4IwjIjWcYV9bFgcTG_4T1Y_&index=1][Fixits]]

[[http://www.youtube.com/watch?v=mnQPz5J7gN0&list=PLAL6K6Ycnt4IwjIjWcYV9bFgcTG_4T1Y_&index=3]["IMenu" / virtuals / filenames]]

[[http://www.youtube.com/watch?v=p6JHriYmVuY&list=PLAL6K6Ycnt4IwjIjWcYV9bFgcTG_4T1Y_&index=4][Rename symbol]]

[[http://www.youtube.com/watch?v=9CsoJTs58q8&list=PLAL6K6Ycnt4IwjIjWcYV9bFgcTG_4T1Y_&index=8][Enums and cursor info]]

• Debugging RTags
  If you find that rp is crashing (leading to output like this: "job
  crashed 191 9698036154370 0x331e7e30"). You should be able to do the
  following:

#+BEGIN_SRC
$ rdm --suspend-rp-on-crash
#+END_SRC

When rp crashes the rp process will stay alive, enabling you to debug
it with something like this:

#+BEGIN_SRC
gdb -p pidof rp
#+END_SRC

• Support for other editors
  There are several other projects integrating RTags with other editors.

Sublime Text:
https://github.com/rampage644/sublime-rtags

Vim:
https://github.com/lyuts/vim-rtags
https://github.com/shaneharper/vim-rtags
https://github.com/mattn/vim-rtags

Note to those maintainers. If you need RTags to behave differently or
add features to make these other integrations easier (like produce
output in other formats etc), just drop us a note.

• Disclaimer
  RTags is still under development and is not the most stable piece of
  software you'll ever find. We're constantly working to improve on it.