87 changes: 79 additions & 8 deletions libc/docs/full_host_build.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,27 +8,97 @@ Full Host Build
:depth: 1
:local:

.. note::
Fullbuild requires running headergen, which is a python program that depends on
pyyaml. The minimum versions are listed on the :ref:`header_generation`
page, as well as additional information.

In this document, we will present a recipe to build the full libc for the host.
When we say *build the libc for the host*, the goal is to build the libc for
the same system on which the libc is being built. Also, we will take this
opportunity to demonstrate how one can set up a *sysroot* (see the documentation
the same system on which the libc is being built. First, we will explain how to
build for developing LLVM-libc, then we will explain how to build LLVM-libc as
part of a complete toolchain.

Configure the build for development
===================================


Below is the list of commands for a simple recipe to build LLVM-libc for
development. In this we've set the Ninja generator, set the build type to
"Debug", and enabled the Scudo allocator. This build also enables generating the
documentation and verbose cmake logging, which are useful development features.

.. note::
if your build fails with an error saying the compiler can't find
``<asm/unistd.h>`` or similar then you're probably missing the symlink from
``/usr/include/asm`` to ``/usr/include/<HOST TRIPLE>/asm``. Installing the
``gcc-multilib`` package creates this symlink, or you can do it manually with
this command:
``sudo ln -s /usr/include/<HOST TRIPLE>/asm /usr/include/asm``
(your host triple will probably be similar to ``x86_64-linux-gnu``)

.. code-block:: sh
$> cd llvm-project # The llvm-project checkout
$> mkdir build
$> cd build
$> cmake ../runtimes \
-G Ninja \
-DCMAKE_C_COMPILER=clang \
-DCMAKE_CXX_COMPILER=clang++ \
-DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \
-DLLVM_LIBC_FULL_BUILD=ON \
-DCMAKE_BUILD_TYPE=Debug \
-DLLVM_LIBC_INCLUDE_SCUDO=ON \
-DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \
-DCOMPILER_RT_BUILD_GWP_ASAN=OFF \
-DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF \
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
-DLLVM_ENABLE_SPHINX=ON -DLIBC_INCLUDE_DOCS=ON \
-DLIBC_CMAKE_VERBOSE_LOGGING=ON
Build and test
==============

After configuring the build with the above ``cmake`` command, one can build test
libc with the following command:

.. code-block:: sh
$> ninja libc libm check-libc
To build the docs run this command:


.. code-block:: sh
$> ninja docs-libc-html
To run a specific test, use the following:

.. code-block:: sh
$> ninja libc.test.src.<HEADER>.<FUNCTION>_test.__unit__
$> ninja libc.test.src.ctype.isalpha_test.__unit__ # EXAMPLE
Configure the complete toolchain build
======================================

For a complete toolchain we recommend creating a *sysroot* (see the documentation
of the ``--sysroot`` option here:
`<https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html>`_) which includes
not only the components of LLVM's libc, but also a full LLVM only toolchain
consisting of the `clang <https://clang.llvm.org/>`_ compiler, the
`lld <https://lld.llvm.org/>`_ linker and the
`compiler-rt <https://compiler-rt.llvm.org/>`_ runtime libraries. LLVM's libc is
not yet complete enough to allow using and linking a C++ application against
`compiler-rt <https://compiler-rt.llvm.org/>`_ runtime libraries. LLVM-libc is
not quite complete enough to allow using and linking a C++ application against
a C++ standard library (like libc++). Hence, we do not include
`libc++ <https://libcxx.llvm.org/>`_ in the sysroot.

.. note:: When the libc is complete enough, we should be able to include
`libc++ <https://libcxx.llvm.org/>`_, libcxx-abi and libunwind in the
LLVM only toolchain and use them to build and link C++ applications.

Configure the full libc build
===============================

Below is the list of commands for a simple recipe to build and install the
libc components along with other components of an LLVM only toolchain. In this
we've set the Ninja generator, enabled a full compiler suite, set the build
Expand All @@ -43,6 +113,7 @@ to use the freshly built lld and compiler-rt.
this command:
``sudo ln -s /usr/include/<TARGET TRIPLE>/asm /usr/include/asm``

.. TODO: Move from projects to runtimes for libc, compiler-rt
.. code-block:: sh
$> cd llvm-project # The llvm-project checkout
Expand All @@ -51,7 +122,7 @@ to use the freshly built lld and compiler-rt.
$> SYSROOT=/path/to/sysroot # Remember to set this!
$> cmake ../llvm \
-G Ninja \
-DLLVM_ENABLE_PROJECTS="clang;libc;lld;compiler-rt" \
-DLLVM_ENABLE_PROJECTS="clang;lld;libc;compiler-rt" \
-DCMAKE_BUILD_TYPE=Debug \
-DCMAKE_C_COMPILER=clang \
-DCMAKE_CXX_COMPILER=clang++ \
Expand Down
5 changes: 5 additions & 0 deletions libc/docs/fullbuild_mode.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@
Fullbuild Mode
==============

.. note::
Fullbuild requires running headergen, which is a python program that depends on
pyyaml. The minimum versions are listed on the :ref:`header_generation`
page, as well as additional information.

The *fullbuild* mode of LLVM's libc is the mode in which it is to be used as
the only libc (as opposed to the :ref:`overlay_mode` in which it is used along
with the system libc.) In order to use it as the only libc, one will have to
Expand Down
6 changes: 5 additions & 1 deletion libc/docs/gpu/building.rst
Original file line number Diff line number Diff line change
Expand Up @@ -63,9 +63,13 @@ targeting the default host environment as well.
Runtimes cross build
--------------------

.. note::
These instructions need to be updated for new headergen. They may be
inaccurate.

For users wanting more direct control over the build process, the build steps
can be done manually instead. This build closely follows the instructions in the
:ref:`main documentation<runtimes_cross_build>` but is specialized for the GPU
:ref:`main documentation<full_cross_build>` but is specialized for the GPU
build. We follow the same steps to first build the libc tools and a suitable
compiler. These tools must all be up-to-date with the libc source.

Expand Down
17 changes: 10 additions & 7 deletions libc/docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,16 @@
The LLVM C Library
==================

.. warning::
The libc is not complete. If you need a fully functioning C library right
now, you should continue to use your standard system libraries.
.. note::
LLVM-libc is not fully complete right now. Some programs may fail to build due
to missing functions (especially C++ ones). If you would like to help us
finish LLVM-libc, check out "Contributing to the libc project" in the sidebar
or ask on discord.

Introduction
============

The libc aspires to a unique place in the software ecosystem. The goals are:
LLVM-libc aspires to a unique place in the software ecosystem. The goals are:

- Fully compliant with current C standards (C17 and upcoming C2x) and POSIX.
- Easily decomposed and embedded: Supplement or replace system C library
Expand All @@ -32,16 +34,17 @@ The libc aspires to a unique place in the software ecosystem. The goals are:
Platform Support
================

Most development is currently targeting x86_64 and aarch64 on Linux. Several
functions in the libc have been tested on Windows. The Fuchsia platform is
Most development is currently targeting Linux on x86_64, aarch64, arm, and
RISC-V. Embedded/baremetal targets are supported on arm and RISC-V, and Windows
and MacOS have limited support (may be broken). The Fuchsia platform is
slowly replacing functions from its bundled libc with functions from this
project.

ABI Compatibility
=================

The libc is written to be ABI independent. Interfaces are generated using
LLVM's tablegen, so supporting arbitrary ABIs is possible. In it's initial
headergen, so supporting arbitrary ABIs is possible. In it's initial
stages there is no ABI stability in any form.

.. toctree::
Expand Down
36 changes: 20 additions & 16 deletions libc/docs/overlay_mode.rst
Original file line number Diff line number Diff line change
Expand Up @@ -28,18 +28,18 @@ 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
--------------------------------------------------------------
Building LLVM-libc as a standalone runtime
------------------------------------------

We can treat the ``libc`` project as any other normal LLVM project and perform
the CMake configure step as follows:
We can treat the ``libc`` project like any other normal LLVM runtime library by
building it with the following cmake command:

.. code-block:: sh
$> cd llvm-project # The llvm-project checkout
$> mkdir build
$> cd build
$> cmake ../llvm -G Ninja -DLLVM_ENABLE_RUNTIMES="libc" \
$> cmake ../runtimes -G Ninja -DLLVM_ENABLE_RUNTIMES="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
Expand All @@ -50,24 +50,29 @@ Next, build the libc:
$> ninja libc
Then, run the tests:

.. code-block:: sh
$> ninja check-libc
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:
specified an install prefix. This is optional, but it's used, then the following
command will install the static archive to the install path:

.. code-block:: sh
$> ninja install-llvmlibc
$> ninja install-libc
Building the static archive as part of the bootstrap build
----------------------------------------------------------

The bootstrap 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 bootstrap build if one wants to. The first step is to configure
appropriately:
produces an in-sync toolchain of compiler + runtime libraries. This ensures that
LLVM-libc has access to the latest clang features, which should provide the best
performance possible.

.. code-block:: sh
Expand All @@ -77,14 +82,13 @@ appropriately:
-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``.
The build and install steps are the same as above, but the build step will take
much longer since ``clang`` will be built before building ``libllvmlibc.a``.

.. code-block:: sh
$> ninja libc
$> ninja install-llvmlibc
$> ninja check-libc
Using the overlay static archive
================================
Expand Down
15 changes: 0 additions & 15 deletions libc/docs/porting.rst
Original file line number Diff line number Diff line change
Expand Up @@ -43,21 +43,6 @@ have their own config directory.
config directory for Fuchsia as the bring up is being done in the Fuchsia
source tree.

The api.td file
---------------

If the :ref:`fullbuild_mode` is to be supported on the new operating system,
then a file named ``api.td`` should be added in its config directory. It is
written in the
`LLVM tablegen language <https://llvm.org/docs/TableGen/ProgRef.html>`_.
It lists all the relevant macros and type definitions we want in the
public libc header files. See the existing Linux
`api.td <https://github.com/llvm/llvm-project/blob/main/libc/config/linux/api.td>`_
file as an example to prepare the ``api.td`` file for the new operating system.

.. note:: In future, LLVM tablegen will be replaced with a different DSL to list
config information.

Architecture Subdirectory
=========================

Expand Down