summaryrefslogtreecommitdiffstats
path: root/documentation/poky-ref-manual/development.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/poky-ref-manual/development.xml')
-rw-r--r--documentation/poky-ref-manual/development.xml519
1 files changed, 274 insertions, 245 deletions
diff --git a/documentation/poky-ref-manual/development.xml b/documentation/poky-ref-manual/development.xml
index 67badce777..0eda1e9a88 100644
--- a/documentation/poky-ref-manual/development.xml
+++ b/documentation/poky-ref-manual/development.xml
@@ -14,22 +14,26 @@
14 <section id="platdev-appdev-external-sdk"> 14 <section id="platdev-appdev-external-sdk">
15 <title>External Development Using the Poky SDK</title> 15 <title>External Development Using the Poky SDK</title>
16 <para> 16 <para>
17 The meta-toolchain and meta-toolchain-sdk targets (<link linkend='ref-images'>see 17 The meta-toolchain and meta-toolchain-sdk targets build tarballs that contain toolchains and
18 the images section</link>) build tarballs that contain toolchains and 18 libraries suitable for application development outside of Poky.
19 libraries suitable for application development outside of Poky. These tarballs 19 For information on these targets see the <ulink linkend='ref-images'>Reference: Images</ulink>
20 unpack into the 20 appendix.
21 </para>
22 <para>
23 These tarballs unpack into the
21 <filename class="directory">/opt/poky</filename> directory and contain 24 <filename class="directory">/opt/poky</filename> directory and contain
22 a setup script (e.g. 25 a setup script (e.g.
23 <filename>/opt/poky/environment-setup-i586-poky-linux</filename>, which 26 <filename>/opt/poky/environment-setup-i586-poky-linux</filename>), from which
24 you can source to initialize a suitable environment. Sourcing these adds the 27 you can source to initialize a suitable environment. Sourcing these files adds the
25 compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other 28 compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other
26 useful utilities to the PATH variable. Variables to assist pkgconfig and 29 useful utilities to the PATH variable. Variables to assist pkgconfig and
27 autotools are also set so that, for example, configure can find pre-generated test 30 autotools are also defined so that, for example, configure can find pre-generated test
28 results for tests that need target hardware on which to run. 31 results for tests that need target hardware on which to run.
29 </para> 32 </para>
30 <para> 33 <para>
31 Using the toolchain with autotool-enabled packages is straightforward - just pass the 34 Using the toolchain with autotool-enabled packages is straightforward - just pass the
32 appropriate host option to configure as in the following example: 35 appropriate host option to configure.
36 Following is an example:
33 <literallayout class='monospaced'> 37 <literallayout class='monospaced'>
34 $ ./configure --host=arm-poky-linux-gnueabi 38 $ ./configure --host=arm-poky-linux-gnueabi
35 </literallayout> 39 </literallayout>
@@ -47,7 +51,7 @@
47 easier for the application developer. The plug-ins provide capability 51 easier for the application developer. The plug-ins provide capability
48 extensions to the graphical IDE allowing for cross compilation, 52 extensions to the graphical IDE allowing for cross compilation,
49 deployment and execution of the output in a QEMU emulation session. 53 deployment and execution of the output in a QEMU emulation session.
50 Support of these plug-ins also supports cross debugging and 54 Support of these plug-ins also allows for cross debugging and
51 profiling. Additionally, the Eclipse plug-in provides a suite of tools 55 profiling. Additionally, the Eclipse plug-in provides a suite of tools
52 that allows the developer to perform remote profiling, tracing, collection of 56 that allows the developer to perform remote profiling, tracing, collection of
53 power data, collection of latency data and collection of performance data. 57 power data, collection of latency data and collection of performance data.
@@ -57,13 +61,13 @@
57 <title>The Eclipse Plug-in</title> 61 <title>The Eclipse Plug-in</title>
58 <para> 62 <para>
59 To use the Eclipse plug-in, a toolchain and SDK built by Poky is required along with 63 To use the Eclipse plug-in, a toolchain and SDK built by Poky is required along with
60 the Eclipse Framework (Helios 3.6). 64 the Eclipse Framework (Helios 3.6.1).
61 To install the plug-in you need to be in the Eclipse IDE and select 65 To install the plug-in you need to be in the Eclipse IDE and select
62 the following menu: 66 the following menu:
63 <literallayout class='monospaced'> 67 <literallayout class='monospaced'>
64 Help -> Install New Software 68 Help -> Install New Software
65 </literallayout> 69 </literallayout>
66 Specify the target URL as http://yocto./download (real link needed). 70 Specify the target URL as <ulink url='http://www.yoctoproject.org/downloads/eclipse-plugin/'></ulink>.
67 </para> 71 </para>
68 <para> 72 <para>
69 If you want to download the source code for the plug-in you can find it in the Poky 73 If you want to download the source code for the plug-in you can find it in the Poky
@@ -74,23 +78,25 @@
74 <section id="installing-and-setting-up-the-eclipse-ide"> 78 <section id="installing-and-setting-up-the-eclipse-ide">
75 <title>Installing and Setting up the Eclipse IDE</title> 79 <title>Installing and Setting up the Eclipse IDE</title>
76 <para> 80 <para>
77 If you don't have the Eclipse IDE (Helios 3.6) on your system you need to 81 If you don't have the Eclipse IDE (Helios 3.6.1) on your system you need to
78 download and install it from <ulink url="http://www.eclipse.org/downloads"></ulink>. 82 download and install it from <ulink url="http://www.eclipse.org/downloads"></ulink>.
79 Choose the Eclipse Classic, which contains the Eclipse Platform, Java Development 83 Choose the Eclipse Classic, which contains the Eclipse Platform, Java Development
80 Tools (JDT), and the Plug-in Development Environment. 84 Tools (JDT), and the Plug-in Development Environment.
81 </para> 85 </para>
82 <para> 86 <note>
83 NOTE: Due to the Java Virtual Machine's garbage collection (GC) process the 87 <para>
84 permanent generation space (PermGen) is not cleaned up. This space is used 88 Due to the Java Virtual Machine's garbage collection (GC) process the
85 to store meta-data descriptions of classes. The default value is set too small 89 permanent generation space (PermGen) is not cleaned up. This space stores
86 and it could trigger an out of memory error like the following: 90 meta-data descriptions of classes. The default value is set too small
91 and it could trigger an out-of-memory error like the following:
87 <literallayout class='monospaced'> 92 <literallayout class='monospaced'>
88 Java.lang.OutOfMemoryError: PermGen space 93 Java.lang.OutOfMemoryError: PermGen space
89 </literallayout> 94 </literallayout>
90 This error causes the applications to hang. 95 This error causes the applications to hang.
91 </para> 96 </para>
97 </note>
92 <para> 98 <para>
93 To fix this issue you can use the <command>-vmargs</command> 99 To fix this issue you can use the <filename>-vmargs</filename>
94 option when you start Eclipse to increase the size of the permenant generation space: 100 option when you start Eclipse to increase the size of the permenant generation space:
95 <literallayout class='monospaced'> 101 <literallayout class='monospaced'>
96 Eclipse -vmargs -XX:PermSize=256M 102 Eclipse -vmargs -XX:PermSize=256M
@@ -101,149 +107,173 @@
101 <section id="installing-the-yocto-plug-in"> 107 <section id="installing-the-yocto-plug-in">
102 <title>Installing the Yocto Plug-in</title> 108 <title>Installing the Yocto Plug-in</title>
103 <para> 109 <para>
104 Once you have the Eclipse IDE installed and configure you need to install the 110 Once you have the Eclipse IDE installed and configured you need to install the
105 Yocto plug-in. You do this similar to installing the Eclipse plug-ins in the 111 Yocto plug-in. You do this similar to installing the Eclipse plug-ins in the
106 previous section. 112 previous section.
107 </para> 113 </para>
108 <para> 114 <para>
109 Do the following to install the Yocto plug-in into the Eclipse IDE: 115 Do the following to install the Yocto plug-in into the Eclipse IDE:
110 <itemizedlist> 116 <orderedlist>
111 <listitem>Select the "Help -> Install New Software" item.</listitem> 117 <listitem>Select the "Help -> Install New Software" item.</listitem>
112 <listitem>In the "Work with:" area click "Add..." and enter the URL for 118 <listitem>In the "Work with:" area click "Add..." and enter the URL for
113 the Yocto plug-in (we need to supply this URL).</listitem> 119 the Yocto plug-in, which is
120 <ulink url='http://www.yoctoproject.org/downloads/eclipse-plugin/'></ulink></listitem>
114 <listitem>Finish out the installation of the update similar to any other 121 <listitem>Finish out the installation of the update similar to any other
115 Eclipse plug-in.</listitem> 122 Eclipse plug-in.</listitem>
116 </itemizedlist> 123 </orderedlist>
117 </para> 124 </para>
118 </section> 125 </section>
119 126
120 <section id="configuring-yocto-eclipse-plug-in"> 127 <section id="configuring-yocto-eclipse-plug-in">
121 <title>Configuring Yocto Eclipse plug-in</title> 128 <title>Configuring Yocto Eclipse plug-in</title>
122 <para> 129 <para>
123 To configure the Yocto Eclipse plug-in you need to select the mode and then the 130 To configure the Yocto Eclipse plug-in you need to select the mode and the
124 architecture with which you will be working. Start by selecting "Preferences" 131 architecture with which you will be working. Start by selecting "Preferences"
125 from the "Window" menu and then selecting "Yocto SDK". 132 from the "Window" menu and then select "Yocto SDK".
126 </para> 133 </para>
127 <para> 134 <para>
128 If you normally will use an installed Yocto 135 If you normally will use an installed Yocto
129 SDK (under /opt/poky) select “SDK Root Mode”. Otherwise, if your crosstool chain 136 SDK (under <filename>/opt/poky</filename>) select “SDK Root Mode”. Otherwise, if your crosstool chain
130 and sysroot are within your poky tree, select “Poky Tree Mode”. 137 and sysroot are within your poky tree, select “Poky Tree Mode”.
131 If you are in SDK Root Mode you will need to provide your poky tree path, for 138 If you are in SDK Root Mode you need to provide your poky tree path, for
132 example, $&lt;Poky_tree&gt;/build/. 139 example, <filename>$&lt;Poky_tree&gt;/build/</filename>.
133 </para> 140 </para>
134 <para> 141 <para>
135 Now you need to select the architecture. 142 Next, you need to select the architecture.
136 Use the drop down list and select the architecture that you’ll be primarily 143 Use the drop down list and select the architecture that you’ll be primarily
137 working against. 144 working against.
138 For target option, select your typical target QEMU vs External HW. If you 145 For target option, select your typical target QEMU vs External HW. If you
139 choose QEMU, you’ll need to specify your QEMU kernel file with full path and the 146 choose QEMU, you’ll need to specify your QEMU kernel file with full path and the
140 rootfs mount point. Yocto QEMU boots off user mode NFS, Please refer to QEMU 147 rootfs mount point. Yocto QEMU boots off user mode NFS.
141 section for how to set it up. (Section TBD) 148 See the <link linkend='platdev-appdev-qemu'>Developing Externally in QEMU</link> section for
149 how to set it up.
142 </para> 150 </para>
143 <para> 151 <para>
144 Save all your settings and they become your defaults for every new Yocto project 152 To make your settings the defaults for every new Yocto project created using
145 created using the Eclipse IDE. 153 the Eclipse IDE, simply save the settings.
146 </para> 154 </para>
147 </section> 155 </section>
148 156
149 <section id="using-the-yocto-eclipse-plug-in"> 157 <section id="using-the-yocto-eclipse-plug-in">
150 <title>Using the Yocto Eclipse Plug-in</title> 158 <title>Using the Yocto Eclipse Plug-in</title>
151 <para> 159 <para>
152 As an example, this section shows you how to cross-compile a Yocto C autotools 160 As an example, this section shows you how to cross-compile a Yocto C project that
153 based project, deploy it into QEMU, and then run the debugger against it. 161 is autotools-based, deploy the project into QEMU, and then run the debugger against it.
154 You need to configure the project, trigger <command> autogen.sh</command>, build 162 You need to configure the project, trigger the <filename> autogen.sh</filename>, build
155 the image, start QEMU, and then debug. 163 the image, start QEMU, and then debug.
156 </para> 164 </para>
165 <para>
166 The following steps show how to create a Yocto autotools-based project using a given template:
167 </para>
157 <orderedlist> 168 <orderedlist>
158 <listitem>Creating a Yocto Autotools Based Project Using a Template: 169 <listitem>Select "File -> New -> Project" to start the wizard.</listitem>
159 Get to the Wizard selection by selecting the File -> New -> Project 170 <listitem>Expand "C/C++" and select "C Project".</listitem>
160 menu. Expand "C/C++" and select "C Project". Click "Next" and select a template 171 <listitem>Click "Next" and select a template (e.g. "Hello World ANSI C Project").</listitem>
161 to start with, for example "Hello World ANSI C Project". Complete the steps 172 <listitem>Complete the steps to create the new Yocto autotools-based project using
162 to create a new Yocto autotools based project using this template.</listitem> 173 your chosen template.</listitem>
163 <listitem>Specify Specific Toolchain Configurations: By default the project 174 </orderedlist>
164 uses the Yocto preferences settings as defined using the procedure in 175 <para>
165 <link linkend="configuring-yocto-eclipse-plug-in"> the previous section</link>. 176 By default, the project uses the Yocto preferences settings as defined using the procedure in
166 If there are any specific setup requirements for the newly created project 177 <link linkend="configuring-yocto-eclipse-plug-in">the previous section</link>.
167 you need to reconfigure the Yocto plug-in through the menu selection 178 If there are any specific setup requirements for the newly created project
168 Project -> Invoke Yocto Tools -> Reconfigure Yocto. Use this dialogue 179 you need to reconfigure the Yocto plug-in through the menu selection by doing the following:
169 to specify specific toolchain and QEMU setups for the project.</listitem> 180 </para>
170 <listitem>Building the Project: Trigger <command>autogen.sh</command> through 181 <orderedlist>
171 Project -> Reconfigure Project. Then build the project using 182 <listitem>Select the "Project -> Invoke Yocto Tools -> Reconfigure Yocto" menu item.</listitem>
172 Project -> Build.</listitem> 183 <listitem>Complete the dialogue to specify the specific toolchain and QEMU setup information.</listitem>
173 <listitem>Starting QEMU: Use the Run -> External Tools menu and see if there is 184 </orderedlist>
174 a QEMU instance for the desired target. If there is click on the instance 185 <para>
175 to start QEMU. If your target is not there then click "External Tools 186 To build the project follow these steps:
176 Configuration". You should find an instance of QEMU for your architecture 187 </para>
177 under the entry under "Program". After the boot completes you are ready to 188 <orderedlist>
178 deploy the image into QEMU.</listitem> 189 <listitem>Select "Project -> Reconfigure Project" to trigger the
179 <listitem>Debugging: To bring up your remote debugging configuration in the 190 <filename>autogen.sh</filename> command.</listitem>
180 right-hand window highlight your project in “Project Explorer”, select 191 <listitem>Select "Project -> Build" to build the project.</listitem>
181 the Run -> Debug Configurations menu item and expand “C/C++ Remote Application”. 192 </orderedlist>
182 Next, select projectname_ gdb_target-poky-linux. 193 <para>
183 You need to be sure that there is an 194 To start QEMU follow these steps:
184 entry for the remote target you want to deploy and cross debug with. If there 195 </para>
185 is no entry then click "New..." to bring up the wizard. Using the wizard 196 <orderedlist>
186 select TCF and enter the IP address of you remote target in the 197 <listitem>Select "Run -> External Tools" and see if there is
187 “Host name:” field. Back in the remote debug configure window, 198 a QEMU instance for the desired target.
188 you need to specify the absolute path for the program on the remote target 199 If one exists, click on the instance to start QEMU.
189 in the “Remote Absolute File Path for C/C++ Application” field. By default, 200 If your target does not exist, click "External Tools Configuration" and
190 the program deploys into the remote target. If you don't want this then check 201 you should find an instance of QEMU for your architecture
191 “Skip download to target path”. Finally, click "Debug” to start the remote 202 under the entry under "Program".</listitem>
192 debugging session.</listitem> 203 <listitem>Wait for the boot to complete.</listitem>
204 </orderedlist>
205 <para>
206 To deploy your project and start debugging follow these steps:
207 </para>
208 <orderedlist>
209 <listitem>Highlight your project in the project explorer.</listitem>
210 <listitem>Select "Run -> Debug Configurations" to bring up your remote debugging configuration
211 in the right-hand window.</listitem>
212 <listitem>Expand “C/C++ Remote Application”.</listitem>
213 <listitem>Select "projectname_ gdb_target-poky-linux".
214 You need to be sure there is an entry for the remote target.
215 If no entry exists, click "New..." to bring up the wizard.
216 Use the wizard to select TCF and enter the IP address of you remote target in the
217 “Host name:” field.
218 Back in the Remote Debug Configure window, specify in the
219 “Remote Absolute File Path for C/C++ Application” field the absolute path for the program on
220 the remote target.
221 By default, the program deploys into the remote target.
222 If you don't want this behavior then check “Skip download to target path”.</listitem>
223 <listitem>Click "Debug” to start the remote debugging session.</listitem>
193 </orderedlist> 224 </orderedlist>
194 </section> 225 </section>
195 226
196 <section id="using-yocto-eclipse-plug-in-remote-tools-suite"> 227 <section id="using-yocto-eclipse-plug-in-remote-tools-suite">
197 <title>Using Yocto Eclipse plug-in Remote Tools Suite</title> 228 <title>Using Yocto Eclipse plug-in Remote Tools Suite</title>
198 <para> 229 <para>
199 Remote tools let you do things like perform system profiling, kernel tracing, 230 Remote tools allow you to perform system profiling, kernel tracing,
200 examine power consumption, and so forth. To see and access the remote tools use the 231 examine power consumption, and so forth. To see and access the remote tools use the
201 Window -> YoctoTools menu. 232 "Window -> YoctoTools" menu.
202 </para> 233 </para>
203 <para> 234 <para>
204 Once you pick a tool you need to configure it for the remote target. Every tool 235 Once you pick a tool you need to configure it for the remote target. Every tool
205 needs to have the connection configured. You have to select an existing TCF-based 236 needs to have the connection configured. You must select an existing TCF-based
206 RSE connection to the remote target. If one does not exist you need to create one 237 RSE connection to the remote target. If one does not exist, click "New" to create one.
207 by clicking "New"
208 </para> 238 </para>
209 <para> 239 <para>
210 Here are some specifics about the remote tools: 240 Here are some specifics about the remote tools:
211 <itemizedlist> 241 <itemizedlist>
212 <listitem>Oprofile: Selecting this tool causes the oprofile-server on the remote 242 <listitem>Oprofile: Selecting this tool causes the oprofile-server on the remote
213 target to launch on the local host machine. To use the oprofile the oprofile-viewer 243 target to launch on the local host machine. The oprofile-viewer
214 must be installed on the local host machine and the oprofile-server must be 244 must be installed on the local host machine and the oprofile-server must be
215 installed on the remote target.</listitem> 245 installed on the remote target, respectively, in order to use .</listitem>
216 <listitem>lttng: Selecting this tool runs ustrace on the remote target, transfers 246 <listitem>lttng: Selecting this tool runs "ustrace" on the remote target, transfers
217 the output data back to the local host machine and uses lttv-gui to graphically 247 the output data back to the local host machine and uses "lttv-gui" to graphically
218 display the output. To use this tool the lttv-gui must be installed on the 248 display the output. The "lttv-gui" must be installed on the
219 local host machine. See <ulink url="http://lttng.org/files/ust/manual/ust.html"> 249 local host machine to use this tool.
220 </ulink> for information on how to use <command>lttng</command> to trace an 250 For information on how to use "lttng" to trace an
221 application. 251 application, see <ulink url="http://lttng.org/files/ust/manual/ust.html"></ulink>.
222 <para> 252 <para>
223 For "Application" you must supply the absolute path name to the application to 253 For "Application" you must supply the absolute path name of the application to
224 be traced by user mode lttng. For example, typing <command>/path/to/foo" 254 be traced by user mode lttng. For example, typing <filename>/path/to/foo"
225 </command> triggers <command>usttrace /path/to/foo</command> on the 255 </filename> triggers "usttrace /path/to/foo" on the
226 remote target to trace the program <command>/path/to/foo</command>. 256 remote target to trace the program <filename>/path/to/foo</filename>.
227 </para> 257 </para>
228 <para> 258 <para>
229 "Argument" is passed to "usttrace" running on the remote target. 259 "Argument" is passed to "usttrace" running on the remote target.
230 </para> 260 </para>
231 </listitem> 261 </listitem>
232 <listitem>powertop: Selecting this tool runs <command>powertop</command> on the 262 <listitem>powertop: Selecting this tool runs "powertop" on the
233 remote target machine and displays the result in a new view called "powertop". 263 remote target machine and displays the results in a new view called "powertop".
234 <para> 264 <para>
235 "Time to gather data(sec):" is the time passed in seconds before data is 265 "Time to gather data(sec):" is the time passed in seconds before data is
236 gathered from the remote target for analysis. 266 gathered from the remote target for analysis.
237 </para> 267 </para>
238 <para> 268 <para>
239 "show pids in wakeups list:" corresponds to the <command>-p</command> 269 "show pids in wakeups list:" corresponds to the <filename>-p</filename>
240 argument passed to <command>powertop</command> 270 argument passed to "powertop".
241 </para> 271 </para>
242 </listitem> 272 </listitem>
243 <listitem>latencytop and perf: The <command>latencytop</command> identifies 273 <listitem>latencytop and perf: "latencytop" identifies
244 system latency, while <command>perf</command> monitors the system's performance 274 system latency, while "perf" monitors the system's performance
245 counter registers. Selecting either of these tools causes an RSE 275 counter registers. Selecting either of these tools causes an RSE
246 terminal view to appear in which you can run the tools. Both tools refresh the 276 terminal view to appear from which you can run the tools. Both tools refresh the
247 entire screen to display results while they run.</listitem> 277 entire screen to display results while they run.</listitem>
248 </itemizedlist> 278 </itemizedlist>
249 </para> 279 </para>
@@ -252,25 +282,24 @@
252 282
253 <section id="the-anjuta-plug-in"> 283 <section id="the-anjuta-plug-in">
254 <title>The Anjuta Plug-in</title> 284 <title>The Anjuta Plug-in</title>
255 <para> 285 <note>
256 <emphasis>Note:</emphasis> We will stop Anjuta plug-in support after 286 <para>
257 Yocto project 0.9 release. Its source 287 Support for the Anjuta plug-in ends after Yocto project 0.9 release.
258 code can be downloaded from git respository listed below, and free for the community to 288 However, the source code can be downloaded from the git repository listed later in
259 continue supporting it moving forward. 289 this section.
260 </para> 290 The community is free to continue supporting it post 0.9 release.
291 </para>
292 </note>
261 <para> 293 <para>
262 An Anjuta IDE plugin exists to make developing software within the Poky framework 294 An Anjuta IDE plugin exists to make developing software within the Poky framework
263 easier for the application developer. 295 easier for the application developer familiar with that environment.
264 It presents a graphical IDE with which you can cross compile an application 296 The plug-in presents a graphical IDE that allows you to cross-compile, cross-debug,
265 then deploy and execute the output in a 297 profile, deploy, and execute an application.
266 QEMU emulation session.
267 It also supports cross debugging and profiling.
268 </para> 298 </para>
269 <para> 299 <para>
270 To use the plugin, a toolchain and SDK built by Poky is required, 300 To use the plugin, a toolchain and SDK built by Poky, Anjuta, it's development headers and the Anjuta
271 Anjuta, it's development headers and the Anjuta plugin. 301 Plug-in are all required.
272 The Poky Anjuta plugin is available to download as a tarball at the 302 The Poky Anjuta Plug-in is available to download as a tarball at the OpenedHand
273 OpenedHand
274 labs <ulink url="http://labs.o-hand.com/anjuta-poky-sdk-plugin/"></ulink> page or 303 labs <ulink url="http://labs.o-hand.com/anjuta-poky-sdk-plugin/"></ulink> page or
275 directly from the Poky Git repository located at 304 directly from the Poky Git repository located at
276 <ulink url="git://git.pokylinux.org/anjuta-poky"></ulink>. 305 <ulink url="git://git.pokylinux.org/anjuta-poky"></ulink>.
@@ -279,10 +308,9 @@
279 </para> 308 </para>
280 <para> 309 <para>
281 See the README file contained in the project for more information on 310 See the README file contained in the project for more information on
282 Anjuta dependencies and building the plugin. 311 Anjuta dependencies and building the plug-in.
283 If you want to disable remote gdb debugging, 312 If you want to disable remote gdb debugging, pass the "--diable-gdb-integration" switch when
284 please pass the <command>--diable-gdb-integration</command> switch when doing 313 you configure the plug-in.
285 configure.
286 </para> 314 </para>
287 <section id="setting-up-the-anjuta-plugin"> 315 <section id="setting-up-the-anjuta-plugin">
288 <title>Setting Up the Anjuta Plug-in</title> 316 <title>Setting Up the Anjuta Plug-in</title>
@@ -290,18 +318,17 @@
290 Follow these steps to set up the plug-in: 318 Follow these steps to set up the plug-in:
291 <orderedlist> 319 <orderedlist>
292 <listitem>Extract the tarball for the toolchain into / as root. 320 <listitem>Extract the tarball for the toolchain into / as root.
293 The toolchain will be installed into <command>/opt/poky</command>.</listitem> 321 The toolchain will be installed into <filename>/opt/poky</filename>.</listitem>
294 <listitem>To use the plug-in, first open or create an existing project. 322 <listitem>To use the plug-in, first open or create an existing project.
295 If you are creating a new project, the "C GTK+" 323 If you are creating a new project, the "C GTK+"
296 project type will allow itself to be cross-compiled. 324 project type will allow itself to be cross-compiled.
297 However you should be aware that this uses glade for the UI.</listitem> 325 However, you should be aware that this type uses "glade" for the UI.</listitem>
298 <listitem>To activate the plug-in go to Edit -> Preferences, then choose 326 <listitem>To activate the plug-in, select "Edit -> Preferences" and then choose
299 General from the left hand side. 327 "General" from the left hand side.
300 Choose the Installed plug-ins tab, scroll down to Poky SDK and 328 Choose the "Installed plug-ins" tab, scroll down to "Poky SDK" and
301 check the box.</listitem> 329 check the box.</listitem>
302 </orderedlist> 330 </orderedlist>
303 The plug-in is now activated but not configured. 331 The plug-in is now activated but not configured.
304 See the next section to learn how to configure it.
305 </para> 332 </para>
306 </section> 333 </section>
307 <section id="configuring-the-anjuta-plugin"> 334 <section id="configuring-the-anjuta-plugin">
@@ -309,89 +336,82 @@
309 <para> 336 <para>
310 You can find the configuration options for the SDK by choosing the Poky 337 You can find the configuration options for the SDK by choosing the Poky
311 SDK icon from the left hand side. 338 SDK icon from the left hand side.
312 You need to set the following options: 339 You need to define the following options:
313 <itemizedlist> 340 <itemizedlist>
314 <listitem>SDK root: If you use an external toolchain you need to set 341 <listitem>SDK root: If you use an external toolchain you need to set
315 SDK root. This is the root directory of the 342 SDK root, which is the root directory of the SDK's sysroot.
316 SDK's sysroot. 343 For an i586 SDK directory is <filename>/opt/poky/</filename>.
317 For an i586 SDK this will be <command>/opt/poky/</command>. 344 This directory will contain "bin", "include", "var" and so forth under your
318 This directory will contain <command>bin</command>, <command>include
319 </command>, <command>var</command> and so forth under your
320 selected target architecture subdirectory 345 selected target architecture subdirectory
321 <command>/opt/poky/sysroot/i586-poky-linux/</command>. 346 <filename>/opt/poky/sysroot/i586-poky-linux/</filename>.
322 The cross comple tools you need are in 347 The cross-compile tools you need are in
323 <command>/opt/poky/sysroot/i586-pokysdk-linux/</command>.</listitem> 348 <filename>/opt/poky/sysroot/i586-pokysdk-linux/</filename>.</listitem>
324 <listitem>Poky root: If you have a local poky build tree, you need to 349 <listitem>Poky root: If you have a local Poky build tree, you need to
325 set the Poky root. 350 set the Poky root, which is the root directory of the poky build tree.
326 This is the root directory of the poky build tree.
327 If you build your i586 target architecture under the subdirectory of 351 If you build your i586 target architecture under the subdirectory of
328 <command>build_x86</command> within your poky tree, the Poky root directory 352 <filename>build_x86</filename> within your Poky tree, the Poky root directory
329 should be <command>$&lt;poky_tree&gt;/build_x86/</command>.</listitem> 353 should be <filename>$&lt;poky_tree&gt;/build_x86/</filename>.</listitem>
330 <listitem>Target Architecture: This is the cross compile triplet, 354 <listitem>Target Architecture: This is the cross compile triplet,
331 for example, "i586-poky-linux". 355 for example, "i586-poky-linux".
332 This target triplet is the prefix extracted from the set up script file 356 This target triplet is the prefix extracted from the set up script file's name.
333 name. 357 For example, if the script file name is
334 For example, "i586-poky-linux" is extracted from the 358 <filename>/opt/poky/environment-setup-i586-poky-linux</filename> then the extracted target
335 set up script file 359 triplet is "i586-poky-linux".</listitem>
336 <command>/opt/poky/environment-setup-i586-poky-linux</command>.</listitem> 360 <listitem>Kernel: Use the file chooser to select the kernel used with QEMU.</listitem>
337 <listitem>Kernel: Use the file chooser to select the kernel to use
338 with QEMU.</listitem>
339 <listitem>Root filesystem: Use the file chooser to select the root 361 <listitem>Root filesystem: Use the file chooser to select the root
340 filesystem directory. This directory is where you use the 362 filesystem directory. This directory is where you use "poky-extract-sdk" to extract the
341 <command>poky-extract-sdk</command> to extract the poky-image-sdk 363 poky-image-sdk tarball.</listitem>
342 tarball.</listitem>
343 </itemizedlist> 364 </itemizedlist>
344 </para> 365 </para>
345 </section> 366 </section>
346 <section id="using-the-anjuta-plug-in"> 367 <section id="using-the-anjuta-plug-in">
347 <title>Using the Anjuta Plug-in</title> 368 <title>Using the Anjuta Plug-in</title>
348 <para> 369 <para>
349 This section uses an example that cross-compiles a project, deploys it into 370 The steps in this section show how to cross-compile a project, deploy it into
350 QEMU, runs a debugger against it and then does a system wide profile. 371 QEMU, run a debugger against it and then perform a system-wide profile.
351 <orderedlist> 372 <orderedlist>
352 <listitem>Choose Build -> Run Configure or Build -> Run Autogenerate to run 373 <listitem>Choose "Build -> Run Configure" or "Build -> Run Autogenerate" to run
353 "configure" or autogen, respectively for the project. 374 "configure" or "autogen", respectively for the project.
354 Either command passes command-line arguments to instruct the 375 Either command passes command-line arguments to instruct the
355 cross-compile.</listitem> 376 cross-compile.</listitem>
356 <listitem>Select Build -> Build Project to build and compile the project. 377 <listitem>Choose "Build -> Build Project" to build and compile the project.
357 If you have previously built the project in the same tree without using 378 If you have previously built the project in the same tree without using
358 the cross-compiler you might find that your project fails to link. 379 the cross-compiler you might find that your project fails to link.
359 If this is the case, simply select Build -> Clean Project to remove the 380 If this is the case, simply select "Build -> Clean Project" to remove the
360 old binaries. 381 old binaries.
361 After you clean the project you can then try building it again.</listitem> 382 After you clean the project you can then try building it again.</listitem>
362 <listitem>Start QEMU by selecting Tools -> Start QEMU. This menu selection 383 <listitem>Choose "Tools -> Start QEMU" to start QEMU.
363 starts QEMU and will show any error messages in the message view. 384 After QEMU starts any error messages will appear in the message view.
364 Once Poky has fully booted within QEMU you can now deploy the project 385 Once Poky has fully booted within QEMU you can deploy the project
365 into it.</listitem> 386 into it.</listitem>
366 <listitem>Once the project is built and you have QEMU running choose 387 <listitem>Once the project is built and you have QEMU running choose
367 Tools -> Deploy. 388 "Tools -> Deploy" to install the package into a temporary
368 This selection installs the package into a temporary 389 directory and then copy it using "rsync" over SSH into the target.
369 directory and then copies using rsync over SSH into the target. 390 A progress bar and appropriate messages appear in the message view.</listitem>
370 Progress and messages appear in the message view.</listitem>
371 <listitem>To debug a program installed onto the target choose 391 <listitem>To debug a program installed onto the target choose
372 Tools -> Debug remote. 392 "Tools -> Debug remote".
373 This selection prompts you for the local binary to debug and also the 393 Choosing this menu item causes prompts to appear to define the local binary
374 command line to run on the target. 394 for debugging and also for the command line used to run on the target.
375 The command line to run should include the full path to the to binary 395 When you provide the command line be sure to include the full path to the to binary
376 installed in the target. 396 installed in the target.
377 This will start a gdbserver over SSH on the target and also an instance 397 When the command line runs a "gdbserver" over SSH is started on the target and
378 of a cross-gdb in a local terminal. 398 an instance of "cross-gdb" starts in a local terminal.
379 This will be preloaded to connect to the server and use the SDK root to 399 The instance of "cross-gdb" will be preloaded to connect to the server and use the SDK root to
380 find symbols. 400 find symbols.
381 This gdb will connect to the target and load in various libraries and the 401 It also connects to the target and loads in various libraries as well as the
382 target program. 402 target program.
383 You should setup any breakpoints or watchpoints now since you might not 403 You should define any breakpoints or watchpoints at this point in the process since you might not
384 be able to interrupt the execution later. 404 be able to interrupt the execution later.
385 You can stop the debugger on the target using Tools -> Stop debugger.</listitem> 405 To stop the debugger on the target choose "Tools -> Stop debugger".</listitem>
386 <listitem>It is also possible to execute a command in the target over SSH, 406 <listitem>It is also possible to execute a command in the target over SSH.
387 the appropriate environment will be be set for the execution. 407 Doing so causes the appropriate environment to be established for execution.
388 Choose Tools -> Run remote to do this. 408 To execute a command choose "Choose Tools -> Run remote".
389 This selection opens a terminal with the SSH command inside.</listitem> 409 This selection opens a terminal with the SSH command inside.</listitem>
390 <listitem>To do a system wide profile against the system running in QEMU choose 410 <listitem>To perform a system-wide profile against the system running in QEMU choose
391 Tools -> Profile remote. 411 "Tools -> Profile remote".
392 This selection starts up OProfileUI with the appropriate parameters to 412 This choice starts up "OProfileUI" with the appropriate parameters to
393 connect to the server running inside QEMU and also supplies the path 413 connect to the server running inside QEMU and also supplies the path
394 to the debug information necessary to get a useful profile.</listitem> 414 for debug information necessary to get a useful profile.</listitem>
395 </orderedlist> 415 </orderedlist>
396 </para> 416 </para>
397 </section> 417 </section>
@@ -399,7 +419,7 @@
399 </section> 419 </section>
400 420
401 <section id="platdev-appdev-qemu"> 421 <section id="platdev-appdev-qemu">
402 <title>Developing externally in QEMU</title> 422 <title>Developing Externally in QEMU</title>
403 <para> 423 <para>
404 Running Poky QEMU images is covered in the 424 Running Poky QEMU images is covered in the
405 <ulink url="http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html"> 425 <ulink url="http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html">
@@ -407,35 +427,36 @@
407 </para> 427 </para>
408 <para> 428 <para>
409 Poky's QEMU images contain a complete native toolchain. This means 429 Poky's QEMU images contain a complete native toolchain. This means
410 that applications can be developed within QEMU in the same was as a 430 you can develop applications within QEMU similar to the way you would in a normal system.
411 normal system. Using qemux86 on an x86 machine is fast since the 431 Using qemux86 on an x86 machine is fast since the
412 guest and host architectures match, qemuarm is slower but gives 432 guest and host architectures match.
413 faithful emulation of ARM specific issues. To speed things up these 433 On the other hand, using qemuarm can be slower but gives
414 images support using distcc to call a cross-compiler outside the 434 faithful emulation of ARM-specific issues. To speed things up, these
415 emulated system too. If <command>runqemu</command> was used to start 435 images support using "distcc" to call a cross-compiler outside the
416 QEMU, and distccd is present on the host system, any bitbake cross 436 emulated system. If "runqemu" was used to start
417 compiling toolchain available from the build system will automatically 437 QEMU, and "distccd" is present on the host system, any Bitbake cross-compiling
418 be used from within qemu simply by calling distcc 438 toolchain available from the build system is automatically
419 (<command>export CC="distcc"</command> can be set in the enviroment). 439 used from within QEMU simply by calling "distcc". You can accomplish this by defining the
440 cross-compiler variable (e.g. <filename>export CC="distcc"</filename>).
420 Alterntatively, if a suitable SDK/toolchain is present in 441 Alterntatively, if a suitable SDK/toolchain is present in
421 <filename class="directory">/opt/poky</filename> it will also 442 <filename>/opt/poky</filename> it is also
422 automatically be used. 443 automatically be used.
423 </para> 444 </para>
424 445
425 <para> 446 <para>
426 There are several options for connecting into the emulated system. 447 There are several options for connecting into the emulated system.
427 QEMU provides a framebuffer interface which has standard consoles 448 QEMU provides a framebuffer interface that has standard consoles
428 available. There is also a serial connection available which has a 449 available. There is also a serial connection available that has a
429 console to the system running on it and IP networking as standard. 450 console to the system running on it and uses standard IP networking.
430 The images have a dropbear ssh server running with the root password 451 The images have a dropbear ssh server running with the root password
431 disabled allowing standard ssh and scp commands to work. The images 452 disabled to allow standard ssh and scp commands to work. The images
432 also contain an NFS server exporting the guest's root filesystem 453 also contain an NFS server that exports the guest's root filesystem, which
433 allowing that to be made available to the host. 454 allows it to be made available to the host.
434 </para> 455 </para>
435 </section> 456 </section>
436 457
437 <section id="platdev-appdev-insitu"> 458 <section id="platdev-appdev-insitu">
438 <title>Developing in Poky directly</title> 459 <title>Developing in Poky Directly</title>
439 <para> 460 <para>
440 Working directly in Poky is a fast and effective development technique. 461 Working directly in Poky is a fast and effective development technique.
441 The idea is that you can directly edit files in 462 The idea is that you can directly edit files in
@@ -448,36 +469,36 @@
448 469
449 <para> 470 <para>
450 <literallayout class='monospaced'> 471 <literallayout class='monospaced'>
451$ bitbake matchbox-desktop 472 $ bitbake matchbox-desktop
452$ sh 473 $ sh
453$ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/ 474 $ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/
454$ cd matchbox-desktop-2 475 $ cd matchbox-desktop-2
455$ vi src/main.c 476 $ vi src/main.c
456$ exit 477 $ exit
457$ bitbake matchbox-desktop -c compile -f 478 $ bitbake matchbox-desktop -c compile -f
458$ bitbake matchbox-desktop 479 $ bitbake matchbox-desktop
459</literallayout> 480 </literallayout>
460 </para> 481 </para>
461 482
462 <para> 483 <para>
463 Here, we build the package, change into the work directory for the package, 484 This example builds the package, changes into the work directory for the package,
464 change a file, then recompile the package. Instead of using sh like this, 485 changes a file, then recompiles the package. Instead of using "sh" as it is in the example,
465 you can also use two different terminals. The risk with working like this 486 you can also use two different terminals. However, the risk of using two terminals
466 is that a command like unpack could wipe out the changes you've made to the 487 is that a command like "unpack" could destroy the changes you've made to the
467 work directory so you need to work carefully. 488 work directory. Consequently, you need to work carefully.
468 </para> 489 </para>
469 490
470 <para> 491 <para>
471 It is useful when making changes directly to the work directory files to do 492 It is useful when making changes directly to the work directory files to do
472 so using quilt as detailed in the <link linkend='usingpoky-modifying-packages-quilt'> 493 so using "quilt" as detailed in the <link linkend='usingpoky-modifying-packages-quilt'>
473 modifying packages with quilt</link> section. The resulting patches can be copied 494 modifying packages with quilt</link> section. You can copy the resulting patches
474 into the recipe directory and used directly in the <glossterm><link 495 into the recipe directory and use them directly in the <glossterm><link
475 linkend='var-SRC_URI'>SRC_URI</link></glossterm>. 496 linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
476 </para> 497 </para>
477 <para> 498 <para>
478 For a review of the skills used in this section see Sections <link 499 For a review of the skills used in this section see the <link
479 linkend="usingpoky-components-bitbake">2.1.1</link> and <link 500 linkend="usingpoky-components-bitbake">Bitbake</link> and <link
480 linkend="usingpoky-debugging-taskrunning">2.4.2</link>. 501 linkend="usingpoky-debugging-taskrunning">Running Specific Tasks</link> Sections.
481 </para> 502 </para>
482 </section> 503 </section>
483 504
@@ -485,67 +506,75 @@ $ bitbake matchbox-desktop
485 <title>Developing with 'devshell'</title> 506 <title>Developing with 'devshell'</title>
486 507
487 <para> 508 <para>
488 When debugging certain commands or even to just edit packages, the 509 When debugging certain commands or even when just editing packages, the
489 'devshell' can be a useful tool. To start it you run a command like: 510 'devshell' can be a useful tool.
511 Use a command like the following to start this tool.
490 </para> 512 </para>
491 513
492 <para> 514 <para>
493 <literallayout class='monospaced'> 515 <literallayout class='monospaced'>
494$ bitbake matchbox-desktop -c devshell 516 $ bitbake matchbox-desktop -c devshell
495</literallayout> 517 </literallayout>
496 </para> 518 </para>
497 519
498 <para> 520 <para>
499 which will open a terminal with a shell prompt within the Poky 521 This command opens a terminal with a shell prompt within the Poky
500 environment. This means PATH is setup to include the cross toolchain, 522 environment. Consequently, the following occurs:
501 the pkgconfig variables are setup to find the right .pc files, 523 <itemizedlist>
502 configure will be able to find the Poky site files etc. Within this 524 <listitem>The PATH variable includes the cross toolchain.</listitem>
503 environment, you can run configure or compile command as if they 525 <listitem>The pkgconfig variables find the correct <filename>.pc</filename> files.</listitem>
504 were being run by Poky itself. You are also changed into the 526 <listitem>"configure" finds the Poky site files as well as any other necessary files.</listitem>
505 source (<glossterm><link linkend='var-S'>S</link></glossterm>) 527 </itemizedlist>
506 directory automatically. When finished with the shell just exit it 528 Within this environment, you can run "configure" or "compile" commands as if they
507 or close the terminal window. 529 were being run by Poky itself.
530 The working directory also automatically changes to the (<glossterm><link linkend='var-S'>S</link></glossterm>)
531 directory.
532 When you are finished, you just exit the shell or close the terminal window.
508 </para> 533 </para>
509 534
510 <para> 535 <para>
511 The default shell used by devshell is the gnome-terminal. Other 536 The default shell used by "devshell" is the gnome-terminal.
512 forms of terminal can also be used by setting the <glossterm> 537 You can use other forms of terminal can by setting the <glossterm>
513 <link linkend='var-TERMCMD'>TERMCMD</link></glossterm> and <glossterm> 538 <link linkend='var-TERMCMD'>TERMCMD</link></glossterm> and <glossterm>
514 <link linkend='var-TERMCMDRUN'>TERMCMDRUN</link></glossterm> variables 539 <link linkend='var-TERMCMDRUN'>TERMCMDRUN</link></glossterm> variables
515 in local.conf. For examples of the other options available, see 540 in <filename>local.conf</filename>.
516 <filename>meta/conf/bitbake.conf</filename>. An external shell is 541 For examples of the other options available, see
517 launched rather than opening directly into the original terminal 542 <filename>meta/conf/bitbake.conf</filename>.
518 window to make interaction with bitbakes multiple threads easier 543 </para>
519 and also allow a client/server split of bitbake in the future 544 <para>
520 (devshell will still work over X11 forwarding or similar). 545 An external shell is launched rather than opening directly into the original terminal
546 window.
547 This allows easier interaction with Bitbake's multiple threads as well as
548 for a future client/server split.
549 Note that "devshell" will still work over X11 forwarding or similar situations.
521 </para> 550 </para>
522 551
523 <para> 552 <para>
524 It is worth remembering that inside devshell you need to use the full 553 It is worth remembering that inside "devshell" you need to use the full
525 compiler name such as <command>arm-poky-linux-gnueabi-gcc</command> 554 compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename>
526 instead of just <command>gcc</command> and the same applies to other 555 instead of just <filename>gcc</filename>.
527 applications from gcc, bintuils, libtool etc. Poky will have setup 556 The same applies to other applications such as gcc, bintuils, libtool and so forth.
528 environmental variables such as CC to assist applications, such as make, 557 Poky will have setup environmental variables such as CC to assist applications, such as make,
529 find the correct tools. 558 find the correct tools.
530 </para> 559 </para>
531 </section> 560 </section>
532 561
533 <section id="platdev-appdev-srcrev"> 562 <section id="platdev-appdev-srcrev">
534 <title>Developing within Poky with an external SCM based package</title> 563 <title>Developing within Poky with an External SCM-based Package</title>
535 564
536 <para> 565 <para>
537 If you're working on a recipe which pulls from an external SCM it 566 If you're working on a recipe that pulls from an external SCM it
538 is possible to have Poky notice new changes added to the 567 is possible to have Poky notice new changes added to the
539 SCM and then build the latest version. This only works for SCMs 568 SCM and then build the latest version using them.
540 where its possible to get a sensible revision number for changes. 569 This only works for SCMs from which it is possible to get a sensible revision number for changes.
541 Currently it works for svn, git and bzr repositories. 570 Currently it works for svn, git and bzr repositories.
542 </para> 571 </para>
543 572
544 <para> 573 <para>
545 To enable this behaviour it is simply a case of adding <glossterm> 574 To enable this behavior simply add <glossterm>
546 <link linkend='var-SRCREV'>SRCREV</link></glossterm>_pn-<glossterm> 575 <link linkend='var-SRCREV'>SRCREV</link></glossterm>_pn-<glossterm>
547 <link linkend='var-PN'>PN</link></glossterm> = "${AUTOREV}" to 576 <link linkend='var-PN'>PN</link></glossterm> = "${AUTOREV}" to
548 local.conf where <glossterm><link linkend='var-PN'>PN</link></glossterm> 577 <filename>local.conf</filename>, where <glossterm><link linkend='var-PN'>PN</link></glossterm>
549 is the name of the package for which you want to enable automatic source 578 is the name of the package for which you want to enable automatic source
550 revision updating. 579 revision updating.
551 </para> 580 </para>