diff --git a/libc/docs/fullbuild_mode.rst b/libc/docs/fullbuild_mode.rst index 635dc8b66417f..a5c51aa4cb079 100644 --- a/libc/docs/fullbuild_mode.rst +++ b/libc/docs/fullbuild_mode.rst @@ -4,4 +4,80 @@ Fullbuild Mode ============== -Coming soon, stay tuned! +.. contents:: Table of Contents + :depth: 4 + :local: + +The *fullbuild* mode of LLVM's libc is the mode in which it is being used as +the only libc (as opposed to the :ref:`overlay_mode` in which it is used along +with the system libc.) Hence, to start using it that way, you will have to build +and install the ``libc.a`` static archive from LLVM's libc as well as the +start-up objects and public headers provided by it. In this document, we will +present a way to set up a *sysroot* (see the documentation of the ``--sysroot`` +option here: ``_) +which includes not only the components of LLVM's libc, but also full a LLVM only +toolchain consisting of the `clang `_ compiler, the +`lld `_ linker and the +`compiler-rt `_ runtime libraries. LLVM's libc +is not yet complete enough to allow using and linking a C++ application against +a C++ standard library (like libc++). Hence, we do not include a C++ standard +library in the sysroot. + +.. note:: When the libc is complete enough, we should be able to include + `libc++ `_, libcxx-abi and libunwind in the + toolchain and use them to build and link C++ applications. + +Building the full libc +====================== + +LLVM's libc uses `Scudo `_ +as its allocator. So, when building the full libc, we should specify that we +want Scudo to be included in the libc. Since the libc currently only supports +static linking, we also specify that we do not want a shared library for Scudo. +A typical ``cmake`` configure step will look like this: + +.. code-block:: sh + + $> cd llvm-project # The llvm-project checkout + $> mkdir build + $> cd build + $> cmake ../llvm -G Ninja \ + -DLLVM_ENABLE_PROJECTS="clang;libc;lld;compiler-rt" \ + -DCMAKE_BUILD_TYPE= \ # Select build type + -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \ + -DLLVM_LIBC_FULL_BUILD=ON \ # We want the full libc + -DLLVM_LIBC_INCLUDE_SCUDO=ON \ # Include Scudo in the libc + -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \ + -DCOMPILER_RT_BUILD_GWP_ASAN=OFF \ + -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF \ + -DCMAKE_INSTALL_PREFIX= # Specify a sysroot directory + +Since we want to include ``clang``, ``lld`` and ``compiler-rt`` in our +toolchain, we list them in ``LLVM_ENABLE_PROJECTS`` along with ``libc``. The +option ``CMAKE_INSTALL_PREFIX`` specifies the sysroot directory in which to +install the new toolchain. + +Installation +============ + +To build and install the libc, clang (and its support libraries and builtins), +lld and compiler-rt, run the following command after the above ``cmake`` +command: + +.. code-block:: sh + + $> ninja install-clang install-builtins install-compiler-rt \ + install-core-resource-headers install-libc install-lld + +Once the above command completes successfully, the ```` directory you +have specified with the CMake configure step above will contain a full LLVM-only +toolchain with which you can build practical/real-world C applications. See +``_ for examples +of how to start using this new toolchain. + +Linux Headers +============= + +If you are using the full libc on Linux, then you will also need to install +Linux headers in your sysroot. It is left to the reader to figure out the best +way to install Linux headers on the system they want to use the full libc on. diff --git a/libc/examples/README.md b/libc/examples/README.md new file mode 100644 index 0000000000000..ecdbe33656939 --- /dev/null +++ b/libc/examples/README.md @@ -0,0 +1 @@ +Coming soon, stay tuned!