diff --git a/libc/docs/full_cross_build.rst b/libc/docs/full_cross_build.rst new file mode 100644 index 0000000000000..2f95f5b4e8d31 --- /dev/null +++ b/libc/docs/full_cross_build.rst @@ -0,0 +1,64 @@ +.. _full_cross_build: + +================ +Full Cross Build +================ + +.. contents:: Table of Contents + :depth: 1 + :local: + +In this document, we will present a recipe to cross build a full libc. When we +say *cross build* a full libc, we mean that we will build the libc for a target +system which is not the same as the system on which the libc is being built. +For example, you could be building for a bare metal aarch64 *target* on a Linux +x86_64 *host*. + +Configure the full cross build of the libc +========================================== + +Below is a simple recipe to configure the libc for a cross build. + +.. code-block:: sh + + $> cd llvm-project # The llvm-project checkout + $> mkdir build + $> cd build + $> cmake ../llvm \ + -G Ninja \ # Generator + -DLLVM_ENABLE_PROJECTS=libc \ # Enable the libc project + -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \ + -DLLVM_LIBC_FULL_BUILD=ON \ # We are building the full libc + -DLIBC_TARGET_TRIPLE= + +We will go over the special options passed to the ``cmake`` command above. + +* **Enabled Projects** - Since we want to build the libc project, we list + ``libc`` as the enabled project. +* **The full build option** - Since we want to build the full libc, we pass + ``-DLLVM_LIBC_FULL_BUILD=ON``. +* **The target triple** - This is the target triple of the target for which + we are building the libc. For example, for a Linux 32-bit Arm target, + one can specify it as ``arm-linux-eabi``. + +Build and install +================= + +After configuring the build with the above ``cmake`` command, one can build the +the libc for the target with the following command: + +.. code-block:: sh + + $> ninja libc + +The above ``ninja`` command will build the ``libc.a`` static archive for the +target specified with ``-DLIBC_TARGET_TRIPLE`` to the ``cmake`` command. + +Building for bare metal +======================= + +To build for bare metal, all one has to do is to specify the +`system `_ +component of the target triple as ``none``. For example, to build for a +32-bit arm target on bare metal, one can use a target triple like +``arm-none-eabi``. diff --git a/libc/docs/full_host_build.rst b/libc/docs/full_host_build.rst new file mode 100644 index 0000000000000..835c009c59585 --- /dev/null +++ b/libc/docs/full_host_build.rst @@ -0,0 +1,91 @@ +.. _full_host_build: + +=============== +Full Host Build +=============== + +.. contents:: Table of Contents + :depth: 1 + :local: + +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 +of the ``--sysroot`` option here: +``_) which includes +not only the components of LLVM's libc, but also a full LLVM only toolchain +consisting of the `clang `_ compiler, the +`lld `_ linker and the +`compiler-rt `_ runtime libraries. LLVM's libc is +not yet complete enough to allow using and linking a C++ application against +a C++ standard library (like libc++). Hence, we do not include +`libc++ `_ in the sysroot. + +.. note:: When the libc is complete enough, we should be able to include + `libc++ `_, 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. + +.. code-block:: sh + + $> cd llvm-project # The llvm-project checkout + $> mkdir build + $> cd build + $> cmake ../llvm \ + -G Ninja \ # Generator + -DLLVM_ENABLE_PROJECTS="clang;libc;lld;compiler-rt" \ # Enabled projects + -DCMAKE_BUILD_TYPE= \ # Select build type + -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \ + -DLLVM_LIBC_FULL_BUILD=ON \ # We want the full libc + -DLLVM_LIBC_INCLUDE_SCUDO=ON \ # Include Scudo in the libc + -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \ + -DCOMPILER_RT_BUILD_GWP_ASAN=OFF \ + -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF \ + -DCMAKE_INSTALL_PREFIX= # Specify a sysroot directory + +We will go over some of the special options passed to the ``cmake`` command +above. + +* **Enabled Projects** - Since we want to build and install clang, lld + and compiler-rt along with the libc, we specify + ``clang;libc;lld;compiler-rt`` as the list of enabled projects. +* **The full build option** - Since we want to do build the full libc, we pass + ``-DLLVM_LIBC_FULL_BUILD=ON``. +* **Scudo related options** - LLVM's libc uses + `Scudo `_ as its allocator. + So, when building the full libc, we should specify that we want to include + Scudo in the libc. Since the libc currently only supports static linking, we + also specify that we do not want to build the Scudo shared library. +* **The install prefix** - This is the path to the tool chain install directory. + This is the directory where you intend to set up the sysroot. + +Build and install +================= + +After configuring the build with the above ``cmake`` command, one can build and +install the libc, clang (and its support libraries and builtins), lld and +compiler-rt, with the following command: + +.. code-block:: sh + + $> ninja install-clang install-builtins install-compiler-rt \ + install-core-resource-headers install-libc install-lld + +Once the above command completes successfully, the ```` directory you +have specified with the CMake configure step above will contain a full LLVM-only +toolchain with which you can build practical/real-world C applications. See +``_ for examples +of how to start using this new toolchain. + +Linux Headers +============= + +If you are using the full libc on Linux, then you will also need to install +Linux headers in your sysroot. It is left to the reader to figure out the best +way to install Linux headers on the system they want to use the full libc on. diff --git a/libc/docs/fullbuild_mode.rst b/libc/docs/fullbuild_mode.rst index a5c51aa4cb079..0af923de42f84 100644 --- a/libc/docs/fullbuild_mode.rst +++ b/libc/docs/fullbuild_mode.rst @@ -4,80 +4,16 @@ Fullbuild Mode ============== -.. contents:: Table of Contents - :depth: 4 - :local: - -The *fullbuild* mode of LLVM's libc is the mode in which it is being used as +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.) Hence, to start using it that way, you will have to build -and install the ``libc.a`` static archive from LLVM's libc as well as the -start-up objects and public headers provided by it. In this document, we will -present a way to set up a *sysroot* (see the documentation of the ``--sysroot`` -option here: ``_) -which includes not only the components of LLVM's libc, but also full a LLVM only -toolchain consisting of the `clang `_ compiler, the -`lld `_ linker and the -`compiler-rt `_ runtime libraries. LLVM's libc -is not yet complete enough to allow using and linking a C++ application against -a C++ standard library (like libc++). Hence, we do not include a C++ standard -library in the sysroot. - -.. note:: When the libc is complete enough, we should be able to include - `libc++ `_, libcxx-abi and libunwind in the - toolchain and use them to build and link C++ applications. - -Building the full libc -====================== - -LLVM's libc uses `Scudo `_ -as its allocator. So, when building the full libc, we should specify that we -want Scudo to be included in the libc. Since the libc currently only supports -static linking, we also specify that we do not want a shared library for Scudo. -A typical ``cmake`` configure step will look like this: - -.. code-block:: sh - - $> cd llvm-project # The llvm-project checkout - $> mkdir build - $> cd build - $> cmake ../llvm -G Ninja \ - -DLLVM_ENABLE_PROJECTS="clang;libc;lld;compiler-rt" \ - -DCMAKE_BUILD_TYPE= \ # Select build type - -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \ - -DLLVM_LIBC_FULL_BUILD=ON \ # We want the full libc - -DLLVM_LIBC_INCLUDE_SCUDO=ON \ # Include Scudo in the libc - -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \ - -DCOMPILER_RT_BUILD_GWP_ASAN=OFF \ - -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF \ - -DCMAKE_INSTALL_PREFIX= # Specify a sysroot directory - -Since we want to include ``clang``, ``lld`` and ``compiler-rt`` in our -toolchain, we list them in ``LLVM_ENABLE_PROJECTS`` along with ``libc``. The -option ``CMAKE_INSTALL_PREFIX`` specifies the sysroot directory in which to -install the new toolchain. - -Installation -============ - -To build and install the libc, clang (and its support libraries and builtins), -lld and compiler-rt, run the following command after the above ``cmake`` -command: - -.. code-block:: sh - - $> ninja install-clang install-builtins install-compiler-rt \ - install-core-resource-headers install-libc install-lld +with the system libc.) In to order use it as the only libc, one will have to +build and install not only the static archives like ``libc.a`` from LLVM's libc, +but also the start-up objects like ``crt1.o`` and the public headers. -Once the above command completes successfully, the ```` directory you -have specified with the CMake configure step above will contain a full LLVM-only -toolchain with which you can build practical/real-world C applications. See -``_ for examples -of how to start using this new toolchain. +The full libc build can be of two types: -Linux Headers -============= +.. toctree:: + :maxdepth: 1 -If you are using the full libc on Linux, then you will also need to install -Linux headers in your sysroot. It is left to the reader to figure out the best -way to install Linux headers on the system they want to use the full libc on. + full_host_build + full_cross_build diff --git a/libc/docs/index.rst b/libc/docs/index.rst index 10e30a363ec98..31bc1e2ce8f39 100644 --- a/libc/docs/index.rst +++ b/libc/docs/index.rst @@ -46,7 +46,7 @@ stages there is no ABI stability in any form. .. toctree:: :hidden: - :maxdepth: 1 + :maxdepth: 2 :caption: Using usage_modes