[libc] Add a doc about the libc overlay mode.

Reviewed By: jeffbailey

Differential Revision: https://reviews.llvm.org/D136810

libc/docs/fullbuild_mode.rst

@@ -0,0 +1,7 @@
+.. _fullbuild_mode:
+
+==============
+Fullbuild Mode
+==============
+
+Coming soon, stay tuned!

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:

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=<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)
+
+

libc/docs/runtimes_build.rst

@@ -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.

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.