[lldb][Docs] Add simpler "automatic" cross-compile option to build docs (#65311)

The main way I cross build lldb is to point CMake at an existing host
build to get the native tablegen tools. This is what we had documented
before.

There is another option where you start from scratch and the host tools
are built for you. This patch documents that and explains which one to
choose.

Added another arm64 example which uses this. So the frst one is the
"automatic" build and the second is the traditional approach.

For ease of copy paste and understanding, I've kept the full command in
each section and noted the one difference between them.

Along the way I updated some of the preamble to explain the two
approaches and updated some language e.g. removing "just ...". Eveyone's
"just" is different, doubly so when cross-compiling.

1 files changed, 58 insertions, 17 deletions

diff --git a/lldb/docs/resources/build.rst b/lldb/docs/resources/build.rst
index 25ba3bf..b405a20 100644
--- a/lldb/docs/resources/build.rst
+++ b/lldb/docs/resources/build.rst
@@ -427,10 +427,10 @@ of CMake at this time. Please refer to `CMake's documentation <https://cmake.org
 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,
-this is often not feasible, and in these cases you will need to cross-compile
-LLDB on your host.
+host, you will need to compile LLDB (or at least the server component
+``lldb-server``) for the target. While the easiest solution is to 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.
 
 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
@@ -470,9 +470,22 @@ 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:
+Once all of the dependencies are in place, you need to configure the build
+system with the locations and arguments of all the necessary tools.
+
+There are 2 ways to do this depending on your starting point and requirements.
+
+1. If you are starting from scratch and only need the resulting cross compiled
+binaries, you can have LLVM build the native tools for you.
+
+2. If you need a host build too, or already have one, you can tell CMake where
+that is and it will use those native tools instead.
+
+If you are going to run ``lldb`` and ``lldb-server`` only on the target machine,
+choose option 1. If you are going to run ``lldb`` on the host machine and
+connect to ``lldb-server`` on the target, choose option 2.
+
+Either way, the most important cmake options when cross-compiling are:
 
 * ``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.
@@ -482,17 +495,18 @@ The most important cmake options here are:
   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.
+  this is a list of library search paths referencing the target libraries.
 * ``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.
+* ``LLVM_NATIVE_TOOL_DIR`` (only when using an existing host build): 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 only for the
+  purpose of a cross build, you will need it to include at least
+  ``llvm-tblgen``, ``clang-tblgen`` and ``lldb-tblgen``. Be aware that
+  the 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.
@@ -516,8 +530,33 @@ Example 1: Cross-compiling for linux arm64 on Ubuntu host
 
 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:
+``g++-aarch64-linux-gnu``, ``binutils-aarch64-linux-gnu``.
+
+Configure as follows:
+
+::
+
+  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 \
+    -DLLDB_ENABLE_PYTHON=0 \
+    -DLLDB_ENABLE_LIBEDIT=0 \
+    -DLLDB_ENABLE_CURSES=0
+
+During this build native tools will be built automatically when they are needed.
+The contents of ``<build dir>/bin`` will be target binaries as you'd expect.
+AArch64 binaries in this case.
+
+Example 2: Cross-compiling for linux arm64 on Ubuntu host using an existing host build
+**************************************************************************************
+
+This build requires an existing host build that includes the required native
+tools. Install the compiler as in example 1 then run CMake as follows:
 
 ::
 
@@ -534,6 +573,8 @@ to prepare the cmake build with the following parameters:
     -DLLDB_ENABLE_LIBEDIT=0 \
     -DLLDB_ENABLE_CURSES=0
 
+The only difference from example 1 is the addition of
+``DLLVM_NATIVE_TOOL_DIR`` pointing to your existing host build.
 
 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
@@ -556,7 +597,7 @@ 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.
 
-Example 2: Cross-compiling for Android on Linux
+Example 3: Cross-compiling for Android on Linux
 ***********************************************
 
 In the case of Android, the toolchain and all required headers and libraries