[cmake] Enable building tests when cross compiling (#2354)
This commit enables -DIREE_BUILD_TESTS=ON when invoking CMake
with a toolchain file. Now we can compile non-host-only tests
towards, e.g., ARM for Android.
This commit also enables cross-compiling iree-benchmark-module.
diff --git a/docs/GetStarted/cmake_options_and_variables.md b/docs/GetStarted/cmake_options_and_variables.md
index 33b8d04..3316a59 100644
--- a/docs/GetStarted/cmake_options_and_variables.md
+++ b/docs/GetStarted/cmake_options_and_variables.md
@@ -97,6 +97,9 @@
## Cross-compilation
+[TODO(#2111): The following explanation is developer oriented. Move it to
+the developer build doc once we've created that.]
+
Cross-compilation involves both a *host* platform and a *target* platform. One
invokes compiler toolchains on the host platform to generate libraries and
executables that can be run on the target platform.
@@ -114,6 +117,32 @@
above conceptual two-stage compilation happens in two separate CMake
invocations.
+When CMake is invoked with a toolchain file, e.g.,
+[`android.toolchain.cmake`](https://android.googlesource.com/platform/ndk/+/master/build/cmake/android.toolchain.cmake),
+we get the compiler toolchain for the target platform from the toolchain file.
+IREE under the hood will [create another CMake invocation](https://github.com/google/iree/blob/main/build_tools/cmake/iree_cross_compile.cmake)
+using host platform's compiler toolchain. The inner CMake invocation will be
+placed under `IREE_HOST_BINARY_ROOT`.
+
+The tricky part is to set up target artifacts' dependencies on host executables.
+Normally in CMake we define targets and `target_link_libraries` to express the
+dependency relationship between targets. The optimal way is to [`export`](https://cmake.org/cmake/help/latest/command/export.html)
+targets under host configuration and then [`import`](https://cmake.org/cmake/help/latest/command/add_executable.html?highlight=import#imported-executables)
+into target configuration. But that is not playing well with LLVM's TableGen
+configurations. LLVM's cross-compilation uses on files for dependencies. So
+here we need to do the same. This results in reverting the relationship between
+IREE artifact output names (e.g., `iree-translate`) and IREE package-prefixed
+CMake target names (e.g., `iree_tools_iree-translate`).
+
+When not cross-compiling, IREE uses the CMake target names as the real unique
+identification inside CMake for defining the object and expressing dependencies;
+the artifact output names are just used for naming the build artifacts. When
+cross-compiling, it's the artifact names being load-bearing. The artifact names
+are used to express dependencies across CMake invocation boundary (remember that
+we cannot access targets defined in another CMake invocation);
+the package-prefixed CMake target names are just cutom targets depending on
+the host artfact.
+
#### `IREE_HOST_BINARY_ROOT`:FILEPATH
Specifies the root directory for containing all host CMake invocation artifacts.
