libc/docs/full_host_build.rst

   1 .. _full_host_build:
   2
   3 ===============
   4 Full Host Build
   5 ===============
   6
   7 .. contents:: Table of Contents
   8    :depth: 1
   9    :local:
  10
  11 In this document, we will present a recipe to build the full libc for the host.
  12 When we say *build the libc for the host*, the goal is to build the libc for
  13 the same system on which the libc is being built. Also, we will take this
  14 opportunity to demonstrate how one can set up a *sysroot* (see the documentation
  15 of the ``--sysroot`` option here:
  16 `<https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html>`_) which includes
  17 not only the components of LLVM's libc, but also a full LLVM only toolchain
  18 consisting of the `clang <https://clang.llvm.org/>`_ compiler, the
  19 `lld <https://lld.llvm.org/>`_ linker and the
  20 `compiler-rt <https://compiler-rt.llvm.org/>`_ runtime libraries. LLVM's libc is
  21 not yet complete enough to allow using and linking a C++ application against
  22 a C++ standard library (like libc++). Hence, we do not include
  23 `libc++ <https://libcxx.llvm.org/>`_ in the sysroot.
  24
  25 .. note:: When the libc is complete enough, we should be able to include
  26    `libc++ <https://libcxx.llvm.org/>`_, libcxx-abi and libunwind in the
  27    LLVM only toolchain and use them to build and link C++ applications.
  28
  29 Configure the full libc build
  30 ===============================
  31
  32 Below is the list of commands for a simple recipe to build and install the
  33 libc components along with other components of an LLVM only toolchain.  In this
  34 we've set the Ninja generator, enabled a full compiler suite, set the build
  35 type to "Debug", and enabled the Scudo allocator.  The build also tells clang
  36 to use the freshly built lld and compiler-rt.
  37
  38 .. code-block:: sh
  39
  40    $> cd llvm-project  # The llvm-project checkout
  41    $> mkdir build
  42    $> cd build
  43    $> SYSROOT=/path/to/sysroot # Remember to set this!
  44    $> cmake ../llvm  \
  45       -G Ninja  \
  46       -DLLVM_ENABLE_PROJECTS="clang;libc;lld;compiler-rt"   \
  47       -DCMAKE_BUILD_TYPE=Debug  \
  48       -DCMAKE_C_COMPILER=clang \
  49       -DCMAKE_CXX_COMPILER=clang++ \
  50       -DLLVM_LIBC_FULL_BUILD=ON \
  51       -DLLVM_LIBC_INCLUDE_SCUDO=ON \
  52       -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \
  53       -DCOMPILER_RT_BUILD_GWP_ASAN=OFF                       \
  54       -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF        \
  55       -DCLANG_DEFAULT_LINKER=lld \
  56       -DCLANG_DEFAULT_RTLIB=compiler-rt \
  57       -DDEFAULT_SYSROOT=$SYSROOT \
  58       -DCMAKE_INSTALL_PREFIX=$SYSROOT
  59
  60 We will go over some of the special options passed to the ``cmake`` command
  61 above.
  62
  63 * **Enabled Projects** - Since we want to build and install clang, lld
  64   and compiler-rt along with the libc, we specify
  65   ``clang;libc;lld;compiler-rt`` as the list of enabled projects.
  66 * **The full build option** - Since we want to do build the full libc, we pass
  67   ``-DLLVM_LIBC_FULL_BUILD=ON``.
  68 * **Scudo related options** - LLVM's libc uses
  69   `Scudo <https://llvm.org/docs/ScudoHardenedAllocator.html>`_ as its allocator.
  70   So, when building the full libc, we should specify that we want to include
  71   Scudo in the libc. Since the libc currently only supports static linking, we
  72   also specify that we do not want to build the Scudo shared library.
  73 * **Default sysroot and install prefix** - This is the path to the tool chain
  74   install directory.  This is the directory where you intend to set up the sysroot.
  75
  76 Build and install
  77 =================
  78
  79 After configuring the build with the above ``cmake`` command, one can build and
  80 install the libc, clang (and its support libraries and builtins), lld and
  81 compiler-rt, with the following command:
  82
  83 .. code-block:: sh
  84
  85    $> ninja install-clang install-builtins install-compiler-rt  \
  86       install-core-resource-headers install-libc install-lld
  87
  88 Once the above command completes successfully, the ``$SYSROOT`` directory you
  89 have specified with the CMake configure step above will contain a full LLVM-only
  90 toolchain with which you can build practical/real-world C applications. See
  91 `<https://github.com/llvm/llvm-project/tree/main/libc/examples>`_ for examples
  92 of how to start using this new toolchain.
  93
  94 Linux Headers
  95 =============
  96
  97 If you are using the full libc on Linux, then you will also need to install
  98 Linux headers in your sysroot.  The way to do this varies per system.
  99
 100 These instructions should work on a Debian-based x86_64 system:
 101
 102 .. code-block:: sh
 103
 104    $> apt download linux-libc-dev
 105    $> dpkg -x linux-libc-dev*deb .
 106    $> mv usr/include/* /path/to/sysroot/include
 107    $> rm -rf usr linux-libc-dev*deb
 108    $> ln -s x86_64-linux-gnu/asm ~/Programming/sysroot/include/asm
 109
 110 Using your newly built libc
 111 ===========================
 112
 113 You can now use your newly built libc nearly like you would use any compiler
 114 invocation:
 115
 116 .. code-block:: sh
 117
 118    $> /path/to/sysroot/bin/clang -static main.c
 119
 120 .. warning::
 121    Because the libc does not yet support dynamic linking, the -static parameter
 122    must be added to all clang invocations.
 123