+
Preliminaries
+
+ LLDB relies on many of the technologies developed by the larger LLVM project.
+ In particular, it requires both Clang and LLVM itself in order to build. Due to
+ this tight integration the Getting Started guides for both of these projects
+ come as prerequisite reading:
+
+
+
Supported compilers for building LLDB on Linux include:
+
+ - Clang 3.2
+ - GCC 4.6.2 (later versions should work as well)
+
+
It is recommended to use libstdc++ 4.6 (or higher) to build LLDB on Linux, but using libc++ is also known to work.
+
+ On FreeBSD the base system Clang and libc++ may be used to build LLDB,
+ or the GCC port or package.
+
+
+ In addition to any dependencies required by LLVM and Clang, LLDB needs a few
+ development packages that may also need to be installed depending on your
+ system. The current list of dependencies are:
+
+
+
So for example, on a Fedora system one might run:
+
> yum install swig python-devel libedit-devel
+
On a Debian or Ubuntu system one might run:
+
> sudo apt-get install build-essential subversion swig python2.7-dev libedit-dev libncurses5-dev
+
or
+
> sudo apt-get build-dep lldb-3.3 # or lldb-3.4
+
On FreeBSD one might run:
+
> pkg install swig python
+
If you wish to build the optional reference documentation, additional dependencies are required:
+
+ - Graphviz (for the 'dot' tool).
+
+ - doxygen (only if you wish to build the C++ API reference)
+
+ - epydoc (only if you wish to build the Python API reference)
+
+
+
To install the prerequisites for building the documentation (on Debian/Ubuntu) do:
+
+
> sudo apt-get install doxygen graphviz
+
> sudo pip install epydoc # or install package python-epydoc
+
+
Building LLDB
+
+ We first need to checkout the source trees into the appropriate locations. Both
+ Clang and LLDB build as subprojects of LLVM. This means we will be checking out
+ the source for both Clang and LLDB into the tools subdirectory of LLVM. We
+ will be setting up a directory hierarchy looking something like this:
+
+
+
+ llvm
+ |
+ `-- tools
+ |
+ +-- clang
+ |
+ `-- lldb
+
+
+
+ For reference, we will call the root of the LLVM project tree $llvm, and the
+ roots of the Clang and LLDB source trees $clang and $lldb respectively.
+
+
Change to the directory where you want to do development work and checkout LLVM:
+
> svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
+
+
Now switch to LLVM’s tools subdirectory and checkout both Clang and LLDB:
+
+ > cd $llvm/tools
+
> svn co http://llvm.org/svn/llvm-project/cfe/trunk clang
+
> svn co http://llvm.org/svn/llvm-project/lldb/trunk lldb
+
+
+
+ In general, building the LLDB trunk revision requires trunk revisions of both
+ LLVM and Clang.
+
+
+ It is highly recommended that you build the system out of tree. Create a second
+ build directory and configure the LLVM project tree to your specifications as
+ outlined in LLVM’s Getting Started Guide. A typical build procedure
+ might be:
+
+
+ > cd $llvm/..
+
> mkdir build
+
> cd build
+
+
To build with CMake
+
+ Using CMake is documented on the Building LLVM with CMake
+ page. Building LLDB is possible using one of the following generators:
+
+
+ - Ninja
+ - Unix Makefiles
+
+
Using CMake + Ninja
+
+ Ninja is the fastest way to build LLDB! In order to use ninja, you need to have recent versions of CMake and
+ ninja on your system. To build using ninja:
+
+
+ > cmake .. -G Ninja
+
> ninja lldb
+
> ninja check-lldb
+
+
Using CMake + Unix Makefiles
+
If you do not have Ninja, you can still use CMake to generate Unix Makefiles that build LLDB:
+
+ > cmake ..
+
> make
+
> make check-lldb
+
+
To build with autoconf
+
+ If you do not have CMake, it is still possible to build LLDB using the autoconf build system. If you are using
+ Clang or GCC 4.8+, run:
+
+
+ > $llvm/configure
+
> make
+
+
If you are building with a GCC that isn't the default gcc/g++, like gcc-4.9/g++-4.9
+
+ > $llvm/configure CC=gcc-4.9 CXX=g++-4.9
+
> make CC=gcc-4.9 CXX=g++-4.9
+
+
+ If you are running in a system that doesn't have a lot of RAM (less than 4GB), you might want to disable
+ debug symbols by specifying DEBUG_SYMBOLS=0 when running make. You will know if you need to enable this
+ because you will fail to link clang (the linker will get a SIGKILL and exit with status 9).
+
+
+ > make DEBUG_SYMBOLS=0
+
+
To run the LLDB test suite, run:
+
+
> make -C tools/lldb/test
+
+
+ Note that once both LLVM and Clang have been configured and built it is not
+ necessary to perform a top-level make to rebuild changes made only to LLDB.
+ You can run make from the build/tools/lldb subdirectory as well.
+
+
+ If you wish to build with libc++ instead of libstdc++ (the default), run configure with the
+ --enable-libcpp flag.
+
+
If you wish to build a release version of LLDB, run configure with the --enable-optimized flag.
+
Testing
+
+ By default, the check-lldb target builds the 64-bit variants of the test programs with the same
+ compiler that was used to build LLDB. It is possible to customize the architecture and compiler by appending -A and
+ -C options respectively to the CMake variable LLDB_TEST_ARGS. For example, to test LLDB against 32-bit binaries
+ built with a custom version of clang, do:
+
+
+
> cmake -DLLDB_TEST_ARGS="-A i386 -C /path/to/custom/clang" -G Ninja
+
> ninja check-lldb
+
+
Note that multiple -A and -C flags can be specified to LLDB_TEST_ARGS.
+
+ In addition to running all the LLDB test suites with the "check-lldb" CMake target above, it is possible to
+ run individual LLDB tests. For example, to run the test cases defined in TestInferiorCrashing.py, run:
+
+
+
> cd $lldb/test
+
> python dotest.py --executable <path-to-lldb> -p TestInferiorCrashing.py
+
+
+ In addition to running a test by name, it is also possible to specify a directory path to dotest.py
+ in order to run all the tests under that directory. For example, to run all the tests under the
+ 'functionalities/data-formatter' directory, run:
+
+
+
> python dotest.py --executable <path-to-lldb> functionalities/data-formatter
+
+
+ To dump additional information to stdout about how the test harness is driving LLDB, run
+ dotest.py with the -t flag. Many more options that are available. To see a list of all of them, run:
+
+
+
> python dotest.py -h
+
+
Building API reference documentation
+
+ LLDB exposes a C++ as well as a Python API. To build the reference documentation for these two APIs, ensure you have
+ the required dependencies installed, and build the lldb-python-doc and lldb-cpp-doc CMake targets.
+
+
The output HTML reference documentation can be found in <build-dir>/tools/lldb/docs/.
+
Additional Notes
+
+
+ LLDB has a Python scripting capability and supplies its own Python module named lldb.
+ If a script is run inside the command line lldb application, the Python module
+ is made available automatically. However, if a script is to be run by a Python interpreter
+ outside the command line application, the PYTHONPATH environment variable can be used
+ to let the Python interpreter find the lldb module.
+
+
The correct path can be obtained by invoking the command line lldb tool with the -P flag:
+
> export PYTHONPATH=`$llvm/build/Debug+Asserts/bin/lldb -P`
+
+ If you used a different build directory or made a release build, you may need to adjust the
+ above to suit your needs. To test that the lldb Python module
+ is built correctly and is available to the default Python interpreter, run:
+
+
> python -c 'import lldb'
+