| .. _overlay_mode: |
| |
| ============ |
| Overlay Mode |
| ============ |
| |
| .. contents:: Table of Contents |
| :depth: 4 |
| :local: |
| |
| One can choose to use LLVM's libc in the overlay mode. In this mode, the link |
| order semantics are exploited to pick symbols from ``libllvmlibc.a`` (if they |
| are available in ``libllvmlibc.a``) and the rest are picked from the system |
| libc. The user programs also have to use header files from the system libc. |
| Naturally, only functions which do not depend on implementation specific ABI |
| are included in ``libllvmlibc.a``. Examples of such functions are ``strlen`` |
| and ``round``. Functions like ``fopen`` and friends are not included as they |
| depend on the implementation specific definition of the ``FILE`` data structure. |
| |
| Building the libc in the overlay mode |
| ===================================== |
| |
| There are two different ways in which the libc can be built for use in the |
| overlay mode. In both the ways, we build a static archive named |
| ``libllvmlibc.a``. We use a rather verbose name with a repeated ``lib`` to make |
| it clear that it is not the system libc, which is typically named ``libc.a``. |
| Also, if users choose to mix more than one libc with the system libc, then |
| the name ``libllvmlibc.a`` makes it absolutely clear that it is the static |
| archive of LLVM's libc. |
| |
| Building the static archive with libc as a normal LLVM project |
| -------------------------------------------------------------- |
| |
| We can treat the ``libc`` project as any other normal LLVM project and perform |
| the CMake configure step as follows: |
| |
| .. code-block:: sh |
| |
| $> cd llvm-project # The llvm-project checkout |
| $> mkdir build |
| $> cd build |
| $> cmake ../llvm -G Ninja -DLLVM_ENABLE_PROJECTS="libc" \ |
| -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \ |
| -DCMAKE_BUILD_TYPE=<Debug|Release> \ # Select build type |
| -DCMAKE_INSTALL_PREFIX=<Your prefix of choice> # Optional |
| |
| Next, build the libc: |
| |
| .. code-block:: sh |
| |
| $> ninja libc |
| |
| The build step will build the static archive the in the directory |
| ``build/projects/libc/lib``. Notice that the above CMake configure step also |
| specified an install prefix. This is optional, but if one uses it, then they |
| can follow up the build step with an install step: |
| |
| .. code-block:: sh |
| |
| $> ninja install-llvmlibc |
| |
| Building the static archive as part of the bootstrap build |
| ---------------------------------------------------------- |
| |
| The bootstrap build is a build mode in which runtime components like libc++, |
| libcxx-abi, libc etc. are built using the ToT clang. The idea is that this build |
| produces an in-sync toolchain of compiler + runtime libraries. Such a synchrony |
| is not essential for the libc but can one still build the overlay static archive |
| as part of the bootstrap build if one wants to. The first step is to configure |
| appropriately: |
| |
| .. code-block:: sh |
| |
| $> cmake ../llvm -G Ninja -DLLVM_ENABLE_PROJECTS="clang" \ |
| -DLLVM_ENABLE_RUNTIMES="libc" \ # libc is listed as runtime and not as a project |
| -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \ |
| -DCMAKE_BUILD_TYPE=<Debug|Release> \ # Select build type |
| -DCMAKE_INSTALL_PREFIX=<Your prefix of choice> # Optional |
| |
| The build and install steps are similar to the those used when configured |
| as a normal project. Note that the build step takes much longer this time |
| as ``clang`` will be built before building ``libllvmlibc.a``. |
| |
| .. code-block:: sh |
| |
| $> ninja libc |
| $> ninja install-llvmlibc |
| |
| Using the overlay static archive |
| ================================ |
| |
| Once built (and optionally installed), the overlay static archive can be linked |
| to your binaries like any other static archive. For example, when building with |
| ``clang`` on Linux, one should follow a recipe like: |
| |
| |
| .. code-block:: sh |
| |
| $> clang <other compiler and/or linker options> <file.o|c(pp)> \ |
| -L <path to the directory in which libllvmlibc.a is installed> \ # Optional |
| -lllvmlibc |
| |
| If you installed ``libllvmlibc.a`` in a standard linker lookup path, for example |
| ``/usr/local/lib`` on Linux like systems, then specifying the path to the |
| static archive using the ``-L`` option is not necessary. |
| |
| Linking the static archive to other LLVM binaries |
| ------------------------------------------------- |
| |
| Since the libc and other LLVM binaries are developed in the same source tree, |
| linking ``libllvmlibc.a`` to those LLVM binaries does not require any special |
| install step or explicitly passing any special linker flags/options. One can |
| simply add ``llvmlibc`` as a link library to that binary's target. For example, |
| if you want to link ``libllvmlibc.a`` to ``llvm-objcopy``, all you have to do |
| is to add a CMake command as follows: |
| |
| .. code-block:: cmake |
| |
| target_link_libraries(llvm-objcopy PRIVATE llvmlibc) |
| |
| |