[libc-commits] [libc] 0a94ee6 - [libc] update host build docs (#120147)
via libc-commits
libc-commits at lists.llvm.org
Thu Dec 19 13:13:59 PST 2024
Author: Michael Jones
Date: 2024-12-19T13:13:55-08:00
New Revision: 0a94ee694fbe1a17c5a948fbe86b881527f81343
URL: https://github.com/llvm/llvm-project/commit/0a94ee694fbe1a17c5a948fbe86b881527f81343
DIFF: https://github.com/llvm/llvm-project/commit/0a94ee694fbe1a17c5a948fbe86b881527f81343.diff
LOG: [libc] update host build docs (#120147)
Update the host build docs to better reflect the current recommended
process.
Added:
Modified:
libc/docs/dev/index.rst
libc/docs/full_host_build.rst
Removed:
################################################################################
diff --git a/libc/docs/dev/index.rst b/libc/docs/dev/index.rst
index c16121feb3a45d..9ed50bb6683aae 100644
--- a/libc/docs/dev/index.rst
+++ b/libc/docs/dev/index.rst
@@ -7,6 +7,7 @@ Developer Guides
Navigate to the links below for information on the respective topics:
.. toctree::
+ :maxdepth: 1
code_style
source_tree_layout
diff --git a/libc/docs/full_host_build.rst b/libc/docs/full_host_build.rst
index f687c2fdab213e..e25079141f47b2 100644
--- a/libc/docs/full_host_build.rst
+++ b/libc/docs/full_host_build.rst
@@ -8,7 +8,7 @@ Full Host Build
:depth: 1
:local:
-.. note::
+.. 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.
@@ -99,11 +99,16 @@ a C++ standard library (like libc++). Hence, we do not include
`libc++ <https://libcxx.llvm.org/>`_, libcxx-abi and libunwind in the
LLVM only toolchain and use them to build and link C++ applications.
-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
-type to "Debug", and enabled the Scudo allocator. The build also tells clang
-to use the freshly built lld and compiler-rt.
+Below is the cmake command for a bootstrapping build of LLVM. This will build
+clang and lld with the current system's toolchain, then build compiler-rt and
+LLVM-libc with that freshly built clang. This ensures that LLVM-libc can take
+advantage of the latest clang features and optimizations.
+
+This build also uses Ninja as cmake's generator, and sets lld and compiler-rt as
+the default for the fresh clang. Those settings are recommended, but the build
+should still work without them. The compiler-rt options are required for
+building `Scudo <https://llvm.org/docs/ScudoHardenedAllocator.html>`_ as the
+allocator for LLVM-libc.
.. note::
if your build fails with an error saying the compiler can't find
@@ -113,7 +118,6 @@ 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
@@ -122,8 +126,9 @@ 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;lld;libc;compiler-rt" \
- -DCMAKE_BUILD_TYPE=Debug \
+ -DLLVM_ENABLE_PROJECTS="clang;lld" \
+ -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \
+ -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_C_COMPILER=clang \
-DCMAKE_CXX_COMPILER=clang++ \
-DLLVM_LIBC_FULL_BUILD=ON \
@@ -133,25 +138,8 @@ to use the freshly built lld and compiler-rt.
-DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF \
-DCLANG_DEFAULT_LINKER=lld \
-DCLANG_DEFAULT_RTLIB=compiler-rt \
- -DDEFAULT_SYSROOT=$SYSROOT \
-DCMAKE_INSTALL_PREFIX=$SYSROOT
-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.
-* **Default sysroot and 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
=================
@@ -164,14 +152,19 @@ Build and install
you may need to delete them from ``/usr/local/include``.
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:
+install the toolchain with
.. code-block:: sh
$> ninja install-clang install-builtins install-compiler-rt \
install-core-resource-headers install-libc install-lld
+or
+
+.. code-block:: sh
+
+ $> ninja install
+
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
@@ -190,9 +183,9 @@ These instructions should work on a Debian-based x86_64 system:
$> apt download linux-libc-dev
$> dpkg -x linux-libc-dev*deb .
- $> mv usr/include/* /path/to/sysroot/include
- $> rm -rf usr linux-libc-dev*deb
- $> ln -s x86_64-linux-gnu/asm ~/Programming/sysroot/include/asm
+ $> cp -r usr/* /path/to/sysroot/
+ $> rm -r usr linux-libc-dev*deb
+ $> ln -s /path/to/sysroot/include/x86_64-linux-gnu/asm /path/to/sysroot/include/asm
Using your newly built libc
===========================
@@ -208,3 +201,20 @@ invocation:
Because the libc does not yet support dynamic linking, the -static parameter
must be added to all clang invocations.
+
+You can make sure you're using the newly built toolchain by trying out features
+that aren't yet supported by the system toolchain, such as fixed point. The
+following is an example program that demonstrates the
diff erence:
+
+.. code-block:: C
+
+ // $ $SYSROOT/bin/clang example.c -static -ffixed-point --sysroot=$SYSROOT
+
+ #include <stdio.h>
+ int main() {
+ printf("Hello, World!\n%.9f\n%.9lK\n",
+ 4294967295.000000001,
+ 4294967295.000000001ulK);
+ return 0;
+ }
+
More information about the libc-commits
mailing list