summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/sdk-appendix-obtain.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/sdk-manual/sdk-appendix-obtain.xml')
-rw-r--r--documentation/sdk-manual/sdk-appendix-obtain.xml444
1 files changed, 0 insertions, 444 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml
deleted file mode 100644
index de7f75e2bb..0000000000
--- a/documentation/sdk-manual/sdk-appendix-obtain.xml
+++ /dev/null
@@ -1,444 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<appendix id='sdk-appendix-obtain'>
7
8<title>Obtaining the SDK</title>
9
10<section id='sdk-locating-pre-built-sdk-installers'>
11 <title>Locating Pre-Built SDK Installers</title>
12
13 <para>
14 You can use existing, pre-built toolchains by locating and running
15 an SDK installer script that ships with the Yocto Project.
16 Using this method, you select and download an architecture-specific
17 SDK installer and then run the script to hand-install the
18 toolchain.
19 </para>
20
21 <para>
22 Follow these steps to locate and hand-install the toolchain:
23 <orderedlist>
24 <listitem><para>
25 <emphasis>Go to the Installers Directory:</emphasis>
26 Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
27 </para></listitem>
28 <listitem><para>
29 <emphasis>Open the Folder for Your Build Host:</emphasis>
30 Open the folder that matches your
31 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>build host</ulink>
32 (i.e. <filename>i686</filename> for 32-bit machines or
33 <filename>x86_64</filename> for 64-bit machines).
34 </para></listitem>
35 <listitem><para>
36 <emphasis>Locate and Download the SDK Installer:</emphasis>
37 You need to find and download the installer appropriate for
38 your build host, target hardware, and image type.
39 </para>
40
41 <para>The installer files (<filename>*.sh</filename>) follow
42 this naming convention:
43 <literallayout class='monospaced'>
44 poky-glibc-<replaceable>host_system</replaceable>-core-image-<replaceable>type</replaceable>-<replaceable>arch</replaceable>-toolchain[-ext]-<replaceable>release</replaceable>.sh
45
46 Where:
47 <replaceable>host_system</replaceable> is a string representing your development system:
48 "i686" or "x86_64"
49
50 <replaceable>type</replaceable> is a string representing the image:
51 "sato" or "minimal"
52
53 <replaceable>arch</replaceable> is a string representing the target architecture:
54 "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2",
55 "mips64", or "ppc7400"
56
57 <replaceable>release</replaceable> is the version of Yocto Project.
58
59 NOTE:
60 The standard SDK installer does not have the "-ext" string as
61 part of the filename.
62
63 </literallayout>
64 The toolchains provided by the Yocto Project are based off of
65 the <filename>core-image-sato</filename> and
66 <filename>core-image-minimal</filename> images and contain
67 libraries appropriate for developing against those images.
68 </para>
69
70 <para>For example, if your build host is a 64-bit x86 system
71 and you need an extended SDK for a 64-bit core2 target, go
72 into the <filename>x86_64</filename> folder and download the
73 following installer:
74 <literallayout class='monospaced'>
75 poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
76 </literallayout>
77 </para></listitem>
78 <listitem><para>
79 <emphasis>Run the Installer:</emphasis>
80 Be sure you have execution privileges and run the installer.
81 Following is an example from the <filename>Downloads</filename>
82 directory:
83 <literallayout class='monospaced'>
84 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
85 </literallayout>
86 During execution of the script, you choose the root location
87 for the toolchain.
88 See the
89 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
90 section and the
91 "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>"
92 section for more information.
93 </para></listitem>
94 </orderedlist>
95 </para>
96</section>
97
98<section id='sdk-building-an-sdk-installer'>
99 <title>Building an SDK Installer</title>
100
101 <para>
102 As an alternative to locating and downloading an SDK installer,
103 you can build the SDK installer.
104 Follow these steps:
105 <orderedlist>
106 <listitem><para>
107 <emphasis>Set Up the Build Environment:</emphasis>
108 Be sure you are set up to use BitBake in a shell.
109 See the
110 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
111 section in the Yocto Project Development Tasks Manual for
112 information on how to get a build host ready that is either a
113 native Linux machine or a machine that uses CROPS.
114 </para></listitem>
115 <listitem><para>
116 <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
117 You need to have a local copy of the Yocto Project
118 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
119 (i.e. a local <filename>poky</filename> repository).
120 See the
121 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
122 and possibly the
123 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
124 and
125 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
126 sections all in the Yocto Project Development Tasks Manual for
127 information on how to clone the <filename>poky</filename>
128 repository and check out the appropriate branch for your work.
129 </para></listitem>
130 <listitem><para>
131 <emphasis>Initialize the Build Environment:</emphasis>
132 While in the root directory of the Source Directory (i.e.
133 <filename>poky</filename>), run the
134 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
135 environment setup script to define the OpenEmbedded
136 build environment on your build host.
137 <literallayout class='monospaced'>
138 $ source &OE_INIT_FILE;
139 </literallayout>
140 Among other things, the script creates the
141 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
142 which is <filename>build</filename> in this case
143 and is located in the Source Directory.
144 After the script runs, your current working directory
145 is set to the <filename>build</filename> directory.
146 </para></listitem>
147 <listitem><para>
148 <emphasis>Make Sure You Are Building an Installer for the Correct Machine:</emphasis>
149 Check to be sure that your
150 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
151 variable in the <filename>local.conf</filename> file in your
152 Build Directory matches the architecture for which you are
153 building.
154 </para></listitem>
155 <listitem><para>
156 <emphasis>Make Sure Your SDK Machine is Correctly Set:</emphasis>
157 If you are building a toolchain designed to run on an
158 architecture that differs from your current development host
159 machine (i.e. the build host), be sure that the
160 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
161 variable in the <filename>local.conf</filename> file in your
162 Build Directory is correctly set.
163 <note>
164 If you are building an SDK installer for the Extensible
165 SDK, the <filename>SDKMACHINE</filename> value must be
166 set for the architecture of the machine you are using to
167 build the installer.
168 If <filename>SDKMACHINE</filename> is not set appropriately,
169 the build fails and provides an error message similar to
170 the following:
171 <literallayout class='monospaced'>
172 The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is
173 set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64).
174 Unable to continue.
175 </literallayout>
176 </note>
177 </para></listitem>
178 <listitem><para>
179 <emphasis>Build the SDK Installer:</emphasis>
180 To build the SDK installer for a standard SDK and populate
181 the SDK image, use the following command form.
182 Be sure to replace <replaceable>image</replaceable> with
183 an image (e.g. "core-image-sato"):
184 <literallayout class='monospaced'>
185 $ bitbake <replaceable>image</replaceable> -c populate_sdk
186 </literallayout>
187 You can do the same for the extensible SDK using this command
188 form:
189 <literallayout class='monospaced'>
190 $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext
191 </literallayout>
192 These commands produce an SDK installer that contains the
193 sysroot that matches your target root filesystem.</para>
194
195 <para>When the <filename>bitbake</filename> command completes,
196 the SDK installer will be in
197 <filename>tmp/deploy/sdk</filename> in the Build Directory.
198 <note><title>Notes</title>
199 <itemizedlist>
200 <listitem><para>
201 By default, the previous BitBake command does not
202 build static binaries.
203 If you want to use the toolchain to build these
204 types of libraries, you need to be sure your SDK
205 has the appropriate static development libraries.
206 Use the
207 <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>
208 variable inside your <filename>local.conf</filename>
209 file before building the SDK installer.
210 Doing so ensures that the eventual SDK installation
211 process installs the appropriate library packages
212 as part of the SDK.
213 Following is an example using
214 <filename>libc</filename> static development
215 libraries:
216 <literallayout class='monospaced'>
217 TOOLCHAIN_TARGET_TASK_append = " libc-staticdev"
218 </literallayout>
219 </para></listitem>
220 </itemizedlist>
221 </note>
222 </para></listitem>
223 <listitem><para>
224 <emphasis>Run the Installer:</emphasis>
225 You can now run the SDK installer from
226 <filename>tmp/deploy/sdk</filename> in the Build Directory.
227 Following is an example:
228 <literallayout class='monospaced'>
229 $ cd ~/poky/build/tmp/deploy/sdk
230 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
231 </literallayout>
232 During execution of the script, you choose the root location
233 for the toolchain.
234 See the
235 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
236 section and the
237 "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>"
238 section for more information.
239 </para></listitem>
240 </orderedlist>
241 </para>
242</section>
243
244<section id='sdk-extracting-the-root-filesystem'>
245 <title>Extracting the Root Filesystem</title>
246
247 <para>
248 After installing the toolchain, for some use cases you
249 might need to separately extract a root filesystem:
250 <itemizedlist>
251 <listitem><para>
252 You want to boot the image using NFS.
253 </para></listitem>
254 <listitem><para>
255 You want to use the root filesystem as the
256 target sysroot.
257 </para></listitem>
258 <listitem><para>
259 You want to develop your target application
260 using the root filesystem as the target sysroot.
261 </para></listitem>
262 </itemizedlist>
263 </para>
264
265 <para>
266 Follow these steps to extract the root filesystem:
267 <orderedlist>
268 <listitem><para>
269 <emphasis>Locate and Download the Tarball for the Pre-Built
270 Root Filesystem Image File:</emphasis>
271 You need to find and download the root filesystem image
272 file that is appropriate for your target system.
273 These files are kept in machine-specific folders in the
274 <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/machines/'>Index of Releases</ulink>
275 in the "machines" directory.</para>
276
277 <para>The machine-specific folders of the "machines" directory
278 contain tarballs (<filename>*.tar.bz2</filename>) for supported
279 machines.
280 These directories also contain flattened root filesystem
281 image files (<filename>*.ext4</filename>), which you can use
282 with QEMU directly.</para>
283
284 <para>The pre-built root filesystem image files
285 follow these naming conventions:
286 <literallayout class='monospaced'>
287<!--
288 core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>-<replaceable>date_time</replaceable>.rootfs.tar.bz2
289-->
290 core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>.tar.bz2
291
292 Where:
293 <replaceable>profile</replaceable> is the filesystem image's profile:
294 lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs,
295 sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on
296 these types of image profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
297 the Yocto Project Reference Manual.
298
299 <replaceable>arch</replaceable> is a string representing the target architecture:
300 beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb,
301 genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*.
302
303<!-->
304 <replaceable>date_time</replaceable> is a date and time stamp.
305-->
306
307 </literallayout>
308 The root filesystems provided by the Yocto Project are based
309 off of the <filename>core-image-sato</filename> and
310 <filename>core-image-minimal</filename> images.
311 </para>
312
313 <para>For example, if you plan on using a BeagleBone device
314 as your target hardware and your image is a
315 <filename>core-image-sato-sdk</filename>
316 image, you can download the following file:
317 <literallayout class='monospaced'>
318 core-image-sato-sdk-beaglebone-yocto.tar.bz2
319 </literallayout>
320 </para></listitem>
321 <listitem><para>
322 <emphasis>Initialize the Cross-Development Environment:</emphasis>
323 You must <filename>source</filename> the cross-development
324 environment setup script to establish necessary environment
325 variables.</para>
326
327 <para>This script is located in the top-level directory in
328 which you installed the toolchain (e.g.
329 <filename>poky_sdk</filename>).</para>
330
331 <para>Following is an example based on the toolchain installed
332 in the
333 "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>"
334 section:
335 <literallayout class='monospaced'>
336 $ source ~/poky_sdk/environment-setup-core2-64-poky-linux
337 </literallayout>
338 </para></listitem>
339 <listitem><para>
340 <emphasis>Extract the Root Filesystem:</emphasis>
341 Use the <filename>runqemu-extract-sdk</filename> command
342 and provide the root filesystem image.</para>
343
344 <para>Following is an example command that extracts the root
345 filesystem from a previously built root filesystem image that
346 was downloaded from the
347 <ulink url='&YOCTO_DOCS_OM_URL;#index-downloads'>Index of Releases</ulink>.
348 This command extracts the root filesystem into the
349 <filename>core2-64-sato</filename> directory:
350 <literallayout class='monospaced'>
351 $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
352 </literallayout>
353 You could now point to the target sysroot at
354 <filename>beablebone-sato</filename>.
355 </para></listitem>
356 </orderedlist>
357 </para>
358</section>
359
360<section id='sdk-installed-standard-sdk-directory-structure'>
361 <title>Installed Standard SDK Directory Structure</title>
362
363 <para>
364 The following figure shows the resulting directory structure after
365 you install the Standard SDK by running the <filename>*.sh</filename>
366 SDK installation script:
367 </para>
368
369 <para>
370 <imagedata fileref="figures/sdk-installed-standard-sdk-directory.png" scale="80" align="center" />
371 </para>
372
373 <para>
374 The installed SDK consists of an environment setup script for the SDK,
375 a configuration file for the target, a version file for the target,
376 and the root filesystem (<filename>sysroots</filename>) needed to
377 develop objects for the target system.
378 </para>
379
380 <para>
381 Within the figure, italicized text is used to indicate replaceable
382 portions of the file or directory name.
383 For example,
384 <replaceable>install_dir</replaceable>/<replaceable>version</replaceable>
385 is the directory where the SDK is installed.
386 By default, this directory is <filename>/opt/poky/</filename>.
387 And, <replaceable>version</replaceable> represents the specific
388 snapshot of the SDK (e.g. <filename>&DISTRO;</filename>).
389 Furthermore, <replaceable>target</replaceable> represents the target
390 architecture (e.g. <filename>i586</filename>) and
391 <replaceable>host</replaceable> represents the development system's
392 architecture (e.g. <filename>x86_64</filename>).
393 Thus, the complete names of the two directories within the
394 <filename>sysroots</filename> could be
395 <filename>i586-poky-linux</filename> and
396 <filename>x86_64-pokysdk-linux</filename> for the target and host,
397 respectively.
398 </para>
399</section>
400
401<section id='sdk-installed-extensible-sdk-directory-structure'>
402 <title>Installed Extensible SDK Directory Structure</title>
403
404 <para>
405 The following figure shows the resulting directory structure after
406 you install the Extensible SDK by running the <filename>*.sh</filename>
407 SDK installation script:
408 </para>
409
410 <para>
411 <imagedata fileref="figures/sdk-installed-extensible-sdk-directory.png" scale="80" align="center" />
412 </para>
413
414 <para>
415 The installed directory structure for the extensible SDK is quite
416 different than the installed structure for the standard SDK.
417 The extensible SDK does not separate host and target parts in the
418 same manner as does the standard SDK.
419 The extensible SDK uses an embedded copy of the OpenEmbedded
420 build system, which has its own sysroots.
421 </para>
422
423 <para>
424 Of note in the directory structure are an environment setup script
425 for the SDK, a configuration file for the target, a version file for
426 the target, and log files for the OpenEmbedded build system
427 preparation script run by the installer and BitBake.
428 </para>
429
430 <para>
431 Within the figure, italicized text is used to indicate replaceable
432 portions of the file or directory name.
433 For example,
434 <replaceable>install_dir</replaceable> is the directory where the SDK
435 is installed, which is <filename>poky_sdk</filename> by default, and
436 <replaceable>target</replaceable> represents the target
437 architecture (e.g. <filename>i586</filename>).
438 </para>
439</section>
440
441</appendix>
442<!--
443vim: expandtab tw=80 ts=4
444-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 09:27:53 +0000