[libc-commits] [libc] 89ba240 - [libc] Add a doc about the libc overlay mode.
Siva Chandra Reddy via libc-commits
libc-commits at lists.llvm.org
Wed Oct 26 21:53:55 PDT 2022
Author: Siva Chandra Reddy
Date: 2022-10-26T21:53:29-07:00
New Revision: 89ba240f4b65f8e8e0876c7d066cebf85d1163b5
URL: https://github.com/llvm/llvm-project/commit/89ba240f4b65f8e8e0876c7d066cebf85d1163b5
DIFF: https://github.com/llvm/llvm-project/commit/89ba240f4b65f8e8e0876c7d066cebf85d1163b5.diff
LOG: [libc] Add a doc about the libc overlay mode.
Reviewed By: jeffbailey
Differential Revision: https://reviews.llvm.org/D136810
Added:
libc/docs/fullbuild_mode.rst
libc/docs/overlay_mode.rst
libc/docs/usage_modes.rst
Modified:
libc/docs/index.rst
Removed:
libc/docs/runtimes_build.rst
################################################################################
diff --git a/libc/docs/fullbuild_mode.rst b/libc/docs/fullbuild_mode.rst
new file mode 100644
index 0000000000000..635dc8b66417f
--- /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
index 0031c81a1df51..35dff05a56d06 100644
--- a/libc/docs/index.rst
+++ b/libc/docs/index.rst
@@ -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:
diff --git a/libc/docs/overlay_mode.rst b/libc/docs/overlay_mode.rst
new file mode 100644
index 0000000000000..4c5eaf939487c
--- /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
diff erent 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)
+
+
diff --git a/libc/docs/runtimes_build.rst b/libc/docs/runtimes_build.rst
deleted file mode 100644
index 06f674b8b5db0..0000000000000
--- 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
diff erent 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
index 0000000000000..11c10623b61db
--- /dev/null
+++ b/libc/docs/usage_modes.rst
@@ -0,0 +1,11 @@
+===========
+Usage Modes
+===========
+
+The libc can used in two
diff erent 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.
More information about the libc-commits
mailing list