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