libc/docs/overlay_mode.rst

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