1 files changed, 216 insertions, 0 deletions
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 @@
        </section>
    </section>
+    <section id="cross-development-toolchain-generation">
+        <title>Cross-Development Toolchain Generation</title>
+        <para>
+            The Yocto Project does most of the work for you when it comes to
+            creating
+            <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchains</ulink>.
+            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
+            <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+            manual.
+        </para>
+        <para>
+            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.
+        </para>
+        <para>
+            The following figure shows a high-level build environment regarding
+            toolchain construction and use.
+        </para>
+        <para>
+            <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" />
+        </para>
+        <para>
+            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 <filename>gcc</filename> compiler to bootstrap a
+            cross-compiler named <filename>gcc-cross</filename>.
+            The <filename>gcc-cross</filename> compiler is what BitBake uses to
+            compile source files when creating the target image.
+            You can think of <filename>gcc-cross</filename> simply as an
+            automatically generated cross-compiler that is used internally within
+            BitBake only.
+            <note>
+                The extensible SDK does not use
+                <filename>gcc-cross-canadian</filename> since this SDK
+                ships a copy of the OpenEmbedded build system and the sysroot
+                within it contains <filename>gcc-cross</filename>.
+            </note>
+        </para>
+        <para>
+            The chain of events that occurs when <filename>gcc-cross</filename> is
+            bootstrapped is as follows:
+            <literallayout class='monospaced'>
+     gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime
+            </literallayout>
+            <itemizedlist>
+                <listitem><para>
+                    <filename>gcc</filename>:
+                    The build host's GNU Compiler Collection (GCC).
+                    </para></listitem>
+                <listitem><para>
+                    <filename>binutils-cross</filename>:
+                    The bare minimum binary utilities needed in order to run
+                    the <filename>gcc-cross-initial</filename> phase of the
+                    bootstrap operation.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>gcc-cross-initial</filename>:
+                    An early stage of the bootstrap process for creating
+                    the cross-compiler.
+                    This stage builds enough of the <filename>gcc-cross</filename>,
+                    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).
+                    </para></listitem>
+                <listitem><para>
+                    <filename>linux-libc-headers</filename>:
+                    Headers needed for the cross-compiler.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>glibc-initial</filename>:
+                    An initial version of the Embedded GLIBC needed to bootstrap
+                    <filename>glibc</filename>.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>gcc-cross</filename>:
+                    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.
+                    <note>
+                        If you are replacing this cross compiler toolchain
+                        with a custom version, you must replace
+                        <filename>gcc-cross</filename>.
+                    </note>
+                    This tool is also a "native" package (i.e. it is
+                    designed to run on the build host).
+                    </para></listitem>
+                <listitem><para>
+                    <filename>gcc-runtime</filename>:
+                    Runtime libraries resulting from the toolchain bootstrapping
+                    process.
+                    This tool produces a binary that consists of the
+                    runtime libraries need for the targeted device.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+        <para>
+            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
+            <filename>gcc-cross-canadian</filename>),
+            <filename>binutils-cross-canadian</filename>, and other
+            <filename>nativesdk-*</filename> tools,
+            which are tools native to the SDK (i.e. native to
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_ARCH'><filename>SDK_ARCH</filename></ulink>),
+            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
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>,
+            which might or might not be the same
+            machine as the Build Host.
+            <note>
+                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.
+            </note>
+        </para>
+        <para>
+            Here is the bootstrap process for the relocatable toolchain:
+            <literallayout class='monospaced'>
+     gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers ->
+        glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian
+            </literallayout>
+            <itemizedlist>
+                <listitem><para>
+                    <filename>gcc</filename>:
+                    The build host's GNU Compiler Collection (GCC).
+                    </para></listitem>
+                <listitem><para>
+                    <filename>binutils-crosssdk</filename>:
+                    The bare minimum binary utilities needed in order to run
+                    the <filename>gcc-crosssdk-initial</filename> phase of the
+                    bootstrap operation.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>gcc-crosssdk-initial</filename>:
+                    An early stage of the bootstrap process for creating
+                    the cross-compiler.
+                    This stage builds enough of the
+                    <filename>gcc-crosssdk</filename> 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.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>linux-libc-headers</filename>:
+                    Headers needed for the cross-compiler.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>glibc-initial</filename>:
+                    An initial version of the Embedded GLIBC needed to bootstrap
+                    <filename>nativesdk-glibc</filename>.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>nativesdk-glibc</filename>:
+                    The Embedded GLIBC needed to bootstrap the
+                    <filename>gcc-crosssdk</filename>.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>gcc-crosssdk</filename>:
+                    The final stage of the bootstrap process for the
+                    relocatable cross-compiler.
+                    The <filename>gcc-crosssdk</filename> is a transitory compiler
+                    and never leaves the build host.
+                    Its purpose is to help in the bootstrap process to create the
+                    eventual relocatable <filename>gcc-cross-canadian</filename>
+                    compiler, which is relocatable.
+                    This tool is also a "native" package (i.e. it is
+                    designed to run on the build host).
+                    </para></listitem>
+                <listitem><para>
+                    <filename>gcc-cross-canadian</filename>:
+                    The final relocatable cross-compiler.
+                    When run on the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>,
+                    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.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+        <note>
+            For information on advantages gained when building a
+            cross-development toolchain installer, see the
+            "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
+            section in the Yocto Project Application Development and the
+            Extensible Software Development Kit (eSDK) manual.
+        </note>
+    </section>
    <section id='x32'>
        <title>x32 psABI</title>

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