[docs] Add/update docs regarding LLVM_NATIVE_TOOL_DIR vs LLVM_TABLEGEN

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

diff --git a/llvm/docs/CMake.rst b/llvm/docs/CMake.rst
index fba7e3f6ff0cc24e0cd70e82612f19e0b4be75a8..7926de258ec8049497acd77f467908316b010abd 100644 (file)
--- a/llvm/docs/CMake.rst
+++ b/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

diff --git a/llvm/docs/HowToBuildWithPGO.rst b/llvm/docs/HowToBuildWithPGO.rst
index 617aadc5dfe38377cd4bea9dc3adf9fa1eb4c673..977dbe7314f82882373d452c40122412ff285ba3 100644 (file)
--- a/llvm/docs/HowToBuildWithPGO.rst
+++ b/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.

diff --git a/llvm/docs/HowToCrossCompileLLVM.rst b/llvm/docs/HowToCrossCompileLLVM.rst
index 9e21160eeba97bb508657c79e03d6ff403a91e37..258d3a2eab6fceabfd8f45c3a6656a1c5b800ac6 100644 (file)
--- a/llvm/docs/HowToCrossCompileLLVM.rst
+++ b/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.