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

[DavidSpickett]

Summary

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.

[DavidSpickett]

I've confirmed the instructions work for x86 -> AArch64. The original issue was x86 -> Arm 32 bit, so I hope to get the issue reporter to confirm whether the instructions make sense with this change.

[JDevlieghere]

LGTM

[bulbazord]

This is in line with my understanding of cross-compiling LLDB. It could be useful to also document some other interesting cross-compilation options like CMAKE_TOOLCHAIN_FILE or mention the use of CMake caches, but if you're unfamiliar or aren't comfortable listing those that's ok too.

[DavidSpickett]

I think CMAKE_TOOLCHAIN_FILE is the "proper" way to be passing CMAKE_SYSTEM_NAME etc. so let me look into that. It may be something we get away with with current CMake, but breaks later, much like CMAKE_CROSS_COMPILING seemed to be less effective as time went on.

On caches, let me check the rest of the doc because there are some caches in tree for Mac OS. If they're already mentioned I can expand that. Maybe I'll add a cache for the x86 -> aarch64 cross compile.

[DavidSpickett]

Address feedback from Github issue:

• Include the whole command not just the additions.
• Note how to find the possible values of CMAKE_SYSTEM_*.
• Add a note about testing and setting the test compiler.

[DavidSpickett]

It could be useful to also document some other interesting cross-compilation options like CMAKE_TOOLCHAIN_FILE

So this is the way CMake prefers you to do it, but I don't really understand the best practice so I'll leave it out for now. We have plenty of caches that directly set the system and processor name in llvm already, so I am in good (/not as good as could be) company.

or mention the use of CMake caches, but if you're unfamiliar or aren't comfortable listing those that's ok too.

This seems like a general tip so I'm not sure it belongs here, beyond the fact that you might have 99 options to get a cross build, but want to tweak just one on top. Again, bit of a generic tip.

As to adding a cache file, one thing the Github poster mentioned is that if you don't set LLVM_NATIVE_TOOL_DIR we appear to compile the host tools for you now. So I'd like to land this as is, then I'll look into that and see if it can be even simpler.

[DavidSpickett]

Use <path-to-monorepo> so people have to think about what that should be for their build.

[DavidSpickett]

Will land Monday unless there are other comments.

[bulbazord]

In D158085#4598601, @DavidSpickett wrote:

It could be useful to also document some other interesting cross-compilation options like CMAKE_TOOLCHAIN_FILE

So this is the way CMake prefers you to do it, but I don't really understand the best practice so I'll leave it out for now. We have plenty of caches that directly set the system and processor name in llvm already, so I am in good (/not as good as could be) company.

IMO it's usually the safest/most sustainable way to maintain cross-compilation jobs. CMake documents all of the intricacies with cross-compiling to other platforms here on their page documenting cmake toolchains: https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html
I don't think we need to include all the intricacies, but it might be nice to maintain a link to the cmake documentation so people can self-service a bit when they encounter issues.

or mention the use of CMake caches, but if you're unfamiliar or aren't comfortable listing those that's ok too.

This seems like a general tip so I'm not sure it belongs here, beyond the fact that you might have 99 options to get a cross build, but want to tweak just one on top. Again, bit of a generic tip.

As to adding a cache file, one thing the Github poster mentioned is that if you don't set LLVM_NATIVE_TOOL_DIR we appear to compile the host tools for you now. So I'd like to land this as is, then I'll look into that and see if it can be even simpler.

Sounds good to me. Thanks for working on this!

[DavidSpickett]

Link to CMake's cross compilation docs up front, as a fallback.

[DavidSpickett]

IMO it's usually the safest/most sustainable way to maintain cross-compilation jobs.

Part of my unfamiliarity is that I don't cross compile more than one configuration at a time, so a another config file just to do what I already do always seems like work I don't need to do.

Anything else is liable to break eventually though, so I'll look into it for further updates to these instructions.

lldb/docs/resources/build.rst

 * `Ninja <https://ninja-build.org>`_ (strongly recommended)
 
 If you want to run the test suite, you'll need to build LLDB with Python
 scripting support.
 
 * `Python <http://www.python.org/>`_
 * `SWIG <http://swig.org/>`_ 4 or later.
 
+.. _Optional Dependencies:
+
 Optional Dependencies
 *********************
 
 Although the following dependencies are optional, they have a big impact on
 LLDB's functionality. It is strongly encouraged to build LLDB with these
 dependencies enabled.
 
 By default they are auto-detected: if CMake can find the dependency it will be

 
 ::
 
   -DLLDB_ENABLE_PYTHON=0
   -DLLDB_ENABLE_LIBEDIT=0
   -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
 *********************************************************
 
 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:
 
 ::
 
-  -DCMAKE_CROSSCOMPILING=1 \
+  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_TABLEGEN=<path-to-host>/bin/llvm-tblgen \
-  -DCLANG_TABLEGEN=<path-to-host>/bin/clang-tblgen \
+    -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
 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):
 
 ::