summaryrefslogtreecommitdiffstats
path: root/documentation/adt-manual/adt-prepare.xml
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 16:30:32 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-06 13:56:17 +0100
commit43d07a285181e64c30d98d10ff93ef50391efe59 (patch)
tree78918fc94d55d44d35e1e3e61c7a6fccc28bca24 /documentation/adt-manual/adt-prepare.xml
parent1fd9c4b2c0ae927df29f7a0d34c3e595bcf48e89 (diff)
downloadpoky-43d07a285181e64c30d98d10ff93ef50391efe59.tar.gz
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/adt-manual/adt-prepare.xml')
-rw-r--r--documentation/adt-manual/adt-prepare.xml1000
1 files changed, 0 insertions, 1000 deletions
diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
deleted file mode 100644
index 2dc9843259..0000000000
--- a/documentation/adt-manual/adt-prepare.xml
+++ /dev/null
@@ -1,1000 +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<chapter id='adt-prepare'>
7
8<title>Preparing for Application Development</title>
9
10<para>
11 In order to develop applications, you need set up your host development system.
12 Several ways exist that allow you to install cross-development tools, QEMU, the
13 Eclipse Yocto Plug-in, and other tools.
14 This chapter describes how to prepare for application development.
15</para>
16
17<section id='installing-the-adt'>
18 <title>Installing the ADT and Toolchains</title>
19
20 <para>
21 The following list describes installation methods that set up varying
22 degrees of tool availability on your system.
23 Regardless of the installation method you choose,
24 you must <filename>source</filename> the cross-toolchain
25 environment setup script, which establishes several key
26 environment variables, before you use a toolchain.
27 See the
28 "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>"
29 section for more information.
30 </para>
31
32 <note>
33 <para>
34 Avoid mixing installation methods when installing toolchains for
35 different architectures.
36 For example, avoid using the ADT Installer to install some
37 toolchains and then hand-installing cross-development toolchains
38 by running the toolchain installer for different architectures.
39 Mixing installation methods can result in situations where the
40 ADT Installer becomes unreliable and might not install the
41 toolchain.
42 </para>
43
44 <para>
45 If you must mix installation methods, you might avoid problems by
46 deleting <filename>/var/lib/opkg</filename>, thus purging the
47 <filename>opkg</filename> package metadata.
48 </para>
49 </note>
50
51 <para>
52 <itemizedlist>
53 <listitem><para><emphasis>Use the ADT installer script:</emphasis>
54 This method is the recommended way to install the ADT because it
55 automates much of the process for you.
56 For example, you can configure the installation to install the QEMU emulator
57 and the user-space NFS, specify which root filesystem profiles to download,
58 and define the target sysroot location.</para></listitem>
59 <listitem><para><emphasis>Use an existing toolchain:</emphasis>
60 Using this method, you select and download an architecture-specific
61 toolchain installer and then run the script to hand-install the toolchain.
62 If you use this method, you just get the cross-toolchain and QEMU - you do not
63 get any of the other mentioned benefits had you run the ADT Installer script.</para></listitem>
64 <listitem><para><emphasis>Use the toolchain from within the Build Directory:</emphasis>
65 If you already have a
66 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
67 you can build the cross-toolchain within the directory.
68 However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you
69 do not get any of the other benefits without taking separate steps.</para></listitem>
70 </itemizedlist>
71 </para>
72
73 <section id='using-the-adt-installer'>
74 <title>Using the ADT Installer</title>
75
76 <para>
77 To run the ADT Installer, you need to get the ADT Installer tarball, be sure
78 you have the necessary host development packages that support the ADT Installer,
79 and then run the ADT Installer Script.
80 </para>
81
82 <para>
83 For a list of the host packages needed to support ADT installation and use, see the
84 "ADT Installer Extras" lists in the
85 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" section
86 of the Yocto Project Reference Manual.
87 </para>
88
89 <section id='getting-the-adt-installer-tarball'>
90 <title>Getting the ADT Installer Tarball</title>
91
92 <para>
93 The ADT Installer is contained in the ADT Installer tarball.
94 You can get the tarball using either of these methods:
95 <itemizedlist>
96 <listitem><para><emphasis>Download the Tarball:</emphasis>
97 You can download the tarball from
98 <ulink url='&YOCTO_ADTINSTALLER_DL_URL;'></ulink> into
99 any directory.</para></listitem>
100 <listitem><para><emphasis>Build the Tarball:</emphasis>
101 You can use
102 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
103 to generate the tarball inside an existing
104 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
105 </para>
106 <para>If you use BitBake to generate the ADT Installer
107 tarball, you must <filename>source</filename> the
108 environment setup script
109 (<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
110 or
111 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
112 located in the Source Directory before running the
113 <filename>bitbake</filename> command that creates the
114 tarball.</para>
115 <para>The following example commands establish
116 the
117 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
118 check out the current release branch, set up the
119 build environment while also creating the default
120 Build Directory, and run the
121 <filename>bitbake</filename> command that results in the
122 tarball
123 <filename>poky/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>:
124 <note>
125 Before using BitBake to build the ADT tarball, be
126 sure to make sure your
127 <filename>local.conf</filename> file is properly
128 configured.
129 See the
130 "<ulink url='&YOCTO_DOCS_REF_URL;#user-configuration'>User Configuration</ulink>"
131 section in the Yocto Project Reference Manual for
132 general configuration information.
133 </note>
134 <literallayout class='monospaced'>
135 $ cd ~
136 $ git clone git://git.yoctoproject.org/poky
137 $ cd poky
138 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
139 $ source &OE_INIT_FILE;
140 $ bitbake adt-installer
141 </literallayout></para></listitem>
142 </itemizedlist>
143 </para>
144 </section>
145
146 <section id='configuring-and-running-the-adt-installer-script'>
147 <title>Configuring and Running the ADT Installer Script</title>
148
149 <para>
150 Before running the ADT Installer script, you need to unpack the tarball.
151 You can unpack the tarball in any directory you wish.
152 For example, this command copies the ADT Installer tarball from where
153 it was built into the home directory and then unpacks the tarball into
154 a top-level directory named <filename>adt-installer</filename>:
155 <literallayout class='monospaced'>
156 $ cd ~
157 $ cp poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME
158 $ tar -xjf adt_installer.tar.bz2
159 </literallayout>
160 Unpacking it creates the directory <filename>adt-installer</filename>,
161 which contains the ADT Installer script (<filename>adt_installer</filename>)
162 and its configuration file (<filename>adt_installer.conf</filename>).
163 </para>
164
165 <para>
166 Before you run the script, however, you should examine the ADT Installer configuration
167 file and be sure you are going to get what you want.
168 Your configurations determine which kernel and filesystem image are downloaded.
169 </para>
170
171 <para>
172 The following list describes the configurations you can define for the ADT Installer.
173 For configuration values and restrictions, see the comments in
174 the <filename>adt-installer.conf</filename> file:
175
176 <itemizedlist>
177 <listitem><para><filename>YOCTOADT_REPO</filename>: This area
178 includes the IPKG-based packages and the root filesystem upon which
179 the installation is based.
180 If you want to set up your own IPKG repository pointed to by
181 <filename>YOCTOADT_REPO</filename>, you need to be sure that the
182 directory structure follows the same layout as the reference directory
183 set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.
184 Also, your repository needs to be accessible through HTTP.</para></listitem>
185 <listitem><para><filename>YOCTOADT_TARGETS</filename>: The machine
186 target architectures for which you want to set up cross-development
187 environments.</para></listitem>
188 <listitem><para><filename>YOCTOADT_QEMU</filename>: Indicates whether
189 or not to install the emulator QEMU.</para></listitem>
190 <listitem><para><filename>YOCTOADT_NFS_UTIL</filename>: Indicates whether
191 or not to install user-mode NFS.
192 If you plan to use the Eclipse IDE Yocto plug-in against QEMU,
193 you should install NFS.
194 <note>To boot QEMU images using our userspace NFS server, you need
195 to be running <filename>portmap</filename> or <filename>rpcbind</filename>.
196 If you are running <filename>rpcbind</filename>, you will also need to add the
197 <filename>-i</filename> option when <filename>rpcbind</filename> starts up.
198 Please make sure you understand the security implications of doing this.
199 You might also have to modify your firewall settings to allow
200 NFS booting to work.</note></para></listitem>
201 <listitem><para><filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>: The root
202 filesystem images you want to download from the
203 <filename>YOCTOADT_IPKG_REPO</filename> repository.</para></listitem>
204 <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_</filename><replaceable>arch</replaceable>: The
205 particular root filesystem used to extract and create the target sysroot.
206 The value of this variable must have been specified with
207 <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>.
208 For example, if you downloaded both <filename>minimal</filename> and
209 <filename>sato-sdk</filename> images by setting
210 <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>
211 to "minimal sato-sdk", then <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>
212 must be set to either "minimal" or "sato-sdk".
213 </para></listitem>
214 <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_</filename><replaceable>arch</replaceable>: The
215 location on the development host where the target sysroot is created.
216 </para></listitem>
217 </itemizedlist>
218 </para>
219
220 <para>
221 After you have configured the <filename>adt_installer.conf</filename> file,
222 run the installer using the following command:
223 <literallayout class='monospaced'>
224 $ cd adt-installer
225 $ ./adt_installer
226 </literallayout>
227 Once the installer begins to run, you are asked to enter the
228 location for cross-toolchain installation.
229 The default location is
230 <filename>/opt/poky/</filename><replaceable>release</replaceable>.
231 After either accepting the default location or selecting your
232 own location, you are prompted to run the installation script
233 interactively or in silent mode.
234 If you want to closely monitor the installation,
235 choose "I" for interactive mode rather than "S" for silent mode.
236 Follow the prompts from the script to complete the installation.
237 </para>
238
239 <para>
240 Once the installation completes, the ADT, which includes the
241 cross-toolchain, is installed in the selected installation
242 directory.
243 You will notice environment setup files for the cross-toolchain
244 in the installation directory, and image tarballs in the
245 <filename>adt-installer</filename> directory according to your
246 installer configurations, and the target sysroot located
247 according to the
248 <filename>YOCTOADT_TARGET_SYSROOT_LOC_</filename><replaceable>arch</replaceable>
249 variable also in your configuration file.
250 </para>
251 </section>
252 </section>
253
254 <section id='using-an-existing-toolchain-tarball'>
255 <title>Using a Cross-Toolchain Tarball</title>
256
257 <para>
258 If you want to simply install a cross-toolchain by hand, you can
259 do so by running the toolchain installer.
260 The installer includes the pre-built cross-toolchain, the
261 <filename>runqemu</filename> script, and support files.
262 If you use this method to install the cross-toolchain, you
263 might still need to install the target sysroot by installing and
264 extracting it separately.
265 For information on how to install the sysroot, see the
266 "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.
267 </para>
268
269 <para>
270 Follow these steps:
271 <orderedlist>
272 <listitem><para><emphasis>Get your toolchain installer using one of the following methods:</emphasis>
273 <itemizedlist>
274 <listitem><para>Go to
275 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
276 and find the folder that matches your host
277 development system (i.e. <filename>i686</filename>
278 for 32-bit machines or <filename>x86_64</filename>
279 for 64-bit machines).</para>
280 <para>Go into that folder and download the toolchain
281 installer whose name includes the appropriate target
282 architecture.
283 The toolchains provided by the Yocto Project
284 are based off of the
285 <filename>core-image-sato</filename> image and
286 contain libraries appropriate for developing
287 against that image.
288 For example, if your host development system is a
289 64-bit x86 system and you are going to use
290 your cross-toolchain for a 32-bit x86
291 target, go into the <filename>x86_64</filename>
292 folder and download the following installer:
293 <literallayout class='monospaced'>
294 poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
295 </literallayout></para></listitem>
296 <listitem><para>Build your own toolchain installer.
297 For cases where you cannot use an installer
298 from the download area, you can build your own as
299 described in the
300 "<link linkend='optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</link>"
301 section.</para></listitem>
302 </itemizedlist></para></listitem>
303 <listitem><para><emphasis>Once you have the installer, run it to install the toolchain:</emphasis>
304 <note>
305 You must change the permissions on the toolchain
306 installer script so that it is executable.
307 </note></para>
308 <para>The following command shows how to run the installer
309 given a toolchain tarball for a 64-bit x86 development host
310 system and a 32-bit x86 target architecture.
311 The example assumes the toolchain installer is located
312 in <filename>~/Downloads/</filename>.
313 <literallayout class='monospaced'>
314 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
315 </literallayout>
316 The first thing the installer prompts you for is the
317 directory into which you want to install the toolchain.
318 The default directory used is
319 <filename>/opt/poky/&DISTRO;</filename>.
320 If you do not have write permissions for the directory
321 into which you are installing the toolchain, the
322 toolchain installer notifies you and exits.
323 Be sure you have write permissions in the directory and
324 run the installer again.</para>
325 <para>When the script finishes, the cross-toolchain is
326 installed.
327 You will notice environment setup files for the
328 cross-toolchain in the installation directory.
329 </para></listitem>
330 </orderedlist>
331 </para>
332 </section>
333
334 <section id='using-the-toolchain-from-within-the-build-tree'>
335 <title>Using BitBake and the Build Directory</title>
336
337 <para>
338 A final way of making the cross-toolchain available is to use BitBake
339 to generate the toolchain within an existing
340 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
341 This method does not install the toolchain into the default
342 <filename>/opt</filename> directory.
343 As with the previous method, if you need to install the target sysroot, you must
344 do that separately as well.
345 </para>
346
347 <para>
348 Follow these steps to generate the toolchain into the Build Directory:
349 <orderedlist>
350 <listitem><para><emphasis>Set up the Build Environment:</emphasis>
351 Source the OpenEmbedded build environment setup
352 script (i.e.
353 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
354 or
355 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
356 located in the
357 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
358 </para></listitem>
359 <listitem><para><emphasis>Check your Local Configuration File:</emphasis>
360 At this point, you should be sure that the
361 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable
362 in the <filename>local.conf</filename> file found in the
363 <filename>conf</filename> directory of the Build Directory
364 is set for the target architecture.
365 Comments within the <filename>local.conf</filename> file
366 list the values you can use for the
367 <filename>MACHINE</filename> variable.
368 If you do not change the <filename>MACHINE</filename>
369 variable, the OpenEmbedded build system uses
370 <filename>qemux86</filename> as the default target
371 machine when building the cross-toolchain.
372 <note>
373 You can populate the Build Directory with the
374 cross-toolchains for more than a single architecture.
375 You just need to edit the <filename>MACHINE</filename>
376 variable in the <filename>local.conf</filename> file and
377 re-run the <filename>bitbake</filename> command.
378 </note></para></listitem>
379 <listitem><para><emphasis>Make Sure Your Layers are Enabled:</emphasis>
380 Examine the <filename>conf/bblayers.conf</filename> file
381 and make sure that you have enabled all the compatible
382 layers for your target machine.
383 The OpenEmbedded build system needs to be aware of each
384 layer you want included when building images and
385 cross-toolchains.
386 For information on how to enable a layer, see the
387 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
388 section in the Yocto Project Development Manual.
389 </para></listitem>
390 <listitem><para><emphasis>Generate the Cross-Toolchain:</emphasis>
391 Run <filename>bitbake meta-ide-support</filename> to
392 complete the cross-toolchain generation.
393 Once the <filename>bitbake</filename> command finishes,
394 the cross-toolchain is
395 generated and populated within the Build Directory.
396 You will notice environment setup files for the
397 cross-toolchain that contain the string
398 "<filename>environment-setup</filename>" in the
399 Build Directory's <filename>tmp</filename> folder.</para>
400 <para>Be aware that when you use this method to install the
401 toolchain, you still need to separately extract and install
402 the sysroot filesystem.
403 For information on how to do this, see the
404 "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.
405 </para></listitem>
406 </orderedlist>
407 </para>
408 </section>
409</section>
410
411<section id='setting-up-the-cross-development-environment'>
412 <title>Setting Up the Cross-Development Environment</title>
413
414 <para>
415 Before you can develop using the cross-toolchain, you need to set up the
416 cross-development environment by sourcing the toolchain's environment setup script.
417 If you used the ADT Installer or hand-installed cross-toolchain,
418 then you can find this script in the directory you chose for installation.
419 For this release, the default installation directory is
420 <filename>&YOCTO_ADTPATH_DIR;</filename>.
421 If you installed the toolchain in the
422 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
423 you can find the environment setup
424 script for the toolchain in the Build Directory's <filename>tmp</filename> directory.
425 </para>
426
427 <para>
428 Be sure to run the environment setup script that matches the
429 architecture for which you are developing.
430 Environment setup scripts begin with the string
431 "<filename>environment-setup</filename>" and include as part of their
432 name the architecture.
433 For example, the toolchain environment setup script for a 64-bit
434 IA-based architecture installed in the default installation directory
435 would be the following:
436 <literallayout class='monospaced'>
437 &YOCTO_ADTPATH_DIR;/environment-setup-x86_64-poky-linux
438 </literallayout>
439 When you run the setup script, many environment variables are
440 defined:
441 <literallayout class='monospaced'>
442 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
443 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
444 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
445 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
446 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
447 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
448 <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
449 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
450 <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
451 <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols
452 <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
453 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
454 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
455 <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
456 <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
457 <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
458 <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools
459 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
460 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
461 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
462 <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
463 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags
464 </literallayout>
465 </para>
466</section>
467
468<section id='securing-kernel-and-filesystem-images'>
469 <title>Securing Kernel and Filesystem Images</title>
470
471 <para>
472 You will need to have a kernel and filesystem image to boot using your
473 hardware or the QEMU emulator.
474 Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem
475 as the target sysroot, you need to extract the root filesystem.
476 </para>
477
478 <section id='getting-the-images'>
479 <title>Getting the Images</title>
480
481 <para>
482 To get the kernel and filesystem images, you either have to build them or download
483 pre-built versions.
484 For an example of how to build these images, see the
485 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-buiding-images'>Buiding Images</ulink>"
486 section of the Yocto Project Quick Start.
487 For an example of downloading pre-build versions, see the
488 "<link linkend='using-pre-built'>Example Using Pre-Built Binaries and QEMU</link>"
489 section.
490 </para>
491
492 <para>
493 The Yocto Project ships basic kernel and filesystem images for several
494 architectures (<filename>x86</filename>, <filename>x86-64</filename>,
495 <filename>mips</filename>, <filename>powerpc</filename>, and <filename>arm</filename>)
496 that you can use unaltered in the QEMU emulator.
497 These kernel images reside in the release
498 area - <ulink url='&YOCTO_MACHINES_DL_URL;'></ulink>
499 and are ideal for experimentation using Yocto Project.
500 For information on the image types you can build using the OpenEmbedded build system,
501 see the
502 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
503 chapter in the Yocto Project Reference Manual.
504 </para>
505
506 <para>
507 If you are planning on developing against your image and you are not
508 building or using one of the Yocto Project development images
509 (e.g. <filename>core-image-*-dev</filename>), you must be sure to
510 include the development packages as part of your image recipe.
511 </para>
512
513 <para>
514 If you plan on remotely deploying and debugging your
515 application from within the Eclipse IDE, you must have an image
516 that contains the Yocto Target Communication Framework (TCF) agent
517 (<filename>tcf-agent</filename>).
518 You can do this by including the <filename>eclipse-debug</filename>
519 image feature.
520 <note>
521 See the
522 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>"
523 section in the Yocto Project Reference Manual for information on
524 image features.
525 </note>
526 To include the <filename>eclipse-debug</filename> image feature,
527 modify your <filename>local.conf</filename> file in the
528 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
529 so that the
530 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
531 variable includes the "eclipse-debug" feature.
532 After modifying the configuration file, you can rebuild the image.
533 Once the image is rebuilt, the <filename>tcf-agent</filename>
534 will be included in the image and is launched automatically after
535 the boot.
536 </para>
537 </section>
538
539 <section id='extracting-the-root-filesystem'>
540 <title>Extracting the Root Filesystem</title>
541
542 <para>
543 If you install your toolchain by hand or build it using BitBake and
544 you need a root filesystem, you need to extract it separately.
545 If you use the ADT Installer to install the ADT, the root
546 filesystem is automatically extracted and installed.
547 </para>
548
549 <para>
550 Here are some cases where you need to extract the root filesystem:
551 <itemizedlist>
552 <listitem><para>You want to boot the image using NFS.
553 </para></listitem>
554 <listitem><para>You want to use the root filesystem as the
555 target sysroot.
556 For example, the Eclipse IDE environment with the Eclipse
557 Yocto Plug-in installed allows you to use QEMU to boot
558 under NFS.</para></listitem>
559 <listitem><para>You want to develop your target application
560 using the root filesystem as the target sysroot.
561 </para></listitem>
562 </itemizedlist>
563 </para>
564
565 <para>
566 To extract the root filesystem, first <filename>source</filename>
567 the cross-development environment setup script to establish
568 necessary environment variables.
569 If you built the toolchain in the Build Directory, you will find
570 the toolchain environment script in the
571 <filename>tmp</filename> directory.
572 If you installed the toolchain by hand, the environment setup
573 script is located in <filename>/opt/poky/&DISTRO;</filename>.
574 </para>
575
576 <para>
577 After sourcing the environment script, use the
578 <filename>runqemu-extract-sdk</filename> command and provide the
579 filesystem image.
580 </para>
581
582 <para>
583 Following is an example.
584 The second command sets up the environment.
585 In this case, the setup script is located in the
586 <filename>/opt/poky/&DISTRO;</filename> directory.
587 The third command extracts the root filesystem from a previously
588 built filesystem that is located in the
589 <filename>~/Downloads</filename> directory.
590 Furthermore, this command extracts the root filesystem into the
591 <filename>qemux86-sato</filename> directory:
592 <literallayout class='monospaced'>
593 $ cd ~
594 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
595 $ runqemu-extract-sdk \
596 ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \
597 $HOME/qemux86-sato
598 </literallayout>
599 You could now point to the target sysroot at
600 <filename>qemux86-sato</filename>.
601 </para>
602 </section>
603</section>
604
605<section id='optionally-building-a-toolchain-installer'>
606 <title>Optionally Building a Toolchain Installer</title>
607
608 <para>
609 As an alternative to locating and downloading a toolchain installer,
610 you can build the toolchain installer if you have a
611 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
612 <note>
613 Although not the preferred method, it is also possible to use
614 <filename>bitbake meta-toolchain</filename> to build the toolchain
615 installer.
616 If you do use this method, you must separately install and extract
617 the target sysroot.
618 For information on how to install the sysroot, see the
619 "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
620 section.
621 </note>
622 </para>
623
624 <para>
625 To build the toolchain installer and populate the SDK image, use the
626 following command:
627 <literallayout class='monospaced'>
628 $ bitbake <replaceable>image</replaceable> -c populate_sdk
629 </literallayout>
630 The command results in a toolchain installer that contains the sysroot
631 that matches your target root filesystem.
632 </para>
633
634 <para>
635 Another powerful feature is that the toolchain is completely
636 self-contained.
637 The binaries are linked against their own copy of
638 <filename>libc</filename>, which results in no dependencies
639 on the target system.
640 To achieve this, the pointer to the dynamic loader is
641 configured at install time since that path cannot be dynamically
642 altered.
643 This is the reason for a wrapper around the
644 <filename>populate_sdk</filename> archive.
645 </para>
646
647 <para>
648 Another feature is that only one set of cross-canadian toolchain
649 binaries are produced per architecture.
650 This feature takes advantage of the fact that the target hardware can
651 be passed to <filename>gcc</filename> as a set of compiler options.
652 Those options are set up by the environment script and contained in
653 variables such as
654 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
655 and
656 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>.
657 This reduces the space needed for the tools.
658 Understand, however, that a sysroot is still needed for every target
659 since those binaries are target-specific.
660 </para>
661
662 <para>
663 Remember, before using any BitBake command, you
664 must source the build environment setup script
665 (i.e.
666 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
667 or
668 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
669 located in the Source Directory and you must make sure your
670 <filename>conf/local.conf</filename> variables are correct.
671 In particular, you need to be sure the
672 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
673 variable matches the architecture for which you are building and that
674 the
675 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
676 variable is correctly set if you are building a toolchain designed to
677 run on an architecture that differs from your current development host
678 machine (i.e. the build machine).
679 </para>
680
681 <para>
682 When the <filename>bitbake</filename> command completes, the toolchain
683 installer will be in
684 <filename>tmp/deploy/sdk</filename> in the Build Directory.
685 <note>
686 By default, this toolchain does not build static binaries.
687 If you want to use the toolchain to build these types of libraries,
688 you need to be sure your image has the appropriate static
689 development libraries.
690 Use the
691 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
692 variable inside your <filename>local.conf</filename> file to
693 install the appropriate library packages.
694 Following is an example using <filename>glibc</filename> static
695 development libraries:
696 <literallayout class='monospaced'>
697 IMAGE_INSTALL_append = " glibc-staticdev"
698 </literallayout>
699 </note>
700 </para>
701</section>
702
703<section id='optionally-using-an-external-toolchain'>
704 <title>Optionally Using an External Toolchain</title>
705
706 <para>
707 You might want to use an external toolchain as part of your
708 development.
709 If this is the case, the fundamental steps you need to accomplish
710 are as follows:
711 <itemizedlist>
712 <listitem><para>
713 Understand where the installed toolchain resides.
714 For cases where you need to build the external toolchain, you
715 would need to take separate steps to build and install the
716 toolchain.
717 </para></listitem>
718 <listitem><para>
719 Make sure you add the layer that contains the toolchain to
720 your <filename>bblayers.conf</filename> file through the
721 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
722 variable.
723 </para></listitem>
724 <listitem><para>
725 Set the
726 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNAL_TOOLCHAIN'><filename>EXTERNAL_TOOLCHAIN</filename></ulink>
727 variable in your <filename>local.conf</filename> file
728 to the location in which you installed the toolchain.
729 </para></listitem>
730 </itemizedlist>
731 A good example of an external toolchain used with the Yocto Project
732 is <trademark class='registered'>Mentor Graphics</trademark>
733 Sourcery G++ Toolchain.
734 You can see information on how to use that particular layer in the
735 <filename>README</filename> file at
736 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
737 You can find further information by reading about the
738 <ulink url='&YOCTO_DOCS_REF_URL;#var-TCMODE'><filename>TCMODE</filename></ulink>
739 variable in the Yocto Project Reference Manual's variable glossary.
740 </para>
741</section>
742
743 <section id='using-pre-built'>
744 <title>Example Using Pre-Built Binaries and QEMU</title>
745
746 <para>
747 If hardware, libraries and services are stable, you can get started by using a pre-built binary
748 of the filesystem image, kernel, and toolchain and run it using the QEMU emulator.
749 This scenario is useful for developing application software.
750 </para>
751
752 <mediaobject>
753 <imageobject>
754 <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/>
755 </imageobject>
756 <caption>
757 <para>Using a Pre-Built Image</para>
758 </caption>
759 </mediaobject>
760
761 <para>
762 For this scenario, you need to do several things:
763 </para>
764
765 <itemizedlist>
766 <listitem><para>Install the appropriate stand-alone toolchain tarball.</para></listitem>
767 <listitem><para>Download the pre-built image that will boot with QEMU.
768 You need to be sure to get the QEMU image that matches your target machine's
769 architecture (e.g. x86, ARM, etc.).</para></listitem>
770 <listitem><para>Download the filesystem image for your target machine's architecture.
771 </para></listitem>
772 <listitem><para>Set up the environment to emulate the hardware and then start the QEMU emulator.
773 </para></listitem>
774 </itemizedlist>
775
776 <section id='installing-the-toolchain'>
777 <title>Installing the Toolchain</title>
778
779 <para>
780 You can download a tarball installer, which includes the
781 pre-built toolchain, the <filename>runqemu</filename>
782 script, and support files from the appropriate directory under
783 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
784 Toolchains are available for 32-bit and 64-bit x86 development
785 systems from the <filename>i686</filename> and
786 <filename>x86_64</filename> directories, respectively.
787 The toolchains the Yocto Project provides are based off the
788 <filename>core-image-sato</filename> image and contain
789 libraries appropriate for developing against that image.
790 Each type of development system supports five or more target
791 architectures.
792 </para>
793
794 <para>
795 The names of the tarball installer scripts are such that a
796 string representing the host system appears first in the
797 filename and then is immediately followed by a string
798 representing the target architecture.
799 </para>
800
801 <literallayout class='monospaced'>
802 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh
803
804 Where:
805 <replaceable>host_system</replaceable> is a string representing your development system:
806
807 i686 or x86_64.
808
809 <replaceable>image_type</replaceable> is a string representing the image you wish to
810 develop a Software Development Toolkit (SDK) for use against.
811 The Yocto Project builds toolchain installers using the
812 following BitBake command:
813
814 bitbake core-image-sato -c populate_sdk
815
816 <replaceable>arch</replaceable> is a string representing the tuned target architecture:
817
818 i586, x86_64, powerpc, mips, armv7a or armv5te
819
820 <replaceable>release_version</replaceable> is a string representing the release number of the
821 Yocto Project:
822
823 &DISTRO;, &DISTRO;+snapshot
824 </literallayout>
825
826 <para>
827 For example, the following toolchain installer is for a 64-bit
828 development host system and a i586-tuned target architecture
829 based off the SDK for <filename>core-image-sato</filename>:
830 <literallayout class='monospaced'>
831 poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
832 </literallayout>
833 </para>
834
835 <para>
836 Toolchains are self-contained and by default are installed into
837 <filename>/opt/poky</filename>.
838 However, when you run the toolchain installer, you can choose an
839 installation directory.
840 </para>
841
842 <para>
843 The following command shows how to run the installer given a toolchain tarball
844 for a 64-bit x86 development host system and a 32-bit x86 target architecture.
845 You must change the permissions on the toolchain
846 installer script so that it is executable.
847 </para>
848
849 <para>
850 The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>.
851 <note>
852 If you do not have write permissions for the directory into which you are installing
853 the toolchain, the toolchain installer notifies you and exits.
854 Be sure you have write permissions in the directory and run the installer again.
855 </note>
856 </para>
857
858 <para>
859 <literallayout class='monospaced'>
860 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
861 </literallayout>
862 </para>
863
864 <para>
865 For more information on how to install tarballs, see the
866 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and
867 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" sections in the Yocto Project Application Developer's Guide.
868 </para>
869 </section>
870
871 <section id='downloading-the-pre-built-linux-kernel'>
872 <title>Downloading the Pre-Built Linux Kernel</title>
873
874 <para>
875 You can download the pre-built Linux kernel suitable for running in the QEMU emulator from
876 <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.
877 Be sure to use the kernel that matches the architecture you want to simulate.
878 Download areas exist for the five supported machine architectures:
879 <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>,
880 <filename>qemux86</filename>, and <filename>qemux86-64</filename>.
881 </para>
882
883 <para>
884 Most kernel files have one of the following forms:
885 <literallayout class='monospaced'>
886 *zImage-qemu<replaceable>arch</replaceable>.bin
887 vmlinux-qemu<replaceable>arch</replaceable>.bin
888
889 Where:
890 <replaceable>arch</replaceable> is a string representing the target architecture:
891 x86, x86-64, ppc, mips, or arm.
892 </literallayout>
893 </para>
894
895 <para>
896 You can learn more about downloading a Yocto Project kernel in the
897 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>"
898 bulleted item in the Yocto Project Development Manual.
899 </para>
900 </section>
901
902 <section id='downloading-the-filesystem'>
903 <title>Downloading the Filesystem</title>
904
905 <para>
906 You can also download the filesystem image suitable for your target architecture from
907 <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.
908 Again, be sure to use the filesystem that matches the architecture you want
909 to simulate.
910 </para>
911
912 <para>
913 The filesystem image has two tarball forms: <filename>ext3</filename> and
914 <filename>tar</filename>.
915 You must use the <filename>ext3</filename> form when booting an image using the
916 QEMU emulator.
917 The <filename>tar</filename> form can be flattened out in your host development system
918 and used for build purposes with the Yocto Project.
919 <literallayout class='monospaced'>
920 core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.ext3
921 core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.tar.bz2
922
923 Where:
924 <replaceable>profile</replaceable> is the filesystem image's profile:
925 lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato,
926 sato-dev, or sato-sdk. For information on these types of image
927 profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
928 chapter in the Yocto Project Reference Manual.
929
930 <replaceable>arch</replaceable> is a string representing the target architecture:
931 x86, x86-64, ppc, mips, or arm.
932 </literallayout>
933 </para>
934 </section>
935
936 <section id='setting-up-the-environment-and-starting-the-qemu-emulator'>
937 <title>Setting Up the Environment and Starting the QEMU Emulator</title>
938
939 <para>
940 Before you start the QEMU emulator, you need to set up the emulation environment.
941 The following command form sets up the emulation environment.
942 <literallayout class='monospaced'>
943 $ source &YOCTO_ADTPATH_DIR;/environment-setup-<replaceable>arch</replaceable>-poky-linux-<replaceable>if</replaceable>
944
945 Where:
946 <replaceable>arch</replaceable> is a string representing the target architecture:
947 i586, x86_64, ppc603e, mips, or armv5te.
948
949 <replaceable>if</replaceable> is a string representing an embedded application binary interface.
950 Not all setup scripts include this string.
951 </literallayout>
952 </para>
953
954 <para>
955 Finally, this command form invokes the QEMU emulator
956 <literallayout class='monospaced'>
957 $ runqemu <replaceable>qemuarch</replaceable> <replaceable>kernel-image</replaceable> <replaceable>filesystem-image</replaceable>
958
959 Where:
960 <replaceable>qemuarch</replaceable> is a string representing the target architecture: qemux86, qemux86-64,
961 qemuppc, qemumips, or qemuarm.
962
963 <replaceable>kernel-image</replaceable> is the architecture-specific kernel image.
964
965 <replaceable>filesystem-image</replaceable> is the .ext3 filesystem image.
966
967 </literallayout>
968 </para>
969
970 <para>
971 Continuing with the example, the following two commands setup the emulation
972 environment and launch QEMU.
973 This example assumes the root filesystem (<filename>.ext3</filename> file) and
974 the pre-built kernel image file both reside in your home directory.
975 The kernel and filesystem are for a 32-bit target architecture.
976 <literallayout class='monospaced'>
977 $ cd $HOME
978 $ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux
979 $ runqemu qemux86 bzImage-qemux86.bin \
980 core-image-sato-qemux86.ext3
981 </literallayout>
982 </para>
983
984 <para>
985 The environment in which QEMU launches varies depending on the filesystem image and on the
986 target architecture.
987 For example, if you source the environment for the ARM target
988 architecture and then boot the minimal QEMU image, the emulator comes up in a new
989 shell in command-line mode.
990 However, if you boot the SDK image, QEMU comes up with a GUI.
991 <note>Booting the PPC image results in QEMU launching in the same shell in
992 command-line mode.</note>
993 </para>
994 </section>
995</section>
996
997</chapter>
998<!--
999vim: expandtab tw=80 ts=4
1000-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-08-15 20:43:43 +0000