219 lines · plain
1.. _full_host_build:2 3===============4Full Host Build5===============6 7.. contents:: Table of Contents8 :depth: 19 :local:10 11.. note::12 Fullbuild requires running headergen, which is a python program that depends on13 pyyaml. The minimum versions are listed on the :ref:`header_generation`14 page, as well as additional information.15 16In this document, we will present a recipe to build the full libc for the host.17When we say *build the libc for the host*, the goal is to build the libc for18the same system on which the libc is being built. First, we will explain how to19build for developing LLVM-libc, then we will explain how to build LLVM-libc as20part of a complete toolchain.21 22Configure the build for development23===================================24 25 26Below is the list of commands for a simple recipe to build LLVM-libc for27development. In this we've set the Ninja generator, set the build type to28"Debug", and enabled the Scudo allocator. This build also enables generating the29documentation 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 find33 ``<asm/unistd.h>`` or similar then you're probably missing the symlink from34 ``/usr/include/asm`` to ``/usr/include/<HOST TRIPLE>/asm``. Installing the35 ``gcc-multilib`` package creates this symlink, or you can do it manually with36 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:: sh41 42 $> cd llvm-project # The llvm-project checkout43 $> mkdir build44 $> cd build45 $> 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=ON59 60Build and test61==============62 63After configuring the build with the above ``cmake`` command, one can build test64libc with the following command:65 66.. code-block:: sh67 68 $> ninja libc libm check-libc69 70To build the docs run this command:71 72 73.. code-block:: sh74 75 $> ninja docs-libc-html76 77To run a specific test, use the following:78 79.. code-block:: sh80 81 $> ninja libc.test.src.<HEADER>.<FUNCTION>_test.__unit__82 $> ninja libc.test.src.ctype.isalpha_test.__unit__ # EXAMPLE83 84Configure the complete toolchain build85======================================86 87For a complete toolchain we recommend creating a *sysroot* (see the documentation88of the ``--sysroot`` option here:89`<https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html>`_) which includes90not only the components of LLVM's libc, but also a full LLVM only toolchain91consisting of the `clang <https://clang.llvm.org/>`_ compiler, the92`lld <https://lld.llvm.org/>`_ linker and the93`compiler-rt <https://compiler-rt.llvm.org/>`_ runtime libraries. LLVM-libc is94not quite complete enough to allow using and linking a C++ application against95a C++ standard library (like libc++). Hence, we do not include96`libc++ <https://libcxx.llvm.org/>`_ in the sysroot.97 98.. note:: When the libc is complete enough, we should be able to include99 `libc++ <https://libcxx.llvm.org/>`_, libcxx-abi and libunwind in the100 LLVM only toolchain and use them to build and link C++ applications.101 102Below is the cmake command for a bootstrapping build of LLVM. This will build103clang and lld with the current system's toolchain, then build compiler-rt and104LLVM-libc with that freshly built clang. This ensures that LLVM-libc can take105advantage of the latest clang features and optimizations.106 107This build also uses Ninja as cmake's generator, and sets lld and compiler-rt as108the default for the fresh clang. Those settings are recommended, but the build109should still work without them. The compiler-rt options are required for110building `Scudo <https://llvm.org/docs/ScudoHardenedAllocator.html>`_ as the111allocator for LLVM-libc.112 113.. note::114 if your build fails with an error saying the compiler can't find115 ``<asm/unistd.h>`` or similar then you're probably missing the symlink from116 ``/usr/include/asm`` to ``/usr/include/<TARGET TRIPLE>/asm``. Installing the117 ``gcc-multilib`` package creates this symlink, or you can do it manually with118 this command:119 ``sudo ln -s /usr/include/<TARGET TRIPLE>/asm /usr/include/asm``120 121.. code-block:: sh122 123 $> cd llvm-project # The llvm-project checkout124 $> mkdir build125 $> cd build126 $> SYSROOT=/path/to/sysroot # Remember to set this!127 $> cmake ../llvm \128 -G Ninja \129 -DLLVM_ENABLE_PROJECTS="clang;lld" \130 -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \131 -DCMAKE_BUILD_TYPE=Release \132 -DCMAKE_C_COMPILER=clang \133 -DCMAKE_CXX_COMPILER=clang++ \134 -DLLVM_LIBC_FULL_BUILD=ON \135 -DLLVM_LIBC_INCLUDE_SCUDO=ON \136 -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \137 -DCOMPILER_RT_BUILD_GWP_ASAN=OFF \138 -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF \139 -DCLANG_DEFAULT_LINKER=lld \140 -DCLANG_DEFAULT_RTLIB=compiler-rt \141 -DCMAKE_INSTALL_PREFIX=$SYSROOT142 143Build and install144=================145 146.. TODO: add this warning to the cmake147.. warning::148 Running these install commands without setting a ``$SYSROOT`` will install149 them into your system include path, which may break your system. If you're150 just trying to develop libc, then just run ``ninja check-libc`` to build the151 libc and run the tests. If you've already accidentally installed the headers,152 you may need to delete them from ``/usr/local/include``.153 154After configuring the build with the above ``cmake`` command, one can build and155install the toolchain with156 157.. code-block:: sh158 159 $> ninja install-clang install-builtins install-compiler-rt \160 install-core-resource-headers install-libc install-lld161 162or163 164.. code-block:: sh165 166 $> ninja install167 168Once the above command completes successfully, the ``$SYSROOT`` directory you169have specified with the CMake configure step above will contain a full LLVM-only170toolchain with which you can build practical/real-world C applications. See171`<https://github.com/llvm/llvm-project/tree/main/libc/examples>`_ for examples172of how to start using this new toolchain.173 174Linux Headers175=============176 177If you are using the full libc on Linux, then you will also need to install178Linux headers in your sysroot. Let's build them from source.179 180.. code-block:: sh181 182 $> git clone --depth=1 git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git /tmp/linux183 $> make LLVM=1 INSTALL_HDR_PATH=/path/to/sysroot -C /tmp/linux headers_install184 185The headers can be built to target non-host architectures by adding the186``ARCH={arm|arm64|i386}`` to the above invocation of ``make``.187 188Using your newly built libc189===========================190 191You can now use your newly built libc nearly like you would use any compiler192invocation:193 194.. code-block:: sh195 196 $> /path/to/sysroot/bin/clang -static main.c197 198.. warning::199 Because the libc does not yet support dynamic linking, the -static parameter200 must be added to all clang invocations.201 202 203You can make sure you're using the newly built toolchain by trying out features204that aren't yet supported by the system toolchain, such as fixed point. The205following is an example program that demonstrates the difference:206 207.. code-block:: C208 209 // $ $SYSROOT/bin/clang example.c -static -ffixed-point --sysroot=$SYSROOT210 211 #include <stdio.h>212 int main() {213 printf("Hello, World!\n%.9f\n%.9lK\n",214 4294967295.000000001,215 4294967295.000000001ulK);216 return 0;217 }218 219