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 0000000000..d36670a198
--- /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 0000000000..d36670a198
--- /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 0634f5702d..f17291f2cb 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -153,6 +153,180 @@
    </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_DEV_URL;#cross-development-toolchain'>cross-development toolchains</ulink>.
+        This section provides some technical background information on how
+        cross-development toolchains are created and used.
+        For more information on these toolchain, you can also see the
+        <ulink url='&YOCTO_DOCS_ADT_URL;'>the Yocto Project Application Developer's Guide</ulink>.
+    </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.
+    </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 -> eglibc-initial -> eglibc -> 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>eglibc-initial</filename>:
+                An initial version of the Embedded GLIBC needed to bootstrap
+                <filename>eglibc</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 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
+        <filename>SDKMACHINE</filename>, 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 -> eglibc-initial -> nativesdk-eglibc -> 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>eglibc-initial</filename>:
+                An initial version of the Embedded GLIBC needed to bootstrap
+                <filename>nativesdk-eglibc</filename>.
+                </para></listitem>
+            <listitem><para><filename>nativesdk-eglibc</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 <filename>SDKMACHINE</filename>, this tool
+                produces executable code that runs on the target device.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
 <section id="shared-state-cache">
    <title>Shared State Cache</title>

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 0000000000..d36670a198 --- /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 0000000000..d36670a198 --- /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 0634f5702d..f17291f2cb 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>
		158
		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>
		168
		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>
		176
		177	<para>
		178	The following figure shows a high-level build environment regarding
		179	toolchain construction and use.
		180	</para>
		181
		182	<para>
		183	<imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" />
		184	</para>
		185
		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>
		199
		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>
		253
		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>
		275
		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>
		328	</section>
		329
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