diff --git a/libc/docs/index.rst b/libc/docs/index.rst --- a/libc/docs/index.rst +++ b/libc/docs/index.rst @@ -82,3 +82,4 @@ mechanics_of_public_api redirectors source_layout + runtimes_build diff --git a/libc/docs/runtimes_build.rst b/libc/docs/runtimes_build.rst new file mode 100644 --- /dev/null +++ b/libc/docs/runtimes_build.rst @@ -0,0 +1,36 @@ +Building libc using the runtimes build setup +============================================ + +The runtimes build of the LLVM toolchain first builds clang and then builds the +various runtimes (like ``libc++`` and ``compiler-rt``) and LLVM binutils (like +``llvm-objcopy`` and ``llvm-readelf``) using the freshly built clang. One can +build libc also as in the same manner. As of this writing, only the ABI agnostic +parts of the libc are included when built in that manner. This allows interested +users to continue using their system libc's headers while linking to LLVM libc's +implementations when they are available. To build libc using the runtimes build +setup, one needs to include the ``libc`` project in the list of the enabled +runtimes when configuring the build: + +.. code-block:: shell + + $> cmake ../llvm -GNinja -DLLVM_ENABLE_PROJECTS="llvm;clang" \ + -DLLVM_ENABLE_RUNTIMES=libc + +Note that Ninja is used as the generator in the above CMake command. Hence, to +actually build the libc, one has to build the target named ``llvmlibc``: + +.. code-block:: shell + + $> ninja llvmlibc + +If a different generator is used, then the build command should be suitably +adapted to build the target ``llvmlibc``. Building that target will produce a +static archive which includes all ABI agnostic functions available in LLVM libc. + +Future direction +---------------- + +We plan to enhance the runtimes build of LLVM libc to include ABI sensitive +parts and to also generate the public headers. Likewise, we would like to +provide an option to build other runtimes like ``libc++`` and ``compiler-rt`` +against LLVM libc.