diff options
-rw-r--r-- | documentation/Makefile | 3 | ||||
-rw-r--r-- | documentation/overview-manual/figures/cross-development-toolchains.png (renamed from documentation/ref-manual/figures/cross-development-toolchains.png) | bin | 59275 -> 59275 bytes | |||
-rw-r--r-- | documentation/overview-manual/overview-concepts.xml | 216 | ||||
-rw-r--r-- | documentation/overview-manual/overview-development-environment.xml | 8 | ||||
-rw-r--r-- | documentation/ref-manual/ref-classes.xml | 14 | ||||
-rw-r--r-- | documentation/ref-manual/ref-terms.xml | 4 | ||||
-rw-r--r-- | documentation/ref-manual/ref-variables.xml | 8 | ||||
-rw-r--r-- | documentation/ref-manual/technical-details.xml | 201 |
8 files changed, 235 insertions, 219 deletions
diff --git a/documentation/Makefile b/documentation/Makefile index 4759a1d992..e9ec914df9 100644 --- a/documentation/Makefile +++ b/documentation/Makefile | |||
@@ -94,7 +94,7 @@ TARFILES = overview-style.css overview-manual.html figures/overview-title.png \ | |||
94 | figures/source-fetching.png figures/patching.png figures/configuration-compile-autoreconf.png \ | 94 | figures/source-fetching.png figures/patching.png figures/configuration-compile-autoreconf.png \ |
95 | figures/analysis-for-package-splitting.png figures/image-generation.png \ | 95 | figures/analysis-for-package-splitting.png figures/image-generation.png \ |
96 | figures/sdk-generation.png figures/images.png figures/sdk.png \ | 96 | figures/sdk-generation.png figures/images.png figures/sdk.png \ |
97 | figures/YP-flow-diagram.png \ | 97 | figures/YP-flow-diagram.png figures/cross-development-toolchains.png \ |
98 | eclipse | 98 | eclipse |
99 | MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse | 99 | MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse |
100 | FIGURES = figures | 100 | FIGURES = figures |
@@ -282,7 +282,6 @@ XSLTOPTS = --xinclude | |||
282 | ALLPREQ = html eclipse tarball | 282 | ALLPREQ = html eclipse tarball |
283 | TARFILES = ref-manual.html ref-style.css figures/poky-title.png \ | 283 | TARFILES = ref-manual.html ref-style.css figures/poky-title.png \ |
284 | figures/buildhistory.png figures/buildhistory-web.png \ | 284 | figures/buildhistory.png figures/buildhistory-web.png \ |
285 | figures/cross-development-toolchains.png \ | ||
286 | figures/building-an-image.png \ | 285 | figures/building-an-image.png \ |
287 | figures/build-workspace-directory.png \ | 286 | figures/build-workspace-directory.png \ |
288 | eclipse | 287 | eclipse |
diff --git a/documentation/ref-manual/figures/cross-development-toolchains.png b/documentation/overview-manual/figures/cross-development-toolchains.png index d36670a198..d36670a198 100644 --- a/documentation/ref-manual/figures/cross-development-toolchains.png +++ b/documentation/overview-manual/figures/cross-development-toolchains.png | |||
Binary files differ | |||
diff --git a/documentation/overview-manual/overview-concepts.xml b/documentation/overview-manual/overview-concepts.xml index aa8d35e3f9..0a45cd7256 100644 --- a/documentation/overview-manual/overview-concepts.xml +++ b/documentation/overview-manual/overview-concepts.xml | |||
@@ -255,6 +255,222 @@ | |||
255 | </section> | 255 | </section> |
256 | </section> | 256 | </section> |
257 | 257 | ||
258 | <section id="cross-development-toolchain-generation"> | ||
259 | <title>Cross-Development Toolchain Generation</title> | ||
260 | |||
261 | <para> | ||
262 | The Yocto Project does most of the work for you when it comes to | ||
263 | creating | ||
264 | <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchains</ulink>. | ||
265 | This section provides some technical background on how | ||
266 | cross-development toolchains are created and used. | ||
267 | For more information on toolchains, you can also see the | ||
268 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> | ||
269 | manual. | ||
270 | </para> | ||
271 | |||
272 | <para> | ||
273 | In the Yocto Project development environment, cross-development | ||
274 | toolchains are used to build the image and applications that run | ||
275 | on the target hardware. | ||
276 | With just a few commands, the OpenEmbedded build system creates | ||
277 | these necessary toolchains for you. | ||
278 | </para> | ||
279 | |||
280 | <para> | ||
281 | The following figure shows a high-level build environment regarding | ||
282 | toolchain construction and use. | ||
283 | </para> | ||
284 | |||
285 | <para> | ||
286 | <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" /> | ||
287 | </para> | ||
288 | |||
289 | <para> | ||
290 | Most of the work occurs on the Build Host. | ||
291 | This is the machine used to build images and generally work within the | ||
292 | the Yocto Project environment. | ||
293 | When you run BitBake to create an image, the OpenEmbedded build system | ||
294 | uses the host <filename>gcc</filename> compiler to bootstrap a | ||
295 | cross-compiler named <filename>gcc-cross</filename>. | ||
296 | The <filename>gcc-cross</filename> compiler is what BitBake uses to | ||
297 | compile source files when creating the target image. | ||
298 | You can think of <filename>gcc-cross</filename> simply as an | ||
299 | automatically generated cross-compiler that is used internally within | ||
300 | BitBake only. | ||
301 | <note> | ||
302 | The extensible SDK does not use | ||
303 | <filename>gcc-cross-canadian</filename> since this SDK | ||
304 | ships a copy of the OpenEmbedded build system and the sysroot | ||
305 | within it contains <filename>gcc-cross</filename>. | ||
306 | </note> | ||
307 | </para> | ||
308 | |||
309 | <para> | ||
310 | The chain of events that occurs when <filename>gcc-cross</filename> is | ||
311 | bootstrapped is as follows: | ||
312 | <literallayout class='monospaced'> | ||
313 | gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime | ||
314 | </literallayout> | ||
315 | <itemizedlist> | ||
316 | <listitem><para> | ||
317 | <filename>gcc</filename>: | ||
318 | The build host's GNU Compiler Collection (GCC). | ||
319 | </para></listitem> | ||
320 | <listitem><para> | ||
321 | <filename>binutils-cross</filename>: | ||
322 | The bare minimum binary utilities needed in order to run | ||
323 | the <filename>gcc-cross-initial</filename> phase of the | ||
324 | bootstrap operation. | ||
325 | </para></listitem> | ||
326 | <listitem><para> | ||
327 | <filename>gcc-cross-initial</filename>: | ||
328 | An early stage of the bootstrap process for creating | ||
329 | the cross-compiler. | ||
330 | This stage builds enough of the <filename>gcc-cross</filename>, | ||
331 | the C library, and other pieces needed to finish building the | ||
332 | final cross-compiler in later stages. | ||
333 | This tool is a "native" package (i.e. it is designed to run on | ||
334 | the build host). | ||
335 | </para></listitem> | ||
336 | <listitem><para> | ||
337 | <filename>linux-libc-headers</filename>: | ||
338 | Headers needed for the cross-compiler. | ||
339 | </para></listitem> | ||
340 | <listitem><para> | ||
341 | <filename>glibc-initial</filename>: | ||
342 | An initial version of the Embedded GLIBC needed to bootstrap | ||
343 | <filename>glibc</filename>. | ||
344 | </para></listitem> | ||
345 | <listitem><para> | ||
346 | <filename>gcc-cross</filename>: | ||
347 | The final stage of the bootstrap process for the | ||
348 | cross-compiler. | ||
349 | This stage results in the actual cross-compiler that | ||
350 | BitBake uses when it builds an image for a targeted | ||
351 | device. | ||
352 | <note> | ||
353 | If you are replacing this cross compiler toolchain | ||
354 | with a custom version, you must replace | ||
355 | <filename>gcc-cross</filename>. | ||
356 | </note> | ||
357 | This tool is also a "native" package (i.e. it is | ||
358 | designed to run on the build host). | ||
359 | </para></listitem> | ||
360 | <listitem><para> | ||
361 | <filename>gcc-runtime</filename>: | ||
362 | Runtime libraries resulting from the toolchain bootstrapping | ||
363 | process. | ||
364 | This tool produces a binary that consists of the | ||
365 | runtime libraries need for the targeted device. | ||
366 | </para></listitem> | ||
367 | </itemizedlist> | ||
368 | </para> | ||
369 | |||
370 | <para> | ||
371 | You can use the OpenEmbedded build system to build an installer for | ||
372 | the relocatable SDK used to develop applications. | ||
373 | When you run the installer, it installs the toolchain, which contains | ||
374 | the development tools (e.g., the | ||
375 | <filename>gcc-cross-canadian</filename>), | ||
376 | <filename>binutils-cross-canadian</filename>, and other | ||
377 | <filename>nativesdk-*</filename> tools, | ||
378 | which are tools native to the SDK (i.e. native to | ||
379 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_ARCH'><filename>SDK_ARCH</filename></ulink>), | ||
380 | you need to cross-compile and test your software. | ||
381 | The figure shows the commands you use to easily build out this | ||
382 | toolchain. | ||
383 | This cross-development toolchain is built to execute on the | ||
384 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>, | ||
385 | which might or might not be the same | ||
386 | machine as the Build Host. | ||
387 | <note> | ||
388 | If your target architecture is supported by the Yocto Project, | ||
389 | you can take advantage of pre-built images that ship with the | ||
390 | Yocto Project and already contain cross-development toolchain | ||
391 | installers. | ||
392 | </note> | ||
393 | </para> | ||
394 | |||
395 | <para> | ||
396 | Here is the bootstrap process for the relocatable toolchain: | ||
397 | <literallayout class='monospaced'> | ||
398 | gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> | ||
399 | glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian | ||
400 | </literallayout> | ||
401 | <itemizedlist> | ||
402 | <listitem><para> | ||
403 | <filename>gcc</filename>: | ||
404 | The build host's GNU Compiler Collection (GCC). | ||
405 | </para></listitem> | ||
406 | <listitem><para> | ||
407 | <filename>binutils-crosssdk</filename>: | ||
408 | The bare minimum binary utilities needed in order to run | ||
409 | the <filename>gcc-crosssdk-initial</filename> phase of the | ||
410 | bootstrap operation. | ||
411 | </para></listitem> | ||
412 | <listitem><para> | ||
413 | <filename>gcc-crosssdk-initial</filename>: | ||
414 | An early stage of the bootstrap process for creating | ||
415 | the cross-compiler. | ||
416 | This stage builds enough of the | ||
417 | <filename>gcc-crosssdk</filename> and supporting pieces so that | ||
418 | the final stage of the bootstrap process can produce the | ||
419 | finished cross-compiler. | ||
420 | This tool is a "native" binary that runs on the build host. | ||
421 | </para></listitem> | ||
422 | <listitem><para> | ||
423 | <filename>linux-libc-headers</filename>: | ||
424 | Headers needed for the cross-compiler. | ||
425 | </para></listitem> | ||
426 | <listitem><para> | ||
427 | <filename>glibc-initial</filename>: | ||
428 | An initial version of the Embedded GLIBC needed to bootstrap | ||
429 | <filename>nativesdk-glibc</filename>. | ||
430 | </para></listitem> | ||
431 | <listitem><para> | ||
432 | <filename>nativesdk-glibc</filename>: | ||
433 | The Embedded GLIBC needed to bootstrap the | ||
434 | <filename>gcc-crosssdk</filename>. | ||
435 | </para></listitem> | ||
436 | <listitem><para> | ||
437 | <filename>gcc-crosssdk</filename>: | ||
438 | The final stage of the bootstrap process for the | ||
439 | relocatable cross-compiler. | ||
440 | The <filename>gcc-crosssdk</filename> is a transitory compiler | ||
441 | and never leaves the build host. | ||
442 | Its purpose is to help in the bootstrap process to create the | ||
443 | eventual relocatable <filename>gcc-cross-canadian</filename> | ||
444 | compiler, which is relocatable. | ||
445 | This tool is also a "native" package (i.e. it is | ||
446 | designed to run on the build host). | ||
447 | </para></listitem> | ||
448 | <listitem><para> | ||
449 | <filename>gcc-cross-canadian</filename>: | ||
450 | The final relocatable cross-compiler. | ||
451 | When run on the | ||
452 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>, | ||
453 | this tool | ||
454 | produces executable code that runs on the target device. | ||
455 | Only one cross-canadian compiler is produced per architecture | ||
456 | since they can be targeted at different processor optimizations | ||
457 | using configurations passed to the compiler through the | ||
458 | compile commands. | ||
459 | This circumvents the need for multiple compilers and thus | ||
460 | reduces the size of the toolchains. | ||
461 | </para></listitem> | ||
462 | </itemizedlist> | ||
463 | </para> | ||
464 | |||
465 | <note> | ||
466 | For information on advantages gained when building a | ||
467 | cross-development toolchain installer, see the | ||
468 | "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" | ||
469 | section in the Yocto Project Application Development and the | ||
470 | Extensible Software Development Kit (eSDK) manual. | ||
471 | </note> | ||
472 | </section> | ||
473 | |||
258 | <section id='x32'> | 474 | <section id='x32'> |
259 | <title>x32 psABI</title> | 475 | <title>x32 psABI</title> |
260 | 476 | ||
diff --git a/documentation/overview-manual/overview-development-environment.xml b/documentation/overview-manual/overview-development-environment.xml index d34f35ec88..62f3ccd438 100644 --- a/documentation/overview-manual/overview-development-environment.xml +++ b/documentation/overview-manual/overview-development-environment.xml | |||
@@ -2426,8 +2426,8 @@ | |||
2426 | <note> | 2426 | <note> |
2427 | For more information on the cross-development toolchain | 2427 | For more information on the cross-development toolchain |
2428 | generation, see the | 2428 | generation, see the |
2429 | "<ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" | 2429 | "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" |
2430 | section in the Yocto Project Reference Manual. | 2430 | section. |
2431 | For information on advantages gained when building a | 2431 | For information on advantages gained when building a |
2432 | cross-development toolchain using the | 2432 | cross-development toolchain using the |
2433 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></ulink> | 2433 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></ulink> |
@@ -2792,8 +2792,8 @@ | |||
2792 | <listitem><para> | 2792 | <listitem><para> |
2793 | For background information on cross-development toolchains | 2793 | For background information on cross-development toolchains |
2794 | in the Yocto Project development environment, see the | 2794 | in the Yocto Project development environment, see the |
2795 | "<ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" | 2795 | "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" |
2796 | section in the Yocto Project Reference Manual. | 2796 | section. |
2797 | </para></listitem> | 2797 | </para></listitem> |
2798 | <listitem><para> | 2798 | <listitem><para> |
2799 | For information on setting up a cross-development | 2799 | For information on setting up a cross-development |
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml index f27f33f292..b11fbea63e 100644 --- a/documentation/ref-manual/ref-classes.xml +++ b/documentation/ref-manual/ref-classes.xml | |||
@@ -568,8 +568,9 @@ | |||
568 | provides support for the recipes that build the Canadian | 568 | provides support for the recipes that build the Canadian |
569 | Cross-compilation tools for SDKs. | 569 | Cross-compilation tools for SDKs. |
570 | See the | 570 | See the |
571 | "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" | 571 | "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" |
572 | section for more discussion on these cross-compilation tools. | 572 | section in the Yocto Project Overview Manual for more discussion on |
573 | these cross-compilation tools. | ||
573 | </para> | 574 | </para> |
574 | </section> | 575 | </section> |
575 | 576 | ||
@@ -581,8 +582,9 @@ | |||
581 | provides support for the recipes that build the cross-compilation | 582 | provides support for the recipes that build the cross-compilation |
582 | tools used for building SDKs. | 583 | tools used for building SDKs. |
583 | See the | 584 | See the |
584 | "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" | 585 | "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" |
585 | section for more discussion on these cross-compilation tools. | 586 | section in the Yocto Project Overview Manual for more discussion on |
587 | these cross-compilation tools. | ||
586 | </para> | 588 | </para> |
587 | </section> | 589 | </section> |
588 | 590 | ||
@@ -2720,8 +2722,8 @@ This check was removed for YP 2.3 release | |||
2720 | <para> | 2722 | <para> |
2721 | For more information on the cross-development toolchain | 2723 | For more information on the cross-development toolchain |
2722 | generation, see the | 2724 | generation, see the |
2723 | "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" | 2725 | "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" |
2724 | section. | 2726 | section in the Yocto Project Overview Manual. |
2725 | For information on advantages gained when building a | 2727 | For information on advantages gained when building a |
2726 | cross-development toolchain using the | 2728 | cross-development toolchain using the |
2727 | <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link> | 2729 | <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link> |
diff --git a/documentation/ref-manual/ref-terms.xml b/documentation/ref-manual/ref-terms.xml index f5ff7df5fb..237e765202 100644 --- a/documentation/ref-manual/ref-terms.xml +++ b/documentation/ref-manual/ref-terms.xml | |||
@@ -181,8 +181,8 @@ | |||
181 | <para>Creation of these toolchains is simple and automated. | 181 | <para>Creation of these toolchains is simple and automated. |
182 | For information on toolchain concepts as they apply to the | 182 | For information on toolchain concepts as they apply to the |
183 | Yocto Project, see the | 183 | Yocto Project, see the |
184 | "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" | 184 | "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" |
185 | section. | 185 | section in the Yocto Project Overview Manual. |
186 | You can also find more information on using the | 186 | You can also find more information on using the |
187 | relocatable toolchain in the | 187 | relocatable toolchain in the |
188 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> | 188 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> |
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index 1b5f863970..48849b1fef 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml | |||
@@ -15183,8 +15183,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
15183 | <para> | 15183 | <para> |
15184 | For background information on cross-development toolchains | 15184 | For background information on cross-development toolchains |
15185 | in the Yocto Project development environment, see the | 15185 | in the Yocto Project development environment, see the |
15186 | "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" | 15186 | "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" |
15187 | section. | 15187 | section in the Yocto Project Overview Manual. |
15188 | For information on setting up a cross-development | 15188 | For information on setting up a cross-development |
15189 | environment, see the | 15189 | environment, see the |
15190 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> | 15190 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> |
@@ -15242,8 +15242,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
15242 | <para> | 15242 | <para> |
15243 | For background information on cross-development toolchains | 15243 | For background information on cross-development toolchains |
15244 | in the Yocto Project development environment, see the | 15244 | in the Yocto Project development environment, see the |
15245 | "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" | 15245 | "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" |
15246 | section. | 15246 | section in the Yocto Project Overview Manual. |
15247 | For information on setting up a cross-development | 15247 | For information on setting up a cross-development |
15248 | environment, see the | 15248 | environment, see the |
15249 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> | 15249 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> |
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index d0929bd756..3d3def5a65 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml | |||
@@ -13,207 +13,6 @@ | |||
13 | x32, Wayland support, and Licenses. | 13 | x32, Wayland support, and Licenses. |
14 | </para> | 14 | </para> |
15 | 15 | ||
16 | <section id="cross-development-toolchain-generation"> | ||
17 | <title>Cross-Development Toolchain Generation</title> | ||
18 | |||
19 | <para> | ||
20 | The Yocto Project does most of the work for you when it comes to | ||
21 | creating | ||
22 | <link linkend='cross-development-toolchain'>cross-development toolchains</link>. | ||
23 | This section provides some technical background on how | ||
24 | cross-development toolchains are created and used. | ||
25 | For more information on toolchains, you can also see the | ||
26 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> | ||
27 | manual. | ||
28 | </para> | ||
29 | |||
30 | <para> | ||
31 | In the Yocto Project development environment, cross-development | ||
32 | toolchains are used to build the image and applications that run on the | ||
33 | target hardware. | ||
34 | With just a few commands, the OpenEmbedded build system creates | ||
35 | these necessary toolchains for you. | ||
36 | </para> | ||
37 | |||
38 | <para> | ||
39 | The following figure shows a high-level build environment regarding | ||
40 | toolchain construction and use. | ||
41 | </para> | ||
42 | |||
43 | <para> | ||
44 | <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" /> | ||
45 | </para> | ||
46 | |||
47 | <para> | ||
48 | Most of the work occurs on the Build Host. | ||
49 | This is the machine used to build images and generally work within the | ||
50 | the Yocto Project environment. | ||
51 | When you run BitBake to create an image, the OpenEmbedded build system | ||
52 | uses the host <filename>gcc</filename> compiler to bootstrap a | ||
53 | cross-compiler named <filename>gcc-cross</filename>. | ||
54 | The <filename>gcc-cross</filename> compiler is what BitBake uses to | ||
55 | compile source files when creating the target image. | ||
56 | You can think of <filename>gcc-cross</filename> simply as an | ||
57 | automatically generated cross-compiler that is used internally within | ||
58 | BitBake only. | ||
59 | <note> | ||
60 | The extensible SDK does not use | ||
61 | <filename>gcc-cross-canadian</filename> since this SDK | ||
62 | ships a copy of the OpenEmbedded build system and the sysroot | ||
63 | within it contains <filename>gcc-cross</filename>. | ||
64 | </note> | ||
65 | </para> | ||
66 | |||
67 | <para> | ||
68 | The chain of events that occurs when <filename>gcc-cross</filename> is | ||
69 | bootstrapped is as follows: | ||
70 | <literallayout class='monospaced'> | ||
71 | gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime | ||
72 | </literallayout> | ||
73 | <itemizedlist> | ||
74 | <listitem><para><filename>gcc</filename>: | ||
75 | The build host's GNU Compiler Collection (GCC). | ||
76 | </para></listitem> | ||
77 | <listitem><para><filename>binutils-cross</filename>: | ||
78 | The bare minimum binary utilities needed in order to run | ||
79 | the <filename>gcc-cross-initial</filename> phase of the | ||
80 | bootstrap operation. | ||
81 | </para></listitem> | ||
82 | <listitem><para><filename>gcc-cross-initial</filename>: | ||
83 | An early stage of the bootstrap process for creating | ||
84 | the cross-compiler. | ||
85 | This stage builds enough of the <filename>gcc-cross</filename>, | ||
86 | the C library, and other pieces needed to finish building the | ||
87 | final cross-compiler in later stages. | ||
88 | This tool is a "native" package (i.e. it is designed to run on | ||
89 | the build host). | ||
90 | </para></listitem> | ||
91 | <listitem><para><filename>linux-libc-headers</filename>: | ||
92 | Headers needed for the cross-compiler. | ||
93 | </para></listitem> | ||
94 | <listitem><para><filename>glibc-initial</filename>: | ||
95 | An initial version of the Embedded GLIBC needed to bootstrap | ||
96 | <filename>glibc</filename>. | ||
97 | </para></listitem> | ||
98 | <listitem><para><filename>gcc-cross</filename>: | ||
99 | The final stage of the bootstrap process for the | ||
100 | cross-compiler. | ||
101 | This stage results in the actual cross-compiler that | ||
102 | BitBake uses when it builds an image for a targeted | ||
103 | device. | ||
104 | <note> | ||
105 | If you are replacing this cross compiler toolchain | ||
106 | with a custom version, you must replace | ||
107 | <filename>gcc-cross</filename>. | ||
108 | </note> | ||
109 | This tool is also a "native" package (i.e. it is | ||
110 | designed to run on the build host). | ||
111 | </para></listitem> | ||
112 | <listitem><para><filename>gcc-runtime</filename>: | ||
113 | Runtime libraries resulting from the toolchain bootstrapping | ||
114 | process. | ||
115 | This tool produces a binary that consists of the | ||
116 | runtime libraries need for the targeted device. | ||
117 | </para></listitem> | ||
118 | </itemizedlist> | ||
119 | </para> | ||
120 | |||
121 | <para> | ||
122 | You can use the OpenEmbedded build system to build an installer for | ||
123 | the relocatable SDK used to develop applications. | ||
124 | When you run the installer, it installs the toolchain, which contains | ||
125 | the development tools (e.g., the | ||
126 | <filename>gcc-cross-canadian</filename>), | ||
127 | <filename>binutils-cross-canadian</filename>, and other | ||
128 | <filename>nativesdk-*</filename> tools, | ||
129 | which are tools native to the SDK (i.e. native to | ||
130 | <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>), | ||
131 | you need to cross-compile and test your software. | ||
132 | The figure shows the commands you use to easily build out this | ||
133 | toolchain. | ||
134 | This cross-development toolchain is built to execute on the | ||
135 | <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>, | ||
136 | which might or might not be the same | ||
137 | machine as the Build Host. | ||
138 | <note> | ||
139 | If your target architecture is supported by the Yocto Project, | ||
140 | you can take advantage of pre-built images that ship with the | ||
141 | Yocto Project and already contain cross-development toolchain | ||
142 | installers. | ||
143 | </note> | ||
144 | </para> | ||
145 | |||
146 | <para> | ||
147 | Here is the bootstrap process for the relocatable toolchain: | ||
148 | <literallayout class='monospaced'> | ||
149 | gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> | ||
150 | glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian | ||
151 | </literallayout> | ||
152 | <itemizedlist> | ||
153 | <listitem><para><filename>gcc</filename>: | ||
154 | The build host's GNU Compiler Collection (GCC). | ||
155 | </para></listitem> | ||
156 | <listitem><para><filename>binutils-crosssdk</filename>: | ||
157 | The bare minimum binary utilities needed in order to run | ||
158 | the <filename>gcc-crosssdk-initial</filename> phase of the | ||
159 | bootstrap operation. | ||
160 | </para></listitem> | ||
161 | <listitem><para><filename>gcc-crosssdk-initial</filename>: | ||
162 | An early stage of the bootstrap process for creating | ||
163 | the cross-compiler. | ||
164 | This stage builds enough of the | ||
165 | <filename>gcc-crosssdk</filename> and supporting pieces so that | ||
166 | the final stage of the bootstrap process can produce the | ||
167 | finished cross-compiler. | ||
168 | This tool is a "native" binary that runs on the build host. | ||
169 | </para></listitem> | ||
170 | <listitem><para><filename>linux-libc-headers</filename>: | ||
171 | Headers needed for the cross-compiler. | ||
172 | </para></listitem> | ||
173 | <listitem><para><filename>glibc-initial</filename>: | ||
174 | An initial version of the Embedded GLIBC needed to bootstrap | ||
175 | <filename>nativesdk-glibc</filename>. | ||
176 | </para></listitem> | ||
177 | <listitem><para><filename>nativesdk-glibc</filename>: | ||
178 | The Embedded GLIBC needed to bootstrap the | ||
179 | <filename>gcc-crosssdk</filename>. | ||
180 | </para></listitem> | ||
181 | <listitem><para><filename>gcc-crosssdk</filename>: | ||
182 | The final stage of the bootstrap process for the | ||
183 | relocatable cross-compiler. | ||
184 | The <filename>gcc-crosssdk</filename> is a transitory compiler | ||
185 | and never leaves the build host. | ||
186 | Its purpose is to help in the bootstrap process to create the | ||
187 | eventual relocatable <filename>gcc-cross-canadian</filename> | ||
188 | compiler, which is relocatable. | ||
189 | This tool is also a "native" package (i.e. it is | ||
190 | designed to run on the build host). | ||
191 | </para></listitem> | ||
192 | <listitem><para><filename>gcc-cross-canadian</filename>: | ||
193 | The final relocatable cross-compiler. | ||
194 | When run on the | ||
195 | <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>, | ||
196 | this tool | ||
197 | produces executable code that runs on the target device. | ||
198 | Only one cross-canadian compiler is produced per architecture | ||
199 | since they can be targeted at different processor optimizations | ||
200 | using configurations passed to the compiler through the | ||
201 | compile commands. | ||
202 | This circumvents the need for multiple compilers and thus | ||
203 | reduces the size of the toolchains. | ||
204 | </para></listitem> | ||
205 | </itemizedlist> | ||
206 | </para> | ||
207 | |||
208 | <note> | ||
209 | For information on advantages gained when building a | ||
210 | cross-development toolchain installer, see the | ||
211 | "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" | ||
212 | section in the Yocto Project Application Development and the | ||
213 | Extensible Software Development Kit (eSDK) manual. | ||
214 | </note> | ||
215 | </section> | ||
216 | |||
217 | <section id="shared-state-cache"> | 16 | <section id="shared-state-cache"> |
218 | <title>Shared State Cache</title> | 17 | <title>Shared State Cache</title> |
219 | 18 | ||