| <!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> |
| <link href="style.css" rel="stylesheet" type="text/css" /> |
| <title>Building LLDB</title> |
| </head> |
| <body> |
| <div class="www_title"> |
| The <strong>LLDB</strong> Debugger |
| </div> |
| |
| <div id="container"> |
| <div id="content"> |
| |
| <!--#include virtual="sidebar.incl"--> |
| |
| <div id="middle"> |
| <h1 class="postheader">Continuous Integraton</h1> |
| <div class="postcontent"> |
| <p> |
| The following LLVM buildbots build and test LLDB trunk: |
| <ul> |
| <li> <a href="http://lab.llvm.org:8011/builders/lldb-x86_64-debian-clang">LLDB Linux x86_64 build with Clang (automake)</a> |
| </li> |
| <li> <a href="http://lab.llvm.org:8011/builders/lldb-x86_64-linux">LLDB Linux x86_64 build with GCC 4.6 (automake)</a> |
| </li> |
| <li> <a href="http://lab.llvm.org:8011/builders/lldb-x86_64-darwin12">LLDB Mac OS X x86_64 build with Clang (XCode)</a> |
| </li> |
| <li> <a href="http://llvm-amd64.freebsd.your.org:8010/builders/lldb-amd64-freebsd">LLDB FreeBSD x86_64 (CMake)</a> |
| </li> |
| <li> <a href="http://llvm-amd64.freebsd.your.org:8010/builders/lldb-i386-freebsd">LLDB FreeBSD i386</a> |
| </li> |
| </ul> |
| </p> |
| </div> |
| <div class="postfooter"></div> |
| <div class="post"> |
| <h1 class="postheader">Building LLDB</h1> |
| <ul> |
| <li><a href="#BuildingLldbOnWindows">Building LLDB on Windows</a></li> |
| <li><a href="#BuildingLldbOnMacOSX">Building LLDB on Mac OSX</a></li> |
| <li><a href="#BuildingLldbOnLinux">Building LLDB on Linux and FreeBSD</a></li> |
| </ul> |
| </div> |
| <div class="postfooter"></div> |
| <div class="post" id="BuildingLldbOnWindows"> |
| <h1 class="postheader">Building LLDB on Windows</h1> |
| <div class="postcontent"> |
| <h2>Required Dependencies</h2> |
| <ul> |
| <li>Visual Studio 2012 or greater</li> |
| <li>Windows SDK 8.0 or higher</li> |
| <li> |
| <a href="https://www.python.org/download/releases/2.7/">Python 2.7</a>. Note that you <b>must</b> |
| compile Python from source. See <a href="#WindowsPreliminaries">Preliminaries</a> for more |
| information. |
| </li> |
| <li><a href="http://martine.github.io/ninja/">Ninja build tool</a> (strongly recommended)</li> |
| <li><a href="http://gnuwin32.sourceforge.net/">GnuWin32</a></li> |
| <li><a href="http://www.swig.org/download.html">SWIG for Windows</a></li> |
| </ul> |
| <h2 id="WindowsPreliminaries">Preliminaries</h2> |
| <p> |
| This section describes how to set up your system and install the required dependencies such that |
| they can be found when needed during the build process. The steps outlined here only need to |
| be performed once. |
| </p> |
| <ol> |
| <li><p>Install Visual Studio and the Windows SDK.</p></li> |
| <li> |
| <p> |
| Build Python from source using the solution file supplied with the Python 2.7 source |
| distribution. |
| </p> |
| <p> |
| Because LLDB functionality is compiled into a Python extension module, |
| the extension module must be compiled with the same version of Visual Studio that |
| Python itself was compiled with. The binary release of Python 2.7 is compiled with |
| Visual Studio 2008, so it is incompatible with linking against LLDB. |
| </p> |
| <p> |
| Note that if you plan to do both debug and release builds of LLDB, you will need to |
| compile both debug and release builds of Python. |
| </p> |
| </li> |
| <li> |
| <p>Copy <python src dir>\PC\pyconfig.h to <python src dir>\Include.</p> |
| <p> |
| This is necessary because pyconfig.h is a hand-maintained file which is platform specific, |
| so multiple copies of this file are included with each source distribution. It appears to |
| be up to the person building Python to move the correct version of pyconfig.h to the Include |
| folder. |
| </p> |
| </li> |
| <li><p>Install GnuWin32, making sure <GnuWin32 install dir>\bin is added to your PATH environment variable.</p></li> |
| <li><p>Install SWIG for Windows, making sure <SWIG install dir> is added to your PATH environment variable.</p></li> |
| <li> |
| <p>(Optional) Create a file somewhere on your disk called llvm_env.bat and add the following code to it:</p> |
| <code> |
| @ECHO OFF<br /><br /> |
| IF "%1" == "build" goto do_build<br /> |
| IF "%1" == "dev" goto do_dev<br /> |
| ECHO Unknown option, expected "build" or "dev"<br /> |
| goto do_end<br /><br /> |
| :do_build<br /> |
| ECHO Initializing MSVC Build Environment...<br /> |
| CALL "c:\Program Files (x86)\Microsoft Visual Studio 12.0\vc\vcvarsall.bat"<br /> |
| ECHO Initializing Python environment...<br /> |
| set PYTHONPATH=<python src dir>\Lib;<cmake gen dir>\lib\site-packages<br /> |
| set PATH=%PATH%;<python src dir>\PCbuild<br /> |
| goto do_end<br /><br /> |
| :do_dev<br /> |
| set PYTHONPATH=<br /> |
| goto do_end<br /> |
| :do_end<br /> |
| </code> |
| </li> |
| <li> |
| <p> |
| (Optional) To make the process of setting up the environment before building more convenient, you can |
| optionally create a shortcut with the following properties: |
| </p> |
| <code>%windir%\system32\cmd.exe /K <path-to-llvm_env.bat> build</code> |
| </li> |
| </ol> |
| <h2>Building LLDB</h2> |
| <p> |
| Any command prompt from which you build LLDB should have a valid Visual Studio environment setup. |
| This means you should run vcvarsall.bat or open an appropriate Visual Studio Command Prompt |
| corresponding to the version you wish to use. Additionally, in order for LLDB to be able to locate |
| Python to link against, you will need to set up your PYTHONPATH environment variable to contain two |
| additional values: |
| </p> |
| <ol> |
| <li><python src dir>\Lib</li> |
| <li><folder where CMake build files are generated>\lib\site-packages</li> |
| </ol> |
| <p> |
| The first allows your custom built python installation to locate its system libraries, and |
| the second allows Python to locate the LLDB extension module. |
| </p> |
| <p> |
| Steps 6 and 7 of <a href="#WindowsPreliminaries">Preliminaries</a> describe a method for simplifying |
| this setup. |
| </p> |
| <p>Finally, when you are ready to build LLDB, generate CMake with the following command line:</p> |
| <code>cmake -G Ninja <cmake variables> <path to root of llvm src tree></code> |
| <p>and run <code>ninja</code> to build LLDB, and <code>ninja check-lldb</code> to run LLDB's test suite.</p> |
| <p> |
| Following is a description of some of the most important CMake variables which you are likely to encounter. |
| A variable <code>FOO</code> is set by adding <code>-DFOO=value</code> to the CMake command line. |
| </p> |
| <ul> |
| <li> |
| <b>LLDB_TEST_DEBUG_TEST_CRASHES</b> (Default=0): If set to 1, will cause Windows to generate a crash |
| dialog whenever lldb.exe or the python extension module crashes while running the test suite. If set to |
| 0, LLDB will silently crash. Setting to 1 allows a developer to attach a JIT debugger at the time of |
| a crash, rather than having to reproduce a failure or use a crash dump. |
| </li> |
| <li> |
| <b>PYTHON_LIBRARY</b>: Path to python27.lib. If doing a debug build, note that the library is called |
| python27_d.lib. Generally this should be set to <div align="center"><python src dir>\PCBuild\python27(_d).lib</div> |
| </li> |
| <li> |
| <b>PYTHON_INCLUDE_DIR</b>: Path to python include directory. Generally this should be set to |
| <div align="center"><python src dir>\Include</div> |
| </li> |
| <li> |
| <b>PYTHON_EXECUTABLE</b>: Path to python.exe. If doing a debug build of LLDB, note that the executable |
| is called python_d.exe. Generally this should be set to <div align="center"><python src dir>\PCBuild\python(_d).exe</div> |
| </li> |
| <li> |
| <b>LLDB_TEST_COMPILER</b>: The test suite only supports testing executables that were compiled with clang. This specifies |
| the path to the copy of clang that you wish to use to compile test executables. To use the version |
| of clang that you compiled alongside LLDB, set this to <div align="center"><folder where CMake build files are generated>\bin\clang.exe</div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="post" id="BuildingLldbOnMacOSX"> |
| <h1 class="postheader">Building LLDB on Mac OS X</h1> |
| <div class="postcontent"> |
| <p>Building on Mac OS X is as easy as downloading the code and building the Xcode project or workspace:</p> |
| </div> |
| <div class="postcontent"> |
| <h2>Preliminaries</h2> |
| <ul> |
| <li>XCode 4.3 or newer requires the "Command Line Tools" component (XCode->Preferences->Downloads->Components).</li> |
| <li>Mac OS X Lion or newer requires installing <a href="http://swig.org">Swig</a>.</li> |
| </ul> |
| <h2>Building LLDB</h2> |
| <ul> |
| <li><a href="download.html">Download</a> the lldb sources.</li> |
| <li>Follow the code signing instructions in <b>lldb/docs/code-signing.txt</b></li> |
| <li>In Xcode 3.x: <b>lldb/lldb.xcodeproj</b>, select the <b>lldb-tool</b> target, and build.</li> |
| <li>In Xcode 4.x: <b>lldb/lldb.xcworkspace</b>, select the <b>lldb-tool</b> scheme, and build.</li> |
| </ul> |
| </div> |
| <div class="postfooter"></div> |
| </div> |
| <div class="post" id="BuildingLldbOnLinux"> |
| <h1 class="postheader">Building LLDB on Linux and FreeBSD</h1> |
| <div class="postcontent"> |
| <p>This document describes the steps needed to compile LLDB on most Linux systems, and FreeBSD.</a></p> |
| </div> |
| <div class="postcontent"> |
| <h2>Preliminaries</h2> |
| <p> |
| 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 <em>Getting Started</em> guides for both of these projects |
| come as prerequisite reading: |
| </p> |
| <ul> |
| <li><a href="http://llvm.org/docs/GettingStarted.html">LLVM</a></li> |
| <li><a href="http://clang.llvm.org/get_started.html">Clang</a></li> |
| </ul> |
| <p>Supported compilers for building LLDB on Linux include:</p> |
| <ul> |
| <li>Clang 3.2</li> |
| <li><a href="http://gcc.gnu.org">GCC</a> 4.6.2 (later versions should work as well)</li> |
| </ul> |
| <p>It is recommended to use libstdc++ 4.6 (or higher) to build LLDB on Linux, but using libc++ is also known to work.</p> |
| <p> |
| On FreeBSD the base system Clang and libc++ may be used to build LLDB, |
| or the GCC port or package. |
| </p> |
| <p> |
| 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: |
| </p> |
| <ul> |
| <li><a href="http://swig.org">Swig</a></li> |
| <li><a href="http://www.thrysoee.dk/editline">libedit</a> (Linux only)</li> |
| <li><a href="http://www.python.org">Python</a></li> |
| </ul> |
| <p>So for example, on a Fedora system one might run:</p> |
| <code>> yum install swig python-devel libedit-devel</code> |
| <p>On a Debian or Ubuntu system one might run:</p> |
| <code>> sudo apt-get install build-essential subversion swig python2.7-dev libedit-dev libncurses5-dev </code> |
| <p>or</p> |
| <code>> sudo apt-get build-dep lldb-3.3 # or lldb-3.4</code> |
| <p>On FreeBSD one might run:</p> |
| <code>> pkg install swig python</code> |
| <p>If you wish to build the optional reference documentation, additional dependencies are required:</p> |
| <ul> |
| <li> Graphviz (for the 'dot' tool). |
| </li> |
| <li> doxygen (only if you wish to build the C++ API reference) |
| </li> |
| <li> epydoc (only if you wish to build the Python API reference) |
| </li> |
| </ul> |
| <p>To install the prerequisites for building the documentation (on Debian/Ubuntu) do:</p> |
| <code> |
| <br />> sudo apt-get install doxygen graphviz |
| <br />> sudo pip install epydoc # or install package python-epydoc |
| </code> |
| <h2>Building LLDB</h2> |
| <p> |
| 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 <tt>tools</tt> subdirectory of LLVM. We |
| will be setting up a directory hierarchy looking something like this: |
| </p> |
| <p> |
| <pre><tt> |
| llvm |
| | |
| `-- tools |
| | |
| +-- clang |
| | |
| `-- lldb |
| </tt></pre> |
| </p> |
| <p> |
| For reference, we will call the root of the LLVM project tree <tt>$llvm</tt>, and the |
| roots of the Clang and LLDB source trees <tt>$clang</tt> and <tt>$lldb</tt> respectively. |
| </p> |
| <p>Change to the directory where you want to do development work and checkout LLVM:</p> |
| <code>> svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</code> |
| |
| <p>Now switch to LLVM’s tools subdirectory and checkout both Clang and LLDB:</p> |
| <code> |
| > cd $llvm/tools |
| <br />> svn co http://llvm.org/svn/llvm-project/cfe/trunk clang |
| <br />> svn co http://llvm.org/svn/llvm-project/lldb/trunk lldb |
| </code> |
| |
| <p> |
| In general, building the LLDB trunk revision requires trunk revisions of both |
| LLVM and Clang. |
| </p> |
| <p> |
| 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 <em>Getting Started Guide</em>. A typical build procedure |
| might be: |
| </p> |
| <code> |
| > cd $llvm/.. |
| <br />> mkdir build |
| <br />> cd build |
| </code> |
| <h2>To build with CMake</h2> |
| <p> |
| Using CMake is documented on the <a href="http://llvm.org/docs/CMake.html">Building LLVM with CMake</a> |
| page. Building LLDB is possible using one of the following generators: |
| </p> |
| <ul> |
| <li> Ninja </li> |
| <li> Unix Makefiles </li> |
| </ul> |
| <h3>Using CMake + Ninja</h3> |
| <p> |
| 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: |
| </p> |
| <code> |
| > cmake .. -G Ninja |
| <br />> ninja lldb |
| <br />> ninja check-lldb |
| </code> |
| <h3>Using CMake + Unix Makefiles</h3> |
| <p>If you do not have Ninja, you can still use CMake to generate Unix Makefiles that build LLDB:</p> |
| <code> |
| > cmake .. |
| <br />> make |
| <br />> make check-lldb |
| </code> |
| <h2>To build with autoconf</h2> |
| <p> |
| 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: |
| </p> |
| <code> |
| > $llvm/configure |
| <br />> make |
| </code> |
| <p>If you are building with a GCC that isn't the default gcc/g++, like gcc-4.9/g++-4.9</p> |
| <code> |
| > $llvm/configure CC=gcc-4.9 CXX=g++-4.9 |
| <br />> make CC=gcc-4.9 CXX=g++-4.9 |
| </code> |
| <p> |
| 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). |
| </p> |
| <code> |
| > make DEBUG_SYMBOLS=0 |
| </code> |
| <p> To run the LLDB test suite, run:</p> |
| <code> |
| <br />> make -C tools/lldb/test |
| </code> |
| <p> |
| Note that once both LLVM and Clang have been configured and built it is not |
| necessary to perform a top-level <tt>make</tt> to rebuild changes made only to LLDB. |
| You can run <tt>make</tt> from the <tt>build/tools/lldb</tt> subdirectory as well. |
| </p> |
| <p> |
| If you wish to build with libc++ instead of libstdc++ (the default), run configure with the |
| <tt>--enable-libcpp</tt> flag. |
| </p> |
| <p> If you wish to build a release version of LLDB, run configure with the <tt>--enable-optimized</tt> flag.</p> |
| <h2>Testing</h2> |
| <p> |
| By default, the <tt>check-lldb</tt> 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 <tt>LLDB_TEST_ARGS</tt>. For example, to test LLDB against 32-bit binaries |
| built with a custom version of clang, do: |
| </p> |
| <code> |
| <br />> cmake -DLLDB_TEST_ARGS="-A i386 -C /path/to/custom/clang" -G Ninja |
| <br />> ninja check-lldb |
| </code> |
| <p>Note that multiple -A and -C flags can be specified to <tt>LLDB_TEST_ARGS</tt>.</p> |
| <p> |
| 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: |
| </p> |
| <code> |
| <br />> cd $lldb/test |
| <br />> python dotest.py --executable <path-to-lldb> -p TestInferiorCrashing.py |
| </code> |
| <p> |
| In addition to running a test by name, it is also possible to specify a directory path to <tt>dotest.py</tt> |
| in order to run all the tests under that directory. For example, to run all the tests under the |
| 'functionalities/data-formatter' directory, run: |
| </p> |
| <code> |
| <br />> python dotest.py --executable <path-to-lldb> functionalities/data-formatter |
| </code> |
| <p> |
| To dump additional information to <tt>stdout</tt> about how the test harness is driving LLDB, run |
| <tt>dotest.py</tt> with the <tt>-t</tt> flag. Many more options that are available. To see a list of all of them, run: |
| </p> |
| <code> |
| <br />> python dotest.py -h |
| </code> |
| <h2>Building API reference documentation</h2> |
| <p> |
| 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 <tt>lldb-python-doc</tt> and <tt>lldb-cpp-doc</tt> CMake targets. |
| </p> |
| <p> The output HTML reference documentation can be found in <tt><build-dir>/tools/lldb/docs/</tt>.</p><p> |
| <h2>Additional Notes</h2> |
| </p> |
| <p> |
| LLDB has a Python scripting capability and supplies its own Python module named <tt>lldb</tt>. |
| If a script is run inside the command line <tt>lldb</tt> 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 <tt>PYTHONPATH</tt> environment variable can be used |
| to let the Python interpreter find the <tt>lldb</tt> module. |
| </p> |
| <p>The correct path can be obtained by invoking the command line <tt>lldb</tt> tool with the -P flag:</p> |
| <code>> export PYTHONPATH=`$llvm/build/Debug+Asserts/bin/lldb -P`</code> |
| <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: |
| </p> |
| <code>> python -c 'import lldb'</code></p> |
| </div> |
| <div class="postfooter"></div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
