summaryrefslogtreecommitdiffstats
path: root/documentation/adt-manual/adt-eclipse.xml
blob: 4dd90f52fd6cd3e552b48365a467e0ba543db67a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<chapter id='adt-eclipse'>
<title>Working Within Eclipse</title>
    <para>
        The Eclipse IDE is a popular development environment and it fully supports 
        development using Yocto Project.  
        When you install and configure the Eclipse Yocto Project Plug-in into 
        the Eclipse IDE you maximize your Yocto Project design experience.  
        Installing and configuring the Plug-in results in an environment that 
        has extensions specifically designed to let you more easily develop software.  
        These extensions allow for cross-compilation and deployment and execution of 
        your output into a QEMU emulation session.  
        You can also perform cross-debugging and profiling.  
        The environment also has a suite of tools that allows you to perform 
        remote profiling, tracing, collection of power data, collection of 
        latency data, and collection of performance data.
    </para>
    <para>
        This section describes how to install and configure the Eclipse IDE 
        Yocto Plug-in and how to use it to develop your Yocto Project.
    </para>

<section id='setting-up-the-eclipse-ide'>
    <title>Setting Up the Eclipse IDE</title>
    <para>
        To develop within the Eclipse IDE you need to do the following:
        <orderedlist>
            <listitem><para>Be sure the optimal version of Eclipse IDE 
            is installed.</para></listitem>
            <listitem><para>Install Eclipse plug-in requirements prior to installing 
            the Eclipse Yocto Plug-in.</para></listitem>
            <listitem><para>Configure the Eclipse Yocto Plug-in.</para></listitem>
        </orderedlist>
    </para>

    <section id='installing-eclipse-ide'>
    <title>Installing Eclipse IDE</title>
        <para>
            It is recommended that you have the Indigo 3.7 version of the 
            Eclipse IDE installed on your development system.  
            If you don’t have this version you can find it at 
            <ulink url='http://www.eclipse.org/downloads'></ulink>.  
            From that site, choose the Eclipse Classic version.  
            This version contains the Eclipse Platform, the Java Development 
            Tools (JDT), and the Plug-in Development Environment.
        </para>
        <para>
            Once you have downloaded the tarball, extract it into a clean 
            directory and complete the installation.
        </para>
        <para>
            One issue exists that you need to be aware of regarding the Java 
            Virtual machine’s garbage collection (GC) process.  
            The GC process does not clean up the permanent generation 
            space (PermGen).  
            This space stores meta-data descriptions of classes.  
            The default value is set too small and it could trigger an 
            out-of-memory error such as the following:
            <literallayout class='monospaced'>
     Java.lang.OutOfMemoryError: PermGen space
            </literallayout>
        </para>
        <para>
            This error causes the application to hang.
        </para>
        <para>
            To fix this issue you can use the &dash;&dash;vmargs option when you start 
            Eclipse to increase the size of the permanent generation space:
            <literallayout class='monospaced'>
     eclipse &dash;&dash;vmargs &dash;&dash;XX:PermSize=256M
            </literallayout>
        </para>
    </section>

    <section id='installing-required-plug-ins-and-the-eclipse-yocto-plug-in'>
    <title>Installing Required Plug-ins and the Eclipse Yocto Plug-in</title>
        <para>
            Before installing the Yocto Plug-in you need to be sure that the 
            CDT 8.0, RSE 3.2, and Autotools plug-ins are all installed in the 
            following order.  
            After installing these three plug-ins, you can install the 
            Eclipse Yocto Plug-in.  
            Use the following URLs for the plug-ins:
            <orderedlist>
                <listitem><para><emphasis>CDT 8.0</emphasis><ulink url='http://download.eclipse.org/tools/cdt/releases/indigo/'></ulink>:  
                For CDT main features select the checkbox so you get all items.  
                For CDT optional features expand the selections and check 
                “C/C++ Remote Launch”.</para></listitem>
                <listitem><para><emphasis>RSE 3.2</emphasis><ulink url='http://download.eclipse.org/tm/updates/3.2'></ulink>:  
                Check the box next to “TM and RSE Main Features” so you select all 
                those items.  
                Note that all items in the main features depend on 3.2.1 version.  
                Expand the items under “TM and RSE Uncategorized 3.2.1” and 
                select the following:  “Remote System Explorer End-User Runtime”, 
                “Remote System Explorer Extended SDK”, “Remote System Explorer User Actions”, 
                “RSE Core”, “RSE Terminals UI”, and “Target Management Terminal”.</para></listitem>
                <listitem><para><emphasis>Autotools</emphasis><ulink url='http://download.eclipse.org/technology/linuxtools/update/'></ulink>:
                Expand the items under “Linux Tools” and select “Autotools support for 
                CDT (Incubation)”.</para></listitem>
                <listitem><para><emphasis>Yocto Plug-in</emphasis><ulink url='http://www.yoctoproject.org/downloads/eclipse-plugin/1.0'></ulink>:
                Check the box next to “Development tools &amp; SDKs for Yocto Linux” 
                to select all the items.</para></listitem>
            </orderedlist>
        </para>
        <para>
            Follow these general steps to install a plug-in:
            <orderedlist>
                <listitem><para>From within the Eclipse IDE select the 
                “Install New Software” item from the “Help” menu.</para></listitem>
                <listitem><para>Click “Add…” in the “Work with:” area.</para></listitem>
                <listitem><para>Enter the URL for the repository and leave the “Name” 
                field blank.</para></listitem>
                <listitem><para>Check the boxes next to the software you need to 
                install and then complete the installation.  
                For information on the specific software packages you need to include, 
                see the previous list.</para></listitem>
            </orderedlist>
        </para>
    </section>

    <section id='configuring-the-plug-in'>
    <title>Configuring the Plug-in</title>
        <para>
            Configuring the Eclipse Yocto Plug-in involves choosing the Cross 
            Compiler Options, selecting the Target Architecture, and choosing 
            the Target Options.  
            These settings are the default settings for all projects.  
            You do have opportunities to change them later if you choose to when 
            you configure the project.  
            See “Configuring the Cross Toolchain” section later in the manual.
        </para>
        <para>
            To start, you need to do the following from within the Eclipse IDE:
            <itemizedlist>
                <listitem><para>Choose Windows -&gt; Preferences to display 
                the Preferences Dialog</para></listitem>
                <listitem><para>Click “Yocto SDK”</para></listitem>
            </itemizedlist>
        </para>

        <section id='configuring-the-cross-compiler-options'>
        <title>Configuring the Cross-Compiler Options</title>
            <para>
                Choose between ‘Stand-alone Prebuilt Toolchain’ and ‘Build System Derived Toolchain’ for Cross 
                Compiler Options.
                <itemizedlist>
                    <listitem><para><emphasis>Stand-alone Prebuilt Toolchain</emphasis> – Select this mode 
                    when you are not concerned with building a target image or you do not have 
                    a Yocto Project build tree on your development system.  
                    For example, suppose you are an application developer and do not 
                    need to build a target image.  
                    Instead, you just want to use an architecture-specific toolchain on an 
                    existing kernel and target root filesystem.  
                    When you use Stand-alone Prebuilt Toolchain you are using the toolchain installed 
                    in the <filename>/opt/poky</filename> directory.</para></listitem>
                    <listitem><para><emphasis>Build System Derived Toolchain</emphasis> – Select this mode 
                    if you are building images for target hardware or your 
                    development environment already has a Yocto Project build tree.  
                    In this case you likely already have a Yocto Project build tree installed on 
                    your system or you (or someone else) will be building one.
                    When you select Build System Derived Toolchain you are using the toolchain bundled 
                    inside the Yocto Project build tree.  
                    If you use this mode you must also supply the Yocto Project build directory 
                    in the Preferences Dialog.</para></listitem>
                </itemizedlist>
            </para>
        </section>

        <section id='configuring-the-sysroot'>
        <title>Configuring the Sysroot</title>
            <para>
                Specify the sysroot location, which is where the root filesystem for the 
                target hardware is created on the development system by the ADT Installer.
                The QEMU user-space tools, the 
                NFS boot process and the cross-toolchain all use the sysroot location
                regardless of wheather you select (Stand-alone Prebuilt Toolchain or Build System Derived Toolchain).  
            </para>
        </section>

        <section id='selecting-the-target-architecture'>
        <title>Selecting the Target Architecture</title>
            <para>
                Use the pull-down Target Architecture menu and select the 
                target architecture.
            </para>
            <para>
                The Target Architecture is the type of hardware you are 
                going to use or emulate.  
                This pull-down menu should have the supported architectures.  
                If the architecture you need is not listed in the menu then you 
                will need to re-visit 
                <xref linkend='adt-prepare'>
                “Preparing to Use the Application Development Toolkit (ADT)”</xref> 
                section  earlier in this document.
            </para>
        </section>

        <section id='choosing-the-target-options'>
        <title>Choosing the Target Options</title>
            <para>
                You can choose to emulate hardware using the QEMU emulator, or you 
                can choose to use actual hardware.
                <itemizedlist>
                    <listitem><para><emphasis>External HW</emphasis> – Select this option 
                    if you will be using actual hardware.</para></listitem>
                    <listitem><para><emphasis>QEMU</emphasis> – Select this option if 
                    you will be using the QEMU emulator.  
                    If you are using the emulator you also need to locate the Kernel 
                    and specify any custom options.</para>
                    <para>If you select Build System Derived Toolchain the target kernel you built 
                    will be located in the 
                    Yocto Project build tree in <filename>tmp/deploy/images</filename> directory.   
                    If you select Stand-alone Prebuilt Toolchain the pre-built kernel you downloaded is located 
                    in the directory you specified when you downloaded the image.</para>
                    <para>Most custom options are for advanced QEMU users to further 
                    customize their QEMU instance.  
                    These options are specified between paired angled brackets.  
                    Some options must be specified outside the brackets.
                    In particular, the options <filename>serial</filename>, 
                    <filename>nographic</filename>, and <filename>kvm</filename> must all 
                    be outside the brackets.  
                    Use the <filename>man qemu</filename> command to get help on all the options
                    and their use.  
                    The following is an example:
                        <literallayout class='monospaced'>
    serial ‘&lt;-m 256 -full-screen&gt;</literallayout>
                    </para>
                    <para>
                    Regardless of the mode, Sysroot is already defined in the “Sysroot” 
                    field.</para></listitem>
                </itemizedlist>
            </para>
            <para>
                Click the “OK” button to save your plug-in configurations.
            </para>
        </section>
    </section>
</section>

<section id='creating-the-project'>
<title>Creating the Project</title>
    <para>
        You can create two types of projects:  Autotools-based, or Makefile-based.  
        This section describes how to create autotools-based projects from within 
        the Eclipse IDE.  
        For information on creating projects in a terminal window see 
        <xref linkend='using-the-command-line'> “Using the Command Line”</xref> 
        section.
    </para>
    <para>
        To create a project based on a Yocto template and then display the source code, 
        follow these steps:
        <orderedlist>
            <listitem><para>Select File -> New -> Project.</para></listitem>
            <listitem><para>Double click “CC++”.</para></listitem>
            <listitem><para>Double click “C Project” to create the project.</para></listitem>
            <listitem><para>Double click “Yocto SDK Project”.</para></listitem>
            <listitem><para>Select “Hello World ANSI C Autotools Project”.  
            This is an Autotools-based project based on a Yocto Project template.</para></listitem>
            <listitem><para>Put a name in the “Project name:” field.</para></listitem>
            <listitem><para>Click “Next”.</para></listitem>
            <listitem><para>Add information in the “Author” field.</para></listitem>
            <listitem><para>Use “GNU General Public License v2.0” for the License.</para></listitem>
            <listitem><para>Click “Finish”.</para></listitem>
            <listitem><para>Answer ‘Yes” to the open perspective prompt.</para></listitem>
            <listitem><para>In the Project Explorer expand your project.</para></listitem>
            <listitem><para>Expand ‘src’.</para></listitem>
            <listitem><para>Double click on your source file and the code appears 
            in the window.  
            This is the template.</para></listitem>
        </orderedlist>
    </para>
</section>

<section id='configuring-the-cross-toolchains'>
<title>Configuring the Cross-Toolchains</title>
    <para>
        The previous section, <xref linkend='configuring-the-cross-compiler-options'>
        “Configuring the Cross-Compiler Options”</xref>, set up the default project 
        configurations.  
        You can change these settings for a given project by following these steps:
        <orderedlist>
            <listitem><para>Select Project -> Invoke Yocto Tools -> Reconfigure Yocto.  
            This brings up the project's Yocto Settings Dialog.  
            Settings are inherited from the default project configuration.  
            The information in this dialogue is identical to that chosen earlier 
            for the Cross Compiler Option (Stand-alone Prebuilt Toolchain or Build System Derived Toolchain), 
            the Target Architecture, and the Target Options.  
            The settings are inherited from the Yocto Plug-in configuration performed 
            after installing the plug-in.</para></listitem>
            <listitem><para>Select Project -> Reconfigure Project.  
            This runs the <filename>autogen.sh</filename> in the workspace for your project.  
            The script runs <filename>libtoolize</filename>, <filename>aclocal</filename>,
            <filename>autoconf</filename>, <filename>autoheader</filename>, 
            <filename>automake &dash;&dash;a</filename>, and 
            <filename>./configure</filename>.</para></listitem>
        </orderedlist>
    </para>
</section>

<section id='building-the-project'>
<title>Building the Project</title>
    <para>
        To build the project, select Project -&gt; Build Project.  
        The console should update and you can note the cross-compiler you are using.
    </para>
</section>

<section id='starting-qemu-in-user-space-nfs-mode'>
<title>Starting QEMU in User Space NFS Mode</title>
    <para>
        To start the QEMU emulator from within Eclipse, follow these steps:
        <orderedlist>
            <listitem><para>Select Run -> External Tools -> External Tools Configurations...
            This selection brings up the External Tools Configurations Dialogue.</para></listitem>
            <listitem><para>Go to the left navigation area and expand ‘Program’.  
            You should find the image listed.  
            For example, qemu-x86_64-poky-linux.</para></listitem>
            <listitem><para>Click on the image.  
            This brings up a new environment in the main area of the External 
            Tools Configurations Dialogue.  
            The Main tab is selected.</para></listitem>
            <listitem><para>Click “Run” next.  
            This brings up a shell window.</para></listitem>
            <listitem><para>Enter your host root password in the shell window at the prompt.  
            This sets up a Tap 0 connection needed for running in user-space NFS mode.</para></listitem>
            <listitem><para>Wait for QEMU to launch.</para></listitem>
            <listitem><para>Once QEMU launches you need to determine the IP Address 
            for the user-space NFS.  
            You can do that by going to a terminal in the QEMU and entering the 
            <filename>ipconfig</filename> command.</para></listitem>
        </orderedlist>
    </para>
</section>

<section id='deploying-and-debugging-the-application'>
<title>Deploying and Debugging the Application</title>
    <para>
        Once QEMU is running you can deploy your application and use the emulator 
        to perform debugging.  
        Follow these steps to deploy the application.
        <orderedlist>
            <listitem><para>Select Run -> Debug Configurations...</para></listitem>
            <listitem><para>In the left area expand “C/C++Remote Application”.</para></listitem>
            <listitem><para>Locate your project and select it to bring up a new 
            tabbed view in the Debug Configurations dialogue.</para></listitem>
            <listitem><para>Enter the absolute path into which you want to deploy 
            the application.  
            Use the Remote Absolute File Path for C/C++Application:.  
            For example, enter <filename>/usr/bin/&lt;programname&gt;</filename>.</para></listitem>
            <listitem><para>Click on the Debugger tab to see the cross-tool debugger 
            you are using.</para></listitem>
            <listitem><para>Create a new connection to the QEMU instance 
            by clicking on “new”.</para></listitem>
            <listitem><para>Select “TCF, which means Target Communication Framework.</para></listitem>
            <listitem><para>Click “Next”.</para></listitem>
            <listitem><para>Clear out the “host name” field and enter the IP Address 
            determined earlier.</para></listitem>
            <listitem><para>Click Finish to close the new connections dialogue.</para></listitem>
            <listitem><para>Use the drop-down menu now in the “Connection” field and pick 
            the IP Address you entered.</para></listitem>
            <listitem><para>Click “Debug” to bring up a login screen and login.</para></listitem>
            <listitem><para>Accept the debug perspective.</para></listitem>
        </orderedlist>
    </para>
</section>

<section id='running-user-space-tools'>
<title>Running User-Space Tools</title>
    <para>
        As mentioned earlier in the manual several tools exist that enhance 
        your development experience.  
        These tools are aids in developing and debugging applications and images.  
        You can run these user-space tools from within the Yocto Eclipse 
        Plug-in through the Window -> YoctoTools menu.
    </para>
    <para>
        Once you pick a tool you need to configure it for the remote target. 
        Every tool needs to have the connection configured. 
        You must select an existing TCF-based RSE connection to the remote target. 
        If one does not exist, click "New" to create one.
    </para>
    <para>
        Here are some specifics about the remote tools:
        <itemizedlist>
            <listitem><para><emphasis>OProfile:</emphasis>  Selecting this tool causes 
            the oprofile-server on the remote target to launch on the local host machine.  
            The oprofile-viewer must be installed on the local host machine and the 
            oprofile-server must be installed on the remote target, respectively, in order 
            to use.  
            You can locate both the viewer and server from 
            <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/oprofileui/'></ulink>.  
            You need to compile and install the oprofile-viewer from the source code 
            on your local host machine.  
            The oprofile-server is installed by default in the image.</para></listitem>
            <listitem><para><emphasis>Lttng-ust:</emphasis>  Selecting this tool runs 
            <filename>usttrace</filename> on the remote target, transfers the output data back to the 
            local host machine and uses <filename>lttv-gui</filename> to graphically display the output.  
            The <filename>lttv-gui</filename> must be installed on the local host machine to use this tool.  
            For information on how to use <filename>lttng</filename> to trace an application, see 
            <ulink url='http://lttng.org/files/ust/manual/ust.html'></ulink>.</para>
            <para>For "Application" you must supply the absolute path name of the 
            application to be traced by user mode lttng.  
            For example, typing <filename>/path/to/foo</filename> triggers 
            <filename>usttrace /path/to/foo</filename> on the remote target to trace the 
            program <filename>/path/to/foo</filename>.</para>
            <para>"Argument" is passed to <filename>usttrace</filename>
            running on the remote target.</para></listitem>
            <listitem><para><emphasis>PowerTOP:</emphasis>  Selecting this tool runs 
            "PowerTOP" on the remote target machine and displays the results in a 
            new view called "powertop".</para>
            <para>"Time to gather data(sec):" is the time passed in seconds before data 
            is gathered from the remote target for analysis.</para>
            <para>"show pids in wakeups list:" corresponds to the <filename>-p</filename> argument 
            passed to <filename>powertop</filename>.</para></listitem>
            <listitem><para><emphasis>LatencyTOP and Perf:</emphasis>  "LatencyTOP" 
            identifies system latency, while <filename>perf</filename> monitors the system's 
            performance counter registers. 
            Selecting either of these tools causes an RSE terminal view to appear 
            from which you can run the tools. 
            Both tools refresh the entire screen to display results while they run.</para></listitem>
        </itemizedlist>
    </para>
</section> 

</chapter>
<!--
vim: expandtab tw=80 ts=4
-->