intel/llvm
1
0
Fork 0
mirror of https://github.com/intel/llvm.git synced 2026-01-18 07:57:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

[libc] Add document for a recipe to do a full standalone cross-build.

Browse Source 
Reviewed By: jeffbailey

Differential Revision: https://reviews.llvm.org/D141037
This commit is contained in:
Siva Chandra Reddy
2023-01-05 01:09:28 -08:00
parent 9bde3d0cc5
commit 36de85f93f
4 changed files with 165 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
libc/docs/full_cross_build.rst Normal file
View File

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

91
libc/docs/full_host_build.rst Normal file
View File

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

82
libc/docs/fullbuild_mode.rst
View File

@@ -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.
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.
.. 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.
The full libc build can be of two types:
Building the full libc
======================
.. toctree::
:maxdepth: 1
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
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.
full_host_build
full_cross_build

2
libc/docs/index.rst
View File

@@ -46,7 +46,7 @@ stages there is no ABI stability in any form.
.. toctree::
:hidden:
:maxdepth: 1
:maxdepth: 2
:caption: Using
usage_modes