[doc][cmake] Convert read-me for the common CMake utils to reST

[Ericson2314]

Summary

@phosek mentioned others might want it reST for consistency. As I
personally do not like Markdown at all and just did the "usual GitHub
read-me thing" out of habit, I am more than happy to oblige.

Also fix the typos found in the original.

[Ericson2314]

Coming from https://reviews.llvm.org/D116477#inline-1114179, just let me know what style you think is best for the tools and runtime libs alike, @idionne, and I will happy go update all of them + the readme to match.

[lebedev.ri]

Hmm, i guess this does seem sound.
I'd like for someone else to comment (@beanz ? not sure who, out of those that are still around, owns cmake), though.

[sterni]

cmake/README.md

10

typo: should be *uses* them

[phosek]

This looks reasonable, thank you for writing it. The only thing I'm not sure about is the format. We use reStructuredText for most documentation in LLVM although we do have a handful of Markdown documents in the tree. Personally, I'm fine with either format but others may have stronger opinion on this.

cmake/README.md

44

I'd say "For runtime libraries" instead.

[beanz]

LGTM too. I think markdown is probably better than rst for documentation files that aren't part of the sphinx doc builds, so I'd leave this as md.

[Ericson2314]

I will fix the typo and convert it. I actually agree Markdown is terrible on principle, but just was doing the "usual thing for readmes on github". Even though it is not being fed to sphinx git can still be in reST.

I will make a new commit reverting it.

And sorry I already landed it. Was discussing on IRC and thought the only thing that happened was it getting a second approval from @beanz.

[Ericson2314]

Convert to reST

[Ericson2314]

I'll let this sit a bit in case anyone wants to re-review it.

[sterni]

In D116524#3229046, @Ericson2314 wrote:

I'll let this sit a bit in case anyone wants to re-review it.

The typos / wording stuff pointed out above still apply, I think.

[Ericson2314]

Fix typos

[Ericson2314]

cmake/README.rst

12 ↗

(On Diff #398356)

Fixed typo

50 ↗

(On Diff #398356)

Fixed typo

cmake/README.md

+# 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.