From 6bf7b263ff2ada9dd1335fcc900820af32dc99c1 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 10 Jan 2018 13:01:25 -0800 Subject: ref-manual, overview-manual, Makefile: Moved toolchain concepts Fixes [YOCTO #12370] Moved the "Cross-Development Toolchain Generation" section from the ref-manual to the overview-manual into the concepts chapter. This information is conceptual and now needs to live in the concepts chapter of the new overview-manual. Moving the section caused a few links to have to be fixed in the ref-manual. There was also a figure in the section. So, I had to move the figure from the ref-manual to the overview-manual "figures" folder and update the Makefile for the TARFILE generation. (From yocto-docs rev: 1f3ee5ab308cbe6bd7194086026db397b67ca7c4) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/Makefile | 3 +- .../figures/cross-development-toolchains.png | Bin 0 -> 59275 bytes .../overview-manual/overview-concepts.xml | 216 +++++++++++++++++++++ .../overview-development-environment.xml | 8 +- .../figures/cross-development-toolchains.png | Bin 59275 -> 0 bytes documentation/ref-manual/ref-classes.xml | 14 +- documentation/ref-manual/ref-terms.xml | 4 +- documentation/ref-manual/ref-variables.xml | 8 +- documentation/ref-manual/technical-details.xml | 201 ------------------- 9 files changed, 235 insertions(+), 219 deletions(-) create mode 100644 documentation/overview-manual/figures/cross-development-toolchains.png delete mode 100644 documentation/ref-manual/figures/cross-development-toolchains.png 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 \ figures/source-fetching.png figures/patching.png figures/configuration-compile-autoreconf.png \ figures/analysis-for-package-splitting.png figures/image-generation.png \ figures/sdk-generation.png figures/images.png figures/sdk.png \ - figures/YP-flow-diagram.png \ + figures/YP-flow-diagram.png figures/cross-development-toolchains.png \ eclipse MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse FIGURES = figures @@ -282,7 +282,6 @@ XSLTOPTS = --xinclude ALLPREQ = html eclipse tarball TARFILES = ref-manual.html ref-style.css figures/poky-title.png \ figures/buildhistory.png figures/buildhistory-web.png \ - figures/cross-development-toolchains.png \ figures/building-an-image.png \ figures/build-workspace-directory.png \ eclipse diff --git a/documentation/overview-manual/figures/cross-development-toolchains.png b/documentation/overview-manual/figures/cross-development-toolchains.png new file mode 100644 index 0000000000..d36670a198 Binary files /dev/null and b/documentation/overview-manual/figures/cross-development-toolchains.png 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 @@ +
+ Cross-Development Toolchain Generation + + + The Yocto Project does most of the work for you when it comes to + creating + cross-development toolchains. + This section provides some technical background on how + cross-development toolchains are created and used. + For more information on toolchains, you can also see the + Yocto Project Application Development and the Extensible Software Development Kit (eSDK) + manual. + + + + In the Yocto Project development environment, cross-development + toolchains are used to build the image and applications that run + on the target hardware. + With just a few commands, the OpenEmbedded build system creates + these necessary toolchains for you. + + + + The following figure shows a high-level build environment regarding + toolchain construction and use. + + + + + + + + Most of the work occurs on the Build Host. + This is the machine used to build images and generally work within the + the Yocto Project environment. + When you run BitBake to create an image, the OpenEmbedded build system + uses the host gcc compiler to bootstrap a + cross-compiler named gcc-cross. + The gcc-cross compiler is what BitBake uses to + compile source files when creating the target image. + You can think of gcc-cross simply as an + automatically generated cross-compiler that is used internally within + BitBake only. + + The extensible SDK does not use + gcc-cross-canadian since this SDK + ships a copy of the OpenEmbedded build system and the sysroot + within it contains gcc-cross. + + + + + The chain of events that occurs when gcc-cross is + bootstrapped is as follows: + + gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime + + + + gcc: + The build host's GNU Compiler Collection (GCC). + + + binutils-cross: + The bare minimum binary utilities needed in order to run + the gcc-cross-initial phase of the + bootstrap operation. + + + gcc-cross-initial: + An early stage of the bootstrap process for creating + the cross-compiler. + This stage builds enough of the gcc-cross, + the C library, and other pieces needed to finish building the + final cross-compiler in later stages. + This tool is a "native" package (i.e. it is designed to run on + the build host). + + + linux-libc-headers: + Headers needed for the cross-compiler. + + + glibc-initial: + An initial version of the Embedded GLIBC needed to bootstrap + glibc. + + + gcc-cross: + The final stage of the bootstrap process for the + cross-compiler. + This stage results in the actual cross-compiler that + BitBake uses when it builds an image for a targeted + device. + + If you are replacing this cross compiler toolchain + with a custom version, you must replace + gcc-cross. + + This tool is also a "native" package (i.e. it is + designed to run on the build host). + + + gcc-runtime: + Runtime libraries resulting from the toolchain bootstrapping + process. + This tool produces a binary that consists of the + runtime libraries need for the targeted device. + + + + + + You can use the OpenEmbedded build system to build an installer for + the relocatable SDK used to develop applications. + When you run the installer, it installs the toolchain, which contains + the development tools (e.g., the + gcc-cross-canadian), + binutils-cross-canadian, and other + nativesdk-* tools, + which are tools native to the SDK (i.e. native to + SDK_ARCH), + you need to cross-compile and test your software. + The figure shows the commands you use to easily build out this + toolchain. + This cross-development toolchain is built to execute on the + SDKMACHINE, + which might or might not be the same + machine as the Build Host. + + If your target architecture is supported by the Yocto Project, + you can take advantage of pre-built images that ship with the + Yocto Project and already contain cross-development toolchain + installers. + + + + + Here is the bootstrap process for the relocatable toolchain: + + gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> + glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian + + + + gcc: + The build host's GNU Compiler Collection (GCC). + + + binutils-crosssdk: + The bare minimum binary utilities needed in order to run + the gcc-crosssdk-initial phase of the + bootstrap operation. + + + gcc-crosssdk-initial: + An early stage of the bootstrap process for creating + the cross-compiler. + This stage builds enough of the + gcc-crosssdk and supporting pieces so that + the final stage of the bootstrap process can produce the + finished cross-compiler. + This tool is a "native" binary that runs on the build host. + + + linux-libc-headers: + Headers needed for the cross-compiler. + + + glibc-initial: + An initial version of the Embedded GLIBC needed to bootstrap + nativesdk-glibc. + + + nativesdk-glibc: + The Embedded GLIBC needed to bootstrap the + gcc-crosssdk. + + + gcc-crosssdk: + The final stage of the bootstrap process for the + relocatable cross-compiler. + The gcc-crosssdk is a transitory compiler + and never leaves the build host. + Its purpose is to help in the bootstrap process to create the + eventual relocatable gcc-cross-canadian + compiler, which is relocatable. + This tool is also a "native" package (i.e. it is + designed to run on the build host). + + + gcc-cross-canadian: + The final relocatable cross-compiler. + When run on the + SDKMACHINE, + this tool + produces executable code that runs on the target device. + Only one cross-canadian compiler is produced per architecture + since they can be targeted at different processor optimizations + using configurations passed to the compiler through the + compile commands. + This circumvents the need for multiple compilers and thus + reduces the size of the toolchains. + + + + + + For information on advantages gained when building a + cross-development toolchain installer, see the + "Building an SDK Installer" + section in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + +
+
x32 psABI 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 @@ For more information on the cross-development toolchain generation, see the - "Cross-Development Toolchain Generation" - section in the Yocto Project Reference Manual. + "Cross-Development Toolchain Generation" + section. For information on advantages gained when building a cross-development toolchain using the do_populate_sdk @@ -2792,8 +2792,8 @@ For background information on cross-development toolchains in the Yocto Project development environment, see the - "Cross-Development Toolchain Generation" - section in the Yocto Project Reference Manual. + "Cross-Development Toolchain Generation" + section. For information on setting up a cross-development diff --git a/documentation/ref-manual/figures/cross-development-toolchains.png b/documentation/ref-manual/figures/cross-development-toolchains.png deleted file mode 100644 index d36670a198..0000000000 Binary files a/documentation/ref-manual/figures/cross-development-toolchains.png and /dev/null differ 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 @@ provides support for the recipes that build the Canadian Cross-compilation tools for SDKs. See the - "Cross-Development Toolchain Generation" - section for more discussion on these cross-compilation tools. + "Cross-Development Toolchain Generation" + section in the Yocto Project Overview Manual for more discussion on + these cross-compilation tools.
@@ -581,8 +582,9 @@ provides support for the recipes that build the cross-compilation tools used for building SDKs. See the - "Cross-Development Toolchain Generation" - section for more discussion on these cross-compilation tools. + "Cross-Development Toolchain Generation" + section in the Yocto Project Overview Manual for more discussion on + these cross-compilation tools. @@ -2720,8 +2722,8 @@ This check was removed for YP 2.3 release For more information on the cross-development toolchain generation, see the - "Cross-Development Toolchain Generation" - section. + "Cross-Development Toolchain Generation" + section in the Yocto Project Overview Manual. For information on advantages gained when building a cross-development toolchain using the do_populate_sdk 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 @@ Creation of these toolchains is simple and automated. For information on toolchain concepts as they apply to the Yocto Project, see the - "Cross-Development Toolchain Generation" - section. + "Cross-Development Toolchain Generation" + section in the Yocto Project Overview Manual. You can also find more information on using the relocatable toolchain in the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) 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" For background information on cross-development toolchains in the Yocto Project development environment, see the - "Cross-Development Toolchain Generation" - section. + "Cross-Development Toolchain Generation" + section in the Yocto Project Overview Manual. For information on setting up a cross-development environment, see the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) @@ -15242,8 +15242,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" For background information on cross-development toolchains in the Yocto Project development environment, see the - "Cross-Development Toolchain Generation" - section. + "Cross-Development Toolchain Generation" + section in the Yocto Project Overview Manual. For information on setting up a cross-development environment, see the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) 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 @@ x32, Wayland support, and Licenses. -
- Cross-Development Toolchain Generation - - - The Yocto Project does most of the work for you when it comes to - creating - cross-development toolchains. - This section provides some technical background on how - cross-development toolchains are created and used. - For more information on toolchains, you can also see the - Yocto Project Application Development and the Extensible Software Development Kit (eSDK) - manual. - - - - In the Yocto Project development environment, cross-development - toolchains are used to build the image and applications that run on the - target hardware. - With just a few commands, the OpenEmbedded build system creates - these necessary toolchains for you. - - - - The following figure shows a high-level build environment regarding - toolchain construction and use. - - - - - - - - Most of the work occurs on the Build Host. - This is the machine used to build images and generally work within the - the Yocto Project environment. - When you run BitBake to create an image, the OpenEmbedded build system - uses the host gcc compiler to bootstrap a - cross-compiler named gcc-cross. - The gcc-cross compiler is what BitBake uses to - compile source files when creating the target image. - You can think of gcc-cross simply as an - automatically generated cross-compiler that is used internally within - BitBake only. - - The extensible SDK does not use - gcc-cross-canadian since this SDK - ships a copy of the OpenEmbedded build system and the sysroot - within it contains gcc-cross. - - - - - The chain of events that occurs when gcc-cross is - bootstrapped is as follows: - - gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime - - - gcc: - The build host's GNU Compiler Collection (GCC). - - binutils-cross: - The bare minimum binary utilities needed in order to run - the gcc-cross-initial phase of the - bootstrap operation. - - gcc-cross-initial: - An early stage of the bootstrap process for creating - the cross-compiler. - This stage builds enough of the gcc-cross, - the C library, and other pieces needed to finish building the - final cross-compiler in later stages. - This tool is a "native" package (i.e. it is designed to run on - the build host). - - linux-libc-headers: - Headers needed for the cross-compiler. - - glibc-initial: - An initial version of the Embedded GLIBC needed to bootstrap - glibc. - - gcc-cross: - The final stage of the bootstrap process for the - cross-compiler. - This stage results in the actual cross-compiler that - BitBake uses when it builds an image for a targeted - device. - - If you are replacing this cross compiler toolchain - with a custom version, you must replace - gcc-cross. - - This tool is also a "native" package (i.e. it is - designed to run on the build host). - - gcc-runtime: - Runtime libraries resulting from the toolchain bootstrapping - process. - This tool produces a binary that consists of the - runtime libraries need for the targeted device. - - - - - - You can use the OpenEmbedded build system to build an installer for - the relocatable SDK used to develop applications. - When you run the installer, it installs the toolchain, which contains - the development tools (e.g., the - gcc-cross-canadian), - binutils-cross-canadian, and other - nativesdk-* tools, - which are tools native to the SDK (i.e. native to - SDK_ARCH), - you need to cross-compile and test your software. - The figure shows the commands you use to easily build out this - toolchain. - This cross-development toolchain is built to execute on the - SDKMACHINE, - which might or might not be the same - machine as the Build Host. - - If your target architecture is supported by the Yocto Project, - you can take advantage of pre-built images that ship with the - Yocto Project and already contain cross-development toolchain - installers. - - - - - Here is the bootstrap process for the relocatable toolchain: - - gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> - glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian - - - gcc: - The build host's GNU Compiler Collection (GCC). - - binutils-crosssdk: - The bare minimum binary utilities needed in order to run - the gcc-crosssdk-initial phase of the - bootstrap operation. - - gcc-crosssdk-initial: - An early stage of the bootstrap process for creating - the cross-compiler. - This stage builds enough of the - gcc-crosssdk and supporting pieces so that - the final stage of the bootstrap process can produce the - finished cross-compiler. - This tool is a "native" binary that runs on the build host. - - linux-libc-headers: - Headers needed for the cross-compiler. - - glibc-initial: - An initial version of the Embedded GLIBC needed to bootstrap - nativesdk-glibc. - - nativesdk-glibc: - The Embedded GLIBC needed to bootstrap the - gcc-crosssdk. - - gcc-crosssdk: - The final stage of the bootstrap process for the - relocatable cross-compiler. - The gcc-crosssdk is a transitory compiler - and never leaves the build host. - Its purpose is to help in the bootstrap process to create the - eventual relocatable gcc-cross-canadian - compiler, which is relocatable. - This tool is also a "native" package (i.e. it is - designed to run on the build host). - - gcc-cross-canadian: - The final relocatable cross-compiler. - When run on the - SDKMACHINE, - this tool - produces executable code that runs on the target device. - Only one cross-canadian compiler is produced per architecture - since they can be targeted at different processor optimizations - using configurations passed to the compiler through the - compile commands. - This circumvents the need for multiple compilers and thus - reduces the size of the toolchains. - - - - - - For information on advantages gained when building a - cross-development toolchain installer, see the - "Building an SDK Installer" - section in the Yocto Project Application Development and the - Extensible Software Development Kit (eSDK) manual. - -
-
Shared State Cache -- cgit v1.2.3-54-g00ecf