summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-03-15 15:41:35 -0600
committerSaul Wold <sgw@linux.intel.com>2011-03-16 08:08:16 -0700
commit4dfed39284e4350311f9dfec4ebea9c4498a7f46 (patch)
treeab21ac93a68fc863db693550081b417991d1825a /documentation
parentfc6863bea9cb150cc4342dafe3fe107c4f3cf115 (diff)
downloadpoky-4dfed39284e4350311f9dfec4ebea9c4498a7f46.tar.gz
documentation/adt-manual/adt-eclipse.xml: Initial draft for Eclipse chapter.
This is the initial draft of the Eclipse chapter. (From OE-Core rev: 44512573d62fa5e209bf227d6811f9a94ec42372) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/adt-manual/adt-eclipse.xml443
1 files changed, 408 insertions, 35 deletions
diff --git a/documentation/adt-manual/adt-eclipse.xml b/documentation/adt-manual/adt-eclipse.xml
index 2bb5bd5125..9fa39cf5cf 100644
--- a/documentation/adt-manual/adt-eclipse.xml
+++ b/documentation/adt-manual/adt-eclipse.xml
@@ -2,54 +2,427 @@
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3 3
4<chapter id='adt-eclipse'> 4<chapter id='adt-eclipse'>
5 5<title>Working Within Eclipse</title>
6<title>Yocto Project Kernel Architecture and Use Manual</title>
7
8<section id='eclipse'>
9 <title>Introduction</title>
10 <para> 6 <para>
11 The Yocto Project presents the kernel as a fully patched, history-clean git 7 The Eclipse IDE is a popular development environment and it fully supports
12 repository. 8 development using Yocto Project.
13 The git tree represents the selected features, board support, 9 When you install and configure the Eclipse Yocto Project Plug-in into
14 and configurations extensively tested by Yocto Project. 10 the Eclipse IDE you maximize your Yocto Project design experience.
15 The Yocto Project kernel allows the end user to leverage community 11 Installing and configuring the Plug-in results in an environment that
16 best practices to seamlessly manage the development, build and debug cycles. 12 has extensions specifically designed to let you more easily develop software.
13 These extensions allow for cross-compilation and deployment and execution of
14 your output into a QEMU emulation session.
15 You can also perform cross-debugging and profiling.
16 The environment also has a suite of tools that allows you to perform
17 remote profiling, tracing, collection of power data, collection of
18 latency data, and collection of performance data.
17 </para> 19 </para>
18 <para> 20 <para>
19 This manual describes the Yocto Project kernel by providing information 21 This section describes how to install and configure the Eclipse IDE
20 on its history, organization, benefits, and use. 22 Yocto Plug-in and how to use it to develop your Yocto Project.
21 The manual consists of two sections:
22 <itemizedlist>
23 <listitem><para>Concepts - Describes concepts behind the kernel.
24 You will understand how the kernel is organized and why it is organized in
25 the way it is. You will understand the benefits of the kernel's organization
26 and the mechanisms used to work with the kernel and how to apply it in your
27 design process.</para></listitem>
28 <listitem><para>Using the Kernel - Describes best practices and "how-to" information
29 that lets you put the kernel to practical use. Some examples are "How to Build a
30 Project Specific Tree", "How to Examine Changes in a Branch", and "Saving Kernel
31 Modifications."</para></listitem>
32 </itemizedlist>
33 </para> 23 </para>
24
25<section id='setting-up-the-eclipse-ide'>
26 <title>Setting Up the Eclipse IDE</title>
34 <para> 27 <para>
35 For more information on the kernel, see the following links: 28 To develop within the Eclipse IDE you need to do the following:
36 <itemizedlist> 29 <orderedlist>
37 <listitem><para><ulink url='http://ldn.linuxfoundation.org/book/1-a-guide-kernel-development-process'></ulink></para></listitem> 30 <listitem><para>Be sure the optimal version of Eclipse IDE
38 <listitem><para><ulink url='http://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem> 31 is installed.</para></listitem>
39 <listitem><para><ulink url='http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD'></ulink></para></listitem> 32 <listitem><para>Install required Eclipse plug-ins prior to installing
40 </itemizedlist> 33 the Eclipse Yocto Plug-in.</para></listitem>
41 <para> 34 <listitem><para>Configure the Eclipse Yocto Plug-in.</para></listitem>
42 You can find more information on Yocto Project by visiting the website at 35 </orderedlist>
43 <ulink url='http://www.yoctoproject.org'></ulink>.
44 </para>
45 </para> 36 </para>
37
38 <section id='installing-eclipse-ide'>
39 <title>Installing Eclipse IDE</title>
40 <para>
41 It is recommended that you have the Helios 3.6.1 version of the
42 Eclipse IDE installed on your development system.
43 If you don’t have this version you can find it at
44 <ulink url='http://www.eclipse.org/downloads'></ulink>.
45 From that site, choose the Eclipse Classic version.
46 This version contains the Eclipse Platform, the Java Development
47 Tools (JDT), and the Plug-in Development Environment.
48 </para>
49 <para>
50 Once you have downloaded the tarball, extract it into a clean
51 directory and complete the installation.
52 </para>
53 <para>
54 One issue exists that you need to be aware of regarding the Java
55 Virtual machine’s garbage collection (GC) process.
56 The GC process does not clean up the permanent generation
57 space (PermGen).
58 This space stores meta-data descriptions of classes.
59 The default value is set too small and it could trigger an
60 out-of-memory error such as the following:
61 <literallayout class='monospaced'>
62 Java.lang.OutOfMemoryError: PermGen space
63 </literallayout>
64 </para>
65 <para>
66 This error causes the application to hang.
67 </para>
68 <para>
69 To fix this issue you can use the &dash;&dash;vmargs option when you start
70 Eclipse to increase the size of the permanent generation space:
71 <literallayout class='monospaced'>
72 eclipse &dash;&dash;vmargs &dash;&dash;XX:PermSize=256M
73 </literallayout>
74 </para>
75 </section>
76
77 <section id='installing-required-plug-ins-and-the-eclipse-yocto-plug-in'>
78 <title>Installing Required Plug-ins and the Eclipse Yocto Plug-in</title>
79 <para>
80 Before installing the Yocto Plug-in you need to be sure that the
81 CDT 7.0, RSE 3.2, and Autotools plug-ins are all installed.
82 After installing these three plug-ins, you can install the
83 Eclipse Yocto Plug-in.
84 Use the following URLs for the plug-ins:
85 <orderedlist>
86 <listitem><para><emphasis>CDT 7.0</emphasis> –
87 <ulink url='http://download.eclipse.org/tools/cdt/releases/helios/'></ulink>:
88 For CDT main features select the checkbox so you get all items.
89 For CDT optional features expand the selections and check
90 “C/C++ Remote Launch”.</para></listitem>
91 <listitem><para><emphasis>RSE 3.2</emphasis> –
92 <ulink url='http://download.eclipse.org/tm/updates/3.2'></ulink>:
93 Check the box next to “TM and RSE Main Features” so you select all
94 those items.
95 Note that all items in the main features depend on 3.2.1 version.
96 Expand the items under “TM and RSE Uncategorized 3.2.1” and
97 select the following: “Remote System Explorer End-User Runtime”,
98 “Remote System Explorer Extended SDK”, “Remote System Explorer User Actions”,
99 “RSE Core”, “RSE Terminals UI”, and “Target Management Terminal”.</para></listitem>
100 <listitem><para><emphasis>Autotools</emphasis> –
101 <ulink url='http://download.eclipse.org/technology/linuxtools/update'></ulink>:
102 Expand the items under “Linux Tools” and select “Autotools support
103 for CDT (Incubation)”.</para></listitem>
104 <listitem><para><emphasis>Yocto Plug-in</emphasis> –
105 <ulink url='http://www.yoctoproject.org/downloads/eclipse-plugin/'></ulink>:
106 Check the box next to “Development tools &amp; SDKs for Yocto Linux”
107 to select all the items.</para></listitem>
108 </orderedlist>
109 </para>
110 <para>
111 Follow these general steps to install a plug-in:
112 <orderedlist>
113 <listitem><para>From within the Eclipse IDE select the
114 “Install New Software” item from the “Help” menu.</para></listitem>
115 <listitem><para>Click “Add…” in the “Work with:” area.</para></listitem>
116 <listitem><para>Enter the URL for the repository and leave the “Name”
117 field blank.</para></listitem>
118 <listitem><para>Check the boxes next to the software you need to
119 install and then complete the installation.
120 For information on the specific software packages you need to include,
121 see the previous list.</para></listitem>
122 </orderedlist>
123 </para>
124 </section>
125
126 <section id='configuring-the-plug-in'>
127 <title>Configuring the Plug-in</title>
128 <para>
129 Configuring the Eclipse Yocto Plug-in involves choosing the Cross
130 Compiler Options, selecting the Target Architecture, and choosing
131 the Target Options.
132 These settings are the default settings for all projects.
133 You do have opportunities to change them later if you choose to when
134 you configure the project.
135 See “Configuring the Cross Toolchain” section later in the manual.
136 </para>
137 <para>
138 To start, you need to do the following from within the Eclipse IDE:
139 <itemizedlist>
140 <listitem><para>Choose Windows -&gt; Preferences to display
141 the Preferences Dialog</para></listitem>
142 <listitem><para>Click “Yocto SDK”</para></listitem>
143 </itemizedlist>
144 </para>
145
146 <section id='configuring-the-cross-compiler-options'>
147 <title>Configuring the Cross-Compiler Options</title>
148 <para>
149 Choose between ‘SDK Root Mode’ and ‘Poky Tree Mode’ for Cross
150 Compiler Options.
151 <itemizedlist>
152 <listitem><para><emphasis>SDK Root Mode</emphasis> – Select this mode
153 when you are not concerned with building an image or you do not have
154 a Poky build tree on your system.
155 For example, suppose you are an application developer and do not
156 need to build an image.
157 You just want to use an architecture-specific toolchain on an
158 existing kernel and root filesystem.
159 When you use SDK Root Mode you are using the toolchain installed
160 in the <filename>/opt/poky</filename> directory.</para></listitem>
161 <listitem><para><emphasis>Poky Tree Mode</emphasis> – Select this mode
162 if you are concerned with building images for hardware or your
163 development environment already has a build tree.
164 In this case you likely already have a Poky build tree installed on
165 your system or you (or someone else) will be building one.
166 When you use the Poky Tree Mode you are using the toolchain bundled
167 inside the Poky build tree.
168 If you use this mode you must also supply the Poky Root Location
169 in the Preferences Dialog.</para></listitem>
170 </itemizedlist>
171 </para>
172 </section>
173
174 <section id='configuring-the-sysroot'>
175 <title>Configuring the Sysroot</title>
176 <para>
177 Specify the sysroot, which is used by both the QEMU user-space
178 NFS boot process and by the cross-toolchain regardless of the
179 mode you select (SDK Root Mode or Poky Tree Mode).
180 For example, sysroot is the location to which you extract the
181 downloaded image’s root filesystem to through the ADT Installer.
182 </para>
183 </section>
184
185 <section id='selecting-the-target-architecture'>
186 <title>Selecting the Target Architecture</title>
187 <para>
188 Use the pull-down Target Architecture menu and select the
189 target architecture.
190 </para>
191 <para>
192 The Target Architecture is the type of hardware you are
193 going to use or emulate.
194 This pull-down menu should have the supported architectures.
195 If the architecture you need is not listed in the menu then you
196 will need to re-visit
197 <xref linkend='adt-prepare'>
198 “Preparing to Use the Application Development Toolkit (ADT)”</xref>
199 section earlier in this document.
200 </para>
201 </section>
202
203 <section id='choosing-the-target-options'>
204 <title>Choosing the Target Options</title>
205 <para>
206 You can choose to emulate hardware using the QEMU emulator, or you
207 can choose to use actual hardware.
208 <itemizedlist>
209 <listitem><para><emphasis>External HW</emphasis> – Select this option
210 if you will be using actual hardware.</para></listitem>
211 <listitem><para><emphasis>QEMU</emphasis> – Select this option if
212 you will be using the QEMU emulator.
213 If you are using the emulator you also need to locate the Kernel
214 and you can specify custom options.</para>
215 <para>In Poky Tree Mode the kernel you built will be located in the
216 Poky Build tree in <filename>tmp/deploy/images</filename> directory.
217 In SDK Root Mode the pre-built kernel you downloaded is located
218 in the directory you specified when you downloaded the image.</para>
219 <para>Most custom options are for advanced QEMU users to further
220 customize their QEMU instance.
221 These options are specified between paired angled brackets.
222 Some options must be specified outside the brackets.
223 Use the <filename>man qemu</filename> command to get help on all the options.
224 The following is an example custom:
225 <literallayout class='monospaced'>
226 serial ‘&lt;-m 256 –full-screen&gt;’
227 </literallayout>
228 </para>
229 <para>
230 Regardless of the mode, Sysroot is already defined in the “Sysroot”
231 field.</para></listitem>
232 </itemizedlist>
233 </para>
234 <para>
235 Click the “OK” button to save your plug-in configurations.
236 </para>
237 </section>
238 </section>
46</section> 239</section>
47 240
241<section id='creating-the-project'>
242<title>Creating the Project</title>
243 <para>
244 You can create two types of projects: Autotools-based, or Makefile-based.
245 This section describes how to create autotools-based projects from within
246 the Eclipse IDE.
247 For information on creating projects in a terminal window see
248 <xref linkend='using-the-command-line'> “Using the Command Line”</xref>
249 section.
250 </para>
251 <para>
252 To create a project based on a Yocto template and then display the source code,
253 follow these steps:
254 <orderedlist>
255 <listitem><para>Select File -> New -> Project.</para></listitem>
256 <listitem><para>Double click “CC++”.</para></listitem>
257 <listitem><para>Double click “C Project” to create the project.</para></listitem>
258 <listitem><para>Double click “Yocto SDK Project”.</para></listitem>
259 <listitem><para>Select “Hello World ANSI C Autotools Project”.
260 This is an Autotools-based project based on a Yocto Project template.</para></listitem>
261 <listitem><para>Put a name in the “Project name:” field.</para></listitem>
262 <listitem><para>Click “Next”.</para></listitem>
263 <listitem><para>Add information in the “Author” field.</para></listitem>
264 <listitem><para>Use “GNU General Public License v2.0” for the License.</para></listitem>
265 <listitem><para>Click “Finish”.</para></listitem>
266 <listitem><para>Answer ‘Yes” to the open perspective prompt.</para></listitem>
267 <listitem><para>In the Project Explorer expand your project.</para></listitem>
268 <listitem><para>Expand ‘src’.</para></listitem>
269 <listitem><para>Double click on your source file and the code appears
270 in the window.
271 This is the template.</para></listitem>
272 </orderedlist>
273 </para>
274</section>
48 275
276<section id='configuring-the-cross-toolchains'>
277<title>Configuring the Cross-Toolchains</title>
278 <para>
279 The previous section, <xref linkend='configuring-the-cross-compiler-options'>
280 “Configuring the Cross-Compiler Options”</xref>, set up the default project
281 configurations.
282 You can change these settings for a given project by following these steps:
283 <orderedlist>
284 <listitem><para>Select Project -> Invoke Yocto Tools -> Reconfigure Yocto.
285 This brings up the project Yocto Settings Dialog.
286 Settings are inherited from the default project configuration.
287 The information in this dialogue is identical to that chosen earlier
288 for the Cross Compiler Option (SDK Root Mode or Poky Tree Mode),
289 the Target Architecture, and the Target Options.
290 The settings are inherited from the Yocto Plug-in configuration performed
291 after installing the plug-in.</para></listitem>
292 <listitem><para>Select Project -> Reconfigure Project.
293 This runs the <filename>autogen.sh</filename> in the workspace for your project.
294 The script runs <filename>libtoolize</filename>, <filename>aclocal</filename>,
295 <filename>autoconf</filename>, <filename>autoheader</filename>,
296 <filename>automake &dash;&dash;a</filename>, and
297 <filename>./configure</filename>.</para></listitem>
298 </orderedlist>
299 </para>
300</section>
49 301
302<section id='building-the-project'>
303<title>Building the Project</title>
304 <para>
305 To build the project, select Project -&gt; Build Project.
306 You should see the console updated and you can note the cross-compiler you are using.
307 </para>
308</section>
50 309
310<section id='starting-qemu-in-user-space-nfs-mode'>
311<title>Starting QEMU in User Space NFS Mode</title>
312 <para>
313 To start the QEMU emulator from within Eclipse, follow these steps:
314 <orderedlist>
315 <listitem><para>Select Run -> External Tools -> External Tools Configurations...
316 This selection brings up the External Tools Configurations Dialogue.</para></listitem>
317 <listitem><para>Go to the left navigation area and expand ‘Program’.
318 You should find the image listed.
319 For example, qemu-x86_64-poky-linux.</para></listitem>
320 <listitem><para>Click on the image.
321 This brings up a new environment in the main area of the External
322 Tools Configurations Dialogue.
323 The Main tab is selected.</para></listitem>
324 <listitem><para>Click “Run” next.
325 This brings up a shell window.</para></listitem>
326 <listitem><para>Enter your host root password in the shell window at the prompt.
327 This sets up a Tap 0 connection needed for running in user-space NFS mode.</para></listitem>
328 <listitem><para>Wait for QEMU to launch.</para></listitem>
329 <listitem><para>Once QEMU launches you need to determine the IP Address
330 for the user-space NFS.
331 You can do that by going to a terminal in the QEMU and entering the
332 <filename>ipconfig</filename> command.</para></listitem>
333 </orderedlist>
334 </para>
335</section>
51 336
337<section id='deploying-and-debugging-the-application'>
338<title>Deploying and Debugging the Application</title>
339 <para>
340 Once QEMU is running you can deploy your application and use the emulator
341 to perform debugging.
342 Follow these steps to deploy the application.
343 <orderedlist>
344 <listitem><para>Select Run -> Debug Configurations...</para></listitem>
345 <listitem><para>In the left area expand “C/C++Remote Application”.</para></listitem>
346 <listitem><para>Locate your project and select it to bring up a new
347 tabbed view in the Debug Configurations dialogue.</para></listitem>
348 <listitem><para>Enter the absolute path into which you want to deploy
349 the application.
350 Use the Remote Absolute File Path for C/C++Application:.
351 For example, enter <filename>/usr/bin/&lt;programname&gt;</filename>.</para></listitem>
352 <listitem><para>Click on the Debugger tab to see the cross-tool debugger
353 you are using.</para></listitem>
354 <listitem><para>Create a new connection to the QEMU instance
355 by clicking on “new”.</para></listitem>
356 <listitem><para>Select “TCF, which means Target Communication Framework.</para></listitem>
357 <listitem><para>Click “Next”.</para></listitem>
358 <listitem><para>Clear out the “host name” field and enter the IP Address
359 determined earlier.</para></listitem>
360 <listitem><para>Click Finish to close the new connections dialogue.</para></listitem>
361 <listitem><para>Use the drop-down menu now in the “Connection” field and pick
362 the IP Address you entered.</para></listitem>
363 <listitem><para>Click “Debug” to bring up a login screen and login.</para></listitem>
364 <listitem><para>Accept the debug perspective.</para></listitem>
365 </orderedlist>
366 </para>
367</section>
52 368
369<section id='running-user-space-tools'>
370<title>Running User-Space Tools</title>
371 <para>
372 As mentioned earlier in the manual several tools exist that enhance
373 your development experience.
374 These tools are aids in developing and debugging applications and images.
375 You can run these user-space tools from within the Yocto Eclipse
376 Plug-in through the Window -> YoctoTools menu.
377 </para>
378 <para>
379 Once you pick a tool you need to configure it for the remote target.
380 Every tool needs to have the connection configured.
381 You must select an existing TCF-based RSE connection to the remote target.
382 If one does not exist, click "New" to create one.
383 </para>
384 <para>
385 Here are some specifics about the remote tools:
386 <itemizedlist>
387 <listitem><para><emphasis>OProfile:</emphasis> Selecting this tool causes
388 the oprofile-server on the remote target to launch on the local host machine.
389 The oprofile-viewer must be installed on the local host machine and the
390 oprofile-server must be installed on the remote target, respectively, in order
391 to use.
392 You can locate both the viewer and server from
393 <ulink url='http://git.pokylinux.org/cgit/cgit.cgi/oprofileui/'></ulink>.
394 You need to compile and install the oprofile-viewer from the source code
395 on your local host machine.
396 The oprofile-server is installed by default in the image.</para></listitem>
397 <listitem><para><emphasis>Lttng-ust:</emphasis> Selecting this tool runs
398 "usttrace" on the remote target, transfers the output data back to the
399 local host machine and uses "lttv-gui" to graphically display the output.
400 The "lttv-gui" must be installed on the local host machine to use this tool.
401 For information on how to use "lttng" to trace an application, see
402 <ulink url='http://lttng.org/files/ust/manual/ust.html'></ulink>.</para>
403 <para>For "Application" you must supply the absolute path name of the
404 application to be traced by user mode lttng.
405 For example, typing <filename>/path/to/foo</filename> triggers
406 <filename>usttrace /path/to/foo</filename> on the remote target to trace the
407 program <filename>/path/to/foo</filename>.</para>
408 <para>"Argument" is passed to <filename>usttrace</filename>
409 running on the remote target.</para></listitem>
410 <listitem><para><emphasis>PowerTOP:</emphasis> Selecting this tool runs
411 "PowerTOP" on the remote target machine and displays the results in a
412 new view called "powertop".</para>
413 <para>"Time to gather data(sec):" is the time passed in seconds before data
414 is gathered from the remote target for analysis.</para>
415 <para>"show pids in wakeups list:" corresponds to the -p argument
416 passed to "powertop".</para></listitem>
417 <listitem><para><emphasis>LatencyTOP and Perf:</emphasis> "LatencyTOP"
418 identifies system latency, while "perf" monitors the system's
419 performance counter registers.
420 Selecting either of these tools causes an RSE terminal view to appear
421 from which you can run the tools.
422 Both tools refresh the entire screen to display results while they run.</para></listitem>
423 </itemizedlist>
424 </para>
425</section>
53 426
54</chapter> 427</chapter>
55<!-- 428<!--