summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/sdk-extensible.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/sdk-manual/sdk-extensible.xml')
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml566
1 files changed, 517 insertions, 49 deletions
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index c238dee382..bc9ccd28d3 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -6,69 +6,537 @@
6 6
7<title>Using the Extensible SDK</title> 7<title>Using the Extensible SDK</title>
8 8
9<para role='writernotes'> 9<para>
10 This chapter describes what you need on your machine in order to use 10 This chapter describes the extensible SDK and how to use it.
11 an extensible SDK. 11 The extensible SDK makes it easy to add new applications and libraries
12 The chapter does not repeat information that also applies to using the 12 to an image, modify the source for an existing component, test
13 standard SDK. 13 changes on the target hardware, and ease integration into the rest
14 The chapter also includes procedures of tasks you can perform using 14 of the build system.
15 an extensible SDK.
16 <note>
17 The tasks you can perform using a standard SDK are also available
18 using an extensible SDK.
19 For information on using the standard SDK, see the
20 "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>"
21 chapter.
22 </note>
23</para> 15</para>
24 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>
25 26
26<section id='sdk-setting-up-to-use-the-extensible-sdk'> 27<section id='sdk-setting-up-to-use-the-extensible-sdk'>
27 <title>Setting Up to Use the Extensible SDK</title> 28 <title>Setting Up to Use the Extensible SDK</title>
28 29
29 <para role='writernotes'> 30 <para>
30 Here is a list of items I think need addressed in this section: 31 Getting set up to use the extensible SDK is identical to getting set
32 up to use the standard SDK.
33 You still need to locate and run the installer and then run the
34 environment setup script.
35 See the
36 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
37 and the
38 "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
39 sections for general information.
40 The following items highlight the only differences between getting
41 set up to use the extensible SDK as compared to the standard SDK:
31 <itemizedlist> 42 <itemizedlist>
32 <listitem><para role='writernotes'><emphasis>Cover differences in the development 43 <listitem><para><emphasis>Default Installation Directory:</emphasis>
33 that might be impacted because they are using an extensible 44 By default, the extensible SDK installs into the
34 SDK</emphasis></para> 45 <filename>poky_sdk</filename> folder of your home directory.
35 <para role='writernotes'>Presumably, the various development scenarios are 46 As with the standard SDK, you can choose to install the
36 covered regarding setup in the previous chapter. 47 extensible SDK in any location when you run the installer.
37 Are these impacted because the developer is going to now be
38 using an extensible SDK?
39 If so, what are the implications?
40 </para></listitem> 48 </para></listitem>
41 <listitem><para role='writernotes'><emphasis>What new recommendations exist now that 49 <listitem><para><emphasis>Build Tools and Build System:</emphasis>
42 the developer is going to be using an extensible SDK?</emphasis></para> 50 The extensible SDK installer performs additional tasks as
43 <para role='writernotes'>We should cover the most common development scenarios 51 compared to the standard SDK installer.
44 that apply when using an extensible SDK. 52 The extensible SDK installer extracts build tools specific
45 Is there a recommended development flow we want to present 53 to the SDK and the installer also prepares the build system.
46 when using an extensible SDK? 54 Here is example output for running the extensible SDK
47 What conditions in a development scenario warrant use of 55 installer:
48 the extensible SDK as compared to the standard SDK? 56 <literallayout class='monospaced'>
49 </para></listitem> 57 $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.1+snapshot.sh
50 <listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set 58 Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.1+snapshot
51 up the extensible SDK?</emphasis></para> 59 ===================================================================================
52 <para role='writernotes'>Is it just a matter of building out the SDK using 60 Enter target directory for SDK (default: ~/poky_sdk):
53 <filename>bitbake -c populate_sdk_ext</filename>? 61 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
54 Is there a pre-built extensible SDK laying around they can 62 Extracting SDK......................................................................done
55 find and download if they are using a machine that does not 63 Setting it up...
56 have YP installed, which would prevent them from building their 64 Extracting buildtools...
57 own SDK? 65 Preparing build system...
66 done
67 SDK has been successfully set up and is ready to be used.
68 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
69 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
70 </literallayout>
58 </para></listitem> 71 </para></listitem>
59 </itemizedlist> 72 </itemizedlist>
60 </para> 73 </para>
74
75 <para>
76 After installing the SDK, you need to run the SDK environment setup
77 script.
78 Here is the output:
79 <literallayout class='monospaced'>
80 $ source environment-setup-core2-64-poky-linux
81 SDK environment now set up; additionally you may now run devtool to perform development tasks.
82 Run devtool --help for further details.
83 </literallayout>
84 Once you run the environment setup script, you have
85 <filename>devtool</filename> available.
86 </para>
61</section> 87</section>
62 88
63<section id='sdk-using-the-extensible-sdk-to-task-1'> 89<section id='sdk-use-devtool-to-add-an-application'>
64 <title>Using the Extensible SDK to <replaceable>item 1</replaceable></title> 90 <title>Use <filename>devtool add</filename> to Add an Application</title>
65 91
66 <para role='writernotes'> 92 <para>
67 Describe the specific task you are going to accomplish with the 93 The <filename>devtool add</filename> command generates
68 extensible SDK. 94 a new recipe based on existing source code.
69 Provide a diagram showing the rough flow of the task. 95 This command takes advantage of the
70 Provide specific steps using a real example that works through the 96 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
71 task. 97 layer that many <filename>devtool</filename> commands
98 use.
99 The command is flexible enough to allow you to extract source
100 code into both the workspace or a separate local Git repository
101 and to use existing code that does not need to be extracted.
102 </para>
103
104 <para>
105 Depending on your particular scenario, the arguments and options
106 you use with <filename>devtool add</filename> form different
107 combinations.
108 The following diagram shows common development flows
109 you would use with the <filename>devtool add</filename>
110 command:
111 </para>
112
113 <para>
114 <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" />
115 </para>
116
117 <para>
118 <orderedlist>
119 <listitem><para><emphasis>Generating the New Recipe</emphasis>:
120 The top part of the flow shows three scenarios by which
121 you could use <filename>devtool add</filename> to
122 generate a recipe based on existing source code.</para>
123
124 <para>In a shared development environment, it is
125 typical where other developers are responsible for
126 various areas of source code.
127 As a developer, you are probably interested in using
128 that source code as part of your development using
129 the Yocto Project.
130 All you need is access to the code, a recipe, and a
131 controlled area in which to do your work.</para>
132
133 <para>Within the diagram, three possible scenarios
134 feed into the <filename>devtool add</filename> workflow:
135 <itemizedlist>
136 <listitem><para><emphasis>Left</emphasis>:
137 The left scenario represents a common situation
138 where the source code does not exist locally
139 and needs to be extracted.
140 In this situation, you just let it get
141 extracted to the default workspace - you do not
142 want it in some specific location outside of the
143 workspace.
144 Thus, everything you need will be located in the
145 workspace:
146 <literallayout class='monospaced'>
147 $ devtool add <replaceable>recipe fetchuri</replaceable>
148 </literallayout>
149 With this command, <filename>devtool</filename>
150 creates a recipe and an append file in the
151 workspace as well as extracts the upstream
152 source files into a local Git repository also
153 within the <filename>sources</filename> folder.
154 </para></listitem>
155 <listitem><para><emphasis>Middle</emphasis>:
156 The middle scenario also represents a situation where
157 the source code does not exist locally.
158 In this case, the code is again upstream
159 and needs to be extracted to some
160 local area - this time outside of the default
161 workspace.
162 As always, if required <filename>devtool</filename> creates
163 a Git repository locally during the extraction.
164 Furthermore, the first positional argument
165 <replaceable>srctree</replaceable> in this case
166 identifies where the
167 <filename>devtool add</filename> command
168 will locate the extracted code outside of the
169 workspace:
170 <literallayout class='monospaced'>
171 $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
172 </literallayout>
173 In summary, the source code is pulled from
174 <replaceable>fetchuri</replaceable> and extracted
175 into the location defined by
176 <replaceable>srctree</replaceable> as a local
177 Git repository.</para>
178
179 <para>Within workspace, <filename>devtool</filename>
180 creates both the recipe and an append file
181 for the recipe.
182 </para></listitem>
183 <listitem><para><emphasis>Right</emphasis>:
184 The right scenario represents a situation
185 where the source tree (srctree) has been
186 previously prepared outside of the
187 <filename>devtool</filename> workspace.
188 </para>
189
190 <para>The following command names the recipe
191 and identifies where the existing source tree
192 is located:
193 <literallayout class='monospaced'>
194 $ devtool add <replaceable>recipe srctree</replaceable>
195 </literallayout>
196 The command examines the source code and creates
197 a recipe for it placing the recipe into the
198 workspace.</para>
199
200 <para>Because the extracted source code already exists,
201 <filename>devtool</filename> does not try to
202 relocate it into the workspace - just the new
203 the recipe is placed in the workspace.</para>
204
205 <para>Aside from a recipe folder, the command
206 also creates an append folder and places an initial
207 <filename>*.bbappend</filename> within.
208 </para></listitem>
209 </itemizedlist>
210 </para></listitem>
211 <listitem><para><emphasis>Edit the Recipe</emphasis>:
212 At this point, you can use <filename>devtool edit-recipe</filename>
213 to open up the editor as defined by the
214 <filename>$EDITOR</filename> environment variable
215 and modify the file:
216 <literallayout class='monospaced'>
217 $ devtool edit-recipe <replaceable>recipe</replaceable>
218 </literallayout>
219 From within the editor, you can make modifications to the
220 recipe that take affect when you build it later.
221 </para></listitem>
222 <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:
223 At this point in the flow, the next step you
224 take depends on what you are going to do with
225 the new code.</para>
226 <para>If you need to take the build output and eventually
227 move it to the target hardware, you would use
228 <filename>devtool build</filename>:
229 <note>
230 You could use <filename>bitbake</filename> to build
231 the recipe as well.
232 </note>
233 <literallayout class='monospaced'>
234 $ devtool build <replaceable>recipe</replaceable>
235 </literallayout></para>
236 <para>On the other hand, if you want an image to
237 contain the recipe's packages for immediate deployment
238 onto a device (e.g. for testing purposes), you can use
239 the <filename>devtool build-image</filename> command:
240 <literallayout class='monospaced'>
241 $ devtool build-image <replaceable>image</replaceable>
242 </literallayout>
243 </para></listitem>
244 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
245 When you use the <filename>devtool build</filename>
246 command to build out your recipe, you probably want to
247 see if the resulting build output works as expected on target
248 hardware.
249 <note>
250 This step assumes you have a previously built
251 image that is already either running in QEMU or
252 running on actual hardware.
253 Also, it is assumed that for deployment of the image
254 to the target, SSH is installed in the image and if
255 the image is running on real hardware that you have
256 network access to and from your development machine.
257 </note>
258 You can deploy your build output to that target hardware by
259 using the <filename>devtool deploy-target</filename> command:
260 <literallayout class='monospaced'>
261 $ devtool deploy-target <replaceable>recipe target</replaceable>
262 </literallayout>
263 The <replaceable>target</replaceable> is a live target machine
264 running as an SSH server.</para>
265
266 <para>You can, of course, also deploy the image you build
267 using the <filename>devtool build-image</filename> command
268 to actual hardware.
269 However, <filename>devtool</filename> does not provide a
270 specific command that allows you to do this.
271 </para></listitem>
272 <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>:
273 Once you are satisfied with the recipe, if you have made
274 any changes to the source tree that you want to have
275 applied by the recipe, you need to generate patches
276 from those changes.
277 You do this before moving the recipe
278 to its final layer and cleaning up the workspace area
279 <filename>devtool</filename> uses.
280 This optional step is especially relevant if you are
281 using or adding third-party software.</para>
282 <para>To convert commits created using Git to patch files,
283 use the <filename>devtool update-recipe</filename> command.
284 <note>
285 Any changes you want to turn into patches must be
286 committed to the Git repository in the source tree.
287 </note>
288 <literallayout class='monospaced'>
289 $ devtool update-recipe <replaceable>recipe</replaceable>
290 </literallayout>
291 </para></listitem>
292 <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:
293 Before cleaning up the workspace, you need to move the
294 final recipe to its permanent layer.
295 You must do this before using the
296 <filename>devtool reset</filename> command if you want to
297 retain the recipe.
298 </para></listitem>
299 <listitem><para><emphasis>Reset the Recipe</emphasis>:
300 As a final step, you can restore the state such that
301 standard layers and the upstream source is used to build
302 the recipe rather than data in the workspace.
303 To reset the recipe, use the <filename>devtool reset</filename>
304 command:
305 <literallayout class='monospaced'>
306 $ devtool reset <replaceable>recipe</replaceable>
307 </literallayout>
308 </para></listitem>
309 </orderedlist>
310 </para>
311</section>
312
313<section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>
314 <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title>
315
316 <para>
317 The <filename>devtool modify</filename> command prepares the
318 way to work on existing code that already has a recipe in
319 place.
320 The command is flexible enough to allow you to extract code,
321 specify the existing recipe, and keep track of and gather any
322 patch files from other developers that are
323 associated with the code.
324 </para>
325
326 <para>
327 Depending on your particular scenario, the arguments and options
328 you use with <filename>devtool modify</filename> form different
329 combinations.
330 The following diagram shows common development flows
331 you would use with the <filename>devtool modify</filename>
332 command:
333 </para>
334
335 <para>
336 <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" />
337 </para>
338
339 <para>
340 <orderedlist>
341 <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
342 The top part of the flow shows three scenarios by which
343 you could use <filename>devtool modify</filename> to
344 prepare to work on source files.
345 Each scenario assumes the following:
346 <itemizedlist>
347 <listitem><para>The recipe exists in some layer external
348 to the <filename>devtool</filename> workspace.
349 </para></listitem>
350 <listitem><para>The source files exist upstream in an
351 un-extracted state or locally in a previously
352 extracted state.
353 </para></listitem>
354 </itemizedlist>
355 The typical situation is where another developer has
356 created some layer for use with the Yocto Project and
357 their recipe already resides in that layer.
358 Furthermore, their source code is readily available
359 either upstream or locally.
360 <itemizedlist>
361 <listitem><para><emphasis>Left</emphasis>:
362 The left scenario represents a common situation
363 where the source code does not exist locally
364 and needs to be extracted.
365 In this situation, the source is extracted
366 into the default workspace location.
367 The recipe, in this scenario, is in its own
368 layer outside the workspace
369 (i.e.
370 <filename>meta-</filename><replaceable>layername</replaceable>).
371 </para>
372
373 <para>The following command identifies the recipe
374 and by default extracts the source files:
375 <literallayout class='monospaced'>
376 $ devtool modify <replaceable>recipe</replaceable>
377 </literallayout>
378 Once <filename>devtool</filename>locates the recipe,
379 it uses the
380 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
381 variable to locate the source code and
382 any local patch files from other developers are
383 located.
384 <note>
385 You cannot provide an URL for
386 <replaceable>srctree</replaceable> when using the
387 <filename>devtool modify</filename> command.
388 </note>
389 With this scenario, however, since no
390 <replaceable>srctree</replaceable> argument exists, the
391 <filename>devtool modify</filename> command by default
392 extracts the source files to a Git structure.
393 Furthermore, the location for the extracted source is the
394 default area within the workspace.
395 The result is that the command sets up both the source
396 code and an append file within the workspace with the
397 recipe remaining in its original location.
398 </para></listitem>
399 <listitem><para><emphasis>Middle</emphasis>:
400 The middle scenario represents a situation where
401 the source code also does not exist locally.
402 In this case, the code is again upstream
403 and needs to be extracted to some
404 local area as a Git repository.
405 The recipe, in this scenario, is again in its own
406 layer outside the workspace.</para>
407
408 <para>The following command tells
409 <filename>devtool</filename> what recipe with
410 which to work and, in this case, identifies a local
411 area for the extracted source files that is outside
412 of the default workspace:
413 <literallayout class='monospaced'>
414 $ devtool modify <replaceable>recipe srctree</replaceable>
415 </literallayout>
416 As with all extractions, the command uses
417 the recipe's <filename>SRC_URI</filename> to locate the
418 source files.
419 Once the files are located, the command by default
420 extracts them.
421 Providing the <replaceable>srctree</replaceable>
422 argument instructs <filename>devtool</filename> where
423 place the extracted source.</para>
424
425 <para>Within workspace, <filename>devtool</filename>
426 creates an append file for the recipe.
427 The recipe remains in its original location but
428 the source files are extracted to the location you
429 provided with <replaceable>srctree</replaceable>.
430 </para></listitem>
431 <listitem><para><emphasis>Right</emphasis>:
432 The right scenario represents a situation
433 where the source tree
434 (<replaceable>srctree</replaceable>) exists as a
435 previously extracted Git structure outside of
436 the <filename>devtool</filename> workspace.
437 In this example, the recipe also exists
438 elsewhere in its own layer.
439 </para>
440
441 <para>The following command tells
442 <filename>devtool</filename> the recipe
443 with which to work, uses the "-n" option to indicate
444 source does not need to be extracted, and uses
445 <replaceable>srctree</replaceable> to point to the
446 previously extracted source files:
447 <literallayout class='monospaced'>
448 $ devtool modify -n <replaceable>recipe srctree</replaceable>
449 </literallayout>
450 </para>
451
452 <para>Once the command finishes, it creates only
453 an append file for the recipe in the workspace.
454 The recipe and the source code remain in their
455 original locations.
456 </para></listitem>
457 </itemizedlist>
458 </para></listitem>
459 <listitem><para><emphasis>Edit the Source</emphasis>:
460 Once you have used the <filename>devtool modify</filename>
461 command, you are free to make changes to the source
462 files.
463 You can use any editor you like to make and save
464 your source code modifications.
465 </para></listitem>
466 <listitem><para><emphasis>Build the Recipe</emphasis>:
467 Once you have updated the source files, you can build
468 the recipe.
469 You can either use <filename>devtool build</filename> or
470 <filename>bitbake</filename>.
471 Either method produces build output that is stored
472 in
473 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
474 </para></listitem>
475 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
476 When you use the <filename>devtool build</filename>
477 command or <filename>bitbake</filename> to build out your
478 recipe, you probably want to see if the resulting build
479 output works as expected on target hardware.
480 <note>
481 This step assumes you have a previously built
482 image that is already either running in QEMU or
483 running on actual hardware.
484 Also, it is assumed that for deployment of the image
485 to the target, SSH is installed in the image and if
486 the image is running on real hardware that you have
487 network access to and from your development machine.
488 </note>
489 You can deploy your build output to that target hardware by
490 using the <filename>devtool deploy-target</filename> command:
491 <literallayout class='monospaced'>
492 $ devtool deploy-target <replaceable>recipe target</replaceable>
493 </literallayout>
494 The <replaceable>target</replaceable> is a live target machine
495 running as an SSH server.</para>
496
497 <para>You can, of course, also deploy the image you build
498 using the <filename>devtool build-image</filename> command
499 to actual hardware.
500 However, <filename>devtool</filename> does not provide a
501 specific command that allows you to do this.
502 </para></listitem>
503 <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
504 After you have debugged your changes, you can
505 use <filename>devtool update-recipe</filename> to
506 generate patch files for all the commits you have
507 made.
508 <note>
509 Patch files are generated only for changes
510 you have committed.
511 </note>
512 <literallayout class='monospaced'>
513 $ devtool update-recipe <replaceable>recipe</replaceable>
514 </literallayout>
515 By default, the
516 <filename>devtool update-recipe</filename> command
517 creates the patch files in a folder named the same
518 as the recipe beneath the folder in which the recipe
519 resides, and updates the recipe's
520 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
521 statement to point to the generated patch files.
522 <note>
523 You can use the
524 "--append <replaceable>LAYERDIR</replaceable>"
525 option to cause the command to create append files
526 in a specific layer rather than the default
527 recipe layer.
528 </note>
529 </para></listitem>
530 <listitem><para><emphasis>Restore the Workspace</emphasis>:
531 The <filename>devtool reset</filename> restores the
532 state so that standard layers and upstream sources are
533 used to build the recipe rather than what is in the
534 workspace.
535 <literallayout class='monospaced'>
536 $ devtool reset <replaceable>recipe</replaceable>
537 </literallayout>
538 </para></listitem>
539 </orderedlist>
72 </para> 540 </para>
73</section> 541</section>
74 542