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