diff --git a/libc/docs/full_cross_build.rst b/libc/docs/full_cross_build.rst --- a/libc/docs/full_cross_build.rst +++ b/libc/docs/full_cross_build.rst @@ -8,17 +8,44 @@ :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*. +In this document, we will present recipes to cross build the full libc. When we +say *cross build* a full libc, we mean that we will build the full 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 -========================================== +There are three main recipes to cross build the full libc. Each one serves a +different use case. Below is a short description of these recipes to help users +pick the recipe that best suites their needs and contexts. -Below is a simple recipe to configure the libc for a cross build. In this, -we've set Ninja as the generator, and are building the full libc. +* **Standalone cross build** - Using this recipe, one can build the libc, and + only the libc for the target of their choice. The users can use the compiler + of their choice to build the libc. +* **Runtimes cross build** - In this recipe, one will have to first build the + libc build tools for the host separately and then use those build tools to + build the libc. The users can use the compiler of their choice to build the + libc build tools as well as the libc. +* **Bootstrap cross build** - In this recipe, one will build the ``clang`` + compiler and the libc build tools for the host first, and then use them to + build the libc for the target. Unlike with the runtimes build recipe, the + user does not have explicitly build ``clang`` and other libc build tools. + They get built automatically before building the libc. + +The following sections present the three recipes in detail. + +Standalone cross build +====================== + +In the *standalone crossbuild* recipe, the compiler of user's choice is used to +build the libc. The necessary build tools for the host are built first, and +those build tools are then used to build the libc for the target. Both these +steps happen automatically, as in, the user does not have to explicitly build +the builds first and then build the libc. + +CMake configure step +-------------------- + +Below is the CMake command to configure the standalone crossbuild of the libc. .. code-block:: sh @@ -28,10 +55,11 @@ $> cmake ../llvm \ -G Ninja \ -DLLVM_ENABLE_PROJECTS=libc \ - -DCMAKE_C_COMPILER=clang \ - -DCMAKE_CXX_COMPILER=clang++ \ + -DCMAKE_C_COMPILER= \ # For example, clang or gcc + -DCMAKE_CXX_COMPILER= \ # For example, clang++ or g++ -DLLVM_LIBC_FULL_BUILD=ON \ - -DLIBC_TARGET_TRIPLE= + -DLIBC_TARGET_TRIPLE= \ + -DCMAKE_BUILD_TYPE= We will go over the special options passed to the ``cmake`` command above. @@ -43,18 +71,134 @@ 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 -================= +Build step +---------- 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 + $> ninja libc libm + +The above ``ninja`` command will build the libc static archives ``libc.a`` and +``libm.a`` for the target specified with ``-DLIBC_TARGET_TRIPLE`` in the CMake +configure step. + +Runtimes cross build +==================== + +The *runtimes cross build* is very similar to the standalone crossbuild but the +user will have to first build the libc build tools separately. At the time of +this writing, there is only one libc build tool that has to be built separately. +It is done as follows: + +.. code-block:: sh + + $> cd llvm-project # The llvm-project checkout + $> mkdir build-libc-tools # A different build directory for the build tools + $> cd build-libc-tools + $> cmake ../llvm \ + -G Ninja \ + -DLLVM_ENABLE_PROJECTS=libc \ + -DCMAKE_C_COMPILER= \ # For example, clang or gcc + -DCMAKE_CXX_COMPILER= \ # For example, clang++ or g++ + -DLLVM_LIBC_FULL_BUILD=ON \ + -DCMAKE_BUILD_TYPE= + $> ninja libc-hdrgen + +The above commands should build a binary named ``libc-hdrgen``. Copy this binary +to a directory of your choice. + +CMake configure step +-------------------- + +After copying the ``libc-hdrgen`` binary to say ``/path/to/libc-hdrgen``, +configure the libc build using the following command: + +.. code-block:: sh + + $> cd llvm-project # The llvm-project checkout + $> mkdir build + $> cd build + $> cmake ../runtimes \ + -G Ninja \ + -DLLVM_ENABLE_RUNTIMES=libc \ + -DCMAKE_C_COMPILER= \ # For example, clang or gcc + -DCMAKE_CXX_COMPILER= \ # For example, clang++ or g++ + -DLLVM_LIBC_FULL_BUILD=ON \ + -DLIBC_HDRGEN_EXE=/path/to/libc-hdrgen \ + -DLIBC_TARGET_TRIPLE= \ + -DCMAKE_BUILD_TYPE= + +Note the differences in the above cmake command versus the one used in the +CMake configure step of the standalone build recipe: + +* Instead of listing ``libc`` in ``LLVM_ENABLED_PROJECTS``, we list it in + ``LLVM_ENABLED_RUNTIMES``. +* Instead of using ``llvm-project/llvm`` as the root CMake source directory, + we use ``llvm-project/runtimes`` as the root CMake source directory. +* The path to the ``libc-hdrgen`` binary built earlier is specified with + ``-DLIBC_HDRGEN_EXE=/path/to/libc-hdrgen``. + +Build step +---------- + +The build step in the runtimes build recipe is exactly the same as that of +the standalone build recipe: + +.. code-block:: sh + + $> ninja libc libm + +As with the standalone build recipe, the above ninja command will build the +libc static archives for the target specified with ``-DLIBC_TARGET_TRIPLE`` in +the CMake configure step. + + +Bootstrap cross build +===================== + +In this recipe, the clang compiler and the ``libc-hdrgen`` binary, both are +built automatically before building the libc for the target. + +CMake configure step +-------------------- + +.. code-block:: sh + + $> cd llvm-project # The llvm-project checkout + $> mkdir build + $> cd build + $> cmake ../llvm \ + -G Ninja \ + -DCMAKE_C_COMPILER= \ + -DCMAKE_CXX_COMPILER= \ + -DLLVM_ENABLE_PROJECTS=clang \ + -DLLVM_ENABLE_RUNTIMES=libc \ + -DLLVM_LIBC_FULL_BUILD=ON \ + -DLLVM_RUNTIME_TARGETS= \ + -DCMAKE_BUILD_TYPE=Debug + +Note how the above cmake command differs from the one used in the other two +recipes: + +* ``clang`` is listed in ``-DLLVM_ENABLE_PROJECTS`` and ``libc`` is + listed in ``-DLLVM_ENABLE_RUNTIMES``. +* The CMake root source directory is ``llvm-project/llvm``. +* The target triple is specified with ``-DLLVM_RUNTIMES_TARGET``. + +Build step +---------- + +The build step is similar to the other two recipes: + +.. 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. +The above ninja command should build the libc static archives for the target +speficied with ``-DLLVM_RUNTIMES_TARGET``. Building for bare metal ======================= @@ -63,4 +207,5 @@ `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``. +``arm-none-eabi``. Other than that, the libc for a bare metal target can be +built using any of the three recipes described above.