path: root/docs/WritingAnLLVMPass.rst

====================
Writing an LLVM Pass
====================

.. contents::
    :local:

Introduction --- What is a pass?
================================

The LLVM Pass Framework is an important part of the LLVM system, because LLVM
passes are where most of the interesting parts of the compiler exist.  Passes
perform the transformations and optimizations that make up the compiler, they
build the analysis results that are used by these transformations, and they
are, above all, a structuring technique for compiler code.

All LLVM passes are subclasses of the `Pass
<http://llvm.org/doxygen/classllvm_1_1Pass.html>`_ class, which implement
functionality by overriding virtual methods inherited from ``Pass``.  Depending
on how your pass works, you should inherit from the :ref:`ModulePass
<writing-an-llvm-pass-ModulePass>` , :ref:`CallGraphSCCPass
<writing-an-llvm-pass-CallGraphSCCPass>`, :ref:`FunctionPass
<writing-an-llvm-pass-FunctionPass>` , or :ref:`LoopPass
<writing-an-llvm-pass-LoopPass>`, or :ref:`RegionPass
<writing-an-llvm-pass-RegionPass>`, or :ref:`BasicBlockPass
<writing-an-llvm-pass-BasicBlockPass>` classes, which gives the system more
information about what your pass does, and how it can be combined with other
passes.  One of the main features of the LLVM Pass Framework is that it
schedules passes to run in an efficient way based on the constraints that your
pass meets (which are indicated by which class they derive from).

We start by showing you how to construct a pass, everything from setting up the
code, to compiling, loading, and executing it.  After the basics are down, more
advanced features are discussed.

Quick Start --- Writing hello world
===================================

Here we describe how to write the "hello world" of passes.  The "Hello" pass is
designed to simply print out the name of non-external functions that exist in
the program being compiled.  It does not modify the program at all, it just
inspects it.  The source code and files for this pass are available in the LLVM
source tree in the ``lib/Transforms/Hello`` directory.

.. _writing-an-llvm-pass-makefile:

Setting up the build environment
--------------------------------

.. FIXME: Why does this recommend to build in-tree?

First, configure and build LLVM.  This needs to be done directly inside the
LLVM source tree rather than in a separate objects directory.  Next, you need
to create a new directory somewhere in the LLVM source base.  For this example,
we'll assume that you made ``lib/Transforms/Hello``.  Finally, you must set up
a build script (``Makefile``) that will compile the source code for the new
pass.  To do this, copy the following into ``Makefile``:

.. code-block:: make

    # Makefile for hello pass

    # Path to top level of LLVM hierarchy
    LEVEL = ../../..

    # Name of the library to build
    LIBRARYNAME = Hello

    # Make the shared library become a loadable module so the tools can
    # dlopen/dlsym on the resulting library.
    LOADABLE_MODULE = 1

    # Include the makefile implementation stuff
    include $(LEVEL)/Makefile.common

This makefile specifies that all of the ``.cpp`` files in the current directory
are to be compiled and linked together into a shared object
``$(LEVEL)/Debug+Asserts/lib/Hello.so`` that can be dynamically loaded by the
:program:`opt` or :program:`bugpoint` tools via their :option:`-load` options.
If your operating system uses a suffix other than ``.so`` (such as Windows or Mac
OS X), the appropriate extension will be used.

If you are used CMake to build LLVM, see :ref:`cmake-out-of-source-pass`.

Now that we have the build scripts set up, we just need to write the code for
the pass itself.

.. _writing-an-llvm-pass-basiccode:

Basic code required
-------------------

Now that we have a way to compile our new pass, we just h