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,6 +49,9 @@ :maxdepth: 1 :caption: Using + usage_modes + overlay_mode + fullbuild_mode runtimes_build .. toctree:: 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/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.