716 lines · plain
1Building2========3 4Getting the Sources5-------------------6 7Please refer to the `LLVM Getting Started Guide8<https://llvm.org/docs/GettingStarted.html#getting-started-with-llvm>`_ for9general instructions on how to check out the LLVM monorepo, which contains the10LLDB sources.11 12Git browser: https://github.com/llvm/llvm-project/tree/main/lldb13 14Preliminaries15-------------16 17LLDB relies on many of the technologies developed by the larger LLVM project.18In particular, it requires both Clang and LLVM itself in order to build. Due to19this tight integration the Getting Started guides for both of these projects20come as prerequisite reading:21 22* `LLVM <https://llvm.org/docs/GettingStarted.html>`_23* `Clang <http://clang.llvm.org/get_started.html>`_24 25The following requirements are shared on all platforms.26 27* `CMake <https://cmake.org>`_28* `Ninja <https://ninja-build.org>`_ (strongly recommended)29 30If you want to run the test suite, you'll need to build LLDB with Python31scripting support.32 33* `Python <http://www.python.org/>`_ 3.8 or later.34* `SWIG <http://swig.org/>`_ 4 or later.35 36If you are on FreeBSD or NetBSD, you will need to install ``gmake`` for building37the test programs. On other platforms ``make`` is used.38 39.. _Optional Dependencies:40 41Optional Dependencies42*********************43 44Although the following dependencies are optional, they have a big impact on45LLDB's functionality. It is strongly encouraged to build LLDB with these46dependencies enabled.47 48By default they are auto-detected: if CMake can find the dependency it will be49used. It is possible to override this behavior by setting the corresponding50CMake flag to ``On`` or ``Off`` to force the dependency to be enabled or51disabled. When a dependency is set to ``On`` and can't be found it will cause a52CMake configuration error.53 54+-------------------+--------------------------------------------------------------+--------------------------+55| Feature | Description | CMake Flag |56+===================+==============================================================+==========================+57| Editline | Generic line editing, history, Emacs and Vi bindings | ``LLDB_ENABLE_LIBEDIT`` |58+-------------------+--------------------------------------------------------------+--------------------------+59| Curses | Text user interface | ``LLDB_ENABLE_CURSES`` |60+-------------------+--------------------------------------------------------------+--------------------------+61| LZMA | Lossless data compression | ``LLDB_ENABLE_LZMA`` |62+-------------------+--------------------------------------------------------------+--------------------------+63| Libxml2 | XML | ``LLDB_ENABLE_LIBXML2`` |64+-------------------+--------------------------------------------------------------+--------------------------+65| Python | Python scripting. >= 3.8 is required. | ``LLDB_ENABLE_PYTHON`` |66+-------------------+--------------------------------------------------------------+--------------------------+67| Lua | Lua scripting. Lua 5.3 and 5.4 are supported. | ``LLDB_ENABLE_LUA`` |68+-------------------+--------------------------------------------------------------+--------------------------+69 70Depending on your platform and package manager, one might run any of the71commands below.72 73::74 75 $ yum install libedit-devel libxml2-devel ncurses-devel python-devel swig76 $ sudo apt-get install build-essential swig python3-dev libedit-dev libncurses5-dev libxml2-dev77 $ pkg install swig python libxml278 $ pkgin install swig python38 cmake ninja-build79 $ brew install swig cmake ninja80 81.. note::82 There is an `incompatibility83 <https://github.com/swig/swig/issues/1321>`_ between Python version 3.7 and later84 and swig versions older than 4.0.0 which makes builds of LLDB using debug85 versions of python unusable. This primarily affects Windows, as debug builds of86 LLDB must use debug python as well.87 88.. note::89 Installing multiple versions of Curses, particularly when only one is built with90 wide character support, can cause lldb to be linked with an incorrect set of91 libraries. If your system already has Curses, we recommend you use that version.92 If you do install another one, use a tool like ``ldd`` to ensure only one version93 of Curses is being used in the final ``lldb`` executable.94 95Windows96*******97 98The steps outlined here describe how to set up your system and install the99required dependencies for building and testing LLDB on Windows. They only need100to be performed once.101 102Build Requirements103^^^^^^^^^^^^^^^^^^104 105Please follow the steps below if you only want to **build** lldb.106 1071. Install `Visual Studio <https://visualstudio.microsoft.com>` with the108 "Desktop Development with C++" workload. Make sure that the latest Windows109 SDK and the Active Template Library (ATL) are installed.1102. Install `Git Bash <https://git-scm.com/install/windows>`_ and add111 ``<Git install dir>\usr\bin`` to your ``PATH``. Verify that utilities like112 ``dirname`` are available from your terminal.1133. Install `make <https://sourceforge.net/projects/ezwinports/files/>`_ and114 verify that it's in your ``PATH``.1154. Install `Python 3 <https://www.python.org/downloads/windows/>`_ from the116 GUI installer. If you will be building LLDB in Debug mode, **include the117 debug libraries** during the install. Make sure ``python`` is added to your118 ``PATH``.1195. Install `SWIG for Windows <http://www.swig.org/download.html>`_. Make sure120 ``swig`` is added to your ``PATH`` and that ``swig -swiglib`` points to the121 correct directory.1226. Register the Debug Interface Access DLLs with the Registry from a privileged123 terminal.124 125::126 127> regsvr32 "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\DIA SDK\bin\msdia140.dll"128> regsvr32 "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\DIA SDK\bin\amd64\msdia140.dll"129 130Any command prompt from which you build LLDB should have a valid Visual Studio131environment setup. This means you should open an appropriate `Developer Command132Prompt for VS <https://docs.microsoft.com/en-us/visualstudio/ide/reference/command-prompt-powershell?view=vs-2019>`_133corresponding to the version you wish to use or run ``vcvarsall.bat`` or134``VsDevCmd.bat``.135 136Test Requirements137^^^^^^^^^^^^^^^^^138 139Please follow the steps above and below if you want to **test** `lldb`.140 141* Install `Python Tools for Visual Studio <https://github.com/Microsoft/PTVS/>`_,142 an indispensable debugging extension to Visual Studio which enables full143 editing and debugging support for Python (including mixed native/managed144 debugging).145 146macOS147*****148 149* To use the in-tree debug server on macOS, lldb needs to be code signed. For150 more information see :ref:`CodeSigning` below.151* If you are building both Clang and LLDB together, be sure to also check out152 libc++, which is a required for testing on macOS.153 154Building LLDB with CMake155------------------------156 157The LLVM project is migrating to a single monolithic repository for LLVM and158its subprojects. This is the recommended way to build LLDB. Check out the159source-tree with git:160 161::162 163 $ git clone https://github.com/llvm/llvm-project.git164 165CMake is a cross-platform build-generator tool. CMake does not build the166project, it generates the files needed by your build tool. The recommended167build tool for LLVM is Ninja, but other generators like Xcode or Visual Studio168may be used as well. Please also read `Building LLVM with CMake169<https://llvm.org/docs/CMake.html>`_.170 171Regular in-tree builds172**********************173 174Create a new directory for your build-tree. From there run CMake and point it175to the ``llvm`` directory in the source-tree:176 177::178 179 $ cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;lldb" [<cmake options>] path/to/llvm-project/llvm180 181We used the ``LLVM_ENABLE_PROJECTS`` option here to tell the build-system which182subprojects to build in addition to LLVM (for more options see183:ref:`CommonCMakeOptions` and :ref:`CMakeCaches`). Parts of the LLDB test suite184require ``lld``. Add it to the list in order to run all tests. Once CMake is done,185run ninja to perform the actual build.186 187::188 189 $ ninja lldb lldb-server190 191If you only want lldb, or are on a platform where lldb-server is not supported,192you can pass just ``lldb``. Ninja will only build what is necessary to run the193lldb driver:194 195::196 197 $ ninja lldb198 199Standalone builds200*****************201 202This is another way to build LLDB. We can use the same source-tree as we203checked out above, but now we will have multiple build-trees:204 205* the main build-tree for LLDB in ``/path/to/lldb-build``206* one or more provided build-trees for LLVM and Clang; for simplicity we use a207 single one in ``/path/to/llvm-build``208 209Run CMake with ``-B`` pointing to a new directory for the provided210build-tree\ :sup:`1` and the positional argument pointing to the ``llvm``211directory in the source-tree.\ :sup:`2` Note that we leave out LLDB here and only include212Clang. Then we build the ``ALL`` target with ninja:213 214::215 216 $ cmake -B /path/to/llvm-build -G Ninja \217 -DCMAKE_BUILD_TYPE=[<build type>] \218 -DLLVM_ENABLE_PROJECTS=clang \219 -DCMAKE_BUILD_TYPE=Release \220 [<more cmake options>] /path/to/llvm-project/llvm221 $ ninja222 223Now run CMake a second time with ``-B`` pointing to a new directory for the224main build-tree and the positional argument pointing to the ``lldb`` directory225in the source-tree. In order to find the provided build-tree, the build system226looks for the path to its CMake modules in ``LLVM_DIR``. If you use a separate227build directory for Clang, remember to pass its module path via ``Clang_DIR``228(CMake variables are case-sensitive!):229 230::231 232 $ cmake -B /path/to/lldb-build -G Ninja \233 -DCMAKE_BUILD_TYPE=Release \234 -DLLVM_DIR=/path/to/llvm-build/lib/cmake/llvm \235 [<more cmake options>] /path/to/llvm-project/lldb236 $ ninja lldb lldb-server237 238If you do not require or cannot build ``lldb-server`` on your platform, simply239remove it from the Ninja command.240 241.. note::242 243 #. The ``-B`` argument was undocumented for a while and is only officially244 supported since `CMake version 3.14245 <https://cmake.org/cmake/help/v3.14/release/3.14.html#command-line>`_246 #. If you want to have a standalone LLDB build with tests enabled, you also247 need to pass in ``-DLLVM_ENABLE_RUNTIME='libcxx;libcxxabi;libunwind'`` to your CMake invocation when configuring your LLVM standalone build.248 249.. _CommonCMakeOptions:250 251Common CMake options252********************253 254Following is a description of some of the most important CMake variables which255you are likely to encounter. A variable FOO is set by adding ``-DFOO=value`` to256the CMake command line.257 258If you want to debug the lldb that you're building -- that is, build it with259debug info enabled -- pass two additional arguments to cmake before running260ninja:261 262::263 264 $ cmake -G Ninja \265 -DLLDB_EXPORT_ALL_SYMBOLS=1 \266 -DCMAKE_BUILD_TYPE=Debug267 <path to root of llvm source tree>268 269If you want to run the test suite, you will need a compiler to build the test270programs. If you have Clang checked out, that will be used by default.271Alternatively, you can specify a C and C++ compiler to be used by the test272suite.273 274::275 276 $ cmake -G Ninja \277 -DLLDB_TEST_COMPILER=<path to C compiler> \278 <path to root of llvm source tree>279 280It is strongly recommend to use a release build for the compiler to speed up281test execution.282 283Windows284^^^^^^^285 286On Windows the LLDB test suite requires lld. Either add ``lld`` to287``LLVM_ENABLE_PROJECTS`` or disable the test suite with288``LLDB_INCLUDE_TESTS=OFF``.289 290Although the following CMake variables are by no means Windows specific, they291are commonly used on Windows.292 293* ``LLDB_TEST_DEBUG_TEST_CRASHES`` (Default=0): If set to 1, will cause Windows294 to generate a crash dialog whenever lldb.exe or the python extension module295 crashes while running the test suite. If set to 0, LLDB will silently crash.296 Setting to 1 allows a developer to attach a JIT debugger at the time of a297 crash, rather than having to reproduce a failure or use a crash dump.298* ``PYTHON_HOME`` (Required): Path to the folder where the Python distribution299 is installed. For example, ``C:\Python35``.300* ``LLDB_EMBED_PYTHON_HOME`` (Default=1 on Windows): When this is 1, LLDB will bind301 statically to the location specified in the ``PYTHON_HOME`` CMake variable,302 ignoring any value of ``PYTHONHOME`` set in the environment. This is most303 useful for developers who simply want to run LLDB after they build it. If you304 wish to move a build of LLDB to a different machine where Python will be in a305 different location, setting ``LLDB_EMBED_PYTHON_HOME`` to 0 will cause306 Python to use its default mechanism for finding the python installation at307 runtime (looking for installed Pythons, or using the ``PYTHONHOME``308 environment variable if it is specified).309 310Sample command line:311 312::313 314 $ cmake -G Ninja^315 -DLLDB_TEST_DEBUG_TEST_CRASHES=1^316 -DPYTHON_HOME=C:\Python35^317 -DLLDB_TEST_COMPILER=d:\src\llvmbuild\ninja_release\bin\clang.exe^318 <path to root of llvm source tree>319 320 321Building with ninja is both faster and simpler than building with Visual Studio,322but chances are you still want to debug LLDB with an IDE. One solution is to run323cmake twice and generate the output into two different folders. One for324compiling (the ninja folder), and one for editing, browsing and debugging.325 326Follow the previous instructions in one directory, and generate a Visual Studio327project in another directory.328 329::330 331 $ cmake -G "Visual Studio 16 2019" -A x64 -T host=x64 <cmake variables> <path to root of llvm source tree>332 333Then you can open the .sln file in Visual Studio, set lldb as the startup334project, and use F5 to run it. You need only edit the project settings to set335the executable and the working directory to point to binaries inside of the336ninja tree.337 338 339macOS340^^^^^341 342On macOS the LLDB test suite requires libc++. Either add343``LLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind"`` or disable the test suite with344``LLDB_INCLUDE_TESTS=OFF``. Further useful options:345 346* ``LLDB_BUILD_FRAMEWORK:BOOL``: Builds the LLDB.framework.347* ``LLDB_CODESIGN_IDENTITY:STRING``: Set the identity to use for code-signing348 all executables. If not explicitly specified, only ``debugserver`` will be349 code-signed with identity ``lldb_codesign`` (see :ref:`CodeSigning`).350* ``LLDB_USE_SYSTEM_DEBUGSERVER:BOOL``: Use the system's debugserver, so lldb is351 functional without setting up code-signing.352* ``LLDB_ENFORCE_STRICT_TEST_REQUIREMENTS:BOOL``: Detect missing packages or modules at configuration time.353 354.. _CMakeCaches:355 356CMake caches357************358 359CMake caches allow to store common sets of configuration options in the form of360CMake scripts and can be useful to reproduce builds for particular use-cases361(see by analogy `usage in LLVM and Clang <https://llvm.org/docs/AdvancedBuilds.html>`_).362A cache is passed to CMake with the ``-C`` flag, following the absolute path to363the file on disk. Subsequent ``-D`` options are still allowed. Please find the364currently available caches in the `lldb/cmake/caches/365<https://github.com/llvm/llvm-project/tree/main/lldb/cmake/caches>`_366directory.367 368Common configurations on macOS369^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^370 371Build, test and install a distribution of LLDB from the `monorepo372<https://github.com/llvm/llvm-project>`_ (see also `Building a Distribution of373LLVM <https://llvm.org/docs/BuildingADistribution.html>`_):374 375::376 377 $ git clone https://github.com/llvm/llvm-project378 379 $ cmake -B /path/to/lldb-build -G Ninja \380 -C /path/to/llvm-project/lldb/cmake/caches/Apple-lldb-macOS.cmake \381 -DLLVM_ENABLE_PROJECTS="clang;lldb" \382 -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \383 llvm-project/llvm384 385 $ DESTDIR=/path/to/lldb-install ninja -C /path/to/lldb-build check-lldb install-distribution386 387.. _CMakeGeneratedXcodeProject:388 389Build LLDB standalone for development with Xcode:390 391::392 393 $ git clone https://github.com/llvm/llvm-project394 395 $ cmake -B /path/to/llvm-build -G Ninja \396 -C /path/to/llvm-project/lldb/cmake/caches/Apple-lldb-base.cmake \397 -DLLVM_ENABLE_PROJECTS="clang" \398 -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \399 llvm-project/llvm400 $ ninja -C /path/to/llvm-build401 402 $ cmake -B /path/to/lldb-build \403 -C /path/to/llvm-project/lldb/cmake/caches/Apple-lldb-Xcode.cmake \404 -DLLVM_DIR=/path/to/llvm-build/lib/cmake/llvm \405 llvm-project/lldb406 $ open lldb.xcodeproj407 $ cmake --build /path/to/lldb-build --target check-lldb408 409.. note::410 411 The ``-B`` argument was undocumented for a while and is only officially412 supported since `CMake version 3.14413 <https://cmake.org/cmake/help/v3.14/release/3.14.html#command-line>`_414 415 416Building the Documentation417--------------------------418 419If you wish to build the optional (reference) documentation, additional420dependencies are required:421 422* Sphinx (for the website and the Python API reference)423* Graphviz (for the 'dot' tool)424* doxygen (if you wish to build the C++ API reference)425* SWIG (for generating Python bindings)426 427To install the system prerequisites for building the documentation (on Debian/Ubuntu)428do:429 430::431 432 $ sudo apt-get install doxygen graphviz swig433 434To install Sphinx and its dependencies, use the ``requirements.txt`` available within LLVM435to ensure you get a working configuration:436 437::438 439 $ pip3 install -r /path/to/llvm-project/llvm/docs/requirements.txt440 441To build the documentation, configure with ``LLVM_ENABLE_SPHINX=ON`` and build the desired target(s).442 443::444 445 $ ninja docs-lldb-html446 $ ninja docs-lldb-man447 $ ninja lldb-cpp-doc448 449Cross-compiling LLDB450--------------------451 452The advice presented here may not be complete or represent the best practices453of CMake at this time. Please refer to `CMake's documentation <https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html>`_454if you have any doubts or want more in depth information.455 456In order to debug remote targets running different architectures than your457host, you will need to compile LLDB (or at least the server component458``lldb-server``) for the target. While the easiest solution is to compile it459locally on the target, this is often not feasible, and in these cases you will460need to cross-compile LLDB on your host.461 462Cross-compilation is often a daunting task and has a lot of quirks which depend463on the exact host and target architectures, so it is not possible to give a464universal guide which will work on all platforms. However, here we try to465provide an overview of the cross-compilation process along with the main things466you should look out for.467 468First, you will need a working toolchain which is capable of producing binaries469for the target architecture. Since you already have a checkout of clang and470lldb, you can compile a host version of clang in a separate folder and use471that. Alternatively you can use system clang or even cross-gcc if your472distribution provides such packages (e.g., ``g++-aarch64-linux-gnu`` on473Ubuntu).474 475Next, you will need a copy of the required target headers and libraries on your476host. The libraries can be usually obtained by copying from the target machine,477however the headers are often not found there, especially in case of embedded478platforms. In this case, you will need to obtain them from another source,479either a cross-package if one is available, or cross-compiling the respective480library from source. Fortunately the list of LLDB dependencies is not big and481if you are only interested in the server component, you can reduce this even482further by passing the appropriate cmake options, such as:483 484::485 486 -DLLDB_ENABLE_PYTHON=0487 -DLLDB_ENABLE_LIBEDIT=0488 -DLLDB_ENABLE_CURSES=0489 490(see :ref:`Optional Dependencies` for more)491 492In this case you, will often not need anything other than the standard C and493C++ libraries.494 495If you find that CMake is finding a version of an optional dependency that496for whatever reason doesn't work, consider simply disabling it if you don't497know that you need it.498 499Once all of the dependencies are in place, you need to configure the build500system with the locations and arguments of all the necessary tools.501 502There are 2 ways to do this depending on your starting point and requirements.503 5041. If you are starting from scratch and only need the resulting cross compiled505binaries, you can have LLVM build the native tools for you.506 5072. If you need a host build too, or already have one, you can tell CMake where508that is and it will use those native tools instead.509 510If you are going to run ``lldb`` and ``lldb-server`` only on the target machine,511choose option 1. If you are going to run ``lldb`` on the host machine and512connect to ``lldb-server`` on the target, choose option 2.513 514Either way, the most important cmake options when cross-compiling are:515 516* ``CMAKE_SYSTEM_NAME`` and ``CMAKE_SYSTEM_PROCESSOR``: This tells CMake what517 the build target is and from this it will infer that you are cross compiling.518* ``CMAKE_C_COMPILER``, ``CMAKE_CXX_COMPILER`` : C and C++ compilers for the519 target architecture.520* ``CMAKE_C_FLAGS``, ``CMAKE_CXX_FLAGS`` : The flags for the C and C++ target521 compilers. You may need to specify the exact target cpu and ABI besides the522 include paths for the target headers.523* ``CMAKE_EXE_LINKER_FLAGS`` : The flags to be passed to the linker. Usually524 this is a list of library search paths referencing the target libraries.525* ``LLVM_HOST_TRIPLE`` : The triple of the system that lldb (or lldb-server)526 will run on. Not setting this (or setting it incorrectly) can cause a lot of527 issues with remote debugging as a lot of the choices lldb makes depend on the528 triple reported by the remote platform.529* ``LLVM_NATIVE_TOOL_DIR`` (only when using an existing host build): Is a530 path to the llvm tools compiled for the host. Any tool that must be run on the531 host during a cross build will be configured from this path, so you do not532 need to set them all individually. If you are doing a host build only for the533 purpose of a cross build, you will need it to include at least534 ``llvm-tblgen``, ``clang-tblgen`` and ``lldb-tblgen``. Be aware that535 the list may grow over time.536* ``CMAKE_LIBRARY_ARCHITECTURE`` : Affects the cmake search path when looking537 for libraries. You may need to set this to your architecture triple if you do538 not specify all your include and library paths explicitly.539 540To find the possible values of the ``CMAKE_*`` options, please refer to the541CMake documentation.542 543You can of course also specify the usual cmake options like544``CMAKE_BUILD_TYPE``, etc.545 546For testing, you may want to set one of:547 548* ``LLDB_TEST_COMPILER`` : The compiler used to build programs used549 in the test suite. If you are also building clang, this will be used550 but if you want to test remotely from the host, you should choose the551 cross compiler you are using for the cross build.552* ``LLDB_INCLUDE_TESTS=0`` : To disable the tests completely.553 554Example 1: Cross-compiling for linux arm64 on Ubuntu host555*********************************************************556 557Ubuntu already provides the packages necessary to cross-compile LLDB for arm64.558It is sufficient to install packages ``gcc-aarch64-linux-gnu``,559``g++-aarch64-linux-gnu``, ``binutils-aarch64-linux-gnu``.560 561Configure as follows:562 563::564 565 cmake <path-to-monorepo>/llvm-project/llvm -G Ninja \566 -DCMAKE_BUILD_TYPE=Release \567 -DLLVM_ENABLE_PROJECTS="clang;lld;lldb" \568 -DCMAKE_SYSTEM_NAME=Linux \569 -DCMAKE_SYSTEM_PROCESSOR=AArch64 \570 -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \571 -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \572 -DLLVM_HOST_TRIPLE=aarch64-unknown-linux-gnu \573 -DLLDB_ENABLE_PYTHON=0 \574 -DLLDB_ENABLE_LIBEDIT=0 \575 -DLLDB_ENABLE_CURSES=0576 577During this build native tools will be built automatically when they are needed.578The contents of ``<build dir>/bin`` will be target binaries as you'd expect.579AArch64 binaries in this case.580 581Example 2: Cross-compiling for linux arm64 on Ubuntu host using an existing host build582**************************************************************************************583 584This build requires an existing host build that includes the required native585tools. Install the compiler as in example 1 then run CMake as follows:586 587::588 589 cmake <path-to-monorepo>/llvm-project/llvm -G Ninja \590 -DCMAKE_BUILD_TYPE=Release \591 -DLLVM_ENABLE_PROJECTS="clang;lld;lldb" \592 -DCMAKE_SYSTEM_NAME=Linux \593 -DCMAKE_SYSTEM_PROCESSOR=AArch64 \594 -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \595 -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \596 -DLLVM_HOST_TRIPLE=aarch64-unknown-linux-gnu \597 -DLLVM_NATIVE_TOOL_DIR=<path-to-host>/bin/ \598 -DLLDB_ENABLE_PYTHON=0 \599 -DLLDB_ENABLE_LIBEDIT=0 \600 -DLLDB_ENABLE_CURSES=0601 602The only difference from example 1 is the addition of603``DLLVM_NATIVE_TOOL_DIR`` pointing to your existing host build.604 605An alternative (and recommended) way to compile LLDB is with clang.606Unfortunately, clang is not able to find all the include paths necessary for a607successful cross-compile, so we need to help it with a couple of CFLAGS608options. In my case it was sufficient to add the following arguments to609``CMAKE_C_FLAGS`` and ``CMAKE_CXX_FLAGS`` (in addition to changing610``CMAKE_C(XX)_COMPILER`` to point to clang compilers):611 612::613 614 -target aarch64-linux-gnu \615 -I /usr/aarch64-linux-gnu/include/c++/4.8.2/aarch64-linux-gnu \616 -I /usr/aarch64-linux-gnu/include617 618If you wanted to build a full version of LLDB and avoid passing619``-DLLDB_ENABLE_PYTHON=0`` and other options, you would need to obtain the620target versions of the respective libraries. The easiest way to achieve this is621to use the qemu-debootstrap utility, which can prepare a system image using622qemu and chroot to simulate the target environment. Then you can install the623necessary packages in this environment (python-dev, libedit-dev, etc.) and624point your compiler to use them using the correct -I and -L arguments.625 626Example 3: Cross-compiling for Android on Linux627***********************************************628 629In the case of Android, the toolchain and all required headers and libraries630are available in the Android NDK.631 632The NDK also contains a cmake toolchain file, which makes configuring the build633much simpler. The compiler, include and library paths will be configured by the634toolchain file and all you need to do is to select the architecture635(ANDROID_ABI) and platform level (``ANDROID_PLATFORM``, should be at least 21).636You will also need to set ``ANDROID_ALLOW_UNDEFINED_SYMBOLS=On``, as the637toolchain file defaults to "no undefined symbols in shared libraries", which is638not compatible with some llvm libraries. The first version of NDK which639supports this approach is r14.640 641For example, the following arguments are sufficient to configure an android642arm64 build:643 644::645 646 -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \647 -DANDROID_ABI=arm64-v8a \648 -DANDROID_PLATFORM=android-21 \649 -DANDROID_ALLOW_UNDEFINED_SYMBOLS=On \650 -DLLVM_HOST_TRIPLE=aarch64-unknown-linux-android \651 -DCROSS_TOOLCHAIN_FLAGS_NATIVE='-DCMAKE_C_COMPILER=cc;-DCMAKE_CXX_COMPILER=c++'652 653Note that currently only lldb-server is functional on android. The lldb client654is not supported and unlikely to work.655 656Verifying Python Support657------------------------658 659LLDB has a Python scripting capability and supplies its own Python module named660lldb. If a script is run inside the command line lldb application, the Python661module is made available automatically. However, if a script is to be run by a662Python interpreter outside the command line application, the ``PYTHONPATH``663environment variable can be used to let the Python interpreter find the lldb664module.665 666The correct path can be obtained by invoking the command line lldb tool with667the -P flag:668 669::670 671 $ export PYTHONPATH=`$llvm/build/Debug+Asserts/bin/lldb -P`672 673If you used a different build directory or made a release build, you may need674to adjust the above to suit your needs. To test that the lldb Python module is675built correctly and is available to the default Python interpreter, run:676 677::678 679 $ python -c 'import lldb'680 681 682Make sure you're using the Python interpreter that matches the Python library683you linked against. For more details please refer to the :ref:`caveats684<python_caveat>`.685 686.. _CodeSigning:687 688Code Signing on macOS689---------------------690 691To use the in-tree debug server on macOS, lldb needs to be code signed. The692Debug, DebugClang and Release builds are set to code sign using a code signing693certificate named ``lldb_codesign``.694 695Automatic setup, run:696 697* ``scripts/macos-setup-codesign.sh``698 699Note that it's possible to build and use lldb on macOS without setting up code700signing by using the system's debug server. To configure lldb in this way with701cmake, specify ``-DLLDB_USE_SYSTEM_DEBUGSERVER=ON``.702 703If you have re-installed a new OS, please delete all old ``lldb_codesign`` items704from your keychain. There will be a code signing certification and a public705and private key. Reboot after deleting them. You will also need to delete and706build folders that contained old signed items. The darwin kernel will cache707code signing using the executable's file system node, so you will need to708delete the file so the kernel clears its cache.709 710When you build your LLDB for the first time, the Xcode GUI will prompt you for711permission to use the ``lldb_codesign`` keychain. Be sure to click "Always712Allow" on your first build. From here on out, the ``lldb_codesign`` will be713trusted and you can build from the command line without having to authorize.714Also the first time you debug using a LLDB that was built with this code715signing certificate, you will need to authenticate once.716