[PATCH] D116524: [cmake] Add read me for the common CMake utils

[John Ericson via Phabricator via llvm-commits]

Ericson2314 created this revision.
Ericson2314 added reviewers: phosek, mstorsjo, beanz.
Herald added a subscriber: mgorny.
Ericson2314 requested review of this revision.
Herald added a project: LLVM.
Herald added a subscriber: llvm-commits.

Now that I am adding more things there, I thought it prudent to document
these things.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D116524

Files:
  cmake/README.md


Index: cmake/README.md
===================================================================
--- /dev/null
+++ cmake/README.md
@@ -0,0 +1,53 @@
+# LLVM Common CMake Utils
+
+## What goes here
+
+These are CMake modules to be shared between LLVM projects strictly at build
+time. In other words, they must not be included from an installed CMake module,
+such as the `Add*.cmake` ones. Modules that are reachable from installed
+modules should instead go in `${project}/cmake/modules` of the most upstream
+project that use them.
+
+The advantage of not putting these modules in an existing location like
+`llvm/cmake/modules` is two-fold:
+
+- Since they are not installed, we don't have to worry about any out-of-tree
+  downstream usage, and thus there is no need for stability.
+
+- Since they are available as part of the source at build-time, we don't have
+  to do the usual stand-alone vs combined-build dances, avoiding much
+  complexity.
+
+## How to use
+
+For tools, please do:
+
+```cmake
+if(NOT DEFINED LLVM_COMMON_CMAKE_UTILS)
+  set(LLVM_COMMON_CMAKE_UTILS ${LLVM_COMMON_CMAKE_UTILS}/../cmake)
+endif()
+
+# Add path for custom modules.
+list(INSERT CMAKE_MODULE_PATH 0
+  # project-specific module dirs first
+  "${LLVM_COMMON_CMAKE_UTILS}/Modules"
+  )
+```
+
+- The `if(NOT DEFINED ...)` guard is there because in combined builds, LLVM
+  will set this variable.  This is useful for legacy builds where projects are
+  found in `llvm/tools` instead.
+
+- `INSERT ... 0` ensures these new entries are prepended to the front of the
+  module path, so nothing might shadow them by mistake.
+
+If runtime libs, we skip the `if(NOT DEFINED` part:
+
+```cmake
+set(LLVM_COMMON_CMAKE_UTILS ${LLVM_COMMON_CMAKE_UTILS}/../cmake)
+
+... # same as before
+```
+
+If `llvm/tools` legacy-style combined builds are deprecated, we should then
+skip it everywhere, bringing the tools and runtimes boilerplate back in line.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D116524.397013.patch
Type: text/x-patch
Size: 1925 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20220103/791ff8e9/attachment.bin>