See also this topic on discourse: https://discourse.llvm.org/t/an-opinionated-way-to-outsource-simplify-and-unify-repetitive-cmake-code-in-standalone-build-mode/67508
Rationale
This is an opinionated change for the standalone build mode CMake code.
The rationale behind this change is to unify the parts of standalone
builds that historically had to be kept in each and every project. With
the advent of the top-level cmake directory inside the LLVM source
tree, it is now possible to bundle the CMake instructions into a file,
aka cmake/Modules/StandaloneBuildHelpers.cmake, and include that file
in each project that wants to build in standalone-mode.
Historically the standalone build mode is used mostly by Linux
distributions. Certainly not every LLVM contributor cares about Linux
distributions. To reduce the frictions it makes even more sense to have
a unified place where to keep the specialities of building in standalone
mode.
Affected projects (so far)
This change brings the unified standalone build mode to the clang and
lld project.
Assumptions
One radical assumption for this change is that in order to build clang
or ldd in standalone mode, you have to first build the llvm subproject
and *install* it into any location. You can assist the build process to
find LLVM using find_package(LLVM) by specifying
-DCMAKE_PREFIX_PATH=${LLVM_INSTALL_DIR}/lib/cmake/llvm in the cmake
configuration process.
You have to build the `llvm subproject with utilies included and
installed
(-DLLVM_INCLUDE_UTILS:BOOL=ON and -DLLVM_INSTALL_UTILS:BOOL=ON. But
I'm sure that this is done most of the time anyways, no?
Don't build as you go: No more cross-project dependencies on LLVM utilties
Another assumption is that in standalone build mode it makes no sense to
build clang and try to build an LLVM utility binary like FileCheck if
that is missing. This only adds noise to the cmake files and creates an
indirect dependency on the LLVM utilities directory which doesn't exist
in the the clang source tarball. Therefore we go and search for
Don't silently turn off tests
Before this change, we would silently turn off tests if a binary like
FileCheck, count or not was missing. This is not only dangerous
but IMHO not helpful. If someone asks for tests by passing
-DLLVM_INCLUDE_TESTS=On we should error out at configure time because
we cannot fulfil this request when a binary is missing. This is exactly
what this tests does. If you want to check if an LLVM utility binary
exists and what the path to it is, you can call
get_llvm_utility_binary_path("FileCheck" "FileCheck_EXE") and it will
get the import location for the target, aka the path to the binary that
was found when we did find_package(LLVM).
Require external LIT in standalone mode
We also think that in standalone mode you always want to use an external
lit and not build it as you go. That's why the find_external_lit macro
checks if LLVM_EXTERNAL_LIT is set and the path exists. If one of
these conditions doesn't hold true, we error out.
TODO:
( ) make sure the correct binaries of FileCheck and count and not
get substituted in lit test files.
( ) get feedback on this change or just opinions
( ) extend usage to other projects like mlir, libomp and so on.
( ) more encapsulation in cmake/Modules/StandaloneBuildHelpers.cmake
It's somewhat unusual to quote output variable names in our CMake files, I'd prefer to follow existing conventions for consistency.