[docs] Add/update docs regarding LLVM_NATIVE_TOOL_DIR vs LLVM_TABLEGEN

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

Author: mstorsjo

llvm/docs/CMake.rst

@@ -698,6 +698,13 @@ enabled sub-projects. Nearly all of these variable names begin with
   %PATH%, then you can set this variable to the GnuWin32 directory so that
   lit can find tools needed for tests in that directory.
 
+**LLVM_NATIVE_TOOL_DIR**:STRING
+  Full path to a directory containing executables for the build host
+  (containing binaries such as ``llvm-tblgen`` and ``clang-tblgen``). This is
+  intended for cross-compiling: if the user sets this variable and the
+  directory contains executables with the expected names, no separate
+  native versions of those executables will be built.
+
 **LLVM_OPTIMIZED_TABLEGEN**:BOOL
   If enabled and building a debug or asserts build the CMake build system will
   generate a Release build tree to build a fully optimized tablegen for use

llvm/docs/HowToBuildWithPGO.rst

@@ -165,7 +165,6 @@ If this worked well for you and you plan on doing it often, there's a slight
 optimization that can be made: LLVM and Clang have a tool called tblgen that's
 built and run during the build process. While it's potentially nice to build
 this for coverage as part of step 3, none of your other builds should benefit
-from building it. You can pass the CMake options
-``-DCLANG_TABLEGEN=/path/to/stage1/bin/clang-tblgen
--DLLVM_TABLEGEN=/path/to/stage1/bin/llvm-tblgen`` to steps 2 and onward to avoid
-these useless rebuilds.
+from building it. You can pass the CMake option
+``-DLLVM_NATIVE_TOOL_DIR=/path/to/stage1/bin``
+to steps 2 and onward to avoid these useless rebuilds.

llvm/docs/HowToCrossCompileLLVM.rst

@@ -42,8 +42,7 @@ The CMake options you need to add are:
 
  * ``-DCMAKE_SYSTEM_NAME=<target-system>``
  * ``-DCMAKE_INSTALL_PREFIX=<install-dir>``
- * ``-DLLVM_TABLEGEN=<path-to-host-bin>/llvm-tblgen``
- * ``-DCLANG_TABLEGEN=<path-to-host-bin>/clang-tblgen``
+ * ``-DLLVM_NATIVE_TOOL_DIR=<path-to-host-bin>``
  * ``-DLLVM_DEFAULT_TARGET_TRIPLE=arm-linux-gnueabihf``
  * ``-DLLVM_TARGET_ARCH=ARM``
  * ``-DLLVM_TARGETS_TO_BUILD=ARM``
@@ -66,9 +65,12 @@ In addition to the ones above, you'll also need:
  * Appropriate use of ``-I`` and ``-L``, depending on how the cross GCC is installed,
    and where are the libraries and headers.
 
-The TableGen options are required to compile it with the host compiler,
-so you'll need to compile LLVM (or at least ``llvm-tblgen``) to your host
-platform before you start. The CXX flags define the target, cpu (which in this case
+The ``LLVM_NATIVE_TOOL_DIR`` option allows you to reuse prebuilt binaries
+(``llvm-tblgen``, ``clang-tblgen`` etc) for the build host, if such are
+available. If that's not available, the LLVM cross build will automatically
+launch a nested build to build the tools that are required.
+
+The CXX flags define the target, cpu (which in this case
 defaults to ``fpu=VFP3`` with NEON), and forcing the hard-float ABI. If you're
 using Clang as a cross-compiler, you will *also* have to set ``--sysroot``
 to make sure it picks the correct linker.