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.xml891
1 files changed, 458 insertions, 433 deletions
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index f9f04072d7..58d2aec977 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -10,8 +10,8 @@
10 This chapter describes the extensible SDK and how to use it. 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 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 12 to an image, modify the source for an existing component, test
13 changes on the target hardware, and ease integration into the rest 13 changes on the target hardware, and ease integration into the rest of the
14 of the build system. 14 <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
15</para> 15</para>
16 16
17<para> 17<para>
@@ -45,12 +45,17 @@
45 <filename>poky_sdk</filename> folder of your home directory. 45 <filename>poky_sdk</filename> folder of your home directory.
46 As with the standard SDK, you can choose to install the 46 As with the standard SDK, you can choose to install the
47 extensible SDK in any location when you run the installer. 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.
48 </para></listitem> 52 </para></listitem>
49 <listitem><para><emphasis>Build Tools and Build System:</emphasis> 53 <listitem><para><emphasis>Build Tools and Build System:</emphasis>
50 The extensible SDK installer performs additional tasks as 54 The extensible SDK installer performs additional tasks as
51 compared to the standard SDK installer. 55 compared to the standard SDK installer.
52 The extensible SDK installer extracts build tools specific 56 The extensible SDK installer extracts build tools specific
53 to the SDK and the installer also prepares the build system. 57 to the SDK and the installer also prepares the OpenEmbedded
58 build system.
54 Here is example output for running the extensible SDK 59 Here is example output for running the extensible SDK
55 installer: 60 installer:
56 <literallayout class='monospaced'> 61 <literallayout class='monospaced'>
@@ -86,458 +91,478 @@
86 </para> 91 </para>
87</section> 92</section>
88 93
89<section id='sdk-use-devtool-to-add-an-application'> 94<section id='using-devtool-in-your-sdk-workflow'>
90 <title>Use <filename>devtool add</filename> to Add an Application</title> 95 <title>Using <filename>devtool</filename> in Your SDK Workflow</title>
91 96
92 <para> 97 <para>
93 The <filename>devtool add</filename> command generates 98 <filename>devtool</filename> helps you easily develop projects whose
94 a new recipe based on existing source code. 99 build output must be part of an image built using the OpenEmbedded
95 This command takes advantage of the 100 build system.
96 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
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> 101 </para>
103 102
104 <para> 103 <para>
105 Depending on your particular scenario, the arguments and options 104 These entry points exist that allow you to develop using
106 you use with <filename>devtool add</filename> form different 105 <filename>devtool</filename>:
107 combinations. 106 <itemizedlist>
108 The following diagram shows common development flows 107 <listitem><para><emphasis><filename>devtool add</filename></emphasis>
109 you would use with the <filename>devtool add</filename> 108 </para></listitem>
110 command: 109 <listitem><para><emphasis><filename>devtool modify</filename></emphasis>
110 </para></listitem>
111 </itemizedlist>
111 </para> 112 </para>
112 113
113 <para> 114 <para>
114 <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" /> 115 The remainder of this section presents these workflows.
115 </para> 116 </para>
116 117
117 <para> 118 <section id='sdk-use-devtool-to-add-an-application'>
118 <orderedlist> 119 <title>Use <filename>devtool add</filename> to Add an Application</title>
119 <listitem><para><emphasis>Generating the New Recipe</emphasis>: 120
120 The top part of the flow shows three scenarios by which 121 <para>
121 you could use <filename>devtool add</filename> to 122 The <filename>devtool add</filename> command generates
122 generate a recipe based on existing source code.</para> 123 a new recipe based on existing source code.
123 124 This command takes advantage of the
124 <para>In a shared development environment, it is 125 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
125 typical where other developers are responsible for 126 layer that many <filename>devtool</filename> commands
126 various areas of source code. 127 use.
127 As a developer, you are probably interested in using 128 The command is flexible enough to allow you to extract source
128 that source code as part of your development using 129 code into both the workspace or a separate local Git repository
129 the Yocto Project. 130 and to use existing code that does not need to be extracted.
130 All you need is access to the code, a recipe, and a 131 </para>
131 controlled area in which to do your work.</para> 132
132 133 <para>
133 <para>Within the diagram, three possible scenarios 134 Depending on your particular scenario, the arguments and options
134 feed into the <filename>devtool add</filename> workflow: 135 you use with <filename>devtool add</filename> form different
135 <itemizedlist> 136 combinations.
136 <listitem><para><emphasis>Left</emphasis>: 137 The following diagram shows common development flows
137 The left scenario represents a common situation 138 you would use with the <filename>devtool add</filename>
138 where the source code does not exist locally 139 command:
139 and needs to be extracted. 140 </para>
140 In this situation, you just let it get 141
141 extracted to the default workspace - you do not 142 <para>
142 want it in some specific location outside of the 143 <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" />
143 workspace. 144 </para>
144 Thus, everything you need will be located in the 145
145 workspace: 146 <para>
146 <literallayout class='monospaced'> 147 <orderedlist>
148 <listitem><para><emphasis>Generating the New Recipe</emphasis>:
149 The top part of the flow shows three scenarios by which
150 you could use <filename>devtool add</filename> to
151 generate a recipe based on existing source code.</para>
152
153 <para>In a shared development environment, it is
154 typical where other developers are responsible for
155 various areas of source code.
156 As a developer, you are probably interested in using
157 that source code as part of your development using
158 the Yocto Project.
159 All you need is access to the code, a recipe, and a
160 controlled area in which to do your work.</para>
161
162 <para>Within the diagram, three possible scenarios
163 feed into the <filename>devtool add</filename> workflow:
164 <itemizedlist>
165 <listitem><para><emphasis>Left</emphasis>:
166 The left scenario represents a common situation
167 where the source code does not exist locally
168 and needs to be extracted.
169 In this situation, you just let it get
170 extracted to the default workspace - you do not
171 want it in some specific location outside of the
172 workspace.
173 Thus, everything you need will be located in the
174 workspace:
175 <literallayout class='monospaced'>
147 $ devtool add <replaceable>recipe fetchuri</replaceable> 176 $ devtool add <replaceable>recipe fetchuri</replaceable>
148 </literallayout> 177 </literallayout>
149 With this command, <filename>devtool</filename> 178 With this command, <filename>devtool</filename>
150 creates a recipe and an append file in the 179 creates a recipe and an append file in the
151 workspace as well as extracts the upstream 180 workspace as well as extracts the upstream
152 source files into a local Git repository also 181 source files into a local Git repository also
153 within the <filename>sources</filename> folder. 182 within the <filename>sources</filename> folder.
154 </para></listitem> 183 </para></listitem>
155 <listitem><para><emphasis>Middle</emphasis>: 184 <listitem><para><emphasis>Middle</emphasis>:
156 The middle scenario also represents a situation where 185 The middle scenario also represents a situation where
157 the source code does not exist locally. 186 the source code does not exist locally.
158 In this case, the code is again upstream 187 In this case, the code is again upstream
159 and needs to be extracted to some 188 and needs to be extracted to some
160 local area - this time outside of the default 189 local area - this time outside of the default
161 workspace. 190 workspace.
162 As always, if required <filename>devtool</filename> creates 191 As always, if required <filename>devtool</filename> creates
163 a Git repository locally during the extraction. 192 a Git repository locally during the extraction.
164 Furthermore, the first positional argument 193 Furthermore, the first positional argument
165 <replaceable>srctree</replaceable> in this case 194 <replaceable>srctree</replaceable> in this case
166 identifies where the 195 identifies where the
167 <filename>devtool add</filename> command 196 <filename>devtool add</filename> command
168 will locate the extracted code outside of the 197 will locate the extracted code outside of the
169 workspace: 198 workspace:
170 <literallayout class='monospaced'> 199 <literallayout class='monospaced'>
171 $ devtool add <replaceable>recipe srctree fetchuri</replaceable> 200 $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
172 </literallayout> 201 </literallayout>
173 In summary, the source code is pulled from 202 In summary, the source code is pulled from
174 <replaceable>fetchuri</replaceable> and extracted 203 <replaceable>fetchuri</replaceable> and extracted
175 into the location defined by 204 into the location defined by
176 <replaceable>srctree</replaceable> as a local 205 <replaceable>srctree</replaceable> as a local
177 Git repository.</para> 206 Git repository.</para>
178 207
179 <para>Within workspace, <filename>devtool</filename> 208 <para>Within workspace, <filename>devtool</filename>
180 creates both the recipe and an append file 209 creates both the recipe and an append file
181 for the recipe. 210 for the recipe.
182 </para></listitem> 211 </para></listitem>
183 <listitem><para><emphasis>Right</emphasis>: 212 <listitem><para><emphasis>Right</emphasis>:
184 The right scenario represents a situation 213 The right scenario represents a situation
185 where the source tree (srctree) has been 214 where the source tree (srctree) has been
186 previously prepared outside of the 215 previously prepared outside of the
187 <filename>devtool</filename> workspace. 216 <filename>devtool</filename> workspace.
188 </para> 217 </para>
189 218
190 <para>The following command names the recipe 219 <para>The following command names the recipe
191 and identifies where the existing source tree 220 and identifies where the existing source tree
192 is located: 221 is located:
193 <literallayout class='monospaced'> 222 <literallayout class='monospaced'>
194 $ devtool add <replaceable>recipe srctree</replaceable> 223 $ devtool add <replaceable>recipe srctree</replaceable>
195 </literallayout> 224 </literallayout>
196 The command examines the source code and creates 225 The command examines the source code and creates
197 a recipe for it placing the recipe into the 226 a recipe for it placing the recipe into the
198 workspace.</para> 227 workspace.</para>
199 228
200 <para>Because the extracted source code already exists, 229 <para>Because the extracted source code already exists,
201 <filename>devtool</filename> does not try to 230 <filename>devtool</filename> does not try to
202 relocate it into the workspace - just the new 231 relocate it into the workspace - just the new
203 the recipe is placed in the workspace.</para> 232 the recipe is placed in the workspace.</para>
204 233
205 <para>Aside from a recipe folder, the command 234 <para>Aside from a recipe folder, the command
206 also creates an append folder and places an initial 235 also creates an append folder and places an initial
207 <filename>*.bbappend</filename> within. 236 <filename>*.bbappend</filename> within.
208 </para></listitem> 237 </para></listitem>
209 </itemizedlist> 238 </itemizedlist>
210 </para></listitem> 239 </para></listitem>
211 <listitem><para><emphasis>Edit the Recipe</emphasis>: 240 <listitem><para><emphasis>Edit the Recipe</emphasis>:
212 At this point, you can use <filename>devtool edit-recipe</filename> 241 At this point, you can use <filename>devtool edit-recipe</filename>
213 to open up the editor as defined by the 242 to open up the editor as defined by the
214 <filename>$EDITOR</filename> environment variable 243 <filename>$EDITOR</filename> environment variable
215 and modify the file: 244 and modify the file:
216 <literallayout class='monospaced'> 245 <literallayout class='monospaced'>
217 $ devtool edit-recipe <replaceable>recipe</replaceable> 246 $ devtool edit-recipe <replaceable>recipe</replaceable>
218 </literallayout> 247 </literallayout>
219 From within the editor, you can make modifications to the 248 From within the editor, you can make modifications to the
220 recipe that take affect when you build it later. 249 recipe that take affect when you build it later.
221 </para></listitem> 250 </para></listitem>
222 <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>: 251 <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:
223 At this point in the flow, the next step you 252 At this point in the flow, the next step you
224 take depends on what you are going to do with 253 take depends on what you are going to do with
225 the new code.</para> 254 the new code.</para>
226 <para>If you need to take the build output and eventually 255 <para>If you need to take the build output and eventually
227 move it to the target hardware, you would use 256 move it to the target hardware, you would use
228 <filename>devtool build</filename>: 257 <filename>devtool build</filename>:
229 <note> 258 <note>
230 You could use <filename>bitbake</filename> to build 259 You could use <filename>bitbake</filename> to build
231 the recipe as well. 260 the recipe as well.
232 </note> 261 </note>
233 <literallayout class='monospaced'> 262 <literallayout class='monospaced'>
234 $ devtool build <replaceable>recipe</replaceable> 263 $ devtool build <replaceable>recipe</replaceable>
235 </literallayout></para> 264 </literallayout></para>
236 <para>On the other hand, if you want an image to 265 <para>On the other hand, if you want an image to
237 contain the recipe's packages for immediate deployment 266 contain the recipe's packages for immediate deployment
238 onto a device (e.g. for testing purposes), you can use 267 onto a device (e.g. for testing purposes), you can use
239 the <filename>devtool build-image</filename> command: 268 the <filename>devtool build-image</filename> command:
240 <literallayout class='monospaced'> 269 <literallayout class='monospaced'>
241 $ devtool build-image <replaceable>image</replaceable> 270 $ devtool build-image <replaceable>image</replaceable>
242 </literallayout> 271 </literallayout>
243 </para></listitem> 272 </para></listitem>
244 <listitem><para><emphasis>Deploy the Build Output</emphasis>: 273 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
245 When you use the <filename>devtool build</filename> 274 When you use the <filename>devtool build</filename>
246 command to build out your recipe, you probably want to 275 command to build out your recipe, you probably want to
247 see if the resulting build output works as expected on target 276 see if the resulting build output works as expected on target
248 hardware. 277 hardware.
249 <note> 278 <note>
250 This step assumes you have a previously built 279 This step assumes you have a previously built
251 image that is already either running in QEMU or 280 image that is already either running in QEMU or
252 running on actual hardware. 281 running on actual hardware.
253 Also, it is assumed that for deployment of the image 282 Also, it is assumed that for deployment of the image
254 to the target, SSH is installed in the image and if 283 to the target, SSH is installed in the image and if
255 the image is running on real hardware that you have 284 the image is running on real hardware that you have
256 network access to and from your development machine. 285 network access to and from your development machine.
257 </note> 286 </note>
258 You can deploy your build output to that target hardware by 287 You can deploy your build output to that target hardware by
259 using the <filename>devtool deploy-target</filename> command: 288 using the <filename>devtool deploy-target</filename> command:
260 <literallayout class='monospaced'> 289 <literallayout class='monospaced'>
261 $ devtool deploy-target <replaceable>recipe target</replaceable> 290 $ devtool deploy-target <replaceable>recipe target</replaceable>
262 </literallayout> 291 </literallayout>
263 The <replaceable>target</replaceable> is a live target machine 292 The <replaceable>target</replaceable> is a live target machine
264 running as an SSH server.</para> 293 running as an SSH server.</para>
265 294
266 <para>You can, of course, also deploy the image you build 295 <para>You can, of course, also deploy the image you build
267 using the <filename>devtool build-image</filename> command 296 using the <filename>devtool build-image</filename> command
268 to actual hardware. 297 to actual hardware.
269 However, <filename>devtool</filename> does not provide a 298 However, <filename>devtool</filename> does not provide a
270 specific command that allows you to do this. 299 specific command that allows you to do this.
271 </para></listitem> 300 </para></listitem>
272 <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>: 301 <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>:
273 Once you are satisfied with the recipe, if you have made 302 Once you are satisfied with the recipe, if you have made
274 any changes to the source tree that you want to have 303 any changes to the source tree that you want to have
275 applied by the recipe, you need to generate patches 304 applied by the recipe, you need to generate patches
276 from those changes. 305 from those changes.
277 You do this before moving the recipe 306 You do this before moving the recipe
278 to its final layer and cleaning up the workspace area 307 to its final layer and cleaning up the workspace area
279 <filename>devtool</filename> uses. 308 <filename>devtool</filename> uses.
280 This optional step is especially relevant if you are 309 This optional step is especially relevant if you are
281 using or adding third-party software.</para> 310 using or adding third-party software.</para>
282 <para>To convert commits created using Git to patch files, 311 <para>To convert commits created using Git to patch files,
283 use the <filename>devtool update-recipe</filename> command. 312 use the <filename>devtool update-recipe</filename> command.
284 <note> 313 <note>
285 Any changes you want to turn into patches must be 314 Any changes you want to turn into patches must be
286 committed to the Git repository in the source tree. 315 committed to the Git repository in the source tree.
287 </note> 316 </note>
288 <literallayout class='monospaced'> 317 <literallayout class='monospaced'>
289 $ devtool update-recipe <replaceable>recipe</replaceable> 318 $ devtool update-recipe <replaceable>recipe</replaceable>
290 </literallayout> 319 </literallayout>
291 </para></listitem> 320 </para></listitem>
292 <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>: 321 <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:
293 Before cleaning up the workspace, you need to move the 322 Before cleaning up the workspace, you need to move the
294 final recipe to its permanent layer. 323 final recipe to its permanent layer.
295 You must do this before using the 324 You must do this before using the
296 <filename>devtool reset</filename> command if you want to 325 <filename>devtool reset</filename> command if you want to
297 retain the recipe. 326 retain the recipe.
298 </para></listitem> 327 </para></listitem>
299 <listitem><para><emphasis>Reset the Recipe</emphasis>: 328 <listitem><para><emphasis>Reset the Recipe</emphasis>:
300 As a final step, you can restore the state such that 329 As a final step, you can restore the state such that
301 standard layers and the upstream source is used to build 330 standard layers and the upstream source is used to build
302 the recipe rather than data in the workspace. 331 the recipe rather than data in the workspace.
303 To reset the recipe, use the <filename>devtool reset</filename> 332 To reset the recipe, use the <filename>devtool reset</filename>
304 command: 333 command:
305 <literallayout class='monospaced'> 334 <literallayout class='monospaced'>
306 $ devtool reset <replaceable>recipe</replaceable> 335 $ devtool reset <replaceable>recipe</replaceable>
307 </literallayout> 336 </literallayout>
308 </para></listitem> 337 </para></listitem>
309 </orderedlist> 338 </orderedlist>
310 </para> 339 </para>
311</section> 340 </section>
312 341
313<section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'> 342 <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> 343 <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title>
315 344
316 <para> 345 <para>
317 The <filename>devtool modify</filename> command prepares the 346 The <filename>devtool modify</filename> command prepares the
318 way to work on existing code that already has a recipe in 347 way to work on existing code that already has a recipe in
319 place. 348 place.
320 The command is flexible enough to allow you to extract code, 349 The command is flexible enough to allow you to extract code,
321 specify the existing recipe, and keep track of and gather any 350 specify the existing recipe, and keep track of and gather any
322 patch files from other developers that are 351 patch files from other developers that are
323 associated with the code. 352 associated with the code.
324 </para> 353 </para>
325 354
326 <para> 355 <para>
327 Depending on your particular scenario, the arguments and options 356 Depending on your particular scenario, the arguments and options
328 you use with <filename>devtool modify</filename> form different 357 you use with <filename>devtool modify</filename> form different
329 combinations. 358 combinations.
330 The following diagram shows common development flows 359 The following diagram shows common development flows
331 you would use with the <filename>devtool modify</filename> 360 you would use with the <filename>devtool modify</filename>
332 command: 361 command:
333 </para> 362 </para>
334 363
335 <para> 364 <para>
336 <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" /> 365 <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" />
337 </para> 366 </para>
338 367
339 <para> 368 <para>
340 <orderedlist> 369 <orderedlist>
341 <listitem><para><emphasis>Preparing to Modify the Code</emphasis>: 370 <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
342 The top part of the flow shows three scenarios by which 371 The top part of the flow shows three scenarios by which
343 you could use <filename>devtool modify</filename> to 372 you could use <filename>devtool modify</filename> to
344 prepare to work on source files. 373 prepare to work on source files.
345 Each scenario assumes the following: 374 Each scenario assumes the following:
346 <itemizedlist> 375 <itemizedlist>
347 <listitem><para>The recipe exists in some layer external 376 <listitem><para>The recipe exists in some layer external
348 to the <filename>devtool</filename> workspace. 377 to the <filename>devtool</filename> workspace.
349 </para></listitem> 378 </para></listitem>
350 <listitem><para>The source files exist upstream in an 379 <listitem><para>The source files exist upstream in an
351 un-extracted state or locally in a previously 380 un-extracted state or locally in a previously
352 extracted state. 381 extracted state.
353 </para></listitem> 382 </para></listitem>
354 </itemizedlist> 383 </itemizedlist>
355 The typical situation is where another developer has 384 The typical situation is where another developer has
356 created some layer for use with the Yocto Project and 385 created some layer for use with the Yocto Project and
357 their recipe already resides in that layer. 386 their recipe already resides in that layer.
358 Furthermore, their source code is readily available 387 Furthermore, their source code is readily available
359 either upstream or locally. 388 either upstream or locally.
360 <itemizedlist> 389 <itemizedlist>
361 <listitem><para><emphasis>Left</emphasis>: 390 <listitem><para><emphasis>Left</emphasis>:
362 The left scenario represents a common situation 391 The left scenario represents a common situation
363 where the source code does not exist locally 392 where the source code does not exist locally
364 and needs to be extracted. 393 and needs to be extracted.
365 In this situation, the source is extracted 394 In this situation, the source is extracted
366 into the default workspace location. 395 into the default workspace location.
367 The recipe, in this scenario, is in its own 396 The recipe, in this scenario, is in its own
368 layer outside the workspace 397 layer outside the workspace
369 (i.e. 398 (i.e.
370 <filename>meta-</filename><replaceable>layername</replaceable>). 399 <filename>meta-</filename><replaceable>layername</replaceable>).
371 </para> 400 </para>
372 401
373 <para>The following command identifies the recipe 402 <para>The following command identifies the recipe
374 and by default extracts the source files: 403 and by default extracts the source files:
375 <literallayout class='monospaced'> 404 <literallayout class='monospaced'>
376 $ devtool modify <replaceable>recipe</replaceable> 405 $ devtool modify <replaceable>recipe</replaceable>
377 </literallayout> 406 </literallayout>
378 Once <filename>devtool</filename>locates the recipe, 407 Once <filename>devtool</filename>locates the recipe,
379 it uses the 408 it uses the
380 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 409 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
381 variable to locate the source code and 410 variable to locate the source code and
382 any local patch files from other developers are 411 any local patch files from other developers are
383 located. 412 located.
384 <note> 413 <note>
385 You cannot provide an URL for 414 You cannot provide an URL for
386 <replaceable>srctree</replaceable> when using the 415 <replaceable>srctree</replaceable> when using the
387 <filename>devtool modify</filename> command. 416 <filename>devtool modify</filename> command.
388 </note> 417 </note>
389 With this scenario, however, since no 418 With this scenario, however, since no
390 <replaceable>srctree</replaceable> argument exists, the 419 <replaceable>srctree</replaceable> argument exists, the
391 <filename>devtool modify</filename> command by default 420 <filename>devtool modify</filename> command by default
392 extracts the source files to a Git structure. 421 extracts the source files to a Git structure.
393 Furthermore, the location for the extracted source is the 422 Furthermore, the location for the extracted source is the
394 default area within the workspace. 423 default area within the workspace.
395 The result is that the command sets up both the source 424 The result is that the command sets up both the source
396 code and an append file within the workspace with the 425 code and an append file within the workspace with the
397 recipe remaining in its original location. 426 recipe remaining in its original location.
398 </para></listitem> 427 </para></listitem>
399 <listitem><para><emphasis>Middle</emphasis>: 428 <listitem><para><emphasis>Middle</emphasis>:
400 The middle scenario represents a situation where 429 The middle scenario represents a situation where
401 the source code also does not exist locally. 430 the source code also does not exist locally.
402 In this case, the code is again upstream 431 In this case, the code is again upstream
403 and needs to be extracted to some 432 and needs to be extracted to some
404 local area as a Git repository. 433 local area as a Git repository.
405 The recipe, in this scenario, is again in its own 434 The recipe, in this scenario, is again in its own
406 layer outside the workspace.</para> 435 layer outside the workspace.</para>
407 436
408 <para>The following command tells 437 <para>The following command tells
409 <filename>devtool</filename> what recipe with 438 <filename>devtool</filename> what recipe with
410 which to work and, in this case, identifies a local 439 which to work and, in this case, identifies a local
411 area for the extracted source files that is outside 440 area for the extracted source files that is outside
412 of the default workspace: 441 of the default workspace:
413 <literallayout class='monospaced'> 442 <literallayout class='monospaced'>
414 $ devtool modify <replaceable>recipe srctree</replaceable> 443 $ devtool modify <replaceable>recipe srctree</replaceable>
415 </literallayout> 444 </literallayout>
416 As with all extractions, the command uses 445 As with all extractions, the command uses
417 the recipe's <filename>SRC_URI</filename> to locate the 446 the recipe's <filename>SRC_URI</filename> to locate the
418 source files. 447 source files.
419 Once the files are located, the command by default 448 Once the files are located, the command by default
420 extracts them. 449 extracts them.
421 Providing the <replaceable>srctree</replaceable> 450 Providing the <replaceable>srctree</replaceable>
422 argument instructs <filename>devtool</filename> where 451 argument instructs <filename>devtool</filename> where
423 place the extracted source.</para> 452 place the extracted source.</para>
424 453
425 <para>Within workspace, <filename>devtool</filename> 454 <para>Within workspace, <filename>devtool</filename>
426 creates an append file for the recipe. 455 creates an append file for the recipe.
427 The recipe remains in its original location but 456 The recipe remains in its original location but
428 the source files are extracted to the location you 457 the source files are extracted to the location you
429 provided with <replaceable>srctree</replaceable>. 458 provided with <replaceable>srctree</replaceable>.
430 </para></listitem> 459 </para></listitem>
431 <listitem><para><emphasis>Right</emphasis>: 460 <listitem><para><emphasis>Right</emphasis>:
432 The right scenario represents a situation 461 The right scenario represents a situation
433 where the source tree 462 where the source tree
434 (<replaceable>srctree</replaceable>) exists as a 463 (<replaceable>srctree</replaceable>) exists as a
435 previously extracted Git structure outside of 464 previously extracted Git structure outside of
436 the <filename>devtool</filename> workspace. 465 the <filename>devtool</filename> workspace.
437 In this example, the recipe also exists 466 In this example, the recipe also exists
438 elsewhere in its own layer. 467 elsewhere in its own layer.
439 </para> 468 </para>
440 469
441 <para>The following command tells 470 <para>The following command tells
442 <filename>devtool</filename> the recipe 471 <filename>devtool</filename> the recipe
443 with which to work, uses the "-n" option to indicate 472 with which to work, uses the "-n" option to indicate
444 source does not need to be extracted, and uses 473 source does not need to be extracted, and uses
445 <replaceable>srctree</replaceable> to point to the 474 <replaceable>srctree</replaceable> to point to the
446 previously extracted source files: 475 previously extracted source files:
447 <literallayout class='monospaced'> 476 <literallayout class='monospaced'>
448 $ devtool modify -n <replaceable>recipe srctree</replaceable> 477 $ devtool modify -n <replaceable>recipe srctree</replaceable>
449 </literallayout> 478 </literallayout>
450 </para> 479 </para>
451 480
452 <para>Once the command finishes, it creates only 481 <para>Once the command finishes, it creates only
453 an append file for the recipe in the workspace. 482 an append file for the recipe in the workspace.
454 The recipe and the source code remain in their 483 The recipe and the source code remain in their
455 original locations. 484 original locations.
456 </para></listitem> 485 </para></listitem>
457 </itemizedlist> 486 </itemizedlist>
458 </para></listitem> 487 </para></listitem>
459 <listitem><para><emphasis>Edit the Source</emphasis>: 488 <listitem><para><emphasis>Edit the Source</emphasis>:
460 Once you have used the <filename>devtool modify</filename> 489 Once you have used the <filename>devtool modify</filename>
461 command, you are free to make changes to the source 490 command, you are free to make changes to the source
462 files. 491 files.
463 You can use any editor you like to make and save 492 You can use any editor you like to make and save
464 your source code modifications. 493 your source code modifications.
465 </para></listitem> 494 </para></listitem>
466 <listitem><para><emphasis>Build the Recipe</emphasis>: 495 <listitem><para><emphasis>Build the Recipe</emphasis>:
467 Once you have updated the source files, you can build 496 Once you have updated the source files, you can build
468 the recipe. 497 the recipe.
469 You can either use <filename>devtool build</filename> or 498 </para></listitem>
470 <filename>bitbake</filename>. 499 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
471 Either method produces build output that is stored 500 When you use the <filename>devtool build</filename>
472 in 501 command or <filename>bitbake</filename> to build out your
473 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. 502 recipe, you probably want to see if the resulting build
474 </para></listitem> 503 output works as expected on target hardware.
475 <listitem><para><emphasis>Deploy the Build Output</emphasis>: 504 <note>
476 When you use the <filename>devtool build</filename> 505 This step assumes you have a previously built
477 command or <filename>bitbake</filename> to build out your 506 image that is already either running in QEMU or
478 recipe, you probably want to see if the resulting build 507 running on actual hardware.
479 output works as expected on target hardware. 508 Also, it is assumed that for deployment of the image
480 <note> 509 to the target, SSH is installed in the image and if
481 This step assumes you have a previously built 510 the image is running on real hardware that you have
482 image that is already either running in QEMU or 511 network access to and from your development machine.
483 running on actual hardware. 512 </note>
484 Also, it is assumed that for deployment of the image 513 You can deploy your build output to that target hardware by
485 to the target, SSH is installed in the image and if 514 using the <filename>devtool deploy-target</filename> command:
486 the image is running on real hardware that you have 515 <literallayout class='monospaced'>
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> 516 $ devtool deploy-target <replaceable>recipe target</replaceable>
493 </literallayout> 517 </literallayout>
494 The <replaceable>target</replaceable> is a live target machine 518 The <replaceable>target</replaceable> is a live target machine
495 running as an SSH server.</para> 519 running as an SSH server.</para>
496 520
497 <para>You can, of course, also deploy the image you build 521 <para>You can, of course, also deploy the image you build
498 using the <filename>devtool build-image</filename> command 522 using the <filename>devtool build-image</filename> command
499 to actual hardware. 523 to actual hardware.
500 However, <filename>devtool</filename> does not provide a 524 However, <filename>devtool</filename> does not provide a
501 specific command that allows you to do this. 525 specific command that allows you to do this.
502 </para></listitem> 526 </para></listitem>
503 <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>: 527 <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
504 After you have debugged your changes, you can 528 After you have debugged your changes, you can
505 use <filename>devtool update-recipe</filename> to 529 use <filename>devtool update-recipe</filename> to
506 generate patch files for all the commits you have 530 generate patch files for all the commits you have
507 made. 531 made.
508 <note> 532 <note>
509 Patch files are generated only for changes 533 Patch files are generated only for changes
510 you have committed. 534 you have committed.
511 </note> 535 </note>
512 <literallayout class='monospaced'> 536 <literallayout class='monospaced'>
513 $ devtool update-recipe <replaceable>recipe</replaceable> 537 $ devtool update-recipe <replaceable>recipe</replaceable>
514 </literallayout> 538 </literallayout>
515 By default, the 539 By default, the
516 <filename>devtool update-recipe</filename> command 540 <filename>devtool update-recipe</filename> command
517 creates the patch files in a folder named the same 541 creates the patch files in a folder named the same
518 as the recipe beneath the folder in which the recipe 542 as the recipe beneath the folder in which the recipe
519 resides, and updates the recipe's 543 resides, and updates the recipe's
520 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 544 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
521 statement to point to the generated patch files. 545 statement to point to the generated patch files.
522 <note> 546 <note>
523 You can use the 547 You can use the
524 "--append <replaceable>LAYERDIR</replaceable>" 548 "--append <replaceable>LAYERDIR</replaceable>"
525 option to cause the command to create append files 549 option to cause the command to create append files
526 in a specific layer rather than the default 550 in a specific layer rather than the default
527 recipe layer. 551 recipe layer.
528 </note> 552 </note>
529 </para></listitem> 553 </para></listitem>
530 <listitem><para><emphasis>Restore the Workspace</emphasis>: 554 <listitem><para><emphasis>Restore the Workspace</emphasis>:
531 The <filename>devtool reset</filename> restores the 555 The <filename>devtool reset</filename> restores the
532 state so that standard layers and upstream sources are 556 state so that standard layers and upstream sources are
533 used to build the recipe rather than what is in the 557 used to build the recipe rather than what is in the
534 workspace. 558 workspace.
535 <literallayout class='monospaced'> 559 <literallayout class='monospaced'>
536 $ devtool reset <replaceable>recipe</replaceable> 560 $ devtool reset <replaceable>recipe</replaceable>
537 </literallayout> 561 </literallayout>
538 </para></listitem> 562 </para></listitem>
539 </orderedlist> 563 </orderedlist>
540 </para> 564 </para>
565 </section>
541</section> 566</section>
542 567
543<section id='sdk-installing-additional-items-into-the-extensible-sdk'> 568<section id='sdk-installing-additional-items-into-the-extensible-sdk'>
@@ -574,7 +599,7 @@
574 It is important to remember that building the item from source takes 599 It is important to remember that building the item from source takes
575 significantly longer than installing the pre-built artifact. 600 significantly longer than installing the pre-built artifact.
576 Also, if no recipe exists for the item you want to add to the SDK, you 601 Also, if no recipe exists for the item you want to add to the SDK, you
577 must add it using the <filename>devtool add</filename> command. 602 must instead add it using the <filename>devtool add</filename> command.
578 </para> 603 </para>
579</section> 604</section>
580 605
@@ -635,8 +660,8 @@
635 constructs a new SDK installer containing those recipes and the 660 constructs a new SDK installer containing those recipes and the
636 resulting binary artifacts. 661 resulting binary artifacts.
637 The recipes go into their own separate layer in the constructed 662 The recipes go into their own separate layer in the constructed
638 derivative SDK, leaving the workspace clean and ready for you 663 derivative SDK, leaving the workspace clean and ready for users
639 to add your own recipes. 664 to add their own recipes.
640 </para> 665 </para>
641</section> 666</section>
642 667