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 .. note::
  12    Fullbuild requires running headergen, which is a python program that depends on
  13    pyyaml. The minimum versions are listed on the :ref:`header_generation`
  14    page, as well as additional information.
  15
  16 In this document, we will present a recipe to build the full libc for the host.
  17 When we say *build the libc for the host*, the goal is to build the libc for
  18 the same system on which the libc is being built. First, we will explain how to
  19 build for developing LLVM-libc, then we will explain how to build LLVM-libc as
  20 part of a complete toolchain.
  21
  22 Configure the build for development
  23 ===================================
  24
  25
  26 Below is the list of commands for a simple recipe to build LLVM-libc for
  27 development. In this we've set the Ninja generator, set the build type to
  28 "Debug", and enabled the Scudo allocator. This build also enables generating the
  29 documentation and verbose cmake logging, which are useful development features.
  30
  31 .. note::
  32    if your build fails with an error saying the compiler can't find
  33    ``<asm/unistd.h>`` or similar then you're probably missing the symlink from
  34    ``/usr/include/asm`` to ``/usr/include/<HOST TRIPLE>/asm``. Installing the
  35    ``gcc-multilib`` package creates this symlink, or you can do it manually with
  36    this command:
  37    ``sudo ln -s /usr/include/<HOST TRIPLE>/asm /usr/include/asm``
  38    (your host triple will probably be similar to ``x86_64-linux-gnu``)
  39
  40 .. code-block:: sh
  41
  42    $> cd llvm-project  # The llvm-project checkout
  43    $> mkdir build
  44    $> cd build
  45    $> cmake ../runtimes \
  46       -G Ninja \
  47       -DCMAKE_C_COMPILER=clang \
  48       -DCMAKE_CXX_COMPILER=clang++ \
  49       -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \
  50       -DLLVM_LIBC_FULL_BUILD=ON \
  51       -DCMAKE_BUILD_TYPE=Debug \
  52       -DLLVM_LIBC_INCLUDE_SCUDO=ON \
  53       -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \
  54       -DCOMPILER_RT_BUILD_GWP_ASAN=OFF                       \
  55       -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF        \
  56       -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
  57       -DLLVM_ENABLE_SPHINX=ON -DLIBC_INCLUDE_DOCS=ON \
  58       -DLIBC_CMAKE_VERBOSE_LOGGING=ON
  59
  60 Build and test
  61 ==============
  62
  63 After configuring the build with the above ``cmake`` command, one can build test
  64 libc with the following command:
  65
  66 .. code-block:: sh
  67
  68    $> ninja libc libm check-libc
  69
  70 To build the docs run this command:
  71
  72
  73 .. code-block:: sh
  74
  75    $> ninja docs-libc-html
  76
  77 To run a specific test, use the following:
  78
  79 .. code-block:: sh
  80
  81    $> ninja libc.test.src.<HEADER>.<FUNCTION>_test.__unit__
  82    $> ninja libc.test.src.ctype.isalpha_test.__unit__ # EXAMPLE
  83
  84 Configure the complete toolchain build
  85 ======================================
  86
  87 For a complete toolchain we recommend creating a *sysroot* (see the documentation
  88 of the ``--sysroot`` option here:
  89 `<https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html>`_) which includes
  90 not only the components of LLVM's libc, but also a full LLVM only toolchain
  91 consisting of the `clang <https://clang.llvm.org/>`_ compiler, the
  92 `lld <https://lld.llvm.org/>`_ linker and the
  93 `compiler-rt <https://compiler-rt.llvm.org/>`_ runtime libraries. LLVM-libc is
  94 not quite complete enough to allow using and linking a C++ application against
  95 a C++ standard library (like libc++). Hence, we do not include
  96 `libc++ <https://libcxx.llvm.org/>`_ in the sysroot.
  97
  98 .. note:: When the libc is complete enough, we should be able to include
  99    `libc++ <https://libcxx.llvm.org/>`_, libcxx-abi and libunwind in the
 100    LLVM only toolchain and use them to build and link C++ applications.
 101
 102 Below is the list of commands for a simple recipe to build and install the
 103 libc components along with other components of an LLVM only toolchain.  In this
 104 we've set the Ninja generator, enabled a full compiler suite, set the build
 105 type to "Debug", and enabled the Scudo allocator.  The build also tells clang
 106 to use the freshly built lld and compiler-rt.
 107
 108 .. note::
 109    if your build fails with an error saying the compiler can't find
 110    ``<asm/unistd.h>`` or similar then you're probably missing the symlink from
 111    ``/usr/include/asm`` to ``/usr/include/<TARGET TRIPLE>/asm``. Installing the
 112    ``gcc-multilib`` package creates this symlink, or you can do it manually with
 113    this command:
 114    ``sudo ln -s /usr/include/<TARGET TRIPLE>/asm /usr/include/asm``
 115
 116 .. TODO: Move from projects to runtimes for libc, compiler-rt
 117 .. code-block:: sh
 118
 119    $> cd llvm-project  # The llvm-project checkout
 120    $> mkdir build
 121    $> cd build
 122    $> SYSROOT=/path/to/sysroot # Remember to set this!
 123    $> cmake ../llvm  \
 124       -G Ninja  \
 125       -DLLVM_ENABLE_PROJECTS="clang;lld;libc;compiler-rt"   \
 126       -DCMAKE_BUILD_TYPE=Debug  \
 127       -DCMAKE_C_COMPILER=clang \
 128       -DCMAKE_CXX_COMPILER=clang++ \
 129       -DLLVM_LIBC_FULL_BUILD=ON \
 130       -DLLVM_LIBC_INCLUDE_SCUDO=ON \
 131       -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \
 132       -DCOMPILER_RT_BUILD_GWP_ASAN=OFF                       \
 133       -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF        \
 134       -DCLANG_DEFAULT_LINKER=lld \
 135       -DCLANG_DEFAULT_RTLIB=compiler-rt \
 136       -DDEFAULT_SYSROOT=$SYSROOT \
 137       -DCMAKE_INSTALL_PREFIX=$SYSROOT
 138
 139 We will go over some of the special options passed to the ``cmake`` command
 140 above.
 141
 142 * **Enabled Projects** - Since we want to build and install clang, lld
 143   and compiler-rt along with the libc, we specify
 144   ``clang;libc;lld;compiler-rt`` as the list of enabled projects.
 145 * **The full build option** - Since we want to do build the full libc, we pass
 146   ``-DLLVM_LIBC_FULL_BUILD=ON``.
 147 * **Scudo related options** - LLVM's libc uses
 148   `Scudo <https://llvm.org/docs/ScudoHardenedAllocator.html>`_ as its allocator.
 149   So, when building the full libc, we should specify that we want to include
 150   Scudo in the libc. Since the libc currently only supports static linking, we
 151   also specify that we do not want to build the Scudo shared library.
 152 * **Default sysroot and install prefix** - This is the path to the tool chain
 153   install directory.  This is the directory where you intend to set up the sysroot.
 154
 155 Build and install
 156 =================
 157
 158 .. TODO: add this warning to the cmake
 159 .. warning::
 160    Running these install commands without setting a ``$SYSROOT`` will install
 161    them into your system include path, which may break your system. If you're
 162    just trying to develop libc, then just run ``ninja check-libc`` to build the
 163    libc and run the tests. If you've already accidentally installed the headers,
 164    you may need to delete them from ``/usr/local/include``.
 165
 166 After configuring the build with the above ``cmake`` command, one can build and
 167 install the libc, clang (and its support libraries and builtins), lld and
 168 compiler-rt, with the following command:
 169
 170 .. code-block:: sh
 171
 172    $> ninja install-clang install-builtins install-compiler-rt  \
 173       install-core-resource-headers install-libc install-lld
 174
 175 Once the above command completes successfully, the ``$SYSROOT`` directory you
 176 have specified with the CMake configure step above will contain a full LLVM-only
 177 toolchain with which you can build practical/real-world C applications. See
 178 `<https://github.com/llvm/llvm-project/tree/main/libc/examples>`_ for examples
 179 of how to start using this new toolchain.
 180
 181 Linux Headers
 182 =============
 183
 184 If you are using the full libc on Linux, then you will also need to install
 185 Linux headers in your sysroot.  The way to do this varies per system.
 186
 187 These instructions should work on a Debian-based x86_64 system:
 188
 189 .. code-block:: sh
 190
 191    $> apt download linux-libc-dev
 192    $> dpkg -x linux-libc-dev*deb .
 193    $> mv usr/include/* /path/to/sysroot/include
 194    $> rm -rf usr linux-libc-dev*deb
 195    $> ln -s x86_64-linux-gnu/asm ~/Programming/sysroot/include/asm
 196
 197 Using your newly built libc
 198 ===========================
 199
 200 You can now use your newly built libc nearly like you would use any compiler
 201 invocation:
 202
 203 .. code-block:: sh
 204
 205    $> /path/to/sysroot/bin/clang -static main.c
 206
 207 .. warning::
 208    Because the libc does not yet support dynamic linking, the -static parameter
 209    must be added to all clang invocations.
 210