path: root/documentation
diff options
authorScott Rifenbark <>2013-06-14 14:10:46 (GMT)
committerRichard Purdie <>2013-06-21 13:26:30 (GMT)
commit07c94053657e1a5d1236f39b4c86d7ad9154b1fd (patch)
tree1d09a94216507e47cf521c47dda6ae32c1eb521c /documentation
parent26a9dd8c29102863a79333c76b2b9507bada89e8 (diff)
ref-manual: New section on cross-development toolchains added.
First draft of this new section. It included a figure so the figure had to be added to the "figures" folder of the mega-manual. New section introduces concepts behind the types of cross-toolchains YP develops through user commands that build images and build the relocatable SDK. (From yocto-docs rev: b3c9a2e3f90892a2175110393a962fd152316ca6) Signed-off-by: Scott Rifenbark <> Signed-off-by: Richard Purdie <>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/mega-manual/figures/cross-development-toolchains.pngbin0 -> 59275 bytes
-rw-r--r--documentation/ref-manual/figures/cross-development-toolchains.pngbin0 -> 59275 bytes
3 files changed, 174 insertions, 0 deletions
diff --git a/documentation/mega-manual/figures/cross-development-toolchains.png b/documentation/mega-manual/figures/cross-development-toolchains.png
new file mode 100644
index 0000000..d36670a
--- /dev/null
+++ b/documentation/mega-manual/figures/cross-development-toolchains.png
Binary files differ
diff --git a/documentation/ref-manual/figures/cross-development-toolchains.png b/documentation/ref-manual/figures/cross-development-toolchains.png
new file mode 100644
index 0000000..d36670a
--- /dev/null
+++ b/documentation/ref-manual/figures/cross-development-toolchains.png
Binary files differ
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 0634f57..f17291f 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -153,6 +153,180 @@
153 </section> 153 </section>
154</section> 154</section>
155 155
156<section id="cross-development-toolchain-generation">
157 <title>Cross-Development Toolchain Generation</title>
159 <para>
160 The Yocto Project does most of the work for you when it comes to
161 creating
162 <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>cross-development toolchains</ulink>.
163 This section provides some technical background information on how
164 cross-development toolchains are created and used.
165 For more information on these toolchain, you can also see the
166 <ulink url='&YOCTO_DOCS_ADT_URL;'>the Yocto Project Application Developer's Guide</ulink>.
167 </para>
169 <para>
170 In the Yocto Project development environment, cross-development
171 toolchains are used to build the image and applications that run on the
172 target hardware.
173 With just a few commands, the OpenEmbedded build system creates
174 these necessary toolchains for you.
175 </para>
177 <para>
178 The following figure shows a high-level build environment regarding
179 toolchain construction and use.
180 </para>
182 <para>
183 <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" />
184 </para>
186 <para>
187 Most of the work occurs on the Build Host.
188 This is the machine used to build images and generally work within the
189 the Yocto Project environment.
190 When you run BitBake to create an image, the OpenEmbedded build system
191 uses the host <filename>gcc</filename> compiler to bootstrap a
192 cross-compiler named <filename>gcc-cross</filename>.
193 The <filename>gcc-cross</filename> compiler is what BitBake uses to
194 compile source files when creating the target image.
195 You can think of <filename>gcc-cross</filename> simply as an
196 automatically generated cross-compiler that is used internally within
197 BitBake only.
198 </para>
200 <para>
201 The chain of events that occurs when <filename>gcc-cross</filename> is
202 bootstrapped is as follows:
203 <literallayout class='monospaced'>
204 gcc -> binutils-cross -> gcc-cross-initial -> linux_libc-headers -> eglibc-initial -> eglibc -> gcc-cross -> gcc-runtime
205 </literallayout>
206 <itemizedlist>
207 <listitem><para><filename>gcc</filename>:
208 The build host's GNU Compiler Collection (GCC).
209 </para></listitem>
210 <listitem><para><filename>binutils-cross</filename>:
211 The bare minimum binary utilities needed in order to run
212 the <filename>gcc-cross-initial</filename> phase of the
213 bootstrap operation.
214 </para></listitem>
215 <listitem><para><filename>gcc-cross-initial</filename>:
216 An early stage of the bootstrap process for creating
217 the cross-compiler.
218 This stage builds enough of the <filename>gcc-cross</filename>,
219 the C library, and other pieces needed to finish building the
220 final cross-compiler in later stages.
221 This tool is a "native" package (i.e. it is designed to run on
222 the build host).
223 </para></listitem>
224 <listitem><para><filename>linux_libc-headers</filename>:
225 Headers needed for the cross-compiler.
226 </para></listitem>
227 <listitem><para><filename>eglibc-initial</filename>:
228 An initial version of the Embedded GLIBC needed to bootstrap
229 <filename>eglibc</filename>.
230 </para></listitem>
231 <listitem><para><filename>gcc-cross</filename>:
232 The final stage of the bootstrap process for the
233 cross-compiler.
234 This stage results in the actual cross-compiler that
235 BitBake uses when it builds an image for a targeted
236 device.
237 <note>
238 If you are replacing this cross compiler toolchain
239 with a custom version, you must replace
240 <filename>gcc-cross</filename>.
241 </note>
242 This tool is also a "native" package (i.e. it is
243 designed to run on the build host).
244 </para></listitem>
245 <listitem><para><filename>gcc-runtime</filename>:
246 Runtime libraries resulting from the toolchain bootstrapping
247 process.
248 This tool produces a binary that consists of the
249 runtime libraries need for the targeted device.
250 </para></listitem>
251 </itemizedlist>
252 </para>
254 <para>
255 You can use the OpenEmbedded build system to build an installer for
256 the relocatable SDK used to develop applications.
257 When you run the installer, it installs the toolchain, which contains
258 the development tools (e.g., the
259 <filename>gcc-cross-canadian</filename>),
260 <filename>binutils-cross-canadian</filename>, and other
261 <filename>nativesdk-*</filename> tools you need to cross-compile and
262 test your software.
263 The figure shows the commands you use to easily build out this
264 toolchain.
265 This cross-development toolchain is built to execute on the
266 <filename>SDKMACHINE</filename>, which might or might not be the same
267 machine as the Build Host.
268 <note>
269 If your target architecture is supported by the Yocto Project,
270 you can take advantage of pre-built images that ship with the
271 Yocto Project and already contain cross-development toolchain
272 installers.
273 </note>
274 </para>
276 <para>
277 Here is the bootstrap process for the relocatable toolchain:
278 <literallayout class='monospaced'>
279 gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux_libc-headers -> eglibc-initial -> nativesdk-eglibc -> gcc-crosssdk -> gcc-cross-canadian
280 </literallayout>
281 <itemizedlist>
282 <listitem><para><filename>gcc</filename>:
283 The build host's GNU Compiler Collection (GCC).
284 </para></listitem>
285 <listitem><para><filename>binutils-crosssdk</filename>:
286 The bare minimum binary utilities needed in order to run
287 the <filename>gcc-crosssdk-initial</filename> phase of the
288 bootstrap operation.
289 </para></listitem>
290 <listitem><para><filename>gcc-crosssdk-initial</filename>:
291 An early stage of the bootstrap process for creating
292 the cross-compiler.
293 This stage builds enough of the
294 <filename>gcc-crosssdk</filename> and supporting pieces so that
295 the final stage of the bootstrap process can produce the
296 finished cross-compiler.
297 This tool is a "native" binary that runs on the build host.
298 </para></listitem>
299 <listitem><para><filename>linux_libc-headers</filename>:
300 Headers needed for the cross-compiler.
301 </para></listitem>
302 <listitem><para><filename>eglibc-initial</filename>:
303 An initial version of the Embedded GLIBC needed to bootstrap
304 <filename>nativesdk-eglibc</filename>.
305 </para></listitem>
306 <listitem><para><filename>nativesdk-eglibc</filename>:
307 The Embedded GLIBC needed to bootstrap the
308 <filename>gcc-crosssdk</filename>.
309 </para></listitem>
310 <listitem><para><filename>gcc-crosssdk</filename>:
311 The final stage of the bootstrap process for the
312 relocatable cross-compiler.
313 The <filename>gcc-crosssdk</filename> is a transitory compiler
314 and never leaves the build host.
315 Its purpose is to help in the bootstrap process to create the
316 eventual relocatable <filename>gcc-cross-canadian</filename>
317 compiler, which is relocatable.
318 This tool is also a "native" package (i.e. it is
319 designed to run on the build host).
320 </para></listitem>
321 <listitem><para><filename>gcc-cross-canadian</filename>:
322 The final relocatable cross-compiler.
323 When run on the <filename>SDKMACHINE</filename>, this tool
324 produces executable code that runs on the target device.
325 </para></listitem>
326 </itemizedlist>
327 </para>
156<section id="shared-state-cache"> 330<section id="shared-state-cache">
157 <title>Shared State Cache</title> 331 <title>Shared State Cache</title>
158 332