diff options
Diffstat (limited to 'www/build.html')
| -rwxr-xr-x | www/build.html | 551 |
1 files changed, 551 insertions, 0 deletions
diff --git a/www/build.html b/www/build.html new file mode 100755 index 0000000000000..787ce6220a2c0 --- /dev/null +++ b/www/build.html @@ -0,0 +1,551 @@ +<!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 Integration</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-ubuntu-14.04-cmake">LLDB Ubuntu 14.04 x86_64 (CMake, clang-3.5+/gcc-4.8, i386/x86_64)</a> + </li> + <li> <a href="http://lab.llvm.org:8011/builders/lldb-x86_64-ubuntu-14.04-android">LLDB Ubuntu 14.04 x86_64->Android (CMake, gcc-4.9 arm/arm64/x86)</a> + </li> + <li> <a href="http://lab.llvm.org:8011/builders/lldb-x86_64-darwin-13.4">LLDB Mac OS X 10.9.5 x86_64 (Xcode)</a> + </li> + <li> <a href="http://lab.llvm.org:8011/builders/lldb-x86-windows-msvc">LLDB Windows Server 2008 x86 (CMake, MSVS 2013, Windows SDK 8.1, no tests)</a> + </li> + <li> <a href="http://lab.llvm.org:8011/builders/lldb-x86-win7-msvc">LLDB Windows 7 x86 (CMake, MSVS 2013, Windows SDK 8.1, no tests)</a> + </li> + <li> <a href="http://lab.llvm.org:8011/builders/lldb-x86_64-debian-clang">LLDB Ubuntu 14.04 x86_64 build (automake, Clang 3.4, VMware Workstation)</a> + </li> + <li> <a href="http://lab.llvm.org:8011/builders/lldb-x86_64-freebsd">LLDB FreeBSD x86_64 (CMake)</a> + </li> + <li> <a href="http://lab.llvm.org:8011/builders/lldb-amd64-ninja-netbsd7">LLDB NetBSD-7.0 amd64 (GCC 4.8.5, Ninja)</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, FreeBSD and NetBSD</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. The same applies if you plan to build + both x86 and x64 configurations of LLDB + </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> + Run lldb/scripts/install_custom_python.py so to "install" your custom build of Python to a + canonical directory structure. + </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> + </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. + </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. Information about running the LLDB test suite can be found on the <a href="test.html">test</a> page.</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_HOME</b> (Required): Path the folder you specified in the --dest argument to install_custom_python.py. + Note that install_custom_python.py will create x86 and x64 subdirectories under this folder. PYTHON_HOME should + refer to the correct architecture-specific folder. + </li> + <li> + <b>LLDB_RELOCATABLE_PYTHON</b> (Default=0): When this is 0, LLDB will bind statically to the location specified + in the PYTHON_HOME CMake variable, ignoring any value of PYTHONHOME set in the environment. This is most useful for + developers who simply want to run LLDB after they build it. If you wish to move a build of LLDB to a different + machine where Python will be in a different location, setting LLDB_RELOCATABLE_PYTHON to 1 will cause Python to + use its default mechanism for finding the python installation at runtime (looking for installed Pythons, or using + the PYTHONHOME environment variable if it is specified). + </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, FreeBSD and NetBSD</h1> + <div class="postcontent"> + <p>This document describes the steps needed to compile LLDB on most Linux systems, FreeBSD and NetBSD.</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> + On NetBSD the base system GCC and libstdc++ are used to build LLDB, + Clang/LLVM and libc++ should also work. + </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 libedit-devel libxml2-devel ncurses-devel python-devel swig</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>On NetBSD one might run:</p> + <code>> pkgin install swig python27 cmake ninja-build</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>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> + Current stable NetBSD release doesn't ship with libpanel(3), therefore it's required to disable curses(3) support with + the <tt>-DLLDB_DISABLE_CURSES:BOOL=TRUE</tt> option. To make sure check if <tt>/usr/include/panel.h</tt> exists in your + system. + </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> + + <h2 id="cross-compilation">Cross-compiling LLDB</h2> + <p> + In order to debug remote targets running different architectures than your host, you + will need to compile LLDB (or at least the server component) for the target. While + the easiest solution is to just compile it locally on the target, this is often not + feasible, and in these cases you will need to cross-compile LLDB on your host. + </p> + + <p> + Cross-compilation is often a daunting task and has a lot of quirks which depend on + the exact host and target architectures, so it is not possible to give a universal + guide which will work on all platforms. However, here we try to provide an overview + of the cross-compilation process along with the main things you should look out for. + </p> + + <p> + First, you will need a working toolchain which is capable of producing binaries for + the target architecture. Since you already have a checkout of clang and lldb, you + can compile a host version of clang in a separate folder and use that. + Alternatively you can use system clang or even cross-gcc if your distribution + provides such packages (e.g., <code>g++-aarch64-linux-gnu</code> on Ubuntu). On + Android, a working toolchain can be produced by downloading the Android NDK and + running the contained <code>make-standalone-toolchain.sh</code> script. + </p> + + <p> + Next, you will need a copy of the required target headers and libraries on your + host. The libraries can be usually obtained by copying from the target machine, + however the headers are often not found there, especially in case of embedded + platforms. In this case, you will need to obtain them from another source, either + a cross-package if one is available, or cross-compiling the respective library from + source. Fortunately the list of LLDB dependencies is not big and if you are only + interested in the server component, you can reduce this even further by passing the + appropriate cmake options, such as: + </p> + <code> + -DLLDB_DISABLE_LIBEDIT=1<br/> + -DLLDB_DISABLE_CURSES=1<br/> + -DLLDB_DISABLE_PYTHON=1<br/> + -DLLVM_ENABLE_TERMINFO=0 + </code> + <p> + In this case you, will often not need anything other than the standard C and C++ + libraries. + </p> + + <p> + In the case of Android, all required headers and libraries are provided by the + aforementioned <code>make-standalone-toolchain.sh</code> script. + </p> + + <p> + Once all of the dependencies are in place, it's just a matter of configuring the + build system with the locations and arguments of all the necessary tools. The most + important cmake options here are: + </p> + <dl> + <dt>CMAKE_CROSSCOMPILING</dt> + <dd>Set to 1 to enable cross-compilation.</dd> + + <dt>CMAKE_LIBRARY_ARCHITECTURE</dt> + <dd>Affects the cmake search path when looking for libraries. You may need to set + this to your architecture triple if you do not specify all your include and + library paths explicitly.</dd> + + <dt>CMAKE_C_COMPILER, CMAKE_CXX_COMPILER</dt> + <dd>C and C++ compilers for the target architecture</dd> + + <dt>CMAKE_C_FLAGS, CMAKE_CXX_FLAGS</dt> + <dd>The flags for the C and C++ target compilers. You may need to specify the + exact target cpu and abi besides the include paths for the target headers.</dd> + + <dt>CMAKE_EXE_LINKER_FLAGS</dt> + <dd>The flags to be passed to the linker. Usually just a list of library search + paths referencing the target libraries.</dd> + + <dt>LLVM_TABLEGEN, CLANG_TABLEGEN</dt> + <dd>Paths to llvm-tblgen and clang-tblgen for the <em>host</em> architecture. If + you already have built clang for the host, you can point these variables to the + executables in your build directory. If not, you will need to build the + llvm-tblgen and clang-tblgen host targets at least.<dd> + + <dt>LLVM_HOST_TRIPLE</dt> + <dd>The triple of the system that lldb (or lldb-server) will run on. Not setting + this (or setting it incorrectly) can cause a lot of issues with remote debugging + as a lot of the choices lldb makes depend on the triple reported by the remote + platform.</dd> + </dl> + <p> + You can of course also specify the usual cmake options like CMAKE_BUILD_TYPE, etc. + </p> + + <h3>Example 1: Cross-compiling for linux arm64 on Ubuntu host</h3> + + <p> + Ubuntu already provides the packages necessary to cross-compile LLDB for arm64. It + is sufficient to install packages gcc-aarch64-linux-gnu, g++-aarch64-linux-gnu, + binutils-aarch64-linux-gnu. Then it is possible to prepare the cmake build with the + following parameters: + </p> + <code> + -DCMAKE_CROSSCOMPILING=1 \<br/> + -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \<br/> + -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \<br/> + -DLLVM_HOST_TRIPLE=aarch64-unknown-linux-gnu \<br/> + -DLLVM_TABLEGEN=<path-to-host>/bin/llvm-tblgen \<br/> + -DCLANG_TABLEGEN=<path-to-host>/bin/clang-tblgen \<br/> + -DLLDB_DISABLE_PYTHON=1 \<br/> + -DLLDB_DISABLE_LIBEDIT=1 \<br/> + -DLLDB_DISABLE_CURSES=1 + </code> + + <p> + An alternative (and recommended) way to compile LLDB is with clang. Unfortunately, + clang is not able to find all the include paths necessary for a successful + cross-compile, so we need to help it with a couple of CFLAGS options. In my case it + was sufficient to add the following arguments to CMAKE_C_FLAGS and CMAKE_CXX_FLAGS + (in addition to changing CMAKE_C(XX)_COMPILER to point to clang compilers): + </p> + <code> + -target aarch64-linux-gnu \<br/> + -I /usr/aarch64-linux-gnu/include/c++/4.8.2/aarch64-linux-gnu \<br/> + -I /usr/aarch64-linux-gnu/include + </code> + + <p> + If you wanted to build a full version of LLDB and avoid passing + -DLLDB_DISABLE_PYTHON and other options, you would need to obtain the target + versions of the respective libraries. The easiest way to achieve this is to use the + <code>qemu-debootstrap</code> utility, which can prepare a system image using qemu + and chroot to simulate the target environment. Then you can install the necessary + packages in this environment (python-dev, libedit-dev, etc.) and point your + compiler to use them using the correct -I and -L arguments. + </p> + + <h3>Example 2: Cross-compiling for Android on Linux</h3> + + <p> + All tools needed to build LLDB for android are available in the Android NDK. For + example, we can produce an x86 toolchain along with all the libraries and headers + by running + </p> + <code> + ./build/tools/make-standalone-toolchain.sh \<br/> + --platform=android-21 \<br/> + --toolchain=x86-4.9 \<br/> + --install-dir=$HOME/Toolchains/x86-android-toolchain + </code> + <p> + from inside the unzipped NDK. Toolchains for other architectures can be produced in + a similar manner. + </p> + + <p> + For Android we provide a Android.cmake script which sets a lot of the required + options automatically. A cmake build can therefore be prepared with the following parameters: + </p> + <code> + -DCMAKE_TOOLCHAIN_FILE=cmake/platforms/Android.cmake \<br/> + -DANDROID_TOOLCHAIN_DIR=$HOME/Toolchains/x86-android-toolchain \<br/> + -DANDROID_ABI=x86 \<br/> + -DLLVM_HOST_TRIPLE=i386-unknown-linux-android \<br/> + -DLLVM_TABLEGEN=<path-to-host>/bin/llvm-tblgen \<br/> + -DCLANG_TABLEGEN=<path-to-host>/bin/clang-tblgen + </code> + + <p> + Note that the full LLVM build is not functional on android yet, so simply running + <code>ninja</code> will not work. You will need to manually specify the target you + want to build: <code>lldb</code>, <code>lldb-server</code>, etc. + </p> + </div> + <div class="postfooter"></div> + </div> + </div> + </div> + </div> +</body> +</html> |