summaryrefslogtreecommitdiffstats
path: root/handbook/development.xml
diff options
context:
space:
mode:
authorRichard Purdie <richard@openedhand.com>2008-02-28 16:10:56 +0000
committerRichard Purdie <richard@openedhand.com>2008-02-28 16:10:56 +0000
commit2e7348694df9520306179d19b64fd382602fea6f (patch)
tree0b54d0a6b79092b5877874f791f37e9068377234 /handbook/development.xml
parentaf790c334a0ed1d95b641b2e1f92f59af52da01d (diff)
downloadpoky-2e7348694df9520306179d19b64fd382602fea6f.tar.gz
poky-handbook: Add screenshots, change development section order, tweak css for screenshots
git-svn-id: https://svn.o-hand.com/repos/poky/trunk@3877 311d38ba-8fff-0310-9ca6-ca027cbcb966
Diffstat (limited to 'handbook/development.xml')
-rw-r--r--handbook/development.xml317
1 files changed, 177 insertions, 140 deletions
diff --git a/handbook/development.xml b/handbook/development.xml
index c56c69ca79..ee98265ca0 100644
--- a/handbook/development.xml
+++ b/handbook/development.xml
@@ -37,6 +37,172 @@
37 </para> 37 </para>
38 </section> 38 </section>
39 39
40 <section id="platdev-appdev-external-anjuta">
41 <title>Developing externally using the Anjuta plugin</title>
42
43 <para>
44 An Anjuta IDE plugin exists to make developing software within the Poky framework
45 easier for the application developer. It presents a graphical IDE from which the
46 developer can cross compile an application then deploy and execute the output in a QEMU
47 emulation session. It also supports cross debugging and profiling.
48 </para>
49
50 <screenshot>
51 <mediaobject>
52 <imageobject>
53 <imagedata fileref="screenshots/ss-anjuta-poky-1.png" format="PNG"/>
54 </imageobject>
55 <caption>
56 <para>The Anjuta Poky SDK plugin showing an active QEMU session running Sato</para>
57 </caption>
58 </mediaobject>
59 </screenshot>
60
61 <para>
62 To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta and the Anjuta
63 plugin. The Poky Anjuta plugin is available from the OpenedHand SVN repository located at
64 http://svn.o-hand.com/repos/anjuta-poky/trunk/anjuta-plugin-sdk/; a web interface
65 to the repository can be accessed at <ulink url='http://svn.o-hand.com/view/anjuta-poky/'/>.
66 See the README file contained in the project for more information
67 about the dependencies and how to get them along with details of
68 the prebuilt packages.
69 </para>
70
71 <section id="platdev-appdev-external-anjuta-setup">
72 <title>Setting up the Anjuta plugin</title>
73
74 <para>Extract the tarball for the toolchain into / as root. The
75 toolchain will be installed into
76 <filename class="directory">/usr/local/poky</filename>.</para>
77
78 <para>To use the plugin, first open or create an existing
79 project. If creating a new project the "C GTK+" project type
80 will allow itself to be cross-compiled. However you should be
81 aware that this uses glade for the UI.</para>
82
83 <para>To activate the plugin go to
84 <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>,
85 then choose <guilabel>General</guilabel> from the left hand side. Choose the
86 Installed plugins tab, scroll down to <guilabel>Poky
87 SDK</guilabel> and check the
88 box. The plugin is now activated but first it must be
89 configured.</para>
90 </section>
91
92 <section id="platdev-appdev-external-anjuta-configuration">
93 <title>Configuring the Anjuta plugin</title>
94
95 <para>The configuration options for the SDK can be found by choosing
96 the <guilabel>Poky SDK</guilabel> icon from the left hand side. The following options
97 need to be set:</para>
98
99 <itemizedlist>
100
101 <listitem><para><guilabel>SDK root</guilabel>: this is the root directory of the SDK
102 for an ARM EABI SDK this will be <filename
103 class="directory">/usr/local/poky/eabi-glibc/arm</filename>.
104 This directory will contain directories named like "bin",
105 "include", "var", etc. With the file chooser it is important
106 to enter into the "arm" subdirectory for this
107 example.</para></listitem>
108
109 <listitem><para><guilabel>Toolchain triplet</guilabel>: this is the cross compile
110 triplet, e.g. "arm-poky-linux-gnueabi".</para></listitem>
111
112 <listitem><para><guilabel>Kernel</guilabel>: use the file chooser to select the kernel
113 to use with QEMU</para></listitem>
114
115 <listitem><para><guilabel>Root filesystem</guilabel>: use the file chooser to select
116 the root filesystem image, this should be an image (not a
117 tarball)</para></listitem>
118 </itemizedlist>
119
120 <screenshot>
121 <mediaobject>
122 <imageobject>
123 <imagedata fileref="screenshots/ss-anjuta-poky-2.png" format="PNG"/>
124 </imageobject>
125 <caption>
126 <para>Anjuta Preferences Dialog</para>
127 </caption>
128 </mediaobject>
129 </screenshot>
130
131
132 </section>
133
134 <section id="platdev-appdev-external-anjuta-usage">
135 <title>Using the Anjuta plugin</title>
136
137 <para>As an example, cross-compiling a project, deploying it into
138 QEMU and running a debugger against it and then doing a system
139 wide profile.</para>
140
141 <para>Choose <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
142 Configure</guimenuitem></menuchoice> or
143 <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
144 Autogenerate</guimenuitem></menuchoice> to run "configure"
145 (or to run "autogen") for the project. This passes command line
146 arguments to instruct it to cross-compile.</para>
147
148 <para>Next do
149 <menuchoice><guimenu>Build</guimenu><guimenuitem>Build
150 Project</guimenuitem></menuchoice> to build and compile the
151 project. If you have previously built the project in the same
152 tree without using the cross-compiler you may find that your
153 project fails to link. Simply do
154 <menuchoice><guimenu>Build</guimenu><guimenuitem>Clean
155 Project</guimenuitem></menuchoice> to remove the old
156 binaries. You may then try building again.</para>
157
158 <para>Next start QEMU by using
159 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Start
160 QEMU</guimenuitem></menuchoice>, this will start QEMU and
161 will show any error messages in the message view. Once Poky has
162 fully booted within QEMU you may now deploy into it.</para>
163
164 <para>Once built and QEMU is running, choose
165 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Deploy</guimenuitem></menuchoice>,
166 this will install the package into a temporary directory and
167 then copy using rsync over SSH into the target. Progress and
168 messages will be shown in the message view.</para>
169
170 <para>To debug a program installed into onto the target choose
171 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Debug
172 remote</guimenuitem></menuchoice>. This prompts for the
173 local binary to debug and also the command line to run on the
174 target. The command line to run should include the full path to
175 the to binary installed in the target. This will start a
176 gdbserver over SSH on the target and also an instance of a
177 cross-gdb in a local terminal. This will be preloaded to connect
178 to the server and use the <guilabel>SDK root</guilabel> to find
179 symbols. This gdb will connect to the target and load in
180 various libraries and the target program. You should setup any
181 breakpoints or watchpoints now since you might not be able to
182 interrupt the execution later. You may stop
183 the debugger on the target using
184 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Stop
185 debugger</guimenuitem></menuchoice>.</para>
186
187 <para>It is also possible to execute a command in the target over
188 SSH, the appropriate environment will be be set for the
189 execution. Choose
190 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Run
191 remote</guimenuitem></menuchoice> to do this. This will open
192 a terminal with the SSH command inside.</para>
193
194 <para>To do a system wide profile against the system running in
195 QEMU choose
196 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Profile
197 remote</guimenuitem></menuchoice>. This will start up
198 OProfileUI with the appropriate parameters to connect to the
199 server running inside QEMU and will also supply the path to the
200 debug information necessary to get a useful profile.</para>
201
202 </section>
203 </section>
204
205
40 <section id="platdev-appdev-qemu"> 206 <section id="platdev-appdev-qemu">
41 <title>Developing externally in QEMU</title> 207 <title>Developing externally in QEMU</title>
42 <para> 208 <para>
@@ -233,146 +399,6 @@ $ bitbake matchbox-desktop -c devshell
233 </para> 399 </para>
234 </section> 400 </section>
235 401
236 <section id="platdev-appdev-external-anjuta">
237 <title>Developing externally using the Anjuta plugin</title>
238
239 <para>
240 An Anjuta IDE plugin exists to make developing software within the Poky framework
241 easier for the application developer. It presents a graphical IDE from which the
242 developer can cross compile an application then deploy and execute the output in a QEMU
243 emulation session. It also supports cross debugging and profiling.
244 </para>
245
246 <para>
247 To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta and the Anjuta
248 plugin. The Poky Anjuta plugin is available from the OpenedHand SVN repository located at
249 http://svn.o-hand.com/repos/anjuta-poky/trunk/anjuta-plugin-sdk/; a web interface
250 to the repository can be accessed at <ulink url='http://svn.o-hand.com/view/anjuta-poky/'/>.
251 See the README file contained in the project for more information
252 about the dependencies and how to get them along with details of
253 the prebuilt packages.
254 </para>
255
256 <section id="platdev-appdev-external-anjuta-setup">
257 <title>Setting up the Anjuta plugin</title>
258
259 <para>Extract the tarball for the toolchain into / as root. The
260 toolchain will be installed into
261 <filename class="directory">/usr/local/poky</filename>.</para>
262
263 <para>To use the plugin, first open or create an existing
264 project. If creating a new project the "C GTK+" project type
265 will allow itself to be cross-compiled. However you should be
266 aware that this uses glade for the UI.</para>
267
268 <para>To activate the plugin go
269 <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>,
270 then choose <guilabel>General</guilabel> from the left hand side. Choose the
271 Installed plugins tab, scroll down to <guilabel>Poky
272 SDK</guilabel> and check the
273 box. The plugin is now activated but first it must be
274 configured.</para> </section>
275
276 <section id="platdev-appdev-external-anjuta-configuration">
277 <title>Configuring the Anjuta plugin</title>
278
279 <para>The configuration options for the SDK can be found by choosing
280 the <guilabel>Poky SDK</guilabel> icon from the left hand side. The following options
281 need to be set:</para>
282
283 <itemizedlist>
284
285 <listitem><para><guilabel>SDK root</guilabel>: this is the root directory of the SDK
286 for an ARM EABI SDK this will be <filename
287 class="directory">/usr/local/poky/eabi-glibc/arm</filename>.
288 This directory will contain directories named like "bin",
289 "include", "var", etc. With the file chooser it is important
290 to enter into the "arm" subdirectory for this
291 example.</para></listitem>
292
293 <listitem><para><guilabel>Toolchain triplet</guilabel>: this is the cross compile
294 triplet, e.g. "arm-poky-linux-gnueabi".</para></listitem>
295
296 <listitem><para><guilabel>Kernel</guilabel>: use the file chooser to select the kernel
297 to use with QEMU</para></listitem>
298
299 <listitem><para><guilabel>Root filesystem</guilabel>: use the file chooser to select
300 the root filesystem image, this should be an image (not a
301 tarball)</para></listitem>
302 </itemizedlist>
303
304 </section>
305
306 <section id="platdev-appdev-external-anjuta-usage">
307 <title>Using the Anjuta plugin</title>
308
309 <para>As an example, cross-compiling a project, deploying it into
310 QEMU and running a debugger against it and then doing a system
311 wide profile.</para>
312
313 <para>Choose <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
314 Configure</guimenuitem></menuchoice> or
315 <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
316 Autogenerate</guimenuitem></menuchoice> to run "configure"
317 (or to run "autogen") for the project. This passes command line
318 arguments to instruct it to cross-compile.</para>
319
320 <para>Next do
321 <menuchoice><guimenu>Build</guimenu><guimenuitem>Build
322 Project</guimenuitem></menuchoice> to build and compile the
323 project. If you have previously built the project in the same
324 tree without using the cross-compiler you may find that your
325 project fails to link. Simply do
326 <menuchoice><guimenu>Build</guimenu><guimenuitem>Clean
327 Project</guimenuitem></menuchoice> to remove the old
328 binaries. You may then try building again.</para>
329
330 <para>Next start QEMU by using
331 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Start
332 QEMU</guimenuitem></menuchoice>, this will start QEMU and
333 will show any error messages in the message view. Once Poky has
334 fully booted within QEMU you may now deploy into it.</para>
335
336 <para>Once built and QEMU is running, choose
337 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Deploy</guimenuitem></menuchoice>,
338 this will install the package into a temporary directory and
339 then copy using rsync over SSH into the target. Progress and
340 messages will be shown in the message view.</para>
341
342 <para>To debug a program installed into onto the target choose
343 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Debug
344 remote</guimenuitem></menuchoice>. This prompts for the
345 local binary to debug and also the command line to run on the
346 target. The command line to run should include the full path to
347 the to binary installed in the target. This will start a
348 gdbserver over SSH on the target and also an instance of a
349 cross-gdb in a local terminal. This will be preloaded to connect
350 to the server and use the <guilabel>SDK root</guilabel> to find
351 symbols. This gdb will connect to the target and load in
352 various libraries and the target program. You should setup any
353 breakpoints or watchpoints now since you might not be able to
354 interrupt the execution later. You may stop
355 the debugger on the target using
356 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Stop
357 debugger</guimenuitem></menuchoice>.</para>
358
359 <para>It is also possible to execute a command in the target over
360 SSH, the appropriate environment will be be set for the
361 execution. Choose
362 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Run
363 remote</guimenuitem></menuchoice> to do this. This will open
364 a terminal with the SSH command inside.</para>
365
366 <para>To do a system wide profile against the system running in
367 QEMU choose
368 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Profile
369 remote</guimenuitem></menuchoice>. This will start up
370 OProfileUI with the appropriate parameters to connect to the
371 server running inside QEMU and will also supply the path to the
372 debug information necessary to get a useful profile.</para>
373
374 </section>
375 </section>
376 </section> 402 </section>
377 403
378<section id="platdev-gdb-remotedebug"> 404<section id="platdev-gdb-remotedebug">
@@ -660,6 +686,17 @@ $ opreport -cl
660 are installed onto the target device for OProfileUI interaction. 686 are installed onto the target device for OProfileUI interaction.
661 </para> 687 </para>
662 688
689 <screenshot>
690 <mediaobject>
691 <imageobject>
692 <imagedata fileref="screenshots/ss-oprofile-viewer.png" format="PNG"/>
693 </imageobject>
694 <caption>
695 <para>OProfileUI Viewer showing an application being profiled on a remote device</para>
696 </caption>
697 </mediaobject>
698 </screenshot>
699
663 <para> 700 <para>
664 In order to convert the data in the sample format from the target 701 In order to convert the data in the sample format from the target
665 to the host the <filename>opimport</filename> program is needed. 702 to the host the <filename>opimport</filename> program is needed.