summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-07-23 11:23:56 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-07-24 10:35:34 +0100
commit41c7020d7ae6c81e8fa092f2a0c8e0c3ac976a62 (patch)
treeebc327616f0ceff8ba21fbf1004e6c85038e3982
parentfad4b8fbbdab7a9701e63475317a804188376c27 (diff)
downloadpoky-41c7020d7ae6c81e8fa092f2a0c8e0c3ac976a62.tar.gz
documentation: Moved the Eclipse chapter to the YP Dev Manual.
The detailed chapter that describes how to install and configure the Eclipse Yocto Plug-in has been moved to become a subsection of the "Workflow" chapter in the YP Development Manual. This commit accomplished the bulk move, edits to integrate the information, and fixes to all cross-references. Moving the chapter creates a sectioning issue in the YP Development manual that results in subsections that are six levels deep. Not ideal. Will look at fixing these with a subsequent commit. (From yocto-docs rev: e6abff8f578f2cf6997895260f607395281ae8e8) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/adt-manual/adt-eclipse.xml740
-rw-r--r--documentation/adt-manual/adt-intro.xml20
-rw-r--r--documentation/adt-manual/adt-manual.xml2
-rw-r--r--documentation/dev-manual/dev-manual-model.xml739
4 files changed, 754 insertions, 747 deletions
diff --git a/documentation/adt-manual/adt-eclipse.xml b/documentation/adt-manual/adt-eclipse.xml
deleted file mode 100644
index 4d400ad6df..0000000000
--- a/documentation/adt-manual/adt-eclipse.xml
+++ /dev/null
@@ -1,740 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='adt-eclipse'>
6<title>Working Within Eclipse</title>
7
8 <para>
9 The Eclipse IDE is a popular development environment and it fully supports
10 development using the Yocto Project.
11 When you install and configure the Eclipse Yocto Project Plug-in into
12 the Eclipse IDE, you maximize your Yocto Project experience.
13 Installing and configuring the Plug-in results in an environment that
14 has extensions specifically designed to let you more easily develop software.
15 These extensions allow for cross-compilation, deployment, and execution of
16 your output into a QEMU emulation session.
17 You can also perform cross-debugging and profiling.
18 The environment also supports a suite of tools that allows you to perform
19 remote profiling, tracing, collection of power data, collection of
20 latency data, and collection of performance data.
21 </para>
22 <para>
23 This section describes how to install and configure the Eclipse IDE
24 Yocto Plug-in and how to use it to develop your application.
25 </para>
26
27<section id='setting-up-the-eclipse-ide'>
28 <title>Setting Up the Eclipse IDE</title>
29
30 <para>
31 To develop within the Eclipse IDE, you need to do the following:
32 <orderedlist>
33 <listitem><para>Install the optimal version of the Eclipse IDE.</para></listitem>
34 <listitem><para>Configure the Eclipse IDE.</para></listitem>
35 <listitem><para>Install the Eclipse Yocto Plug-in.</para></listitem>
36 <listitem><para>Configure the Eclipse Yocto Plug-in.</para></listitem>
37 </orderedlist>
38 <note>
39 Do not install Eclipse from your distribution's package repository.
40 Be sure to install Eclipse from the official Eclipse download site as directed
41 in the next section.
42 </note>
43 </para>
44
45 <section id='installing-eclipse-ide'>
46 <title>Installing the Eclipse IDE</title>
47
48 <para>
49 It is recommended that you have the Indigo 3.7.2 version of the
50 Eclipse IDE installed on your development system.
51 If you don’t have this version, you can find it at
52 <ulink url='&ECLIPSE_MAIN_URL;'></ulink>.
53 From that site, choose the Eclipse Classic version particular to your development
54 host.
55 This version contains the Eclipse Platform, the Java Development
56 Tools (JDT), and the Plug-in Development Environment.
57 </para>
58
59 <para>
60 Once you have downloaded the tarball, extract it into a clean
61 directory.
62 For example, the following commands unpack and install the Eclipse IDE
63 tarball found in the <filename>Downloads</filename> area
64 into a clean directory using the default name <filename>eclipse</filename>:
65 <literallayout class='monospaced'>
66 $ cd ~
67 $ tar -xzvf ~/Downloads/eclipse-SDK-3.7.2-linux-gtk-x86_64.tar.gz
68 </literallayout>
69 </para>
70
71 <para>
72 One issue exists that you need to be aware of regarding the Java
73 Virtual machine’s garbage collection (GC) process.
74 The GC process does not clean up the permanent generation
75 space (PermGen).
76 This space stores metadata descriptions of classes.
77 The default value is set too small and it could trigger an
78 out-of-memory error such as the following:
79 <literallayout class='monospaced'>
80 Java.lang.OutOfMemoryError: PermGen space
81 </literallayout>
82 </para>
83
84 <para>
85 This error causes the application to hang.
86 </para>
87
88 <para>
89 To fix this issue, you can use the <filename>--vmargs</filename>
90 option when you start Eclipse to increase the size of the permanent generation space:
91 <literallayout class='monospaced'>
92 eclipse --vmargs --XX:PermSize=256M
93 </literallayout>
94 </para>
95 </section>
96
97 <section id='configuring-the-eclipse-ide'>
98 <title>Configuring the Eclipse IDE</title>
99
100 <para>
101 Before installing and configuring the Eclipse Yocto Plug-in, you need to configure
102 the Eclipse IDE.
103 Follow these general steps to configure Eclipse:
104 <orderedlist>
105 <listitem><para>Start the Eclipse IDE.</para></listitem>
106 <listitem><para>Make sure you are in your Workbench and select
107 "Install New Software" from the "Help" pull-down menu.
108 </para></listitem>
109 <listitem><para>Select <filename>indigo - &ECLIPSE_INDIGO_URL;</filename>
110 from the "Work with:" pull-down menu.</para></listitem>
111 <listitem><para>Expand the box next to <filename>Programming Languages</filename>
112 and select the <filename>Autotools Support for CDT (incubation)</filename>
113 and <filename>C/C++ Development Tools</filename> boxes.</para></listitem>
114 <listitem><para>Expand the box next to "Linux Tools" and select the
115 "LTTng - Linux Tracing Toolkit(incubation)" boxes.</para></listitem>
116 <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
117 <listitem><para>After the Eclipse IDE restarts and from the Workbench, select
118 "Install New Software" from the "Help" pull-down menu.</para></listitem>
119 <listitem><para>Click the
120 "Available Software Sites" link.</para></listitem>
121 <listitem><para>Check the box next to
122 <filename>&ECLIPSE_UPDATES_URL;</filename>
123 and click "OK".</para></listitem>
124 <listitem><para>Select <filename>&ECLIPSE_UPDATES_URL;</filename>
125 from the "Work with:" pull-down menu.</para></listitem>
126 <listitem><para>Check the box next to <filename>TM and RSE Main Features</filename>.
127 </para></listitem>
128 <listitem><para>Expand the box next to <filename>TM and RSE Optional Add-ons</filename>
129 and select every item except <filename>RSE Unit Tests</filename> and
130 <filename>RSE WinCE Services (incubation)</filename>.</para></listitem>
131 <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
132 <listitem><para>If necessary, select
133 "Install New Software" from the "Help" pull-down menu so you can click the
134 "Available Software Sites" link again.</para></listitem>
135 <listitem><para>After clicking "Available Software Sites", check the box next to
136 <filename>http://download.eclipse.org/tools/cdt/releases/indigo</filename>
137 and click "OK".</para></listitem>
138 <listitem><para>Select <filename>&ECLIPSE_INDIGO_CDT_URL;</filename>
139 from the "Work with:" pull-down menu.</para></listitem>
140 <listitem><para>Check the box next to <filename>CDT Main Features</filename>.
141 </para></listitem>
142 <listitem><para>Expand the box next to <filename>CDT Optional Features</filename>
143 and select <filename>C/C++ Remote Launch</filename> and
144 <filename>Target Communication Framework (incubation)</filename>.</para></listitem>
145 <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
146 </orderedlist>
147 </para>
148 </section>
149
150 <section id='installing-the-eclipse-yocto-plug-in'>
151 <title>Installing or Accessing the Eclipse Yocto Plug-in</title>
152
153 <para>
154 You can install the Eclipse Yocto Plug-in into the Eclipse IDE
155 one of two ways: use the Yocto Project's Eclipse Update site to install the pre-built plug-in,
156 or build and install the plug-in from the latest source code.
157 If you don't want to permanently install the plug-in but just want to try it out
158 within the Eclipse environment, you can import the plug-in project from the
159 Yocto Project source repositories.
160 </para>
161
162 <section id='new-software'>
163 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
164
165 <para>
166 To install the Eclipse Yocto Plug-in from the update site,
167 follow these steps:
168 <orderedlist>
169 <listitem><para>Start up the Eclipse IDE.</para></listitem>
170 <listitem><para>In Eclipse, select "Install New Software" from the "Help" menu.</para></listitem>
171 <listitem><para>Click "Add..." in the "Work with:" area.</para></listitem>
172 <listitem><para>Enter
173 <filename>&ECLIPSE_DL_PLUGIN_URL;</filename>
174 in the URL field and provide a meaningful name in the "Name" field.</para></listitem>
175 <listitem><para>Click "OK" to have the entry added to the "Work with:"
176 drop-down list.</para></listitem>
177 <listitem><para>Select the entry for the plug-in from the "Work with:" drop-down
178 list.</para></listitem>
179 <listitem><para>Check the box next to <filename>Development tools and SDKs for Yocto Linux</filename>.
180 </para></listitem>
181 <listitem><para>Complete the remaining software installation steps and
182 then restart the Eclipse IDE to finish the installation of the plug-in.
183 </para></listitem>
184 </orderedlist>
185 </para>
186 </section>
187
188 <section id='zip-file-method'>
189 <title>Installing the Plug-in Using the Latest Source Code</title>
190 <para>
191 To install the Eclipse Yocto Plug-in from the latest source code, follow these steps:
192 <orderedlist>
193 <listitem><para>Open a shell and create a Git repository with:
194 <literallayout class='monospaced'>
195 $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse
196 </literallayout>
197 For this example, the repository is named
198 <filename>~/yocto-eclipse</filename>.</para></listitem>
199 <listitem><para>Locate the <filename>build.sh</filename> script in the
200 Git repository you created in the previous step.
201 The script is located in the <filename>scripts</filename>.</para></listitem>
202 <listitem><para>Be sure to set and export the <filename>ECLIPSE_HOME</filename> environment
203 variable to the top-level directory in which you installed the Indigo
204 version of Eclipse.
205 For example, if your Eclipse directory is <filename>$HOME/eclipse</filename>,
206 use the following:
207 <literallayout class='monospaced'>
208 $ export ECLIPSE_HOME=$HOME/eclipse
209 </literallayout></para></listitem>
210 <listitem><para>Run the <filename>build.sh</filename> script and provide the
211 name of the Git branch along with the Yocto Project release you are
212 using.
213 Here is an example that uses the <filename>master</filename> Git repository
214 and the <filename>1.1M4</filename> release:
215 <literallayout class='monospaced'>
216 $ scripts/build.sh master 1.1M4
217 </literallayout>
218 After running the script, the file
219 <filename>org.yocto.sdk-&lt;release&gt;-&lt;date&gt;-archive.zip</filename>
220 is in the current directory.</para></listitem>
221 <listitem><para>If necessary, start the Eclipse IDE and be sure you are in the
222 Workbench.</para></listitem>
223 <listitem><para>Select "Install New Software" from the "Help" pull-down menu.
224 </para></listitem>
225 <listitem><para>Click "Add".</para></listitem>
226 <listitem><para>Provide anything you want in the "Name" field.</para></listitem>
227 <listitem><para>Click "Archive" and browse to the ZIP file you built
228 in step four.
229 This ZIP file should not be "unzipped", and must be the
230 <filename>*archive.zip</filename> file created by running the
231 <filename>build.sh</filename> script.</para></listitem>
232 <listitem><para>Check the box next to the new entry in the installation window and complete
233 the installation.</para></listitem>
234 <listitem><para>Restart the Eclipse IDE if necessary.</para></listitem>
235 </orderedlist>
236 </para>
237
238 <para>
239 At this point you should be able to configure the Eclipse Yocto Plug-in as described in the
240 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>"
241 section.</para>
242 </section>
243
244 <section id='yocto-project-source'>
245 <title>Importing the Plug-in Project into the Eclipse Environment</title>
246 <para>
247 Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories
248 is useful when you want to try out the latest plug-in from the tip of plug-in's
249 development tree.
250 It is important to understand when you import the plug-in you are not installing
251 it into the Eclipse application.
252 Rather, you are importing the project and just using it.
253 To import the plug-in project, follow these steps:
254 <orderedlist>
255 <listitem><para>Open a shell and create a Git repository with:
256 <literallayout class='monospaced'>
257 $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse
258 </literallayout>
259 For this example, the repository is named
260 <filename>~/yocto-eclipse</filename>.</para></listitem>
261 <listitem><para>In Eclipse, select "Import" from the "File" menu.</para></listitem>
262 <listitem><para>Expand the "General" box and select "existing projects into workspace"
263 and then click "Next".</para></listitem>
264 <listitem><para>Select the root directory and browse to
265 <filename>~/yocto-eclipse/plugins</filename>.</para></listitem>
266 <listitem><para>Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and
267 "org.yocto.sdk.remotetools".
268 Select and import all of them.</para></listitem>
269 </orderedlist>
270 </para>
271
272 <para>
273 The left navigation pane in the Eclipse application shows the default projects.
274 Right-click on one of these projects and run it as an Eclipse application.
275 This brings up a second instance of Eclipse IDE that has the Yocto Plug-in.
276 </para>
277 </section>
278 </section>
279
280 <section id='configuring-the-eclipse-yocto-plug-in'>
281 <title>Configuring the Eclipse Yocto Plug-in</title>
282
283 <para>
284 Configuring the Eclipse Yocto Plug-in involves setting the Cross
285 Compiler options and the Target options.
286 The configurations you choose become the default settings for all projects.
287 You do have opportunities to change them later when
288 you configure the project (see the following section).
289 </para>
290
291 <para>
292 To start, you need to do the following from within the Eclipse IDE:
293 <itemizedlist>
294 <listitem><para>Choose <filename>Windows -&gt; Preferences</filename> to display
295 the <filename>Preferences</filename> Dialog</para></listitem>
296 <listitem><para>Click <filename>Yocto Project ADT</filename></para></listitem>
297 </itemizedlist>
298 </para>
299
300 <section id='configuring-the-cross-compiler-options'>
301 <title>Configuring the Cross-Compiler Options</title>
302
303 <para>
304 To configure the Cross Compiler Options, you must select the type of toolchain,
305 point to the toolchain, specify the sysroot location, and select the target architecture.
306 <itemizedlist>
307 <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
308 Choose between <filename>Standalone pre-built toolchain</filename>
309 and <filename>Build system derived toolchain</filename> for Cross
310 Compiler Options.
311 <itemizedlist>
312 <listitem><para><emphasis>
313 <filename>Standalone Pre-built Toolchain:</filename></emphasis>
314 Select this mode when you are using a stand-alone cross-toolchain.
315 For example, suppose you are an application developer and do not
316 need to build a target image.
317 Instead, you just want to use an architecture-specific toolchain on an
318 existing kernel and target root filesystem.
319 </para></listitem>
320 <listitem><para><emphasis>
321 <filename>Build System Derived Toolchain:</filename></emphasis>
322 Select this mode if the cross-toolchain has been installed and built
323 as part of the build directory.
324 When you select <filename>Build system derived toolchain</filename>,
325 you are using the toolchain bundled
326 inside the build directory.
327 </para></listitem>
328 </itemizedlist>
329 </para></listitem>
330 <listitem><para><emphasis>Point to the Toolchain:</emphasis>
331 If you are using a stand-alone pre-built toolchain, you should be pointing to the
332 <filename>&YOCTO_ADTPATH_DIR;</filename> directory.
333 This is the location for toolchains installed by the ADT Installer or by hand.
334 Sections "<link linkend='configuring-and-running-the-adt-installer-script'>Configuring
335 and Running the ADT Installer Script</link>" and
336 "<link linkend='using-an-existing-toolchain-tarball'>Using a Cross-Toolchain
337 Tarball</link>" describe two ways to install
338 a stand-alone cross-toolchain in the
339 <filename>/opt/poky</filename> directory.
340 <note>It is possible to install a stand-alone cross-toolchain in a directory
341 other than <filename>/opt/poky</filename>.
342 However, doing so is discouraged.</note></para>
343 <para>If you are using a system-derived toolchain, the path you provide
344 for the <filename>Toolchain Root Location</filename>
345 field is the build directory.
346 See section "<link linkend='using-the-toolchain-from-within-the-build-tree'>Using
347 BitBake and the build directory</link>" for
348 information on how to install the toolchain into the build directory.</para></listitem>
349 <listitem><para><emphasis>Specify the Sysroot Location:</emphasis>
350 This location is where the root filesystem for the
351 target hardware is created on the development system by the ADT Installer.
352 The QEMU user-space tools, the
353 NFS boot process, and the cross-toolchain all use the sysroot location.
354 </para></listitem>
355 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
356 The target architecture is the type of hardware you are
357 going to use or emulate.
358 Use the pull-down <filename>Target Architecture</filename> menu to make
359 your selection.
360 The pull-down menu should have the supported architectures.
361 If the architecture you need is not listed in the menu, you
362 will need to build the image.
363 See the "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
364 of The Yocto Project Quick Start for more information.</para></listitem>
365 </itemizedlist>
366 </para>
367 </section>
368
369 <section id='configuring-the-target-options'>
370 <title>Configuring the Target Options</title>
371
372 <para>
373 You can choose to emulate hardware using the QEMU emulator, or you
374 can choose to run your image on actual hardware.
375 <itemizedlist>
376 <listitem><para><emphasis><filename>QEMU:</filename></emphasis> Select this option if
377 you will be using the QEMU emulator.
378 If you are using the emulator, you also need to locate the kernel
379 and specify any custom options.</para>
380 <para>If you selected <filename>Build system derived toolchain</filename>,
381 the target kernel you built will be located in the
382 build directory in <filename>tmp/deploy/images</filename> directory.
383 If you selected <filename>Standalone pre-built toolchain</filename>, the
384 pre-built image you downloaded is located
385 in the directory you specified when you downloaded the image.</para>
386 <para>Most custom options are for advanced QEMU users to further
387 customize their QEMU instance.
388 These options are specified between paired angled brackets.
389 Some options must be specified outside the brackets.
390 In particular, the options <filename>serial</filename>,
391 <filename>nographic</filename>, and <filename>kvm</filename> must all
392 be outside the brackets.
393 Use the <filename>man qemu</filename> command to get help on all the options
394 and their use.
395 The following is an example:
396 <literallayout class='monospaced'>
397 serial ‘&lt;-m 256 -full-screen&gt;’
398 </literallayout></para>
399 <para>
400 Regardless of the mode, Sysroot is already defined as part of the
401 Cross Compiler Options configuration in the
402 <filename>Sysroot Location:</filename> field.</para></listitem>
403 <listitem><para><emphasis><filename>External HW:</filename></emphasis> Select this option
404 if you will be using actual hardware.</para></listitem>
405 </itemizedlist>
406 </para>
407
408 <para>
409 Click the <filename>OK</filename> button to save your plug-in configurations.
410 </para>
411 </section>
412 </section>
413</section>
414
415<section id='creating-the-project'>
416<title>Creating the Project</title>
417
418 <para>
419 You can create two types of projects: Autotools-based, or Makefile-based.
420 This section describes how to create Autotools-based projects from within
421 the Eclipse IDE.
422 For information on creating Makefile-based projects in a terminal window, see the section
423 "<link linkend='using-the-command-line'>Using the Command Line</link>".
424 </para>
425
426 <para>
427 To create a project based on a Yocto template and then display the source code,
428 follow these steps:
429 <orderedlist>
430 <listitem><para>Select <filename>File -&gt; New -&gt; Project</filename>.</para></listitem>
431 <listitem><para>Double click <filename>CC++</filename>.</para></listitem>
432 <listitem><para>Double click <filename>C Project</filename> to create the project.</para></listitem>
433 <listitem><para>Expand <filename>Yocto Project ADT Project</filename>.</para></listitem>
434 <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>.
435 This is an Autotools-based project based on a Yocto template.</para></listitem>
436 <listitem><para>Put a name in the <filename>Project name:</filename> field.
437 Do not use hyphens as part of the name.</para></listitem>
438 <listitem><para>Click <filename>Next</filename>.</para></listitem>
439 <listitem><para>Add information in the <filename>Author</filename> and
440 <filename>Copyright notice</filename> fields.</para></listitem>
441 <listitem><para>Be sure the <filename>License</filename> field is correct.</para></listitem>
442 <listitem><para>Click <filename>Finish</filename>.</para></listitem>
443 <listitem><para>If the "open perspective" prompt appears, click "Yes" so that you
444 in the C/C++ perspective.</para></listitem>
445 <listitem><para>The left-hand navigation pane shows your project.
446 You can display your source by double clicking the project's source file.
447 </para></listitem>
448 </orderedlist>
449 </para>
450</section>
451
452<section id='configuring-the-cross-toolchains'>
453<title>Configuring the Cross-Toolchains</title>
454
455 <para>
456 The earlier section, "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring
457 the Eclipse Yocto Plug-in</link>", sets up the default project
458 configurations.
459 You can override these settings for a given project by following these steps:
460 <orderedlist>
461 <listitem><para>Select <filename>Project -&gt; Change Yocto Project Settings</filename>:
462 This selection brings up the <filename>Yocot Project Settings</filename> Dialog
463 and allows you to make changes specific to an individual project.
464 </para>
465 <para>By default, the Cross Compiler Options and Target Options for a project
466 are inherited from settings you provide using the <filename>Preferences</filename>
467 Dialog as described earlier
468 in the "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse
469 Yocto Plug-in</link>" section.
470 The <filename>Yocto Project Settings</filename>
471 Dialog allows you to override those default settings
472 for a given project.</para></listitem>
473 <listitem><para>Make your configurations for the project and click "OK".</para></listitem>
474 <listitem><para>Select <filename>Project -&gt; Reconfigure Project</filename>:
475 This selection reconfigures the project by running
476 <filename>autogen.sh</filename> in the workspace for your project.
477 The script also runs <filename>libtoolize</filename>, <filename>aclocal</filename>,
478 <filename>autoconf</filename>, <filename>autoheader</filename>,
479 <filename>automake --a</filename>, and
480 <filename>./configure</filename>.
481 Click on the <filename>Console</filename> tab beneath your source code to
482 see the results of reconfiguring your project.</para></listitem>
483 </orderedlist>
484 </para>
485</section>
486
487<section id='building-the-project'>
488<title>Building the Project</title>
489
490 <para>
491 To build the project, select <filename>Project -&gt; Build Project</filename>.
492 The console should update and you can note the cross-compiler you are using.
493 </para>
494</section>
495
496<section id='starting-qemu-in-user-space-nfs-mode'>
497<title>Starting QEMU in User Space NFS Mode</title>
498
499 <para>
500 To start the QEMU emulator from within Eclipse, follow these steps:
501 <orderedlist>
502 <listitem><para>Expose the <filename>Run -&gt; External Tools</filename> menu.
503 Your image should appear as a selectable menu item.
504 </para></listitem>
505 <listitem><para>Select your image from the menu to launch the
506 emulator in a new window.</para></listitem>
507 <listitem><para>If needed, enter your host root password in the shell window at the prompt.
508 This sets up a <filename>Tap 0</filename> connection needed for running in user-space
509 NFS mode.</para></listitem>
510 <listitem><para>Wait for QEMU to launch.</para></listitem>
511 <listitem><para>Once QEMU launches, you can begin operating within that
512 environment.
513 For example, you could determine the IP Address
514 for the user-space NFS by using the <filename>ifconfig</filename> command.
515 </para></listitem>
516 </orderedlist>
517 </para>
518</section>
519
520<section id='deploying-and-debugging-the-application'>
521<title>Deploying and Debugging the Application</title>
522
523 <para>
524 Once the QEMU emulator is running the image, using the Eclipse IDE
525 you can deploy your application and use the emulator to perform debugging.
526 Follow these steps to deploy the application.
527 <orderedlist>
528 <listitem><para>Select <filename>Run -&gt; Debug Configurations...</filename></para></listitem>
529 <listitem><para>In the left area, expand <filename>C/C++Remote Application</filename>.</para></listitem>
530 <listitem><para>Locate your project and select it to bring up a new
531 tabbed view in the <filename>Debug Configurations</filename> Dialog.</para></listitem>
532 <listitem><para>Enter the absolute path into which you want to deploy
533 the application.
534 Use the <filename>Remote Absolute File Path for C/C++Application:</filename> field.
535 For example, enter <filename>/usr/bin/&lt;programname&gt;</filename>.</para></listitem>
536 <listitem><para>Click on the <filename>Debugger</filename> tab to see the cross-tool debugger
537 you are using.</para></listitem>
538 <listitem><para>Click on the <filename>Main</filename> tab.</para></listitem>
539 <listitem><para>Create a new connection to the QEMU instance
540 by clicking on <filename>new</filename>.</para></listitem>
541 <listitem><para>Select <filename>TCF</filename>, which means Target Communication
542 Framework.</para></listitem>
543 <listitem><para>Click <filename>Next</filename>.</para></listitem>
544 <listitem><para>Clear out the <filename>host name</filename> field and enter the IP Address
545 determined earlier.</para></listitem>
546 <listitem><para>Click <filename>Finish</filename> to close the
547 <filename>New Connections</filename> Dialog.</para></listitem>
548 <listitem><para>Use the drop-down menu now in the <filename>Connection</filename> field and pick
549 the IP Address you entered.</para></listitem>
550 <listitem><para>Click <filename>Debug</filename> to bring up a login screen
551 and login.</para></listitem>
552 <listitem><para>Accept the debug perspective.</para></listitem>
553 </orderedlist>
554 </para>
555</section>
556
557<section id='running-user-space-tools'>
558<title>Running User-Space Tools</title>
559
560 <para>
561 As mentioned earlier in the manual, several tools exist that enhance
562 your development experience.
563 These tools are aids in developing and debugging applications and images.
564 You can run these user-space tools from within the Eclipse IDE through the
565 <filename>YoctoTools</filename> menu.
566 </para>
567
568 <para>
569 Once you pick a tool, you need to configure it for the remote target.
570 Every tool needs to have the connection configured.
571 You must select an existing TCF-based RSE connection to the remote target.
572 If one does not exist, click <filename>New</filename> to create one.
573 </para>
574
575 <para>
576 Here are some specifics about the remote tools:
577 <itemizedlist>
578 <listitem><para><emphasis><filename>OProfile</filename>:</emphasis> Selecting this tool causes
579 the <filename>oprofile-server</filename> on the remote target to launch on
580 the local host machine.
581 The <filename>oprofile-viewer</filename> must be installed on the local host machine and the
582 <filename>oprofile-server</filename> must be installed on the remote target,
583 respectively, in order to use.
584 You must compile and install the <filename>oprofile-viewer</filename> from the source code
585 on your local host machine.
586 Furthermore, in order to convert the target's sample format data into a form that the
587 host can use, you must have <filename>oprofile</filename> version 0.9.4 or
588 greater installed on the host.</para>
589 <para>You can locate both the viewer and server from
590 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>.
591 <note>The <filename>oprofile-server</filename> is installed by default on
592 the <filename>core-image-sato-sdk</filename> image.</note></para></listitem>
593 <listitem><para><emphasis><filename>Lttng-ust</filename>:</emphasis> Selecting this tool runs
594 <filename>usttrace</filename> on the remote target, transfers the output data back
595 to the local host machine, and uses the <filename>lttng</filename> Eclipse plug-in to
596 graphically display the output.
597 For information on how to use <filename>lttng</filename> to trace an application, see
598 <ulink url='http://lttng.org/files/ust/manual/ust.html'></ulink>.</para>
599 <para>For <filename>Application</filename>, you must supply the absolute path name of the
600 application to be traced by user mode <filename>lttng</filename>.
601 For example, typing <filename>/path/to/foo</filename> triggers
602 <filename>usttrace /path/to/foo</filename> on the remote target to trace the
603 program <filename>/path/to/foo</filename>.</para>
604 <para><filename>Argument</filename> is passed to <filename>usttrace</filename>
605 running on the remote target.</para>
606 <para>Before you use the <filename>lttng-ust</filename> tool, you need to setup
607 the <filename>lttng</filename> Eclipse plug-in and create a <filename>lttng</filename>
608 project.
609 Do the following:
610 <orderedlist>
611 <listitem><para>Follow these
612 <ulink url='http://wiki.eclipse.org/Linux_Tools_Project/LTTng#Downloading_and_installing_the_LTTng_parser_library'>instructions</ulink>
613 to download and install the <filename>lttng</filename> parser library.
614 </para></listitem>
615 <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename>
616 and then select <filename>LTTng</filename>.</para></listitem>
617 <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective
618 into the <filename>LTTng</filename> perspective.</para></listitem>
619 <listitem><para>Create a new <filename>LTTng</filename> project by selecting
620 <filename>File -> New -> Project</filename>.</para></listitem>
621 <listitem><para>Choose <filename>LTTng -> LTTng Project</filename>.</para></listitem>
622 <listitem><para>Click <filename>YoctoTools -> lttng-ust</filename> to start user mode
623 <filename>lttng</filename> on the remote target.</para></listitem>
624 </orderedlist></para>
625 <para>After the output data has been transferred from the remote target back to the local
626 host machine, new traces will be imported into the selected <filename>LTTng</filename> project.
627 Then you can go to the <filename>LTTng</filename> project, right click the imported
628 trace, and set the trace type as the <filename>LTTng</filename> kernel trace.
629 Finally, right click the imported trace and select <filename>Open</filename>
630 to display the data graphically.</para></listitem>
631 <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> Selecting this tool runs
632 <filename>powertop</filename> on the remote target machine and displays the results in a
633 new view called <filename>powertop</filename>.</para>
634 <para><filename>Time to gather data(sec):</filename> is the time passed in seconds before data
635 is gathered from the remote target for analysis.</para>
636 <para><filename>show pids in wakeups list:</filename> corresponds to the
637 <filename>-p</filename> argument
638 passed to <filename>powertop</filename>.</para></listitem>
639 <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis>
640 <filename>latencytop</filename> identifies system latency, while
641 <filename>perf</filename> monitors the system's
642 performance counter registers.
643 Selecting either of these tools causes an RSE terminal view to appear
644 from which you can run the tools.
645 Both tools refresh the entire screen to display results while they run.</para></listitem>
646 </itemizedlist>
647 </para>
648</section>
649
650<section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'>
651 <title>Customizing an Image Using a BitBake Commander Project and Hob</title>
652
653 <para>
654 Within Eclipse, you can create a Yocto BitBake Commander project,
655 edit the metadata, and then use the
656 <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build a customized
657 image all within one IDE.
658 </para>
659
660 <section id='creating-the-yocto-bitbake-commander-project'>
661 <title>Creating the Yocto BitBake Commander Project</title>
662
663 <para>
664 To create a Yocto BitBake Commander project, follow these steps:
665 <orderedlist>
666 <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename>
667 and then choose <filename>Bitbake Commander</filename>.</para></listitem>
668 <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective into the
669 Bitbake Commander perspective.</para></listitem>
670 <listitem><para>Select <filename>File -> New -> Project</filename> to create a new Yocto
671 Bitbake Commander project.</para></listitem>
672 <listitem><para>Choose <filename>Yocto Project Bitbake Commander -> New Yocto Project</filename>
673 and click <filename>Next</filename>.</para></listitem>
674 <listitem><para>Enter the Project Name and choose the Project Location.
675 The Yocto project's metadata files will be put under the directory
676 <filename>&lt;project_location&gt;/&lt;project_name&gt;</filename>.
677 If that directory does not exist, you need to check
678 the "Clone from Yocto Git Repository" box, which would execute a
679 <filename>git clone</filename> command to get the project's metadata files.
680 </para></listitem>
681 <listitem><para>Select <filename>Finish</filename> to create the project.</para></listitem>
682 </orderedlist>
683 </para>
684 </section>
685
686 <section id='editing-the-metadata-files'>
687 <title>Editing the Metadata Files</title>
688
689 <para>
690 After you create the Yocto Bitbake Commander project, you can modify the metadata files
691 by opening them in the project.
692 When editing recipe files (<filename>.bb</filename> files), you can view BitBake
693 variable values and information by hovering the mouse pointer over the variable name and
694 waiting a few seconds.
695 </para>
696
697 <para>
698 To edit the metadata, follow these steps:
699 <orderedlist>
700 <listitem><para>Select your Yocto Bitbake Commander project.</para></listitem>
701 <listitem><para>Select <filename>File -> New -> Yocto BitBake Commander -> BitBake Recipe</filename>
702 to open a new recipe wizard.</para></listitem>
703 <listitem><para>Point to your source by filling in the "SRC_URL" field.
704 For example, you can add a recipe to your
705 <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-source-files'>source directory structure</ulink>
706 by defining "SRC_URL" as follows:
707 <literallayout class='monospaced'>
708 ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz
709 </literallayout></para></listitem>
710 <listitem><para>Click "Populate" to calculate the archive md5, sha256,
711 license checksum values and to auto-generate the recipe filename.</para></listitem>
712 <listitem><para>Fill in the "Description" field.</para></listitem>
713 <listitem><para>Be sure values for all required fields exist.</para></listitem>
714 <listitem><para>Click <filename>Finish</filename>.</para></listitem>
715 </orderedlist>
716 </para>
717 </section>
718
719 <section id='buiding-and-customizing-the-image'>
720 <title>Building and Customizing the Image</title>
721
722 <para>
723 To build and customize the image in Eclipse, follow these steps:
724 <orderedlist>
725 <listitem><para>Select your Yocto Bitbake Commander project.</para></listitem>
726 <listitem><para>Select <filename>Project -> Launch HOB</filename>.</para></listitem>
727 <listitem><para>Enter the build directory where you want to put your final images.</para></listitem>
728 <listitem><para>Click <filename>OK</filename> to launch Hob.</para></listitem>
729 <listitem><para>Use Hob to customize and build your own images.
730 For information on Hob, see the
731 <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob Project Page</ulink> on the
732 Yocto Project website.</para></listitem>
733 </orderedlist>
734 </para>
735 </section>
736</section>
737</chapter>
738<!--
739vim: expandtab tw=80 ts=4
740-->
diff --git a/documentation/adt-manual/adt-intro.xml b/documentation/adt-manual/adt-intro.xml
index 04c47369f9..93737826b5 100644
--- a/documentation/adt-manual/adt-intro.xml
+++ b/documentation/adt-manual/adt-intro.xml
@@ -13,11 +13,13 @@
13 13
14<para> 14<para>
15 The Yocto Project provides an application development environment based on 15 The Yocto Project provides an application development environment based on
16 an Application Development Toolkit (ADT). 16 an Application Development Toolkit (ADT) and the availability of stand-alone
17 This manual describes the ADT and how you can configure and install it. 17 cross-development toolchains and other tools.
18 You will also learn how to customize the development packages installation, 18 This manual describes the ADT and how you can configure and install it,
19 learn about the Eclipse Yocto Plug-in, and learn how to use command line 19 how to access and use the cross-development toolchains, how to
20 development for both Autotools-based and Makefile-based projects. 20 customize the development packages installation,
21 how to use command line development for both Autotools-based and Makefile-based projects,
22 and an introduction to the Eclipse Yocto Plug-in.
21</para> 23</para>
22 24
23<section id='book-intro'> 25<section id='book-intro'>
@@ -88,6 +90,14 @@
88 remote profiling, tracing, collection of power data, collection of 90 remote profiling, tracing, collection of power data, collection of
89 latency data, and collection of performance data. 91 latency data, and collection of performance data.
90 </para> 92 </para>
93
94 <para>
95 For information about the application development workflow that uses the Eclipse
96 IDE and for a detailed example of how to install and configure the Eclipse
97 Yocto Project Plug-in, see the
98 "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working Within Eclipse</ulink>" section
99 of the Yocto Project Development Manual.
100 </para>
91 </section> 101 </section>
92 102
93 <section id='the-qemu-emulator'> 103 <section id='the-qemu-emulator'>
diff --git a/documentation/adt-manual/adt-manual.xml b/documentation/adt-manual/adt-manual.xml
index c553e7cc08..285c347fae 100644
--- a/documentation/adt-manual/adt-manual.xml
+++ b/documentation/adt-manual/adt-manual.xml
@@ -85,8 +85,6 @@
85 85
86 <xi:include href="adt-package.xml"/> 86 <xi:include href="adt-package.xml"/>
87 87
88 <xi:include href="adt-eclipse.xml"/>
89
90 <xi:include href="adt-command.xml"/> 88 <xi:include href="adt-command.xml"/>
91 89
92<!-- <index id='index'> 90<!-- <index id='index'>
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index b5274b8452..3bfd1a3963 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -641,6 +641,745 @@
641 </para> 641 </para>
642 </section> 642 </section>
643 643
644 <section id='adt-eclipse'>
645 <title>Working Within Eclipse</title>
646
647 <para>
648 The Eclipse IDE is a popular development environment and it fully supports
649 development using the Yocto Project.
650 When you install and configure the Eclipse Yocto Project Plug-in into
651 the Eclipse IDE, you maximize your Yocto Project experience.
652 Installing and configuring the Plug-in results in an environment that
653 has extensions specifically designed to let you more easily develop software.
654 These extensions allow for cross-compilation, deployment, and execution of
655 your output into a QEMU emulation session.
656 You can also perform cross-debugging and profiling.
657 The environment also supports a suite of tools that allows you to perform
658 remote profiling, tracing, collection of power data, collection of
659 latency data, and collection of performance data.
660 </para>
661
662 <para>
663 This section describes how to install and configure the Eclipse IDE
664 Yocto Plug-in and how to use it to develop your application.
665 </para>
666
667 <section id='setting-up-the-eclipse-ide'>
668 <title>Setting Up the Eclipse IDE</title>
669
670 <para>
671 To develop within the Eclipse IDE, you need to do the following:
672 <orderedlist>
673 <listitem><para>Install the optimal version of the Eclipse IDE.</para></listitem>
674 <listitem><para>Configure the Eclipse IDE.</para></listitem>
675 <listitem><para>Install the Eclipse Yocto Plug-in.</para></listitem>
676 <listitem><para>Configure the Eclipse Yocto Plug-in.</para></listitem>
677 </orderedlist>
678 <note>
679 Do not install Eclipse from your distribution's package repository.
680 Be sure to install Eclipse from the official Eclipse download site as directed
681 in the next section.
682 </note>
683 </para>
684
685 <section id='installing-eclipse-ide'>
686 <title>Installing the Eclipse IDE</title>
687
688 <para>
689 It is recommended that you have the Indigo 3.7.2 version of the
690 Eclipse IDE installed on your development system.
691 If you don’t have this version, you can find it at
692 <ulink url='&ECLIPSE_MAIN_URL;'></ulink>.
693 From that site, choose the Eclipse Classic version particular to your development
694 host.
695 This version contains the Eclipse Platform, the Java Development
696 Tools (JDT), and the Plug-in Development Environment.
697 </para>
698
699 <para>
700 Once you have downloaded the tarball, extract it into a clean
701 directory.
702 For example, the following commands unpack and install the Eclipse IDE
703 tarball found in the <filename>Downloads</filename> area
704 into a clean directory using the default name <filename>eclipse</filename>:
705 <literallayout class='monospaced'>
706 $ cd ~
707 $ tar -xzvf ~/Downloads/eclipse-SDK-3.7.2-linux-gtk-x86_64.tar.gz
708 </literallayout>
709 </para>
710
711 <para>
712 One issue exists that you need to be aware of regarding the Java
713 Virtual machine’s garbage collection (GC) process.
714 The GC process does not clean up the permanent generation
715 space (PermGen).
716 This space stores metadata descriptions of classes.
717 The default value is set too small and it could trigger an
718 out-of-memory error such as the following:
719 <literallayout class='monospaced'>
720 Java.lang.OutOfMemoryError: PermGen space
721 </literallayout>
722 </para>
723
724 <para>
725 This error causes the application to hang.
726 </para>
727
728 <para>
729 To fix this issue, you can use the <filename>--vmargs</filename>
730 option when you start Eclipse to increase the size of the permanent generation space:
731 <literallayout class='monospaced'>
732 eclipse --vmargs --XX:PermSize=256M
733 </literallayout>
734 </para>
735 </section>
736
737 <section id='configuring-the-eclipse-ide'>
738 <title>Configuring the Eclipse IDE</title>
739
740 <para>
741 Before installing and configuring the Eclipse Yocto Plug-in, you need to configure
742 the Eclipse IDE.
743 Follow these general steps to configure Eclipse:
744 <orderedlist>
745 <listitem><para>Start the Eclipse IDE.</para></listitem>
746 <listitem><para>Make sure you are in your Workbench and select
747 "Install New Software" from the "Help" pull-down menu.
748 </para></listitem>
749 <listitem><para>Select <filename>indigo - &ECLIPSE_INDIGO_URL;</filename>
750 from the "Work with:" pull-down menu.</para></listitem>
751 <listitem><para>Expand the box next to <filename>Programming Languages</filename>
752 and select the <filename>Autotools Support for CDT (incubation)</filename>
753 and <filename>C/C++ Development Tools</filename> boxes.</para></listitem>
754 <listitem><para>Expand the box next to "Linux Tools" and select the
755 "LTTng - Linux Tracing Toolkit(incubation)" boxes.</para></listitem>
756 <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
757 <listitem><para>After the Eclipse IDE restarts and from the Workbench, select
758 "Install New Software" from the "Help" pull-down menu.</para></listitem>
759 <listitem><para>Click the
760 "Available Software Sites" link.</para></listitem>
761 <listitem><para>Check the box next to
762 <filename>&ECLIPSE_UPDATES_URL;</filename>
763 and click "OK".</para></listitem>
764 <listitem><para>Select <filename>&ECLIPSE_UPDATES_URL;</filename>
765 from the "Work with:" pull-down menu.</para></listitem>
766 <listitem><para>Check the box next to <filename>TM and RSE Main Features</filename>.
767 </para></listitem>
768 <listitem><para>Expand the box next to <filename>TM and RSE Optional Add-ons</filename>
769 and select every item except <filename>RSE Unit Tests</filename> and
770 <filename>RSE WinCE Services (incubation)</filename>.</para></listitem>
771 <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
772 <listitem><para>If necessary, select
773 "Install New Software" from the "Help" pull-down menu so you can click the
774 "Available Software Sites" link again.</para></listitem>
775 <listitem><para>After clicking "Available Software Sites", check the box next to
776 <filename>http://download.eclipse.org/tools/cdt/releases/indigo</filename>
777 and click "OK".</para></listitem>
778 <listitem><para>Select <filename>&ECLIPSE_INDIGO_CDT_URL;</filename>
779 from the "Work with:" pull-down menu.</para></listitem>
780 <listitem><para>Check the box next to <filename>CDT Main Features</filename>.
781 </para></listitem>
782 <listitem><para>Expand the box next to <filename>CDT Optional Features</filename>
783 and select <filename>C/C++ Remote Launch</filename> and
784 <filename>Target Communication Framework (incubation)</filename>.</para></listitem>
785 <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
786 </orderedlist>
787 </para>
788 </section>
789
790 <section id='installing-the-eclipse-yocto-plug-in'>
791 <title>Installing or Accessing the Eclipse Yocto Plug-in</title>
792
793 <para>
794 You can install the Eclipse Yocto Plug-in into the Eclipse IDE
795 one of two ways: use the Yocto Project's Eclipse Update site to install the pre-built plug-in,
796 or build and install the plug-in from the latest source code.
797 If you don't want to permanently install the plug-in but just want to try it out
798 within the Eclipse environment, you can import the plug-in project from the
799 Yocto Project source repositories.
800 </para>
801
802 <section id='new-software'>
803 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
804
805 <para>
806 To install the Eclipse Yocto Plug-in from the update site,
807 follow these steps:
808 <orderedlist>
809 <listitem><para>Start up the Eclipse IDE.</para></listitem>
810 <listitem><para>In Eclipse, select "Install New Software" from the "Help" menu.</para></listitem>
811 <listitem><para>Click "Add..." in the "Work with:" area.</para></listitem>
812 <listitem><para>Enter
813 <filename>&ECLIPSE_DL_PLUGIN_URL;</filename>
814 in the URL field and provide a meaningful name in the "Name" field.</para></listitem>
815 <listitem><para>Click "OK" to have the entry added to the "Work with:"
816 drop-down list.</para></listitem>
817 <listitem><para>Select the entry for the plug-in from the "Work with:" drop-down
818 list.</para></listitem>
819 <listitem><para>Check the box next to <filename>Development tools and SDKs for Yocto Linux</filename>.
820 </para></listitem>
821 <listitem><para>Complete the remaining software installation steps and
822 then restart the Eclipse IDE to finish the installation of the plug-in.
823 </para></listitem>
824 </orderedlist>
825 </para>
826 </section>
827
828 <section id='zip-file-method'>
829 <title>Installing the Plug-in Using the Latest Source Code</title>
830
831 <para>
832 To install the Eclipse Yocto Plug-in from the latest source code, follow these steps:
833 <orderedlist>
834 <listitem><para>Open a shell and create a Git repository with:
835 <literallayout class='monospaced'>
836 $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse
837 </literallayout>
838 For this example, the repository is named
839 <filename>~/yocto-eclipse</filename>.</para></listitem>
840 <listitem><para>Locate the <filename>build.sh</filename> script in the
841 Git repository you created in the previous step.
842 The script is located in the <filename>scripts</filename>.</para></listitem>
843 <listitem><para>Be sure to set and export the <filename>ECLIPSE_HOME</filename> environment
844 variable to the top-level directory in which you installed the Indigo
845 version of Eclipse.
846 For example, if your Eclipse directory is <filename>$HOME/eclipse</filename>,
847 use the following:
848 <literallayout class='monospaced'>
849 $ export ECLIPSE_HOME=$HOME/eclipse
850 </literallayout></para></listitem>
851 <listitem><para>Run the <filename>build.sh</filename> script and provide the
852 name of the Git branch along with the Yocto Project release you are
853 using.
854 Here is an example that uses the <filename>master</filename> Git repository
855 and the <filename>1.1M4</filename> release:
856 <literallayout class='monospaced'>
857 $ scripts/build.sh master 1.1M4
858 </literallayout>
859 After running the script, the file
860 <filename>org.yocto.sdk-&lt;release&gt;-&lt;date&gt;-archive.zip</filename>
861 is in the current directory.</para></listitem>
862 <listitem><para>If necessary, start the Eclipse IDE and be sure you are in the
863 Workbench.</para></listitem>
864 <listitem><para>Select "Install New Software" from the "Help" pull-down menu.
865 </para></listitem>
866 <listitem><para>Click "Add".</para></listitem>
867 <listitem><para>Provide anything you want in the "Name" field.</para></listitem>
868 <listitem><para>Click "Archive" and browse to the ZIP file you built
869 in step four.
870 This ZIP file should not be "unzipped", and must be the
871 <filename>*archive.zip</filename> file created by running the
872 <filename>build.sh</filename> script.</para></listitem>
873 <listitem><para>Check the box next to the new entry in the installation window and complete
874 the installation.</para></listitem>
875 <listitem><para>Restart the Eclipse IDE if necessary.</para></listitem>
876 </orderedlist>
877 </para>
878
879 <para>
880 At this point you should be able to configure the Eclipse Yocto Plug-in as described in the
881 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>"
882 section.</para>
883 </section>
884
885 <section id='yocto-project-source'>
886 <title>Importing the Plug-in Project into the Eclipse Environment</title>
887
888 <para>
889 Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories
890 is useful when you want to try out the latest plug-in from the tip of plug-in's
891 development tree.
892 It is important to understand when you import the plug-in you are not installing
893 it into the Eclipse application.
894 Rather, you are importing the project and just using it.
895 To import the plug-in project, follow these steps:
896 <orderedlist>
897 <listitem><para>Open a shell and create a Git repository with:
898 <literallayout class='monospaced'>
899 $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse
900 </literallayout>
901 For this example, the repository is named
902 <filename>~/yocto-eclipse</filename>.</para></listitem>
903 <listitem><para>In Eclipse, select "Import" from the "File" menu.</para></listitem>
904 <listitem><para>Expand the "General" box and select "existing projects into workspace"
905 and then click "Next".</para></listitem>
906 <listitem><para>Select the root directory and browse to
907 <filename>~/yocto-eclipse/plugins</filename>.</para></listitem>
908 <listitem><para>Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and
909 "org.yocto.sdk.remotetools".
910 Select and import all of them.</para></listitem>
911 </orderedlist>
912 </para>
913
914 <para>
915 The left navigation pane in the Eclipse application shows the default projects.
916 Right-click on one of these projects and run it as an Eclipse application.
917 This brings up a second instance of Eclipse IDE that has the Yocto Plug-in.
918 </para>
919 </section>
920 </section>
921
922 <section id='configuring-the-eclipse-yocto-plug-in'>
923 <title>Configuring the Eclipse Yocto Plug-in</title>
924
925 <para>
926 Configuring the Eclipse Yocto Plug-in involves setting the Cross
927 Compiler options and the Target options.
928 The configurations you choose become the default settings for all projects.
929 You do have opportunities to change them later when
930 you configure the project (see the following section).
931 </para>
932
933 <para>
934 To start, you need to do the following from within the Eclipse IDE:
935 <itemizedlist>
936 <listitem><para>Choose <filename>Windows -&gt; Preferences</filename> to display
937 the <filename>Preferences</filename> Dialog</para></listitem>
938 <listitem><para>Click <filename>Yocto Project ADT</filename></para></listitem>
939 </itemizedlist>
940 </para>
941
942 <section id='configuring-the-cross-compiler-options'>
943 <title>Configuring the Cross-Compiler Options</title>
944
945 <para>
946 To configure the Cross Compiler Options, you must select the type of toolchain,
947 point to the toolchain, specify the sysroot location, and select the target architecture.
948 <itemizedlist>
949 <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
950 Choose between <filename>Standalone pre-built toolchain</filename>
951 and <filename>Build system derived toolchain</filename> for Cross
952 Compiler Options.
953 <itemizedlist>
954 <listitem><para><emphasis>
955 <filename>Standalone Pre-built Toolchain:</filename></emphasis>
956 Select this mode when you are using a stand-alone cross-toolchain.
957 For example, suppose you are an application developer and do not
958 need to build a target image.
959 Instead, you just want to use an architecture-specific toolchain on an
960 existing kernel and target root filesystem.
961 </para></listitem>
962 <listitem><para><emphasis>
963 <filename>Build System Derived Toolchain:</filename></emphasis>
964 Select this mode if the cross-toolchain has been installed and built
965 as part of the build directory.
966 When you select <filename>Build system derived toolchain</filename>,
967 you are using the toolchain bundled
968 inside the build directory.
969 </para></listitem>
970 </itemizedlist>
971 </para></listitem>
972 <listitem><para><emphasis>Point to the Toolchain:</emphasis>
973 If you are using a stand-alone pre-built toolchain, you should be pointing to the
974 <filename>&YOCTO_ADTPATH_DIR;</filename> directory.
975 This is the location for toolchains installed by the ADT Installer or by hand.
976 Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring
977 and Running the ADT Installer Script</ulink>" and
978 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
979 in the Yocto Project Application Developer's Guide
980 describe two ways to install a stand-alone cross-toolchain in the
981 <filename>/opt/poky</filename> directory.
982 <note>It is possible to install a stand-alone cross-toolchain in a directory
983 other than <filename>/opt/poky</filename>.
984 However, doing so is discouraged.</note></para>
985 <para>If you are using a system-derived toolchain, the path you provide
986 for the <filename>Toolchain Root Location</filename>
987 field is the build directory.
988 See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using
989 BitBake and the build directory</ulink>" section in the Yocto Project Application
990 Developer's Guide for information on how to install the toolchain into the build
991directory.</para></listitem>
992 <listitem><para><emphasis>Specify the Sysroot Location:</emphasis>
993 This location is where the root filesystem for the
994 target hardware is created on the development system by the ADT Installer.
995 The QEMU user-space tools, the
996 NFS boot process, and the cross-toolchain all use the sysroot location.
997 </para></listitem>
998 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
999 The target architecture is the type of hardware you are
1000 going to use or emulate.
1001 Use the pull-down <filename>Target Architecture</filename> menu to make
1002 your selection.
1003 The pull-down menu should have the supported architectures.
1004 If the architecture you need is not listed in the menu, you
1005 will need to build the image.
1006 See the "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
1007 of The Yocto Project Quick Start for more information.</para></listitem>
1008 </itemizedlist>
1009 </para>
1010 </section>
1011
1012 <section id='configuring-the-target-options'>
1013 <title>Configuring the Target Options</title>
1014
1015 <para>
1016 You can choose to emulate hardware using the QEMU emulator, or you
1017 can choose to run your image on actual hardware.
1018 <itemizedlist>
1019 <listitem><para><emphasis><filename>QEMU:</filename></emphasis> Select this option if
1020 you will be using the QEMU emulator.
1021 If you are using the emulator, you also need to locate the kernel
1022 and specify any custom options.</para>
1023 <para>If you selected <filename>Build system derived toolchain</filename>,
1024 the target kernel you built will be located in the
1025 build directory in <filename>tmp/deploy/images</filename> directory.
1026 If you selected <filename>Standalone pre-built toolchain</filename>, the
1027 pre-built image you downloaded is located
1028 in the directory you specified when you downloaded the image.</para>
1029 <para>Most custom options are for advanced QEMU users to further
1030 customize their QEMU instance.
1031 These options are specified between paired angled brackets.
1032 Some options must be specified outside the brackets.
1033 In particular, the options <filename>serial</filename>,
1034 <filename>nographic</filename>, and <filename>kvm</filename> must all
1035 be outside the brackets.
1036 Use the <filename>man qemu</filename> command to get help on all the options
1037 and their use.
1038 The following is an example:
1039 <literallayout class='monospaced'>
1040 serial ‘&lt;-m 256 -full-screen&gt;’
1041 </literallayout></para>
1042 <para>
1043 Regardless of the mode, Sysroot is already defined as part of the
1044 Cross Compiler Options configuration in the
1045 <filename>Sysroot Location:</filename> field.</para></listitem>
1046 <listitem><para><emphasis><filename>External HW:</filename></emphasis> Select this option
1047 if you will be using actual hardware.</para></listitem>
1048 </itemizedlist>
1049 </para>
1050
1051 <para>
1052 Click the <filename>OK</filename> button to save your plug-in configurations.
1053 </para>
1054 </section>
1055 </section>
1056 </section>
1057
1058 <section id='creating-the-project'>
1059 <title>Creating the Project</title>
1060
1061 <para>
1062 You can create two types of projects: Autotools-based, or Makefile-based.
1063 This section describes how to create Autotools-based projects from within
1064 the Eclipse IDE.
1065 For information on creating Makefile-based projects in a terminal window, see the section
1066 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>"
1067 in the Yocto Project Application Developer's Guide.
1068 </para>
1069
1070 <para>
1071 To create a project based on a Yocto template and then display the source code,
1072 follow these steps:
1073 <orderedlist>
1074 <listitem><para>Select <filename>File -&gt; New -&gt; Project</filename>.</para></listitem>
1075 <listitem><para>Double click <filename>CC++</filename>.</para></listitem>
1076 <listitem><para>Double click <filename>C Project</filename> to create the project.</para></listitem>
1077 <listitem><para>Expand <filename>Yocto Project ADT Project</filename>.</para></listitem>
1078 <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>.
1079 This is an Autotools-based project based on a Yocto template.</para></listitem>
1080 <listitem><para>Put a name in the <filename>Project name:</filename> field.
1081 Do not use hyphens as part of the name.</para></listitem>
1082 <listitem><para>Click <filename>Next</filename>.</para></listitem>
1083 <listitem><para>Add information in the <filename>Author</filename> and
1084 <filename>Copyright notice</filename> fields.</para></listitem>
1085 <listitem><para>Be sure the <filename>License</filename> field is correct.</para></listitem>
1086 <listitem><para>Click <filename>Finish</filename>.</para></listitem>
1087 <listitem><para>If the "open perspective" prompt appears, click "Yes" so that you
1088 in the C/C++ perspective.</para></listitem>
1089 <listitem><para>The left-hand navigation pane shows your project.
1090 You can display your source by double clicking the project's source file.
1091 </para></listitem>
1092 </orderedlist>
1093 </para>
1094 </section>
1095
1096 <section id='configuring-the-cross-toolchains'>
1097 <title>Configuring the Cross-Toolchains</title>
1098
1099 <para>
1100 The earlier section, "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring
1101 the Eclipse Yocto Plug-in</link>", sets up the default project
1102 configurations.
1103 You can override these settings for a given project by following these steps:
1104 <orderedlist>
1105 <listitem><para>Select <filename>Project -&gt; Change Yocto Project Settings</filename>:
1106 This selection brings up the <filename>Yocot Project Settings</filename> Dialog
1107 and allows you to make changes specific to an individual project.
1108 </para>
1109 <para>By default, the Cross Compiler Options and Target Options for a project
1110 are inherited from settings you provide using the <filename>Preferences</filename>
1111 Dialog as described earlier
1112 in the "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse
1113 Yocto Plug-in</link>" section.
1114 The <filename>Yocto Project Settings</filename>
1115 Dialog allows you to override those default settings
1116 for a given project.</para></listitem>
1117 <listitem><para>Make your configurations for the project and click "OK".</para></listitem>
1118 <listitem><para>Select <filename>Project -&gt; Reconfigure Project</filename>:
1119 This selection reconfigures the project by running
1120 <filename>autogen.sh</filename> in the workspace for your project.
1121 The script also runs <filename>libtoolize</filename>, <filename>aclocal</filename>,
1122 <filename>autoconf</filename>, <filename>autoheader</filename>,
1123 <filename>automake --a</filename>, and
1124 <filename>./configure</filename>.
1125 Click on the <filename>Console</filename> tab beneath your source code to
1126 see the results of reconfiguring your project.</para></listitem>
1127 </orderedlist>
1128 </para>
1129 </section>
1130
1131 <section id='building-the-project'>
1132 <title>Building the Project</title>
1133
1134 <para>
1135 To build the project, select <filename>Project -&gt; Build Project</filename>.
1136 The console should update and you can note the cross-compiler you are using.
1137 </para>
1138 </section>
1139
1140 <section id='starting-qemu-in-user-space-nfs-mode'>
1141 <title>Starting QEMU in User Space NFS Mode</title>
1142
1143 <para>
1144 To start the QEMU emulator from within Eclipse, follow these steps:
1145 <orderedlist>
1146 <listitem><para>Expose the <filename>Run -&gt; External Tools</filename> menu.
1147 Your image should appear as a selectable menu item.
1148 </para></listitem>
1149 <listitem><para>Select your image from the menu to launch the
1150 emulator in a new window.</para></listitem>
1151 <listitem><para>If needed, enter your host root password in the shell window at the prompt.
1152 This sets up a <filename>Tap 0</filename> connection needed for running in user-space
1153 NFS mode.</para></listitem>
1154 <listitem><para>Wait for QEMU to launch.</para></listitem>
1155 <listitem><para>Once QEMU launches, you can begin operating within that
1156 environment.
1157 For example, you could determine the IP Address
1158 for the user-space NFS by using the <filename>ifconfig</filename> command.
1159 </para></listitem>
1160 </orderedlist>
1161 </para>
1162 </section>
1163
1164 <section id='deploying-and-debugging-the-application'>
1165 <title>Deploying and Debugging the Application</title>
1166
1167 <para>
1168 Once the QEMU emulator is running the image, using the Eclipse IDE
1169 you can deploy your application and use the emulator to perform debugging.
1170 Follow these steps to deploy the application.
1171 <orderedlist>
1172 <listitem><para>Select <filename>Run -&gt; Debug Configurations...</filename></para></listitem>
1173 <listitem><para>In the left area, expand <filename>C/C++Remote Application</filename>.</para></listitem>
1174 <listitem><para>Locate your project and select it to bring up a new
1175 tabbed view in the <filename>Debug Configurations</filename> Dialog.</para></listitem>
1176 <listitem><para>Enter the absolute path into which you want to deploy
1177 the application.
1178 Use the <filename>Remote Absolute File Path for C/C++Application:</filename> field.
1179 For example, enter <filename>/usr/bin/&lt;programname&gt;</filename>.</para></listitem>
1180 <listitem><para>Click on the <filename>Debugger</filename> tab to see the cross-tool debugger
1181 you are using.</para></listitem>
1182 <listitem><para>Click on the <filename>Main</filename> tab.</para></listitem>
1183 <listitem><para>Create a new connection to the QEMU instance
1184 by clicking on <filename>new</filename>.</para></listitem>
1185 <listitem><para>Select <filename>TCF</filename>, which means Target Communication
1186 Framework.</para></listitem>
1187 <listitem><para>Click <filename>Next</filename>.</para></listitem>
1188 <listitem><para>Clear out the <filename>host name</filename> field and enter the IP Address
1189 determined earlier.</para></listitem>
1190 <listitem><para>Click <filename>Finish</filename> to close the
1191 <filename>New Connections</filename> Dialog.</para></listitem>
1192 <listitem><para>Use the drop-down menu now in the <filename>Connection</filename> field and pick
1193 the IP Address you entered.</para></listitem>
1194 <listitem><para>Click <filename>Debug</filename> to bring up a login screen
1195 and login.</para></listitem>
1196 <listitem><para>Accept the debug perspective.</para></listitem>
1197 </orderedlist>
1198 </para>
1199 </section>
1200
1201 <section id='running-user-space-tools'>
1202 <title>Running User-Space Tools</title>
1203
1204 <para>
1205 As mentioned earlier in the manual, several tools exist that enhance
1206 your development experience.
1207 These tools are aids in developing and debugging applications and images.
1208 You can run these user-space tools from within the Eclipse IDE through the
1209 <filename>YoctoTools</filename> menu.
1210 </para>
1211
1212 <para>
1213 Once you pick a tool, you need to configure it for the remote target.
1214 Every tool needs to have the connection configured.
1215 You must select an existing TCF-based RSE connection to the remote target.
1216 If one does not exist, click <filename>New</filename> to create one.
1217 </para>
1218
1219 <para>
1220 Here are some specifics about the remote tools:
1221 <itemizedlist>
1222 <listitem><para><emphasis><filename>OProfile</filename>:</emphasis> Selecting this tool causes
1223 the <filename>oprofile-server</filename> on the remote target to launch on
1224 the local host machine.
1225 The <filename>oprofile-viewer</filename> must be installed on the local host machine and the
1226 <filename>oprofile-server</filename> must be installed on the remote target,
1227 respectively, in order to use.
1228 You must compile and install the <filename>oprofile-viewer</filename> from the source code
1229 on your local host machine.
1230 Furthermore, in order to convert the target's sample format data into a form that the
1231 host can use, you must have <filename>oprofile</filename> version 0.9.4 or
1232 greater installed on the host.</para>
1233 <para>You can locate both the viewer and server from
1234 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>.
1235 <note>The <filename>oprofile-server</filename> is installed by default on
1236 the <filename>core-image-sato-sdk</filename> image.</note></para></listitem>
1237 <listitem><para><emphasis><filename>Lttng-ust</filename>:</emphasis> Selecting this tool runs
1238 <filename>usttrace</filename> on the remote target, transfers the output data back
1239 to the local host machine, and uses the <filename>lttng</filename> Eclipse plug-in to
1240 graphically display the output.
1241 For information on how to use <filename>lttng</filename> to trace an application, see
1242 <ulink url='http://lttng.org/files/ust/manual/ust.html'></ulink>.</para>
1243 <para>For <filename>Application</filename>, you must supply the absolute path name of the
1244 application to be traced by user mode <filename>lttng</filename>.
1245 For example, typing <filename>/path/to/foo</filename> triggers
1246 <filename>usttrace /path/to/foo</filename> on the remote target to trace the
1247 program <filename>/path/to/foo</filename>.</para>
1248 <para><filename>Argument</filename> is passed to <filename>usttrace</filename>
1249 running on the remote target.</para>
1250 <para>Before you use the <filename>lttng-ust</filename> tool, you need to setup
1251 the <filename>lttng</filename> Eclipse plug-in and create a <filename>lttng</filename>
1252 project.
1253 Do the following:
1254 <orderedlist>
1255 <listitem><para>Follow these
1256 <ulink url='http://wiki.eclipse.org/Linux_Tools_Project/LTTng#Downloading_and_installing_the_LTTng_parser_library'>instructions</ulink>
1257 to download and install the <filename>lttng</filename> parser library.
1258 </para></listitem>
1259 <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename>
1260 and then select <filename>LTTng</filename>.</para></listitem>
1261 <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective
1262 into the <filename>LTTng</filename> perspective.</para></listitem>
1263 <listitem><para>Create a new <filename>LTTng</filename> project by selecting
1264 <filename>File -> New -> Project</filename>.</para></listitem>
1265 <listitem><para>Choose <filename>LTTng -> LTTng Project</filename>.</para></listitem>
1266 <listitem><para>Click <filename>YoctoTools -> lttng-ust</filename> to start user mode
1267 <filename>lttng</filename> on the remote target.</para></listitem>
1268 </orderedlist></para>
1269 <para>After the output data has been transferred from the remote target back to the local
1270 host machine, new traces will be imported into the selected <filename>LTTng</filename> project.
1271 Then you can go to the <filename>LTTng</filename> project, right click the imported
1272 trace, and set the trace type as the <filename>LTTng</filename> kernel trace.
1273 Finally, right click the imported trace and select <filename>Open</filename>
1274 to display the data graphically.</para></listitem>
1275 <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> Selecting this tool runs
1276 <filename>powertop</filename> on the remote target machine and displays the results in a
1277 new view called <filename>powertop</filename>.</para>
1278 <para><filename>Time to gather data(sec):</filename> is the time passed in seconds before data
1279 is gathered from the remote target for analysis.</para>
1280 <para><filename>show pids in wakeups list:</filename> corresponds to the
1281 <filename>-p</filename> argument
1282 passed to <filename>powertop</filename>.</para></listitem>
1283 <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis>
1284 <filename>latencytop</filename> identifies system latency, while
1285 <filename>perf</filename> monitors the system's
1286 performance counter registers.
1287 Selecting either of these tools causes an RSE terminal view to appear
1288 from which you can run the tools.
1289 Both tools refresh the entire screen to display results while they run.</para></listitem>
1290 </itemizedlist>
1291 </para>
1292 </section>
1293
1294 <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'>
1295 <title>Customizing an Image Using a BitBake Commander Project and Hob</title>
1296
1297 <para>
1298 Within Eclipse, you can create a Yocto BitBake Commander project,
1299 edit the metadata, and then use the
1300 <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build a customized
1301 image all within one IDE.
1302 </para>
1303
1304 <section id='creating-the-yocto-bitbake-commander-project'>
1305 <title>Creating the Yocto BitBake Commander Project</title>
1306
1307 <para>
1308 To create a Yocto BitBake Commander project, follow these steps:
1309 <orderedlist>
1310 <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename>
1311 and then choose <filename>Bitbake Commander</filename>.</para></listitem>
1312 <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective into the
1313 Bitbake Commander perspective.</para></listitem>
1314 <listitem><para>Select <filename>File -> New -> Project</filename> to create a new Yocto
1315 Bitbake Commander project.</para></listitem>
1316 <listitem><para>Choose <filename>Yocto Project Bitbake Commander -> New Yocto Project</filename>
1317 and click <filename>Next</filename>.</para></listitem>
1318 <listitem><para>Enter the Project Name and choose the Project Location.
1319 The Yocto project's metadata files will be put under the directory
1320 <filename>&lt;project_location&gt;/&lt;project_name&gt;</filename>.
1321 If that directory does not exist, you need to check
1322 the "Clone from Yocto Git Repository" box, which would execute a
1323 <filename>git clone</filename> command to get the project's metadata files.
1324 </para></listitem>
1325 <listitem><para>Select <filename>Finish</filename> to create the project.</para></listitem>
1326 </orderedlist>
1327 </para>
1328 </section>
1329
1330 <section id='editing-the-metadata-files'>
1331 <title>Editing the Metadata Files</title>
1332
1333 <para>
1334 After you create the Yocto Bitbake Commander project, you can modify the metadata files
1335 by opening them in the project.
1336 When editing recipe files (<filename>.bb</filename> files), you can view BitBake
1337 variable values and information by hovering the mouse pointer over the variable name and
1338 waiting a few seconds.
1339 </para>
1340
1341 <para>
1342 To edit the metadata, follow these steps:
1343 <orderedlist>
1344 <listitem><para>Select your Yocto Bitbake Commander project.</para></listitem>
1345 <listitem><para>Select <filename>File -> New -> Yocto BitBake Commander -> BitBake Recipe</filename>
1346 to open a new recipe wizard.</para></listitem>
1347 <listitem><para>Point to your source by filling in the "SRC_URL" field.
1348 For example, you can add a recipe to your
1349 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>
1350 by defining "SRC_URL" as follows:
1351 <literallayout class='monospaced'>
1352 ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz
1353 </literallayout></para></listitem>
1354 <listitem><para>Click "Populate" to calculate the archive md5, sha256,
1355 license checksum values and to auto-generate the recipe filename.</para></listitem>
1356 <listitem><para>Fill in the "Description" field.</para></listitem>
1357 <listitem><para>Be sure values for all required fields exist.</para></listitem>
1358 <listitem><para>Click <filename>Finish</filename>.</para></listitem>
1359 </orderedlist>
1360 </para>
1361 </section>
1362
1363 <section id='buiding-and-customizing-the-image'>
1364 <title>Building and Customizing the Image</title>
1365
1366 <para>
1367 To build and customize the image in Eclipse, follow these steps:
1368 <orderedlist>
1369 <listitem><para>Select your Yocto Bitbake Commander project.</para></listitem>
1370 <listitem><para>Select <filename>Project -> Launch HOB</filename>.</para></listitem>
1371 <listitem><para>Enter the build directory where you want to put your final images.</para></listitem>
1372 <listitem><para>Click <filename>OK</filename> to launch Hob.</para></listitem>
1373 <listitem><para>Use Hob to customize and build your own images.
1374 For information on Hob, see the
1375 <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob Project Page</ulink> on the
1376 Yocto Project website.</para></listitem>
1377 </orderedlist>
1378 </para>
1379 </section>
1380 </section>
1381 </section>
1382
644 <section id='workflow-using-stand-alone-cross-development-toolchains'> 1383 <section id='workflow-using-stand-alone-cross-development-toolchains'>
645 <title>Workflow Using Stand-alone Cross-development Toolchains</title> 1384 <title>Workflow Using Stand-alone Cross-development Toolchains</title>
646 1385