[libc-commits] [libc] 36de85f - [libc] Add document for a recipe to do a full standalone cross-build.
Siva Chandra Reddy via libc-commits
libc-commits at lists.llvm.org
Thu Jan 5 09:37:30 PST 2023
Author: Siva Chandra Reddy
Date: 2023-01-05T09:37:21-08:00
New Revision: 36de85f93f8ec300edc028ec915e6e4a3fa58d6d
URL: https://github.com/llvm/llvm-project/commit/36de85f93f8ec300edc028ec915e6e4a3fa58d6d
DIFF: https://github.com/llvm/llvm-project/commit/36de85f93f8ec300edc028ec915e6e4a3fa58d6d.diff
LOG: [libc] Add document for a recipe to do a full standalone cross-build.
Reviewed By: jeffbailey
Differential Revision: https://reviews.llvm.org/D141037
Added:
libc/docs/full_cross_build.rst
libc/docs/full_host_build.rst
Modified:
libc/docs/fullbuild_mode.rst
libc/docs/index.rst
Removed:
################################################################################
diff --git a/libc/docs/full_cross_build.rst b/libc/docs/full_cross_build.rst
new file mode 100644
index 000000000000..2f95f5b4e8d3
--- /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=<Your 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 <https://clang.llvm.org/docs/CrossCompilation.html#target-triple>`_
+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 000000000000..835c009c5958
--- /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:
+`<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
+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.
+
+.. 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=<Debug|Release> \ # 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=<SYSROOT> # 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 <https://llvm.org/docs/ScudoHardenedAllocator.html>`_ 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 ``<SYSROOT>`` 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
+`<https://github.com/llvm/llvm-project/tree/main/libc/examples>`_ 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 a5c51aa4cb07..0af923de42f8 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: `<https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html>`_)
-which includes not only the components of LLVM's libc, but also full a 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
-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++ <https://libcxx.llvm.org/>`_, 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 <https://llvm.org/docs/ScudoHardenedAllocator.html>`_
-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=<Debug|Release> \ # 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=<SYSROOT> # 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 ``<SYSROOT>`` 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
-`<https://github.com/llvm/llvm-project/tree/main/libc/examples>`_ 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 10e30a363ec9..31bc1e2ce8f3 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
More information about the libc-commits
mailing list