[PATCH] D121761: [draft] runtimes doc wip

Wed Mar 16 07:54:48 PDT 2022

ldionne added a comment.

This is awesome -- I think the lack of documentation for the bootstrapping build is one of the main reasons for its slow adoption. Even as a very frequent libc++ contributor, I still don't understand some parts of it (for example how to pass options to specific runtimes, e.g. how to pass `LIBCXX_TEST_CONFIG` to the libc++ build through the bootstrapping build). It would be nice if we could publish this documentation.

================
Comment at: llvm/docs/RuntimeBuild.rst:1
+reviewers: collinbaker, jdionne, phosek, maskray, danalbert, mstorsjo
+cc: rnk
----------------
😄

================
Comment at: llvm/docs/RuntimeBuild.rst:5
+==================
+The runtimes build
+==================
----------------
I would love if we could officially start calling it the "bootstrapping build"!

================
Comment at: llvm/docs/RuntimeBuild.rst:63
+triple is inferred from ``-m32`` / ``-m64`` flags, ``-arch`` flags on darwin
+(in practice, "darwin" means "iOS or macOS"), or if no flags are passed, by the
+value of ``LLVM_DEFAULT_TARGET_TRIPLE`` used at cmake time.
----------------
Also `watchos` and `tvos` -- perhaps it's easier to just drop this parenthesis so it doesn't become outdated.

================
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
----------------
mstorsjo wrote:
> thakis wrote:
> > mstorsjo wrote:
> > > 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.
> > As a tangent to the tangent, (32-bit) arm is also weird in that (e.g.) `--target=arm-linux-androideabi` leads to a cc1 `-triple armv4t-unknown-linux-android`, but `--target=arm-linux-androideabi -march=armv7a` leads to a cc1 `-triple armv7-unknown-linux-android` – i.e. march flags affect the cc1 level triple. You can get the same cc triple by passing `--armv7a-linux-androideabi` without `-march` flag.
> > 
> > On the flipside, `--target=i386-linux` and `--target=i386-unknown-linux` result in the same cc1 triple (`i386-unknown-linux`).
> > 
> > I don't fully understand the motivation behind `LLVM_ENABLE_PER_TARGET_RUNTIME_DIR` yet. I thought it's so it's possible to build compiler-rt for different target configs, but it imho it currently doesn't work well because:
> > 
> > 1. It uses the canonicalized driver-level triple.
> >   * This makes it impossible to build a toolchain that just works for users, since users can use a `--target` flag that canonicalizes to the same triple that you've built libraries for, but since clang looks in the non-canonicalized location you have to guess all possible --target spellings users might use and include symlinks or what
> >   * likewise, you have to guess if users will pick arm level via -march or via triple (or have symlinks for both)
> >   * before D115049, you had to have a dedicated symlink for every single android abi level
> >   * In the other direction, it makes it impossible to have different compiler-rt prebuilts for (say) avx512 on and off, since that's not in the triple
> > 
> > 2. It's not really clear (to me) what the goal even is
> (Speaking as someone who have touched these things quite a bit - not as someone arguing specifically for or against the feature.)
> 
> I think the main motivation is to better support multiarch setups, and with better granularity. For compiler-rt, that's already supported in various ways with filenames such as `libclang_rt.asan-x86_64.a`. But for e.g. libc++, in the current release tarballs, it's provided in `<prefix>/lib/libc++.so` which clearly doesn't scale when targeting even 32+64 bit x86 on the same OS.
> 
> Additionally, it's also supposed to handle other variability than just plain different target architectures - e.g. if building with `-fno-exceptions`, it's supposed to be able to find a copy of libc++ that is built without exceptions, and if building with asan, it can give you an asan-instrumented libc++. AFAIK the fuchsia cache files build a bunch of runtimes (for fuchsia and possibly other OSes too) in this way.
> 
> I totally agree that the variability in mostly-equivalent triples is the main practical issue wrt this.
> 
> 
> In my mingw toolchains (which are structured around cross compiling - native compiling is just a special case), I don't use this feature (yet). All arch-specific files are available in `<prefix>/<triple>/{include,lib}` which are implicitly picked up as sysroots, so there's none of that in `<prefix>/lib`, and the compiler-rt files contain the arch in the file name already.
FWIW I'd be supportive of a plan to ship libc++ and libc++abi in a per-target runtime directory by default, if someone wanted to take over that task.

================
Comment at: llvm/docs/RuntimeBuild.rst:146
+* In the runtimes build, the runtimes are built with just-built clang.
+  In the ``LLVM_ENABLE_PROJECTS`` mode, they are built with the host compiler.
+
----------------
We should remove any reference to `LLVM_ENABLE_PROJECTS` for the runtimes, and instead use `LLVM_ENABLE_RUNTIMES` but root the CMake invocation at `<monorepo>/runtimes` instead of `<monorepo>/llvm/runtimes`.

Yes, that's a bit confusing, we could improve that.

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

https://reviews.llvm.org/D121761