diff --git a/lldb/docs/resources/build.rst b/lldb/docs/resources/build.rst --- a/lldb/docs/resources/build.rst +++ b/lldb/docs/resources/build.rst @@ -36,6 +36,8 @@ * `Python `_ * `SWIG `_ 4 or later. +.. _Optional Dependencies: + Optional Dependencies ********************* @@ -423,6 +425,10 @@ Cross-compiling LLDB -------------------- +The advice presented here may not be complete or represent the best practices +of CMake at this time. Please refer to `CMake's documentation `_ +if you have any doubts or want more in depth information. + 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, @@ -458,37 +464,56 @@ -DLLDB_ENABLE_CURSES=0 -DLLVM_ENABLE_TERMINFO=0 +(see :ref:`Optional Dependencies` for more) + In this case you, will often not need anything other than the standard C and C++ libraries. +If you find that CMake is finding a version of an optional dependency that +for whatever reason doesn't work, consider simply disabling it if you don't +know that you need it. + 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: -* ``CMAKE_CROSSCOMPILING`` : Set to 1 to enable cross-compilation. -* ``CMAKE_LIBRARY_ARCHITECTURE`` : 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. +* ``CMAKE_SYSTEM_NAME`` and ``CMAKE_SYSTEM_PROCESSOR``: This tells CMake what + the build target is and from this it will infer that you are cross compiling. * ``CMAKE_C_COMPILER``, ``CMAKE_CXX_COMPILER`` : C and C++ compilers for the - target architecture + target architecture. * ``CMAKE_C_FLAGS``, ``CMAKE_CXX_FLAGS`` : The flags for the C and C++ target - compilers. You may need to specify the exact target cpu and abi besides the + compilers. You may need to specify the exact target cpu and ABI besides the include paths for the target headers. * ``CMAKE_EXE_LINKER_FLAGS`` : The flags to be passed to the linker. Usually just a list of library search paths referencing the target libraries. -* ``LLVM_TABLEGEN``, ``CLANG_TABLEGEN`` : Paths to llvm-tblgen and clang-tblgen - for the host 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. * ``LLVM_HOST_TRIPLE`` : 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. +* ``LLVM_NATIVE_TOOL_DIR`` : Is a path to the llvm tools compiled for the host. + Any tool that must be run on the host during a cross build will be configured + from this path, so you do not need to set them all individually. If you are + doing a host build just for the purpose of a cross build, you will need it + to include at least ``llvm-tblgen``, ``clang-tblgen`` and ``lldb-tblgen``. + Please be aware that that list may grow over time. +* ``CMAKE_LIBRARY_ARCHITECTURE`` : 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. + +To find the possible values of the ``CMAKE_*`` options, please refer to the +CMake documentation. You can of course also specify the usual cmake options like ``CMAKE_BUILD_TYPE``, etc. +For testing, you may want to set one of: + +* ``LLDB_TEST_COMPILER`` : The compiler used to build programs used + in the test suite. If you are also building clang, this will be used + but if you want to test remotely from the host, you should choose the + cross compiler you are using for the cross build. +* ``LLDB_INCLUDE_TESTS=0`` : To disable the tests completely. + Example 1: Cross-compiling for linux arm64 on Ubuntu host ********************************************************* @@ -499,15 +524,19 @@ :: - -DCMAKE_CROSSCOMPILING=1 \ - -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \ - -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \ - -DLLVM_HOST_TRIPLE=aarch64-unknown-linux-gnu \ - -DLLVM_TABLEGEN=/bin/llvm-tblgen \ - -DCLANG_TABLEGEN=/bin/clang-tblgen \ - -DLLDB_ENABLE_PYTHON=0 \ - -DLLDB_ENABLE_LIBEDIT=0 \ - -DLLDB_ENABLE_CURSES=0 + cmake /llvm-project/llvm -G Ninja \ + -DCMAKE_BUILD_TYPE=Release \ + -DLLVM_ENABLE_PROJECTS="clang;lld;lldb" \ + -DCMAKE_SYSTEM_NAME=Linux \ + -DCMAKE_SYSTEM_PROCESSOR=AArch64 \ + -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \ + -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \ + -DLLVM_HOST_TRIPLE=aarch64-unknown-linux-gnu \ + -DLLVM_NATIVE_TOOL_DIR=/bin/ \ + -DLLDB_ENABLE_PYTHON=0 \ + -DLLDB_ENABLE_LIBEDIT=0 \ + -DLLDB_ENABLE_CURSES=0 + 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