[Lldb-commits] [lldb] 1083ae2 - [LLDB][Docs] Update cross compilation docs and examples

Tue Aug 22 07:53:56 PDT 2023

Author: David Spickett
Date: 2023-08-22T15:53:47+01:00
New Revision: 1083ae23471839878153412d9c78955d9a7a29ac

URL: https://github.com/llvm/llvm-project/commit/1083ae23471839878153412d9c78955d9a7a29ac
DIFF: https://github.com/llvm/llvm-project/commit/1083ae23471839878153412d9c78955d9a7a29ac.diff

LOG: [LLDB][Docs] Update cross compilation docs and examples

To address https://github.com/llvm/llvm-project/issues/64616, this change
does the following:

* Links back to the "Optional Dependencies" section from the cross
  compilation instructions where we talk about removing libraries.
  In the reported issue, the host libXML was found by CMAke somehow and
  disabling libXML fixed it, so this link should encourage users
  to try as many of those options as needed.

* Removes the use of CMAKE_CROSS_COMPILING. In older CMake versions
  it seems you could set this manually but now the advice is to set
  CMAKE_SYSTEM_NAME and CMAKE_SYSTEM_PROCESSOR then let CMake figure
  it out.

  There is also CMAKE_SYSTEM_VERSION which the docs say you have to
  set too, but I can only find examples of Windows and Android builds
  using this. It might be needed to "cross" compile from one version
  of AArch64 Linux to another, but I can't confirm that.

* Removes the tablegen tools paths in favour of DLLVM_NATIVE_TOOL_DIR.
  This one setting deals with all build tools in llvm that must be host
  versions.

* Updates the explanations of the common options and orders them
  in some rough order of relevance with the "might be needed" later.

Reviewed By: JDevlieghere, bulbazord

Differential Revision: https://reviews.llvm.org/D158085

Added: 
    

Modified: 
    lldb/docs/resources/build.rst

Removed: 
    


################################################################################
diff  --git a/lldb/docs/resources/build.rst b/lldb/docs/resources/build.rst
index d4f7a558f87953..356f6d96eabcba 100644

--- a/lldb/docs/resources/build.rst
+++ b/lldb/docs/resources/build.rst
@@ -36,6 +36,8 @@ scripting support.
 * `Python <http://www.python.org/>`_
 * `SWIG <http://swig.org/>`_ 4 or later.
 
+.. _Optional Dependencies:
+
 Optional Dependencies
 *********************
 
@@ -423,6 +425,10 @@ To build the documentation, configure with ``LLVM_ENABLE_SPHINX=ON`` and build t
 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 <https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html>`_
+if you have any doubts or want more in depth information.
+
 In order to debug remote targets running 
diff erent 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 @@ further by passing the appropriate cmake options, such as:
   -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 @@ to prepare the cmake build with the following parameters:
 
 ::
 
-  -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=<path-to-host>/bin/llvm-tblgen \
-  -DCLANG_TABLEGEN=<path-to-host>/bin/clang-tblgen \
-  -DLLDB_ENABLE_PYTHON=0 \
-  -DLLDB_ENABLE_LIBEDIT=0 \
-  -DLLDB_ENABLE_CURSES=0
+  cmake <path-to-monorepo>/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=<path-to-host>/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


        
