summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/ref-devtool-reference.xml911
1 files changed, 466 insertions, 445 deletions
diff --git a/documentation/ref-manual/ref-devtool-reference.xml b/documentation/ref-manual/ref-devtool-reference.xml
index 7506f441ea..7f1520d041 100644
--- a/documentation/ref-manual/ref-devtool-reference.xml
+++ b/documentation/ref-manual/ref-devtool-reference.xml
@@ -5,14 +5,35 @@
5<chapter id='ref-devtool-reference'> 5<chapter id='ref-devtool-reference'>
6 <title><filename>devtool</filename> Quick Reference</title> 6 <title><filename>devtool</filename> Quick Reference</title>
7 7
8 <section id='devtool-getting-help'> 8 <para>
9 <title>Getting Help</title> 9 The <filename>devtool</filename> command is pivotal when using an
10 10 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>.
11 <para> 11 This command-line tool provides a number of features that help you
12 The easiest way to get help with the 12 build, test and package software within the extensible SDK, and
13 <filename>devtool</filename> command is using the 13 optionally integrate it into an image built by the OpenEmbedded build
14 <filename>--help</filename> option: 14 system.
15 <literallayout class='monospaced'> 15 </para>
16
17 <para>
18 This chapter provides a Quick Reference for the
19 <filename>devtool</filename> command.
20 For more information on how to apply the command, see the
21 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
22 section in the Yocto Project Software Development Kit (SDK) Developer's
23 Guide.
24 </para>
25
26 <section id='devtool-getting-help'>
27 <title>Getting Help</title>
28
29 <para>
30 The <filename>devtool</filename> command line is organized
31 similarly to Git in that it has a number of sub-commands for
32 each function.
33 You can run <filename>devtool --help</filename> to see all
34 the commands:
35 <literallayout class='monospaced'>
36 $ devtool --help
16 usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] 37 usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q]
17 [--color COLOR] [-h] 38 [--color COLOR] [-h]
18 &lt;subcommand&gt; ... 39 &lt;subcommand&gt; ...
@@ -52,14 +73,14 @@
52 extract Extract the source for an existing recipe 73 extract Extract the source for an existing recipe
53 sync Synchronize the source tree for an existing recipe 74 sync Synchronize the source tree for an existing recipe
54 Use devtool &lt;subcommand&gt; --help to get help on a specific command 75 Use devtool &lt;subcommand&gt; --help to get help on a specific command
55 </literallayout> 76 </literallayout>
56 </para> 77 </para>
57 78
58 <para> 79 <para>
59 As directed in the general help output, you can get more 80 As directed in the general help output, you can get more
60 syntax on a specific command by providing the command 81 syntax on a specific command by providing the command
61 name and using <filename>--help</filename>: 82 name and using <filename>--help</filename>:
62 <literallayout class='monospaced'> 83 <literallayout class='monospaced'>
63 $ devtool add --help 84 $ devtool add --help
64 usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] 85 usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
65 [--version VERSION] [--no-git] [--autorev] [--binary] 86 [--version VERSION] [--no-git] [--autorev] [--binary]
@@ -99,32 +120,32 @@
99 --also-native Also add native variant (i.e. support building recipe 120 --also-native Also add native variant (i.e. support building recipe
100 for the build host as well as the target machine) 121 for the build host as well as the target machine)
101 --src-subdir SUBDIR Specify subdirectory within source tree to use 122 --src-subdir SUBDIR Specify subdirectory within source tree to use
102 </literallayout> 123 </literallayout>
103 </para> 124 </para>
104 </section> 125 </section>
105 126
106 <section id='devtool-the-workspace-layer-structure'> 127 <section id='devtool-the-workspace-layer-structure'>
107 <title>The Workspace Layer Structure</title> 128 <title>The Workspace Layer Structure</title>
108 129
109 <para> 130 <para>
110 <filename>devtool</filename> uses a "Workspace" layer 131 <filename>devtool</filename> uses a "Workspace" layer
111 in which to accomplish builds. 132 in which to accomplish builds.
112 This layer is not specific to any single 133 This layer is not specific to any single
113 <filename>devtool</filename> command but is rather a common 134 <filename>devtool</filename> command but is rather a common
114 working area used across the tool. 135 working area used across the tool.
115 </para> 136 </para>
116 137
117 <para> 138 <para>
118 The following figure shows the workspace structure: 139 The following figure shows the workspace structure:
119 </para> 140 </para>
120 141
121 <para> 142 <para>
122 <imagedata fileref="figures/build-workspace-directory.png" 143 <imagedata fileref="figures/build-workspace-directory.png"
123 width="6in" depth="5in" align="left" scale="70" /> 144 width="6in" depth="5in" align="left" scale="70" />
124 </para> 145 </para>
125 146
126 <para> 147 <para>
127 <literallayout class='monospaced'> 148 <literallayout class='monospaced'>
128 attic - A directory created if devtool believes it preserve 149 attic - A directory created if devtool believes it preserve
129 anything when you run "devtool reset". For example, if you 150 anything when you run "devtool reset". For example, if you
130 run "devtool add", make changes to the recipe, and then 151 run "devtool add", make changes to the recipe, and then
@@ -152,433 +173,433 @@
152 as the location of the source tree when you do not provide a 173 as the location of the source tree when you do not provide a
153 source tree path. This directory contains a folder for each 174 source tree path. This directory contains a folder for each
154 set of source files matched to a corresponding recipe. 175 set of source files matched to a corresponding recipe.
155 </literallayout> 176 </literallayout>
156 </para> 177 </para>
157 </section> 178 </section>
158 179
159 <section id='devtool-adding-a-new-recipe-to-the-workspace'> 180 <section id='devtool-adding-a-new-recipe-to-the-workspace'>
160 <title>Adding a New Recipe to the Workspace Layer</title> 181 <title>Adding a New Recipe to the Workspace Layer</title>
161 182
162 <para> 183 <para>
163 Use the <filename>devtool add</filename> command to add a new recipe 184 Use the <filename>devtool add</filename> command to add a new recipe
164 to the workspace layer. 185 to the workspace layer.
165 The recipe you add should not exist - 186 The recipe you add should not exist -
166 <filename>devtool</filename> creates it for you. 187 <filename>devtool</filename> creates it for you.
167 The source files the recipe uses should exist in an external 188 The source files the recipe uses should exist in an external
168 area. 189 area.
169 </para> 190 </para>
170 191
171 <para> 192 <para>
172 The following example creates and adds a new recipe named 193 The following example creates and adds a new recipe named
173 <filename>jackson</filename> to a workspace layer the tool creates. 194 <filename>jackson</filename> to a workspace layer the tool creates.
174 The source code built by the recipes resides in 195 The source code built by the recipes resides in
175 <filename>/home/scottrif/sources/jackson</filename>: 196 <filename>/home/scottrif/sources/jackson</filename>:
176 <literallayout class='monospaced'> 197 <literallayout class='monospaced'>
177 $ devtool add jackson /home/scottrif/sources/jackson 198 $ devtool add jackson /home/scottrif/sources/jackson
178 </literallayout> 199 </literallayout>
179 </para> 200 </para>
180 201
181 <para> 202 <para>
182 If you add a recipe and the workspace layer does not exist, 203 If you add a recipe and the workspace layer does not exist,
183 the command creates the layer and populates it as 204 the command creates the layer and populates it as
184 described in 205 described in
185 "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>" 206 "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>"
186 section. 207 section.
187 </para> 208 </para>
188 209
189 <para> 210 <para>
190 Running <filename>devtool add</filename> when the 211 Running <filename>devtool add</filename> when the
191 workspace layer exists causes the tool to add the recipe, 212 workspace layer exists causes the tool to add the recipe,
192 append files, and source files into the existing workspace layer. 213 append files, and source files into the existing workspace layer.
193 The <filename>.bbappend</filename> file is created to point 214 The <filename>.bbappend</filename> file is created to point
194 to the external source tree. 215 to the external source tree.
195 </para> 216 </para>
196 </section> 217 </section>
197 218
198 <section id='devtool-extracting-the-source-for-an-existing-recipe'> 219 <section id='devtool-extracting-the-source-for-an-existing-recipe'>
199 <title>Extracting the Source for an Existing Recipe</title> 220 <title>Extracting the Source for an Existing Recipe</title>
200 221
201 <para> 222 <para>
202 Use the <filename>devtool extract</filename> command to 223 Use the <filename>devtool extract</filename> command to
203 extract the source for an existing recipe. 224 extract the source for an existing recipe.
204 When you use this command, you must supply the root name 225 When you use this command, you must supply the root name
205 of the recipe (i.e. no version, paths, or extensions), and 226 of the recipe (i.e. no version, paths, or extensions), and
206 you must supply the directory to which you want the source 227 you must supply the directory to which you want the source
207 extracted. 228 extracted.
208 </para> 229 </para>
209 230
210 <para> 231 <para>
211 Additional command options let you control the name of a 232 Additional command options let you control the name of a
212 development branch into which you can checkout the source 233 development branch into which you can checkout the source
213 and whether or not to keep a temporary directory, which is 234 and whether or not to keep a temporary directory, which is
214 useful for debugging. 235 useful for debugging.
215 </para> 236 </para>
216 </section> 237 </section>
217 238
218 <section id='devtool-synchronizing-a-recipes-extracted-source-tree'> 239 <section id='devtool-synchronizing-a-recipes-extracted-source-tree'>
219 <title>Synchronizing a Recipe's Extracted Source Tree</title> 240 <title>Synchronizing a Recipe's Extracted Source Tree</title>
220 241
221 <para> 242 <para>
222 Use the <filename>devtool sync</filename> command to 243 Use the <filename>devtool sync</filename> command to
223 synchronize a previously extracted source tree for an 244 synchronize a previously extracted source tree for an
224 existing recipe. 245 existing recipe.
225 When you use this command, you must supply the root name 246 When you use this command, you must supply the root name
226 of the recipe (i.e. no version, paths, or extensions), and 247 of the recipe (i.e. no version, paths, or extensions), and
227 you must supply the directory to which you want the source 248 you must supply the directory to which you want the source
228 extracted. 249 extracted.
229 </para> 250 </para>
230 251
231 <para> 252 <para>
232 Additional command options let you control the name of a 253 Additional command options let you control the name of a
233 development branch into which you can checkout the source 254 development branch into which you can checkout the source
234 and whether or not to keep a temporary directory, which is 255 and whether or not to keep a temporary directory, which is
235 useful for debugging. 256 useful for debugging.
236 </para> 257 </para>
237 </section> 258 </section>
238 259
239 <section id='devtool-modifying-a-recipe'> 260 <section id='devtool-modifying-a-recipe'>
240 <title>Modifying an Existing Recipe</title> 261 <title>Modifying an Existing Recipe</title>
241 262
242 <para> 263 <para>
243 Use the <filename>devtool modify</filename> command to begin 264 Use the <filename>devtool modify</filename> command to begin
244 modifying the source of an existing recipe. 265 modifying the source of an existing recipe.
245 This command is very similar to the 266 This command is very similar to the
246 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></ulink> 267 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></ulink>
247 command except that it does not physically create the 268 command except that it does not physically create the
248 recipe in the workspace layer because the recipe already 269 recipe in the workspace layer because the recipe already
249 exists in an another layer. 270 exists in an another layer.
250 </para> 271 </para>
251 272
252 <para> 273 <para>
253 The <filename>devtool modify</filename> command extracts the 274 The <filename>devtool modify</filename> command extracts the
254 source for a recipe, sets it up as a Git repository if the 275 source for a recipe, sets it up as a Git repository if the
255 source had not already been fetched from Git, checks out a 276 source had not already been fetched from Git, checks out a
256 branch for development, and applies any patches from the recipe 277 branch for development, and applies any patches from the recipe
257 as commits on top. 278 as commits on top.
258 You can use the following command to checkout the source 279 You can use the following command to checkout the source
259 files: 280 files:
260 <literallayout class='monospaced'> 281 <literallayout class='monospaced'>
261 $ devtool modify <replaceable>recipe</replaceable> 282 $ devtool modify <replaceable>recipe</replaceable>
262 </literallayout> 283 </literallayout>
263 Using the above command form, <filename>devtool</filename> uses 284 Using the above command form, <filename>devtool</filename> uses
264 the existing recipe's 285 the existing recipe's
265 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> 286 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
266 statement to locate the upstream source, extracts the source 287 statement to locate the upstream source, extracts the source
267 into the default sources location in the workspace. 288 into the default sources location in the workspace.
268 The default development branch used is "devtool". 289 The default development branch used is "devtool".
269 </para> 290 </para>
270 </section> 291 </section>
271 292
272 <section id='devtool-edit-an-existing-recipe'> 293 <section id='devtool-edit-an-existing-recipe'>
273 <title>Edit an Existing Recipe</title> 294 <title>Edit an Existing Recipe</title>
274 295
275 <para> 296 <para>
276 Use the <filename>devtool edit-recipe</filename> command 297 Use the <filename>devtool edit-recipe</filename> command
277 to run the default editor, which is identified using the 298 to run the default editor, which is identified using the
278 <filename>EDITOR</filename> variable, on the specified recipe. 299 <filename>EDITOR</filename> variable, on the specified recipe.
279 </para> 300 </para>
280 301
281 <para> 302 <para>
282 When you use the <filename>devtool edit-recipe</filename> 303 When you use the <filename>devtool edit-recipe</filename>
283 command, you must supply the root name of the recipe 304 command, you must supply the root name of the recipe
284 (i.e. no version, paths, or extensions). 305 (i.e. no version, paths, or extensions).
285 Also, the recipe file itself must reside in the workspace 306 Also, the recipe file itself must reside in the workspace
286 as a result of the <filename>devtool add</filename> or 307 as a result of the <filename>devtool add</filename> or
287 <filename>devtool upgrade</filename> commands. 308 <filename>devtool upgrade</filename> commands.
288 However, you can override that requirement by using the 309 However, you can override that requirement by using the
289 "-a" or "--any-recipe" option. 310 "-a" or "--any-recipe" option.
290 Using either of these options allows you to edit any recipe 311 Using either of these options allows you to edit any recipe
291 regardless of its location. 312 regardless of its location.
292 </para> 313 </para>
293 </section> 314 </section>
294 315
295 <section id='devtool-updating-a-recipe'> 316 <section id='devtool-updating-a-recipe'>
296 <title>Updating a Recipe</title> 317 <title>Updating a Recipe</title>
297 318
298 <para> 319 <para>
299 Use the <filename>devtool update-recipe</filename> command to 320 Use the <filename>devtool update-recipe</filename> command to
300 update your recipe with patches that reflect changes you make 321 update your recipe with patches that reflect changes you make
301 to the source files. 322 to the source files.
302 For example, if you know you are going to work on some 323 For example, if you know you are going to work on some
303 code, you could first use the 324 code, you could first use the
304 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-modifying-a-recipe'><filename>devtool modify</filename></ulink> 325 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-modifying-a-recipe'><filename>devtool modify</filename></ulink>
305 command to extract the code and set up the workspace. 326 command to extract the code and set up the workspace.
306 After which, you could modify, compile, and test the code. 327 After which, you could modify, compile, and test the code.
307 </para> 328 </para>
308 329
309 <para> 330 <para>
310 When you are satisfied with the results and you have committed 331 When you are satisfied with the results and you have committed
311 your changes to the Git repository, you can then 332 your changes to the Git repository, you can then
312 run the <filename>devtool update-recipe</filename> to create the 333 run the <filename>devtool update-recipe</filename> to create the
313 patches and update the recipe: 334 patches and update the recipe:
314 <literallayout class='monospaced'> 335 <literallayout class='monospaced'>
315 $ devtool update-recipe <replaceable>recipe</replaceable> 336 $ devtool update-recipe <replaceable>recipe</replaceable>
316 </literallayout> 337 </literallayout>
317 If you run the <filename>devtool update-recipe</filename> 338 If you run the <filename>devtool update-recipe</filename>
318 without committing your changes, the command ignores the 339 without committing your changes, the command ignores the
319 changes. 340 changes.
320 </para> 341 </para>
321 342
322 <para> 343 <para>
323 Often, you might want to apply customizations made to your 344 Often, you might want to apply customizations made to your
324 software in your own layer rather than apply them to the 345 software in your own layer rather than apply them to the
325 original recipe. 346 original recipe.
326 If so, you can use the 347 If so, you can use the
327 <filename>-a</filename> or <filename>--append</filename> 348 <filename>-a</filename> or <filename>--append</filename>
328 option with the <filename>devtool update-recipe</filename> 349 option with the <filename>devtool update-recipe</filename>
329 command. 350 command.
330 These options allow you to specify the layer into which to 351 These options allow you to specify the layer into which to
331 write an append file: 352 write an append file:
332 <literallayout class='monospaced'> 353 <literallayout class='monospaced'>
333 $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable> 354 $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable>
334 </literallayout> 355 </literallayout>
335 The <filename>*.bbappend</filename> file is created at the 356 The <filename>*.bbappend</filename> file is created at the
336 appropriate path within the specified layer directory, which 357 appropriate path within the specified layer directory, which
337 may or may not be in your <filename>bblayers.conf</filename> 358 may or may not be in your <filename>bblayers.conf</filename>
338 file. 359 file.
339 If an append file already exists, the command updates it 360 If an append file already exists, the command updates it
340 appropriately. 361 appropriately.
341 </para> 362 </para>
342 </section> 363 </section>
343 364
344 <section id='devtool-upgrading-a-recipe'> 365 <section id='devtool-upgrading-a-recipe'>
345 <title>Upgrading a Recipe</title> 366 <title>Upgrading a Recipe</title>
346 367
347 <para> 368 <para>
348 Use the <filename>devtool upgrade</filename> command 369 Use the <filename>devtool upgrade</filename> command
349 to upgrade an existing recipe to a new upstream version. 370 to upgrade an existing recipe to a new upstream version.
350 The command puts the upgraded recipe file into the 371 The command puts the upgraded recipe file into the
351 workspace along with any associated files, and extracts 372 workspace along with any associated files, and extracts
352 the source tree to a specified location should patches 373 the source tree to a specified location should patches
353 need rebased or added to as a result of the upgrade. 374 need rebased or added to as a result of the upgrade.
354 </para> 375 </para>
355 376
356 <para> 377 <para>
357 When you use the <filename>devtool upgrade</filename> command, 378 When you use the <filename>devtool upgrade</filename> command,
358 you must supply the root name of the recipe (i.e. no version, 379 you must supply the root name of the recipe (i.e. no version,
359 paths, or extensions), and you must supply the directory 380 paths, or extensions), and you must supply the directory
360 to which you want the source extracted. 381 to which you want the source extracted.
361 Additional command options let you control things such as 382 Additional command options let you control things such as
362 the version number to which you want to upgrade (i.e. the 383 the version number to which you want to upgrade (i.e. the
363 <link linkend='var-PV'><filename>PV</filename></link>), 384 <link linkend='var-PV'><filename>PV</filename></link>),
364 the source revision to which you want to upgrade (i.e. the 385 the source revision to which you want to upgrade (i.e. the
365 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>, 386 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>,
366 whether or not to apply patches, and so forth. 387 whether or not to apply patches, and so forth.
367 </para> 388 </para>
368 </section> 389 </section>
369 390
370 <section id='devtool-resetting-a-recipe'> 391 <section id='devtool-resetting-a-recipe'>
371 <title>Resetting a Recipe</title> 392 <title>Resetting a Recipe</title>
372 393
373 <para> 394 <para>
374 Use the <filename>devtool reset</filename> command to remove a 395 Use the <filename>devtool reset</filename> command to remove a
375 recipe and its configuration (e.g. the corresponding 396 recipe and its configuration (e.g. the corresponding
376 <filename>.bbappend</filename> file) from the workspace layer. 397 <filename>.bbappend</filename> file) from the workspace layer.
377 Realize that this command deletes the recipe and the 398 Realize that this command deletes the recipe and the
378 append file. 399 append file.
379 The command does not physically move them for you. 400 The command does not physically move them for you.
380 Consequently, you must be sure to physically relocate your 401 Consequently, you must be sure to physically relocate your
381 updated recipe and the append file outside of the workspace 402 updated recipe and the append file outside of the workspace
382 layer before running the <filename>devtool reset</filename> 403 layer before running the <filename>devtool reset</filename>
383 command. 404 command.
384 </para> 405 </para>
385 406
386 <para> 407 <para>
387 If the <filename>devtool reset</filename> command detects that 408 If the <filename>devtool reset</filename> command detects that
388 the recipe or the append files have been modified, the 409 the recipe or the append files have been modified, the
389 command preserves the modified files in a separate "attic" 410 command preserves the modified files in a separate "attic"
390 subdirectory under the workspace layer. 411 subdirectory under the workspace layer.
391 </para> 412 </para>
392 413
393 <para> 414 <para>
394 Here is an example that resets the workspace directory that 415 Here is an example that resets the workspace directory that
395 contains the <filename>mtr</filename> recipe: 416 contains the <filename>mtr</filename> recipe:
396 <literallayout class='monospaced'> 417 <literallayout class='monospaced'>
397 $ devtool reset mtr 418 $ devtool reset mtr
398 NOTE: Cleaning sysroot for recipe mtr... 419 NOTE: Cleaning sysroot for recipe mtr...
399 NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no 420 NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no
400 longer need it then please delete it manually 421 longer need it then please delete it manually
401 $ 422 $
402 </literallayout> 423 </literallayout>
403 </para> 424 </para>
404 </section> 425 </section>
405 426
406 <section id='devtool-building-your-recipe'> 427 <section id='devtool-building-your-recipe'>
407 <title>Building Your Recipe</title> 428 <title>Building Your Recipe</title>
408 429
409 <para> 430 <para>
410 Use the <filename>devtool build</filename> command to cause the 431 Use the <filename>devtool build</filename> command to cause the
411 OpenEmbedded build system to build your recipe. 432 OpenEmbedded build system to build your recipe.
412 The <filename>devtool build</filename> command is equivalent to 433 The <filename>devtool build</filename> command is equivalent to
413 <filename>bitbake -c populate_sysroot</filename>. 434 <filename>bitbake -c populate_sysroot</filename>.
414 </para> 435 </para>
415 436
416 <para> 437 <para>
417 When you use the <filename>devtool build</filename> command, 438 When you use the <filename>devtool build</filename> command,
418 you must supply the root name of the recipe (i.e. no version, 439 you must supply the root name of the recipe (i.e. no version,
419 paths, or extensions). 440 paths, or extensions).
420 You can use either the "-s" or the "--disable-parallel-make" 441 You can use either the "-s" or the "--disable-parallel-make"
421 option to disable parallel makes during the build. 442 option to disable parallel makes during the build.
422 Here is an example: 443 Here is an example:
423 <literallayout class='monospaced'> 444 <literallayout class='monospaced'>
424 $ devtool build <replaceable>recipe</replaceable> 445 $ devtool build <replaceable>recipe</replaceable>
425 </literallayout> 446 </literallayout>
426 </para> 447 </para>
427 </section> 448 </section>
428 449
429 <section id='devtool-building-your-image'> 450 <section id='devtool-building-your-image'>
430 <title>Building Your Image</title> 451 <title>Building Your Image</title>
431 452
432 <para> 453 <para>
433 Use the <filename>devtool build-image</filename> command 454 Use the <filename>devtool build-image</filename> command
434 to build an image, extending it to include packages from 455 to build an image, extending it to include packages from
435 recipes in the workspace. 456 recipes in the workspace.
436 Using this command is useful when you want an image that 457 Using this command is useful when you want an image that
437 ready for immediate deployment onto a device for testing. 458 ready for immediate deployment onto a device for testing.
438 For proper integration into a final image, you need to 459 For proper integration into a final image, you need to
439 edit your custom image recipe appropriately. 460 edit your custom image recipe appropriately.
440 </para> 461 </para>
441 462
442 <para> 463 <para>
443 When you use the <filename>devtool build-image</filename> 464 When you use the <filename>devtool build-image</filename>
444 command, you must supply the name of the image. 465 command, you must supply the name of the image.
445 This command has no command line options: 466 This command has no command line options:
446 <literallayout class='monospaced'> 467 <literallayout class='monospaced'>
447 $ devtool build-image <replaceable>image</replaceable> 468 $ devtool build-image <replaceable>image</replaceable>
448 </literallayout> 469 </literallayout>
449 </para> 470 </para>
450 </section> 471 </section>
451 472
452 <section id='devtool-deploying-your-software-on-the-target-machine'> 473 <section id='devtool-deploying-your-software-on-the-target-machine'>
453 <title>Deploying Your Software on the Target Machine</title> 474 <title>Deploying Your Software on the Target Machine</title>
454 475
455 <para> 476 <para>
456 Use the <filename>devtool deploy-target</filename> command to 477 Use the <filename>devtool deploy-target</filename> command to
457 deploy the recipe's build output to the live target machine: 478 deploy the recipe's build output to the live target machine:
458 <literallayout class='monospaced'> 479 <literallayout class='monospaced'>
459 $ devtool deploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable> 480 $ devtool deploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
460 </literallayout> 481 </literallayout>
461 The <replaceable>target</replaceable> is the address of the 482 The <replaceable>target</replaceable> is the address of the
462 target machine, which must be running an SSH server (i.e. 483 target machine, which must be running an SSH server (i.e.
463 <filename>user@hostname[:destdir]</filename>). 484 <filename>user@hostname[:destdir]</filename>).
464 </para> 485 </para>
465 486
466 <para> 487 <para>
467 This command deploys all files installed during the 488 This command deploys all files installed during the
468 <link linkend='ref-tasks-install'><filename>do_install</filename></link> 489 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
469 task. 490 task.
470 Furthermore, you do not need to have package management enabled 491 Furthermore, you do not need to have package management enabled
471 within the target machine. 492 within the target machine.
472 If you do, the package manager is bypassed. 493 If you do, the package manager is bypassed.
473 <note><title>Notes</title> 494 <note><title>Notes</title>
474 <para> 495 <para>
475 The <filename>deploy-target</filename> 496 The <filename>deploy-target</filename>
476 functionality is for development only. 497 functionality is for development only.
477 You should never use it to update an image that will be 498 You should never use it to update an image that will be
478 used in production. 499 used in production.
479 </para> 500 </para>
480 </note> 501 </note>
481 </para> 502 </para>
482 </section> 503 </section>
483 504
484 <section id='devtool-removing-your-software-from-the-target-machine'> 505 <section id='devtool-removing-your-software-from-the-target-machine'>
485 <title>Removing Your Software from the Target Machine</title> 506 <title>Removing Your Software from the Target Machine</title>
486 507
487 <para> 508 <para>
488 Use the <filename>devtool undeploy-target</filename> command to 509 Use the <filename>devtool undeploy-target</filename> command to
489 remove deployed build output from the target machine. 510 remove deployed build output from the target machine.
490 For the <filename>devtool undeploy-target</filename> command to 511 For the <filename>devtool undeploy-target</filename> command to
491 work, you must have previously used the 512 work, you must have previously used the
492 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></ulink> 513 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></ulink>
493 command. 514 command.
494 <literallayout class='monospaced'> 515 <literallayout class='monospaced'>
495 $ devtool undeploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable> 516 $ devtool undeploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
496 </literallayout> 517 </literallayout>
497 The <replaceable>target</replaceable> is the address of the 518 The <replaceable>target</replaceable> is the address of the
498 target machine, which must be running an SSH server (i.e. 519 target machine, which must be running an SSH server (i.e.
499 <filename>user@hostname</filename>). 520 <filename>user@hostname</filename>).
500 </para> 521 </para>
501 </section> 522 </section>
502 523
503 <section id='devtool-creating-the-workspace'> 524 <section id='devtool-creating-the-workspace'>
504 <title>Creating the Workspace Layer in an Alternative Location</title> 525 <title>Creating the Workspace Layer in an Alternative Location</title>
505 526
506 <para> 527 <para>
507 Use the <filename>devtool create-workspace</filename> command to 528 Use the <filename>devtool create-workspace</filename> command to
508 create a new workspace layer in your 529 create a new workspace layer in your
509 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 530 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
510 When you create a new workspace layer, it is populated with the 531 When you create a new workspace layer, it is populated with the
511 <filename>README</filename> file and the 532 <filename>README</filename> file and the
512 <filename>conf</filename> directory only. 533 <filename>conf</filename> directory only.
513 </para> 534 </para>
514 535
515 <para> 536 <para>
516 The following example creates a new workspace layer in your 537 The following example creates a new workspace layer in your
517 current working and by default names the workspace layer 538 current working and by default names the workspace layer
518 "workspace": 539 "workspace":
519 <literallayout class='monospaced'> 540 <literallayout class='monospaced'>
520 $ devtool create-workspace 541 $ devtool create-workspace
521 </literallayout> 542 </literallayout>
522 </para> 543 </para>
523 544
524 <para> 545 <para>
525 You can create a workspace layer anywhere by supplying 546 You can create a workspace layer anywhere by supplying
526 a pathname with the command. 547 a pathname with the command.
527 The following command creates a new workspace layer named 548 The following command creates a new workspace layer named
528 "new-workspace": 549 "new-workspace":
529 <literallayout class='monospaced'> 550 <literallayout class='monospaced'>
530 $ devtool create-workspace /home/scottrif/new-workspace 551 $ devtool create-workspace /home/scottrif/new-workspace
531 </literallayout> 552 </literallayout>
532 </para> 553 </para>
533 </section> 554 </section>
534 555
535 <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'> 556 <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'>
536 <title>Get the Status of the Recipes in Your Workspace</title> 557 <title>Get the Status of the Recipes in Your Workspace</title>
537 558
538 <para> 559 <para>
539 Use the <filename>devtool status</filename> command to 560 Use the <filename>devtool status</filename> command to
540 list the recipes currently in your workspace. 561 list the recipes currently in your workspace.
541 Information includes the paths to their respective 562 Information includes the paths to their respective
542 external source trees. 563 external source trees.
543 </para> 564 </para>
544 565
545 <para> 566 <para>
546 The <filename>devtool status</filename> command has no 567 The <filename>devtool status</filename> command has no
547 command-line options: 568 command-line options:
548 <literallayout class='monospaced'> 569 <literallayout class='monospaced'>
549 devtool status 570 $ devtool status
550 </literallayout> 571 </literallayout>
551 Following is sample output after using 572 Following is sample output after using
552 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></ulink> 573 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></ulink>
553 to create and add the <filename>mtr_0.86.bb</filename> recipe 574 to create and add the <filename>mtr_0.86.bb</filename> recipe
554 to the <filename>workspace</filename> directory: 575 to the <filename>workspace</filename> directory:
555 <literallayout class='monospaced'> 576 <literallayout class='monospaced'>
556 $ devtool status 577 $ devtool status
557 mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) 578 mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
558 $ 579 $
559 </literallayout> 580 </literallayout>
560 </para> 581 </para>
561 </section> 582 </section>
562 583
563 <section id='devtool-search-for-available-target-recipes'> 584 <section id='devtool-search-for-available-target-recipes'>
564 <title>Search for Available Target Recipes</title> 585 <title>Search for Available Target Recipes</title>
565 586
566 <para> 587 <para>
567 Use the <filename>devtool search</filename> command to 588 Use the <filename>devtool search</filename> command to
568 search for available target recipes. 589 search for available target recipes.
569 The command matches the recipe name, package name, 590 The command matches the recipe name, package name,
570 description, and installed files. 591 description, and installed files.
571 The command displays the recipe name as a result of a 592 The command displays the recipe name as a result of a
572 match. 593 match.
573 </para> 594 </para>
574 595
575 <para> 596 <para>
576 When you use the <filename>devtool search</filename> command, 597 When you use the <filename>devtool search</filename> command,
577 you must supply a <replaceable>keyword</replaceable>. 598 you must supply a <replaceable>keyword</replaceable>.
578 The command uses the <replaceable>keyword</replaceable> when 599 The command uses the <replaceable>keyword</replaceable> when
579 searching for a match. 600 searching for a match.
580 </para> 601 </para>
581 </section> 602 </section>
582</chapter> 603</chapter>
583<!-- 604<!--
584vim: expandtab tw=80 ts=4 605vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-11 22:18:28 +0000