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