1.. _overlay_mode: 2 3============ 4Overlay Mode 5============ 6 7.. contents:: Table of Contents 8 :depth: 4 9 :local: 10 11One can choose to use LLVM's libc in the overlay mode. In this mode, the link 12order semantics are exploited to pick symbols from ``libllvmlibc.a`` (if they 13are available in ``libllvmlibc.a``) and the rest are picked from the system 14libc. The user programs also have to use header files from the system libc. 15Naturally, only functions which do not depend on implementation specific ABI 16are included in ``libllvmlibc.a``. Examples of such functions are ``strlen`` 17and ``round``. Functions like ``fopen`` and friends are not included as they 18depend on the implementation specific definition of the ``FILE`` data structure. 19 20Building the libc in the overlay mode 21===================================== 22 23There are two different ways in which the libc can be built for use in the 24overlay mode. In both the ways, we build a static archive named 25``libllvmlibc.a``. We use a rather verbose name with a repeated ``lib`` to make 26it clear that it is not the system libc, which is typically named ``libc.a``. 27Also, if users choose to mix more than one libc with the system libc, then 28the name ``libllvmlibc.a`` makes it absolutely clear that it is the static 29archive of LLVM's libc. 30 31Building LLVM-libc as a standalone runtime 32------------------------------------------ 33 34We can treat the ``libc`` project like any other normal LLVM runtime library by 35building it with the following cmake command: 36 37.. code-block:: sh 38 39 $> cd llvm-project # The llvm-project checkout 40 $> mkdir build 41 $> cd build 42 $> cmake ../runtimes -G Ninja -DLLVM_ENABLE_RUNTIMES="libc" \ 43 -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \ 44 -DCMAKE_BUILD_TYPE=<Debug|Release> \ # Select build type 45 -DCMAKE_INSTALL_PREFIX=<Your prefix of choice> # Optional 46 47Next, build the libc: 48 49.. code-block:: sh 50 51 $> ninja libc 52 53Then, run the tests: 54 55.. code-block:: sh 56 57 $> ninja check-libc 58 59The build step will build the static archive the in the directory 60``build/projects/libc/lib``. Notice that the above CMake configure step also 61specified an install prefix. This is optional, but it's used, then the following 62command will install the static archive to the install path: 63 64.. code-block:: sh 65 66 $> ninja install-libc 67 68Building the static archive as part of the bootstrap build 69---------------------------------------------------------- 70 71The bootstrap build is a build mode in which runtime components like libc++, 72libcxx-abi, libc etc. are built using the ToT clang. The idea is that this build 73produces an in-sync toolchain of compiler + runtime libraries. This ensures that 74LLVM-libc has access to the latest clang features, which should provide the best 75performance possible. 76 77.. code-block:: sh 78 79 $> cmake ../llvm -G Ninja -DLLVM_ENABLE_PROJECTS="clang" \ 80 -DLLVM_ENABLE_RUNTIMES="libc" \ # libc is listed as runtime and not as a project 81 -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \ 82 -DCMAKE_BUILD_TYPE=<Debug|Release> \ # Select build type 83 -DCMAKE_INSTALL_PREFIX=<Your prefix of choice> # Optional 84 85The build and install steps are the same as above, but the build step will take 86much longer since ``clang`` will be built before building ``libllvmlibc.a``. 87 88.. code-block:: sh 89 90 $> ninja libc 91 $> ninja check-libc 92 93Using the overlay static archive 94================================ 95 96Once built (and optionally installed), the overlay static archive can be linked 97to your binaries like any other static archive. For example, when building with 98``clang`` on Linux, one should follow a recipe like: 99 100 101.. code-block:: sh 102 103 $> clang <other compiler and/or linker options> <file.o|c(pp)> \ 104 -L <path to the directory in which libllvmlibc.a is installed> \ # Optional 105 -lllvmlibc 106 107If you installed ``libllvmlibc.a`` in a standard linker lookup path, for example 108``/usr/local/lib`` on Linux like systems, then specifying the path to the 109static archive using the ``-L`` option is not necessary. 110 111Linking the static archive to other LLVM binaries 112------------------------------------------------- 113 114Since the libc and other LLVM binaries are developed in the same source tree, 115linking ``libllvmlibc.a`` to those LLVM binaries does not require any special 116install step or explicitly passing any special linker flags/options. One can 117simply add ``llvmlibc`` as a link library to that binary's target. For example, 118if you want to link ``libllvmlibc.a`` to ``llvm-objcopy``, all you have to do 119is to add a CMake command as follows: 120 121.. code-block:: cmake 122 123 target_link_libraries(llvm-objcopy PRIVATE llvmlibc) 124 125 126