|
252
|
1 .. _full_cross_build:
|
|
|
2
|
|
|
3 ================
|
|
|
4 Full Cross Build
|
|
|
5 ================
|
|
|
6
|
|
|
7 .. contents:: Table of Contents
|
|
|
8 :depth: 1
|
|
|
9 :local:
|
|
|
10
|
|
|
11 In this document, we will present recipes to cross build the full libc. When we
|
|
|
12 say *cross build* a full libc, we mean that we will build the full libc for a
|
|
|
13 target system which is not the same as the system on which the libc is being
|
|
|
14 built. For example, you could be building for a bare metal aarch64 *target* on a
|
|
|
15 Linux x86_64 *host*.
|
|
|
16
|
|
|
17 There are three main recipes to cross build the full libc. Each one serves a
|
|
|
18 different use case. Below is a short description of these recipes to help users
|
|
|
19 pick the recipe that best suites their needs and contexts.
|
|
|
20
|
|
|
21 * **Standalone cross build** - Using this recipe one can build the libc using a
|
|
|
22 compiler of their choice. One should use this recipe if their compiler can
|
|
|
23 build for the host as well as the target.
|
|
|
24 * **Runtimes cross build** - In this recipe, one will have to first build the
|
|
|
25 libc build tools for the host separately and then use those build tools to
|
|
|
26 build the libc. Users can use the compiler of their choice to build the
|
|
|
27 libc build tools as well as the libc. One should use this recipe if they
|
|
|
28 have to use a host compiler to build the build tools for the host and then
|
|
|
29 use a target compiler (which is different from the host compiler) to build
|
|
|
30 the libc.
|
|
|
31 * **Bootstrap cross build** - In this recipe, one will build the ``clang``
|
|
|
32 compiler and the libc build tools for the host first, and then use them to
|
|
|
33 build the libc for the target. Unlike with the runtimes build recipe, the
|
|
|
34 user does not have explicitly build ``clang`` and other libc build tools.
|
|
|
35 They get built automatically before building the libc. One should use this
|
|
|
36 recipe if they intend use the built ``clang`` and the libc as part of their
|
|
|
37 toolchain for the target.
|
|
|
38
|
|
|
39 The following sections present the three recipes in detail.
|
|
|
40
|
|
|
41 Standalone cross build
|
|
|
42 ======================
|
|
|
43
|
|
|
44 In the *standalone crossbuild* recipe, the system compiler or a custom compiler
|
|
|
45 of user's choice is used to build the libc. The necessary build tools for the
|
|
|
46 host are built first, and those build tools are then used to build the libc for
|
|
|
47 the target. Both these steps happen automatically, as in, the user does not have
|
|
|
48 to explicitly build the build tools first and then build the libc. A point to
|
|
|
49 keep in mind is that the compiler used should be capable of building for the
|
|
|
50 host as well as the target.
|
|
|
51
|
|
|
52 CMake configure step
|
|
|
53 --------------------
|
|
|
54
|
|
|
55 Below is the CMake command to configure the standalone crossbuild of the libc.
|
|
|
56
|
|
|
57 .. code-block:: sh
|
|
|
58
|
|
|
59 $> cd llvm-project # The llvm-project checkout
|
|
|
60 $> mkdir build
|
|
|
61 $> cd build
|
|
|
62 $> C_COMPILER=<C compiler> # For example "clang"
|
|
|
63 $> CXX_COMPILER=<C++ compiler> # For example "clang++"
|
|
|
64 $> cmake ../llvm \
|
|
|
65 -G Ninja \
|
|
|
66 -DLLVM_ENABLE_PROJECTS=libc \
|
|
|
67 -DCMAKE_C_COMPILER=$C_COMPILER \
|
|
|
68 -DCMAKE_CXX_COMPILER=$CXX_COMPILER \
|
|
|
69 -DLLVM_LIBC_FULL_BUILD=ON \
|
|
|
70 -DLIBC_TARGET_TRIPLE=<Your target triple> \
|
|
|
71 -DCMAKE_BUILD_TYPE=<Release|Debug>
|
|
|
72
|
|
|
73 We will go over the special options passed to the ``cmake`` command above.
|
|
|
74
|
|
|
75 * **Enabled Projects** - Since we want to build the libc project, we list
|
|
|
76 ``libc`` as the enabled project.
|
|
|
77 * **The full build option** - Since we want to build the full libc, we pass
|
|
|
78 ``-DLLVM_LIBC_FULL_BUILD=ON``.
|
|
|
79 * **The target triple** - This is the target triple of the target for which
|
|
|
80 we are building the libc. For example, for a Linux 32-bit Arm target,
|
|
|
81 one can specify it as ``arm-linux-eabi``.
|
|
|
82
|
|
|
83 Build step
|
|
|
84 ----------
|
|
|
85
|
|
|
86 After configuring the build with the above ``cmake`` command, one can build the
|
|
|
87 the libc for the target with the following command:
|
|
|
88
|
|
|
89 .. code-block:: sh
|
|
|
90
|
|
|
91 $> ninja libc libm
|
|
|
92
|
|
|
93 The above ``ninja`` command will build the libc static archives ``libc.a`` and
|
|
|
94 ``libm.a`` for the target specified with ``-DLIBC_TARGET_TRIPLE`` in the CMake
|
|
|
95 configure step.
|
|
|
96
|
|
|
97 Runtimes cross build
|
|
|
98 ====================
|
|
|
99
|
|
|
100 The *runtimes cross build* is very similar to the standalone crossbuild but the
|
|
|
101 user will have to first build the libc build tools for the host separately. One
|
|
|
102 should use this recipe if they want to use a different host and target compiler.
|
|
|
103 Note that the libc build tools MUST be in sync with the libc. That is, the
|
|
|
104 libc build tools and the libc, both should be built from the same source
|
|
|
105 revision. At the time of this writing, there is only one libc build tool that
|
|
|
106 has to be built separately. It is done as follows:
|
|
|
107
|
|
|
108 .. code-block:: sh
|
|
|
109
|
|
|
110 $> cd llvm-project # The llvm-project checkout
|
|
|
111 $> mkdir build-libc-tools # A different build directory for the build tools
|
|
|
112 $> cd build-libc-tools
|
|
|
113 $> HOST_C_COMPILER=<C compiler for the host> # For example "clang"
|
|
|
114 $> HOST_CXX_COMPILER=<C++ compiler for the host> # For example "clang++"
|
|
|
115 $> cmake ../llvm \
|
|
|
116 -G Ninja \
|
|
|
117 -DLLVM_ENABLE_PROJECTS=libc \
|
|
|
118 -DCMAKE_C_COMPILER=$HOST_C_COMPILER \
|
|
|
119 -DCMAKE_CXX_COMPILER=$HOST_CXX_COMPILER \
|
|
|
120 -DLLVM_LIBC_FULL_BUILD=ON \
|
|
|
121 -DCMAKE_BUILD_TYPE=Debug # User can choose to use "Release" build type
|
|
|
122 $> ninja libc-hdrgen
|
|
|
123
|
|
|
124 The above commands should build a binary named ``libc-hdrgen``. Copy this binary
|
|
|
125 to a directory of your choice.
|
|
|
126
|
|
|
127 CMake configure step
|
|
|
128 --------------------
|
|
|
129
|
|
|
130 After copying the ``libc-hdrgen`` binary to say ``/path/to/libc-hdrgen``,
|
|
|
131 configure the libc build using the following command:
|
|
|
132
|
|
|
133 .. code-block:: sh
|
|
|
134
|
|
|
135 $> cd llvm-project # The llvm-project checkout
|
|
|
136 $> mkdir build
|
|
|
137 $> cd build
|
|
|
138 $> TARGET_C_COMPILER=<C compiler for the target>
|
|
|
139 $> TARGET_CXX_COMPILER=<C++ compiler for the target>
|
|
|
140 $> HDRGEN=</path/to/libc-hdrgen>
|
|
|
141 $> TARGET_TRIPLE=<Your target triple>
|
|
|
142 $> cmake ../runtimes \
|
|
|
143 -G Ninja \
|
|
|
144 -DLLVM_ENABLE_RUNTIMES=libc \
|
|
|
145 -DCMAKE_C_COMPILER=$TARGET_C_COMPILER \
|
|
|
146 -DCMAKE_CXX_COMPILER=$TARGET_CXX_COMPILER \
|
|
|
147 -DLLVM_LIBC_FULL_BUILD=ON \
|
|
|
148 -DLIBC_HDRGEN_EXE=$HDRGEN \
|
|
|
149 -DLIBC_TARGET_TRIPLE=$TARGET_TRIPLE \
|
|
|
150 -DCMAKE_BUILD_TYPE=Debug # User can choose to use "Release" build type
|
|
|
151
|
|
|
152 Note the differences in the above cmake command versus the one used in the
|
|
|
153 CMake configure step of the standalone build recipe:
|
|
|
154
|
|
|
155 * Instead of listing ``libc`` in ``LLVM_ENABLED_PROJECTS``, we list it in
|
|
|
156 ``LLVM_ENABLED_RUNTIMES``.
|
|
|
157 * Instead of using ``llvm-project/llvm`` as the root CMake source directory,
|
|
|
158 we use ``llvm-project/runtimes`` as the root CMake source directory.
|
|
|
159 * The path to the ``libc-hdrgen`` binary built earlier is specified with
|
|
|
160 ``-DLIBC_HDRGEN_EXE=/path/to/libc-hdrgen``.
|
|
|
161
|
|
|
162 Build step
|
|
|
163 ----------
|
|
|
164
|
|
|
165 The build step in the runtimes build recipe is exactly the same as that of
|
|
|
166 the standalone build recipe:
|
|
|
167
|
|
|
168 .. code-block:: sh
|
|
|
169
|
|
|
170 $> ninja libc libm
|
|
|
171
|
|
|
172 As with the standalone build recipe, the above ninja command will build the
|
|
|
173 libc static archives for the target specified with ``-DLIBC_TARGET_TRIPLE`` in
|
|
|
174 the CMake configure step.
|
|
|
175
|
|
|
176
|
|
|
177 Bootstrap cross build
|
|
|
178 =====================
|
|
|
179
|
|
|
180 In this recipe, the clang compiler and the ``libc-hdrgen`` binary, both are
|
|
|
181 built automatically before building the libc for the target.
|
|
|
182
|
|
|
183 CMake configure step
|
|
|
184 --------------------
|
|
|
185
|
|
|
186 .. code-block:: sh
|
|
|
187
|
|
|
188 $> cd llvm-project # The llvm-project checkout
|
|
|
189 $> mkdir build
|
|
|
190 $> cd build
|
|
|
191 $> C_COMPILER=<C compiler> # For example "clang"
|
|
|
192 $> CXX_COMPILER=<C++ compiler> # For example "clang++"
|
|
|
193 $> TARGET_TRIPLE=<Your target triple>
|
|
|
194 $> cmake ../llvm \
|
|
|
195 -G Ninja \
|
|
|
196 -DCMAKE_C_COMPILER=$C_COMPILER \
|
|
|
197 -DCMAKE_CXX_COMPILER=$CXX_COMPILER \
|
|
|
198 -DLLVM_ENABLE_PROJECTS=clang \
|
|
|
199 -DLLVM_ENABLE_RUNTIMES=libc \
|
|
|
200 -DLLVM_LIBC_FULL_BUILD=ON \
|
|
|
201 -DLLVM_RUNTIME_TARGETS=$TARGET_TRIPLE \
|
|
|
202 -DCMAKE_BUILD_TYPE=Debug
|
|
|
203
|
|
|
204 Note how the above cmake command differs from the one used in the other two
|
|
|
205 recipes:
|
|
|
206
|
|
|
207 * ``clang`` is listed in ``-DLLVM_ENABLE_PROJECTS`` and ``libc`` is
|
|
|
208 listed in ``-DLLVM_ENABLE_RUNTIMES``.
|
|
|
209 * The CMake root source directory is ``llvm-project/llvm``.
|
|
|
210 * The target triple is specified with ``-DLLVM_RUNTIME_TARGETS``.
|
|
|
211
|
|
|
212 Build step
|
|
|
213 ----------
|
|
|
214
|
|
|
215 The build step is similar to the other two recipes:
|
|
|
216
|
|
|
217 .. code-block:: sh
|
|
|
218
|
|
|
219 $> ninja libc
|
|
|
220
|
|
|
221 The above ninja command should build the libc static archives for the target
|
|
|
222 specified with ``-DLLVM_RUNTIME_TARGETS``.
|
|
|
223
|
|
|
224 Building for bare metal
|
|
|
225 =======================
|
|
|
226
|
|
|
227 To build for bare metal, all one has to do is to specify the
|
|
|
228 `system <https://clang.llvm.org/docs/CrossCompilation.html#target-triple>`_
|
|
|
229 component of the target triple as ``none``. For example, to build for a
|
|
|
230 32-bit arm target on bare metal, one can use a target triple like
|
|
|
231 ``arm-none-eabi``. Other than that, the libc for a bare metal target can be
|
|
|
232 built using any of the three recipes described above.
|
