summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-model.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-model.xml')
-rw-r--r--documentation/dev-manual/dev-manual-model.xml2112
1 files changed, 2112 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
new file mode 100644
index 0000000000..43c31b8405
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -0,0 +1,2112 @@
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='dev-manual-model'>
6
7<title>Common Development Models</title>
8
9<para>
10 Many development models exist for which you can use the Yocto Project.
11 This chapter overviews simple methods that use tools provided by the
12 Yocto Project:
13 <itemizedlist>
14 <listitem><para><emphasis>System Development:</emphasis>
15 System Development covers Board Support Package (BSP) development and kernel
16 modification or configuration.
17 For an example on how to create a BSP, see the
18 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
19 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
20 For more complete information on how to work with the kernel, see the
21 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
22 </para></listitem>
23 <listitem><para><emphasis>User Application Development:</emphasis>
24 User Application Development covers development of applications that you intend
25 to run on target hardware.
26 For information on how to set up your host development system for user-space
27 application development, see the
28 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>.
29 For a simple example of user-space application development using the
30 <trademark class='trade'>Eclipse</trademark> IDE, see the
31 "<link linkend='application-development-workflow'>Application
32 Development Workflow</link>" section.
33 </para></listitem>
34 <listitem><para><emphasis>Temporary Source Code Modification:</emphasis>
35 Direct modification of temporary source code is a convenient development model
36 to quickly iterate and develop towards a solution.
37 Once you implement the solution, you should of course take steps to
38 get the changes upstream and applied in the affected recipes.</para></listitem>
39 <listitem><para><emphasis>Image Development using Hob:</emphasis>
40 You can use the <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build
41 custom operating system images within the build environment.
42 Hob provides an efficient interface to the OpenEmbedded build system.</para></listitem>
43 <listitem><para><emphasis>Using a Development Shell:</emphasis>
44 You can use a <filename>devshell</filename> to efficiently debug commands or simply
45 edit packages.
46 Working inside a development shell is a quick way to set up the OpenEmbedded build
47 environment to work on parts of a project.</para></listitem>
48 </itemizedlist>
49</para>
50
51<section id='system-development-model'>
52 <title>System Development Workflow</title>
53
54 <para>
55 System development involves modification or creation of an image that you want to run on
56 a specific hardware target.
57 Usually, when you want to create an image that runs on embedded hardware, the image does
58 not require the same number of features that a full-fledged Linux distribution provides.
59 Thus, you can create a much smaller image that is designed to use only the
60 features for your particular hardware.
61 </para>
62
63 <para>
64 To help you understand how system development works in the Yocto Project, this section
65 covers two types of image development: BSP creation and kernel modification or
66 configuration.
67 </para>
68
69 <section id='developing-a-board-support-package-bsp'>
70 <title>Developing a Board Support Package (BSP)</title>
71
72 <para>
73 A BSP is a collection of recipes that, when applied during a build, results in
74 an image that you can run on a particular board.
75 Thus, the package when compiled into the new image, supports the operation of the board.
76 </para>
77
78 <note>
79 For a brief list of terms used when describing the development process in the Yocto Project,
80 see the "<link linkend='yocto-project-terms'>Yocto Project Terms</link>" section.
81 </note>
82
83 <para>
84 The remainder of this section presents the basic
85 steps used to create a BSP using the Yocto Project's
86 <ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>BSP Tools</ulink>.
87 Although not required for BSP creation, the
88 <filename>meta-intel</filename> repository, which contains
89 many BSPs supported by the Yocto Project, is part of the example.
90 </para>
91
92 <para>
93 For an example that shows how to create a new layer using the tools, see the
94 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
95 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
96 </para>
97
98 <para>
99 The following illustration and list summarize the BSP creation general workflow.
100 </para>
101
102 <para>
103 <imagedata fileref="figures/bsp-dev-flow.png" width="6in" depth="7in" align="center" scalefit="1" />
104 </para>
105
106 <para>
107 <orderedlist>
108 <listitem><para><emphasis>Set up your host development system to support
109 development using the Yocto Project</emphasis>: See the
110 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>"
111 and the
112 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
113 in the Yocto Project Quick Start for requirements.</para></listitem>
114 <listitem><para><emphasis>Establish a local copy of the project files on your
115 system</emphasis>: You need this <link linkend='source-directory'>Source
116 Directory</link> available on your host system.
117 Having these files on your system gives you access to the build
118 process and to the tools you need.
119 For information on how to set up the Source Directory,
120 see the
121 "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem>
122 <listitem><para><emphasis>Establish the <filename>meta-intel</filename>
123 repository on your system</emphasis>: Having local copies
124 of these supported BSP layers on your system gives you
125 access to layers you might be able to build on or modify
126 to create your BSP.
127 For information on how to get these files, see the
128 "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem>
129 <listitem><para><emphasis>Create your own BSP layer using the
130 <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></ulink> script</emphasis>:
131 Layers are ideal for
132 isolating and storing work for a given piece of hardware.
133 A layer is really just a location or area in which you place
134 the recipes and configurations for your BSP.
135 In fact, a BSP is, in itself, a special type of layer.
136 The simplest way to create a new BSP layer that is compliant with the
137 Yocto Project is to use the <filename>yocto-bsp</filename> script.
138 For information about that script, see the
139 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
140 section in the Yocto Project Board Support (BSP) Developer's Guide.
141 </para>
142 <para>
143 Another example that illustrates a layer is an application.
144 Suppose you are creating an application that has library or other dependencies in
145 order for it to compile and run.
146 The layer, in this case, would be where all the recipes that define those dependencies
147 are kept.
148 The key point for a layer is that it is an isolated area that contains
149 all the relevant information for the project that the OpenEmbedded build
150 system knows about.
151 For more information on layers, see the
152 "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
153 section.
154 For more information on BSP layers, see the
155 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the
156 Yocto Project Board Support Package (BSP) Developer's Guide.</para>
157 <note>Five BSPs exist that are part of the
158 Yocto Project release: <filename>genericx86</filename>, <filename>genericx86-64</filename>,
159 <filename>beaglebone</filename> (ARM),
160 <filename>mpc8315e</filename> (PowerPC),
161 and <filename>edgerouter</filename> (MIPS).
162 The recipes and configurations for these five BSPs are located and dispersed
163 within the <link linkend='source-directory'>Source Directory</link>.
164 On the other hand, the <filename>meta-intel</filename> layer
165 contains BSP layers for many supported BSPs (e.g.
166 Crystal Forest, Emenlow, Fish River Island 2, Haswell,
167 Jasper Forest, and so forth).
168 Aside from the BSPs in the <filename>meta-intel</filename>
169 layer, the
170 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
171 contain additional BSP layers such as
172 <filename>meta-minnow</filename> and
173 <filename>meta-raspberrypi</filename>.</note>
174 <para>When you set up a layer for a new BSP, you should follow a standard layout.
175 This layout is described in the
176 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>"
177 section of the Board Support Package (BSP) Development Guide.
178 In the standard layout, you will notice a suggested structure for recipes and
179 configuration information.
180 You can see the standard layout for a BSP by examining
181 any supported BSP found in the <filename>meta-intel</filename> layer inside
182 the Source Directory.</para></listitem>
183 <listitem><para><emphasis>Make configuration changes to your new BSP
184 layer</emphasis>: The standard BSP layer structure organizes the files you need
185 to edit in <filename>conf</filename> and several <filename>recipes-*</filename>
186 directories within the BSP layer.
187 Configuration changes identify where your new layer is on the local system
188 and identify which kernel you are going to use.
189 When you run the <filename>yocto-bsp</filename> script, you are able to interactively
190 configure many things for the BSP (e.g. keyboard, touchscreen, and so forth).
191 </para></listitem>
192 <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe
193 changes include altering recipes (<filename>.bb</filename> files), removing
194 recipes you do not use, and adding new recipes or append files
195 (<filename>.bbappend</filename>) that you need to support your hardware.
196 </para></listitem>
197 <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the
198 changes to your BSP layer, there remains a few things
199 you need to do for the OpenEmbedded build system in order for it to create your image.
200 You need to get the build environment ready by sourcing an environment setup script
201 (i.e. <filename>oe-init-build-env</filename> or
202 <filename>oe-init-build-env-memres</filename>)
203 and you need to be sure two key configuration files are configured appropriately:
204 the <filename>conf/local.conf</filename> and the
205 <filename>conf/bblayers.conf</filename> file.
206 You must make the OpenEmbedded build system aware of your new layer.
207 See the
208 "<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section
209 for information on how to let the build system know about your new layer.</para>
210 <para>The entire process for building an image is overviewed in the section
211 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
212 of the Yocto Project Quick Start.
213 You might want to reference this information.</para></listitem>
214 <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system
215 uses the BitBake tool to build images based on the type of image you want to create.
216 You can find more information about BitBake in the
217 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
218 </para>
219 <para>The build process supports several types of images to satisfy different needs.
220 See the
221 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
222 in the Yocto Project Reference Manual for information on
223 supported images.</para></listitem>
224 </orderedlist>
225 </para>
226
227 <para>
228 You can view a video presentation on "Building Custom Embedded Images with Yocto"
229 at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>.
230 After going to the page, just search for "Embedded".
231 You can also find supplemental information in the
232 <ulink url='&YOCTO_DOCS_BSP_URL;'>
233 Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
234 Finally, there is a wiki page write up of the example also located
235 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
236 here</ulink> that you might find helpful.
237 </para>
238 </section>
239
240 <section id='modifying-the-kernel'>
241 <title><anchor id='kernel-spot' />Modifying the Kernel</title>
242
243 <para>
244 Kernel modification involves changing the Yocto Project kernel, which could involve changing
245 configuration options as well as adding new kernel recipes.
246 Configuration changes can be added in the form of configuration fragments, while recipe
247 modification comes through the kernel's <filename>recipes-kernel</filename> area
248 in a kernel layer you create.
249 </para>
250
251 <para>
252 The remainder of this section presents a high-level overview of the Yocto Project
253 kernel architecture and the steps to modify the kernel.
254 You can reference the
255 "<link linkend='patching-the-kernel'>Patching the Kernel</link>" section
256 for an example that changes the source code of the kernel.
257 For information on how to configure the kernel, see the
258 "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" section.
259 For more information on the kernel and on modifying the kernel, see the
260 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
261 </para>
262
263 <section id='kernel-overview'>
264 <title>Kernel Overview</title>
265
266 <para>
267 Traditionally, when one thinks of a patched kernel, they think of a base kernel
268 source tree and a fixed structure that contains kernel patches.
269 The Yocto Project, however, employs mechanisms that, in a sense, result in a kernel source
270 generator.
271 By the end of this section, this analogy will become clearer.
272 </para>
273
274 <para>
275 You can find a web interface to the Yocto Project kernel source repositories at
276 <ulink url='&YOCTO_GIT_URL;'></ulink>.
277 If you look at the interface, you will see to the left a grouping of
278 Git repositories titled "Yocto Linux Kernel."
279 Within this group, you will find several kernels supported by
280 the Yocto Project:
281 <itemizedlist>
282 <listitem><para><emphasis>
283 <filename>linux-yocto-3.8</filename></emphasis> - The
284 stable Yocto Project kernel to use with the Yocto
285 Project Release 1.4. This kernel is based on the
286 Linux 3.8 released kernel.
287 </para></listitem>
288 <listitem><para><emphasis>
289 <filename>linux-yocto-3.10</filename></emphasis> - The
290 stable Yocto Project kernel to use with the Yocto
291 Project Release 1.5.
292 This kernel is based on the Linux 3.10 released kernel.
293 </para></listitem>
294 <listitem><para><emphasis>
295 <filename>linux-yocto-3.14</filename></emphasis> - The
296 stable Yocto Project kernel to use with the Yocto
297 Project Releases 1.6 and 1.7.
298 This kernel is based on the Linux 3.14 released kernel.
299 </para></listitem>
300 <listitem><para><emphasis>
301 <filename>linux-yocto-3.17</filename></emphasis> - An
302 additional Yocto Project kernel used with the Yocto
303 Project Release 1.7.
304 This kernel is based on the Linux 3.17 released kernel.
305 </para></listitem>
306 <listitem><para><emphasis>
307 <filename>linux-yocto-dev</filename></emphasis> - A
308 development kernel based on the latest upstream release
309 candidate available.
310 </para></listitem>
311 </itemizedlist>
312 </para>
313
314 <para>
315 The kernels are maintained using the Git revision control system
316 that structures them using the familiar "tree", "branch", and "leaf" scheme.
317 Branches represent diversions from general code to more specific code, while leaves
318 represent the end-points for a complete and unique kernel whose source files,
319 when gathered from the root of the tree to the leaf, accumulate to create the files
320 necessary for a specific piece of hardware and its features.
321 The following figure displays this concept:
322 <para>
323 <imagedata fileref="figures/kernel-overview-1.png"
324 width="6in" depth="6in" align="center" scale="100" />
325 </para>
326
327 <para>
328 Within the figure, the "Kernel.org Branch Point" represents the point in the tree
329 where a supported base kernel is modified from the Linux kernel.
330 For example, this could be the branch point for the <filename>linux-yocto-3.4</filename>
331 kernel.
332 Thus, everything further to the right in the structure is based on the
333 <filename>linux-yocto-3.4</filename> kernel.
334 Branch points to the right in the figure represent where the
335 <filename>linux-yocto-3.4</filename> kernel is modified for specific hardware
336 or types of kernels, such as real-time kernels.
337 Each leaf thus represents the end-point for a kernel designed to run on a specific
338 targeted device.
339 </para>
340
341 <para>
342 The overall result is a Git-maintained repository from which all the supported
343 kernel types can be derived for all the supported devices.
344 A big advantage to this scheme is the sharing of common features by keeping them in
345 "larger" branches within the tree.
346 This practice eliminates redundant storage of similar features shared among kernels.
347 </para>
348
349 <note>
350 Keep in mind the figure does not take into account all the supported Yocto
351 Project kernel types, but rather shows a single generic kernel just for conceptual purposes.
352 Also keep in mind that this structure represents the Yocto Project source repositories
353 that are either pulled from during the build or established on the host development system
354 prior to the build by either cloning a particular kernel's Git repository or by
355 downloading and unpacking a tarball.
356 </note>
357
358 <para>
359 Upstream storage of all the available kernel source code is one thing, while
360 representing and using the code on your host development system is another.
361 Conceptually, you can think of the kernel source repositories as all the
362 source files necessary for all the supported kernels.
363 As a developer, you are just interested in the source files for the kernel on
364 which you are working.
365 And, furthermore, you need them available on your host system.
366 </para>
367
368 <para>
369 Kernel source code is available on your host system a couple of different
370 ways.
371 If you are working in the kernel all the time, you probably would want
372 to set up your own local Git repository of the kernel tree.
373 If you just need to make some patches to the kernel, you can access
374 temporary kernel source files that were extracted and used
375 during a build.
376 We will just talk about working with the temporary source code.
377 For more information on how to get kernel source code onto your
378 host system, see the
379 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
380 bulleted item earlier in the manual.
381 </para>
382
383 <para>
384 What happens during the build?
385 When you build the kernel on your development system, all files needed for the build
386 are taken from the source repositories pointed to by the
387 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> variable
388 and gathered in a temporary work area
389 where they are subsequently used to create the unique kernel.
390 Thus, in a sense, the process constructs a local source tree specific to your
391 kernel to generate the new kernel image - a source generator if you will.
392 </para>
393 The following figure shows the temporary file structure
394 created on your host system when the build occurs.
395 This
396 <link linkend='build-directory'>Build Directory</link> contains all the
397 source files used during the build.
398 </para>
399
400 <para>
401 <imagedata fileref="figures/kernel-overview-2-generic.png"
402 width="6in" depth="5in" align="center" scale="100" />
403 </para>
404
405 <para>
406 Again, for additional information on the Yocto Project kernel's
407 architecture and its branching strategy, see the
408 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
409 You can also reference the
410 "<link linkend='patching-the-kernel'>Patching the Kernel</link>"
411 section for a detailed example that modifies the kernel.
412 </para>
413 </section>
414
415 <section id='kernel-modification-workflow'>
416 <title>Kernel Modification Workflow</title>
417
418 <para>
419 This illustration and the following list summarizes the kernel modification general workflow.
420 </para>
421
422 <para>
423 <imagedata fileref="figures/kernel-dev-flow.png"
424 width="6in" depth="5in" align="center" scalefit="1" />
425 </para>
426
427 <para>
428 <orderedlist>
429 <listitem><para><emphasis>Set up your host development system to support
430 development using the Yocto Project</emphasis>: See
431 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and
432 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
433 in the Yocto Project Quick Start for requirements.</para></listitem>
434 <listitem><para><emphasis>Establish a local copy of project files on your
435 system</emphasis>: Having the <link linkend='source-directory'>Source
436 Directory</link> on your system gives you access to the build process and tools
437 you need.
438 For information on how to get these files, see the bulleted item
439 "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual.
440 </para></listitem>
441 <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>:
442 Temporary kernel source files are kept in the
443 <link linkend='build-directory'>Build Directory</link>
444 created by the
445 OpenEmbedded build system when you run BitBake.
446 If you have never built the kernel in which you are
447 interested, you need to run an initial build to
448 establish local kernel source files.</para>
449 <para>If you are building an image for the first time, you need to get the build
450 environment ready by sourcing an environment setup script
451 (i.e. <filename>oe-init-build-env</filename> or
452 <filename>oe-init-build-env-memres</filename>).
453 You also need to be sure two key configuration files
454 (<filename>local.conf</filename> and <filename>bblayers.conf</filename>)
455 are configured appropriately.</para>
456 <para>The entire process for building an image is overviewed in the
457 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
458 section of the Yocto Project Quick Start.
459 You might want to reference this information.
460 You can find more information on BitBake in the
461 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
462 </para>
463 <para>The build process supports several types of images to satisfy different needs.
464 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
465 the Yocto Project Reference Manual for information on supported images.
466 </para></listitem>
467 <listitem><para><emphasis>Make changes to the kernel source code if
468 applicable</emphasis>: Modifying the kernel does not always mean directly
469 changing source files.
470 However, if you have to do this, you make the changes to the files in the
471 Build Directory.</para></listitem>
472 <listitem><para><emphasis>Make kernel configuration changes
473 if applicable</emphasis>:
474 If your situation calls for changing the kernel's configuration, you can
475 use the <filename>yocto-kernel</filename> script or <filename>menuconfig</filename>
476 to enable and disable kernel configurations.
477 Using the script lets you interactively set up kernel configurations.
478 Using <filename>menuconfig</filename> allows you to interactively develop and test the
479 configuration changes you are making to the kernel.
480 When saved, changes using <filename>menuconfig</filename> update the kernel's
481 <filename>.config</filename> file.
482 Try to resist the temptation of directly editing the <filename>.config</filename>
483 file found in the Build Directory at
484 <filename>tmp/sysroots/&lt;machine-name&gt;/kernel</filename>.
485 Doing so, can produce unexpected results when the OpenEmbedded build system
486 regenerates the configuration file.</para>
487 <para>Once you are satisfied with the configuration changes made using
488 <filename>menuconfig</filename>, you can directly compare the
489 <filename>.config</filename> file against a saved original and gather those
490 changes into a config fragment to be referenced from within the kernel's
491 <filename>.bbappend</filename> file.</para></listitem>
492 <listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>:
493 Rebuilding the kernel image applies your changes.</para></listitem>
494 </orderedlist>
495 </para>
496 </section>
497 </section>
498</section>
499
500<section id='application-development-workflow'>
501 <title>Application Development Workflow</title>
502
503 <para>
504 Application development involves creating an application that you want
505 to run on your target hardware, which is running a kernel image created using the
506 OpenEmbedded build system.
507 The Yocto Project provides an
508 <ulink url='&YOCTO_DOCS_ADT_URL;#adt-intro'>Application Development Toolkit (ADT)</ulink>
509 and stand-alone
510 <ulink url='&YOCTO_DOCS_ADT_URL;#the-cross-development-toolchain'>cross-development toolchains</ulink>
511 that facilitate quick development and integration of your application into its runtime environment.
512 Using the ADT and toolchains, you can compile and link your application.
513 You can then deploy your application to the actual hardware or to the QEMU emulator for testing.
514 If you are familiar with the popular <trademark class='trade'>Eclipse</trademark> IDE,
515 you can use an Eclipse Yocto Plug-in to
516 allow you to develop, deploy, and test your application all from within Eclipse.
517 </para>
518
519 <para>
520 While we strongly suggest using the ADT to develop your application, this option might not
521 be best for you.
522 If this is the case, you can still use pieces of the Yocto Project for your development process.
523 However, because the process can vary greatly, this manual does not provide detail on the process.
524 </para>
525
526 <section id='workflow-using-the-adt-and-eclipse'>
527 <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title>
528
529 <para>
530 To help you understand how application development works using the ADT, this section
531 provides an overview of the general development process and a detailed example of the process
532 as it is used from within the Eclipse IDE.
533 </para>
534
535 <para>
536 The following illustration and list summarize the application development general workflow.
537 </para>
538
539 <para>
540 <imagedata fileref="figures/app-dev-flow.png"
541 width="7in" depth="8in" align="center" scale="100" />
542 </para>
543
544 <para>
545 <orderedlist>
546 <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>:
547 See
548 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
549 and
550 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both
551 in the Yocto Project Reference Manual for requirements.
552 In particular, be sure your host system has the
553 <filename>xterm</filename> package installed.
554 </para></listitem>
555 <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>:
556 You must have a target kernel image that has been built using the OpenEmbedded
557 build system.</para>
558 <para>Depending on whether the Yocto Project has a pre-built image that matches your target
559 architecture and where you are going to run the image while you develop your application
560 (QEMU or real hardware), the area from which you get the image differs.
561 <itemizedlist>
562 <listitem><para>Download the image from
563 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
564 if your target architecture is supported and you are going to develop
565 and test your application on actual hardware.</para></listitem>
566 <listitem><para>Download the image from
567 <ulink url='&YOCTO_QEMU_DL_URL;'>
568 <filename>machines/qemu</filename></ulink> if your target architecture is supported
569 and you are going to develop and test your application using the QEMU
570 emulator.</para></listitem>
571 <listitem><para>Build your image if you cannot find a pre-built image that matches
572 your target architecture.
573 If your target architecture is similar to a supported architecture, you can
574 modify the kernel image before you build it.
575 See the
576 "<link linkend='patching-the-kernel'>Patching the Kernel</link>"
577 section for an example.</para></listitem>
578 </itemizedlist></para>
579 <para>For information on pre-built kernel image naming schemes for images
580 that can run on the QEMU emulator, see the
581 "<ulink url='&YOCTO_DOCS_QS_URL;#downloading-the-pre-built-linux-kernel'>Downloading the Pre-Built Linux Kernel</ulink>"
582 section in the Yocto Project Quick Start.</para></listitem>
583 <listitem><para><emphasis>Install the ADT</emphasis>:
584 The ADT provides a target-specific cross-development toolchain, the root filesystem,
585 the QEMU emulator, and other tools that can help you develop your application.
586 While it is possible to get these pieces separately, the ADT Installer provides an
587 easy, inclusive method.
588 You can get these pieces by running an ADT installer script, which is configurable.
589 For information on how to install the ADT, see the
590 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Using the ADT Installer</ulink>"
591 section
592 in the Yocto Project Application Developer's Guide.</para></listitem>
593 <listitem><para><emphasis>If applicable, secure the target root filesystem
594 and the Cross-development toolchain</emphasis>:
595 If you choose not to install the ADT using the ADT Installer,
596 you need to find and download the appropriate root filesystem and
597 the cross-development toolchain.</para>
598 <para>You can find the tarballs for the root filesystem in the same area used
599 for the kernel image.
600 Depending on the type of image you are running, the root filesystem you need differs.
601 For example, if you are developing an application that runs on an image that
602 supports Sato, you need to get a root filesystem that supports Sato.</para>
603 <para>You can find the cross-development toolchains at
604 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
605 Be sure to get the correct toolchain for your development host and your
606 target architecture.
607 See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
608 section in the Yocto Project Application Developer's Guide for information
609 and the
610 "<ulink url='&YOCTO_DOCS_QS_URL;#installing-the-toolchain'>Installing the Toolchain</ulink>"
611 in the Yocto Project Quick Start for information on finding and installing
612 the correct toolchain based on your host development system and your target
613 architecture.
614 </para></listitem>
615 <listitem><para><emphasis>Create and build your application</emphasis>:
616 At this point, you need to have source files for your application.
617 Once you have the files, you can use the Eclipse IDE to import them and build the
618 project.
619 If you are not using Eclipse, you need to use the cross-development tools you have
620 installed to create the image.</para></listitem>
621 <listitem><para><emphasis>Deploy the image with the application</emphasis>:
622 If you are using the Eclipse IDE, you can deploy your image to the hardware or to
623 QEMU through the project's preferences.
624 If you are not using the Eclipse IDE, then you need to deploy the application
625 to the hardware using other methods.
626 Or, if you are using QEMU, you need to use that tool and
627 load your image in for testing.
628 See the
629 "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
630 chapter for information on using QEMU.
631 </para></listitem>
632 <listitem><para><emphasis>Test and debug the application</emphasis>:
633 Once your application is deployed, you need to test it.
634 Within the Eclipse IDE, you can use the debugging environment along with the
635 set of user-space tools installed along with the ADT to debug your application.
636 Of course, the same user-space tools are available separately if you choose
637 not to use the Eclipse IDE.</para></listitem>
638 </orderedlist>
639 </para>
640 </section>
641
642 <section id='adt-eclipse'>
643 <title>Working Within Eclipse</title>
644
645 <para>
646 The Eclipse IDE is a popular development environment and it fully
647 supports development using the Yocto Project.
648 <note>
649 This release of the Yocto Project supports both the Kepler
650 and Juno versions of the Eclipse IDE.
651 Thus, the following information provides setup information for
652 both versions.
653 </note>
654 </para>
655
656 <para>
657 When you install and configure the Eclipse Yocto Project Plug-in
658 into the Eclipse IDE, you maximize your Yocto Project experience.
659 Installing and configuring the Plug-in results in an environment
660 that has extensions specifically designed to let you more easily
661 develop software.
662 These extensions allow for cross-compilation, deployment, and
663 execution of your output into a QEMU emulation session as well as
664 actual target hardware.
665 You can also perform cross-debugging and profiling.
666 The environment also supports a suite of tools that allows you
667 to perform remote profiling, tracing, collection of power data,
668 collection of latency data, and collection of performance data.
669 </para>
670
671 <para>
672 This section describes how to install and configure the Eclipse IDE
673 Yocto Plug-in and how to use it to develop your application.
674 </para>
675
676 <section id='setting-up-the-eclipse-ide'>
677 <title>Setting Up the Eclipse IDE</title>
678
679 <para>
680 To develop within the Eclipse IDE, you need to do the following:
681 <orderedlist>
682 <listitem><para>Install the optimal version of the Eclipse
683 IDE.</para></listitem>
684 <listitem><para>Configure the Eclipse IDE.
685 </para></listitem>
686 <listitem><para>Install the Eclipse Yocto Plug-in.
687 </para></listitem>
688 <listitem><para>Configure the Eclipse Yocto Plug-in.
689 </para></listitem>
690 </orderedlist>
691 <note>
692 Do not install Eclipse from your distribution's package
693 repository.
694 Be sure to install Eclipse from the official Eclipse
695 download site as directed in the next section.
696 </note>
697 </para>
698
699 <section id='installing-eclipse-ide'>
700 <title>Installing the Eclipse IDE</title>
701
702 <para>
703 It is recommended that you have the Kepler 4.3.2 version of
704 the Eclipse IDE installed on your development system.
705 However, if you currently have the Juno 4.2 version
706 installed and you do not want to upgrade the IDE, you can
707 configure Juno to work with the Yocto Project.
708 </para>
709
710 <para>
711 If you do not have the Kepler 4.3.2 Eclipse IDE installed,
712 you can find the tarball at
713 <ulink url='&ECLIPSE_MAIN_URL;'></ulink>.
714 From that site, choose the Eclipse Standard 4.3.2 version
715 particular to your development host.
716 This version contains the Eclipse Platform, the Java
717 Development Tools (JDT), and the Plug-in Development
718 Environment.
719 </para>
720
721 <para>
722 Once you have downloaded the tarball, extract it into a
723 clean directory.
724 For example, the following commands unpack and install the
725 downloaded Eclipse IDE tarball into a clean directory
726 using the default name <filename>eclipse</filename>:
727 <literallayout class='monospaced'>
728 $ cd ~
729 $ tar -xzvf ~/Downloads/eclipse-standard-kepler-SR2-linux-gtk-x86_64.tar.gz
730 </literallayout>
731 </para>
732 </section>
733
734 <section id='configuring-the-eclipse-ide'>
735 <title>Configuring the Eclipse IDE</title>
736
737 <para>
738 This section presents the steps needed to configure the
739 Eclipse IDE.
740 </para>
741
742 <para>
743 Before installing and configuring the Eclipse Yocto Plug-in,
744 you need to configure the Eclipse IDE.
745 Follow these general steps:
746 <orderedlist>
747 <listitem><para>Start the Eclipse IDE.</para></listitem>
748 <listitem><para>Make sure you are in your Workbench and
749 select "Install New Software" from the "Help"
750 pull-down menu.</para></listitem>
751 <listitem><para>Select
752 <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename>
753 from the "Work with:" pull-down menu.
754 <note>
755 For Juno, select
756 <filename>Juno - &ECLIPSE_JUNO_URL;</filename>
757 </note>
758 </para></listitem>
759 <listitem><para>Expand the box next to "Linux Tools"
760 and select the
761 <filename>LTTng - Linux Tracing Toolkit</filename>
762 boxes.</para></listitem>
763 <listitem><para>Expand the box next to "Mobile and
764 Device Development" and select the following boxes:
765 <itemizedlist>
766 <listitem><para><filename>C/C++ Remote Launch (Requires RSE Remote System Explorer)</filename></para></listitem>
767 <listitem><para><filename>Remote System Explorer End-user Runtime</filename></para></listitem>
768 <listitem><para><filename>Remote System Explorer User Actions</filename></para></listitem>
769 <listitem><para><filename>Target Management Terminal</filename></para></listitem>
770 <listitem><para><filename>TCF Remote System Explorer add-in</filename></para></listitem>
771 <listitem><para><filename>TCF Target Explorer</filename></para></listitem>
772 </itemizedlist></para></listitem>
773 <listitem><para>Expand the box next to "Programming
774 Languages" and select the
775 <filename>C/C++ Autotools Support</filename>
776 and <filename>C/C++ Development Tools</filename>
777 boxes.</para></listitem>
778 <listitem><para>Complete the installation and restart
779 the Eclipse IDE.</para></listitem>
780 </orderedlist>
781 </para>
782 </section>
783
784 <section id='installing-the-eclipse-yocto-plug-in'>
785 <title>Installing or Accessing the Eclipse Yocto Plug-in</title>
786
787 <para>
788 You can install the Eclipse Yocto Plug-in into the Eclipse
789 IDE one of two ways: use the Yocto Project's Eclipse
790 Update site to install the pre-built plug-in or build and
791 install the plug-in from the latest source code.
792 </para>
793
794 <section id='new-software'>
795 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
796
797 <para>
798 To install the Eclipse Yocto Plug-in from the update
799 site, follow these steps:
800 <orderedlist>
801 <listitem><para>Start up the Eclipse IDE.
802 </para></listitem>
803 <listitem><para>In Eclipse, select "Install New
804 Software" from the "Help" menu.
805 </para></listitem>
806 <listitem><para>Click "Add..." in the "Work with:"
807 area.</para></listitem>
808 <listitem><para>Enter
809 <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename>
810 in the URL field and provide a meaningful name
811 in the "Name" field.
812 <note>
813 If you are using Juno, use
814 <filename>&ECLIPSE_DL_PLUGIN_URL;/juno</filename>
815 in the URL field.
816 </note></para></listitem>
817 <listitem><para>Click "OK" to have the entry added
818 to the "Work with:" drop-down list.
819 </para></listitem>
820 <listitem><para>Select the entry for the plug-in
821 from the "Work with:" drop-down list.
822 </para></listitem>
823 <listitem><para>Check the boxes next to
824 <filename>Yocto Project ADT Plug-in</filename>,
825 <filename>Yocto Project Bitbake Commander Plug-in</filename>,
826 and
827 <filename>Yocto Project Documentation plug-in</filename>.
828 </para></listitem>
829 <listitem><para>Complete the remaining software
830 installation steps and then restart the Eclipse
831 IDE to finish the installation of the plug-in.
832 </para></listitem>
833 </orderedlist>
834 </para>
835 </section>
836
837 <section id='zip-file-method'>
838 <title>Installing the Plug-in Using the Latest Source Code</title>
839
840 <para>
841 To install the Eclipse Yocto Plug-in from the latest
842 source code, follow these steps:
843 <orderedlist>
844 <listitem><para>Be sure your development system
845 is not using OpenJDK to build the plug-in
846 by doing the following:
847 <orderedlist>
848 <listitem><para>Use the Oracle JDK.
849 If you don't have that, go to
850 <ulink url='http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html'></ulink>
851 and download the appropriate tarball
852 for your development system and
853 extract it into your home directory.
854 </para></listitem>
855 <listitem><para>In the shell you are going
856 to do your work, export the location of
857 the Oracle Java as follows:
858 <literallayout class='monospaced'>
859 export PATH=~/jdk1.7.0_40/bin:$PATH
860 </literallayout></para></listitem>
861 </orderedlist></para></listitem>
862 <listitem><para>In the same shell, create a Git
863 repository with:
864 <literallayout class='monospaced'>
865 $ cd ~
866 $ git clone git://git.yoctoproject.org/eclipse-poky-kepler
867 </literallayout>
868 <note>
869 If you are using Juno, the repository is
870 located at
871 <filename>git://git.yoctoproject.org/eclipse-poky-juno</filename>.
872 </note>
873 For this example, the repository is named
874 <filename>~/eclipse-poky-kepler</filename>.
875 </para></listitem>
876 <listitem><para>Change to the directory where you
877 set up the Git repository:
878 <literallayout class='monospaced'>
879 $ cd ~/eclipse-poky-kepler
880 </literallayout></para></listitem>
881 <listitem><para>Be sure you are in the right branch
882 for your Git repository.
883 For this release set the branch to
884 <filename>&DISTRO_NAME;</filename>:
885 <literallayout class='monospaced'>
886 $ git checkout &DISTRO_NAME;
887 </literallayout></para></listitem>
888 <listitem><para>Change to the
889 <filename>scripts</filename>
890 directory within the Git repository:
891 <literallayout class='monospaced'>
892 $ cd scripts
893 </literallayout></para></listitem>
894 <listitem><para>Set up the local build environment
895 by running the setup script:
896 <literallayout class='monospaced'>
897 $ ./setup.sh
898 </literallayout></para></listitem>
899 <listitem><para>When the script finishes execution,
900 it prompts you with instructions on how to run
901 the <filename>build.sh</filename> script, which
902 is also in the <filename>scripts</filename>
903 directory of
904 the Git repository created earlier.
905 </para></listitem>
906 <listitem><para>Run the <filename>build.sh</filename> script
907 as directed.
908 Be sure to provide the name of the Git branch
909 along with the Yocto Project release you are
910 using.
911 Here is an example that uses the
912 <filename>&DISTRO_NAME;</filename> branch:
913 <literallayout class='monospaced'>
914 $ ECLIPSE_HOME=/home/scottrif/eclipse-poky-kepler/scripts/eclipse ./build.sh &DISTRO_NAME; &DISTRO_NAME;
915 </literallayout>
916 After running the script, the file
917 <filename>org.yocto.sdk-&lt;release&gt;-&lt;date&gt;-archive.zip</filename>
918 is in the current directory.</para></listitem>
919 <listitem><para>If necessary, start the Eclipse IDE
920 and be sure you are in the Workbench.
921 </para></listitem>
922 <listitem><para>Select "Install New Software" from the "Help" pull-down menu.
923 </para></listitem>
924 <listitem><para>Click "Add".</para></listitem>
925 <listitem><para>Provide anything you want in the
926 "Name" field.</para></listitem>
927 <listitem><para>Click "Archive" and browse to the
928 ZIP file you built in step eight.
929 This ZIP file should not be "unzipped", and must
930 be the <filename>*archive.zip</filename> file
931 created by running the
932 <filename>build.sh</filename> script.
933 </para></listitem>
934 <listitem><para>Click through the "Okay" buttons.
935 </para></listitem>
936 <listitem><para>Check the boxes
937 in the installation window and complete
938 the installation.</para></listitem>
939 <listitem><para>Restart the Eclipse IDE if
940 necessary.</para></listitem>
941 </orderedlist>
942 </para>
943
944 <para>
945 At this point you should be able to configure the
946 Eclipse Yocto Plug-in as described in the
947 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>"
948 section.</para>
949 </section>
950 </section>
951
952 <section id='configuring-the-eclipse-yocto-plug-in'>
953 <title>Configuring the Eclipse Yocto Plug-in</title>
954
955 <para>
956 Configuring the Eclipse Yocto Plug-in involves setting the
957 Cross Compiler options and the Target options.
958 The configurations you choose become the default settings
959 for all projects.
960 You do have opportunities to change them later when
961 you configure the project (see the following section).
962 </para>
963
964 <para>
965 To start, you need to do the following from within the
966 Eclipse IDE:
967 <itemizedlist>
968 <listitem><para>Choose "Preferences" from the
969 "Windows" menu to display the Preferences Dialog.
970 </para></listitem>
971 <listitem><para>Click "Yocto Project ADT".
972 </para></listitem>
973 </itemizedlist>
974 </para>
975
976 <section id='configuring-the-cross-compiler-options'>
977 <title>Configuring the Cross-Compiler Options</title>
978
979 <para>
980 To configure the Cross Compiler Options, you must select
981 the type of toolchain, point to the toolchain, specify
982 the sysroot location, and select the target
983 architecture.
984 <itemizedlist>
985 <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
986 Choose between
987 <filename>Standalone pre-built toolchain</filename>
988 and
989 <filename>Build system derived toolchain</filename>
990 for Cross Compiler Options.
991 <itemizedlist>
992 <listitem><para><emphasis>
993 <filename>Standalone Pre-built Toolchain:</filename></emphasis>
994 Select this mode when you are using
995 a stand-alone cross-toolchain.
996 For example, suppose you are an
997 application developer and do not
998 need to build a target image.
999 Instead, you just want to use an
1000 architecture-specific toolchain on
1001 an existing kernel and target root
1002 filesystem.</para></listitem>
1003 <listitem><para><emphasis>
1004 <filename>Build System Derived Toolchain:</filename></emphasis>
1005 Select this mode if the
1006 cross-toolchain has been installed
1007 and built as part of the
1008 <link linkend='build-directory'>Build Directory</link>.
1009 When you select
1010 <filename>Build system derived toolchain</filename>,
1011 you are using the toolchain bundled
1012 inside the Build Directory.
1013 </para></listitem>
1014 </itemizedlist>
1015 </para></listitem>
1016 <listitem><para><emphasis>Point to the Toolchain:</emphasis>
1017 If you are using a stand-alone pre-built
1018 toolchain, you should be pointing to where it is
1019 installed.
1020 If you used the ADT Installer script and
1021 accepted the default installation directory, the
1022 toolchain will be installed in the
1023 <filename>&YOCTO_ADTPATH_DIR;</filename>
1024 directory.
1025 Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring and Running the ADT Installer Script</ulink>"
1026 and
1027 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
1028 in the Yocto Project Application Developer's
1029 Guide describe how to install a stand-alone
1030 cross-toolchain.</para>
1031 <para>If you are using a system-derived
1032 toolchain, the path you provide for the
1033 <filename>Toolchain Root Location</filename>
1034 field is the
1035 <link linkend='build-directory'>Build Directory</link>.
1036 See the
1037 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>"
1038 section in the Yocto Project Application
1039 Developer's Guide for information on how to
1040 install the toolchain into the Build
1041 Directory.</para></listitem>
1042 <listitem><para><emphasis>Specify the Sysroot Location:</emphasis>
1043 This location is where the root filesystem for
1044 the target hardware resides.
1045 If you used the ADT Installer script and
1046 accepted the default installation directory,
1047 then the location is
1048 <filename>/opt/poky/&DISTRO;</filename>.
1049 Additionally, when you use the ADT Installer
1050 script, the same location is used for the QEMU
1051 user-space tools and the NFS boot process.
1052 </para>
1053 <para>If you used either of the other two
1054 methods to install the toolchain or did not
1055 accept the ADT Installer script's default
1056 installation directory, then the location of
1057 the sysroot filesystem depends on where you
1058 separately extracted and installed the
1059 filesystem.</para>
1060 <para>For information on how to install the
1061 toolchain and on how to extract and install the
1062 sysroot filesystem, see the
1063 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
1064 section in the Yocto Project Application
1065 Developer's Guide.
1066 </para></listitem>
1067 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
1068 The target architecture is the type of hardware
1069 you are going to use or emulate.
1070 Use the pull-down
1071 <filename>Target Architecture</filename> menu
1072 to make your selection.
1073 The pull-down menu should have the supported
1074 architectures.
1075 If the architecture you need is not listed in
1076 the menu, you will need to build the image.
1077 See the
1078 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1079 section of the Yocto Project Quick Start for
1080 more information.</para></listitem>
1081 </itemizedlist>
1082 </para>
1083 </section>
1084
1085 <section id='configuring-the-target-options'>
1086 <title>Configuring the Target Options</title>
1087
1088 <para>
1089 You can choose to emulate hardware using the QEMU
1090 emulator, or you can choose to run your image on actual
1091 hardware.
1092 <itemizedlist>
1093 <listitem><para><emphasis>QEMU:</emphasis>
1094 Select this option if you will be using the
1095 QEMU emulator.
1096 If you are using the emulator, you also need to
1097 locate the kernel and specify any custom
1098 options.</para>
1099 <para>If you selected
1100 <filename>Build system derived toolchain</filename>,
1101 the target kernel you built will be located in
1102 the Build Directory in
1103 <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
1104 directory.
1105 If you selected
1106 <filename>Standalone pre-built toolchain</filename>,
1107 the pre-built image you downloaded is located
1108 in the directory you specified when you
1109 downloaded the image.</para>
1110 <para>Most custom options are for advanced QEMU
1111 users to further customize their QEMU instance.
1112 These options are specified between paired
1113 angled brackets.
1114 Some options must be specified outside the
1115 brackets.
1116 In particular, the options
1117 <filename>serial</filename>,
1118 <filename>nographic</filename>, and
1119 <filename>kvm</filename> must all be outside the
1120 brackets.
1121 Use the <filename>man qemu</filename> command
1122 to get help on all the options and their use.
1123 The following is an example:
1124 <literallayout class='monospaced'>
1125 serial ‘&lt;-m 256 -full-screen&gt;’
1126 </literallayout></para>
1127 <para>
1128 Regardless of the mode, Sysroot is already
1129 defined as part of the Cross-Compiler Options
1130 configuration in the
1131 <filename>Sysroot Location:</filename> field.
1132 </para></listitem>
1133 <listitem><para><emphasis>External HW:</emphasis>
1134 Select this option if you will be using actual
1135 hardware.</para></listitem>
1136 </itemizedlist>
1137 </para>
1138
1139 <para>
1140 Click the "OK" to save your plug-in configurations.
1141 </para>
1142 </section>
1143 </section>
1144 </section>
1145
1146 <section id='creating-the-project'>
1147 <title>Creating the Project</title>
1148
1149 <para>
1150 You can create two types of projects: Autotools-based, or
1151 Makefile-based.
1152 This section describes how to create Autotools-based projects
1153 from within the Eclipse IDE.
1154 For information on creating Makefile-based projects in a
1155 terminal window, see the section
1156 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>"
1157 in the Yocto Project Application Developer's Guide.
1158 <note>
1159 Do not use special characters in project names
1160 (e.g. spaces, underscores, etc.). Doing so can
1161 cause configuration to fail.
1162 </note>
1163 </para>
1164
1165 <para>
1166 To create a project based on a Yocto template and then display
1167 the source code, follow these steps:
1168 <orderedlist>
1169 <listitem><para>Select "Project" from the "File -> New" menu.
1170 </para></listitem>
1171 <listitem><para>Double click <filename>CC++</filename>.
1172 </para></listitem>
1173 <listitem><para>Double click <filename>C Project</filename>
1174 to create the project.</para></listitem>
1175 <listitem><para>Expand <filename>Yocto Project ADT Project</filename>.
1176 </para></listitem>
1177 <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>.
1178 This is an Autotools-based project based on a Yocto
1179 template.</para></listitem>
1180 <listitem><para>Put a name in the <filename>Project name:</filename>
1181 field.
1182 Do not use hyphens as part of the name.
1183 </para></listitem>
1184 <listitem><para>Click "Next".</para></listitem>
1185 <listitem><para>Add information in the
1186 <filename>Author</filename> and
1187 <filename>Copyright notice</filename> fields.
1188 </para></listitem>
1189 <listitem><para>Be sure the <filename>License</filename>
1190 field is correct.</para></listitem>
1191 <listitem><para>Click "Finish".</para></listitem>
1192 <listitem><para>If the "open perspective" prompt appears,
1193 click "Yes" so that you in the C/C++ perspective.
1194 </para></listitem>
1195 <listitem><para>The left-hand navigation pane shows your
1196 project.
1197 You can display your source by double clicking the
1198 project's source file.</para></listitem>
1199 </orderedlist>
1200 </para>
1201 </section>
1202
1203 <section id='configuring-the-cross-toolchains'>
1204 <title>Configuring the Cross-Toolchains</title>
1205
1206 <para>
1207 The earlier section,
1208 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>",
1209 sets up the default project configurations.
1210 You can override these settings for a given project by following
1211 these steps:
1212 <orderedlist>
1213 <listitem><para>Select "Change Yocto Project Settings" from
1214 the "Project" menu.
1215 This selection brings up the Yocto Project Settings
1216 Dialog and allows you to make changes specific to an
1217 individual project.</para>
1218 <para>By default, the Cross Compiler Options and Target
1219 Options for a project are inherited from settings you
1220 provided using the Preferences Dialog as described
1221 earlier in the
1222 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" section.
1223 The Yocto Project Settings Dialog allows you to override
1224 those default settings for a given project.
1225 </para></listitem>
1226 <listitem><para>Make your configurations for the project
1227 and click "OK".
1228 If you are running the Juno version of Eclipse, you can
1229 skip down to the next section where you build the
1230 project.
1231 If you are not working with Juno, you need to reconfigure the
1232 project as described in the next step.
1233 </para></listitem>
1234 <listitem><para>Select "Reconfigure Project" from the
1235 "Project" menu.
1236 This selection reconfigures the project by running
1237 <filename>autogen.sh</filename> in the workspace for
1238 your project.
1239 The script also runs <filename>libtoolize</filename>,
1240 <filename>aclocal</filename>,
1241 <filename>autoconf</filename>,
1242 <filename>autoheader</filename>,
1243 <filename>automake --a</filename>, and
1244 <filename>./configure</filename>.
1245 Click on the "Console" tab beneath your source code to
1246 see the results of reconfiguring your project.
1247 </para></listitem>
1248 </orderedlist>
1249 </para>
1250 </section>
1251
1252 <section id='building-the-project'>
1253 <title>Building the Project</title>
1254
1255 <para>
1256 To build the project in Juno, right click on the project in
1257 the navigator pane and select "Build Project".
1258 If you are not running Juno, select "Build Project" from the
1259 "Project" menu.
1260 The console should update and you can note the cross-compiler
1261 you are using.
1262 </para>
1263 </section>
1264
1265 <section id='starting-qemu-in-user-space-nfs-mode'>
1266 <title>Starting QEMU in User-Space NFS Mode</title>
1267
1268 <para>
1269 To start the QEMU emulator from within Eclipse, follow these
1270 steps:
1271 <note>
1272 See the
1273 "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
1274 chapter for more information on using QEMU.
1275 </note>
1276 <orderedlist>
1277 <listitem><para>Expose and select "External Tools" from
1278 the "Run" menu.
1279 Your image should appear as a selectable menu item.
1280 </para></listitem>
1281 <listitem><para>Select your image from the menu to launch
1282 the emulator in a new window.</para></listitem>
1283 <listitem><para>If needed, enter your host root password in
1284 the shell window at the prompt.
1285 This sets up a <filename>Tap 0</filename> connection
1286 needed for running in user-space NFS mode.
1287 </para></listitem>
1288 <listitem><para>Wait for QEMU to launch.</para></listitem>
1289 <listitem><para>Once QEMU launches, you can begin operating
1290 within that environment.
1291 For example, you could determine the IP Address
1292 for the user-space NFS by using the
1293 <filename>ifconfig</filename> command.</para></listitem>
1294 </orderedlist>
1295 </para>
1296 </section>
1297
1298 <section id='deploying-and-debugging-the-application'>
1299 <title>Deploying and Debugging the Application</title>
1300
1301 <para>
1302 Once the QEMU emulator is running the image, you can deploy
1303 your application using the Eclipse IDE and then use
1304 the emulator to perform debugging.
1305 Follow these steps to deploy the application.
1306 <orderedlist>
1307 <listitem><para>Select "Debug Configurations..." from the
1308 "Run" menu.</para></listitem>
1309 <listitem><para>In the left area, expand
1310 <filename>C/C++Remote Application</filename>.
1311 </para></listitem>
1312 <listitem><para>Locate your project and select it to bring
1313 up a new tabbed view in the Debug Configurations Dialog.
1314 </para></listitem>
1315 <listitem><para>Enter the absolute path into which you want
1316 to deploy the application.
1317 Use the "Remote Absolute File Path for
1318 C/C++Application:" field.
1319 For example, enter
1320 <filename>/usr/bin/&lt;programname&gt;</filename>.
1321 </para></listitem>
1322 <listitem><para>Click on the "Debugger" tab to see the
1323 cross-tool debugger you are using.</para></listitem>
1324 <listitem><para>Click on the "Main" tab.</para></listitem>
1325 <listitem><para>Create a new connection to the QEMU instance
1326 by clicking on "new".</para></listitem>
1327 <listitem><para>Select <filename>TCF</filename>, which means
1328 Target Communication Framework.</para></listitem>
1329 <listitem><para>Click "Next".</para></listitem>
1330 <listitem><para>Clear out the "host name" field and enter
1331 the IP Address determined earlier.</para></listitem>
1332 <listitem><para>Click "Finish" to close the
1333 New Connections Dialog.</para></listitem>
1334 <listitem><para>Use the drop-down menu now in the
1335 "Connection" field and pick the IP Address you entered.
1336 </para></listitem>
1337 <listitem><para>Click "Run" to bring up a login screen
1338 and login.</para></listitem>
1339 <listitem><para>Accept the debug perspective.
1340 </para></listitem>
1341 </orderedlist>
1342 </para>
1343 </section>
1344
1345 <section id='running-user-space-tools'>
1346 <title>Running User-Space Tools</title>
1347
1348 <para>
1349 As mentioned earlier in the manual, several tools exist that
1350 enhance your development experience.
1351 These tools are aids in developing and debugging applications
1352 and images.
1353 You can run these user-space tools from within the Eclipse
1354 IDE through the "YoctoTools" menu.
1355 </para>
1356
1357 <para>
1358 Once you pick a tool, you need to configure it for the remote
1359 target.
1360 Every tool needs to have the connection configured.
1361 You must select an existing TCF-based RSE connection to the
1362 remote target.
1363 If one does not exist, click "New" to create one.
1364 </para>
1365
1366 <para>
1367 Here are some specifics about the remote tools:
1368 <itemizedlist>
1369 <listitem><para><emphasis><filename>OProfile</filename>:</emphasis>
1370 Selecting this tool causes the
1371 <filename>oprofile-server</filename> on the remote
1372 target to launch on the local host machine.
1373 The <filename>oprofile-viewer</filename> must be
1374 installed on the local host machine and the
1375 <filename>oprofile-server</filename> must be installed
1376 on the remote target, respectively, in order to use.
1377 You must compile and install the
1378 <filename>oprofile-viewer</filename> from the source
1379 code on your local host machine.
1380 Furthermore, in order to convert the target's sample
1381 format data into a form that the host can use, you must
1382 have OProfile version 0.9.4 or greater installed on the
1383 host.</para>
1384 <para>You can locate both the viewer and server from
1385 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>.
1386 You can also find more information on setting up and
1387 using this tool in the
1388 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>"
1389 section of the Yocto Project Profiling and Tracing
1390 Manual.
1391 <note>The <filename>oprofile-server</filename> is
1392 installed by default on the
1393 <filename>core-image-sato-sdk</filename> image.</note>
1394 </para></listitem>
1395 <listitem><para><emphasis><filename>Lttng2.0 ust trace import</filename>:</emphasis>
1396 Selecting this tool transfers the remote target's
1397 <filename>Lttng</filename> tracing data back to the
1398 local host machine and uses the Lttng Eclipse plug-in
1399 to graphically display the output.
1400 For information on how to use Lttng to trace an
1401 application,
1402 see <ulink url='http://lttng.org/documentation'></ulink>
1403 and the
1404 "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>"
1405 section, which is in the Yocto Project Profiling and
1406 Tracing Manual.
1407 <note>Do not use
1408 <filename>Lttng-user space (legacy)</filename> tool.
1409 This tool no longer has any upstream support.</note>
1410 </para>
1411 <para>Before you use the
1412 <filename>Lttng2.0 ust trace import</filename> tool,
1413 you need to setup the Lttng Eclipse plug-in and create a
1414 Tracing project.
1415 Do the following:
1416 <orderedlist>
1417 <listitem><para>Select "Open Perspective" from the
1418 "Window" menu and then select "Tracing".
1419 </para></listitem>
1420 <listitem><para>Click "OK" to change the Eclipse
1421 perspective into the Tracing perspective.
1422 </para></listitem>
1423 <listitem><para>Create a new Tracing project by
1424 selecting "Project" from the "File -> New" menu.
1425 </para></listitem>
1426 <listitem><para>Choose "Tracing Project" from the
1427 "Tracing" menu.
1428 </para></listitem>
1429 <listitem><para>Generate your tracing data on the
1430 remote target.</para></listitem>
1431 <listitem><para>Select "Lttng2.0 ust trace import"
1432 from the "Yocto Project Tools" menu to
1433 start the data import process.</para></listitem>
1434 <listitem><para>Specify your remote connection name.
1435 </para></listitem>
1436 <listitem><para>For the Ust directory path, specify
1437 the location of your remote tracing data.
1438 Make sure the location ends with
1439 <filename>ust</filename> (e.g.
1440 <filename>/usr/mysession/ust</filename>).
1441 </para></listitem>
1442 <listitem><para>Click "OK" to complete the import
1443 process.
1444 The data is now in the local tracing project
1445 you created.</para></listitem>
1446 <listitem><para>Right click on the data and then use
1447 the menu to Select "Generic CTF Trace" from the
1448 "Trace Type... -> Common Trace Format" menu to
1449 map the tracing type.</para></listitem>
1450 <listitem><para>Right click the mouse and select
1451 "Open" to bring up the Eclipse Lttng Trace
1452 Viewer so you view the tracing data.
1453 </para></listitem>
1454 </orderedlist></para></listitem>
1455 <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis>
1456 Selecting this tool runs PowerTOP on the remote target
1457 machine and displays the results in a new view called
1458 PowerTOP.</para>
1459 <para>The "Time to gather data(sec):" field is the time
1460 passed in seconds before data is gathered from the
1461 remote target for analysis.</para>
1462 <para>The "show pids in wakeups list:" field corresponds
1463 to the <filename>-p</filename> argument passed to
1464 <filename>PowerTOP</filename>.</para></listitem>
1465 <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis>
1466 LatencyTOP identifies system latency, while
1467 Perf monitors the system's performance counter
1468 registers.
1469 Selecting either of these tools causes an RSE terminal
1470 view to appear from which you can run the tools.
1471 Both tools refresh the entire screen to display results
1472 while they run.
1473 For more information on setting up and using
1474 <filename>perf</filename>, see the
1475 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>"
1476 section in the Yocto Project Profiling and Tracing
1477 Manual.
1478 </para></listitem>
1479 </itemizedlist>
1480 </para>
1481 </section>
1482
1483 <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'>
1484 <title>Customizing an Image Using a BitBake Commander Project and Hob</title>
1485
1486 <para>
1487 Within the Eclipse IDE, you can create a Yocto BitBake Commander
1488 project, edit the <link linkend='metadata'>Metadata</link>, and
1489 then use
1490 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build a customized image all within one IDE.
1491 </para>
1492
1493 <section id='creating-the-yocto-bitbake-commander-project'>
1494 <title>Creating the Yocto BitBake Commander Project</title>
1495
1496 <para>
1497 To create a Yocto BitBake Commander project, follow these
1498 steps:
1499 <orderedlist>
1500 <listitem><para>Select "Other" from the
1501 "Window -> Open Perspective" menu
1502 and then choose "Bitbake Commander".
1503 </para></listitem>
1504 <listitem><para>Click "OK" to change the perspective to
1505 Bitbake Commander.</para></listitem>
1506 <listitem><para>Select "Project" from the "File -> New"
1507 menu to create a new Yocto
1508 Bitbake Commander project.</para></listitem>
1509 <listitem><para>Choose "New Yocto Project" from the
1510 "Yocto Project Bitbake Commander" menu and click
1511 "Next".</para></listitem>
1512 <listitem><para>Enter the Project Name and choose the
1513 Project Location.
1514 The Yocto project's Metadata files will be put under
1515 the directory
1516 <filename><replaceable>project_location</replaceable>/<replaceable>project_name</replaceable></filename>.
1517 If that directory does not exist, you need to check
1518 the "Clone from Yocto Git Repository" box, which
1519 would execute a <filename>git clone</filename>
1520 command to get the project's Metadata files.
1521 <note>
1522 Do not specify your BitBake Commander project
1523 location as your Eclipse workspace.
1524 Doing so causes an error indicating that the
1525 current project overlaps the location of
1526 another project.
1527 This error occurs even if no such project exits.
1528 </note></para></listitem>
1529 <listitem><para>Select <filename>Finish</filename> to
1530 create the project.</para></listitem>
1531 </orderedlist>
1532 </para>
1533 </section>
1534
1535 <section id='editing-the-metadata'>
1536 <title>Editing the Metadata</title>
1537
1538 <para>
1539 After you create the Yocto Bitbake Commander project, you
1540 can modify the <link linkend='metadata'>Metadata</link>
1541 files by opening them in the project.
1542 When editing recipe files (<filename>.bb</filename> files),
1543 you can view BitBake variable values and information by
1544 hovering the mouse pointer over the variable name and
1545 waiting a few seconds.
1546 </para>
1547
1548 <para>
1549 To edit the Metadata, follow these steps:
1550 <orderedlist>
1551 <listitem><para>Select your Yocto Bitbake Commander
1552 project.</para></listitem>
1553 <listitem><para>Select "BitBake Recipe" from the
1554 "File -> New -> Yocto BitBake Commander" menu
1555 to open a new recipe wizard.</para></listitem>
1556 <listitem><para>Point to your source by filling in the
1557 "SRC_URL" field.
1558 For example, you can add a recipe to your
1559 <link linkend='source-directory'>Source Directory</link>
1560 by defining "SRC_URL" as follows:
1561 <literallayout class='monospaced'>
1562 ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz
1563 </literallayout></para></listitem>
1564 <listitem><para>Click "Populate" to calculate the
1565 archive md5, sha256, license checksum values and to
1566 auto-generate the recipe filename.</para></listitem>
1567 <listitem><para>Fill in the "Description" field.
1568 </para></listitem>
1569 <listitem><para>Be sure values for all required
1570 fields exist.</para></listitem>
1571 <listitem><para>Click "Finish".</para></listitem>
1572 </orderedlist>
1573 </para>
1574 </section>
1575
1576 <section id='biding-and-customizing-the-image-using-hob'>
1577 <title>Building and Customizing the Image Using Hob</title>
1578
1579 <para>
1580 To build and customize the image using Hob from within the
1581 Eclipse IDE, follow these steps:
1582 <orderedlist>
1583 <listitem><para>Select your Yocto Bitbake Commander
1584 project.</para></listitem>
1585 <listitem><para>Select "Launch Hob" from the "Project"
1586 menu.</para></listitem>
1587 <listitem><para>Enter the
1588 <link linkend='build-directory'>Build Directory</link>
1589 where you want to put your final images.
1590 </para></listitem>
1591 <listitem><para>Click "OK" to launch Hob.
1592 </para></listitem>
1593 <listitem><para>Use Hob to customize and build your own
1594 images.
1595 For information on Hob, see the
1596 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob Project Page</ulink>
1597 on the Yocto Project website.</para></listitem>
1598 </orderedlist>
1599 </para>
1600 </section>
1601 </section>
1602 </section>
1603
1604 <section id='workflow-using-stand-alone-cross-development-toolchains'>
1605 <title>Workflow Using Stand-Alone Cross-Development Toolchains</title>
1606
1607 <para>
1608 If you want to develop an application without prior installation
1609 of the ADT, you still can employ the
1610 <link linkend='cross-development-toolchain'>Cross Development Toolchain</link>,
1611 the QEMU emulator, and a number of supported target image files.
1612 You just need to follow these general steps:
1613 <orderedlist>
1614 <listitem><para><emphasis>Install the cross-development
1615 toolchain for your target hardware:</emphasis>
1616 For information on how to install the toolchain, see the
1617 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
1618 section in the Yocto Project Application Developer's
1619 Guide.</para></listitem>
1620 <listitem><para><emphasis>Download the Target Image:</emphasis>
1621 The Yocto Project supports several target architectures
1622 and has many pre-built kernel images and root filesystem
1623 images.</para>
1624 <para>If you are going to develop your application on
1625 hardware, go to the
1626 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
1627 download area and choose a target machine area
1628 from which to download the kernel image and root filesystem.
1629 This download area could have several files in it that
1630 support development using actual hardware.
1631 For example, the area might contain
1632 <filename>.hddimg</filename> files that combine the
1633 kernel image with the filesystem, boot loaders, and
1634 so forth.
1635 Be sure to get the files you need for your particular
1636 development process.</para>
1637 <para>If you are going to develop your application and
1638 then run and test it using the QEMU emulator, go to the
1639 <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink>
1640 download area.
1641 From this area, go down into the directory for your
1642 target architecture (e.g. <filename>qemux86_64</filename>
1643 for an <trademark class='registered'>Intel</trademark>-based
1644 64-bit architecture).
1645 Download kernel, root filesystem, and any other files you
1646 need for your process.
1647 <note>In order to use the root filesystem in QEMU, you
1648 need to extract it.
1649 See the
1650 "<ulink url='&YOCTO_DOCS_ADT_URL;#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>"
1651 section for information on how to extract the root
1652 filesystem.</note></para></listitem>
1653 <listitem><para><emphasis>Develop and Test your
1654 Application:</emphasis> At this point, you have the tools
1655 to develop your application.
1656 If you need to separately install and use the QEMU
1657 emulator, you can go to
1658 <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink>
1659 to download and learn about the emulator.
1660 You can see the
1661 "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
1662 chapter for information on using QEMU within the Yocto
1663 Project.</para></listitem>
1664 </orderedlist>
1665 </para>
1666 </section>
1667</section>
1668
1669<section id="modifying-temporary-source-code">
1670 <title>Modifying Temporary Source Code</title>
1671
1672 <para>
1673 You might
1674 find it helpful during development to modify the temporary source code used by recipes
1675 to build packages.
1676 For example, suppose you are developing a patch and you need to experiment a bit
1677 to figure out your solution.
1678 After you have initially built the package, you can iteratively tweak the
1679 source code, which is located in the
1680 <link linkend='build-directory'>Build Directory</link>, and then
1681 you can force a re-compile and quickly test your altered code.
1682 Once you settle on a solution, you can then preserve your changes in the form of
1683 patches.
1684 You can accomplish these steps all within either a
1685 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or
1686 <link linkend='git'>Git</link> workflow.
1687 </para>
1688
1689 <section id='finding-the-temporary-source-code'>
1690 <title>Finding the Temporary Source Code</title>
1691
1692 <para>
1693 During a build, the unpacked temporary source code used by recipes
1694 to build packages is available in the Build Directory as
1695 defined by the
1696 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable.
1697 Below is the default value for the <filename>S</filename> variable as defined in the
1698 <filename>meta/conf/bitbake.conf</filename> configuration file in the
1699 <link linkend='source-directory'>Source Directory</link>:
1700 <literallayout class='monospaced'>
1701 S = "${WORKDIR}/${BP}"
1702 </literallayout>
1703 You should be aware that many recipes override the <filename>S</filename> variable.
1704 For example, recipes that fetch their source from Git usually set
1705 <filename>S</filename> to <filename>${WORKDIR}/git</filename>.
1706 <note>
1707 The
1708 <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink>
1709 represents the base recipe name, which consists of the name and version:
1710 <literallayout class='monospaced'>
1711 BP = "${BPN}-${PV}"
1712 </literallayout>
1713 </note>
1714 </para>
1715
1716 <para>
1717 The path to the work directory for the recipe
1718 (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>)
1719 is defined as follows:
1720 <literallayout class='monospaced'>
1721 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
1722 </literallayout>
1723 The actual directory depends on several things:
1724 <itemizedlist>
1725 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1726 The top-level build output directory</listitem>
1727 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1728 The target system identifier</listitem>
1729 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1730 The recipe name</listitem>
1731 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1732 The epoch - (if
1733 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1734 is not specified, which is usually the case for most
1735 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1736 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1737 The recipe version</listitem>
1738 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1739 The recipe revision</listitem>
1740 </itemizedlist>
1741 </para>
1742
1743 <para>
1744 As an example, assume a Source Directory top-level folder
1745 name <filename>poky</filename>, a default Build Directory at
1746 <filename>poky/build</filename>, and a
1747 <filename>qemux86-poky-linux</filename> machine target
1748 system.
1749 Furthermore, suppose your recipe is named
1750 <filename>foo_1.3.0.bb</filename>.
1751 In this case, the work directory the build system uses to
1752 build the package would be as follows:
1753 <literallayout class='monospaced'>
1754 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1755 </literallayout>
1756 </para>
1757
1758 <para>
1759 Now that you know where to locate the directory that has the temporary source code,
1760 you can use a Quilt or Git workflow to make your edits, test the changes,
1761 and preserve the changes in the form of patches.
1762 </para>
1763 </section>
1764
1765 <section id="using-a-quilt-workflow">
1766 <title>Using a Quilt Workflow</title>
1767
1768 <para>
1769 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
1770 is a powerful tool that allows you to capture source code changes without having
1771 a clean source tree.
1772 This section outlines the typical workflow you can use to modify temporary source code,
1773 test changes, and then preserve the changes in the form of a patch all using Quilt.
1774 </para>
1775
1776 <para>
1777 Follow these general steps:
1778 <orderedlist>
1779 <listitem><para><emphasis>Find the Source Code:</emphasis>
1780 The temporary source code used by the OpenEmbedded build system is kept in the
1781 Build Directory.
1782 See the
1783 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1784 section to learn how to locate the directory that has the temporary source code for a
1785 particular package.</para></listitem>
1786 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
1787 You need to be in the directory that has the temporary source code.
1788 That directory is defined by the
1789 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1790 variable.</para></listitem>
1791 <listitem><para><emphasis>Create a New Patch:</emphasis>
1792 Before modifying source code, you need to create a new patch.
1793 To create a new patch file, use <filename>quilt new</filename> as below:
1794 <literallayout class='monospaced'>
1795 $ quilt new my_changes.patch
1796 </literallayout></para></listitem>
1797 <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis>
1798 After creating the patch, you need to notify Quilt about the files
1799 you plan to edit.
1800 You notify Quilt by adding the files to the patch you just created:
1801 <literallayout class='monospaced'>
1802 $ quilt add file1.c file2.c file3.c
1803 </literallayout>
1804 </para></listitem>
1805 <listitem><para><emphasis>Edit the Files:</emphasis>
1806 Make your changes in the temporary source code to the files you added
1807 to the patch.</para></listitem>
1808 <listitem><para><emphasis>Test Your Changes:</emphasis>
1809 Once you have modified the source code, the easiest way to
1810 your changes is by calling the
1811 <filename>do_compile</filename> task as shown in the
1812 following example:
1813 <literallayout class='monospaced'>
1814 $ bitbake -c compile -f <replaceable>name_of_package</replaceable>
1815 </literallayout>
1816 The <filename>-f</filename> or <filename>--force</filename>
1817 option forces the specified task to execute.
1818 If you find problems with your code, you can just keep editing and
1819 re-testing iteratively until things work as expected.
1820 <note>All the modifications you make to the temporary source code
1821 disappear once you run the
1822 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>
1823 or
1824 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>
1825 tasks using BitBake (i.e.
1826 <filename>bitbake -c clean <replaceable>name_of_package</replaceable></filename>
1827 and
1828 <filename>bitbake -c cleanall <replaceable>name_of_package</replaceable></filename>).
1829 Modifications will also disappear if you use the <filename>rm_work</filename>
1830 feature as described in the
1831 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1832 section of the Yocto Project Quick Start.
1833 </note></para></listitem>
1834 <listitem><para><emphasis>Generate the Patch:</emphasis>
1835 Once your changes work as expected, you need to use Quilt to generate the final patch that
1836 contains all your modifications.
1837 <literallayout class='monospaced'>
1838 $ quilt refresh
1839 </literallayout>
1840 At this point, the <filename>my_changes.patch</filename> file has all your edits made
1841 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1842 <filename>file3.c</filename> files.</para>
1843 <para>You can find the resulting patch file in the <filename>patches/</filename>
1844 subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
1845 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1846 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1847 which you can create in the same directory that holds the recipe
1848 (<filename>.bb</filename>) file or the
1849 append (<filename>.bbappend</filename>) file.
1850 Placing the patch here guarantees that the OpenEmbedded build system will find
1851 the patch.
1852 Next, add the patch into the
1853 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1854 of the recipe.
1855 Here is an example:
1856 <literallayout class='monospaced'>
1857 SRC_URI += "file://my_changes.patch"
1858 </literallayout></para></listitem>
1859 <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis>
1860 Finally, don't forget to 'bump' the
1861 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1862 value in the recipe since the resulting packages have changed.</para></listitem>
1863 </orderedlist>
1864 </para> </section>
1865
1866 <section id='using-a-git-workflow'>
1867 <title>Using a Git Workflow</title>
1868 <para>
1869 Git is an even more powerful tool that allows you to capture source code changes without having
1870 a clean source tree.
1871 This section outlines the typical workflow you can use to modify temporary source code,
1872 test changes, and then preserve the changes in the form of a patch all using Git.
1873 For general information on Git as it is used in the Yocto Project, see the
1874 "<link linkend='git'>Git</link>" section.
1875 </para>
1876
1877 <note>
1878 This workflow uses Git only for its ability to manage local changes to the source code
1879 and produce patches independent of any version control system used with the Yocto Project.
1880 </note>
1881
1882 <para>
1883 Follow these general steps:
1884 <orderedlist>
1885 <listitem><para><emphasis>Find the Source Code:</emphasis>
1886 The temporary source code used by the OpenEmbedded build system is kept in the
1887 Build Directory.
1888 See the
1889 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1890 section to learn how to locate the directory that has the temporary source code for a
1891 particular package.</para></listitem>
1892 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
1893 You need to be in the directory that has the temporary source code.
1894 That directory is defined by the
1895 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1896 variable.</para></listitem>
1897 <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis>
1898 If the recipe you are working with does not use a Git fetcher,
1899 you need to set up a Git repository as follows:
1900 <literallayout class='monospaced'>
1901 $ git init
1902 $ git add *
1903 $ git commit -m "initial revision"
1904 </literallayout>
1905 The above Git commands initialize a Git repository that is based on the
1906 files in your current working directory, stage all the files, and commit
1907 the files.
1908 At this point, your Git repository is aware of all the source code files.
1909 Any edits you now make to files can be committed later and will be tracked by
1910 Git.</para></listitem>
1911 <listitem><para><emphasis>Edit the Files:</emphasis>
1912 Make your changes to the temporary source code.</para></listitem>
1913 <listitem><para><emphasis>Test Your Changes:</emphasis>
1914 Once you have modified the source code, the easiest way
1915 to test your changes is by calling the
1916 <filename>do_compile</filename> task as shown in the
1917 following example:
1918 <literallayout class='monospaced'>
1919 $ bitbake -c compile -f <replaceable>name_of_package</replaceable>
1920 </literallayout>
1921 The <filename>-f</filename> or <filename>--force</filename>
1922 option forces the specified task to execute.
1923 If you find problems with your code, you can just keep editing and
1924 re-testing iteratively until things work as expected.
1925 <note>All the modifications you make to the temporary source code
1926 disappear once you <filename>-c clean</filename>, <filename>-c cleansstate</filename>,
1927 or <filename>-c cleanall</filename> with BitBake for the package.
1928 Modifications will also disappear if you use the <filename>rm_work</filename>
1929 feature as described in the
1930 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1931 section of the Yocto Project Quick Start.
1932 </note></para></listitem>
1933 <listitem><para><emphasis>See the List of Files You Changed:</emphasis>
1934 Use the <filename>git status</filename> command to see what files you have actually edited.
1935 The ability to have Git track the files you have changed is an advantage that this
1936 workflow has over the Quilt workflow.
1937 Here is the Git command to list your changed files:
1938 <literallayout class='monospaced'>
1939 $ git status
1940 </literallayout></para></listitem>
1941 <listitem><para><emphasis>Stage the Modified Files:</emphasis>
1942 Use the <filename>git add</filename> command to stage the changed files so they
1943 can be committed as follows:
1944 <literallayout class='monospaced'>
1945 $ git add file1.c file2.c file3.c
1946 </literallayout></para></listitem>
1947 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
1948 Use the <filename>git commit</filename> command to commit the changes to the
1949 local repository.
1950 Once you have committed the files, you can use the <filename>git log</filename>
1951 command to see your changes:
1952 <literallayout class='monospaced'>
1953 $ git commit -m "<replaceable>commit-summary-message</replaceable>"
1954 $ git log
1955 </literallayout>
1956 <note>The name of the patch file created in the next step is based on your
1957 <replaceable>commit-summary-message</replaceable>.</note></para></listitem>
1958 <listitem><para><emphasis>Generate the Patch:</emphasis>
1959 Once the changes are committed, use the <filename>git format-patch</filename>
1960 command to generate a patch file:
1961 <literallayout class='monospaced'>
1962 $ git format-patch -1
1963 </literallayout>
1964 Specifying "-1" causes Git to generate the
1965 patch file for the most recent commit.</para>
1966 <para>At this point, the patch file has all your edits made
1967 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1968 <filename>file3.c</filename> files.
1969 You can find the resulting patch file in the current directory and it
1970 is named according to the <filename>git commit</filename> summary line.
1971 The patch file ends with <filename>.patch</filename>.</para></listitem>
1972 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1973 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1974 which you can create in the same directory that holds the recipe
1975 (<filename>.bb</filename>) file or the
1976 append (<filename>.bbappend</filename>) file.
1977 Placing the patch here guarantees that the OpenEmbedded build system will find
1978 the patch.
1979 Next, add the patch into the
1980 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1981 of the recipe.
1982 Here is an example:
1983 <literallayout class='monospaced'>
1984 SRC_URI += "file://0001-<replaceable>commit-summary-message</replaceable>.patch"
1985 </literallayout></para></listitem>
1986 <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis>
1987 Finally, don't forget to 'bump' the
1988 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1989 value in the recipe since the resulting packages have changed.</para></listitem>
1990 </orderedlist>
1991 </para>
1992 </section>
1993</section>
1994
1995<section id='image-development-using-hob'>
1996 <title>Image Development Using Hob</title>
1997
1998 <para>
1999 The <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> is a graphical user interface for the
2000 OpenEmbedded build system, which is based on BitBake.
2001 You can use the Hob to build custom operating system images within the Yocto Project build environment.
2002 Hob simply provides a friendly interface over the build system used during development.
2003 In other words, building images with the Hob lets you take care of common build tasks more easily.
2004 </para>
2005
2006 <para>
2007 For a better understanding of Hob, see the project page at
2008 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'></ulink>
2009 on the Yocto Project website.
2010 If you follow the "Documentation" link from the Hob page, you will
2011 find a short introductory training video on Hob.
2012 The following lists some features of Hob:
2013 <itemizedlist>
2014 <listitem><para>You can setup and run Hob using these commands:
2015 <literallayout class='monospaced'>
2016 $ source oe-init-build-env
2017 $ hob
2018 </literallayout></para></listitem>
2019 <listitem><para>You can set the
2020 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
2021 for which you are building the image.</para></listitem>
2022 <listitem><para>You can modify various policy settings such as the
2023 package format with which to build,
2024 the parallelism BitBake uses, whether or not to build an
2025 external toolchain, and which host to build against.
2026 </para></listitem>
2027 <listitem><para>You can manage
2028 <link linkend='understanding-and-creating-layers'>layers</link>.</para></listitem>
2029 <listitem><para>You can select a base image and then add extra packages for your custom build.
2030 </para></listitem>
2031 <listitem><para>You can launch and monitor the build from within Hob.</para></listitem>
2032 </itemizedlist>
2033 </para>
2034</section>
2035
2036<section id="platdev-appdev-devshell">
2037 <title>Using a Development Shell</title>
2038
2039 <para>
2040 When debugging certain commands or even when just editing packages,
2041 <filename>devshell</filename> can be a useful tool.
2042 When you invoke <filename>devshell</filename>, source files are
2043 extracted into your working directory and patches are applied.
2044 Then, a new terminal is opened and you are placed in the working directory.
2045 In the new terminal, all the OpenEmbedded build-related environment variables are
2046 still defined so you can use commands such as <filename>configure</filename> and
2047 <filename>make</filename>.
2048 The commands execute just as if the OpenEmbedded build system were executing them.
2049 Consequently, working this way can be helpful when debugging a build or preparing
2050 software to be used with the OpenEmbedded build system.
2051 </para>
2052
2053 <para>
2054 Following is an example that uses <filename>devshell</filename> on a target named
2055 <filename>matchbox-desktop</filename>:
2056 <literallayout class='monospaced'>
2057 $ bitbake matchbox-desktop -c devshell
2058 </literallayout>
2059 </para>
2060
2061 <para>
2062 This command spawns a terminal with a shell prompt within the OpenEmbedded build environment.
2063 The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
2064 variable controls what type of shell is opened.
2065 </para>
2066
2067 <para>
2068 For spawned terminals, the following occurs:
2069 <itemizedlist>
2070 <listitem><para>The <filename>PATH</filename> variable includes the
2071 cross-toolchain.</para></listitem>
2072 <listitem><para>The <filename>pkgconfig</filename> variables find the correct
2073 <filename>.pc</filename> files.</para></listitem>
2074 <listitem><para>The <filename>configure</filename> command finds the
2075 Yocto Project site files as well as any other necessary files.</para></listitem>
2076 </itemizedlist>
2077 </para>
2078
2079 <para>
2080 Within this environment, you can run configure or compile
2081 commands as if they were being run by
2082 the OpenEmbedded build system itself.
2083 As noted earlier, the working directory also automatically changes to the
2084 Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
2085 </para>
2086
2087 <para>
2088 When you are finished, you just exit the shell or close the terminal window.
2089 </para>
2090
2091 <note>
2092 <para>
2093 It is worth remembering that when using <filename>devshell</filename>
2094 you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename>
2095 instead of just using <filename>gcc</filename>.
2096 The same applies to other applications such as <filename>binutils</filename>,
2097 <filename>libtool</filename> and so forth.
2098 BitBake sets up environment variables such as <filename>CC</filename>
2099 to assist applications, such as <filename>make</filename> to find the correct tools.
2100 </para>
2101
2102 <para>
2103 It is also worth noting that <filename>devshell</filename> still works over
2104 X11 forwarding and similar situations.
2105 </para>
2106 </note>
2107</section>
2108
2109</chapter>
2110<!--
2111vim: expandtab tw=80 ts=4
2112-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-19 04:34:59 +0000