Pygmalion

Pygmalion is a code indexing tool based on libclang for C and C++. The intention is to deliver the same kind of high quality code navigation that expensive commercial IDEs give you, accessible in a command-line form that fits the UNIX mindset and is easy to integrate into your editor of choice. Pygmalion consists of several utilities that work together:

pygmalion is the primary command-line interface to Pygmalion. Given a location in the source code, it can print information about the item found there. This includes definitions, references, the inheritance hierachy, callers and callees of functions, and other useful data. It can also provide metadata like the compiler flags used for compiling a file, or generate a clang compilation database or TAGS file for use with external tools.
pygmake is a wrapper for make that assists with indexing. In particular, it records the actual compiler flags used for compiling each file, ensuring that the index of each file is as accurate as possible. You don't need to use pygmake; you can set default compiler flags in pygmalion.yaml, use pygmalion index to manually record compiler flags for specific files, or import a compilation database generated by another tool. However, pygmake makes things much easier on large projects with complicated build systems.
pygd is the indexing daemon. It needs to be running for the other tools to work; you can run it by executing pygmalion start-server at the root of the project you want to index. It will automatically index files that are touched in the current directory, so you just need to save for Pygmalion to see your changes. pygd invokes pygindex-clang to do the actual indexing. In the long term, support for other indexers and more languages will be added.

Check the examples/ directory to see how to integrate Pygmalion with other tools, including emacs with irony-mode and vim with YouCompleteMe.

Requirements

The Haskell Platform 2013.2.0. On OS X, you can install it via homebrew with brew install haskell-platform. On Ubuntu 13.10, sudo apt-get install haskell-platform should suffice. On other platforms, check here.
Up-to-date Haskell LibClang bindings. For now you'll need to build from source using the llvm3.4 branch on Github, but I intend to merge that branch into the main repo soon.

Build Instructions

Run make. This will build the project and install it to your cabal executables directory, by default usually ~/.cabal/bin. You may need to add this to your path.

Usage

Change to the root of the project you want to index and run pygmalion init to initialize a .pygmalion directory there. Pygmalion stores all of the information about the project in this directory, including the configuration file pygmalion.yaml which you can customize if needed. (See the next section.) For simple make-based projects, the default configuration should be enough.

To actually index the project, run pygmalion start-server to start the indexing daemon. Pygmalion will immediately start indexing your project. For most projects, the default compiler flags will result in a poor quality index, so if you didn't specify appropriate flags in the configuration file it's advisable to immediately run a complete rebuild using pygmake. This will gather accurate compiler flags and greatly improve the quality of the index.

You can start using pygmalion queries to navigate the code in your project immediately. As new indexing results come in, results will become available for more and more of your project. For very large projects, this may take a while, but once you have the initial index the indexing daemon will automatically keep it up to date as you make changes to the source, check out branches, and pull in others' changes.

Configuring Pygmalion

pygmalion init will create a default configuration file in .pygmalion/pygmalion.yaml in your project root. You can customize this as needed. You will definitely need to if you are using a build system other than make, such as cmake, or compilers other than clang and clang++.

The best source of information on the options is currently examples/pygmalion.yaml.default in the Pygmalion source tree, but these docs will be improved soon.

Frequently Asked Questions

On Linux I get the error 'addWatch: resource exhausted (No space left on device)'.

The default inotify watch limit is too small for your project. Unfortunately, on many Linux installations the limit is unreasonably low by default. Try again after running sudo sh -c 'echo 1048576 > /proc/sys/fs/inotify/max_user_watches'. You can make this fix permanent by adding fs.inotify.max_user_watches=1048576 to /etc/sysctl.conf.