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.xml646
1 files changed, 646 insertions, 0 deletions
diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
new file mode 100644
index 0000000..df9d5b0
--- /dev/null
+++ b/documentation/adt-manual/adt-prepare.xml
@@ -0,0 +1,646 @@
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 BitBake to generate the tarball inside an
91 existing
92 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
93 </para>
94 <para>If you use BitBake to generate the ADT Installer
95 tarball, you must <filename>source</filename> the
96 environment setup script
97 (<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
98 or
99 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
100 located in the Source Directory before running the
101 BitBake command that creates the tarball.</para>
102 <para>The following example commands establish
103 the
104 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
105 check out the current release branch, set up the
106 build environment while also creating the default
107 Build Directory, and run the BitBake command that
108 results in the tarball
109 <filename>poky/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>:
110 <note>
111 Before using BitBake to build the ADT tarball, be
112 sure to make sure your
113 <filename>local.conf</filename> file is properly
114 configured.
115 </note>
116 <literallayout class='monospaced'>
117 $ cd ~
118 $ git clone git://git.yoctoproject.org/poky
119 $ cd poky
120 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
121 $ source &OE_INIT_FILE;
122 $ bitbake adt-installer
123 </literallayout></para></listitem>
124 </itemizedlist>
125 </para>
126 </section>
127
128 <section id='configuring-and-running-the-adt-installer-script'>
129 <title>Configuring and Running the ADT Installer Script</title>
130
131 <para>
132 Before running the ADT Installer script, you need to unpack the tarball.
133 You can unpack the tarball in any directory you wish.
134 For example, this command copies the ADT Installer tarball from where
135 it was built into the home directory and then unpacks the tarball into
136 a top-level directory named <filename>adt-installer</filename>:
137 <literallayout class='monospaced'>
138 $ cd ~
139 $ cp poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME
140 $ tar -xjf adt_installer.tar.bz2
141 </literallayout>
142 Unpacking it creates the directory <filename>adt-installer</filename>,
143 which contains the ADT Installer script (<filename>adt_installer</filename>)
144 and its configuration file (<filename>adt_installer.conf</filename>).
145 </para>
146
147 <para>
148 Before you run the script, however, you should examine the ADT Installer configuration
149 file and be sure you are going to get what you want.
150 Your configurations determine which kernel and filesystem image are downloaded.
151 </para>
152
153 <para>
154 The following list describes the configurations you can define for the ADT Installer.
155 For configuration values and restrictions, see the comments in
156 the <filename>adt-installer.conf</filename> file:
157
158 <itemizedlist>
159 <listitem><para><filename>YOCTOADT_REPO</filename>: This area
160 includes the IPKG-based packages and the root filesystem upon which
161 the installation is based.
162 If you want to set up your own IPKG repository pointed to by
163 <filename>YOCTOADT_REPO</filename>, you need to be sure that the
164 directory structure follows the same layout as the reference directory
165 set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.
166 Also, your repository needs to be accessible through HTTP.</para></listitem>
167 <listitem><para><filename>YOCTOADT_TARGETS</filename>: The machine
168 target architectures for which you want to set up cross-development
169 environments.</para></listitem>
170 <listitem><para><filename>YOCTOADT_QEMU</filename>: Indicates whether
171 or not to install the emulator QEMU.</para></listitem>
172 <listitem><para><filename>YOCTOADT_NFS_UTIL</filename>: Indicates whether
173 or not to install user-mode NFS.
174 If you plan to use the Eclipse IDE Yocto plug-in against QEMU,
175 you should install NFS.
176 <note>To boot QEMU images using our userspace NFS server, you need
177 to be running <filename>portmap</filename> or <filename>rpcbind</filename>.
178 If you are running <filename>rpcbind</filename>, you will also need to add the
179 <filename>-i</filename> option when <filename>rpcbind</filename> starts up.
180 Please make sure you understand the security implications of doing this.
181 You might also have to modify your firewall settings to allow
182 NFS booting to work.</note></para></listitem>
183 <listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>: The root
184 filesystem images you want to download from the
185 <filename>YOCTOADT_IPKG_REPO</filename> repository.</para></listitem>
186 <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename>: The
187 particular root filesystem used to extract and create the target sysroot.
188 The value of this variable must have been specified with
189 <filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>.
190 For example, if you downloaded both <filename>minimal</filename> and
191 <filename>sato-sdk</filename> images by setting
192 <filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>
193 to "minimal sato-sdk", then <filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>
194 must be set to either <filename>minimal</filename> or
195 <filename>sato-sdk</filename>.</para></listitem>
196 <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename>: The
197 location on the development host where the target sysroot is created.
198 </para></listitem>
199 </itemizedlist>
200 </para>
201
202 <para>
203 After you have configured the <filename>adt_installer.conf</filename> file,
204 run the installer using the following command.
205 Be sure that you are not trying to use cross-compilation tools.
206 When you run the installer, the environment must use a
207 host <filename>gcc</filename>:
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>Get your toolchain installer using one of the
258 following methods:
259 <itemizedlist>
260 <listitem><para>Go to
261 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
262 and find the folder that matches your host
263 development system (i.e. <filename>i686</filename>
264 for 32-bit machines or <filename>x86_64</filename>
265 for 64-bit machines).</para>
266 <para>Go into that folder and download the toolchain
267 installer whose name includes the appropriate target
268 architecture.
269 The toolchains provided by the Yocto Project
270 are based off of the
271 <filename>core-image-sato</filename> image and
272 contain libraries appropriate for developing
273 against that image.
274 For example, if your host development system is a
275 64-bit x86 system and you are going to use
276 your cross-toolchain for a 32-bit x86
277 target, go into the <filename>x86_64</filename>
278 folder and download the following installer:
279 <literallayout class='monospaced'>
280 poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
281 </literallayout></para></listitem>
282 <listitem><para>Build your own toolchain installer.
283 For cases where you cannot use an installer
284 from the download area, you can build your own as
285 described in the
286 "<link linkend='optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</link>"
287 section.</para></listitem>
288 </itemizedlist></para></listitem>
289 <listitem><para>Once you have the installer, run it to install
290 the toolchain.
291 <note>
292 You must change the permissions on the toolchain
293 installer script so that it is executable.
294 </note></para>
295 <para>The following command shows how to run the installer
296 given a toolchain tarball for a 64-bit x86 development host
297 system and a 32-bit x86 target architecture.
298 The example assumes the toolchain installer is located
299 in <filename>~/Downloads/</filename>.
300 <literallayout class='monospaced'>
301 $ ~/Downloads/poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
302 </literallayout>
303 The first thing the installer prompts you for is the
304 directory into which you want to install the toolchain.
305 The default directory used is
306 <filename>/opt/poky/&DISTRO;</filename>.
307 If you do not have write permissions for the directory
308 into which you are installing the toolchain, the
309 toolchain installer notifies you and exits.
310 Be sure you have write permissions in the directory and
311 run the installer again.</para>
312 <para>When the script finishes, the cross-toolchain is
313 installed.
314 You will notice environment setup files for the
315 cross-toolchain in the installation directory.
316 </para></listitem>
317 </orderedlist>
318 </para>
319 </section>
320
321 <section id='using-the-toolchain-from-within-the-build-tree'>
322 <title>Using BitBake and the Build Directory</title>
323
324 <para>
325 A final way of making the cross-toolchain available is to use BitBake
326 to generate the toolchain within an existing
327 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
328 This method does not install the toolchain into the default
329 <filename>/opt</filename> directory.
330 As with the previous method, if you need to install the target sysroot, you must
331 do that separately as well.
332 </para>
333
334 <para>
335 Follow these steps to generate the toolchain into the Build Directory:
336 <orderedlist>
337 <listitem><para><emphasis>Set up the Build Environment:</emphasis>
338 Source the OpenEmbedded build environment setup
339 script (i.e.
340 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
341 or
342 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
343 located in the
344 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
345 </para></listitem>
346 <listitem><para><emphasis>Check your Local Configuration File:</emphasis>
347 At this point, you should be sure that the
348 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable
349 in the <filename>local.conf</filename> file found in the
350 <filename>conf</filename> directory of the Build Directory
351 is set for the target architecture.
352 Comments within the <filename>local.conf</filename> file
353 list the values you can use for the
354 <filename>MACHINE</filename> variable.
355 <note>
356 You can populate the Build Directory with the
357 cross-toolchains for more than a single architecture.
358 You just need to edit the <filename>MACHINE</filename>
359 variable in the <filename>local.conf</filename> file and
360 re-run the BitBake command.
361 </note></para></listitem>
362 <listitem><para><emphasis>Generate the Cross-Toolchain:</emphasis>
363 Run <filename>bitbake meta-ide-support</filename> to
364 complete the cross-toolchain generation.
365 Once the BitBake command finishes, the cross-toolchain is
366 generated and populated within the Build Directory.
367 You will notice environment setup files for the
368 cross-toolchain that contain the string
369 "<filename>environment-setup</filename>" in the
370 Build Directory's <filename>tmp</filename> folder.</para>
371 <para>Be aware that when you use this method to install the
372 toolchain, you still need to separately extract and install
373 the sysroot filesystem.
374 For information on how to do this, see the
375 "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.
376 </para></listitem>
377 </orderedlist>
378 </para>
379 </section>
380</section>
381
382<section id='setting-up-the-cross-development-environment'>
383 <title>Setting Up the Cross-Development Environment</title>
384
385 <para>
386 Before you can develop using the cross-toolchain, you need to set up the
387 cross-development environment by sourcing the toolchain's environment setup script.
388 If you used the ADT Installer or hand-installed cross-toolchain,
389 then you can find this script in the directory you chose for installation.
390 The default installation directory is the <filename>&YOCTO_ADTPATH_DIR;</filename>
391 directory.
392 If you installed the toolchain in the
393 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
394 you can find the environment setup
395 script for the toolchain in the Build Directory's <filename>tmp</filename> directory.
396 </para>
397
398 <para>
399 Be sure to run the environment setup script that matches the
400 architecture for which you are developing.
401 Environment setup scripts begin with the string
402 "<filename>environment-setup</filename>" and include as part of their
403 name the architecture.
404 For example, the toolchain environment setup script for a 64-bit
405 IA-based architecture installed in the default installation directory
406 would be the following:
407 <literallayout class='monospaced'>
408 &YOCTO_ADTPATH_DIR;/environment-setup-x86_64-poky-linux
409 </literallayout>
410 </para>
411</section>
412
413<section id='securing-kernel-and-filesystem-images'>
414 <title>Securing Kernel and Filesystem Images</title>
415
416 <para>
417 You will need to have a kernel and filesystem image to boot using your
418 hardware or the QEMU emulator.
419 Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem
420 as the target sysroot, you need to extract the root filesystem.
421 </para>
422
423 <section id='getting-the-images'>
424 <title>Getting the Images</title>
425
426 <para>
427 To get the kernel and filesystem images, you either have to build them or download
428 pre-built versions.
429 You can find examples for both these situations in the
430 "<ulink url='&YOCTO_DOCS_QS_URL;#test-run'>A Quick Test Run</ulink>" section of
431 the Yocto Project Quick Start.
432 </para>
433
434 <para>
435 The Yocto Project ships basic kernel and filesystem images for several
436 architectures (<filename>x86</filename>, <filename>x86-64</filename>,
437 <filename>mips</filename>, <filename>powerpc</filename>, and <filename>arm</filename>)
438 that you can use unaltered in the QEMU emulator.
439 These kernel images reside in the release
440 area - <ulink url='&YOCTO_MACHINES_DL_URL;'></ulink>
441 and are ideal for experimentation using Yocto Project.
442 For information on the image types you can build using the OpenEmbedded build system,
443 see the
444 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
445 the Yocto Project Reference Manual.
446 </para>
447
448 <para>
449 If you are planning on developing against your image and you are not
450 building or using one of the Yocto Project development images
451 (e.g. <filename>core-image-*-dev</filename>), you must be sure to
452 include the development packages as part of your image recipe.
453 </para>
454
455 <para>
456 Furthermore, if you plan on remotely deploying and debugging your
457 application from within the
458 Eclipse IDE, you must have an image that contains the Yocto Target Communication
459 Framework (TCF) agent (<filename>tcf-agent</filename>).
460 By default, the Yocto Project provides only one type of pre-built
461 image that contains the <filename>tcf-agent</filename>.
462 And, those images are SDK (e.g.<filename>core-image-sato-sdk</filename>).
463 </para>
464
465 <para>
466 If you want to use a different image type that contains the <filename>tcf-agent</filename>,
467 you can do so one of two ways:
468 <itemizedlist>
469 <listitem><para>Modify the <filename>conf/local.conf</filename> configuration in
470 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
471 and then rebuild the image.
472 With this method, you need to modify the
473 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
474 variable to have the value of "tools-debug" before rebuilding the image.
475 Once the image is rebuilt, the <filename>tcf-agent</filename> will be included
476 in the image and is launched automatically after the boot.</para></listitem>
477 <listitem><para>Manually build the <filename>tcf-agent</filename>.
478 To build the agent, follow these steps:
479 <orderedlist>
480 <listitem><para>Be sure the ADT is installed as described in the
481 "<link linkend='installing-the-adt'>Installing the ADT and Toolchains</link>" section.
482 </para></listitem>
483 <listitem><para>Set up the cross-development environment as described in the
484 "<link linkend='setting-up-the-cross-development-environment'>Setting
485 Up the Cross-Development Environment</link>" section.</para></listitem>
486 <listitem><para>Get the <filename>tcf-agent</filename> source code using
487 the following commands:
488 <literallayout class='monospaced'>
489 $ git clone http://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git
490 $ cd org.eclipse.tcf.agent/agent
491 </literallayout></para></listitem>
492 <listitem><para>Locate the
493 <filename>Makefile.inc</filename> file inside the
494 <filename>agent</filename> folder and modify it
495 for the cross-compilation environment by setting the
496 <filename>OPSYS</filename> and
497 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
498 variables according to your target.
499 </para></listitem>
500 <listitem><para>Use the cross-development tools to build the
501 <filename>tcf-agent</filename>.
502 Before you "Make" the file, be sure your cross-tools are set up first.
503 See the "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
504 section for information on how to make sure the cross-tools are set up
505 correctly.</para>
506 <para>If the build is successful, the <filename>tcf-agent</filename> output will
507 be <filename>obj/$(OPSYS)/$(MACHINE)/Debug/agent</filename>.</para></listitem>
508 <listitem><para>Deploy the agent into the image's root filesystem.</para></listitem>
509 </orderedlist>
510 </para></listitem>
511 </itemizedlist>
512 </para>
513 </section>
514
515 <section id='extracting-the-root-filesystem'>
516 <title>Extracting the Root Filesystem</title>
517
518 <para>
519 If you install your toolchain by hand or build it using BitBake and
520 you need a root filesystem, you need to extract it separately.
521 If you use the ADT Installer to install the ADT, the root
522 filesystem is automatically extracted and installed.
523 </para>
524
525 <para>
526 Here are some cases where you need to extract the root filesystem:
527 <itemizedlist>
528 <listitem><para>You want to boot the image using NFS.
529 </para></listitem>
530 <listitem><para>You want to use the root filesystem as the
531 target sysroot.
532 For example, the Eclipse IDE environment with the Eclipse
533 Yocto Plug-in installed allows you to use QEMU to boot
534 under NFS.</para></listitem>
535 <listitem><para>You want to develop your target application
536 using the root filesystem as the target sysroot.
537 </para></listitem>
538 </itemizedlist>
539 </para>
540
541 <para>
542 To extract the root filesystem, first <filename>source</filename>
543 the cross-development environment setup script.
544 If you built the toolchain in the Build Directory, you will find
545 the toolchain environment script in the
546 <filename>tmp</filename> directory.
547 If you installed the toolchain by hand, the environment setup
548 script is located in <filename>/opt/poky/&DISTRO;</filename>.
549 </para>
550
551 <para>
552 After sourcing the environment script, use the
553 <filename>runqemu-extract-sdk</filename> command and provide the
554 filesystem image.
555 </para>
556
557 <para>
558 Following is an example.
559 The second command sets up the environment.
560 In this case, the setup script is located in the
561 <filename>/opt/poky/&DISTRO;</filename> directory.
562 The third command extracts the root filesystem from a previously
563 built filesystem that is located in the
564 <filename>~/Downloads</filename> directory.
565 Furthermore, this command extracts the root filesystem into the
566 <filename>qemux86-sato</filename> directory:
567 <literallayout class='monospaced'>
568 $ cd ~
569 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
570 $ runqemu-extract-sdk \
571 ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \
572 $HOME/qemux86-sato
573 </literallayout>
574 You could now point to the target sysroot at
575 <filename>qemux86-sato</filename>.
576 </para>
577 </section>
578</section>
579
580<section id='optionally-building-a-toolchain-installer'>
581 <title>Optionally Building a Toolchain Installer</title>
582
583 <para>
584 As an alternative to locating and downloading a toolchain installer,
585 you can build the toolchain installer one of two ways if you have a
586 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
587 <itemizedlist>
588 <listitem><para>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.</para></listitem>
594 <listitem><para>Use
595 <filename>bitbake image -c populate_sdk</filename>.
596 This method has significant advantages over the previous method
597 because it results in a toolchain installer that contains the
598 sysroot that matches your target root filesystem.
599 </para></listitem>
600 </itemizedlist>
601 </para>
602
603 <para>
604 Remember, before using any BitBake command, you
605 must source the build environment setup script
606 (i.e.
607 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
608 or
609 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
610 located in the Source Directory and you must make sure your
611 <filename>conf/local.conf</filename> variables are correct.
612 In particular, you need to be sure the
613 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
614 variable matches the architecture for which you are building and that
615 the
616 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
617 variable is correctly set if you are building a toolchain designed to
618 run on an architecture that differs from your current development host
619 machine (i.e. the build machine).
620 </para>
621
622 <para>
623 When the BitBake command completes, the toolchain installer will be in
624 <filename>tmp/deploy/sdk</filename> in the Build Directory.
625 <note>
626 By default, this toolchain does not build static binaries.
627 If you want to use the toolchain to build these types of libraries,
628 you need to be sure your image has the appropriate static
629 development libraries.
630 Use the
631 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
632 variable inside your <filename>local.conf</filename> file to
633 install the appropriate library packages.
634 Following is an example using <filename>eglibc</filename> static
635 development libraries:
636 <literallayout class='monospaced'>
637 IMAGE_INSTALL_append = " eglibc-staticdev"
638 </literallayout>
639 </note>
640 </para>
641</section>
642
643</chapter>
644<!--
645vim: expandtab tw=80 ts=4
646-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-05-13 03:05:05 +0000