[PATCH] D121761: [draft] runtimes doc wip

[Martin Storsjö via Phabricator via llvm-commits]

mstorsjo added a subscriber: ldionne.
mstorsjo added a comment.

FWIW, libc++ has some amount of docs on the same matter, see e.g. https://libcxx.llvm.org/BuildingLibcxx.html#the-default-build, also CC @ldionne. Regarding naming of the different build configurations, in the libc++ docs, the setup originally called "runtimes build" is now called "bootstrapping build", as "runtimes build" easily can be confused with manually building using the `llvm-project/runtimes` directory.



================
Comment at: llvm/docs/RuntimeBuild.rst:24
+1. Where LLVM's build system puts the runtime libraries it builds
+2. Where clang looks for runtime libraries
+
----------------
AFAIK, 2. here isn't true. Clang doesn't get the value of `LLVM_ENABLE_PER_TARGET_RUNTIME_DIR` hardcoded in anywhere (and depending on the `--target` option, there might be different expectations for where to find the runtimes).

Additionally, Clang doesn't consistently check for runtimes in in the per-target runtime directory, but code for doing that is enabled in a handful of targets (some of the ones in clang/lib/Driver/ToolChains), but not all of them; the code for doing it is scattered around the subclasses. The ones that support it look for both kinds of layouts and add the directories if they are found - so afaik, Clang is pretty much agnostic.


================
Comment at: llvm/docs/RuntimeBuild.rst:52
+* ``lib/clang/14.0.0/lib/aarch64-unknown-fuchsia/libclang_rt.builtins.a``
+
+Where clang looks for runtime libraries
----------------
These examples cover the case of compiler-rt runtimes, but e.g. libc++ usually is installed in `<toolchain>/lib` right? And with the per-target runtimes, it's installed in `<toolchain>/lib/<triple>`.

It also affects how libc++'s `__config_site` is installed; most libc++ headers are installed in a target-independent directory, while `__config_site` is kept in a per-target directory.


================
Comment at: llvm/docs/RuntimeBuild.rst:81
+  discover the macOS version of the machine that built Xcode's ``clang`` binary
+  this way!)
+
----------------
Hmm, I'm pretty sure the version number is picked up from the host OS. (I get the same version number, matching my version of macOS, when I run the clang binary from a bunch of differing old and new Xcode versions.)


================
Comment at: llvm/docs/RuntimeBuild.rst:87
+* "``cpu``" is something like ``x86_64`` (64-bit intel), ``i386`` (32-bit
+  intel), ``armv7a`` (32-bit arm v7 application profile), ``arm64`` (64-bit arm
+  on darwin), ``aarch64`` (64-bit arm on non-darwin). It determines which CPU
----------------
Just as a tangentially related sidenote; `arm64` on darwin is a tricky case, as LLVM internally normalizes it to `aarch64` even on that OS - or at least it used to. `clang -arch arm64 -dumpmachine` did print `aarch64-apple-darwin...` still in Xcode 12; in Xcode 13 it keeps it as `arm64-apple-darwin...` though.


================
Comment at: llvm/docs/RuntimeBuild.rst:100
+  targeting Windows, ``x86_64-pc-windows-msvc`` picks the Microsoft-compatible
+  ABI, while ``x86_64-pc-windows-mingw`` picks the gcc-compatible ABI. As
+  another example, when targeting Android, this is set to ``android`` (or,
----------------
In the normalized form, mingw (any OS string starting with `mingw32` iirc) corresponds to `windows-gnu`, not `windows-mingw`.


================
Comment at: llvm/docs/RuntimeBuild.rst:141
+and others can be built either by including them in ``LLVM_ENABLE_PROJECTS``
+or in ``LLVM_ENABLE_RUNTIMES`` ("runtimes build").
+
----------------
FWIW, at least for libc++, building it with `LLVM_ENABLE_PROJECTS` is discouraged/deprecated these days. I think both options are still meant to work for e.g. compiler-rt though. (One usecase I've heard about there, is for other languages, who build LLVM and compiler-rt using the existing host C compiler, but don't actually build Clang at all.)


Here it could also be useful to mention building by pointing cmake at `llvm-project/runtimes`, which is a standalone-ish build, where you manually configure cmake to use your desired (cross)compiler. Similar to pointing cmake directly at e.g. `llvm-project/libc++` before, but allowing processing more than one runtime in one cmake invocation.


================
Comment at: llvm/docs/RuntimeBuild.rst:149
+* ``LLVM_ENABLE_PER_TARGET_RUNTIME_DIR`` (documented further up) defaults to
+  ``ON``.
+
----------------
This sentence could be clarified that it is for the runtimes build mode (as the previous bullet covers both).


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D121761/new/

https://reviews.llvm.org/D121761