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