summaryrefslogtreecommitdiffstats
path: root/documentation/adt-manual/adt-prepare.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/adt-manual/adt-prepare.xml')
-rw-r--r--documentation/adt-manual/adt-prepare.xml671
1 files changed, 671 insertions, 0 deletions
diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
new file mode 100644
index 0000000000..89ef09fb24
--- /dev/null
+++ b/documentation/adt-manual/adt-prepare.xml
@@ -0,0 +1,671 @@
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
5<chapter id='adt-prepare'>
6
7<title>Preparing for Application Development</title>
8
9<para>
10 In order to develop applications, you need set up your host development system.
11 Several ways exist that allow you to install cross-development tools, QEMU, the
12 Eclipse Yocto Plug-in, and other tools.
13 This chapter describes how to prepare for application development.
14</para>
15
16<section id='installing-the-adt'>
17 <title>Installing the ADT and Toolchains</title>
18
19 <para>
20 The following list describes installation methods that set up varying degrees of tool
21 availability on your system.
22 Regardless of the installation method you choose,
23 you must <filename>source</filename> the cross-toolchain
24 environment setup script before you use a toolchain.
25 See the "<link linkend='setting-up-the-cross-development-environment'>Setting Up the
26 Cross-Development Environment</link>" section for more information.
27 </para>
28
29 <note>
30 <para>Avoid mixing installation methods when installing toolchains for different architectures.
31 For example, avoid using the ADT Installer to install some toolchains and then hand-installing
32 cross-development toolchains by running the toolchain installer for different architectures.
33 Mixing installation methods can result in situations where the ADT Installer becomes
34 unreliable and might not install the toolchain.</para>
35 <para>If you must mix installation methods, you might avoid problems by deleting
36 <filename>/var/lib/opkg</filename>, thus purging the <filename>opkg</filename> package
37 metadata</para>
38 </note>
39
40 <para>
41 <itemizedlist>
42 <listitem><para><emphasis>Use the ADT installer script:</emphasis>
43 This method is the recommended way to install the ADT because it
44 automates much of the process for you.
45 For example, you can configure the installation to install the QEMU emulator
46 and the user-space NFS, specify which root filesystem profiles to download,
47 and define the target sysroot location.</para></listitem>
48 <listitem><para><emphasis>Use an existing toolchain:</emphasis>
49 Using this method, you select and download an architecture-specific
50 toolchain installer and then run the script to hand-install the toolchain.
51 If you use this method, you just get the cross-toolchain and QEMU - you do not
52 get any of the other mentioned benefits had you run the ADT Installer script.</para></listitem>
53 <listitem><para><emphasis>Use the toolchain from within the Build Directory:</emphasis>
54 If you already have a
55 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
56 you can build the cross-toolchain within the directory.
57 However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you
58 do not get any of the other benefits without taking separate steps.</para></listitem>
59 </itemizedlist>
60 </para>
61
62 <section id='using-the-adt-installer'>
63 <title>Using the ADT Installer</title>
64
65 <para>
66 To run the ADT Installer, you need to get the ADT Installer tarball, be sure
67 you have the necessary host development packages that support the ADT Installer,
68 and then run the ADT Installer Script.
69 </para>
70
71 <para>
72 For a list of the host packages needed to support ADT installation and use, see the
73 "ADT Installer Extras" lists in the
74 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" section
75 of the Yocto Project Reference Manual.
76 </para>
77
78 <section id='getting-the-adt-installer-tarball'>
79 <title>Getting the ADT Installer Tarball</title>
80
81 <para>
82 The ADT Installer is contained in the ADT Installer tarball.
83 You can get the tarball using either of these methods:
84 <itemizedlist>
85 <listitem><para><emphasis>Download the Tarball:</emphasis>
86 You can download the tarball from
87 <ulink url='&YOCTO_ADTINSTALLER_DL_URL;'></ulink> into
88 any directory.</para></listitem>
89 <listitem><para><emphasis>Build the Tarball:</emphasis>
90 You can use
91 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
92 to generate the tarball inside an existing
93 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
94 </para>
95 <para>If you use BitBake to generate the ADT Installer
96 tarball, you must <filename>source</filename> the
97 environment setup script
98 (<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
99 or
100 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
101 located in the Source Directory before running the
102 <filename>bitbake</filename> command that creates the
103 tarball.</para>
104 <para>The following example commands establish
105 the
106 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
107 check out the current release branch, set up the
108 build environment while also creating the default
109 Build Directory, and run the
110 <filename>bitbake</filename> command that results in the
111 tarball
112 <filename>poky/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>:
113 <note>
114 Before using BitBake to build the ADT tarball, be
115 sure to make sure your
116 <filename>local.conf</filename> file is properly
117 configured.
118 </note>
119 <literallayout class='monospaced'>
120 $ cd ~
121 $ git clone git://git.yoctoproject.org/poky
122 $ cd poky
123 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
124 $ source &OE_INIT_FILE;
125 $ bitbake adt-installer
126 </literallayout></para></listitem>
127 </itemizedlist>
128 </para>
129 </section>
130
131 <section id='configuring-and-running-the-adt-installer-script'>
132 <title>Configuring and Running the ADT Installer Script</title>
133
134 <para>
135 Before running the ADT Installer script, you need to unpack the tarball.
136 You can unpack the tarball in any directory you wish.
137 For example, this command copies the ADT Installer tarball from where
138 it was built into the home directory and then unpacks the tarball into
139 a top-level directory named <filename>adt-installer</filename>:
140 <literallayout class='monospaced'>
141 $ cd ~
142 $ cp poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME
143 $ tar -xjf adt_installer.tar.bz2
144 </literallayout>
145 Unpacking it creates the directory <filename>adt-installer</filename>,
146 which contains the ADT Installer script (<filename>adt_installer</filename>)
147 and its configuration file (<filename>adt_installer.conf</filename>).
148 </para>
149
150 <para>
151 Before you run the script, however, you should examine the ADT Installer configuration
152 file and be sure you are going to get what you want.
153 Your configurations determine which kernel and filesystem image are downloaded.
154 </para>
155
156 <para>
157 The following list describes the configurations you can define for the ADT Installer.
158 For configuration values and restrictions, see the comments in
159 the <filename>adt-installer.conf</filename> file:
160
161 <itemizedlist>
162 <listitem><para><filename>YOCTOADT_REPO</filename>: This area
163 includes the IPKG-based packages and the root filesystem upon which
164 the installation is based.
165 If you want to set up your own IPKG repository pointed to by
166 <filename>YOCTOADT_REPO</filename>, you need to be sure that the
167 directory structure follows the same layout as the reference directory
168 set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.
169 Also, your repository needs to be accessible through HTTP.</para></listitem>
170 <listitem><para><filename>YOCTOADT_TARGETS</filename>: The machine
171 target architectures for which you want to set up cross-development
172 environments.</para></listitem>
173 <listitem><para><filename>YOCTOADT_QEMU</filename>: Indicates whether
174 or not to install the emulator QEMU.</para></listitem>
175 <listitem><para><filename>YOCTOADT_NFS_UTIL</filename>: Indicates whether
176 or not to install user-mode NFS.
177 If you plan to use the Eclipse IDE Yocto plug-in against QEMU,
178 you should install NFS.
179 <note>To boot QEMU images using our userspace NFS server, you need
180 to be running <filename>portmap</filename> or <filename>rpcbind</filename>.
181 If you are running <filename>rpcbind</filename>, you will also need to add the
182 <filename>-i</filename> option when <filename>rpcbind</filename> starts up.
183 Please make sure you understand the security implications of doing this.
184 You might also have to modify your firewall settings to allow
185 NFS booting to work.</note></para></listitem>
186 <listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>: The root
187 filesystem images you want to download from the
188 <filename>YOCTOADT_IPKG_REPO</filename> repository.</para></listitem>
189 <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename>: The
190 particular root filesystem used to extract and create the target sysroot.
191 The value of this variable must have been specified with
192 <filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>.
193 For example, if you downloaded both <filename>minimal</filename> and
194 <filename>sato-sdk</filename> images by setting
195 <filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>
196 to "minimal sato-sdk", then <filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>
197 must be set to either "minimal" or "sato-sdk".
198 </para></listitem>
199 <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename>: The
200 location on the development host where the target sysroot is created.
201 </para></listitem>
202 </itemizedlist>
203 </para>
204
205 <para>
206 After you have configured the <filename>adt_installer.conf</filename> file,
207 run the installer using the following command:
208 <literallayout class='monospaced'>
209 $ cd adt-installer
210 $ ./adt_installer
211 </literallayout>
212 Once the installer begins to run, you are asked to enter the
213 location for cross-toolchain installation.
214 The default location is
215 <filename>/opt/poky/&lt;release&gt;</filename>.
216 After either accepting the default location or selecting your
217 own location, you are prompted to run the installation script
218 interactively or in silent mode.
219 If you want to closely monitor the installation,
220 choose “I” for interactive mode rather than “S” for silent mode.
221 Follow the prompts from the script to complete the installation.
222 </para>
223
224 <para>
225 Once the installation completes, the ADT, which includes the
226 cross-toolchain, is installed in the selected installation
227 directory.
228 You will notice environment setup files for the cross-toolchain
229 in the installation directory, and image tarballs in the
230 <filename>adt-installer</filename> directory according to your
231 installer configurations, and the target sysroot located
232 according to the
233 <filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename>
234 variable also in your configuration file.
235 </para>
236 </section>
237 </section>
238
239 <section id='using-an-existing-toolchain-tarball'>
240 <title>Using a Cross-Toolchain Tarball</title>
241
242 <para>
243 If you want to simply install a cross-toolchain by hand, you can
244 do so by running the toolchain installer.
245 The installer includes the pre-built cross-toolchain, the
246 <filename>runqemu</filename> script, and support files.
247 If you use this method to install the cross-toolchain, you
248 might still need to install the target sysroot by installing and
249 extracting it separately.
250 For information on how to install the sysroot, see the
251 "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.
252 </para>
253
254 <para>
255 Follow these steps:
256 <orderedlist>
257 <listitem><para><emphasis>Get your toolchain installer using one of the following methods:</emphasis>
258 <itemizedlist>
259 <listitem><para>Go to
260 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
261 and find the folder that matches your host
262 development system (i.e. <filename>i686</filename>
263 for 32-bit machines or <filename>x86_64</filename>
264 for 64-bit machines).</para>
265 <para>Go into that folder and download the toolchain
266 installer whose name includes the appropriate target
267 architecture.
268 The toolchains provided by the Yocto Project
269 are based off of the
270 <filename>core-image-sato</filename> image and
271 contain libraries appropriate for developing
272 against that image.
273 For example, if your host development system is a
274 64-bit x86 system and you are going to use
275 your cross-toolchain for a 32-bit x86
276 target, go into the <filename>x86_64</filename>
277 folder and download the following installer:
278 <literallayout class='monospaced'>
279 poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
280 </literallayout></para></listitem>
281 <listitem><para>Build your own toolchain installer.
282 For cases where you cannot use an installer
283 from the download area, you can build your own as
284 described in the
285 "<link linkend='optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</link>"
286 section.</para></listitem>
287 </itemizedlist></para></listitem>
288 <listitem><para><emphasis>Once you have the installer, run it to install the toolchain:</emphasis>
289 <note>
290 You must change the permissions on the toolchain
291 installer script so that it is executable.
292 </note></para>
293 <para>The following command shows how to run the installer
294 given a toolchain tarball for a 64-bit x86 development host
295 system and a 32-bit x86 target architecture.
296 The example assumes the toolchain installer is located
297 in <filename>~/Downloads/</filename>.
298 <literallayout class='monospaced'>
299 $ ~/Downloads/poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
300 </literallayout>
301 The first thing the installer prompts you for is the
302 directory into which you want to install the toolchain.
303 The default directory used is
304 <filename>/opt/poky/&DISTRO;</filename>.
305 If you do not have write permissions for the directory
306 into which you are installing the toolchain, the
307 toolchain installer notifies you and exits.
308 Be sure you have write permissions in the directory and
309 run the installer again.</para>
310 <para>When the script finishes, the cross-toolchain is
311 installed.
312 You will notice environment setup files for the
313 cross-toolchain in the installation directory.
314 </para></listitem>
315 </orderedlist>
316 </para>
317 </section>
318
319 <section id='using-the-toolchain-from-within-the-build-tree'>
320 <title>Using BitBake and the Build Directory</title>
321
322 <para>
323 A final way of making the cross-toolchain available is to use BitBake
324 to generate the toolchain within an existing
325 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
326 This method does not install the toolchain into the default
327 <filename>/opt</filename> directory.
328 As with the previous method, if you need to install the target sysroot, you must
329 do that separately as well.
330 </para>
331
332 <para>
333 Follow these steps to generate the toolchain into the Build Directory:
334 <orderedlist>
335 <listitem><para><emphasis>Set up the Build Environment:</emphasis>
336 Source the OpenEmbedded build environment setup
337 script (i.e.
338 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
339 or
340 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
341 located in the
342 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
343 </para></listitem>
344 <listitem><para><emphasis>Check your Local Configuration File:</emphasis>
345 At this point, you should be sure that the
346 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable
347 in the <filename>local.conf</filename> file found in the
348 <filename>conf</filename> directory of the Build Directory
349 is set for the target architecture.
350 Comments within the <filename>local.conf</filename> file
351 list the values you can use for the
352 <filename>MACHINE</filename> variable.
353 <note>
354 You can populate the Build Directory with the
355 cross-toolchains for more than a single architecture.
356 You just need to edit the <filename>MACHINE</filename>
357 variable in the <filename>local.conf</filename> file and
358 re-run the <filename>bitbake</filename> command.
359 </note></para></listitem>
360 <listitem><para><emphasis>Generate the Cross-Toolchain:</emphasis>
361 Run <filename>bitbake meta-ide-support</filename> to
362 complete the cross-toolchain generation.
363 Once the <filename>bitbake</filename> command finishes,
364 the cross-toolchain is
365 generated and populated within the Build Directory.
366 You will notice environment setup files for the
367 cross-toolchain that contain the string
368 "<filename>environment-setup</filename>" in the
369 Build Directory's <filename>tmp</filename> folder.</para>
370 <para>Be aware that when you use this method to install the
371 toolchain, you still need to separately extract and install
372 the sysroot filesystem.
373 For information on how to do this, see the
374 "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.
375 </para></listitem>
376 </orderedlist>
377 </para>
378 </section>
379</section>
380
381<section id='setting-up-the-cross-development-environment'>
382 <title>Setting Up the Cross-Development Environment</title>
383
384 <para>
385 Before you can develop using the cross-toolchain, you need to set up the
386 cross-development environment by sourcing the toolchain's environment setup script.
387 If you used the ADT Installer or hand-installed cross-toolchain,
388 then you can find this script in the directory you chose for installation.
389 For this release, the default installation directory is
390 <filename>&YOCTO_ADTPATH_DIR;</filename>.
391 If you installed the toolchain in the
392 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
393 you can find the environment setup
394 script for the toolchain in the Build Directory's <filename>tmp</filename> directory.
395 </para>
396
397 <para>
398 Be sure to run the environment setup script that matches the
399 architecture for which you are developing.
400 Environment setup scripts begin with the string
401 "<filename>environment-setup</filename>" and include as part of their
402 name the architecture.
403 For example, the toolchain environment setup script for a 64-bit
404 IA-based architecture installed in the default installation directory
405 would be the following:
406 <literallayout class='monospaced'>
407 &YOCTO_ADTPATH_DIR;/environment-setup-x86_64-poky-linux
408 </literallayout>
409 </para>
410</section>
411
412<section id='securing-kernel-and-filesystem-images'>
413 <title>Securing Kernel and Filesystem Images</title>
414
415 <para>
416 You will need to have a kernel and filesystem image to boot using your
417 hardware or the QEMU emulator.
418 Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem
419 as the target sysroot, you need to extract the root filesystem.
420 </para>
421
422 <section id='getting-the-images'>
423 <title>Getting the Images</title>
424
425 <para>
426 To get the kernel and filesystem images, you either have to build them or download
427 pre-built versions.
428 You can find examples for both these situations in the
429 "<ulink url='&YOCTO_DOCS_QS_URL;#test-run'>A Quick Test Run</ulink>" section of
430 the Yocto Project Quick Start.
431 </para>
432
433 <para>
434 The Yocto Project ships basic kernel and filesystem images for several
435 architectures (<filename>x86</filename>, <filename>x86-64</filename>,
436 <filename>mips</filename>, <filename>powerpc</filename>, and <filename>arm</filename>)
437 that you can use unaltered in the QEMU emulator.
438 These kernel images reside in the release
439 area - <ulink url='&YOCTO_MACHINES_DL_URL;'></ulink>
440 and are ideal for experimentation using Yocto Project.
441 For information on the image types you can build using the OpenEmbedded build system,
442 see the
443 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
444 the Yocto Project Reference Manual.
445 </para>
446
447 <para>
448 If you are planning on developing against your image and you are not
449 building or using one of the Yocto Project development images
450 (e.g. <filename>core-image-*-dev</filename>), you must be sure to
451 include the development packages as part of your image recipe.
452 </para>
453
454 <para>
455 Furthermore, if you plan on remotely deploying and debugging your
456 application from within the
457 Eclipse IDE, you must have an image that contains the Yocto Target Communication
458 Framework (TCF) agent (<filename>tcf-agent</filename>).
459 By default, the Yocto Project provides only one type of pre-built
460 image that contains the <filename>tcf-agent</filename>.
461 And, those images are SDK (e.g.<filename>core-image-sato-sdk</filename>).
462 </para>
463
464 <para>
465 If you want to use a different image type that contains the <filename>tcf-agent</filename>,
466 you can do so one of two ways:
467 <itemizedlist>
468 <listitem><para>Modify the <filename>conf/local.conf</filename> configuration in
469 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
470 and then rebuild the image.
471 With this method, you need to modify the
472 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
473 variable to have the value of "tools-debug" before rebuilding the image.
474 Once the image is rebuilt, the <filename>tcf-agent</filename> will be included
475 in the image and is launched automatically after the boot.</para></listitem>
476 <listitem><para>Manually build the <filename>tcf-agent</filename>.
477 To build the agent, follow these steps:
478 <orderedlist>
479 <listitem><para>Be sure the ADT is installed as described in the
480 "<link linkend='installing-the-adt'>Installing the ADT and Toolchains</link>" section.
481 </para></listitem>
482 <listitem><para>Set up the cross-development environment as described in the
483 "<link linkend='setting-up-the-cross-development-environment'>Setting
484 Up the Cross-Development Environment</link>" section.</para></listitem>
485 <listitem><para>Get the <filename>tcf-agent</filename> source code using
486 the following commands:
487 <literallayout class='monospaced'>
488 $ git clone http://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git
489 $ cd org.eclipse.tcf.agent/agent
490 </literallayout></para></listitem>
491 <listitem><para>Locate the
492 <filename>Makefile.inc</filename> file inside the
493 <filename>agent</filename> folder and modify it
494 for the cross-compilation environment by setting the
495 <filename>OPSYS</filename> and
496 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
497 variables according to your target.
498 </para></listitem>
499 <listitem><para>Use the cross-development tools to build the
500 <filename>tcf-agent</filename>.
501 Before you "Make" the file, be sure your cross-tools are set up first.
502 See the "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
503 section for information on how to make sure the cross-tools are set up
504 correctly.</para>
505 <para>If the build is successful, the <filename>tcf-agent</filename> output will
506 be <filename>obj/$(OPSYS)/$(MACHINE)/Debug/agent</filename>.</para></listitem>
507 <listitem><para>Deploy the agent into the image's root filesystem.</para></listitem>
508 </orderedlist>
509 </para></listitem>
510 </itemizedlist>
511 </para>
512 </section>
513
514 <section id='extracting-the-root-filesystem'>
515 <title>Extracting the Root Filesystem</title>
516
517 <para>
518 If you install your toolchain by hand or build it using BitBake and
519 you need a root filesystem, you need to extract it separately.
520 If you use the ADT Installer to install the ADT, the root
521 filesystem is automatically extracted and installed.
522 </para>
523
524 <para>
525 Here are some cases where you need to extract the root filesystem:
526 <itemizedlist>
527 <listitem><para>You want to boot the image using NFS.
528 </para></listitem>
529 <listitem><para>You want to use the root filesystem as the
530 target sysroot.
531 For example, the Eclipse IDE environment with the Eclipse
532 Yocto Plug-in installed allows you to use QEMU to boot
533 under NFS.</para></listitem>
534 <listitem><para>You want to develop your target application
535 using the root filesystem as the target sysroot.
536 </para></listitem>
537 </itemizedlist>
538 </para>
539
540 <para>
541 To extract the root filesystem, first <filename>source</filename>
542 the cross-development environment setup script.
543 If you built the toolchain in the Build Directory, you will find
544 the toolchain environment script in the
545 <filename>tmp</filename> directory.
546 If you installed the toolchain by hand, the environment setup
547 script is located in <filename>/opt/poky/&DISTRO;</filename>.
548 </para>
549
550 <para>
551 After sourcing the environment script, use the
552 <filename>runqemu-extract-sdk</filename> command and provide the
553 filesystem image.
554 </para>
555
556 <para>
557 Following is an example.
558 The second command sets up the environment.
559 In this case, the setup script is located in the
560 <filename>/opt/poky/&DISTRO;</filename> directory.
561 The third command extracts the root filesystem from a previously
562 built filesystem that is located in the
563 <filename>~/Downloads</filename> directory.
564 Furthermore, this command extracts the root filesystem into the
565 <filename>qemux86-sato</filename> directory:
566 <literallayout class='monospaced'>
567 $ cd ~
568 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
569 $ runqemu-extract-sdk \
570 ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \
571 $HOME/qemux86-sato
572 </literallayout>
573 You could now point to the target sysroot at
574 <filename>qemux86-sato</filename>.
575 </para>
576 </section>
577</section>
578
579<section id='optionally-building-a-toolchain-installer'>
580 <title>Optionally Building a Toolchain Installer</title>
581
582 <para>
583 As an alternative to locating and downloading a toolchain installer,
584 you can build the toolchain installer one of two ways if you have a
585 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
586 <itemizedlist>
587 <listitem><para>
588 Use <filename>bitbake meta-toolchain</filename>.
589 This method requires you to still install the target
590 sysroot by installing and extracting it separately.
591 For information on how to install the sysroot, see the
592 "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
593 section.
594 </para></listitem>
595 <listitem><para>
596 Use <filename>bitbake &lt;image&gt; -c populate_sdk</filename>.
597 This method has significant advantages over the previous method
598 because it results in a toolchain installer that contains the
599 sysroot that matches your target root filesystem.
600 </para>
601
602 <para>Another powerful feature is that the toolchain is
603 completely self-contained.
604 The binaries are linked against their own copy of
605 <filename>libc</filename>, which results in no dependencies
606 on the target system.
607 To achieve this, the pointer to the dynamic loader is
608 configured at install time since that path cannot be dynamically
609 altered.
610 This is the reason for a wrapper around the
611 <filename>populate_sdk</filename> archive.</para>
612
613 <para>Another feature is that only one set of cross-canadian
614 toolchain binaries are produced per architecture.
615 This feature takes advantage of the fact that the target
616 hardware can be passed to <filename>gcc</filename> as a set of
617 compiler options.
618 Those options are set up by the environment script and
619 contained in variables like CC and LD.
620 This reduces the space needed for the tools.
621 Understand, however, that a sysroot is still needed for every
622 target since those binaries are target-specific.
623 </para></listitem>
624 </itemizedlist>
625 </para>
626
627 <para>
628 Remember, before using any BitBake command, you
629 must source the build environment setup script
630 (i.e.
631 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
632 or
633 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
634 located in the Source Directory and you must make sure your
635 <filename>conf/local.conf</filename> variables are correct.
636 In particular, you need to be sure the
637 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
638 variable matches the architecture for which you are building and that
639 the
640 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
641 variable is correctly set if you are building a toolchain designed to
642 run on an architecture that differs from your current development host
643 machine (i.e. the build machine).
644 </para>
645
646 <para>
647 When the <filename>bitbake</filename> command completes, the toolchain
648 installer will be in
649 <filename>tmp/deploy/sdk</filename> in the Build Directory.
650 <note>
651 By default, this toolchain does not build static binaries.
652 If you want to use the toolchain to build these types of libraries,
653 you need to be sure your image has the appropriate static
654 development libraries.
655 Use the
656 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
657 variable inside your <filename>local.conf</filename> file to
658 install the appropriate library packages.
659 Following is an example using <filename>eglibc</filename> static
660 development libraries:
661 <literallayout class='monospaced'>
662 IMAGE_INSTALL_append = " eglibc-staticdev"
663 </literallayout>
664 </note>
665 </para>
666</section>
667
668</chapter>
669<!--
670vim: expandtab tw=80 ts=4
671-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-04-22 06:47:28 +0000