summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml2866
-rw-r--r--documentation/sdk-manual/sdk-intro.xml124
-rw-r--r--documentation/sdk-manual/sdk-manual.xml4
-rw-r--r--documentation/sdk-manual/sdk-using.xml1563
-rw-r--r--documentation/sdk-manual/sdk-working-projects.xml1461
5 files changed, 3198 insertions, 2820 deletions
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index 73b317f5c8..8c568a739e 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -4,1516 +4,1628 @@
4 4
5<chapter id='sdk-extensible'> 5<chapter id='sdk-extensible'>
6 6
7<title>Using the Extensible SDK</title> 7 <title>Using the Extensible SDK</title>
8
9<para>
10 This chapter describes the extensible SDK and how to use it.
11 The extensible SDK makes it easy to add new applications and libraries
12 to an image, modify the source for an existing component, test
13 changes on the target hardware, and ease integration into the rest of the
14 <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
15</para>
16
17<para>
18 Information in this chapter covers features that are not part of the
19 standard SDK.
20 In other words, the chapter presents information unique to the
21 extensible SDK only.
22 For information on how to use the standard SDK, see the
23 "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>"
24 chapter.
25</para>
26
27<section id='sdk-setting-up-to-use-the-extensible-sdk'>
28 <title>Setting Up to Use the Extensible SDK</title>
29 8
30 <para> 9 <para>
31 Getting set up to use the extensible SDK is identical to getting set 10 This chapter describes the extensible SDK and how to install it.
32 up to use the standard SDK. 11 Information covers the pieces of the SDK, how to install it, and
33 You still need to locate and run the installer and then run the 12 presents a look at using the <filename>devtool</filename>
34 environment setup script. 13 functionality.
35 See the 14 The extensible SDK makes it easy to add new applications and libraries
36 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" 15 to an image, modify the source for an existing component, test
37 and the 16 changes on the target hardware, and ease integration into the rest of
38 "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>" 17 the
39 sections for general information. 18 <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
40 The following items highlight the only differences between getting
41 set up to use the extensible SDK as compared to the standard SDK:
42 <itemizedlist>
43 <listitem><para><emphasis>Default Installation Directory:</emphasis>
44 By default, the extensible SDK installs into the
45 <filename>poky_sdk</filename> folder of your home directory.
46 As with the standard SDK, you can choose to install the
47 extensible SDK in any location when you run the installer.
48 However, unlike the standard SDK, the location you choose needs
49 to be writable for whichever users need to use the SDK,
50 since files will need to be written under that directory during
51 the normal course of operation.
52 </para></listitem>
53 <listitem><para><emphasis>Build Tools and Build System:</emphasis>
54 The extensible SDK installer performs additional tasks as
55 compared to the standard SDK installer.
56 to the SDK and the installer also prepares the internal build
57 system within the SDK.
58 You can find pre-built extensible SDK installers in the same
59 <ulink url='http://downloads.yoctoproject.org/releases/yocto/yocto-&DISTRO;/toolchain/'>toolchain</ulink>
60 location as the pre-built standard SDK installers.
61 For extensible SDK installers, the
62 <filename>ext</filename> string is part of the name.
63 Here is an example:
64 <literallayout class='monospaced'>
65 poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
66 </literallayout>
67 <note>
68 As an alternative to downloading an SDK, you can build the toolchain
69 installer.
70 For information on building the installer, see the
71 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
72 section.
73 Another helpful resource for building an installer is the
74 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
75 wiki page.
76 </note>
77 Here is example output for running the extensible SDK
78 installer:
79 <literallayout class='monospaced'>
80 $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-&DISTRO;.sh
81 Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
82 ===================================================================================
83 Enter target directory for SDK (default: ~/poky_sdk):
84 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
85 Extracting SDK......................................................................done
86 Setting it up...
87 Extracting buildtools...
88 Preparing build system...
89 done
90 SDK has been successfully set up and is ready to be used.
91 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
92 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
93 </literallayout>
94 </para></listitem>
95 </itemizedlist>
96 </para>
97
98 <para>
99 After installing the SDK, you need to run the SDK environment setup
100 script.
101 Here is the output from an example run:
102 <literallayout class='monospaced'>
103 $ cd /home/scottrif/poky_sdk
104 $ source environment-setup-core2-64-poky-linux
105 SDK environment now set up; additionally you may now run devtool to perform development tasks.
106 Run devtool --help for further details.
107 </literallayout>
108 Once you run the environment setup script, you have
109 <filename>devtool</filename> available.
110 </para>
111</section>
112
113<section id='using-devtool-in-your-sdk-workflow'>
114 <title>Using <filename>devtool</filename> in Your SDK Workflow</title>
115
116 <para>
117 The cornerstone of the extensible SDK is a command-line tool
118 called <filename>devtool</filename>.
119 This tool provides a number of features that help
120 you build, test and package software within the extensible SDK, and
121 optionally integrate it into an image built by the OpenEmbedded build
122 system.
123 </para>
124
125 <para>
126 The <filename>devtool</filename> command line is organized similarly
127 to
128 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> in that it has a
129 number of sub-commands for each function.
130 You can run <filename>devtool --help</filename> to see all the
131 commands.
132 <note> 19 <note>
133 See the 20 For a side-by-side comparison of main features supported for an
134 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>" 21 extensible SDK as compared to a standard SDK, see the
135 in the Yocto Project Reference Manual for more a 22 "<link linkend='sdk-manual-intro'>Introduction</link>"
136 <filename>devtool</filename> reference. 23 section.
137 </note> 24 </note>
138 </para> 25 </para>
139 26
140 <para> 27 <para>
141 Two <filename>devtool</filename> subcommands that provide 28 You can use an extensible SDK to work on Makefile, Autotools, and
142 entry-points into development are: 29 Eclipse-based projects.
143 <itemizedlist> 30 See the
144 <listitem><para><emphasis><filename>devtool add</filename></emphasis>: 31 "<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>"
145 Assists in adding new software to be built. 32 chapter for more information.
146 </para></listitem>
147 <listitem><para><emphasis><filename>devtool modify</filename></emphasis>:
148 Sets up an environment to enable you to modify the source of
149 an existing component.
150 </para></listitem>
151 </itemizedlist>
152 As with the OpenEmbedded build system, "recipes" represent software
153 packages within <filename>devtool</filename>.
154 When you use <filename>devtool add</filename>, a recipe is
155 automatically created.
156 When you use <filename>devtool modify</filename>, the specified
157 existing recipe is used in order to determine where to get the source
158 code and how to patch it.
159 In both cases, an environment is set up so that when you build the
160 recipe a source tree that is under your control is used in order to
161 allow you to make changes to the source as desired.
162 By default, both new recipes and the source go into a "workspace"
163 directory under the SDK.
164 </para>
165
166 <para>
167 The remainder of this section presents the
168 <filename>devtool add</filename> and
169 <filename>devtool modify</filename> workflows.
170 </para> 33 </para>
171 34
172 <section id='sdk-use-devtool-to-add-an-application'> 35 <section id='sdk-extensible-sdk-intro'>
173 <title>Use <filename>devtool add</filename> to Add an Application</title> 36 <title>Why use the Extensible SDK and What is in It?</title>
174
175 <para>
176 The <filename>devtool add</filename> command generates
177 a new recipe based on existing source code.
178 This command takes advantage of the
179 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
180 layer that many <filename>devtool</filename> commands
181 use.
182 The command is flexible enough to allow you to extract source
183 code into both the workspace or a separate local Git repository
184 and to use existing code that does not need to be extracted.
185 </para>
186 37
187 <para> 38 <para>
188 Depending on your particular scenario, the arguments and options 39 The extensible SDK provides a cross-development toolchain and
189 you use with <filename>devtool add</filename> form different 40 libraries tailored to the contents of a specific image.
190 combinations. 41 You would use the Extensible SDK if you want a toolchain experience
191 The following diagram shows common development flows 42 supplemented with the powerful set of <filename>devtool</filename>
192 you would use with the <filename>devtool add</filename> 43 commands tailored for the Yocto Project environment.
193 command:
194 </para> 44 </para>
195 45
196 <para> 46 <para>
197 <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" /> 47 The installed extensible SDK consists of several files and
198 </para> 48 directories.
199 49 Basically, it contains an SDK environment setup script, some
200 <para> 50 configuration files, an internal build system, and the
201 <orderedlist> 51 <filename>devtool</filename> functionality.
202 <listitem><para><emphasis>Generating the New Recipe</emphasis>:
203 The top part of the flow shows three scenarios by which
204 you could use <filename>devtool add</filename> to
205 generate a recipe based on existing source code.</para>
206
207 <para>In a shared development environment, it is
208 typical where other developers are responsible for
209 various areas of source code.
210 As a developer, you are probably interested in using
211 that source code as part of your development using
212 the Yocto Project.
213 All you need is access to the code, a recipe, and a
214 controlled area in which to do your work.</para>
215
216 <para>Within the diagram, three possible scenarios
217 feed into the <filename>devtool add</filename> workflow:
218 <itemizedlist>
219 <listitem><para><emphasis>Left</emphasis>:
220 The left scenario represents a common situation
221 where the source code does not exist locally
222 and needs to be extracted.
223 In this situation, you just let it get
224 extracted to the default workspace - you do not
225 want it in some specific location outside of the
226 workspace.
227 Thus, everything you need will be located in the
228 workspace:
229 <literallayout class='monospaced'>
230 $ devtool add <replaceable>recipe fetchuri</replaceable>
231 </literallayout>
232 With this command, <filename>devtool</filename>
233 creates a recipe and an append file in the
234 workspace as well as extracts the upstream
235 source files into a local Git repository also
236 within the <filename>sources</filename> folder.
237 </para></listitem>
238 <listitem><para><emphasis>Middle</emphasis>:
239 The middle scenario also represents a situation where
240 the source code does not exist locally.
241 In this case, the code is again upstream
242 and needs to be extracted to some
243 local area - this time outside of the default
244 workspace.
245 If required, <filename>devtool</filename>
246 always creates
247 a Git repository locally during the extraction.
248 Furthermore, the first positional argument
249 <replaceable>srctree</replaceable> in this case
250 identifies where the
251 <filename>devtool add</filename> command
252 will locate the extracted code outside of the
253 workspace:
254 <literallayout class='monospaced'>
255 $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
256 </literallayout>
257 In summary, the source code is pulled from
258 <replaceable>fetchuri</replaceable> and extracted
259 into the location defined by
260 <replaceable>srctree</replaceable> as a local
261 Git repository.</para>
262
263 <para>Within workspace, <filename>devtool</filename>
264 creates both the recipe and an append file
265 for the recipe.
266 </para></listitem>
267 <listitem><para><emphasis>Right</emphasis>:
268 The right scenario represents a situation
269 where the source tree (srctree) has been
270 previously prepared outside of the
271 <filename>devtool</filename> workspace.
272 </para>
273
274 <para>The following command names the recipe
275 and identifies where the existing source tree
276 is located:
277 <literallayout class='monospaced'>
278 $ devtool add <replaceable>recipe srctree</replaceable>
279 </literallayout>
280 The command examines the source code and creates
281 a recipe for it placing the recipe into the
282 workspace.</para>
283
284 <para>Because the extracted source code already exists,
285 <filename>devtool</filename> does not try to
286 relocate it into the workspace - just the new
287 the recipe is placed in the workspace.</para>
288
289 <para>Aside from a recipe folder, the command
290 also creates an append folder and places an initial
291 <filename>*.bbappend</filename> within.
292 </para></listitem>
293 </itemizedlist>
294 </para></listitem>
295 <listitem><para><emphasis>Edit the Recipe</emphasis>:
296 At this point, you can use <filename>devtool edit-recipe</filename>
297 to open up the editor as defined by the
298 <filename>$EDITOR</filename> environment variable
299 and modify the file:
300 <literallayout class='monospaced'>
301 $ devtool edit-recipe <replaceable>recipe</replaceable>
302 </literallayout>
303 From within the editor, you can make modifications to the
304 recipe that take affect when you build it later.
305 </para></listitem>
306 <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:
307 At this point in the flow, the next step you
308 take depends on what you are going to do with
309 the new code.</para>
310 <para>If you need to take the build output and eventually
311 move it to the target hardware, you would use
312 <filename>devtool build</filename>:
313 <literallayout class='monospaced'>
314 $ devtool build <replaceable>recipe</replaceable>
315 </literallayout></para>
316 <para>On the other hand, if you want an image to
317 contain the recipe's packages for immediate deployment
318 onto a device (e.g. for testing purposes), you can use
319 the <filename>devtool build-image</filename> command:
320 <literallayout class='monospaced'>
321 $ devtool build-image <replaceable>image</replaceable>
322 </literallayout>
323 </para></listitem>
324 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
325 When you use the <filename>devtool build</filename>
326 command to build out your recipe, you probably want to
327 see if the resulting build output works as expected on target
328 hardware.
329 <note>
330 This step assumes you have a previously built
331 image that is already either running in QEMU or
332 running on actual hardware.
333 Also, it is assumed that for deployment of the image
334 to the target, SSH is installed in the image and if
335 the image is running on real hardware that you have
336 network access to and from your development machine.
337 </note>
338 You can deploy your build output to that target hardware by
339 using the <filename>devtool deploy-target</filename> command:
340 <literallayout class='monospaced'>
341 $ devtool deploy-target <replaceable>recipe target</replaceable>
342 </literallayout>
343 The <replaceable>target</replaceable> is a live target machine
344 running as an SSH server.</para>
345
346 <para>You can, of course, also deploy the image you build
347 using the <filename>devtool build-image</filename> command
348 to actual hardware.
349 However, <filename>devtool</filename> does not provide a
350 specific command that allows you to do this.
351 </para></listitem>
352 <listitem><para>
353 <emphasis>Finish Your Work With the Recipe</emphasis>:
354 The <filename>devtool finish</filename> command creates
355 any patches corresponding to commits in the local
356 Git repository, moves the new recipe to a more permanent
357 layer, and then resets the recipe so that the recipe is
358 built normally rather than from the workspace.
359 <literallayout class='monospaced'>
360 $ devtool finish <replaceable>recipe layer</replaceable>
361 </literallayout>
362 <note>
363 Any changes you want to turn into patches must be
364 committed to the Git repository in the source tree.
365 </note></para>
366
367 <para>As mentioned, the <filename>devtool finish</filename>
368 command moves the final recipe to its permanent layer.
369 </para>
370
371 <para>As a final process of the
372 <filename>devtool finish</filename> command, the state
373 of the standard layers and the upstream source is
374 restored so that you can build the recipe from those
375 areas rather than the workspace.
376 <note>
377 You can use the <filename>devtool reset</filename>
378 command to put things back should you decide you
379 do not want to proceed with your work.
380 If you do use this command, realize that the source
381 tree is preserved.
382 </note>
383 </para></listitem>
384 </orderedlist>
385 </para> 52 </para>
386 </section> 53 </section>
387 54
388 <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'> 55 <section id='sdk-setting-up-to-use-the-extensible-sdk'>
389 <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title> 56 <title>Setting Up to Use the Extensible SDK</title>
390 57
391 <para> 58 <para>
392 The <filename>devtool modify</filename> command prepares the 59 The first thing you need to do is install the SDK on your host
393 way to work on existing code that already has a recipe in 60 development machine by running the <filename>*.sh</filename>
394 place. 61 installation script.
395 The command is flexible enough to allow you to extract code,
396 specify the existing recipe, and keep track of and gather any
397 patch files from other developers that are
398 associated with the code.
399 </para> 62 </para>
400 63
401 <para> 64 <para>
402 Depending on your particular scenario, the arguments and options 65 You can download a tarball installer, which includes the
403 you use with <filename>devtool modify</filename> form different 66 pre-built toolchain, the <filename>runqemu</filename>
404 combinations. 67 script, the internal build system, <filename>devtool</filename>,
405 The following diagram shows common development flows 68 and support files from the appropriate directory under
406 you would use with the <filename>devtool modify</filename> 69 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
407 command: 70 Toolchains are available for 32-bit and 64-bit x86 development
71 systems from the <filename>i686</filename> and
72 <filename>x86_64</filename> directories, respectively.
73 The toolchains the Yocto Project provides are based off the
74 <filename>core-image-sato</filename> image and contain
75 libraries appropriate for developing against that image.
76 Each type of development system supports five or more target
77 architectures.
408 </para> 78 </para>
409 79
410 <para> 80 <para>
411 <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" /> 81 The names of the tarball installer scripts are such that a
412 </para> 82 string representing the host system appears first in the
83 filename and then is immediately followed by a string
84 representing the target architecture.
85 An extensible SDK has the string "-ext" as part of the name.
86 <literallayout class='monospaced'>
87 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh
413 88
414 <para> 89 Where:
415 <orderedlist> 90 <replaceable>host_system</replaceable> is a string representing your development system:
416 <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
417 The top part of the flow shows three scenarios by which
418 you could use <filename>devtool modify</filename> to
419 prepare to work on source files.
420 Each scenario assumes the following:
421 <itemizedlist>
422 <listitem><para>The recipe exists in some layer external
423 to the <filename>devtool</filename> workspace.
424 </para></listitem>
425 <listitem><para>The source files exist upstream in an
426 un-extracted state or locally in a previously
427 extracted state.
428 </para></listitem>
429 </itemizedlist>
430 The typical situation is where another developer has
431 created some layer for use with the Yocto Project and
432 their recipe already resides in that layer.
433 Furthermore, their source code is readily available
434 either upstream or locally.
435 <itemizedlist>
436 <listitem><para><emphasis>Left</emphasis>:
437 The left scenario represents a common situation
438 where the source code does not exist locally
439 and needs to be extracted.
440 In this situation, the source is extracted
441 into the default workspace location.
442 The recipe, in this scenario, is in its own
443 layer outside the workspace
444 (i.e.
445 <filename>meta-</filename><replaceable>layername</replaceable>).
446 </para>
447
448 <para>The following command identifies the recipe
449 and by default extracts the source files:
450 <literallayout class='monospaced'>
451 $ devtool modify <replaceable>recipe</replaceable>
452 </literallayout>
453 Once <filename>devtool</filename>locates the recipe,
454 it uses the
455 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
456 variable to locate the source code and
457 any local patch files from other developers are
458 located.
459 <note>
460 You cannot provide an URL for
461 <replaceable>srctree</replaceable> when using the
462 <filename>devtool modify</filename> command.
463 </note>
464 With this scenario, however, since no
465 <replaceable>srctree</replaceable> argument exists, the
466 <filename>devtool modify</filename> command by default
467 extracts the source files to a Git structure.
468 Furthermore, the location for the extracted source is the
469 default area within the workspace.
470 The result is that the command sets up both the source
471 code and an append file within the workspace with the
472 recipe remaining in its original location.
473 </para></listitem>
474 <listitem><para><emphasis>Middle</emphasis>:
475 The middle scenario represents a situation where
476 the source code also does not exist locally.
477 In this case, the code is again upstream
478 and needs to be extracted to some
479 local area as a Git repository.
480 The recipe, in this scenario, is again in its own
481 layer outside the workspace.</para>
482
483 <para>The following command tells
484 <filename>devtool</filename> what recipe with
485 which to work and, in this case, identifies a local
486 area for the extracted source files that is outside
487 of the default workspace:
488 <literallayout class='monospaced'>
489 $ devtool modify <replaceable>recipe srctree</replaceable>
490 </literallayout>
491 As with all extractions, the command uses
492 the recipe's <filename>SRC_URI</filename> to locate the
493 source files.
494 Once the files are located, the command by default
495 extracts them.
496 Providing the <replaceable>srctree</replaceable>
497 argument instructs <filename>devtool</filename> where
498 place the extracted source.</para>
499
500 <para>Within workspace, <filename>devtool</filename>
501 creates an append file for the recipe.
502 The recipe remains in its original location but
503 the source files are extracted to the location you
504 provided with <replaceable>srctree</replaceable>.
505 </para></listitem>
506 <listitem><para><emphasis>Right</emphasis>:
507 The right scenario represents a situation
508 where the source tree
509 (<replaceable>srctree</replaceable>) exists as a
510 previously extracted Git structure outside of
511 the <filename>devtool</filename> workspace.
512 In this example, the recipe also exists
513 elsewhere in its own layer.
514 </para>
515
516 <para>The following command tells
517 <filename>devtool</filename> the recipe
518 with which to work, uses the "-n" option to indicate
519 source does not need to be extracted, and uses
520 <replaceable>srctree</replaceable> to point to the
521 previously extracted source files:
522 <literallayout class='monospaced'>
523 $ devtool modify -n <replaceable>recipe srctree</replaceable>
524 </literallayout>
525 </para>
526 91
527 <para>Once the command finishes, it creates only 92 i686 or x86_64.
528 an append file for the recipe in the workspace.
529 The recipe and the source code remain in their
530 original locations.
531 </para></listitem>
532 </itemizedlist>
533 </para></listitem>
534 <listitem><para><emphasis>Edit the Source</emphasis>:
535 Once you have used the <filename>devtool modify</filename>
536 command, you are free to make changes to the source
537 files.
538 You can use any editor you like to make and save
539 your source code modifications.
540 </para></listitem>
541 <listitem><para><emphasis>Build the Recipe</emphasis>:
542 Once you have updated the source files, you can build
543 the recipe.
544 </para></listitem>
545 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
546 When you use the <filename>devtool build</filename>
547 command to build out your recipe, you probably want to see
548 if the resulting build output works as expected on target
549 hardware.
550 <note>
551 This step assumes you have a previously built
552 image that is already either running in QEMU or
553 running on actual hardware.
554 Also, it is assumed that for deployment of the image
555 to the target, SSH is installed in the image and if
556 the image is running on real hardware that you have
557 network access to and from your development machine.
558 </note>
559 You can deploy your build output to that target hardware by
560 using the <filename>devtool deploy-target</filename> command:
561 <literallayout class='monospaced'>
562 $ devtool deploy-target <replaceable>recipe target</replaceable>
563 </literallayout>
564 The <replaceable>target</replaceable> is a live target machine
565 running as an SSH server.</para>
566
567 <para>You can, of course, also deploy the image you build
568 using the <filename>devtool build-image</filename> command
569 to actual hardware.
570 However, <filename>devtool</filename> does not provide a
571 specific command that allows you to do this.
572 </para></listitem>
573 <listitem><para>
574 <emphasis>Finish Your Work With the Recipe</emphasis>:
575 The <filename>devtool finish</filename> command creates
576 any patches corresponding to commits in the local
577 Git repository, updates the recipe to point to them
578 (or creates a <filename>.bbappend</filename> file to do
579 so, depending on the specified destination layer), and
580 then resets the recipe so that the recipe is built normally
581 rather than from the workspace.
582 <literallayout class='monospaced'>
583 $ devtool finish <replaceable>recipe layer</replaceable>
584 </literallayout>
585 <note>
586 Any changes you want to turn into patches must be
587 committed to the Git repository in the source tree.
588 </note></para>
589
590 <para>Because there is no need to move the recipe,
591 <filename>devtool finish</filename> either updates the
592 original recipe in the original layer or the command
593 creates a <filename>.bbappend</filename> in a different
594 layer as provided by <replaceable>layer</replaceable>.
595 </para>
596
597 <para>As a final process of the
598 <filename>devtool finish</filename> command, the state
599 of the standard layers and the upstream source is
600 restored so that you can build the recipe from those
601 areas rather than the workspace.
602 <note>
603 You can use the <filename>devtool reset</filename>
604 command to put things back should you decide you
605 do not want to proceed with your work.
606 If you do use this command, realize that the source
607 tree is preserved.
608 </note>
609 </para></listitem>
610 </orderedlist>
611 </para>
612 </section>
613 93
614 <section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'> 94 <replaceable>image_type</replaceable> is the image for which the SDK was built.
615 <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
616 95
617 <para> 96 <replaceable>arch</replaceable> is a string representing the tuned target architecture:
618 The <filename>devtool upgrade</filename> command updates
619 an existing recipe so that you can build it for an updated
620 set of source files.
621 The command is flexible enough to allow you to specify
622 source code revision and versioning schemes, extract code into
623 or out of the <filename>devtool</filename> workspace, and
624 work with any source file forms that the fetchers support.
625 </para>
626 97
627 <para> 98 i586, x86_64, powerpc, mips, armv7a or armv5te
628 Depending on your particular scenario, the arguments and options 99
629 you use with <filename>devtool upgrade</filename> form different 100 <replaceable>release_version</replaceable> is a string representing the release number of the
630 combinations. 101 Yocto Project:
631 The following diagram shows a common development flow 102
632 you would use with the <filename>devtool modify</filename> 103 &DISTRO;, &DISTRO;+snapshot
633 command: 104 </literallayout>
105 For example, the following toolchain installer is for a 64-bit
106 development host system and a i586-tuned target architecture
107 based off the SDK for <filename>core-image-sato</filename> and
108 using the current &DISTRO; snapshot:
109 <literallayout class='monospaced'>
110 poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh
111 </literallayout>
112 <note>
113 As an alternative to downloading an SDK, you can build the
114 toolchain installer.
115 For information on building the installer, see the
116 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
117 section.
118 Another helpful resource for building an installer is the
119 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
120 wiki page.
121 This wiki page focuses on development when using the Eclipse
122 IDE.
123 </note>
634 </para> 124 </para>
635 125
636 <para> 126 <para>
637 <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" /> 127 The SDK and toolchains are self-contained and by default are
128 installed into the <filename>poky_sdk</filename> folder in your
129 home directory.
130 You can choose to install the extensible SDK in any location when
131 you run the installer.
132 However, the location you choose needs to be writable for whichever
133 users need to use the SDK, since files will need to be written
134 under that directory during the normal course of operation.
638 </para> 135 </para>
639 136
640 <para> 137 <para>
641 <orderedlist> 138 The following command shows how to run the installer given a
642 <listitem><para><emphasis>Initiate the Upgrade</emphasis>: 139 toolchain tarball for a 64-bit x86 development host system and
643 The top part of the flow shows a typical scenario by which 140 a 64-bit x86 target architecture.
644 you could use <filename>devtool upgrade</filename>. 141 The example assumes the toolchain installer is located in
645 The following conditions exist: 142 <filename>~/Downloads/</filename>.
646 <itemizedlist> 143 <note>
647 <listitem><para>The recipe exists in some layer external 144 If you do not have write permissions for the directory
648 to the <filename>devtool</filename> workspace. 145 into which you are installing the SDK, the installer
649 </para></listitem> 146 notifies you and exits.
650 <listitem><para>The source files for the new release 147 Be sure you have write permissions in the directory and
651 exist adjacent to the same location pointed to by 148 run the installer again.
652 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 149 </note>
653 in the recipe (e.g. a tarball with the new version 150 <literallayout class='monospaced'>
654 number in the name, or as a different revision in 151 $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-&DISTRO;.sh
655 the upstream Git repository). 152 Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
656 </para></listitem> 153 ===================================================================================
657 </itemizedlist> 154 Enter target directory for SDK (default: ~/poky_sdk):
658 A common situation is where third-party software has 155 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
659 undergone a revision so that it has been upgraded. 156 Extracting SDK......................................................................done
660 The recipe you have access to is likely in your own layer. 157 Setting it up...
661 Thus, you need to upgrade the recipe to use the 158 Extracting buildtools...
662 newer version of the software: 159 Preparing build system...
663 <literallayout class='monospaced'> 160 done
664 $ devtool upgrade -V <replaceable>version recipe</replaceable> 161 SDK has been successfully set up and is ready to be used.
665 </literallayout> 162 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
666 By default, the <filename>devtool upgrade</filename> command 163 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
667 extracts source code into the <filename>sources</filename> 164 </literallayout>
668 directory in the workspace.
669 If you want the code extracted to any other location, you
670 need to provide the <replaceable>srctree</replaceable>
671 positional argument with the command as follows:
672 <literallayout class='monospaced'>
673 $ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
674 </literallayout>
675 Also, in this example, the "-V" option is used to specify
676 the new version.
677 If the source files pointed to by the
678 <filename>SRC_URI</filename> statement in the recipe are
679 in a Git repository, you must provide the "-S" option and
680 specify a revision for the software.</para>
681
682 <para>Once <filename>devtool</filename> locates the recipe,
683 it uses the <filename>SRC_URI</filename> variable to locate
684 the source code and any local patch files from other
685 developers are located.
686 The result is that the command sets up the source
687 code, the new version of the recipe, and an append file
688 all within the workspace.
689 </para></listitem>
690 <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
691 At this point, there could be some conflicts due to the
692 software being upgraded to a new version.
693 This would occur if your recipe specifies some patch files in
694 <filename>SRC_URI</filename> that conflict with changes
695 made in the new version of the software.
696 If this is the case, you need to resolve the conflicts
697 by editing the source and following the normal
698 <filename>git rebase</filename> conflict resolution
699 process.</para>
700 <para>Before moving onto the next step, be sure to resolve any
701 such conflicts created through use of a newer or different
702 version of the software.
703 </para></listitem>
704 <listitem><para><emphasis>Build the Recipe</emphasis>:
705 Once you have your recipe in order, you can build it.
706 You can either use <filename>devtool build</filename> or
707 <filename>bitbake</filename>.
708 Either method produces build output that is stored
709 in
710 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
711 </para></listitem>
712 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
713 When you use the <filename>devtool build</filename>
714 command or <filename>bitbake</filename> to build out your
715 recipe, you probably want to see if the resulting build
716 output works as expected on target hardware.
717 <note>
718 This step assumes you have a previously built
719 image that is already either running in QEMU or
720 running on actual hardware.
721 Also, it is assumed that for deployment of the image
722 to the target, SSH is installed in the image and if
723 the image is running on real hardware that you have
724 network access to and from your development machine.
725 </note>
726 You can deploy your build output to that target hardware by
727 using the <filename>devtool deploy-target</filename> command:
728 <literallayout class='monospaced'>
729 $ devtool deploy-target <replaceable>recipe target</replaceable>
730 </literallayout>
731 The <replaceable>target</replaceable> is a live target machine
732 running as an SSH server.</para>
733 <para>You can, of course, also deploy the image you build
734 using the <filename>devtool build-image</filename> command
735 to actual hardware.
736 However, <filename>devtool</filename> does not provide a
737 specific command that allows you to do this.
738 </para></listitem>
739 <listitem><para>
740 <emphasis>Finish Your Work With the Recipe</emphasis>:
741 The <filename>devtool finish</filename> command creates
742 any patches corresponding to commits in the local
743 Git repository, updates the recipe to point to them
744 (or creates a <filename>.bbappend</filename> file to do
745 so, depending on the specified destination layer), and
746 then resets the recipe so that the recipe is built normally
747 rather than from the workspace.
748 <literallayout class='monospaced'>
749 $ devtool finish <replaceable>recipe layer</replaceable>
750 </literallayout>
751 <note>
752 Any changes you want to turn into patches must be
753 committed to the Git repository in the source tree.
754 </note></para>
755 <para>Because there is no need to move the recipe,
756 <filename>devtool finish</filename> either updates the
757 original recipe in the original layer or the command
758 creates a <filename>.bbappend</filename> in a different
759 layer as provided by <replaceable>layer</replaceable>.
760 </para>
761 <para>As a final process of the
762 <filename>devtool finish</filename> command, the state
763 of the standard layers and the upstream source is
764 restored so that you can build the recipe from those
765 areas rather than the workspace.
766 <note>
767 You can use the <filename>devtool reset</filename>
768 command to put things back should you decide you
769 do not want to proceed with your work.
770 If you do use this command, realize that the source
771 tree is preserved.
772 </note>
773 </para></listitem>
774 </orderedlist>
775 </para> 165 </para>
776 </section> 166 </section>
777</section>
778
779<section id='sdk-a-closer-look-at-devtool-add'>
780 <title>A Closer Look at <filename>devtool add</filename></title>
781 167
782 <para> 168 <section id='sdk-running-the-extensible-sdk-environment-setup-script'>
783 The <filename>devtool add</filename> command automatically creates a 169 <title>Running the Extensible SDK Environment Setup Script</title>
784 recipe based on the source tree with which you provide it.
785 Currently, the command has support for the following:
786 <itemizedlist>
787 <listitem><para>
788 Autotools (<filename>autoconf</filename> and
789 <filename>automake</filename>)
790 </para></listitem>
791 <listitem><para>
792 CMake
793 </para></listitem>
794 <listitem><para>
795 Scons
796 </para></listitem>
797 <listitem><para>
798 <filename>qmake</filename>
799 </para></listitem>
800 <listitem><para>
801 Plain <filename>Makefile</filename>
802 </para></listitem>
803 <listitem><para>
804 Out-of-tree kernel module
805 </para></listitem>
806 <listitem><para>
807 Binary package (i.e. "-b" option)
808 </para></listitem>
809 <listitem><para>
810 Node.js module
811 </para></listitem>
812 <listitem><para>
813 Python modules that use <filename>setuptools</filename>
814 or <filename>distutils</filename>
815 </para></listitem>
816 </itemizedlist>
817 </para>
818
819 <para>
820 Apart from binary packages, the determination of how a source tree
821 should be treated is automatic based on the files present within
822 that source tree.
823 For example, if a <filename>CMakeLists.txt</filename> file is found,
824 then the source tree is assumed to be using
825 CMake and is treated accordingly.
826 <note>
827 In most cases, you need to edit the automatically generated
828 recipe in order to make it build properly.
829 Typically, you would go through several edit and build cycles
830 until you can build the recipe.
831 Once the recipe can be built, you could use possible further
832 iterations to test the recipe on the target device.
833 </note>
834 </para>
835
836 <para>
837 The remainder of this section covers specifics regarding how parts
838 of the recipe are generated.
839 </para>
840
841 <section id='sdk-name-and-version'>
842 <title>Name and Version</title>
843 170
844 <para> 171 <para>
845 If you do not specify a name and version on the command 172 Once you have the SDK installed, you must run the SDK environment
846 line, <filename>devtool add</filename> attempts to determine 173 setup script before you can actually use it.
847 the name and version of the software being built from 174 This setup script resides in the directory you chose when you
848 various metadata within the source tree. 175 installed the SDK, which is either the default
849 Furthermore, the command sets the name of the created recipe 176 <filename>poky_sdk</filename> directory or the directory you
850 file accordingly. 177 chose during installation.
851 If the name or version cannot be determined, the
852 <filename>devtool add</filename> command prints an error and
853 you must re-run the command with both the name and version
854 or just the name or version specified.
855 </para> 178 </para>
856 179
857 <para> 180 <para>
858 Sometimes the name or version determined from the source tree 181 Before running the script, be sure it is the one that matches the
859 might be incorrect. 182 architecture for which you are developing.
860 For such a case, you must reset the recipe: 183 Environment setup scripts begin with the string
184 "<filename>environment-setup</filename>" and include as part of
185 their name the tuned target architecture.
186 As an example, the following commands set the working directory
187 to where the SDK was installed and then source the environment
188 setup script.
189 In this example, the setup script is for an IA-based
190 target machine using i586 tuning:
861 <literallayout class='monospaced'> 191 <literallayout class='monospaced'>
862 $ devtool reset -n <replaceable>recipename</replaceable> 192 $ cd /home/scottrif/poky_sdk
193 $ source environment-setup-core2-64-poky-linux
194 SDK environment now set up; additionally you may now run devtool to perform development tasks.
195 Run devtool --help for further details.
196 </literallayout>
197 When you run the setup script, many environment variables are
198 defined:
199 <literallayout class='monospaced'>
200 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
201 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
202 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
203 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
204 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
205 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
206 <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
207 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
208 <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
209 <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols
210 <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
211 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
212 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
213 <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
214 <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
215 <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
216 <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools
217 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
218 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
219 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
220 <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
221 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags
863 </literallayout> 222 </literallayout>
864 After running the <filename>devtool reset</filename> command,
865 you need to run <filename>devtool add</filename> again and
866 provide the name or the version.
867 </para> 223 </para>
868 </section> 224 </section>
869 225
870 <section id='sdk-dependency-detection-and-mapping'> 226 <section id='using-devtool-in-your-sdk-workflow'>
871 <title>Dependency Detection and Mapping</title> 227 <title>Using <filename>devtool</filename> in Your SDK Workflow</title>
872 228
873 <para> 229 <para>
874 The <filename>devtool add</filename> command attempts to 230 The cornerstone of the extensible SDK is a command-line tool
875 detect build-time dependencies and map them to other recipes 231 called <filename>devtool</filename>.
876 in the system. 232 This tool provides a number of features that help
877 During this mapping, the command fills in the names of those 233 you build, test and package software within the extensible SDK, and
878 recipes in the 234 optionally integrate it into an image built by the OpenEmbedded build
879 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> 235 system.
880 value within the recipe.
881 If a dependency cannot be mapped, then a comment is placed in
882 the recipe indicating such.
883 The inability to map a dependency might be caused because the
884 naming is not recognized or because the dependency simply is
885 not available.
886 For cases where the dependency is not available, you must use
887 the <filename>devtool add</filename> command to add an
888 additional recipe to satisfy the dependency and then come
889 back to the first recipe and add its name to
890 <filename>DEPENDS</filename>.
891 </para> 236 </para>
892 237
893 <para> 238 <para>
894 If you need to add runtime dependencies, you can do so by 239 The <filename>devtool</filename> command line is organized similarly
895 adding the following to your recipe: 240 to
896 <literallayout class='monospaced'> 241 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> in that it has a
897 RDEPENDS_${PN} += "dependency1 dependency2 ..." 242 number of sub-commands for each function.
898 </literallayout> 243 You can run <filename>devtool --help</filename> to see all the
244 commands.
899 <note> 245 <note>
900 The <filename>devtool add</filename> command often cannot 246 See the
901 distinguish between mandatory and optional dependencies. 247 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
902 Consequently, some of the detected dependencies might 248 in the Yocto Project Reference Manual for more a
903 in fact be optional. 249 <filename>devtool</filename> reference.
904 When in doubt, consult the documentation or the configure
905 script for the software the recipe is building for further
906 details.
907 In some cases, you might find you can substitute the
908 dependency for an option to disable the associated
909 functionality passed to the configure script.
910 </note> 250 </note>
911 </para> 251 </para>
912 </section>
913
914 <section id='sdk-license-detection'>
915 <title>License Detection</title>
916 252
917 <para> 253 <para>
918 The <filename>devtool add</filename> command attempts to 254 Two <filename>devtool</filename> subcommands that provide
919 determine if the software you are adding is able to be 255 entry-points into development are:
920 distributed under a common open-source license and sets the 256 <itemizedlist>
921 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> 257 <listitem><para><emphasis><filename>devtool add</filename></emphasis>:
922 value accordingly. 258 Assists in adding new software to be built.
923 You should double-check this value against the documentation 259 </para></listitem>
924 or source files for the software you are building and update 260 <listitem><para><emphasis><filename>devtool modify</filename></emphasis>:
925 that <filename>LICENSE</filename> value if necessary. 261 Sets up an environment to enable you to modify the source of
262 an existing component.
263 </para></listitem>
264 </itemizedlist>
265 As with the OpenEmbedded build system, "recipes" represent software
266 packages within <filename>devtool</filename>.
267 When you use <filename>devtool add</filename>, a recipe is
268 automatically created.
269 When you use <filename>devtool modify</filename>, the specified
270 existing recipe is used in order to determine where to get the source
271 code and how to patch it.
272 In both cases, an environment is set up so that when you build the
273 recipe a source tree that is under your control is used in order to
274 allow you to make changes to the source as desired.
275 By default, both new recipes and the source go into a "workspace"
276 directory under the SDK.
926 </para> 277 </para>
927 278
928 <para> 279 <para>
929 The <filename>devtool add</filename> command also sets the 280 The remainder of this section presents the
930 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink> 281 <filename>devtool add</filename> and
931 value to point to all files that appear to be license-related. 282 <filename>devtool modify</filename> workflows.
932 However, license statements often appear in comments at the top
933 of source files or within documentation.
934 Consequently, you might need to amend the
935 <filename>LIC_FILES_CHKSUM</filename> variable to point to one
936 or more of those comments if present.
937 Setting <filename>LIC_FILES_CHKSUM</filename> is particularly
938 important for third-party software.
939 The mechanism attempts to ensure correct licensing should you
940 upgrade the recipe to a newer upstream version in future.
941 Any change in licensing is detected and you receive an error
942 prompting you to check the license text again.
943 </para> 283 </para>
944 284
945 <para> 285 <section id='sdk-use-devtool-to-add-an-application'>
946 If the <filename>devtool add</filename> command cannot 286 <title>Use <filename>devtool add</filename> to Add an Application</title>
947 determine licensing information, the 287
948 <filename>LICENSE</filename> value is set to "CLOSED" and the 288 <para>
949 <filename>LIC_FILES_CHKSUM</filename> value remains unset. 289 The <filename>devtool add</filename> command generates
950 This behavior allows you to continue with development but is 290 a new recipe based on existing source code.
951 unlikely to be correct in all cases. 291 This command takes advantage of the
952 Consequently, you should check the documentation or source 292 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
953 files for the software you are building to determine the actual 293 layer that many <filename>devtool</filename> commands
954 license. 294 use.
955 </para> 295 The command is flexible enough to allow you to extract source
296 code into both the workspace or a separate local Git repository
297 and to use existing code that does not need to be extracted.
298 </para>
299
300 <para>
301 Depending on your particular scenario, the arguments and options
302 you use with <filename>devtool add</filename> form different
303 combinations.
304 The following diagram shows common development flows
305 you would use with the <filename>devtool add</filename>
306 command:
307 </para>
308
309 <para>
310 <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" />
311 </para>
312
313 <para>
314 <orderedlist>
315 <listitem><para><emphasis>Generating the New Recipe</emphasis>:
316 The top part of the flow shows three scenarios by which
317 you could use <filename>devtool add</filename> to
318 generate a recipe based on existing source code.</para>
319
320 <para>In a shared development environment, it is
321 typical where other developers are responsible for
322 various areas of source code.
323 As a developer, you are probably interested in using
324 that source code as part of your development using
325 the Yocto Project.
326 All you need is access to the code, a recipe, and a
327 controlled area in which to do your work.</para>
328
329 <para>Within the diagram, three possible scenarios
330 feed into the <filename>devtool add</filename> workflow:
331 <itemizedlist>
332 <listitem><para><emphasis>Left</emphasis>:
333 The left scenario represents a common situation
334 where the source code does not exist locally
335 and needs to be extracted.
336 In this situation, you just let it get
337 extracted to the default workspace - you do not
338 want it in some specific location outside of the
339 workspace.
340 Thus, everything you need will be located in the
341 workspace:
342 <literallayout class='monospaced'>
343 $ devtool add <replaceable>recipe fetchuri</replaceable>
344 </literallayout>
345 With this command, <filename>devtool</filename>
346 creates a recipe and an append file in the
347 workspace as well as extracts the upstream
348 source files into a local Git repository also
349 within the <filename>sources</filename> folder.
350 </para></listitem>
351 <listitem><para><emphasis>Middle</emphasis>:
352 The middle scenario also represents a situation where
353 the source code does not exist locally.
354 In this case, the code is again upstream
355 and needs to be extracted to some
356 local area - this time outside of the default
357 workspace.
358 If required, <filename>devtool</filename>
359 always creates
360 a Git repository locally during the extraction.
361 Furthermore, the first positional argument
362 <replaceable>srctree</replaceable> in this case
363 identifies where the
364 <filename>devtool add</filename> command
365 will locate the extracted code outside of the
366 workspace:
367 <literallayout class='monospaced'>
368 $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
369 </literallayout>
370 In summary, the source code is pulled from
371 <replaceable>fetchuri</replaceable> and extracted
372 into the location defined by
373 <replaceable>srctree</replaceable> as a local
374 Git repository.</para>
375
376 <para>Within workspace, <filename>devtool</filename>
377 creates both the recipe and an append file
378 for the recipe.
379 </para></listitem>
380 <listitem><para><emphasis>Right</emphasis>:
381 The right scenario represents a situation
382 where the source tree (srctree) has been
383 previously prepared outside of the
384 <filename>devtool</filename> workspace.
385 </para>
386
387 <para>The following command names the recipe
388 and identifies where the existing source tree
389 is located:
390 <literallayout class='monospaced'>
391 $ devtool add <replaceable>recipe srctree</replaceable>
392 </literallayout>
393 The command examines the source code and creates
394 a recipe for it placing the recipe into the
395 workspace.</para>
396
397 <para>Because the extracted source code already exists,
398 <filename>devtool</filename> does not try to
399 relocate it into the workspace - just the new
400 the recipe is placed in the workspace.</para>
401
402 <para>Aside from a recipe folder, the command
403 also creates an append folder and places an initial
404 <filename>*.bbappend</filename> within.
405 </para></listitem>
406 </itemizedlist>
407 </para></listitem>
408 <listitem><para><emphasis>Edit the Recipe</emphasis>:
409 At this point, you can use <filename>devtool edit-recipe</filename>
410 to open up the editor as defined by the
411 <filename>$EDITOR</filename> environment variable
412 and modify the file:
413 <literallayout class='monospaced'>
414 $ devtool edit-recipe <replaceable>recipe</replaceable>
415 </literallayout>
416 From within the editor, you can make modifications to the
417 recipe that take affect when you build it later.
418 </para></listitem>
419 <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:
420 At this point in the flow, the next step you
421 take depends on what you are going to do with
422 the new code.</para>
423 <para>If you need to take the build output and eventually
424 move it to the target hardware, you would use
425 <filename>devtool build</filename>:
426 <literallayout class='monospaced'>
427 $ devtool build <replaceable>recipe</replaceable>
428 </literallayout></para>
429 <para>On the other hand, if you want an image to
430 contain the recipe's packages for immediate deployment
431 onto a device (e.g. for testing purposes), you can use
432 the <filename>devtool build-image</filename> command:
433 <literallayout class='monospaced'>
434 $ devtool build-image <replaceable>image</replaceable>
435 </literallayout>
436 </para></listitem>
437 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
438 When you use the <filename>devtool build</filename>
439 command to build out your recipe, you probably want to
440 see if the resulting build output works as expected on target
441 hardware.
442 <note>
443 This step assumes you have a previously built
444 image that is already either running in QEMU or
445 running on actual hardware.
446 Also, it is assumed that for deployment of the image
447 to the target, SSH is installed in the image and if
448 the image is running on real hardware that you have
449 network access to and from your development machine.
450 </note>
451 You can deploy your build output to that target hardware by
452 using the <filename>devtool deploy-target</filename> command:
453 <literallayout class='monospaced'>
454 $ devtool deploy-target <replaceable>recipe target</replaceable>
455 </literallayout>
456 The <replaceable>target</replaceable> is a live target machine
457 running as an SSH server.</para>
458
459 <para>You can, of course, also deploy the image you build
460 using the <filename>devtool build-image</filename> command
461 to actual hardware.
462 However, <filename>devtool</filename> does not provide a
463 specific command that allows you to do this.
464 </para></listitem>
465 <listitem><para>
466 <emphasis>Finish Your Work With the Recipe</emphasis>:
467 The <filename>devtool finish</filename> command creates
468 any patches corresponding to commits in the local
469 Git repository, moves the new recipe to a more permanent
470 layer, and then resets the recipe so that the recipe is
471 built normally rather than from the workspace.
472 <literallayout class='monospaced'>
473 $ devtool finish <replaceable>recipe layer</replaceable>
474 </literallayout>
475 <note>
476 Any changes you want to turn into patches must be
477 committed to the Git repository in the source tree.
478 </note></para>
479
480 <para>As mentioned, the <filename>devtool finish</filename>
481 command moves the final recipe to its permanent layer.
482 </para>
483
484 <para>As a final process of the
485 <filename>devtool finish</filename> command, the state
486 of the standard layers and the upstream source is
487 restored so that you can build the recipe from those
488 areas rather than the workspace.
489 <note>
490 You can use the <filename>devtool reset</filename>
491 command to put things back should you decide you
492 do not want to proceed with your work.
493 If you do use this command, realize that the source
494 tree is preserved.
495 </note>
496 </para></listitem>
497 </orderedlist>
498 </para>
499 </section>
500
501 <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>
502 <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title>
503
504 <para>
505 The <filename>devtool modify</filename> command prepares the
506 way to work on existing code that already has a recipe in
507 place.
508 The command is flexible enough to allow you to extract code,
509 specify the existing recipe, and keep track of and gather any
510 patch files from other developers that are
511 associated with the code.
512 </para>
513
514 <para>
515 Depending on your particular scenario, the arguments and options
516 you use with <filename>devtool modify</filename> form different
517 combinations.
518 The following diagram shows common development flows
519 you would use with the <filename>devtool modify</filename>
520 command:
521 </para>
522
523 <para>
524 <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" />
525 </para>
526
527 <para>
528 <orderedlist>
529 <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
530 The top part of the flow shows three scenarios by which
531 you could use <filename>devtool modify</filename> to
532 prepare to work on source files.
533 Each scenario assumes the following:
534 <itemizedlist>
535 <listitem><para>The recipe exists in some layer external
536 to the <filename>devtool</filename> workspace.
537 </para></listitem>
538 <listitem><para>The source files exist upstream in an
539 un-extracted state or locally in a previously
540 extracted state.
541 </para></listitem>
542 </itemizedlist>
543 The typical situation is where another developer has
544 created some layer for use with the Yocto Project and
545 their recipe already resides in that layer.
546 Furthermore, their source code is readily available
547 either upstream or locally.
548 <itemizedlist>
549 <listitem><para><emphasis>Left</emphasis>:
550 The left scenario represents a common situation
551 where the source code does not exist locally
552 and needs to be extracted.
553 In this situation, the source is extracted
554 into the default workspace location.
555 The recipe, in this scenario, is in its own
556 layer outside the workspace
557 (i.e.
558 <filename>meta-</filename><replaceable>layername</replaceable>).
559 </para>
560
561 <para>The following command identifies the recipe
562 and by default extracts the source files:
563 <literallayout class='monospaced'>
564 $ devtool modify <replaceable>recipe</replaceable>
565 </literallayout>
566 Once <filename>devtool</filename>locates the recipe,
567 it uses the
568 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
569 variable to locate the source code and
570 any local patch files from other developers are
571 located.
572 <note>
573 You cannot provide an URL for
574 <replaceable>srctree</replaceable> when using the
575 <filename>devtool modify</filename> command.
576 </note>
577 With this scenario, however, since no
578 <replaceable>srctree</replaceable> argument exists, the
579 <filename>devtool modify</filename> command by default
580 extracts the source files to a Git structure.
581 Furthermore, the location for the extracted source is the
582 default area within the workspace.
583 The result is that the command sets up both the source
584 code and an append file within the workspace with the
585 recipe remaining in its original location.
586 </para></listitem>
587 <listitem><para><emphasis>Middle</emphasis>:
588 The middle scenario represents a situation where
589 the source code also does not exist locally.
590 In this case, the code is again upstream
591 and needs to be extracted to some
592 local area as a Git repository.
593 The recipe, in this scenario, is again in its own
594 layer outside the workspace.</para>
595
596 <para>The following command tells
597 <filename>devtool</filename> what recipe with
598 which to work and, in this case, identifies a local
599 area for the extracted source files that is outside
600 of the default workspace:
601 <literallayout class='monospaced'>
602 $ devtool modify <replaceable>recipe srctree</replaceable>
603 </literallayout>
604 As with all extractions, the command uses
605 the recipe's <filename>SRC_URI</filename> to locate the
606 source files.
607 Once the files are located, the command by default
608 extracts them.
609 Providing the <replaceable>srctree</replaceable>
610 argument instructs <filename>devtool</filename> where
611 place the extracted source.</para>
612
613 <para>Within workspace, <filename>devtool</filename>
614 creates an append file for the recipe.
615 The recipe remains in its original location but
616 the source files are extracted to the location you
617 provided with <replaceable>srctree</replaceable>.
618 </para></listitem>
619 <listitem><para><emphasis>Right</emphasis>:
620 The right scenario represents a situation
621 where the source tree
622 (<replaceable>srctree</replaceable>) exists as a
623 previously extracted Git structure outside of
624 the <filename>devtool</filename> workspace.
625 In this example, the recipe also exists
626 elsewhere in its own layer.
627 </para>
628
629 <para>The following command tells
630 <filename>devtool</filename> the recipe
631 with which to work, uses the "-n" option to indicate
632 source does not need to be extracted, and uses
633 <replaceable>srctree</replaceable> to point to the
634 previously extracted source files:
635 <literallayout class='monospaced'>
636 $ devtool modify -n <replaceable>recipe srctree</replaceable>
637 </literallayout>
638 </para>
639
640 <para>Once the command finishes, it creates only
641 an append file for the recipe in the workspace.
642 The recipe and the source code remain in their
643 original locations.
644 </para></listitem>
645 </itemizedlist>
646 </para></listitem>
647 <listitem><para><emphasis>Edit the Source</emphasis>:
648 Once you have used the <filename>devtool modify</filename>
649 command, you are free to make changes to the source
650 files.
651 You can use any editor you like to make and save
652 your source code modifications.
653 </para></listitem>
654 <listitem><para><emphasis>Build the Recipe</emphasis>:
655 Once you have updated the source files, you can build
656 the recipe.
657 </para></listitem>
658 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
659 When you use the <filename>devtool build</filename>
660 command to build out your recipe, you probably want to see
661 if the resulting build output works as expected on target
662 hardware.
663 <note>
664 This step assumes you have a previously built
665 image that is already either running in QEMU or
666 running on actual hardware.
667 Also, it is assumed that for deployment of the image
668 to the target, SSH is installed in the image and if
669 the image is running on real hardware that you have
670 network access to and from your development machine.
671 </note>
672 You can deploy your build output to that target hardware by
673 using the <filename>devtool deploy-target</filename> command:
674 <literallayout class='monospaced'>
675 $ devtool deploy-target <replaceable>recipe target</replaceable>
676 </literallayout>
677 The <replaceable>target</replaceable> is a live target machine
678 running as an SSH server.</para>
679
680 <para>You can, of course, also deploy the image you build
681 using the <filename>devtool build-image</filename> command
682 to actual hardware.
683 However, <filename>devtool</filename> does not provide a
684 specific command that allows you to do this.
685 </para></listitem>
686 <listitem><para>
687 <emphasis>Finish Your Work With the Recipe</emphasis>:
688 The <filename>devtool finish</filename> command creates
689 any patches corresponding to commits in the local
690 Git repository, updates the recipe to point to them
691 (or creates a <filename>.bbappend</filename> file to do
692 so, depending on the specified destination layer), and
693 then resets the recipe so that the recipe is built normally
694 rather than from the workspace.
695 <literallayout class='monospaced'>
696 $ devtool finish <replaceable>recipe layer</replaceable>
697 </literallayout>
698 <note>
699 Any changes you want to turn into patches must be
700 committed to the Git repository in the source tree.
701 </note></para>
702
703 <para>Because there is no need to move the recipe,
704 <filename>devtool finish</filename> either updates the
705 original recipe in the original layer or the command
706 creates a <filename>.bbappend</filename> in a different
707 layer as provided by <replaceable>layer</replaceable>.
708 </para>
709
710 <para>As a final process of the
711 <filename>devtool finish</filename> command, the state
712 of the standard layers and the upstream source is
713 restored so that you can build the recipe from those
714 areas rather than the workspace.
715 <note>
716 You can use the <filename>devtool reset</filename>
717 command to put things back should you decide you
718 do not want to proceed with your work.
719 If you do use this command, realize that the source
720 tree is preserved.
721 </note>
722 </para></listitem>
723 </orderedlist>
724 </para>
725 </section>
726
727 <section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
728 <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
729
730 <para>
731 The <filename>devtool upgrade</filename> command updates
732 an existing recipe so that you can build it for an updated
733 set of source files.
734 The command is flexible enough to allow you to specify
735 source code revision and versioning schemes, extract code into
736 or out of the <filename>devtool</filename> workspace, and
737 work with any source file forms that the fetchers support.
738 </para>
739
740 <para>
741 Depending on your particular scenario, the arguments and options
742 you use with <filename>devtool upgrade</filename> form different
743 combinations.
744 The following diagram shows a common development flow
745 you would use with the <filename>devtool modify</filename>
746 command:
747 </para>
748
749 <para>
750 <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" />
751 </para>
752
753 <para>
754 <orderedlist>
755 <listitem><para><emphasis>Initiate the Upgrade</emphasis>:
756 The top part of the flow shows a typical scenario by which
757 you could use <filename>devtool upgrade</filename>.
758 The following conditions exist:
759 <itemizedlist>
760 <listitem><para>The recipe exists in some layer external
761 to the <filename>devtool</filename> workspace.
762 </para></listitem>
763 <listitem><para>The source files for the new release
764 exist adjacent to the same location pointed to by
765 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
766 in the recipe (e.g. a tarball with the new version
767 number in the name, or as a different revision in
768 the upstream Git repository).
769 </para></listitem>
770 </itemizedlist>
771 A common situation is where third-party software has
772 undergone a revision so that it has been upgraded.
773 The recipe you have access to is likely in your own layer.
774 Thus, you need to upgrade the recipe to use the
775 newer version of the software:
776 <literallayout class='monospaced'>
777 $ devtool upgrade -V <replaceable>version recipe</replaceable>
778 </literallayout>
779 By default, the <filename>devtool upgrade</filename> command
780 extracts source code into the <filename>sources</filename>
781 directory in the workspace.
782 If you want the code extracted to any other location, you
783 need to provide the <replaceable>srctree</replaceable>
784 positional argument with the command as follows:
785 <literallayout class='monospaced'>
786 $ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
787 </literallayout>
788 Also, in this example, the "-V" option is used to specify
789 the new version.
790 If the source files pointed to by the
791 <filename>SRC_URI</filename> statement in the recipe are
792 in a Git repository, you must provide the "-S" option and
793 specify a revision for the software.</para>
794
795 <para>Once <filename>devtool</filename> locates the recipe,
796 it uses the <filename>SRC_URI</filename> variable to locate
797 the source code and any local patch files from other
798 developers are located.
799 The result is that the command sets up the source
800 code, the new version of the recipe, and an append file
801 all within the workspace.
802 </para></listitem>
803 <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
804 At this point, there could be some conflicts due to the
805 software being upgraded to a new version.
806 This would occur if your recipe specifies some patch files in
807 <filename>SRC_URI</filename> that conflict with changes
808 made in the new version of the software.
809 If this is the case, you need to resolve the conflicts
810 by editing the source and following the normal
811 <filename>git rebase</filename> conflict resolution
812 process.</para>
813 <para>Before moving onto the next step, be sure to resolve any
814 such conflicts created through use of a newer or different
815 version of the software.
816 </para></listitem>
817 <listitem><para><emphasis>Build the Recipe</emphasis>:
818 Once you have your recipe in order, you can build it.
819 You can either use <filename>devtool build</filename> or
820 <filename>bitbake</filename>.
821 Either method produces build output that is stored
822 in
823 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
824 </para></listitem>
825 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
826 When you use the <filename>devtool build</filename>
827 command or <filename>bitbake</filename> to build out your
828 recipe, you probably want to see if the resulting build
829 output works as expected on target hardware.
830 <note>
831 This step assumes you have a previously built
832 image that is already either running in QEMU or
833 running on actual hardware.
834 Also, it is assumed that for deployment of the image
835 to the target, SSH is installed in the image and if
836 the image is running on real hardware that you have
837 network access to and from your development machine.
838 </note>
839 You can deploy your build output to that target hardware by
840 using the <filename>devtool deploy-target</filename> command:
841 <literallayout class='monospaced'>
842 $ devtool deploy-target <replaceable>recipe target</replaceable>
843 </literallayout>
844 The <replaceable>target</replaceable> is a live target machine
845 running as an SSH server.</para>
846 <para>You can, of course, also deploy the image you build
847 using the <filename>devtool build-image</filename> command
848 to actual hardware.
849 However, <filename>devtool</filename> does not provide a
850 specific command that allows you to do this.
851 </para></listitem>
852 <listitem><para>
853 <emphasis>Finish Your Work With the Recipe</emphasis>:
854 The <filename>devtool finish</filename> command creates
855 any patches corresponding to commits in the local
856 Git repository, updates the recipe to point to them
857 (or creates a <filename>.bbappend</filename> file to do
858 so, depending on the specified destination layer), and
859 then resets the recipe so that the recipe is built normally
860 rather than from the workspace.
861 <literallayout class='monospaced'>
862 $ devtool finish <replaceable>recipe layer</replaceable>
863 </literallayout>
864 <note>
865 Any changes you want to turn into patches must be
866 committed to the Git repository in the source tree.
867 </note></para>
868 <para>Because there is no need to move the recipe,
869 <filename>devtool finish</filename> either updates the
870 original recipe in the original layer or the command
871 creates a <filename>.bbappend</filename> in a different
872 layer as provided by <replaceable>layer</replaceable>.
873 </para>
874 <para>As a final process of the
875 <filename>devtool finish</filename> command, the state
876 of the standard layers and the upstream source is
877 restored so that you can build the recipe from those
878 areas rather than the workspace.
879 <note>
880 You can use the <filename>devtool reset</filename>
881 command to put things back should you decide you
882 do not want to proceed with your work.
883 If you do use this command, realize that the source
884 tree is preserved.
885 </note>
886 </para></listitem>
887 </orderedlist>
888 </para>
889 </section>
956 </section> 890 </section>
957 891
958 <section id='sdk-adding-makefile-only-software'> 892 <section id='sdk-a-closer-look-at-devtool-add'>
959 <title>Adding Makefile-Only Software</title> 893 <title>A Closer Look at <filename>devtool add</filename></title>
960
961 <para>
962 The use of <filename>make</filename> by itself is very common
963 in both proprietary and open source software.
964 Unfortunately, Makefiles are often not written with
965 cross-compilation in mind.
966 Thus, <filename>devtool add</filename> often cannot do very
967 much to ensure that these Makefiles build correctly.
968 It is very common, for example, to explicitly call
969 <filename>gcc</filename> instead of using the
970 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
971 variable.
972 Usually, in a cross-compilation environment,
973 <filename>gcc</filename> is the compiler for the build host
974 and the cross-compiler is named something similar to
975 <filename>arm-poky-linux-gnueabi-gcc</filename> and might
976 require some arguments (e.g. to point to the associated sysroot
977 for the target machine).
978 </para>
979 894
980 <para> 895 <para>
981 When writing a recipe for Makefile-only software, keep the 896 The <filename>devtool add</filename> command automatically creates a
982 following in mind: 897 recipe based on the source tree with which you provide it.
898 Currently, the command has support for the following:
983 <itemizedlist> 899 <itemizedlist>
984 <listitem><para> 900 <listitem><para>
985 You probably need to patch the Makefile to use 901 Autotools (<filename>autoconf</filename> and
986 variables instead of hardcoding tools within the 902 <filename>automake</filename>)
987 toolchain such as <filename>gcc</filename> and
988 <filename>g++</filename>.
989 </para></listitem> 903 </para></listitem>
990 <listitem><para> 904 <listitem><para>
991 The environment in which <filename>make</filename> runs 905 CMake
992 is set up with various standard variables for
993 compilation (e.g. <filename>CC</filename>,
994 <filename>CXX</filename>, and so forth) in a similar
995 manner to the environment set up by the SDK's
996 environment setup script.
997 One easy way to see these variables is to run the
998 <filename>devtool build</filename> command on the
999 recipe and then look in
1000 <filename>oe-logs/run.do_compile</filename>.
1001 Towards the top of this file you will see a list of
1002 environment variables that are being set.
1003 You can take advantage of these variables within the
1004 Makefile.
1005 </para></listitem> 906 </para></listitem>
1006 <listitem><para> 907 <listitem><para>
1007 If the Makefile sets a default for a variable using "=", 908 Scons
1008 that default overrides the value set in the environment,
1009 which is usually not desirable.
1010 In this situation, you can either patch the Makefile
1011 so it sets the default using the "?=" operator, or
1012 you can alternatively force the value on the
1013 <filename>make</filename> command line.
1014 To force the value on the command line, add the
1015 variable setting to
1016 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink>
1017 or
1018 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1019 within the recipe.
1020 Here is an example using <filename>EXTRA_OEMAKE</filename>:
1021 <literallayout class='monospaced'>
1022 EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
1023 </literallayout>
1024 In the above example, single quotes are used around the
1025 variable settings as the values are likely to contain
1026 spaces because required default options are passed to
1027 the compiler.
1028 </para></listitem> 909 </para></listitem>
1029 <listitem><para> 910 <listitem><para>
1030 Hardcoding paths inside Makefiles is often problematic 911 <filename>qmake</filename>
1031 in a cross-compilation environment.
1032 This is particularly true because those hardcoded paths
1033 often point to locations on the build host and thus
1034 will either be read-only or will introduce
1035 contamination into the cross-compilation by virtue of
1036 being specific to the build host rather than the target.
1037 Patching the Makefile to use prefix variables or other
1038 path variables is usually the way to handle this.
1039 </para></listitem> 912 </para></listitem>
1040 <listitem><para> 913 <listitem><para>
1041 Sometimes a Makefile runs target-specific commands such 914 Plain <filename>Makefile</filename>
1042 as <filename>ldconfig</filename>. 915 </para></listitem>
1043 For such cases, you might be able to simply apply 916 <listitem><para>
1044 patches that remove these commands from the Makefile. 917 Out-of-tree kernel module
918 </para></listitem>
919 <listitem><para>
920 Binary package (i.e. "-b" option)
1045 </para></listitem> 921 </para></listitem>
1046 </itemizedlist>
1047 </para>
1048 </section>
1049
1050 <section id='sdk-adding-native-tools'>
1051 <title>Adding Native Tools</title>
1052
1053 <para>
1054 Often, you need to build additional tools that run on the
1055 build host system as opposed to the target.
1056 You should indicate this using one of the following methods
1057 when you run <filename>devtool add</filename>:
1058 <itemizedlist>
1059 <listitem><para> 922 <listitem><para>
1060 Specify the name of the recipe such that it ends 923 Node.js module
1061 with "-native".
1062 Specifying the name like this produces a recipe that
1063 only builds for the build host.
1064 </para></listitem> 924 </para></listitem>
1065 <listitem><para> 925 <listitem><para>
1066 Specify the "&dash;&dash;also-native" option with the 926 Python modules that use <filename>setuptools</filename>
1067 <filename>devtool add</filename> command. 927 or <filename>distutils</filename>
1068 Specifying this option creates a recipe file that still
1069 builds for the target but also creates a variant with
1070 a "-native" suffix that builds for the build host.
1071 </para></listitem> 928 </para></listitem>
1072 </itemizedlist> 929 </itemizedlist>
930 </para>
931
932 <para>
933 Apart from binary packages, the determination of how a source tree
934 should be treated is automatic based on the files present within
935 that source tree.
936 For example, if a <filename>CMakeLists.txt</filename> file is found,
937 then the source tree is assumed to be using
938 CMake and is treated accordingly.
1073 <note> 939 <note>
1074 If you need to add a tool that is shipped as part of a 940 In most cases, you need to edit the automatically generated
1075 source tree that builds code for the target, you can 941 recipe in order to make it build properly.
1076 typically accomplish this by building the native and target 942 Typically, you would go through several edit and build cycles
1077 parts separately rather than within the same compilation 943 until you can build the recipe.
1078 process. 944 Once the recipe can be built, you could use possible further
1079 Realize though that with the "&dash;&dash;also-native" option, you 945 iterations to test the recipe on the target device.
1080 can add the tool using just one recipe file.
1081 </note> 946 </note>
1082 </para> 947 </para>
1083 </section>
1084
1085 <section id='sdk-adding-node-js-modules'>
1086 <title>Adding Node.js Modules</title>
1087 948
1088 <para> 949 <para>
1089 You can use the <filename>devtool add</filename> command two 950 The remainder of this section covers specifics regarding how parts
1090 different ways to add Node.js modules: 1) Through 951 of the recipe are generated.
1091 <filename>npm</filename> and, 2) from a repository or local
1092 source.
1093 </para> 952 </para>
1094 953
1095 <para> 954 <section id='sdk-name-and-version'>
1096 Use the following form to add Node.js modules through 955 <title>Name and Version</title>
1097 <filename>npm</filename>: 956
1098 <literallayout class='monospaced'> 957 <para>
1099 $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" 958 If you do not specify a name and version on the command
1100 </literallayout> 959 line, <filename>devtool add</filename> attempts to determine
1101 The name and version parameters are mandatory. 960 the name and version of the software being built from
1102 Lockdown and shrinkwrap files are generated and pointed to by 961 various metadata within the source tree.
1103 the recipe in order to freeze the version that is fetched for 962 Furthermore, the command sets the name of the created recipe
1104 the dependencies according to the first time. 963 file accordingly.
1105 This also saves checksums that are verified on future fetches. 964 If the name or version cannot be determined, the
1106 Together, these behaviors ensure the reproducibility and 965 <filename>devtool add</filename> command prints an error and
1107 integrity of the build. 966 you must re-run the command with both the name and version
1108 <note><title>Notes</title> 967 or just the name or version specified.
968 </para>
969
970 <para>
971 Sometimes the name or version determined from the source tree
972 might be incorrect.
973 For such a case, you must reset the recipe:
974 <literallayout class='monospaced'>
975 $ devtool reset -n <replaceable>recipename</replaceable>
976 </literallayout>
977 After running the <filename>devtool reset</filename> command,
978 you need to run <filename>devtool add</filename> again and
979 provide the name or the version.
980 </para>
981 </section>
982
983 <section id='sdk-dependency-detection-and-mapping'>
984 <title>Dependency Detection and Mapping</title>
985
986 <para>
987 The <filename>devtool add</filename> command attempts to
988 detect build-time dependencies and map them to other recipes
989 in the system.
990 During this mapping, the command fills in the names of those
991 recipes in the
992 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
993 value within the recipe.
994 If a dependency cannot be mapped, then a comment is placed in
995 the recipe indicating such.
996 The inability to map a dependency might be caused because the
997 naming is not recognized or because the dependency simply is
998 not available.
999 For cases where the dependency is not available, you must use
1000 the <filename>devtool add</filename> command to add an
1001 additional recipe to satisfy the dependency and then come
1002 back to the first recipe and add its name to
1003 <filename>DEPENDS</filename>.
1004 </para>
1005
1006 <para>
1007 If you need to add runtime dependencies, you can do so by
1008 adding the following to your recipe:
1009 <literallayout class='monospaced'>
1010 RDEPENDS_${PN} += "dependency1 dependency2 ..."
1011 </literallayout>
1012 <note>
1013 The <filename>devtool add</filename> command often cannot
1014 distinguish between mandatory and optional dependencies.
1015 Consequently, some of the detected dependencies might
1016 in fact be optional.
1017 When in doubt, consult the documentation or the configure
1018 script for the software the recipe is building for further
1019 details.
1020 In some cases, you might find you can substitute the
1021 dependency for an option to disable the associated
1022 functionality passed to the configure script.
1023 </note>
1024 </para>
1025 </section>
1026
1027 <section id='sdk-license-detection'>
1028 <title>License Detection</title>
1029
1030 <para>
1031 The <filename>devtool add</filename> command attempts to
1032 determine if the software you are adding is able to be
1033 distributed under a common open-source license and sets the
1034 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
1035 value accordingly.
1036 You should double-check this value against the documentation
1037 or source files for the software you are building and update
1038 that <filename>LICENSE</filename> value if necessary.
1039 </para>
1040
1041 <para>
1042 The <filename>devtool add</filename> command also sets the
1043 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1044 value to point to all files that appear to be license-related.
1045 However, license statements often appear in comments at the top
1046 of source files or within documentation.
1047 Consequently, you might need to amend the
1048 <filename>LIC_FILES_CHKSUM</filename> variable to point to one
1049 or more of those comments if present.
1050 Setting <filename>LIC_FILES_CHKSUM</filename> is particularly
1051 important for third-party software.
1052 The mechanism attempts to ensure correct licensing should you
1053 upgrade the recipe to a newer upstream version in future.
1054 Any change in licensing is detected and you receive an error
1055 prompting you to check the license text again.
1056 </para>
1057
1058 <para>
1059 If the <filename>devtool add</filename> command cannot
1060 determine licensing information, the
1061 <filename>LICENSE</filename> value is set to "CLOSED" and the
1062 <filename>LIC_FILES_CHKSUM</filename> value remains unset.
1063 This behavior allows you to continue with development but is
1064 unlikely to be correct in all cases.
1065 Consequently, you should check the documentation or source
1066 files for the software you are building to determine the actual
1067 license.
1068 </para>
1069 </section>
1070
1071 <section id='sdk-adding-makefile-only-software'>
1072 <title>Adding Makefile-Only Software</title>
1073
1074 <para>
1075 The use of <filename>make</filename> by itself is very common
1076 in both proprietary and open source software.
1077 Unfortunately, Makefiles are often not written with
1078 cross-compilation in mind.
1079 Thus, <filename>devtool add</filename> often cannot do very
1080 much to ensure that these Makefiles build correctly.
1081 It is very common, for example, to explicitly call
1082 <filename>gcc</filename> instead of using the
1083 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
1084 variable.
1085 Usually, in a cross-compilation environment,
1086 <filename>gcc</filename> is the compiler for the build host
1087 and the cross-compiler is named something similar to
1088 <filename>arm-poky-linux-gnueabi-gcc</filename> and might
1089 require some arguments (e.g. to point to the associated sysroot
1090 for the target machine).
1091 </para>
1092
1093 <para>
1094 When writing a recipe for Makefile-only software, keep the
1095 following in mind:
1109 <itemizedlist> 1096 <itemizedlist>
1110 <listitem><para> 1097 <listitem><para>
1111 You must use quotes around the URL. 1098 You probably need to patch the Makefile to use
1112 The <filename>devtool add</filename> does not require 1099 variables instead of hardcoding tools within the
1113 the quotes, but the shell considers ";" as a splitter 1100 toolchain such as <filename>gcc</filename> and
1114 between multiple commands. 1101 <filename>g++</filename>.
1115 Thus, without the quotes,
1116 <filename>devtool add</filename> does not receive the
1117 other parts, which results in several "command not
1118 found" errors.
1119 </para></listitem> 1102 </para></listitem>
1120 <listitem><para> 1103 <listitem><para>
1121 In order to support adding 1104 The environment in which <filename>make</filename> runs
1122 Node.js modules, a 1105 is set up with various standard variables for
1123 <filename>nodejs</filename> recipe must be part of your 1106 compilation (e.g. <filename>CC</filename>,
1124 SDK in order to provide Node.js 1107 <filename>CXX</filename>, and so forth) in a similar
1125 itself. 1108 manner to the environment set up by the SDK's
1109 environment setup script.
1110 One easy way to see these variables is to run the
1111 <filename>devtool build</filename> command on the
1112 recipe and then look in
1113 <filename>oe-logs/run.do_compile</filename>.
1114 Towards the top of this file you will see a list of
1115 environment variables that are being set.
1116 You can take advantage of these variables within the
1117 Makefile.
1118 </para></listitem>
1119 <listitem><para>
1120 If the Makefile sets a default for a variable using "=",
1121 that default overrides the value set in the environment,
1122 which is usually not desirable.
1123 In this situation, you can either patch the Makefile
1124 so it sets the default using the "?=" operator, or
1125 you can alternatively force the value on the
1126 <filename>make</filename> command line.
1127 To force the value on the command line, add the
1128 variable setting to
1129 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink>
1130 or
1131 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1132 within the recipe.
1133 Here is an example using <filename>EXTRA_OEMAKE</filename>:
1134 <literallayout class='monospaced'>
1135 EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
1136 </literallayout>
1137 In the above example, single quotes are used around the
1138 variable settings as the values are likely to contain
1139 spaces because required default options are passed to
1140 the compiler.
1141 </para></listitem>
1142 <listitem><para>
1143 Hardcoding paths inside Makefiles is often problematic
1144 in a cross-compilation environment.
1145 This is particularly true because those hardcoded paths
1146 often point to locations on the build host and thus
1147 will either be read-only or will introduce
1148 contamination into the cross-compilation by virtue of
1149 being specific to the build host rather than the target.
1150 Patching the Makefile to use prefix variables or other
1151 path variables is usually the way to handle this.
1152 </para></listitem>
1153 <listitem><para>
1154 Sometimes a Makefile runs target-specific commands such
1155 as <filename>ldconfig</filename>.
1156 For such cases, you might be able to simply apply
1157 patches that remove these commands from the Makefile.
1126 </para></listitem> 1158 </para></listitem>
1127 </itemizedlist> 1159 </itemizedlist>
1128 </note> 1160 </para>
1129 </para> 1161 </section>
1130 1162
1131 <para> 1163 <section id='sdk-adding-native-tools'>
1132 As mentioned earlier, you can also add Node.js modules 1164 <title>Adding Native Tools</title>
1133 directly from a repository or local source tree.
1134 To add modules this way, use <filename>devtool add</filename> in
1135 the following form:
1136 <literallayout class='monospaced'>
1137 $ devtool add https://github.com/diversario/node-ssdp
1138 </literallayout>
1139 In this example, <filename>devtool</filename> fetches the specified
1140 Git repository, detects that the code is Node.js code, fetches
1141 dependencies using <filename>npm</filename>, and sets
1142 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1143 accordingly.
1144 </para>
1145 </section>
1146</section>
1147 1165
1148<section id='sdk-working-with-recipes'> 1166 <para>
1149 <title>Working With Recipes</title> 1167 Often, you need to build additional tools that run on the
1150 1168 build host system as opposed to the target.
1151 <para> 1169 You should indicate this using one of the following methods
1152 When building a recipe with <filename>devtool build</filename> the 1170 when you run <filename>devtool add</filename>:
1153 typical build progression is as follows: 1171 <itemizedlist>
1154 <orderedlist> 1172 <listitem><para>
1155 <listitem><para> 1173 Specify the name of the recipe such that it ends
1156 Fetch the source 1174 with "-native".
1157 </para></listitem> 1175 Specifying the name like this produces a recipe that
1158 <listitem><para> 1176 only builds for the build host.
1159 Unpack the source 1177 </para></listitem>
1160 </para></listitem> 1178 <listitem><para>
1161 <listitem><para> 1179 Specify the "&dash;&dash;also-native" option with the
1162 Configure the source 1180 <filename>devtool add</filename> command.
1163 </para></listitem> 1181 Specifying this option creates a recipe file that still
1164 <listitem><para> 1182 builds for the target but also creates a variant with
1165 Compiling the source 1183 a "-native" suffix that builds for the build host.
1166 </para></listitem> 1184 </para></listitem>
1167 <listitem><para> 1185 </itemizedlist>
1168 Install the build output 1186 <note>
1169 </para></listitem> 1187 If you need to add a tool that is shipped as part of a
1170 <listitem><para> 1188 source tree that builds code for the target, you can
1171 Package the installed output 1189 typically accomplish this by building the native and target
1172 </para></listitem> 1190 parts separately rather than within the same compilation
1173 </orderedlist> 1191 process.
1174 For recipes in the workspace, fetching and unpacking is disabled 1192 Realize though that with the "&dash;&dash;also-native" option, you
1175 as the source tree has already been prepared and is persistent. 1193 can add the tool using just one recipe file.
1176 Each of these build steps is defined as a function, usually with a 1194 </note>
1177 "do_" prefix. 1195 </para>
1178 These functions are typically shell scripts but can instead be written 1196 </section>
1179 in Python. 1197
1180 </para> 1198 <section id='sdk-adding-node-js-modules'>
1181 1199 <title>Adding Node.js Modules</title>
1182 <para> 1200
1183 If you look at the contents of a recipe, you will see that the 1201 <para>
1184 recipe does not include complete instructions for building the 1202 You can use the <filename>devtool add</filename> command two
1185 software. 1203 different ways to add Node.js modules: 1) Through
1186 Instead, common functionality is encapsulated in classes inherited 1204 <filename>npm</filename> and, 2) from a repository or local
1187 with the <filename>inherit</filename> directive, leaving the recipe 1205 source.
1188 to describe just the things that are specific to the software to be 1206 </para>
1189 built. 1207
1190 A <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink> 1208 <para>
1191 class exists that is implicitly inherited by all recipes and provides 1209 Use the following form to add Node.js modules through
1192 the functionality that most typical recipes need. 1210 <filename>npm</filename>:
1193 </para> 1211 <literallayout class='monospaced'>
1194 1212 $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
1195 <para> 1213 </literallayout>
1196 The remainder of this section presents information useful when 1214 The name and version parameters are mandatory.
1197 working with recipes. 1215 Lockdown and shrinkwrap files are generated and pointed to by
1198 </para> 1216 the recipe in order to freeze the version that is fetched for
1217 the dependencies according to the first time.
1218 This also saves checksums that are verified on future fetches.
1219 Together, these behaviors ensure the reproducibility and
1220 integrity of the build.
1221 <note><title>Notes</title>
1222 <itemizedlist>
1223 <listitem><para>
1224 You must use quotes around the URL.
1225 The <filename>devtool add</filename> does not require
1226 the quotes, but the shell considers ";" as a splitter
1227 between multiple commands.
1228 Thus, without the quotes,
1229 <filename>devtool add</filename> does not receive the
1230 other parts, which results in several "command not
1231 found" errors.
1232 </para></listitem>
1233 <listitem><para>
1234 In order to support adding
1235 Node.js modules, a
1236 <filename>nodejs</filename> recipe must be part of your
1237 SDK in order to provide Node.js
1238 itself.
1239 </para></listitem>
1240 </itemizedlist>
1241 </note>
1242 </para>
1199 1243
1200 <section id='sdk-finding-logs-and-work-files'> 1244 <para>
1201 <title>Finding Logs and Work Files</title> 1245 As mentioned earlier, you can also add Node.js modules
1246 directly from a repository or local source tree.
1247 To add modules this way, use <filename>devtool add</filename> in
1248 the following form:
1249 <literallayout class='monospaced'>
1250 $ devtool add https://github.com/diversario/node-ssdp
1251 </literallayout>
1252 In this example, <filename>devtool</filename> fetches the specified
1253 Git repository, detects that the code is Node.js code, fetches
1254 dependencies using <filename>npm</filename>, and sets
1255 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1256 accordingly.
1257 </para>
1258 </section>
1259 </section>
1202 1260
1203 <para> 1261 <section id='sdk-working-with-recipes'>
1204 When you are debugging a recipe that you previously created using 1262 <title>Working With Recipes</title>
1205 <filename>devtool add</filename> or whose source you are modifying
1206 by using the <filename>devtool modify</filename> command, after
1207 the first run of <filename>devtool build</filename>, you will
1208 find some symbolic links created within the source tree:
1209 <filename>oe-logs</filename>, which points to the directory in
1210 which log files and run scripts for each build step are created
1211 and <filename>oe-workdir</filename>, which points to the temporary
1212 work area for the recipe.
1213 You can use these links to get more information on what is
1214 happening at each build step.
1215 </para>
1216 1263
1217 <para> 1264 <para>
1218 These locations under <filename>oe-workdir</filename> are 1265 When building a recipe with <filename>devtool build</filename> the
1219 particularly useful: 1266 typical build progression is as follows:
1220 <itemizedlist> 1267 <orderedlist>
1221 <listitem><para><filename>image/</filename>: 1268 <listitem><para>
1222 Contains all of the files installed at the 1269 Fetch the source
1223 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1224 stage.
1225 Within a recipe, this directory is referred to by the
1226 expression
1227 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
1228 </para></listitem> 1270 </para></listitem>
1229 <listitem><para><filename>sysroot-destdir/</filename>: 1271 <listitem><para>
1230 Contains a subset of files installed within 1272 Unpack the source
1231 <filename>do_install</filename> that have been put into the
1232 shared sysroot.
1233 For more information, see the
1234 "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"
1235 section.
1236 </para></listitem> 1273 </para></listitem>
1237 <listitem><para><filename>packages-split/</filename>: 1274 <listitem><para>
1238 Contains subdirectories for each package produced by the 1275 Configure the source
1239 recipe.
1240 For more information, see the
1241 "<link linkend='sdk-packaging'>Packaging</link>" section.
1242 </para></listitem> 1276 </para></listitem>
1243 </itemizedlist> 1277 <listitem><para>
1244 </para> 1278 Compiling the source
1245 </section> 1279 </para></listitem>
1246 1280 <listitem><para>
1247 <section id='sdk-setting-configure-arguments'> 1281 Install the build output
1248 <title>Setting Configure Arguments</title> 1282 </para></listitem>
1249 1283 <listitem><para>
1250 <para> 1284 Package the installed output
1251 If the software your recipe is building uses GNU autoconf, 1285 </para></listitem>
1252 then a fixed set of arguments is passed to it to enable 1286 </orderedlist>
1253 cross-compilation plus any extras specified by 1287 For recipes in the workspace, fetching and unpacking is disabled
1254 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink> 1288 as the source tree has already been prepared and is persistent.
1255 or 1289 Each of these build steps is defined as a function, usually with a
1256 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> 1290 "do_" prefix.
1257 set within the recipe. 1291 These functions are typically shell scripts but can instead be written
1258 If you wish to pass additional options, add them to 1292 in Python.
1259 <filename>EXTRA_OECONF</filename> or
1260 <filename>PACKAGECONFIG_CONFARGS</filename>.
1261 Other supported build tools have similar variables
1262 (e.g.
1263 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
1264 for CMake,
1265 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink>
1266 for Scons, and so forth).
1267 If you need to pass anything on the <filename>make</filename>
1268 command line, you can use <filename>EXTRA_OEMAKE</filename> or the
1269 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1270 variables to do so.
1271 </para> 1293 </para>
1272 1294
1273 <para> 1295 <para>
1274 You can use the <filename>devtool configure-help</filename> command 1296 If you look at the contents of a recipe, you will see that the
1275 to help you set the arguments listed in the previous paragraph. 1297 recipe does not include complete instructions for building the
1276 The command determines the exact options being passed, and shows 1298 software.
1277 them to you along with any custom arguments specified through 1299 Instead, common functionality is encapsulated in classes inherited
1278 <filename>EXTRA_OECONF</filename> or 1300 with the <filename>inherit</filename> directive, leaving the recipe
1279 <filename>PACKAGECONFIG_CONFARGS</filename>. 1301 to describe just the things that are specific to the software to be
1280 If applicable, the command also shows you the output of the 1302 built.
1281 configure script's "&dash;&dash;help" option as a reference. 1303 A <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
1304 class exists that is implicitly inherited by all recipes and provides
1305 the functionality that most typical recipes need.
1282 </para> 1306 </para>
1283 </section>
1284
1285 <section id='sdk-sharing-files-between-recipes'>
1286 <title>Sharing Files Between Recipes</title>
1287 1307
1288 <para> 1308 <para>
1289 Recipes often need to use files provided by other recipes on 1309 The remainder of this section presents information useful when
1290 the build host. 1310 working with recipes.
1291 For example, an application linking to a common library needs
1292 access to the library itself and its associated headers.
1293 The way this access is accomplished within the extensible SDK is
1294 through the sysroot.
1295 One sysroot exists per "machine" for which the SDK is being built.
1296 In practical terms, this means a sysroot exists for the target
1297 machine, and a sysroot exists for the build host.
1298 </para> 1311 </para>
1299 1312
1300 <para> 1313 <section id='sdk-finding-logs-and-work-files'>
1301 Recipes should never write files directly into the sysroot. 1314 <title>Finding Logs and Work Files</title>
1302 Instead, files should be installed into standard locations 1315
1303 during the 1316 <para>
1304 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> 1317 When you are debugging a recipe that you previously created using
1305 task within the 1318 <filename>devtool add</filename> or whose source you are modifying
1306 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename> 1319 by using the <filename>devtool modify</filename> command, after
1307 directory. 1320 the first run of <filename>devtool build</filename>, you will
1308 A subset of these files automatically go into the sysroot. 1321 find some symbolic links created within the source tree:
1309 The reason for this limitation is that almost all files that go 1322 <filename>oe-logs</filename>, which points to the directory in
1310 into the sysroot are cataloged in manifests in order to ensure 1323 which log files and run scripts for each build step are created
1311 they can be removed later when a recipe is modified or removed. 1324 and <filename>oe-workdir</filename>, which points to the temporary
1312 Thus, the sysroot is able to remain free from stale files. 1325 work area for the recipe.
1313 </para> 1326 You can use these links to get more information on what is
1327 happening at each build step.
1328 </para>
1329
1330 <para>
1331 These locations under <filename>oe-workdir</filename> are
1332 particularly useful:
1333 <itemizedlist>
1334 <listitem><para><filename>image/</filename>:
1335 Contains all of the files installed at the
1336 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1337 stage.
1338 Within a recipe, this directory is referred to by the
1339 expression
1340 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
1341 </para></listitem>
1342 <listitem><para><filename>sysroot-destdir/</filename>:
1343 Contains a subset of files installed within
1344 <filename>do_install</filename> that have been put into the
1345 shared sysroot.
1346 For more information, see the
1347 "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"
1348 section.
1349 </para></listitem>
1350 <listitem><para><filename>packages-split/</filename>:
1351 Contains subdirectories for each package produced by the
1352 recipe.
1353 For more information, see the
1354 "<link linkend='sdk-packaging'>Packaging</link>" section.
1355 </para></listitem>
1356 </itemizedlist>
1357 </para>
1358 </section>
1359
1360 <section id='sdk-setting-configure-arguments'>
1361 <title>Setting Configure Arguments</title>
1362
1363 <para>
1364 If the software your recipe is building uses GNU autoconf,
1365 then a fixed set of arguments is passed to it to enable
1366 cross-compilation plus any extras specified by
1367 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
1368 or
1369 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1370 set within the recipe.
1371 If you wish to pass additional options, add them to
1372 <filename>EXTRA_OECONF</filename> or
1373 <filename>PACKAGECONFIG_CONFARGS</filename>.
1374 Other supported build tools have similar variables
1375 (e.g.
1376 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
1377 for CMake,
1378 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink>
1379 for Scons, and so forth).
1380 If you need to pass anything on the <filename>make</filename>
1381 command line, you can use <filename>EXTRA_OEMAKE</filename> or the
1382 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1383 variables to do so.
1384 </para>
1385
1386 <para>
1387 You can use the <filename>devtool configure-help</filename> command
1388 to help you set the arguments listed in the previous paragraph.
1389 The command determines the exact options being passed, and shows
1390 them to you along with any custom arguments specified through
1391 <filename>EXTRA_OECONF</filename> or
1392 <filename>PACKAGECONFIG_CONFARGS</filename>.
1393 If applicable, the command also shows you the output of the
1394 configure script's "&dash;&dash;help" option as a reference.
1395 </para>
1396 </section>
1397
1398 <section id='sdk-sharing-files-between-recipes'>
1399 <title>Sharing Files Between Recipes</title>
1400
1401 <para>
1402 Recipes often need to use files provided by other recipes on
1403 the build host.
1404 For example, an application linking to a common library needs
1405 access to the library itself and its associated headers.
1406 The way this access is accomplished within the extensible SDK is
1407 through the sysroot.
1408 One sysroot exists per "machine" for which the SDK is being built.
1409 In practical terms, this means a sysroot exists for the target
1410 machine, and a sysroot exists for the build host.
1411 </para>
1412
1413 <para>
1414 Recipes should never write files directly into the sysroot.
1415 Instead, files should be installed into standard locations
1416 during the
1417 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1418 task within the
1419 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
1420 directory.
1421 A subset of these files automatically go into the sysroot.
1422 The reason for this limitation is that almost all files that go
1423 into the sysroot are cataloged in manifests in order to ensure
1424 they can be removed later when a recipe is modified or removed.
1425 Thus, the sysroot is able to remain free from stale files.
1426 </para>
1427 </section>
1428
1429 <section id='sdk-packaging'>
1430 <title>Packaging</title>
1431
1432 <para>
1433 Packaging is not always particularly relevant within the
1434 extensible SDK.
1435 However, if you examine how build output gets into the final image
1436 on the target device, it is important to understand packaging
1437 because the contents of the image are expressed in terms of
1438 packages and not recipes.
1439 </para>
1440
1441 <para>
1442 During the
1443 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
1444 task, files installed during the
1445 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1446 task are split into one main package, which is almost always named
1447 the same as the recipe, and several other packages.
1448 This separation is done because not all of those installed files
1449 are always useful in every image.
1450 For example, you probably do not need any of the documentation
1451 installed in a production image.
1452 Consequently, for each recipe the documentation files are separated
1453 into a <filename>-doc</filename> package.
1454 Recipes that package software that has optional modules or
1455 plugins might do additional package splitting as well.
1456 </para>
1457
1458 <para>
1459 After building a recipe you can see where files have gone by
1460 looking in the <filename>oe-workdir/packages-split</filename>
1461 directory, which contains a subdirectory for each package.
1462 Apart from some advanced cases, the
1463 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
1464 and
1465 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1466 variables controls splitting.
1467 The <filename>PACKAGES</filename> variable lists all of the
1468 packages to be produced, while the <filename>FILES</filename>
1469 variable specifies which files to include in each package,
1470 using an override to specify the package.
1471 For example, <filename>FILES_${PN}</filename> specifies the files
1472 to go into the main package (i.e. the main package is named the
1473 same as the recipe and
1474 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
1475 evaluates to the recipe name).
1476 The order of the <filename>PACKAGES</filename> value is significant.
1477 For each installed file, the first package whose
1478 <filename>FILES</filename> value matches the file is the package
1479 into which the file goes.
1480 Defaults exist for both the <filename>PACKAGES</filename> and
1481 <filename>FILES</filename> variables.
1482 Consequently, you might find you do not even need to set these
1483 variables in your recipe unless the software the recipe is
1484 building installs files into non-standard locations.
1485 </para>
1486 </section>
1314 </section> 1487 </section>
1315 1488
1316 <section id='sdk-packaging'> 1489 <section id='sdk-restoring-the-target-device-to-its-original-state'>
1317 <title>Packaging</title> 1490 <title>Restoring the Target Device to its Original State</title>
1318 1491
1319 <para> 1492 <para>
1320 Packaging is not always particularly relevant within the 1493 If you use the <filename>devtool deploy-target</filename>
1321 extensible SDK. 1494 command to write a recipe's build output to the target, and
1322 However, if you examine how build output gets into the final image 1495 you are working on an existing component of the system, then you
1323 on the target device, it is important to understand packaging 1496 might find yourself in a situation where you need to restore the
1324 because the contents of the image are expressed in terms of 1497 original files that existed prior to running the
1325 packages and not recipes. 1498 <filename>devtool deploy-target</filename> command.
1326 </para> 1499 Because the <filename>devtool deploy-target</filename> command
1327 1500 backs up any files it overwrites, you can use the
1328 <para> 1501 <filename>devtool undeploy-target</filename> to restore those files
1329 During the 1502 and remove any other files the recipe deployed.
1330 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> 1503 Consider the following example:
1331 task, files installed during the 1504 <literallayout class='monospaced'>
1332 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1333 task are split into one main package, which is almost always named
1334 the same as the recipe, and several other packages.
1335 This separation is done because not all of those installed files
1336 are always useful in every image.
1337 For example, you probably do not need any of the documentation
1338 installed in a production image.
1339 Consequently, for each recipe the documentation files are separated
1340 into a <filename>-doc</filename> package.
1341 Recipes that package software that has optional modules or
1342 plugins might do additional package splitting as well.
1343 </para>
1344
1345 <para>
1346 After building a recipe you can see where files have gone by
1347 looking in the <filename>oe-workdir/packages-split</filename>
1348 directory, which contains a subdirectory for each package.
1349 Apart from some advanced cases, the
1350 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
1351 and
1352 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1353 variables controls splitting.
1354 The <filename>PACKAGES</filename> variable lists all of the
1355 packages to be produced, while the <filename>FILES</filename>
1356 variable specifies which files to include in each package,
1357 using an override to specify the package.
1358 For example, <filename>FILES_${PN}</filename> specifies the files
1359 to go into the main package (i.e. the main package is named the
1360 same as the recipe and
1361 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
1362 evaluates to the recipe name).
1363 The order of the <filename>PACKAGES</filename> value is significant.
1364 For each installed file, the first package whose
1365 <filename>FILES</filename> value matches the file is the package
1366 into which the file goes.
1367 Defaults exist for both the <filename>PACKAGES</filename> and
1368 <filename>FILES</filename> variables.
1369 Consequently, you might find you do not even need to set these
1370 variables in your recipe unless the software the recipe is
1371 building installs files into non-standard locations.
1372 </para>
1373 </section>
1374</section>
1375
1376<section id='sdk-restoring-the-target-device-to-its-original-state'>
1377 <title>Restoring the Target Device to its Original State</title>
1378
1379 <para>
1380 If you use the <filename>devtool deploy-target</filename>
1381 command to write a recipe's build output to the target, and
1382 you are working on an existing component of the system, then you
1383 might find yourself in a situation where you need to restore the
1384 original files that existed prior to running the
1385 <filename>devtool deploy-target</filename> command.
1386 Because the <filename>devtool deploy-target</filename> command
1387 backs up any files it overwrites, you can use the
1388 <filename>devtool undeploy-target</filename> to restore those files
1389 and remove any other files the recipe deployed.
1390 Consider the following example:
1391 <literallayout class='monospaced'>
1392 $ devtool undeploy-target lighttpd root@192.168.7.2 1505 $ devtool undeploy-target lighttpd root@192.168.7.2
1393 </literallayout> 1506 </literallayout>
1394 If you have deployed multiple applications, you can remove them 1507 If you have deployed multiple applications, you can remove them
1395 all at once thus restoring the target device back to its 1508 all at once thus restoring the target device back to its
1396 original state: 1509 original state:
1397 <literallayout class='monospaced'> 1510 <literallayout class='monospaced'>
1398 $ devtool undeploy-target -a root@192.168.7.2 1511 $ devtool undeploy-target -a root@192.168.7.2
1399 </literallayout> 1512 </literallayout>
1400 Information about files deployed to the target as well as any 1513 Information about files deployed to the target as well as any
1401 backed up files are stored on the target itself. 1514 backed up files are stored on the target itself.
1402 This storage of course requires some additional space 1515 This storage of course requires some additional space
1403 on the target machine. 1516 on the target machine.
1404 <note> 1517 <note>
1405 The <filename>devtool deploy-target</filename> and 1518 The <filename>devtool deploy-target</filename> and
1406 <filename>devtool undeploy-target</filename> command do not 1519 <filename>devtool undeploy-target</filename> command do not
1407 currently interact with any package management system on the 1520 currently interact with any package management system on the
1408 target device (e.g. RPM or OPKG). 1521 target device (e.g. RPM or OPKG).
1409 Consequently, you should not intermingle operations 1522 Consequently, you should not intermingle operations
1410 <filename>devtool deploy-target</filename> and the package 1523 <filename>devtool deploy-target</filename> and the package
1411 manager operations on the target device. 1524 manager operations on the target device.
1412 Doing so could result in a conflicting set of files. 1525 Doing so could result in a conflicting set of files.
1413 </note> 1526 </note>
1414 </para> 1527 </para>
1415</section> 1528 </section>
1416 1529
1417<section id='sdk-installing-additional-items-into-the-extensible-sdk'> 1530 <section id='sdk-installing-additional-items-into-the-extensible-sdk'>
1418 <title>Installing Additional Items Into the Extensible SDK</title> 1531 <title>Installing Additional Items Into the Extensible SDK</title>
1419 1532
1420 <para> 1533 <para>
1421 The extensible SDK typically only comes with a small number of tools 1534 The extensible SDK typically only comes with a small number of tools
1422 and libraries out of the box. 1535 and libraries out of the box.
1423 If you have a minimal SDK, then it starts mostly empty and is 1536 If you have a minimal SDK, then it starts mostly empty and is
1424 populated on-demand. 1537 populated on-demand.
1425 However, sometimes you will need to explicitly install extra items 1538 However, sometimes you will need to explicitly install extra items
1426 into the SDK. 1539 into the SDK.
1427 If you need these extra items, you can first search for the items 1540 If you need these extra items, you can first search for the items
1428 using the <filename>devtool search</filename> command. 1541 using the <filename>devtool search</filename> command.
1429 For example, suppose you need to link to libGL but you are not sure 1542 For example, suppose you need to link to libGL but you are not sure
1430 which recipe provides it. 1543 which recipe provides it.
1431 You can use the following command to find out: 1544 You can use the following command to find out:
1432 <literallayout class='monospaced'> 1545 <literallayout class='monospaced'>
1433 $ devtool search libGL 1546 $ devtool search libGL
1434 mesa A free implementation of the OpenGL API 1547 mesa A free implementation of the OpenGL API
1435 </literallayout> 1548 </literallayout>
1436 Once you know the recipe (i.e. <filename>mesa</filename> in this 1549 Once you know the recipe (i.e. <filename>mesa</filename> in this
1437 example), you can install it: 1550 example), you can install it:
1438 <literallayout class='monospaced'> 1551 <literallayout class='monospaced'>
1439 $ devtool sdk-install mesa 1552 $ devtool sdk-install mesa
1440 </literallayout> 1553 </literallayout>
1441 By default, the <filename>devtool sdk-install</filename> assumes the 1554 By default, the <filename>devtool sdk-install</filename> assumes the
1442 item is available in pre-built form from your SDK provider. 1555 item is available in pre-built form from your SDK provider.
1443 If the item is not available and it is acceptable to build the item 1556 If the item is not available and it is acceptable to build the item
1444 from source, you can add the "-s" option as follows: 1557 from source, you can add the "-s" option as follows:
1445 <literallayout class='monospaced'> 1558 <literallayout class='monospaced'>
1446 $ devtool sdk-install -s mesa 1559 $ devtool sdk-install -s mesa
1447 </literallayout> 1560 </literallayout>
1448 It is important to remember that building the item from source takes 1561 It is important to remember that building the item from source takes
1449 significantly longer than installing the pre-built artifact. 1562 significantly longer than installing the pre-built artifact.
1450 Also, if no recipe exists for the item you want to add to the SDK, you 1563 Also, if no recipe exists for the item you want to add to the SDK, you
1451 must instead add it using the <filename>devtool add</filename> command. 1564 must instead add it using the <filename>devtool add</filename> command.
1452 </para> 1565 </para>
1453</section> 1566 </section>
1454 1567
1455<section id='sdk-updating-the-extensible-sdk'> 1568 <section id='sdk-updating-the-extensible-sdk'>
1456 <title>Updating the Extensible SDK</title> 1569 <title>Updating the Extensible SDK</title>
1457 1570
1458 <para> 1571 <para>
1459 If you are working with an extensible SDK that gets occasionally 1572 If you are working with an extensible SDK that gets occasionally
1460 updated (e.g. typically when that SDK has been provided to you by 1573 updated (e.g. typically when that SDK has been provided to you by
1461 another party), then you will need to manually pull down those 1574 another party), then you will need to manually pull down those
1462 updates to your installed SDK. 1575 updates to your installed SDK.
1463 </para> 1576 </para>
1464 1577
1465 <para> 1578 <para>
1466 To update your installed SDK, run the following: 1579 To update your installed SDK, run the following:
1467 <literallayout class='monospaced'> 1580 <literallayout class='monospaced'>
1468 $ devtool sdk-update 1581 $ devtool sdk-update
1469 </literallayout> 1582 </literallayout>
1470 The previous command assumes your SDK provider has set the default 1583 The previous command assumes your SDK provider has set the default
1471 update URL for you. 1584 update URL for you.
1472 If that URL has not been set, you need to specify it yourself as 1585 If that URL has not been set, you need to specify it yourself as
1473 follows: 1586 follows:
1474 <literallayout class='monospaced'> 1587 <literallayout class='monospaced'>
1475 $ devtool sdk-update <replaceable>path_to_update_directory</replaceable> 1588 $ devtool sdk-update <replaceable>path_to_update_directory</replaceable>
1476 </literallayout> 1589 </literallayout>
1477 <note> 1590 <note>
1478 The URL needs to point specifically to a published SDK and not an 1591 The URL needs to point specifically to a published SDK and not an
1479 SDK installer that you would download and install. 1592 SDK installer that you would download and install.
1480 </note> 1593 </note>
1481 </para> 1594 </para>
1482</section> 1595 </section>
1483
1484<section id='sdk-creating-a-derivative-sdk-with-additional-components'>
1485 <title>Creating a Derivative SDK With Additional Components</title>
1486 1596
1487 <para> 1597 <section id='sdk-creating-a-derivative-sdk-with-additional-components'>
1488 You might need to produce an SDK that contains your own custom 1598 <title>Creating a Derivative SDK With Additional Components</title>
1489 libraries for sending to a third party (e.g., if you are a vendor with
1490 customers needing to build their own software for the target platform).
1491 If that is the case, then you can produce a derivative SDK based on
1492 the currently installed SDK fairly easily.
1493 Use these steps:
1494 <orderedlist>
1495 <listitem><para>If necessary, install an extensible SDK that
1496 you want to use as a base for your derivative SDK.
1497 </para></listitem>
1498 <listitem><para>Source the environment script for the SDK.
1499 </para></listitem>
1500 <listitem><para>Add the extra libraries or other components
1501 you want by using the <filename>devtool add</filename>
1502 command.
1503 </para></listitem>
1504 <listitem><para>Run the <filename>devtool build-sdk</filename>
1505 command.
1506 </para></listitem>
1507 </orderedlist>
1508 The above procedure takes the recipes added to the workspace and
1509 constructs a new SDK installer containing those recipes and the
1510 resulting binary artifacts.
1511 The recipes go into their own separate layer in the constructed
1512 derivative SDK, leaving the workspace clean and ready for users
1513 to add their own recipes.
1514 </para>
1515</section>
1516 1599
1600 <para>
1601 You might need to produce an SDK that contains your own custom
1602 libraries for sending to a third party (e.g., if you are a vendor with
1603 customers needing to build their own software for the target platform).
1604 If that is the case, then you can produce a derivative SDK based on
1605 the currently installed SDK fairly easily.
1606 Use these steps:
1607 <orderedlist>
1608 <listitem><para>If necessary, install an extensible SDK that
1609 you want to use as a base for your derivative SDK.
1610 </para></listitem>
1611 <listitem><para>Source the environment script for the SDK.
1612 </para></listitem>
1613 <listitem><para>Add the extra libraries or other components
1614 you want by using the <filename>devtool add</filename>
1615 command.
1616 </para></listitem>
1617 <listitem><para>Run the <filename>devtool build-sdk</filename>
1618 command.
1619 </para></listitem>
1620 </orderedlist>
1621 The above procedure takes the recipes added to the workspace and
1622 constructs a new SDK installer containing those recipes and the
1623 resulting binary artifacts.
1624 The recipes go into their own separate layer in the constructed
1625 derivative SDK, leaving the workspace clean and ready for users
1626 to add their own recipes.
1627 </para>
1628 </section>
1517</chapter> 1629</chapter>
1518<!-- 1630<!--
1519vim: expandtab tw=80 ts=4 1631vim: expandtab tw=80 ts=4
diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml
index 0995f79a93..e0f51e1cf1 100644
--- a/documentation/sdk-manual/sdk-intro.xml
+++ b/documentation/sdk-manual/sdk-intro.xml
@@ -12,25 +12,24 @@
12 Welcome to the Yocto Project Software Development Kit (SDK) 12 Welcome to the Yocto Project Software Development Kit (SDK)
13 Developer's Guide. 13 Developer's Guide.
14 This manual provides information that explains how to use both the 14 This manual provides information that explains how to use both the
15 standard Yocto Project SDK and an extensible SDK to develop 15 Yocto Project extensible and standard SDKs to develop
16 applications and images using the Yocto Project. 16 applications and images.
17 Additionally, the manual also provides information on how to use 17 Additionally, the manual also provides information on how to use
18 the popular <trademark class='trade'>Eclipse</trademark> IDE as part 18 the popular <trademark class='trade'>Eclipse</trademark> IDE as part
19 of your application development workflow within the SDK environment. 19 of your application development workflow within the SDK environment.
20 <note>
21 Prior to the 2.0 Release of the Yocto Project, application
22 development was primarily accomplished through the use of the
23 Application Development Toolkit (ADT) and the availability
24 of stand-alone cross-development toolchains and other tools.
25 With the 2.1 Release of the Yocto Project, application development
26 has transitioned to within a tool-rich extensible SDK and the more
27 traditional standard SDK.
28 </note>
20 </para> 29 </para>
21 30
22 <para> 31 <para>
23 Prior to the 2.0 Release of the Yocto Project, application 32 All SDKs consist of the following:
24 development was primarily accomplished through the use of the
25 Application Development Toolkit (ADT) and the availability
26 of stand-alone cross-development toolchains and other tools.
27 With the 2.1 Release of the Yocto Project, application development
28 has transitioned to within a more traditional SDK and extensible
29 SDK.
30 </para>
31
32 <para>
33 A standard SDK consists of the following:
34 <itemizedlist> 33 <itemizedlist>
35 <listitem><para><emphasis>Cross-Development Toolchain</emphasis>: 34 <listitem><para><emphasis>Cross-Development Toolchain</emphasis>:
36 This toolchain contains a compiler, debugger, and various 35 This toolchain contains a compiler, debugger, and various
@@ -46,19 +45,19 @@
46 preparing for SDK use. 45 preparing for SDK use.
47 </para></listitem> 46 </para></listitem>
48 </itemizedlist> 47 </itemizedlist>
49 You can use the standard SDK to independently develop and test code
50 that is destined to run on some target machine.
51 </para> 48 </para>
52 49
53 <para> 50 <para>
54 An extensible SDK consists of everything that the standard SDK has plus 51 Additionally an extensible SDK has tools that allow you to easily add
55 tools that allow you to easily add new applications and libraries to 52 new applications and libraries to an image, modify the source of an
56 an image, modify the source of an existing component, test changes on 53 existing component, test changes on the target hardware, and easily
57 the target hardware, and easily integrate an application into the 54 integrate an application into the
58 <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. 55 <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
59 </para> 56 </para>
60 57
61 <para> 58 <para>
59 You can use an SDK to independently develop and test code
60 that is destined to run on some target machine.
62 SDKs are completely self-contained. 61 SDKs are completely self-contained.
63 The binaries are linked against their own copy of 62 The binaries are linked against their own copy of
64 <filename>libc</filename>, which results in no dependencies 63 <filename>libc</filename>, which results in no dependencies
@@ -73,7 +72,7 @@
73 72
74 <para> 73 <para>
75 Another feature for the SDKs is that only one set of cross-compiler 74 Another feature for the SDKs is that only one set of cross-compiler
76 toolchain binaries are produced per architecture. 75 toolchain binaries are produced for any given architecture.
77 This feature takes advantage of the fact that the target hardware can 76 This feature takes advantage of the fact that the target hardware can
78 be passed to <filename>gcc</filename> as a set of compiler options. 77 be passed to <filename>gcc</filename> as a set of compiler options.
79 Those options are set up by the environment script and contained in 78 Those options are set up by the environment script and contained in
@@ -98,6 +97,8 @@
98 configuration and extensions, 97 configuration and extensions,
99 which allows you to cross-develop on the host machine for the 98 which allows you to cross-develop on the host machine for the
100 target hardware. 99 target hardware.
100 Additionally, the extensible SDK contains the
101 <filename>devtool</filename> functionality.
101 </para></listitem> 102 </para></listitem>
102 <listitem><para>The Quick EMUlator (QEMU), which lets you simulate 103 <listitem><para>The Quick EMUlator (QEMU), which lets you simulate
103 target hardware. 104 target hardware.
@@ -122,6 +123,85 @@
122 </itemizedlist> 123 </itemizedlist>
123 </para> 124 </para>
124 125
126 <para>
127 In summary, the extensible and standard SDK share many features.
128 However, the extensible SDK has powerful development tools to help you
129 more quickly develop applications.
130 Following is a table that summarizes the primary differences between
131 the standard and extensible SDK types when considering which to
132 build:
133 <informaltable frame='none'>
134 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
135 <colspec colname='c1' colwidth='1*'/>
136 <colspec colname='c2' colwidth='1*'/>
137 <colspec colname='c3' colwidth='1*'/>
138 <thead>
139 <row>
140 <entry align="left"><emphasis>Feature</emphasis></entry>
141 <entry align="left"><emphasis>Standard SDK</emphasis></entry>
142 <entry align="left"><emphasis>Extensible SDK</emphasis></entry>
143 </row>
144 </thead>
145 <tbody>
146 <row>
147 <entry align="left">Toolchain</entry>
148 <entry align="left">Yes</entry>
149 <entry align="left">Yes*</entry>
150 </row>
151 <row>
152 <entry align="left">Debugger</entry>
153 <entry align="left">Yes</entry>
154 <entry align="left">Yes*</entry>
155 </row>
156 <row>
157 <entry align="left">Size</entry>
158 <entry align="left">100+ MBytes</entry>
159 <entry align="left">1+ GBytes (or 300+ MBytes for minimal w/toolchain)</entry>
160 </row>
161 <row>
162 <entry align="left"><filename>devtool</filename></entry>
163 <entry align="left">No</entry>
164 <entry align="left">Yes</entry>
165 </row>
166 <row>
167 <entry align="left">Build Images</entry>
168 <entry align="left">No</entry>
169 <entry align="left">Yes</entry>
170 </row>
171 <row>
172 <entry align="left">Updateable</entry>
173 <entry align="left">No</entry>
174 <entry align="left">Yes</entry>
175 </row>
176 <row>
177 <entry align="left">Managed Sysroot**</entry>
178 <entry align="left">No</entry>
179 <entry align="left">Yes</entry>
180 </row>
181 <row>
182 <entry align="left">Installed Packages</entry>
183 <entry align="left">No***</entry>
184 <entry align="left">Yes****</entry>
185 </row>
186 <row>
187 <entry align="left">Construction</entry>
188 <entry align="left">Packages</entry>
189 <entry align="left">Shared State</entry>
190 </row>
191 </tbody>
192 </tgroup>
193 </informaltable>
194 <literallayout class='monospaced'>
195 * Extensible SDK will contain the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default.
196
197 ** Sysroot is managed through use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries.
198
199 *** Runtime package management can be added to the standard SDK but it is not supported by default.
200
201 **** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install.
202 </literallayout>
203 </para>
204
125 <section id='the-cross-development-toolchain'> 205 <section id='the-cross-development-toolchain'>
126 <title>The Cross-Development Toolchain</title> 206 <title>The Cross-Development Toolchain</title>
127 207
@@ -131,6 +211,8 @@
131 consists of a cross-compiler, cross-linker, and cross-debugger 211 consists of a cross-compiler, cross-linker, and cross-debugger
132 that are used to develop user-space applications for targeted 212 that are used to develop user-space applications for targeted
133 hardware. 213 hardware.
214 Additionally, for an extensible SDK, the toolchain also has
215 built-in <filename>devtool</filename> functionality.
134 This toolchain is created by running a toolchain installer script 216 This toolchain is created by running a toolchain installer script
135 or through a 217 or through a
136 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 218 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
@@ -258,7 +340,7 @@
258 For information on how to install the SDK, see the 340 For information on how to install the SDK, see the
259 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" 341 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
260 section.</para></listitem> 342 section.</para></listitem>
261 <listitem><para><emphasis>Download the Target Image:</emphasis> 343 <listitem><para><emphasis>Download or Build the Target Image:</emphasis>
262 The Yocto Project supports several target architectures 344 The Yocto Project supports several target architectures
263 and has many pre-built kernel images and root filesystem 345 and has many pre-built kernel images and root filesystem
264 images.</para> 346 images.</para>
diff --git a/documentation/sdk-manual/sdk-manual.xml b/documentation/sdk-manual/sdk-manual.xml
index 39a8689195..66cd10d507 100644
--- a/documentation/sdk-manual/sdk-manual.xml
+++ b/documentation/sdk-manual/sdk-manual.xml
@@ -66,9 +66,11 @@
66 66
67 <xi:include href="sdk-intro.xml"/> 67 <xi:include href="sdk-intro.xml"/>
68 68
69 <xi:include href="sdk-extensible.xml"/>
70
69 <xi:include href="sdk-using.xml"/> 71 <xi:include href="sdk-using.xml"/>
70 72
71 <xi:include href="sdk-extensible.xml"/> 73 <xi:include href="sdk-working-projects.xml"/>
72 74
73 <xi:include href="sdk-appendix-obtain.xml"/> 75 <xi:include href="sdk-appendix-obtain.xml"/>
74 76
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
index dd11304319..44cb49c0c8 100644
--- a/documentation/sdk-manual/sdk-using.xml
+++ b/documentation/sdk-manual/sdk-using.xml
@@ -3,74 +3,82 @@
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > 3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4 4
5<chapter id='sdk-using-the-standard-sdk'> 5<chapter id='sdk-using-the-standard-sdk'>
6 6 <title>Using the Standard SDK</title>
7<title>Using the Standard SDK</title>
8
9<para>
10 This chapter describes the standard SDK and how to use it.
11 Information covers the pieces of the SDK, how to install it, and presents
12 several task-based procedures common for developing with a standard SDK.
13 <note>
14 The tasks you can perform using a standard SDK are also applicable
15 when you are using an extensible SDK.
16 For information on the differences when using an extensible SDK as
17 compared to a standard SDK, see the
18 "<link linkend='sdk-extensible'>Using the Extensible SDK</link>"
19 chapter.
20 </note>
21</para>
22
23<section id='sdk-standard-sdk-intro'>
24 <title>Why use the Standard SDK and What is in It?</title>
25 7
26 <para> 8 <para>
27 The Standard SDK provides a cross-development toolchain and libraries 9 This chapter describes the standard SDK and how to install it.
28 tailored to the contents of a specific image. 10 Information includes unique installation and setup aspects for the
29 You would use the Standard SDK if you want a more traditional toolchain 11 standard SDK.
30 experience. 12 <note>
13 For a side-by-side comparison of main features supported for a
14 standard SDK as compared to an extensible SDK, see the
15 "<link linkend='sdk-manual-intro'>Introduction</link>"
16 section.
17 </note>
31 </para> 18 </para>
32 19
33 <para> 20 <para>
34 The installed Standard SDK consists of several files and directories. 21 You can use a standard SDK to work on Makefile, Autotools, and
35 Basically, it contains an SDK environment setup script, some 22 Eclipse-based projects.
36 configuration files, and host and target root filesystems to support 23 See the
37 usage. 24 "<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>"
38 You can see the directory structure in the 25 chapter for more information.
39 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
40 section.
41 </para> 26 </para>
42</section>
43 27
44<section id='sdk-installing-the-sdk'> 28 <section id='sdk-standard-sdk-intro'>
45 <title>Installing the SDK</title> 29 <title>Why use the Standard SDK and What is in It?</title>
46 30
47 <para> 31 <para>
48 The first thing you need to do is install the SDK on your host 32 The Standard SDK provides a cross-development toolchain and
49 development machine by running the <filename>*.sh</filename> 33 libraries tailored to the contents of a specific image.
50 installation script. 34 You would use the Standard SDK if you want a more traditional
51 </para> 35 toolchain experience as compared to the extensible SDK, which
36 provides an internal build system and the
37 <filename>devtool</filename> functionality.
38 </para>
52 39
53 <para> 40 <para>
54 You can download a tarball installer, which includes the 41 The installed Standard SDK consists of several files and
55 pre-built toolchain, the <filename>runqemu</filename> 42 directories.
56 script, and support files from the appropriate directory under 43 Basically, it contains an SDK environment setup script, some
57 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. 44 configuration files, and host and target root filesystems to
58 Toolchains are available for 32-bit and 64-bit x86 development 45 support usage.
59 systems from the <filename>i686</filename> and 46 You can see the directory structure in the
60 <filename>x86_64</filename> directories, respectively. 47 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
61 The toolchains the Yocto Project provides are based off the 48 section.
62 <filename>core-image-sato</filename> image and contain 49 </para>
63 libraries appropriate for developing against that image. 50 </section>
64 Each type of development system supports five or more target
65 architectures.
66 </para>
67 51
68 <para> 52 <section id='sdk-installing-the-sdk'>
69 The names of the tarball installer scripts are such that a 53 <title>Installing the SDK</title>
70 string representing the host system appears first in the 54
71 filename and then is immediately followed by a string 55 <para>
72 representing the target architecture. 56 The first thing you need to do is install the SDK on your host
73 <literallayout class='monospaced'> 57 development machine by running the <filename>*.sh</filename>
58 installation script.
59 </para>
60
61 <para>
62 You can download a tarball installer, which includes the
63 pre-built toolchain, the <filename>runqemu</filename>
64 script, and support files from the appropriate directory under
65 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
66 Toolchains are available for 32-bit and 64-bit x86 development
67 systems from the <filename>i686</filename> and
68 <filename>x86_64</filename> directories, respectively.
69 The toolchains the Yocto Project provides are based off the
70 <filename>core-image-sato</filename> image and contain
71 libraries appropriate for developing against that image.
72 Each type of development system supports five or more target
73 architectures.
74 </para>
75
76 <para>
77 The names of the tarball installer scripts are such that a
78 string representing the host system appears first in the
79 filename and then is immediately followed by a string
80 representing the target architecture.
81 <literallayout class='monospaced'>
74 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh 82 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh
75 83
76 Where: 84 Where:
@@ -88,57 +96,58 @@
88 Yocto Project: 96 Yocto Project:
89 97
90 &DISTRO;, &DISTRO;+snapshot 98 &DISTRO;, &DISTRO;+snapshot
91 </literallayout> 99 </literallayout>
92 For example, the following toolchain installer is for a 64-bit 100 For example, the following toolchain installer is for a 64-bit
93 development host system and a i586-tuned target architecture 101 development host system and a i586-tuned target architecture
94 based off the SDK for <filename>core-image-sato</filename> and 102 based off the SDK for <filename>core-image-sato</filename> and
95 using the current &DISTRO; snapshot: 103 using the current &DISTRO; snapshot:
96 <literallayout class='monospaced'> 104 <literallayout class='monospaced'>
97 poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh 105 poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
98 </literallayout> 106 </literallayout>
99 <note> 107 <note>
100 As an alternative to downloading an SDK, you can build the toolchain 108 As an alternative to downloading an SDK, you can build the
101 installer. 109 toolchain installer.
102 For information on building the installer, see the 110 For information on building the installer, see the
103 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" 111 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
104 section. 112 section.
105 Another helpful resource for building an installer is the 113 Another helpful resource for building an installer is the
106 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink> 114 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
107 wiki page. 115 wiki page.
108 This wiki page focuses on development when using the Eclipse IDE. 116 This wiki page focuses on development when using the Eclipse
109 </note> 117 IDE.
110 </para> 118 </note>
119 </para>
111 120
112 <para> 121 <para>
113 The SDK and toolchains are self-contained and by default are installed 122 The SDK and toolchains are self-contained and by default are
114 into <filename>/opt/poky</filename>. 123 installed into <filename>/opt/poky</filename>.
115 However, when you run the SDK installer, you can choose an 124 However, when you run the SDK installer, you can choose an
116 installation directory. 125 installation directory.
117 <note> 126 <note>
118 You must change the permissions on the toolchain 127 You must change the permissions on the toolchain
119 installer script so that it is executable: 128 installer script so that it is executable:
120 <literallayout class='monospaced'> 129 <literallayout class='monospaced'>
121 $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh 130 $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
122 </literallayout> 131 </literallayout>
123 </note> 132 </note>
124 </para> 133 </para>
125 134
126 <para> 135 <para>
127 The following command shows how to run the installer given a 136 The following command shows how to run the installer given a
128 toolchain tarball for a 64-bit x86 development host system and 137 toolchain tarball for a 64-bit x86 development host system and
129 a 32-bit x86 target architecture. 138 a 32-bit x86 target architecture.
130 The example assumes the toolchain installer is located in 139 The example assumes the toolchain installer is located in
131 <filename>~/Downloads/</filename>. 140 <filename>~/Downloads/</filename>.
132 <note> 141 <note>
133 If you do not have write permissions for the directory 142 If you do not have write permissions for the directory
134 into which you are installing the SDK, the installer 143 into which you are installing the SDK, the installer
135 notifies you and exits. 144 notifies you and exits.
136 Be sure you have write permissions in the directory and 145 Be sure you have write permissions in the directory and
137 run the installer again. 146 run the installer again.
138 </note> 147 </note>
139 <literallayout class='monospaced'> 148 <literallayout class='monospaced'>
140 $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh 149 $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
141 Poky (Yocto Project Reference Distro) SDK installer version 2.0 150 Poky (Yocto Project Reference Distro) SDK installer version &DISTRO;
142 =============================================================== 151 ===============================================================
143 Enter target directory for SDK (default: /opt/poky/&DISTRO;): 152 Enter target directory for SDK (default: /opt/poky/&DISTRO;):
144 You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed[Y/n]? Y 153 You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed[Y/n]? Y
@@ -147,1337 +156,49 @@
147 SDK has been successfully set up and is ready to be used. 156 SDK has been successfully set up and is ready to be used.
148 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. 157 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
149 $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux 158 $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
150 </literallayout>
151 </para>
152
153 <para>
154 Again, reference the
155 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
156 section for more details on the resulting directory structure of
157 the installed SDK.
158 </para>
159</section>
160
161<section id='sdk-running-the-sdk-environment-setup-script'>
162 <title>Running the SDK Environment Setup Script</title>
163
164 <para>
165 Once you have the SDK installed, you must run the SDK environment
166 setup script before you can actually use it.
167 This setup script resides in the directory you chose when you installed
168 the SDK.
169 For information on where this setup script can reside, see the
170 "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>"
171 Appendix.
172 </para>
173
174 <para>
175 Before running the script, be sure it is the one that matches the
176 architecture for which you are developing.
177 Environment setup scripts begin with the string
178 "<filename>environment-setup</filename>" and include as part of their
179 name the tuned target architecture.
180 For example, the command to source a setup script for an IA-based
181 target machine using i586 tuning and located in the default SDK
182 installation directory is as follows:
183 <literallayout class='monospaced'>
184 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
185 </literallayout>
186 When you run the setup script, many environment variables are
187 defined:
188 <literallayout class='monospaced'>
189 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
190 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
191 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
192 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
193 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
194 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
195 <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
196 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
197 <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
198 <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols
199 <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
200 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
201 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
202 <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
203 <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
204 <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
205 <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools
206 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
207 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
208 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
209 <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
210 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags
211 </literallayout>
212 </para>
213</section>
214
215<section id='autotools-based-projects'>
216 <title>Autotools-Based Projects</title>
217
218 <para>
219 Once you have a suitable cross-toolchain installed, it is very easy to
220 develop a project outside of the OpenEmbedded build system.
221 This section presents a simple "Helloworld" example that shows how
222 to set up, compile, and run the project.
223 </para>
224
225 <section id='creating-and-running-a-project-based-on-gnu-autotools'>
226 <title>Creating and Running a Project Based on GNU Autotools</title>
227
228 <para>
229 Follow these steps to create a simple Autotools-based project:
230 <orderedlist>
231 <listitem><para><emphasis>Create your directory:</emphasis>
232 Create a clean directory for your project and then make
233 that directory your working location:
234 <literallayout class='monospaced'>
235 $ mkdir $HOME/helloworld
236 $ cd $HOME/helloworld
237 </literallayout></para></listitem>
238 <listitem><para><emphasis>Populate the directory:</emphasis>
239 Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
240 and <filename>configure.ac</filename> files as follows:
241 <itemizedlist>
242 <listitem><para>For <filename>hello.c</filename>, include
243 these lines:
244 <literallayout class='monospaced'>
245 #include &lt;stdio.h&gt;
246
247 main()
248 {
249 printf("Hello World!\n");
250 }
251 </literallayout></para></listitem>
252 <listitem><para>For <filename>Makefile.am</filename>,
253 include these lines:
254 <literallayout class='monospaced'>
255 bin_PROGRAMS = hello
256 hello_SOURCES = hello.c
257 </literallayout></para></listitem>
258 <listitem><para>For <filename>configure.in</filename>,
259 include these lines:
260 <literallayout class='monospaced'>
261 AC_INIT(hello,0.1)
262 AM_INIT_AUTOMAKE([foreign])
263 AC_PROG_CC
264 AC_PROG_INSTALL
265 AC_OUTPUT(Makefile)
266 </literallayout></para></listitem>
267 </itemizedlist></para></listitem>
268 <listitem><para><emphasis>Source the cross-toolchain
269 environment setup file:</emphasis>
270 As described earlier in the manual, installing the
271 cross-toolchain creates a cross-toolchain
272 environment setup script in the directory that the SDK
273 was installed.
274 Before you can use the tools to develop your project,
275 you must source this setup script.
276 The script begins with the string "environment-setup" and
277 contains the machine architecture, which is followed by the
278 string "poky-linux".
279 Here is an example that sources a script from the
280 default SDK installation directory that uses the
281 32-bit Intel x86 Architecture and the
282 &DISTRO_NAME; Yocto Project release:
283 <literallayout class='monospaced'>
284 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
285 </literallayout></para></listitem>
286 <listitem><para><emphasis>Generate the local aclocal.m4
287 files and create the configure script:</emphasis>
288 The following GNU Autotools generate the local
289 <filename>aclocal.m4</filename> files and create the
290 configure script:
291 <literallayout class='monospaced'>
292 $ aclocal
293 $ autoconf
294 </literallayout></para></listitem>
295 <listitem><para><emphasis>Generate files needed by GNU
296 coding standards:</emphasis>
297 GNU coding standards require certain files in order for the
298 project to be compliant.
299 This command creates those files:
300 <literallayout class='monospaced'>
301 $ touch NEWS README AUTHORS ChangeLog
302 </literallayout></para></listitem>
303 <listitem><para><emphasis>Generate the configure
304 file:</emphasis>
305 This command generates the <filename>configure</filename>:
306 <literallayout class='monospaced'>
307 $ automake -a
308 </literallayout></para></listitem>
309 <listitem><para><emphasis>Cross-compile the project:</emphasis>
310 This command compiles the project using the cross-compiler.
311 The
312 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
313 environment variable provides the minimal arguments for
314 GNU configure:
315 <literallayout class='monospaced'>
316 $ ./configure ${CONFIGURE_FLAGS}
317 </literallayout></para></listitem>
318 <listitem><para><emphasis>Make and install the project:</emphasis>
319 These two commands generate and install the project into the
320 destination directory:
321 <literallayout class='monospaced'>
322 $ make
323 $ make install DESTDIR=./tmp
324 </literallayout></para></listitem>
325 <listitem><para><emphasis>Verify the installation:</emphasis>
326 This command is a simple way to verify the installation
327 of your project.
328 Running the command prints the architecture on which
329 the binary file can run.
330 This architecture should be the same architecture that
331 the installed cross-toolchain supports.
332 <literallayout class='monospaced'>
333 $ file ./tmp/usr/local/bin/hello
334 </literallayout></para></listitem>
335 <listitem><para><emphasis>Execute your project:</emphasis>
336 To execute the project in the shell, simply enter the name.
337 You could also copy the binary to the actual target hardware
338 and run the project there as well:
339 <literallayout class='monospaced'>
340 $ ./hello
341 </literallayout>
342 As expected, the project displays the "Hello World!" message.
343 </para></listitem>
344 </orderedlist>
345 </para>
346 </section>
347
348 <section id='passing-host-options'>
349 <title>Passing Host Options</title>
350
351 <para>
352 For an Autotools-based project, you can use the cross-toolchain by just
353 passing the appropriate host option to <filename>configure.sh</filename>.
354 The host option you use is derived from the name of the environment setup
355 script found in the directory in which you installed the cross-toolchain.
356 For example, the host option for an ARM-based target that uses the GNU EABI
357 is <filename>armv5te-poky-linux-gnueabi</filename>.
358 You will notice that the name of the script is
359 <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
360 Thus, the following command works to update your project and
361 rebuild it using the appropriate cross-toolchain tools:
362 <literallayout class='monospaced'>
363 $ ./configure --host=armv5te-poky-linux-gnueabi \
364 --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
365 </literallayout> 159 </literallayout>
366 <note>
367 If the <filename>configure</filename> script results in problems recognizing the
368 <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option,
369 regenerate the script to enable the support by doing the following and then
370 run the script again:
371 <literallayout class='monospaced'>
372 $ libtoolize --automake
373 $ aclocal -I ${OECORE_TARGET_SYSROOT}/usr/share/aclocal \
374 [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
375 $ autoconf
376 $ autoheader
377 $ automake -a
378 </literallayout>
379 </note>
380 </para> 160 </para>
381 </section>
382</section>
383
384<section id='makefile-based-projects'>
385 <title>Makefile-Based Projects</title>
386
387 <para>
388 For Makefile-based projects, the cross-toolchain environment variables
389 established by running the cross-toolchain environment setup script
390 are subject to general <filename>make</filename> rules.
391 </para>
392
393 <para>
394 To illustrate this, consider the following four cross-toolchain
395 environment variables:
396 <literallayout class='monospaced'>
397 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
398 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
399 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
400 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
401 </literallayout>
402 Now, consider the following three cases:
403 <itemizedlist>
404 <listitem><para><emphasis>Case 1 - No Variables Set in the <filename>Makefile</filename>:</emphasis>
405 Because these variables are not specifically set in the
406 <filename>Makefile</filename>, the variables retain their
407 values based on the environment.
408 </para></listitem>
409 <listitem><para><emphasis>Case 2 - Variables Set in the <filename>Makefile</filename>:</emphasis>
410 Specifically setting variables in the
411 <filename>Makefile</filename> during the build results in the
412 environment settings of the variables being overwritten.
413 </para></listitem>
414 <listitem><para><emphasis>Case 3 - Variables Set when the <filename>Makefile</filename> is Executed from the Command Line:</emphasis>
415 Executing the <filename>Makefile</filename> from the command
416 line results in the variables being overwritten with
417 command-line content regardless of what is being set in the
418 <filename>Makefile</filename>.
419 In this case, environment variables are not considered unless
420 you use the "-e" flag during the build:
421 <literallayout class='monospaced'>
422 $ make -e <replaceable>file</replaceable>
423 </literallayout>
424 If you use this flag, then the environment values of the
425 variables override any variables specifically set in the
426 <filename>Makefile</filename>.
427 </para></listitem>
428 </itemizedlist>
429 <note>
430 For the list of variables set up by the cross-toolchain environment
431 setup script, see the
432 "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
433 section.
434 </note>
435 </para>
436</section>
437
438<section id='sdk-developing-applications-using-eclipse'>
439 <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title>
440
441 <para>
442 If you are familiar with the popular Eclipse IDE, you can use an
443 Eclipse Yocto Plug-in to allow you to develop, deploy, and test your
444 application all from within Eclipse.
445 This section describes general workflow using the SDK and Eclipse
446 and how to configure and set up Eclipse.
447 </para>
448
449 <section id='workflow-using-eclipse'>
450
451 <title>Workflow Using <trademark class='trade'>Eclipse</trademark></title>
452 161
453 <para> 162 <para>
454 The following figure and supporting list summarize the application 163 Again, reference the
455 development general workflow that employs both the SDK Eclipse. 164 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
456 </para> 165 section for more details on the resulting directory structure of
457 166 the installed SDK.
458 <para>
459 <imagedata fileref="figures/sdk-eclipse-dev-flow.png"
460 width="7in" depth="7in" align="center" scale="100" />
461 </para>
462
463 <para>
464 <orderedlist>
465 <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>:
466 See
467 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
468 and
469 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both
470 in the Yocto Project Reference Manual for requirements.
471 In particular, be sure your host system has the
472 <filename>xterm</filename> package installed.
473 </para></listitem>
474 <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>:
475 You must have a target kernel image that has been built using the OpenEmbedded
476 build system.</para>
477 <para>Depending on whether the Yocto Project has a pre-built image that matches your target
478 architecture and where you are going to run the image while you develop your application
479 (QEMU or real hardware), the area from which you get the image differs.
480 <itemizedlist>
481 <listitem><para>Download the image from
482 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
483 if your target architecture is supported and you are going to develop
484 and test your application on actual hardware.</para></listitem>
485 <listitem><para>Download the image from
486 <ulink url='&YOCTO_QEMU_DL_URL;'>
487 <filename>machines/qemu</filename></ulink> if your target architecture is supported
488 and you are going to develop and test your application using the QEMU
489 emulator.</para></listitem>
490 <listitem><para>Build your image if you cannot find a pre-built image that matches
491 your target architecture.
492 If your target architecture is similar to a supported architecture, you can
493 modify the kernel image before you build it.
494 See the
495 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
496 section in the Yocto Project Development
497 manual for an example.
498 </para></listitem>
499 </itemizedlist>
500 </para></listitem>
501 <listitem><para><emphasis>Install the SDK</emphasis>:
502 The SDK provides a target-specific cross-development toolchain, the root filesystem,
503 the QEMU emulator, and other tools that can help you develop your application.
504 For information on how to install the SDK, see the
505 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
506 section.
507 </para></listitem>
508 <listitem><para><emphasis>
509 Secure the target root filesystem
510 and the Cross-development toolchain</emphasis>:
511 You need to find and download the appropriate root
512 filesystem and the cross-development toolchain.</para>
513 <para>You can find the tarballs for the root filesystem in
514 the same area used for the kernel image.
515 Depending on the type of image you are running, the root
516 filesystem you need differs.
517 For example, if you are developing an application that
518 runs on an image that supports Sato, you need to get a
519 root filesystem that supports Sato.</para>
520 <para>You can find the cross-development toolchains at
521 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
522 Be sure to get the correct toolchain for your development host and your
523 target architecture.
524 See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>"
525 section for information and the
526 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
527 section for installation information.
528 <note>
529 As an alternative to downloading an SDK, you can build
530 the toolchain installer.
531 For information on building the installer, see the
532 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
533 section.
534 Another helpful resource for building an installer is
535 the
536 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
537 wiki page.
538 </note>
539 </para></listitem>
540 <listitem><para><emphasis>Create and build your application</emphasis>:
541 At this point, you need to have source files for your application.
542 Once you have the files, you can use the Eclipse IDE to import them and build the
543 project.
544 If you are not using Eclipse, you need to use the cross-development tools you have
545 installed to create the image.</para></listitem>
546 <listitem><para>
547 <emphasis>Deploy the image with the application</emphasis>:
548 Using the Eclipse IDE, you can deploy your image to the
549 hardware or to QEMU through the project's preferences.
550 You can also use Eclipse to load and test your image under
551 QEMU.
552 See the
553 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
554 chapter in the Yocto Project Development Manual
555 for information on using QEMU.
556 </para></listitem>
557 <listitem><para><emphasis>Test and debug the application</emphasis>:
558 Once your application is deployed, you need to test it.
559 Within the Eclipse IDE, you can use the debugging
560 environment along with supported performance enhancing
561 <ulink url='http://www.eclipse.org/linuxtools/'>Linux Tools</ulink>.
562 </para></listitem>
563 </orderedlist>
564 </para> 167 </para>
565 </section> 168 </section>
566 169
567 <section id='adt-eclipse'> 170 <section id='sdk-running-the-sdk-environment-setup-script'>
568 <title>Working Within Eclipse</title> 171 <title>Running the SDK Environment Setup Script</title>
569 172
570 <para> 173 <para>
571 The Eclipse IDE is a popular development environment and it fully 174 Once you have the SDK installed, you must run the SDK environment
572 supports development using the Yocto Project. 175 setup script before you can actually use it.
176 This setup script resides in the directory you chose when you
177 installed the SDK.
178 For information on where this setup script can reside, see the
179 "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>"
180 Appendix.
573 </para> 181 </para>
574 182
575 <para> 183 <para>
576 When you install and configure the Eclipse Yocto Project Plug-in 184 Before running the script, be sure it is the one that matches the
577 into the Eclipse IDE, you maximize your Yocto Project experience. 185 architecture for which you are developing.
578 Installing and configuring the Plug-in results in an environment 186 Environment setup scripts begin with the string
579 that has extensions specifically designed to let you more easily 187 "<filename>environment-setup</filename>" and include as part of
580 develop software. 188 their name the tuned target architecture.
581 These extensions allow for cross-compilation, deployment, and 189 For example, the command to source a setup script for an IA-based
582 execution of your output into a QEMU emulation session as well as 190 target machine using i586 tuning and located in the default SDK
583 actual target hardware. 191 installation directory is as follows:
584 You can also perform cross-debugging and profiling. 192 <literallayout class='monospaced'>
585 The environment also supports performance enhancing 193 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
586 <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink> that 194 </literallayout>
587 allow you to perform remote profiling, tracing, collection of 195 When you run the setup script, the same environment variables are
588 power data, collection of latency data, and collection of 196 defined as are when you run the setup script for an extensible SDK.
589 performance data. 197 See the
590 <note> 198 "<link linkend='sdk-running-the-extensible-sdk-environment-setup-script'>Running the Extensible SDK Environment Setup Script</link>"
591 This release of the Yocto Project supports both the Neon 199 section for more information.
592 and Mars versions of the Eclipse IDE.
593 This section provides information on how to use the Neon
594 release with the Yocto Project.
595 For information on how to use the Mars version of Eclipse
596 with the Yocto Project, see
597 "<link linkend='sdk-appendix-mars'>Appendix C</link>.
598 </note>
599 </para> 200 </para>
600
601 <section id='neon-setting-up-the-eclipse-ide'>
602 <title>Setting Up the Neon Version of the Eclipse IDE</title>
603
604 <para>
605 To develop within the Eclipse IDE, you need to do the following:
606 <orderedlist>
607 <listitem><para>Install the Neon version of the Eclipse
608 IDE.</para></listitem>
609 <listitem><para>Configure the Eclipse IDE.
610 </para></listitem>
611 <listitem><para>Install the Eclipse Yocto Plug-in.
612 </para></listitem>
613 <listitem><para>Configure the Eclipse Yocto Plug-in.
614 </para></listitem>
615 </orderedlist>
616 <note>
617 Do not install Eclipse from your distribution's package
618 repository.
619 Be sure to install Eclipse from the official Eclipse
620 download site as directed in the next section.
621 </note>
622 </para>
623
624 <section id='neon-installing-eclipse-ide'>
625 <title>Installing the Neon Eclipse IDE</title>
626
627 <para>
628 Follow these steps to locate, install, and configure
629 Neon Eclipse:
630 <orderedlist>
631 <listitem><para>
632 <emphasis>Locate the Neon Download:</emphasis>
633 Open a browser and go to
634 <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/neon/</ulink>.
635 </para></listitem>
636 <listitem><para>
637 <emphasis>Download the Tarball:</emphasis>
638 Click through the "Download" buttons to
639 download the file.
640 </para></listitem>
641 <listitem><para>
642 <emphasis>Unpack the Tarball:</emphasis>
643 Move to a clean directory and unpack the tarball.
644 Here is an example:
645 <literallayout class='monospaced'>
646 $ cd ~
647 $ tar -xzvf ~/Downloads/eclipse-inst-linux64.tar.gz
648 </literallayout>
649 Everything unpacks into a folder named
650 "eclipse-installer".
651 </para></listitem>
652 <listitem><para>
653 <emphasis>Launch the Installer:</emphasis>
654 Use the following commands to launch the installer:
655 <literallayout class='monospaced'>
656 $ cd ~/eclipse-installer
657 $ ./eclipse-inst
658 </literallayout>
659 </para></listitem>
660 <listitem><para>
661 <emphasis>Select Your IDE:</emphasis>
662 From the list, select the "Eclipse IDE for
663 C/C++ Developers".
664 </para></listitem>
665 <listitem><para>
666 <emphasis>Install the Software:</emphasis>
667 Accept the default "cpp-neon" directory and click
668 "Install".
669 Accept any license agreements and approve any
670 certificates.
671 </para></listitem>
672 <listitem><para>
673 <emphasis>Launch Neon:</emphasis>
674 Click the "Launch" button and accept the default
675 "workspace".
676 </para></listitem>
677 </orderedlist>
678 </para>
679 </section>
680
681 <section id='neon-configuring-the-mars-eclipse-ide'>
682 <title>Configuring the Neon Eclipse IDE</title>
683
684 <para>
685 Follow these steps to configure the Neon Eclipse IDE.
686 <note>
687 Depending on how you installed Eclipse and what you have
688 already done, some of the options will not appear.
689 If you cannot find an option as directed by the manual,
690 it has already been installed.
691 </note>
692 <orderedlist>
693 <listitem><para>Be sure Eclipse is running and
694 you are in your workbench.
695 </para></listitem>
696 <listitem><para>Select "Install New Software" from
697 the "Help" pull-down menu.
698 </para></listitem>
699 <listitem><para>Select
700 "Neon - http://download.eclipse.org/releases/neon"
701 from the "Work with:" pull-down menu.
702 </para></listitem>
703 <listitem><para>Expand the box next to
704 "Linux Tools" and select the following:
705 <literallayout class='monospaced'>
706 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
707 TM Terminal
708 </literallayout>
709 </para></listitem>
710 <listitem><para>Expand the box next to "Mobile and
711 Device Development" and select the following
712 boxes:
713 <literallayout class='monospaced'>
714 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
715 Remote System Explorer User Actions
716 TM Terminal
717 TCF Remote System Explorer add-in
718 TCF Target Explorer
719 </literallayout>
720 </para></listitem>
721 <listitem><para>Expand the box next to
722 "Programming Languages" and select the
723 following box:
724 <literallayout class='monospaced'>
725 C/C++ Development Tools SDK
726 </literallayout>
727 </para></listitem>
728 <listitem><para>
729 Complete the installation by clicking through
730 appropriate "Next" and "Finish" buttons.
731 </para></listitem>
732 </orderedlist>
733 </para>
734 </section>
735
736 <section id='neon-installing-the-eclipse-yocto-plug-in'>
737 <title>Installing or Accessing the Neon Eclipse Yocto Plug-in</title>
738
739 <para>
740 You can install the Eclipse Yocto Plug-in into the Eclipse
741 IDE one of two ways: use the Yocto Project's Eclipse
742 Update site to install the pre-built plug-in or build and
743 install the plug-in from the latest source code.
744 </para>
745
746 <section id='neon-new-software'>
747 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
748
749 <para>
750 To install the Neon Eclipse Yocto Plug-in from the
751 update site, follow these steps:
752 <orderedlist>
753 <listitem><para>Start up the Eclipse IDE.
754 </para></listitem>
755 <listitem><para>In Eclipse, select "Install New
756 Software" from the "Help" menu.
757 </para></listitem>
758 <listitem><para>Click "Add..." in the "Work with:"
759 area.
760 </para></listitem>
761 <listitem><para>Enter
762 <filename>&ECLIPSE_DL_PLUGIN_URL;/neon</filename>
763 in the URL field and provide a meaningful name
764 in the "Name" field.
765 </para></listitem>
766 <listitem><para>Click "OK" to have the entry added
767 to the "Work with:" drop-down list.
768 </para></listitem>
769 <listitem><para>Select the entry for the plug-in
770 from the "Work with:" drop-down list.
771 </para></listitem>
772 <listitem><para>Check the boxes next to the following:
773 <literallayout class='monospaced'>
774 Yocto Project SDK Plug-in
775 Yocto Project Documentation plug-in
776 </literallayout>
777 </para></listitem>
778 <listitem><para>Complete the remaining software
779 installation steps and then restart the Eclipse
780 IDE to finish the installation of the plug-in.
781 <note>
782 You can click "OK" when prompted about
783 installing software that contains unsigned
784 content.
785 </note>
786 </para></listitem>
787 </orderedlist>
788 </para>
789 </section>
790
791 <section id='neon-zip-file-method'>
792 <title>Installing the Plug-in Using the Latest Source Code</title>
793
794 <para>
795 To install the Neon Eclipse Yocto Plug-in from the
796 latest source code, follow these steps:
797 <orderedlist>
798 <listitem><para>Be sure your development system
799 has JDK 1.8+
800 </para></listitem>
801 <listitem><para>install X11-related packages:
802 <literallayout class='monospaced'>
803 $ sudo apt-get install xauth
804 </literallayout>
805 </para></listitem>
806 <listitem><para>In a new terminal shell, create a
807 Git repository with:
808 <literallayout class='monospaced'>
809 $ cd ~
810 $ git clone git://git.yoctoproject.org/eclipse-poky
811 </literallayout>
812 </para></listitem>
813 <listitem><para>Use Git to create the correct
814 tag:
815 <literallayout class='monospaced'>
816 $ cd ~/eclipse-poky
817 $ git checkout neon/yocto-&DISTRO;
818 </literallayout>
819 This creates a local tag named
820 <filename>neon/yocto-&DISTRO;</filename>
821 based on the branch
822 <filename>origin/neon-master</filename>.
823 You are put into a detached HEAD state, which
824 is fine since you are only going to be building
825 and not developing.
826 </para></listitem>
827 <listitem><para>Change to the
828 <filename>scripts</filename>
829 directory within the Git repository:
830 <literallayout class='monospaced'>
831 $ cd scripts
832 </literallayout>
833 </para></listitem>
834 <listitem><para>Set up the local build environment
835 by running the setup script:
836 <literallayout class='monospaced'>
837 $ ./setup.sh
838 </literallayout>
839 When the script finishes execution,
840 it prompts you with instructions on how to run
841 the <filename>build.sh</filename> script, which
842 is also in the <filename>scripts</filename>
843 directory of the Git repository created
844 earlier.
845 </para></listitem>
846 <listitem><para>
847 Run the <filename>build.sh</filename>
848 script as directed.
849 Be sure to provide the tag name, documentation
850 branch, and a release name.</para>
851 <para>
852 Following is an example:
853 <literallayout class='monospaced'>
854 $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l neon/yocto-&DISTRO; master yocto-&DISTRO; 2>&amp;1 | tee build.log
855 </literallayout>
856 The previous example command adds the tag you
857 need for
858 <filename>mars/yocto-&DISTRO;</filename>
859 to <filename>HEAD</filename>, then tells the
860 build script to use the local (-l) Git checkout
861 for the build.
862 After running the script, the file
863 <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>
864 is in the current directory.
865 </para></listitem>
866 <listitem><para>If necessary, start the Eclipse IDE
867 and be sure you are in the Workbench.
868 </para></listitem>
869 <listitem><para>Select "Install New Software" from
870 the "Help" pull-down menu.
871 </para></listitem>
872 <listitem><para>Click "Add".
873 </para></listitem>
874 <listitem><para>Provide anything you want in the
875 "Name" field.
876 </para></listitem>
877 <listitem><para>Click "Archive" and browse to the
878 ZIP file you built earlier.
879 This ZIP file should not be "unzipped", and must
880 be the <filename>*archive.zip</filename> file
881 created by running the
882 <filename>build.sh</filename> script.
883 </para></listitem>
884 <listitem><para>Click the "OK" button.
885 </para></listitem>
886 <listitem><para>Check the boxes that appear in
887 the installation window to install the
888 following:
889 <literallayout class='monospaced'>
890 Yocto Project SDK Plug-in
891 Yocto Project Documentation plug-in
892 </literallayout>
893 </para></listitem>
894 <listitem><para>Finish the installation by clicking
895 through the appropriate buttons.
896 You can click "OK" when prompted about
897 installing software that contains unsigned
898 content.
899 </para></listitem>
900 <listitem><para>Restart the Eclipse IDE if
901 necessary.
902 </para></listitem>
903 </orderedlist>
904 </para>
905
906 <para>
907 At this point you should be able to configure the
908 Eclipse Yocto Plug-in as described in the
909 "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"
910 section.
911 </para>
912 </section>
913 </section>
914
915 <section id='neon-configuring-the-eclipse-yocto-plug-in'>
916 <title>Configuring the Neon Eclipse Yocto Plug-in</title>
917
918 <para>
919 Configuring the Neon Eclipse Yocto Plug-in involves
920 setting the Cross Compiler options and the Target options.
921 The configurations you choose become the default settings
922 for all projects.
923 You do have opportunities to change them later when
924 you configure the project (see the following section).
925 </para>
926
927 <para>
928 To start, you need to do the following from within the
929 Eclipse IDE:
930 <itemizedlist>
931 <listitem><para>Choose "Preferences" from the
932 "Window" menu to display the Preferences Dialog.
933 </para></listitem>
934 <listitem><para>Click "Yocto Project SDK" to display
935 the configuration screen.
936 </para></listitem>
937 </itemizedlist>
938 The following sub-sections describe how to configure the
939 the plug-in.
940 <note>
941 Throughout the descriptions, a start-to-finish example for
942 preparing a QEMU image for use with Eclipse is referenced
943 as the "wiki" and is linked to the example on the
944 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
945 wiki page.
946 </note>
947 </para>
948
949 <section id='neon-configuring-the-cross-compiler-options'>
950 <title>Configuring the Cross-Compiler Options</title>
951
952 <para>
953 Cross Compiler options enable Eclipse to use your specific
954 cross compiler toolchain.
955 To configure these options, you must select
956 the type of toolchain, point to the toolchain, specify
957 the sysroot location, and select the target
958 architecture.
959 <itemizedlist>
960 <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
961 Choose between
962 <filename>Standalone pre-built toolchain</filename>
963 and
964 <filename>Build system derived toolchain</filename>
965 for Cross Compiler Options.
966 <itemizedlist>
967 <listitem><para><emphasis>
968 <filename>Standalone Pre-built Toolchain:</filename></emphasis>
969 Select this type when you are using
970 a stand-alone cross-toolchain.
971 For example, suppose you are an
972 application developer and do not
973 need to build a target image.
974 Instead, you just want to use an
975 architecture-specific toolchain on
976 an existing kernel and target root
977 filesystem.
978 In other words, you have downloaded
979 and installed a pre-built toolchain
980 for an existing image.
981 </para></listitem>
982 <listitem><para><emphasis>
983 <filename>Build System Derived Toolchain:</filename></emphasis>
984 Select this type if you built the
985 toolchain as part of the
986 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
987 When you select
988 <filename>Build system derived toolchain</filename>,
989 you are using the toolchain built and
990 bundled inside the Build Directory.
991 For example, suppose you created a
992 suitable image using the steps in the
993 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
994 In this situation, you would select the
995 <filename>Build system derived toolchain</filename>.
996 </para></listitem>
997 </itemizedlist>
998 </para></listitem>
999 <listitem><para><emphasis>Specify the Toolchain Root Location:</emphasis>
1000 If you are using a stand-alone pre-built
1001 toolchain, you should be pointing to where it is
1002 installed (e.g.
1003 <filename>/opt/poky/&DISTRO;</filename>).
1004 See the
1005 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
1006 section for information about how the SDK is
1007 installed.</para>
1008 <para>If you are using a build system derived
1009 toolchain, the path you provide for the
1010 <filename>Toolchain Root Location</filename>
1011 field is the
1012 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1013 from which you run the
1014 <filename>bitbake</filename> command (e.g
1015 <filename>/home/scottrif/poky/build</filename>).</para>
1016 <para>For more information, see the
1017 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
1018 section.
1019 </para></listitem>
1020 <listitem><para><emphasis>Specify Sysroot Location:</emphasis>
1021 This location is where the root filesystem for
1022 the target hardware resides.
1023 </para>
1024 <para>This location depends on where you
1025 separately extracted and installed the target
1026 filesystem.
1027 As an example, suppose you prepared an image
1028 using the steps in the
1029 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
1030 If so, the <filename>MY_QEMU_ROOTFS</filename>
1031 directory is found in the
1032 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1033 and you would browse to and select that directory
1034 (e.g. <filename>/home/scottrif/poky/build/MY_QEMU_ROOTFS</filename>).
1035 </para>
1036 <para>For more information on how to install the
1037 toolchain and on how to extract and install the
1038 sysroot filesystem, see the
1039 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
1040 section.
1041 </para></listitem>
1042 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
1043 The target architecture is the type of hardware
1044 you are going to use or emulate.
1045 Use the pull-down
1046 <filename>Target Architecture</filename> menu
1047 to make your selection.
1048 The pull-down menu should have the supported
1049 architectures.
1050 If the architecture you need is not listed in
1051 the menu, you will need to build the image.
1052 See the
1053 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
1054 section of the Yocto Project Quick Start for
1055 more information.
1056 You can also see the
1057 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
1058 </para></listitem>
1059 </itemizedlist>
1060 </para>
1061 </section>
1062
1063 <section id='neon-configuring-the-target-options'>
1064 <title>Configuring the Target Options</title>
1065
1066 <para>
1067 You can choose to emulate hardware using the QEMU
1068 emulator, or you can choose to run your image on actual
1069 hardware.
1070 <itemizedlist>
1071 <listitem><para><emphasis>QEMU:</emphasis>
1072 Select this option if you will be using the
1073 QEMU emulator.
1074 If you are using the emulator, you also need to
1075 locate the kernel and specify any custom
1076 options.</para>
1077 <para>If you selected the
1078 <filename>Build system derived toolchain</filename>,
1079 the target kernel you built will be located in
1080 the
1081 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1082 in
1083 <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
1084 directory.
1085 As an example, suppose you performed the steps in
1086 the
1087 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
1088 In this case, you specify your Build Directory path
1089 followed by the image (e.g.
1090 <filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).
1091 </para>
1092 <para>If you selected the standalone pre-built
1093 toolchain, the pre-built image you downloaded is
1094 located in the directory you specified when you
1095 downloaded the image.</para>
1096 <para>Most custom options are for advanced QEMU
1097 users to further customize their QEMU instance.
1098 These options are specified between paired
1099 angled brackets.
1100 Some options must be specified outside the
1101 brackets.
1102 In particular, the options
1103 <filename>serial</filename>,
1104 <filename>nographic</filename>, and
1105 <filename>kvm</filename> must all be outside the
1106 brackets.
1107 Use the <filename>man qemu</filename> command
1108 to get help on all the options and their use.
1109 The following is an example:
1110 <literallayout class='monospaced'>
1111 serial ‘&lt;-m 256 -full-screen&gt;’
1112 </literallayout></para>
1113 <para>
1114 Regardless of the mode, Sysroot is already
1115 defined as part of the Cross-Compiler Options
1116 configuration in the
1117 <filename>Sysroot Location:</filename> field.
1118 </para></listitem>
1119 <listitem><para><emphasis>External HW:</emphasis>
1120 Select this option if you will be using actual
1121 hardware.</para></listitem>
1122 </itemizedlist>
1123 </para>
1124
1125 <para>
1126 Click the "Apply" and "OK" to save your plug-in
1127 configurations.
1128 </para>
1129 </section>
1130 </section>
1131 </section>
1132
1133 <section id='neon-creating-the-project'>
1134 <title>Creating the Project</title>
1135
1136 <para>
1137 You can create two types of projects: Autotools-based, or
1138 Makefile-based.
1139 This section describes how to create Autotools-based projects
1140 from within the Eclipse IDE.
1141 For information on creating Makefile-based projects in a
1142 terminal window, see the
1143 "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
1144 section.
1145 <note>
1146 Do not use special characters in project names
1147 (e.g. spaces, underscores, etc.). Doing so can
1148 cause configuration to fail.
1149 </note>
1150 </para>
1151
1152 <para>
1153 To create a project based on a Yocto template and then display
1154 the source code, follow these steps:
1155 <orderedlist>
1156 <listitem><para>Select "C Project" from the "File -> New" menu.
1157 </para></listitem>
1158 <listitem><para>Expand <filename>Yocto Project SDK Autotools Project</filename>.
1159 </para></listitem>
1160 <listitem><para>Select <filename>Hello World ANSI C Autotools Projects</filename>.
1161 This is an Autotools-based project based on a Yocto
1162 template.
1163 </para></listitem>
1164 <listitem><para>Put a name in the <filename>Project name:</filename>
1165 field.
1166 Do not use hyphens as part of the name
1167 (e.g. <filename>hello</filename>).
1168 </para></listitem>
1169 <listitem><para>Click "Next".
1170 </para></listitem>
1171 <listitem><para>Add appropriate information in the various
1172 fields.
1173 </para></listitem>
1174 <listitem><para>Click "Finish".
1175 </para></listitem>
1176 <listitem><para>If the "open perspective" prompt appears,
1177 click "Yes" so that you in the C/C++ perspective.
1178 </para></listitem>
1179 <listitem><para>The left-hand navigation pane shows your
1180 project.
1181 You can display your source by double clicking the
1182 project's source file.
1183 </para></listitem>
1184 </orderedlist>
1185 </para>
1186 </section>
1187
1188 <section id='neon-configuring-the-cross-toolchains'>
1189 <title>Configuring the Cross-Toolchains</title>
1190
1191 <para>
1192 The earlier section,
1193 "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>",
1194 sets up the default project configurations.
1195 You can override these settings for a given project by following
1196 these steps:
1197 <orderedlist>
1198 <listitem><para>Select "Yocto Project Settings" from
1199 the "Project -> Properties" menu.
1200 This selection brings up the Yocto Project Settings
1201 Dialog and allows you to make changes specific to an
1202 individual project.</para>
1203 <para>By default, the Cross Compiler Options and Target
1204 Options for a project are inherited from settings you
1205 provided using the Preferences Dialog as described
1206 earlier in the
1207 "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" section.
1208 The Yocto Project Settings Dialog allows you to override
1209 those default settings for a given project.
1210 </para></listitem>
1211 <listitem><para>Make or verify your configurations for the
1212 project and click "OK".
1213 </para></listitem>
1214 <listitem><para>Right-click in the navigation pane and
1215 select "Reconfigure Project" from the pop-up menu.
1216 This selection reconfigures the project by running
1217 <filename>autogen.sh</filename> in the workspace for
1218 your project.
1219 The script also runs <filename>libtoolize</filename>,
1220 <filename>aclocal</filename>,
1221 <filename>autoconf</filename>,
1222 <filename>autoheader</filename>,
1223 <filename>automake --a</filename>, and
1224 <filename>./configure</filename>.
1225 Click on the "Console" tab beneath your source code to
1226 see the results of reconfiguring your project.
1227 </para></listitem>
1228 </orderedlist>
1229 </para>
1230 </section>
1231
1232 <section id='neon-building-the-project'>
1233 <title>Building the Project</title>
1234
1235 <para>
1236 To build the project select "Build All" from the
1237 "Project" menu.
1238 The console should update and you can note the cross-compiler
1239 you are using.
1240 <note>
1241 When building "Yocto Project SDK Autotools" projects, the
1242 Eclipse IDE might display error messages for
1243 Functions/Symbols/Types that cannot be "resolved", even when
1244 the related include file is listed at the project navigator and
1245 when the project is able to build.
1246 For these cases only, it is recommended to add a new linked
1247 folder to the appropriate sysroot.
1248 Use these steps to add the linked folder:
1249 <orderedlist>
1250 <listitem><para>
1251 Select the project.
1252 </para></listitem>
1253 <listitem><para>
1254 Select "Folder" from the
1255 <filename>File > New</filename> menu.
1256 </para></listitem>
1257 <listitem><para>
1258 In the "New Folder" Dialog, select "Link to alternate
1259 location (linked folder)".
1260 </para></listitem>
1261 <listitem><para>
1262 Click "Browse" to navigate to the include folder inside
1263 the same sysroot location selected in the Yocto Project
1264 configuration preferences.
1265 </para></listitem>
1266 <listitem><para>
1267 Click "OK".
1268 </para></listitem>
1269 <listitem><para>
1270 Click "Finish" to save the linked folder.
1271 </para></listitem>
1272 </orderedlist>
1273 </note>
1274 </para>
1275 </section>
1276
1277 <section id='neon-starting-qemu-in-user-space-nfs-mode'>
1278 <title>Starting QEMU in User-Space NFS Mode</title>
1279
1280 <para>
1281 To start the QEMU emulator from within Eclipse, follow these
1282 steps:
1283 <note>
1284 See the
1285 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
1286 chapter in the Yocto Project Development Manual
1287 for more information on using QEMU.
1288 </note>
1289 <orderedlist>
1290 <listitem><para>Expose and select "External Tools
1291 Configurations ..." from the "Run -> External Tools" menu.
1292 </para></listitem>
1293 <listitem><para>
1294 Locate and select your image in the navigation panel to
1295 the left (e.g. <filename>qemu_i586-poky-linux</filename>).
1296 </para></listitem>
1297 <listitem><para>
1298 Click "Run" to launch QEMU.
1299 <note>
1300 The host on which you are running QEMU must have
1301 the <filename>rpcbind</filename> utility running to be
1302 able to make RPC calls on a server on that machine.
1303 If QEMU does not invoke and you receive error messages
1304 involving <filename>rpcbind</filename>, follow the
1305 suggestions to get the service running.
1306 As an example, on a new Ubuntu 16.04 LTS installation,
1307 you must do the following in order to get QEMU to
1308 launch:
1309 <literallayout class='monospaced'>
1310 $ sudo apt-get install rpcbind
1311 </literallayout>
1312 After installing <filename>rpcbind</filename>, you
1313 need to edit the
1314 <filename>/etc/init.d/rpcbind</filename> file to
1315 include the following line:
1316 <literallayout class='monospaced'>
1317 OPTIONS="-i -w"
1318 </literallayout>
1319 After modifying the file, you need to start the
1320 service:
1321 <literallayout class='monospaced'>
1322 $ sudo service portmap restart
1323 </literallayout>
1324 </note>
1325 </para></listitem>
1326 <listitem><para>If needed, enter your host root password in
1327 the shell window at the prompt.
1328 This sets up a <filename>Tap 0</filename> connection
1329 needed for running in user-space NFS mode.
1330 </para></listitem>
1331 <listitem><para>Wait for QEMU to launch.
1332 </para></listitem>
1333 <listitem><para>Once QEMU launches, you can begin operating
1334 within that environment.
1335 One useful task at this point would be to determine the
1336 IP Address for the user-space NFS by using the
1337 <filename>ifconfig</filename> command.
1338 The IP address of the QEMU machine appears in the
1339 xterm window.
1340 You can use this address to help you see which particular
1341 IP address the instance of QEMU is using.
1342 </para></listitem>
1343 </orderedlist>
1344 </para>
1345 </section>
1346
1347 <section id='neon-deploying-and-debugging-the-application'>
1348 <title>Deploying and Debugging the Application</title>
1349
1350 <para>
1351 Once the QEMU emulator is running the image, you can deploy
1352 your application using the Eclipse IDE and then use
1353 the emulator to perform debugging.
1354 Follow these steps to deploy the application.
1355 <note>
1356 Currently, Eclipse does not support SSH port forwarding.
1357 Consequently, if you need to run or debug a remote
1358 application using the host display, you must create a
1359 tunneling connection from outside Eclipse and keep
1360 that connection alive during your work.
1361 For example, in a new terminal, run the following:
1362 <literallayout class='monospaced'>
1363 $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>
1364 </literallayout>
1365 Using the above form, here is an example:
1366 <literallayout class='monospaced'>
1367 $ ssh -XY root@192.168.7.2
1368 </literallayout>
1369 After running the command, add the command to be executed
1370 in Eclipse's run configuration before the application
1371 as follows:
1372 <literallayout class='monospaced'>
1373 export DISPLAY=:10.0
1374 </literallayout>
1375 Be sure to not destroy the connection during your QEMU
1376 session (i.e. do not
1377 exit out of or close that shell).
1378 </note>
1379 <orderedlist>
1380 <listitem><para>Select "Debug Configurations..." from the
1381 "Run" menu.</para></listitem>
1382 <listitem><para>In the left area, expand
1383 <filename>C/C++Remote Application</filename>.
1384 </para></listitem>
1385 <listitem><para>Locate your project and select it to bring
1386 up a new tabbed view in the Debug Configurations Dialog.
1387 </para></listitem>
1388 <listitem><para>Click on the "Debugger" tab to see the
1389 cross-tool debugger you are using.
1390 Be sure to change to the debugger perspective in Eclipse.
1391 </para></listitem>
1392 <listitem><para>Click on the "Main" tab.
1393 </para></listitem>
1394 <listitem><para>Create a new connection to the QEMU instance
1395 by clicking on "new".</para></listitem>
1396 <listitem><para>Select <filename>SSH</filename>, which means
1397 Secure Socket Shell and then click "OK".
1398 Optionally, you can select an TCF connection instead.
1399 </para></listitem>
1400 <listitem><para>Clear out the "Connection name" field and
1401 enter any name you want for the connection.
1402 </para></listitem>
1403 <listitem><para>Put the IP address for the connection in
1404 the "Host" field.
1405 For QEMU, the default is <filename>192.168.7.2</filename>.
1406 However, if a previous QEMU session did not exit
1407 cleanly, the IP address increments (e.g.
1408 <filename>192.168.7.3</filename>).
1409 <note>
1410 You can find the IP address for the current QEMU
1411 session by looking in the xterm that opens when
1412 you launch QEMU.
1413 </note>
1414 </para></listitem>
1415 <listitem><para>Enter <filename>root</filename>, which
1416 is the default for QEMU, for the "User" field.
1417 Be sure to leave the password field empty.
1418 </para></listitem>
1419 <listitem><para>Click "Finish" to close the
1420 New Connections Dialog.
1421 </para></listitem>
1422 <listitem><para>If necessary, use the drop-down menu now in the
1423 "Connection" field and pick the IP Address you entered.
1424 </para></listitem>
1425 <listitem><para>Assuming you are connecting as the root
1426 user, which is the default for QEMU x86-64 SDK images
1427 provided by the Yocto Project, in the "Remote Absolute
1428 File Path for C/C++ Application" field, browse to
1429 <filename>/home/root/</filename><replaceable>ProjectName</replaceable>
1430 (e.g. <filename>/home/root/hello</filename>).
1431 You could also browse to any other path you have write
1432 access to on the target such as
1433 <filename>/usr/bin</filename>.
1434 This location is where your application will be located
1435 on the QEMU system.
1436 If you fail to browse to and specify an appropriate
1437 location, QEMU will not understand what to remotely
1438 launch.
1439 Eclipse is helpful in that it auto fills your
1440 application name for you assuming you browsed to a
1441 directory.
1442 <note>
1443 If you are prompted to provide a username and to
1444 optionally set a password, be sure you provide
1445 "root" as the username and you leave the password
1446 field blank.
1447 </note>
1448 </para></listitem>
1449 <listitem><para>
1450 Be sure you change to the "Debug" perspective in
1451 Eclipse.
1452 </para></listitem>
1453 <listitem><para>Click "Debug"
1454 </para></listitem>
1455 <listitem><para>Accept the debug perspective.
1456 </para></listitem>
1457 </orderedlist>
1458 </para>
1459 </section>
1460
1461 <section id='neon-using-Linuxtools'>
1462 <title>Using Linuxtools</title>
1463
1464 <para>
1465 As mentioned earlier in the manual, performance tools exist
1466 (Linuxtools) that enhance your development experience.
1467 These tools are aids in developing and debugging applications and
1468 images.
1469 You can run these tools from within the Eclipse IDE through the
1470 "Linuxtools" menu.
1471 </para>
1472
1473 <para>
1474 For information on how to configure and use these tools, see
1475 <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
1476 </para>
1477 </section>
1478 </section> 201 </section>
1479</section>
1480
1481</chapter> 202</chapter>
1482<!-- 203<!--
1483vim: expandtab tw=80 ts=4 204vim: expandtab tw=80 ts=4
diff --git a/documentation/sdk-manual/sdk-working-projects.xml b/documentation/sdk-manual/sdk-working-projects.xml
new file mode 100644
index 0000000000..15e533000c
--- /dev/null
+++ b/documentation/sdk-manual/sdk-working-projects.xml
@@ -0,0 +1,1461 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='sdk-working-projects'>
6
7 <title>Working with Different Types of Projects</title>
8
9 <para>
10 You can use extensible and standard SDKs when working with Makefile,
11 Autotools, and <trademark class='trade'>Eclipse</trademark> based
12 projects.
13 This chapter covers information specific to each of these types of
14 projects.
15 </para>
16
17 <section id='autotools-based-projects'>
18 <title>Autotools-Based Projects</title>
19
20 <para>
21 Once you have a suitable cross-toolchain installed, it is very easy
22 to develop a project outside of the OpenEmbedded build system.
23 This section presents a simple "Helloworld" example that shows how
24 to set up, compile, and run the project.
25 </para>
26
27 <section id='creating-and-running-a-project-based-on-gnu-autotools'>
28 <title>Creating and Running a Project Based on GNU Autotools</title>
29
30 <para>
31 Follow these steps to create a simple Autotools-based project:
32 <orderedlist>
33 <listitem><para>
34 <emphasis>Create your directory:</emphasis>
35 Create a clean directory for your project and then make
36 that directory your working location:
37 <literallayout class='monospaced'>
38 $ mkdir $HOME/helloworld
39 $ cd $HOME/helloworld
40 </literallayout>
41 </para></listitem>
42 <listitem><para>
43 <emphasis>Populate the directory:</emphasis>
44 Create <filename>hello.c</filename>,
45 <filename>Makefile.am</filename>,
46 and <filename>configure.ac</filename> files as follows:
47 <itemizedlist>
48 <listitem><para>
49 For <filename>hello.c</filename>, include
50 these lines:
51 <literallayout class='monospaced'>
52 #include &lt;stdio.h&gt;
53
54 main()
55 {
56 printf("Hello World!\n");
57 }
58 </literallayout>
59 </para></listitem>
60 <listitem><para>
61 For <filename>Makefile.am</filename>,
62 include these lines:
63 <literallayout class='monospaced'>
64 bin_PROGRAMS = hello
65 hello_SOURCES = hello.c
66 </literallayout>
67 </para></listitem>
68 <listitem><para>
69 For <filename>configure.in</filename>,
70 include these lines:
71 <literallayout class='monospaced'>
72 AC_INIT(hello,0.1)
73 AM_INIT_AUTOMAKE([foreign])
74 AC_PROG_CC
75 AC_PROG_INSTALL
76 AC_OUTPUT(Makefile)
77 </literallayout>
78 </para></listitem>
79 </itemizedlist>
80 </para></listitem>
81 <listitem><para>
82 <emphasis>Source the cross-toolchain
83 environment setup file:</emphasis>
84 As described earlier in the manual, installing the
85 cross-toolchain creates a cross-toolchain
86 environment setup script in the directory that the SDK
87 was installed.
88 Before you can use the tools to develop your project,
89 you must source this setup script.
90 The script begins with the string "environment-setup"
91 and contains the machine architecture, which is
92 followed by the string "poky-linux".
93 Here is an example that sources a script from the
94 default SDK installation directory that uses the
95 32-bit Intel x86 Architecture and the
96 &DISTRO_NAME; Yocto Project release:
97 <literallayout class='monospaced'>
98 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
99 </literallayout>
100 </para></listitem>
101 <listitem><para>
102 <emphasis>Generate the local aclocal.m4
103 files and create the configure script:</emphasis>
104 The following GNU Autotools generate the local
105 <filename>aclocal.m4</filename> files and create the
106 configure script:
107 <literallayout class='monospaced'>
108 $ aclocal
109 $ autoconf
110 </literallayout>
111 </para></listitem>
112 <listitem><para>
113 <emphasis>Generate files needed by GNU coding
114 standards:</emphasis>
115 GNU coding standards require certain files in order
116 for the project to be compliant.
117 This command creates those files:
118 <literallayout class='monospaced'>
119 $ touch NEWS README AUTHORS ChangeLog
120 </literallayout>
121 </para></listitem>
122 <listitem><para>
123 <emphasis>Generate the configure file:</emphasis>
124 This command generates the
125 <filename>configure</filename>:
126 <literallayout class='monospaced'>
127 $ automake -a
128 </literallayout>
129 </para></listitem>
130 <listitem><para>
131 <emphasis>Cross-compile the project:</emphasis>
132 This command compiles the project using the
133 cross-compiler.
134 The
135 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
136 environment variable provides the minimal arguments for
137 GNU configure:
138 <literallayout class='monospaced'>
139 $ ./configure ${CONFIGURE_FLAGS}
140 </literallayout>
141 </para></listitem>
142 <listitem><para>
143 <emphasis>Make and install the project:</emphasis>
144 These two commands generate and install the project
145 into the destination directory:
146 <literallayout class='monospaced'>
147 $ make
148 $ make install DESTDIR=./tmp
149 </literallayout>
150 </para></listitem>
151 <listitem><para>
152 <emphasis>Verify the installation:</emphasis>
153 This command is a simple way to verify the installation
154 of your project.
155 Running the command prints the architecture on which
156 the binary file can run.
157 This architecture should be the same architecture that
158 the installed cross-toolchain supports.
159 <literallayout class='monospaced'>
160 $ file ./tmp/usr/local/bin/hello
161 </literallayout>
162 </para></listitem>
163 <listitem><para>
164 <emphasis>Execute your project:</emphasis>
165 To execute the project in the shell, simply enter
166 the name.
167 You could also copy the binary to the actual target
168 hardware and run the project there as well:
169 <literallayout class='monospaced'>
170 $ ./hello
171 </literallayout>
172 As expected, the project displays the "Hello World!"
173 message.
174 </para></listitem>
175 </orderedlist>
176 </para>
177 </section>
178
179 <section id='passing-host-options'>
180 <title>Passing Host Options</title>
181
182 <para>
183 For an Autotools-based project, you can use the cross-toolchain
184 by just passing the appropriate host option to
185 <filename>configure.sh</filename>.
186 The host option you use is derived from the name of the
187 environment setup script found in the directory in which you
188 installed the cross-toolchain.
189 For example, the host option for an ARM-based target that uses
190 the GNU EABI is <filename>armv5te-poky-linux-gnueabi</filename>.
191 You will notice that the name of the script is
192 <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
193 Thus, the following command works to update your project and
194 rebuild it using the appropriate cross-toolchain tools:
195 <literallayout class='monospaced'>
196 $ ./configure --host=armv5te-poky-linux-gnueabi \
197 --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
198 </literallayout>
199 <note>
200 If the <filename>configure</filename> script results in
201 problems recognizing the
202 <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable>
203 option, regenerate the script to enable the support by
204 doing the following and then run the script again:
205 <literallayout class='monospaced'>
206 $ libtoolize --automake
207 $ aclocal -I ${OECORE_TARGET_SYSROOT}/usr/share/aclocal \
208 [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
209 $ autoconf
210 $ autoheader
211 $ automake -a
212 </literallayout>
213 </note>
214 </para>
215 </section>
216 </section>
217
218 <section id='makefile-based-projects'>
219 <title>Makefile-Based Projects</title>
220
221 <para>
222 For Makefile-based projects, the cross-toolchain environment
223 variables established by running the cross-toolchain environment
224 setup script are subject to general <filename>make</filename>
225 rules.
226 </para>
227
228 <para>
229 To illustrate this, consider the following four cross-toolchain
230 environment variables:
231 <literallayout class='monospaced'>
232 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
233 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
234 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
235 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
236 </literallayout>
237 Now, consider the following three cases:
238 <itemizedlist>
239 <listitem><para>
240 <emphasis>Case 1 - No Variables Set in the
241 <filename>Makefile</filename>:</emphasis>
242 Because these variables are not specifically set in the
243 <filename>Makefile</filename>, the variables retain their
244 values based on the environment.
245 </para></listitem>
246 <listitem><para>
247 <emphasis>Case 2 - Variables Set in the
248 <filename>Makefile</filename>:</emphasis>
249 Specifically setting variables in the
250 <filename>Makefile</filename> during the build results in
251 the environment settings of the variables being
252 overwritten.
253 </para></listitem>
254 <listitem><para>
255 <emphasis>Case 3 - Variables Set when the
256 <filename>Makefile</filename> is Executed from the
257 Command Line:</emphasis>
258 Executing the <filename>Makefile</filename> from the
259 command-line results in the variables being overwritten
260 with command-line content regardless of what is being set
261 in the <filename>Makefile</filename>.
262 In this case, environment variables are not considered
263 unless you use the "-e" flag during the build:
264 <literallayout class='monospaced'>
265 $ make -e <replaceable>file</replaceable>
266 </literallayout>
267 If you use this flag, then the environment values of the
268 variables override any variables specifically set in the
269 <filename>Makefile</filename>.
270 </para></listitem>
271 </itemizedlist>
272 <note>
273 For the list of variables set up by the cross-toolchain
274 environment setup script, see the
275 "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
276 section.
277 </note>
278 </para>
279 </section>
280
281 <section id='sdk-developing-applications-using-eclipse'>
282 <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title>
283
284 <para>
285 If you are familiar with the popular Eclipse IDE, you can use an
286 Eclipse Yocto Plug-in to allow you to develop, deploy, and test your
287 application all from within Eclipse.
288 This section describes general workflow using the SDK and Eclipse
289 and how to configure and set up Eclipse.
290 </para>
291
292 <section id='workflow-using-eclipse'>
293 <title>Workflow Using <trademark class='trade'>Eclipse</trademark></title>
294
295 <para>
296 The following figure and supporting list summarize the
297 application development general workflow that employs both the
298 SDK Eclipse.
299 </para>
300
301 <para>
302 <imagedata fileref="figures/sdk-eclipse-dev-flow.png"
303 width="7in" depth="7in" align="center" scale="100" />
304 </para>
305
306 <para>
307 <orderedlist>
308 <listitem><para>
309 <emphasis>Prepare the host system for the Yocto
310 Project</emphasis>:
311 See
312 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
313 and
314 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
315 sections both in the Yocto Project Reference Manual for
316 requirements.
317 In particular, be sure your host system has the
318 <filename>xterm</filename> package installed.
319 </para></listitem>
320 <listitem><para>
321 <emphasis>Secure the Yocto Project kernel target
322 image</emphasis>:
323 You must have a target kernel image that has been built
324 using the OpenEmbedded build system.</para>
325 <para>Depending on whether the Yocto Project has a
326 pre-built image that matches your target architecture
327 and where you are going to run the image while you
328 develop your application (QEMU or real hardware), the
329 area from which you get the image differs.
330 <itemizedlist>
331 <listitem><para>
332 Download the image from
333 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
334 if your target architecture is supported and
335 you are going to develop and test your
336 application on actual hardware.
337 </para></listitem>
338 <listitem><para>
339 Download the image from
340 <ulink url='&YOCTO_QEMU_DL_URL;'>
341 <filename>machines/qemu</filename></ulink> if
342 your target architecture is supported and you
343 are going to develop and test your application
344 using the QEMU emulator.
345 </para></listitem>
346 <listitem><para>
347 Build your image if you cannot find a pre-built
348 image that matches your target architecture.
349 If your target architecture is similar to a
350 supported architecture, you can modify the
351 kernel image before you build it.
352 See the
353 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
354 section in the Yocto Project Development
355 manual for an example.
356 </para></listitem>
357 </itemizedlist>
358 </para></listitem>
359 <listitem>
360 <para><emphasis>Install the SDK</emphasis>:
361 The SDK provides a target-specific cross-development
362 toolchain, the root filesystem, the QEMU emulator, and
363 other tools that can help you develop your application.
364 For information on how to install the SDK, see the
365 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
366 section.
367 </para></listitem>
368 <listitem><para>
369 <emphasis>Secure the target root filesystem
370 and the Cross-development toolchain</emphasis>:
371 You need to find and download the appropriate root
372 filesystem and the cross-development toolchain.</para>
373 <para>You can find the tarballs for the root filesystem
374 in the same area used for the kernel image.
375 Depending on the type of image you are running, the
376 root filesystem you need differs.
377 For example, if you are developing an application that
378 runs on an image that supports Sato, you need to get a
379 root filesystem that supports Sato.</para>
380 <para>You can find the cross-development toolchains at
381 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
382 Be sure to get the correct toolchain for your
383 development host and your target architecture.
384 See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>"
385 section for information and the
386 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
387 section for installation information.
388 <note>
389 As an alternative to downloading an SDK, you can
390 build the toolchain installer.
391 For information on building the installer, see the
392 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
393 section.
394 Another helpful resource for building an installer
395 is the
396 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
397 wiki page.
398 </note>
399 </para></listitem>
400 <listitem><para>
401 <emphasis>Create and build your application</emphasis>:
402 At this point, you need to have source files for your
403 application.
404 Once you have the files, you can use the Eclipse IDE
405 to import them and build the project.
406 If you are not using Eclipse, you need to use the
407 cross-development tools you have installed to create
408 the image.</para></listitem>
409 <listitem><para>
410 <emphasis>Deploy the image with the
411 application</emphasis>:
412 Using the Eclipse IDE, you can deploy your image to the
413 hardware or to QEMU through the project's preferences.
414 You can also use Eclipse to load and test your image
415 under QEMU.
416 See the
417 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
418 chapter in the Yocto Project Development Manual
419 for information on using QEMU.
420 </para></listitem>
421 <listitem><para>
422 <emphasis>Test and debug the application</emphasis>:
423 Once your application is deployed, you need to test it.
424 Within the Eclipse IDE, you can use the debugging
425 environment along with supported performance enhancing
426 <ulink url='http://www.eclipse.org/linuxtools/'>Linux Tools</ulink>.
427 </para></listitem>
428 </orderedlist>
429 </para>
430 </section>
431
432 <section id='adt-eclipse'>
433 <title>Working Within Eclipse</title>
434
435 <para>
436 The Eclipse IDE is a popular development environment and it
437 fully supports development using the Yocto Project.
438 </para>
439
440 <para>
441 When you install and configure the Eclipse Yocto Project
442 Plug-in into the Eclipse IDE, you maximize your Yocto
443 Project experience.
444 Installing and configuring the Plug-in results in an
445 environment that has extensions specifically designed to let
446 you more easily develop software.
447 These extensions allow for cross-compilation, deployment, and
448 execution of your output into a QEMU emulation session as well
449 as actual target hardware.
450 You can also perform cross-debugging and profiling.
451 The environment also supports performance enhancing
452 <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink>
453 that allow you to perform remote profiling, tracing,
454 collection of power data, collection of latency data, and
455 collection of performance data.
456 <note>
457 This release of the Yocto Project supports both the Neon
458 and Mars versions of the Eclipse IDE.
459 This section provides information on how to use the Neon
460 release with the Yocto Project.
461 For information on how to use the Mars version of Eclipse
462 with the Yocto Project, see
463 "<link linkend='sdk-appendix-mars'>Appendix C</link>.
464 </note>
465 </para>
466
467 <section id='neon-setting-up-the-eclipse-ide'>
468 <title>Setting Up the Neon Version of the Eclipse IDE</title>
469
470 <para>
471 To develop within the Eclipse IDE, you need to do the
472 following:
473 <orderedlist>
474 <listitem><para>
475 Install the Neon version of the Eclipse IDE.
476 </para></listitem>
477 <listitem><para>
478 Configure the Eclipse IDE.
479 </para></listitem>
480 <listitem><para>
481 Install the Eclipse Yocto Plug-in.
482 </para></listitem>
483 <listitem><para>
484 Configure the Eclipse Yocto Plug-in.
485 </para></listitem>
486 </orderedlist>
487 <note>
488 Do not install Eclipse from your distribution's package
489 repository.
490 Be sure to install Eclipse from the official Eclipse
491 download site as directed in the next section.
492 </note>
493 </para>
494
495 <section id='neon-installing-eclipse-ide'>
496 <title>Installing the Neon Eclipse IDE</title>
497
498 <para>
499 Follow these steps to locate, install, and configure
500 Neon Eclipse:
501 <orderedlist>
502 <listitem><para>
503 <emphasis>Locate the Neon Download:</emphasis>
504 Open a browser and go to
505 <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/neon/</ulink>.
506 </para></listitem>
507 <listitem><para>
508 <emphasis>Download the Tarball:</emphasis>
509 Click through the "Download" buttons to
510 download the file.
511 </para></listitem>
512 <listitem><para>
513 <emphasis>Unpack the Tarball:</emphasis>
514 Move to a clean directory and unpack the
515 tarball.
516 Here is an example:
517 <literallayout class='monospaced'>
518 $ cd ~
519 $ tar -xzvf ~/Downloads/eclipse-inst-linux64.tar.gz
520 </literallayout>
521 Everything unpacks into a folder named
522 "eclipse-installer".
523 </para></listitem>
524 <listitem><para>
525 <emphasis>Launch the Installer:</emphasis>
526 Use the following commands to launch the
527 installer:
528 <literallayout class='monospaced'>
529 $ cd ~/eclipse-installer
530 $ ./eclipse-inst
531 </literallayout>
532 </para></listitem>
533 <listitem><para>
534 <emphasis>Select Your IDE:</emphasis>
535 From the list, select the "Eclipse IDE for
536 C/C++ Developers".
537 </para></listitem>
538 <listitem><para>
539 <emphasis>Install the Software:</emphasis>
540 Accept the default "cpp-neon" directory and
541 click "Install".
542 Accept any license agreements and approve any
543 certificates.
544 </para></listitem>
545 <listitem><para>
546 <emphasis>Launch Neon:</emphasis>
547 Click the "Launch" button and accept the
548 default "workspace".
549 </para></listitem>
550 </orderedlist>
551 </para>
552 </section>
553
554 <section id='neon-configuring-the-mars-eclipse-ide'>
555 <title>Configuring the Neon Eclipse IDE</title>
556
557 <para>
558 Follow these steps to configure the Neon Eclipse IDE.
559 <note>
560 Depending on how you installed Eclipse and what
561 you have already done, some of the options will
562 not appear.
563 If you cannot find an option as directed by the
564 manual, it has already been installed.
565 </note>
566 <orderedlist>
567 <listitem><para>
568 Be sure Eclipse is running and you are in your
569 workbench.
570 </para></listitem>
571 <listitem><para>
572 Select "Install New Software" from the "Help"
573 pull-down menu.
574 </para></listitem>
575 <listitem><para>
576 Select
577 "Neon - http://download.eclipse.org/releases/neon"
578 from the "Work with:" pull-down menu.
579 </para></listitem>
580 <listitem><para>
581 Expand the box next to "Linux Tools" and select
582 the following:
583 <literallayout class='monospaced'>
584 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
585 TM Terminal
586 </literallayout>
587 </para></listitem>
588 <listitem><para>
589 Expand the box next to "Mobile and Device
590 Development" and select the following
591 boxes:
592 <literallayout class='monospaced'>
593 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
594 Remote System Explorer User Actions
595 TM Terminal
596 TCF Remote System Explorer add-in
597 TCF Target Explorer
598 </literallayout>
599 </para></listitem>
600 <listitem><para>
601 Expand the box next to "Programming Languages"
602 and select the following box:
603 <literallayout class='monospaced'>
604 C/C++ Development Tools SDK
605 </literallayout>
606 </para></listitem>
607 <listitem><para>
608 Complete the installation by clicking through
609 appropriate "Next" and "Finish" buttons.
610 </para></listitem>
611 </orderedlist>
612 </para>
613 </section>
614
615 <section id='neon-installing-the-eclipse-yocto-plug-in'>
616 <title>Installing or Accessing the Neon Eclipse Yocto Plug-in</title>
617
618 <para>
619 You can install the Eclipse Yocto Plug-in into the
620 Eclipse IDE one of two ways: use the Yocto Project's
621 Eclipse Update site to install the pre-built plug-in
622 or build and install the plug-in from the latest
623 source code.
624 </para>
625
626 <section id='neon-new-software'>
627 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
628
629 <para>
630 To install the Neon Eclipse Yocto Plug-in from the
631 update site, follow these steps:
632 <orderedlist>
633 <listitem><para>
634 Start up the Eclipse IDE.
635 </para></listitem>
636 <listitem><para>
637 In Eclipse, select "Install New
638 Software" from the "Help" menu.
639 </para></listitem>
640 <listitem><para>
641 Click "Add..." in the "Work with:" area.
642 </para></listitem>
643 <listitem><para>
644 Enter
645 <filename>&ECLIPSE_DL_PLUGIN_URL;/neon</filename>
646 in the URL field and provide a meaningful
647 name in the "Name" field.
648 </para></listitem>
649 <listitem><para>
650 Click "OK" to have the entry added
651 to the "Work with:" drop-down list.
652 </para></listitem>
653 <listitem><para>
654 Select the entry for the plug-in
655 from the "Work with:" drop-down list.
656 </para></listitem>
657 <listitem><para>
658 Check the boxes next to the following:
659 <literallayout class='monospaced'>
660 Yocto Project SDK Plug-in
661 Yocto Project Documentation plug-in
662 </literallayout>
663 </para></listitem>
664 <listitem><para>
665 Complete the remaining software
666 installation steps and then restart the
667 Eclipse IDE to finish the installation of
668 the plug-in.
669 <note>
670 You can click "OK" when prompted about
671 installing software that contains
672 unsigned content.
673 </note>
674 </para></listitem>
675 </orderedlist>
676 </para>
677 </section>
678
679 <section id='neon-zip-file-method'>
680 <title>Installing the Plug-in Using the Latest Source Code</title>
681
682 <para>
683 To install the Neon Eclipse Yocto Plug-in from the
684 latest source code, follow these steps:
685 <orderedlist>
686 <listitem><para>
687 Be sure your development system
688 has JDK 1.8+
689 </para></listitem>
690 <listitem><para>
691 Install X11-related packages:
692 <literallayout class='monospaced'>
693 $ sudo apt-get install xauth
694 </literallayout>
695 </para></listitem>
696 <listitem><para>
697 In a new terminal shell, create a
698 Git repository with:
699 <literallayout class='monospaced'>
700 $ cd ~
701 $ git clone git://git.yoctoproject.org/eclipse-poky
702 </literallayout>
703 </para></listitem>
704 <listitem><para>
705 Use Git to create the correct tag:
706 <literallayout class='monospaced'>
707 $ cd ~/eclipse-poky
708 $ git checkout neon/yocto-&DISTRO;
709 </literallayout>
710 This creates a local tag named
711 <filename>neon/yocto-&DISTRO;</filename>
712 based on the branch
713 <filename>origin/neon-master</filename>.
714 You are put into a detached HEAD state,
715 which is fine since you are only going to
716 be building and not developing.
717 </para></listitem>
718 <listitem><para>
719 Change to the <filename>scripts</filename>
720 directory within the Git repository:
721 <literallayout class='monospaced'>
722 $ cd scripts
723 </literallayout>
724 </para></listitem>
725 <listitem><para>
726 Set up the local build environment
727 by running the setup script:
728 <literallayout class='monospaced'>
729 $ ./setup.sh
730 </literallayout>
731 When the script finishes execution,
732 it prompts you with instructions on how to
733 run the <filename>build.sh</filename>
734 script, which is also in the
735 <filename>scripts</filename> directory of
736 the Git repository created earlier.
737 </para></listitem>
738 <listitem><para>
739 Run the <filename>build.sh</filename>
740 script as directed.
741 Be sure to provide the tag name,
742 documentation branch, and a release name.
743 </para>
744 <para>
745 Following is an example:
746 <literallayout class='monospaced'>
747 $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l neon/yocto-&DISTRO; master yocto-&DISTRO; 2>&amp;1 | tee build.log
748 </literallayout>
749 The previous example command adds the tag
750 you need for
751 <filename>mars/yocto-&DISTRO;</filename>
752 to <filename>HEAD</filename>, then tells
753 the build script to use the local (-l) Git
754 checkout for the build.
755 After running the script, the file
756 <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>
757 is in the current directory.
758 </para></listitem>
759 <listitem><para>
760 If necessary, start the Eclipse IDE
761 and be sure you are in the Workbench.
762 </para></listitem>
763 <listitem><para>
764 Select "Install New Software" from
765 the "Help" pull-down menu.
766 </para></listitem>
767 <listitem><para>
768 Click "Add".
769 </para></listitem>
770 <listitem><para>
771 Provide anything you want in the
772 "Name" field.
773 </para></listitem>
774 <listitem><para>
775 Click "Archive" and browse to the
776 ZIP file you built earlier.
777 This ZIP file should not be "unzipped", and
778 must be the
779 <filename>*archive.zip</filename> file
780 created by running the
781 <filename>build.sh</filename> script.
782 </para></listitem>
783 <listitem><para>
784 Click the "OK" button.
785 </para></listitem>
786 <listitem><para>
787 Check the boxes that appear in
788 the installation window to install the
789 following:
790 <literallayout class='monospaced'>
791 Yocto Project SDK Plug-in
792 Yocto Project Documentation plug-in
793 </literallayout>
794 </para></listitem>
795 <listitem><para>
796 Finish the installation by clicking
797 through the appropriate buttons.
798 You can click "OK" when prompted about
799 installing software that contains unsigned
800 content.
801 </para></listitem>
802 <listitem><para>
803 Restart the Eclipse IDE if necessary.
804 </para></listitem>
805 </orderedlist>
806 </para>
807
808 <para>
809 At this point you should be able to configure the
810 Eclipse Yocto Plug-in as described in the
811 "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"
812 section.
813 </para>
814 </section>
815 </section>
816
817 <section id='neon-configuring-the-eclipse-yocto-plug-in'>
818 <title>Configuring the Neon Eclipse Yocto Plug-in</title>
819
820 <para>
821 Configuring the Neon Eclipse Yocto Plug-in involves
822 setting the Cross Compiler options and the Target
823 options.
824 The configurations you choose become the default
825 settings for all projects.
826 You do have opportunities to change them later when
827 you configure the project (see the following section).
828 </para>
829
830 <para>
831 To start, you need to do the following from within the
832 Eclipse IDE:
833 <itemizedlist>
834 <listitem><para>
835 Choose "Preferences" from the "Window" menu to
836 display the Preferences Dialog.
837 </para></listitem>
838 <listitem><para>
839 Click "Yocto Project SDK" to display
840 the configuration screen.
841 </para></listitem>
842 </itemizedlist>
843 The following sub-sections describe how to configure
844 the plug-in.
845 <note>
846 Throughout the descriptions, a start-to-finish
847 example for preparing a QEMU image for use with
848 Eclipse is referenced as the "wiki" and is linked
849 to the example on the
850 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
851 wiki page.
852 </note>
853 </para>
854
855 <section id='neon-configuring-the-cross-compiler-options'>
856 <title>Configuring the Cross-Compiler Options</title>
857
858 <para>
859 Cross Compiler options enable Eclipse to use your
860 specific cross compiler toolchain.
861 To configure these options, you must select
862 the type of toolchain, point to the toolchain,
863 specify the sysroot location, and select the target
864 architecture.
865 <itemizedlist>
866 <listitem><para>
867 <emphasis>Selecting the Toolchain
868 Type:</emphasis>
869 Choose between
870 <filename>Standalone pre-built toolchain</filename>
871 and
872 <filename>Build system derived toolchain</filename>
873 for Cross Compiler Options.
874 <itemizedlist>
875 <listitem><para>
876 <emphasis>
877 <filename>Standalone Pre-built Toolchain:</filename>
878 </emphasis>
879 Select this type when you are using
880 a stand-alone cross-toolchain.
881 For example, suppose you are an
882 application developer and do not
883 need to build a target image.
884 Instead, you just want to use an
885 architecture-specific toolchain on
886 an existing kernel and target root
887 filesystem.
888 In other words, you have downloaded
889 and installed a pre-built toolchain
890 for an existing image.
891 </para></listitem>
892 <listitem><para>
893 <emphasis>
894 <filename>Build System Derived Toolchain:</filename>
895 </emphasis>
896 Select this type if you built the
897 toolchain as part of the
898 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
899 When you select
900 <filename>Build system derived toolchain</filename>,
901 you are using the toolchain built
902 and bundled inside the Build
903 Directory.
904 For example, suppose you created a
905 suitable image using the steps in the
906 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
907 In this situation, you would select
908 the
909 <filename>Build system derived toolchain</filename>.
910 </para></listitem>
911 </itemizedlist>
912 </para></listitem>
913 <listitem><para>
914 <emphasis>Specify the Toolchain Root
915 Location:</emphasis>
916 If you are using a stand-alone pre-built
917 toolchain, you should be pointing to where
918 it is installed (e.g.
919 <filename>/opt/poky/&DISTRO;</filename>).
920 See the
921 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
922 section for information about how the SDK is
923 installed.</para>
924 <para>If you are using a build system
925 derived toolchain, the path you provide for
926 the
927 <filename>Toolchain Root Location</filename>
928 field is the
929 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
930 from which you run the
931 <filename>bitbake</filename> command (e.g
932 <filename>/home/scottrif/poky/build</filename>).
933 </para>
934 <para>For more information, see the
935 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
936 section.
937 </para></listitem>
938 <listitem><para>
939 <emphasis>Specify Sysroot Location:
940 </emphasis>
941 This location is where the root filesystem
942 for the target hardware resides.
943 </para>
944 <para>This location depends on where you
945 separately extracted and installed the
946 target filesystem.
947 As an example, suppose you prepared an
948 image using the steps in the
949 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
950 If so, the
951 <filename>MY_QEMU_ROOTFS</filename>
952 directory is found in the
953 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
954 and you would browse to and select that
955 directory (e.g.
956 <filename>/home/scottrif/poky/build/MY_QEMU_ROOTFS</filename>).
957 </para>
958 <para>For more information on how to
959 install the toolchain and on how to extract
960 and install the sysroot filesystem, see the
961 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
962 section.
963 </para></listitem>
964 <listitem><para>
965 <emphasis>Select the Target Architecture:
966 </emphasis>
967 The target architecture is the type of
968 hardware you are going to use or emulate.
969 Use the pull-down
970 <filename>Target Architecture</filename>
971 menu to make your selection.
972 The pull-down menu should have the
973 supported architectures.
974 If the architecture you need is not listed
975 in the menu, you will need to build the
976 image.
977 See the
978 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
979 section of the Yocto Project Quick Start
980 for more information.
981 You can also see the
982 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
983 </para></listitem>
984 </itemizedlist>
985 </para>
986 </section>
987
988 <section id='neon-configuring-the-target-options'>
989 <title>Configuring the Target Options</title>
990
991 <para>
992 You can choose to emulate hardware using the QEMU
993 emulator, or you can choose to run your image on
994 actual hardware.
995 <itemizedlist>
996 <listitem><para>
997 <emphasis>QEMU:</emphasis>
998 Select this option if you will be using the
999 QEMU emulator.
1000 If you are using the emulator, you also
1001 need to locate the kernel and specify any
1002 custom options.</para>
1003 <para>If you selected the
1004 <filename>Build system derived toolchain</filename>,
1005 the target kernel you built will be located
1006 in the
1007 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1008 in
1009 <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
1010 directory.
1011 As an example, suppose you performed the
1012 steps in the
1013 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
1014 In this case, you specify your Build
1015 Directory path followed by the image (e.g.
1016 <filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).
1017 </para>
1018 <para>If you selected the standalone
1019 pre-built toolchain, the pre-built image
1020 you downloaded is located in the directory
1021 you specified when you downloaded the
1022 image.</para>
1023 <para>Most custom options are for advanced
1024 QEMU users to further customize their QEMU
1025 instance.
1026 These options are specified between paired
1027 angled brackets.
1028 Some options must be specified outside the
1029 brackets.
1030 In particular, the options
1031 <filename>serial</filename>,
1032 <filename>nographic</filename>, and
1033 <filename>kvm</filename> must all be
1034 outside the brackets.
1035 Use the <filename>man qemu</filename>
1036 command to get help on all the options and
1037 their use.
1038 The following is an example:
1039 <literallayout class='monospaced'>
1040 serial ‘&lt;-m 256 -full-screen&gt;’
1041 </literallayout></para>
1042 <para>
1043 Regardless of the mode, Sysroot is already
1044 defined as part of the Cross-Compiler
1045 Options configuration in the
1046 <filename>Sysroot Location:</filename>
1047 field.
1048 </para></listitem>
1049 <listitem><para>
1050 <emphasis>External HW:</emphasis>
1051 Select this option if you will be using
1052 actual hardware.</para></listitem>
1053 </itemizedlist>
1054 </para>
1055
1056 <para>
1057 Click the "Apply" and "OK" to save your plug-in
1058 configurations.
1059 </para>
1060 </section>
1061 </section>
1062 </section>
1063
1064 <section id='neon-creating-the-project'>
1065 <title>Creating the Project</title>
1066
1067 <para>
1068 You can create two types of projects: Autotools-based, or
1069 Makefile-based.
1070 This section describes how to create Autotools-based
1071 projects from within the Eclipse IDE.
1072 For information on creating Makefile-based projects in a
1073 terminal window, see the
1074 "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
1075 section.
1076 <note>
1077 Do not use special characters in project names
1078 (e.g. spaces, underscores, etc.). Doing so can
1079 cause configuration to fail.
1080 </note>
1081 </para>
1082
1083 <para>
1084 To create a project based on a Yocto template and then
1085 display the source code, follow these steps:
1086 <orderedlist>
1087 <listitem><para>
1088 Select "C Project" from the "File -> New" menu.
1089 </para></listitem>
1090 <listitem><para>
1091 Expand
1092 <filename>Yocto Project SDK Autotools Project</filename>.
1093 </para></listitem>
1094 <listitem><para>
1095 Select <filename>Hello World ANSI C Autotools Projects</filename>.
1096 This is an Autotools-based project based on a Yocto
1097 template.
1098 </para></listitem>
1099 <listitem><para>
1100 Put a name in the
1101 <filename>Project name:</filename> field.
1102 Do not use hyphens as part of the name
1103 (e.g. <filename>hello</filename>).
1104 </para></listitem>
1105 <listitem><para>
1106 Click "Next".
1107 </para></listitem>
1108 <listitem><para>
1109 Add appropriate information in the various fields.
1110 </para></listitem>
1111 <listitem><para>
1112 Click "Finish".
1113 </para></listitem>
1114 <listitem><para>
1115 If the "open perspective" prompt appears,
1116 click "Yes" so that you in the C/C++ perspective.
1117 </para></listitem>
1118 <listitem><para>The left-hand navigation pane shows
1119 your project.
1120 You can display your source by double clicking the
1121 project's source file.
1122 </para></listitem>
1123 </orderedlist>
1124 </para>
1125 </section>
1126
1127 <section id='neon-configuring-the-cross-toolchains'>
1128 <title>Configuring the Cross-Toolchains</title>
1129
1130 <para>
1131 The earlier section,
1132 "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>",
1133 sets up the default project configurations.
1134 You can override these settings for a given project by
1135 following these steps:
1136 <orderedlist>
1137 <listitem><para>
1138 Select "Yocto Project Settings" from
1139 the "Project -> Properties" menu.
1140 This selection brings up the Yocto Project Settings
1141 Dialog and allows you to make changes specific to
1142 an individual project.</para>
1143 <para>By default, the Cross Compiler Options and
1144 Target Options for a project are inherited from
1145 settings you provided using the Preferences Dialog
1146 as described earlier in the
1147 "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"
1148 section.
1149 The Yocto Project Settings Dialog allows you to
1150 override those default settings for a given
1151 project.
1152 </para></listitem>
1153 <listitem><para>
1154 Make or verify your configurations for the
1155 project and click "OK".
1156 </para></listitem>
1157 <listitem><para>
1158 Right-click in the navigation pane and
1159 select "Reconfigure Project" from the pop-up menu.
1160 This selection reconfigures the project by running
1161 <filename>autogen.sh</filename> in the workspace
1162 for your project.
1163 The script also runs
1164 <filename>libtoolize</filename>,
1165 <filename>aclocal</filename>,
1166 <filename>autoconf</filename>,
1167 <filename>autoheader</filename>,
1168 <filename>automake --a</filename>, and
1169 <filename>./configure</filename>.
1170 Click on the "Console" tab beneath your source code
1171 to see the results of reconfiguring your project.
1172 </para></listitem>
1173 </orderedlist>
1174 </para>
1175 </section>
1176
1177 <section id='neon-building-the-project'>
1178 <title>Building the Project</title>
1179
1180 <para>
1181 To build the project select "Build All" from the
1182 "Project" menu.
1183 The console should update and you can note the
1184 cross-compiler you are using.
1185 <note>
1186 When building "Yocto Project SDK Autotools" projects,
1187 the Eclipse IDE might display error messages for
1188 Functions/Symbols/Types that cannot be "resolved",
1189 even when the related include file is listed at the
1190 project navigator and when the project is able to
1191 build.
1192 For these cases only, it is recommended to add a new
1193 linked folder to the appropriate sysroot.
1194 Use these steps to add the linked folder:
1195 <orderedlist>
1196 <listitem><para>
1197 Select the project.
1198 </para></listitem>
1199 <listitem><para>
1200 Select "Folder" from the
1201 <filename>File > New</filename> menu.
1202 </para></listitem>
1203 <listitem><para>
1204 In the "New Folder" Dialog, select "Link to
1205 alternate location (linked folder)".
1206 </para></listitem>
1207 <listitem><para>
1208 Click "Browse" to navigate to the include
1209 folder inside the same sysroot location
1210 selected in the Yocto Project
1211 configuration preferences.
1212 </para></listitem>
1213 <listitem><para>
1214 Click "OK".
1215 </para></listitem>
1216 <listitem><para>
1217 Click "Finish" to save the linked folder.
1218 </para></listitem>
1219 </orderedlist>
1220 </note>
1221 </para>
1222 </section>
1223
1224 <section id='neon-starting-qemu-in-user-space-nfs-mode'>
1225 <title>Starting QEMU in User-Space NFS Mode</title>
1226
1227 <para>
1228 To start the QEMU emulator from within Eclipse, follow
1229 these steps:
1230 <note>
1231 See the
1232 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
1233 chapter in the Yocto Project Development Manual
1234 for more information on using QEMU.
1235 </note>
1236 <orderedlist>
1237 <listitem><para>Expose and select "External Tools
1238 Configurations ..." from the "Run -> External
1239 Tools" menu.
1240 </para></listitem>
1241 <listitem><para>
1242 Locate and select your image in the navigation
1243 panel to the left
1244 (e.g. <filename>qemu_i586-poky-linux</filename>).
1245 </para></listitem>
1246 <listitem><para>
1247 Click "Run" to launch QEMU.
1248 <note>
1249 The host on which you are running QEMU must
1250 have the <filename>rpcbind</filename> utility
1251 running to be able to make RPC calls on a
1252 server on that machine.
1253 If QEMU does not invoke and you receive error
1254 messages involving
1255 <filename>rpcbind</filename>, follow the
1256 suggestions to get the service running.
1257 As an example, on a new Ubuntu 16.04 LTS
1258 installation, you must do the following in
1259 order to get QEMU to launch:
1260 <literallayout class='monospaced'>
1261 $ sudo apt-get install rpcbind
1262 </literallayout>
1263 After installing <filename>rpcbind</filename>,
1264 you need to edit the
1265 <filename>/etc/init.d/rpcbind</filename> file
1266 to include the following line:
1267 <literallayout class='monospaced'>
1268 OPTIONS="-i -w"
1269 </literallayout>
1270 After modifying the file, you need to start the
1271 service:
1272 <literallayout class='monospaced'>
1273 $ sudo service portmap restart
1274 </literallayout>
1275 </note>
1276 </para></listitem>
1277 <listitem><para>
1278 If needed, enter your host root password in
1279 the shell window at the prompt.
1280 This sets up a <filename>Tap 0</filename>
1281 connection needed for running in user-space NFS
1282 mode.
1283 </para></listitem>
1284 <listitem><para>
1285 Wait for QEMU to launch.
1286 </para></listitem>
1287 <listitem><para>
1288 Once QEMU launches, you can begin operating
1289 within that environment.
1290 One useful task at this point would be to determine
1291 the IP Address for the user-space NFS by using the
1292 <filename>ifconfig</filename> command.
1293 The IP address of the QEMU machine appears in the
1294 xterm window.
1295 You can use this address to help you see which
1296 particular
1297 IP address the instance of QEMU is using.
1298 </para></listitem>
1299 </orderedlist>
1300 </para>
1301 </section>
1302
1303 <section id='neon-deploying-and-debugging-the-application'>
1304 <title>Deploying and Debugging the Application</title>
1305
1306 <para>
1307 Once the QEMU emulator is running the image, you can deploy
1308 your application using the Eclipse IDE and then use
1309 the emulator to perform debugging.
1310 Follow these steps to deploy the application.
1311 <note>
1312 Currently, Eclipse does not support SSH port
1313 forwarding.
1314 Consequently, if you need to run or debug a remote
1315 application using the host display, you must create a
1316 tunneling connection from outside Eclipse and keep
1317 that connection alive during your work.
1318 For example, in a new terminal, run the following:
1319 <literallayout class='monospaced'>
1320 $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>
1321 </literallayout>
1322 Using the above form, here is an example:
1323 <literallayout class='monospaced'>
1324 $ ssh -XY root@192.168.7.2
1325 </literallayout>
1326 After running the command, add the command to be
1327 executed in Eclipse's run configuration before the
1328 application as follows:
1329 <literallayout class='monospaced'>
1330 export DISPLAY=:10.0
1331 </literallayout>
1332 Be sure to not destroy the connection during your QEMU
1333 session (i.e. do not
1334 exit out of or close that shell).
1335 </note>
1336 <orderedlist>
1337 <listitem><para>
1338 Select "Debug Configurations..." from the
1339 "Run" menu.
1340 </para></listitem>
1341 <listitem><para>
1342 In the left area, expand
1343 <filename>C/C++Remote Application</filename>.
1344 </para></listitem>
1345 <listitem><para>
1346 Locate your project and select it to bring
1347 up a new tabbed view in the Debug Configurations
1348 Dialog.
1349 </para></listitem>
1350 <listitem><para>
1351 Click on the "Debugger" tab to see the
1352 cross-tool debugger you are using.
1353 Be sure to change to the debugger perspective in
1354 Eclipse.
1355 </para></listitem>
1356 <listitem><para>
1357 Click on the "Main" tab.
1358 </para></listitem>
1359 <listitem><para>
1360 Create a new connection to the QEMU instance
1361 by clicking on "new".</para></listitem>
1362 <listitem><para>Select <filename>SSH</filename>, which
1363 means Secure Socket Shell and then click "OK".
1364 Optionally, you can select an TCF connection
1365 instead.
1366 </para></listitem>
1367 <listitem><para>
1368 Clear out the "Connection name" field and
1369 enter any name you want for the connection.
1370 </para></listitem>
1371 <listitem><para>
1372 Put the IP address for the connection in
1373 the "Host" field.
1374 For QEMU, the default is
1375 <filename>192.168.7.2</filename>.
1376 However, if a previous QEMU session did not exit
1377 cleanly, the IP address increments (e.g.
1378 <filename>192.168.7.3</filename>).
1379 <note>
1380 You can find the IP address for the current
1381 QEMU session by looking in the xterm that
1382 opens when you launch QEMU.
1383 </note>
1384 </para></listitem>
1385 <listitem><para>
1386 Enter <filename>root</filename>, which
1387 is the default for QEMU, for the "User" field.
1388 Be sure to leave the password field empty.
1389 </para></listitem>
1390 <listitem><para>
1391 Click "Finish" to close the New Connections Dialog.
1392 </para></listitem>
1393 <listitem><para>
1394 If necessary, use the drop-down menu now in the
1395 "Connection" field and pick the IP Address you
1396 entered.
1397 </para></listitem>
1398 <listitem><para>
1399 Assuming you are connecting as the root
1400 user, which is the default for QEMU x86-64 SDK
1401 images provided by the Yocto Project, in the
1402 "Remote Absolute File Path for C/C++ Application"
1403 field, browse to
1404 <filename>/home/root/</filename><replaceable>ProjectName</replaceable>
1405 (e.g. <filename>/home/root/hello</filename>).
1406 You could also browse to any other path you have
1407 write access to on the target such as
1408 <filename>/usr/bin</filename>.
1409 This location is where your application will be
1410 located on the QEMU system.
1411 If you fail to browse to and specify an appropriate
1412 location, QEMU will not understand what to remotely
1413 launch.
1414 Eclipse is helpful in that it auto fills your
1415 application name for you assuming you browsed to a
1416 directory.
1417 <note>
1418 If you are prompted to provide a username and
1419 to optionally set a password, be sure you
1420 provide "root" as the username and you leave
1421 the password field blank.
1422 </note>
1423 </para></listitem>
1424 <listitem><para>
1425 Be sure you change to the "Debug" perspective in
1426 Eclipse.
1427 </para></listitem>
1428 <listitem><para>
1429 Click "Debug"
1430 </para></listitem>
1431 <listitem><para>
1432 Accept the debug perspective.
1433 </para></listitem>
1434 </orderedlist>
1435 </para>
1436 </section>
1437
1438 <section id='neon-using-Linuxtools'>
1439 <title>Using Linuxtools</title>
1440
1441 <para>
1442 As mentioned earlier in the manual, performance tools exist
1443 (Linuxtools) that enhance your development experience.
1444 These tools are aids in developing and debugging
1445 applications and images.
1446 You can run these tools from within the Eclipse IDE through
1447 the "Linuxtools" menu.
1448 </para>
1449
1450 <para>
1451 For information on how to configure and use these tools,
1452 see
1453 <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
1454 </para>
1455 </section>
1456 </section>
1457 </section>
1458</chapter>
1459<!--
1460vim: expandtab tw=80 ts=4
1461-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 10:23:46 +0000