[libc] Add a doc about the libc overlay mode.
Reviewed By: jeffbailey Differential Revision: https://reviews.llvm.org/D136810
This commit is contained in:
Siva Chandra Reddy
parent
4f06d46f46
commit
89ba240f4b
|
|
@ -0,0 +1,7 @@
|
|||
.. _fullbuild_mode:
|
||||
|
||||
==============
|
||||
Fullbuild Mode
|
||||
==============
|
||||
|
||||
Coming soon, stay tuned!
|
||||
|
|
@ -49,7 +49,9 @@ stages there is no ABI stability in any form.
|
|||
:maxdepth: 1
|
||||
:caption: Using
|
||||
|
||||
runtimes_build
|
||||
usage_modes
|
||||
overlay_mode
|
||||
fullbuild_mode
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
|
|
|||
|
|
@ -0,0 +1,121 @@
|
|||
.. _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 llvmlibc
|
||||
|
||||
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 runtimes build
|
||||
---------------------------------------------------------
|
||||
|
||||
The runtimes 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 runtimes 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 llvmlibc
|
||||
$> 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 explicity 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)
|
||||
|
||||
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
Building libc using the runtimes build setup
|
||||
============================================
|
||||
|
||||
The runtimes build of the LLVM toolchain first builds clang and then builds the
|
||||
various runtimes (like ``libc++`` and ``compiler-rt``) and LLVM binutils (like
|
||||
``llvm-objcopy`` and ``llvm-readelf``) using the freshly built clang. One can
|
||||
build libc also as in the same manner. As of this writing, only the ABI agnostic
|
||||
parts of the libc are included when built in that manner. This allows interested
|
||||
users to continue using their system libc's headers while linking to LLVM libc's
|
||||
implementations when they are available. To build libc using the runtimes build
|
||||
setup, one needs to include the ``libc`` project in the list of the enabled
|
||||
runtimes when configuring the build:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$> cmake ../llvm -GNinja -DLLVM_ENABLE_PROJECTS="llvm;clang" \
|
||||
-DLLVM_ENABLE_RUNTIMES=libc
|
||||
|
||||
Note that Ninja is used as the generator in the above CMake command. Hence, to
|
||||
actually build the libc, one has to build the Ninja target named ``llvmlibc``:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$> ninja llvmlibc
|
||||
|
||||
If a different generator is used, then the build command should be suitably
|
||||
adapted to build the target ``llvmlibc``. Building that target will produce a
|
||||
static archive which includes all ABI agnostic functions available in LLVM libc.
|
||||
|
||||
Future direction
|
||||
----------------
|
||||
|
||||
We plan to enhance the runtimes build of LLVM libc to include ABI sensitive
|
||||
parts and to also generate the public headers. Likewise, we would like to
|
||||
provide an option to build other runtimes like ``libc++`` and ``compiler-rt``
|
||||
against LLVM libc.
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
===========
|
||||
Usage Modes
|
||||
===========
|
||||
|
||||
The libc can used in two different modes:
|
||||
|
||||
#. The **overlay** mode: In this mode, the link order semantics are exploited
|
||||
to overlay implementations from LLVM's libc over the system libc. See
|
||||
:ref:`overlay_mode` for more information about this mode.
|
||||
#. The **fullbuild** mode: In this mode, LLVM's libc is used as the only libc
|
||||
for the binary. See :ref:`fullbuild_mode` for information about this mode.
|
||||
Loading…
Reference in New Issue