Index: llvm/docs/RuntimeBuild.rst =================================================================== --- /dev/null +++ llvm/docs/RuntimeBuild.rst @@ -0,0 +1,155 @@ +reviewers: collinbaker, jdionne, phosek, maskray, danalbert, mstorsjo +cc: rnk + +================== +The runtimes build +================== + +.. contents:: + :local: + +Introduction +============ + +This document describes the effect of setting +``LLVM_ENABLE_PER_TARGET_RUNTIME_DIR``, and the difference between +``LLVM_ENABLE_PROJECTS`` and ``LLVM_ENABLE_RUNTIMES``. + +``LLVM_ENABLE_PER_TARGET_RUNTIME_DIR`` +====================================== + +``LLVM_ENABLE_PER_TARGET_RUNTIME_DIR`` controls: + +1. Where LLVM's build system puts the runtime libraries it builds +2. Where clang looks for runtime libraries + + +Where LLVM's build system puts the runtime libraries it builds +-------------------------------------------------------------- + +As of early 2022, ``LLVM_ENABLE_PER_TARGET_RUNTIME_DIR`` defaults to off +everywhere. The "ON" setting is newer and it might become the default once +kinks are worked out. For perspective, ``LLVM_ENABLE_PER_TARGET_RUNTIME_DIR`` +was initially added mid-2018. + +The problem that the new setting tries to solve is XXX. + +With ``LLVM_ENABLE_PER_TARGET_RUNTIME_DIR=OFF``, runtimes are placed in +``lib/clang/$version/lib/$host_os/$runtime_name-$optional_suffix.so``. Here +are a few concrete examples of runtime library names with this setup: + +* ``lib/clang/14.0.0/lib/darwin/libclang_rt.osx.a`` +* ``lib/clang/6.0.0/lib/linux/libclang_rt.asan-x86_64.a`` +* ``lib/clang/6.0.0/lib/linux/libclang_rt.asan-arm-android.so`` +* ``lib/clang/12.0.0/lib/windows/clang_rt.profile-x86_64.lib`` + +With ``LLVM_ENABLE_PER_TARGET_RUNTIME_DIR=ON``, runtimes are instead +organized by triple:``lib/clang/$version/lib/$triple/$runtime_name.so``. Here +are a few concrete examples of this setup: + +* ``lib/clang/14.0.0/lib/x86_64-unknown-linux-gnu/libclang_rt.asan.a`` +* ``lib/clang/14.0.0/lib/aarch64-unknown-fuchsia/libclang_rt.builtins.a`` + +Where clang looks for runtime libraries +--------------------------------------- + +clang's behavior depends on the current triple. + +Triples ++++++++ + +If ``--target=`` is passed, its value is the current triple. Else, the current +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. +``LLVM_DEFAULT_TARGET_TRIPLE`` defaults to the triple of the system that clang +was built on. + +``clang -v -c foo.c`` prints the current triple as ``"Target: +$current_triple"``. + +``clang -dumpmachine`` prints the default triple. + +Here are a few examples of flags and the triples they imply: + +* ``--target=x86_64-unknown-linux-gnu`` sets the current triple to + ``x86_64-unknown-linux-gnu``. + +* ``-arch arm64`` when run with a clang built on macOS 12.2 sets the current + triple to ``arm64-apple-darwin21.2.0``. (If you use Xcode's clang, you can + discover the macOS version of the machine that built Xcode's ``clang`` binary + this way!) + +A triple has the general form of ``$cpu-$vendor-$os-$environment``. The fourth +component (the environment) is optional. + +* "``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 + clang generates code for. + +* "``vendor``" is something like ``pc`` or ``apple``. It usually doesn't have + a big effect, and at least when targeting Linux it's often just ``unknown``. + +* "``os``" is the operating system to target, for example ``linux``, + ``windows``, ``darwin``, and so on. This component can have a number suffix, + for example ``darwin21.2.0``. + +* "``environment``" can communicate extra information. For example, when + 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, + for 32-bit arm, ``androideabi``). This can also end in a number, for example + to communicate Android NDK minimum supported OS version + (``armv7a-unknown-linux-androideabi23``) or Microsoft ABI version + (``x86_64-pc-windows-msvc15``). + +In practice, some of the components are sometimes omitted. For example, +``--target=armv7a-linux-androideabi23`` omits the vendor. LLVM's triple parsing +detects this. The interpreted triple with missing parts filled in is called +the "canonical triple" and is ``armv7a-unknown-linux-androideabi23`` in this +case. As another example, ``--target=x86_64-linux`` has +``x86_64-unknown-linux`` as canonical target. However, if clang was built on +a 64-bit Linux system, the default triple that's used when no flags are passed +is ``x86_64-unknown-linux-gnu``. + +XXX -march, -mfloat-abi + +cc1 triple vs driver-level triple + +Runtime lookup +++++++++++++++ + +Implications +------------ + +* "tends to fallback too often, in rare cases" + +This has several implications: XXX + +* old way is stable, works well, can handle "fallback" + +* new way allows supporting multiple ABIs per ISA + +* "tends to fallback too rarely, in common cases" + +``LLVM_ENABLE_PROJECTS`` vs ``LLVM_ENABLE_RUNTIMES`` +==================================================== + +LLVM's runtime libraries like compiler-rt (builtins, asan runtime, ...) +and others can be built either by including them in ``LLVM_ENABLE_PROJECTS`` +or in ``LLVM_ENABLE_RUNTIMES`` ("runtimes build"). + +The difference between the two modes are: + +* 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. + +* ``LLVM_ENABLE_PER_TARGET_RUNTIME_DIR`` (documented further up) defaults to + ``ON``. + +* More flexibility + * different sysroots per triple + +* Sub-cmakes + * Doesn't do anything you couldn't do yourself by running cmake several times