diff --git a/libc/docs/fullbuild_mode.rst b/libc/docs/fullbuild_mode.rst new file mode 100644 --- /dev/null +++ b/libc/docs/fullbuild_mode.rst @@ -0,0 +1,7 @@ +.. _fullbuild_mode: + +============== +Fullbuild Mode +============== + +Coming soon, stay tuned! diff --git a/libc/docs/index.rst b/libc/docs/index.rst --- a/libc/docs/index.rst +++ b/libc/docs/index.rst @@ -49,7 +49,9 @@ :maxdepth: 1 :caption: Using - runtimes_build + usage_modes + overlay_mode + fullbuild_mode .. toctree:: :hidden: diff --git a/libc/docs/overlay_mode.rst b/libc/docs/overlay_mode.rst new file mode 100644 --- /dev/null +++ b/libc/docs/overlay_mode.rst @@ -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= \ # Select build type + -DCMAKE_INSTALL_PREFIX= # 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= \ # Select build type + -DCMAKE_INSTALL_PREFIX= # 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 \ + -L \ # 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) + + diff --git a/libc/docs/runtimes_build.rst b/libc/docs/runtimes_build.rst deleted file mode 100644 --- a/libc/docs/runtimes_build.rst +++ /dev/null @@ -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. diff --git a/libc/docs/usage_modes.rst b/libc/docs/usage_modes.rst new file mode 100644 --- /dev/null +++ b/libc/docs/usage_modes.rst @@ -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.