summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/technical-details.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-01-10 13:01:25 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:28 +0000
commit6bf7b263ff2ada9dd1335fcc900820af32dc99c1 (patch)
tree0db973ae6fe3aadcc9ebb0572178eefe06e5327e /documentation/ref-manual/technical-details.xml
parent707224b57a9d646bbeb619bfe1054e9e4c021b23 (diff)
downloadpoky-6bf7b263ff2ada9dd1335fcc900820af32dc99c1.tar.gz
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 <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/technical-details.xml')
-rw-r--r--documentation/ref-manual/technical-details.xml201
1 files changed, 0 insertions, 201 deletions
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
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-10 01:42:12 +0000