summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-09-19 13:52:07 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-09-28 15:02:32 +0100
commited6a5495a19b7f2bc0f9ae35027b27f2bb973576 (patch)
tree4b09d10b7d3f677ed3961375e6be73d2ac22e226 /documentation/ref-manual
parent38278f0a2162fbb0fda6d5b00d73495906acb968 (diff)
downloadpoky-ed6a5495a19b7f2bc0f9ae35027b27f2bb973576.tar.gz
documentation: devtool upgrade and quick ref changes to mult manuals
Did the following: * Added the devtool upgrade flow to the SDK manual. * Removed the devtool Quick Reference from the dev-manual and added it as a new chapter to the ref-manual. * Made sure all the links and cross-references work now with the moved material. * Updated the Make file so that the manual set builds correctly regarding the new chapter in the ref-manual. * Created cross-referencing notes in both the sdk-manual and the dev-manual to the newly located devtool Quick Reference chapter. (From yocto-docs rev: fda0bf68b3654b1b96407d552c5254657465b5fc) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/figures/build-workspace-directory.pngbin0 -> 29627 bytes
-rw-r--r--documentation/ref-manual/introduction.xml5
-rw-r--r--documentation/ref-manual/ref-devtool-reference.xml585
-rw-r--r--documentation/ref-manual/ref-manual.xml2
4 files changed, 592 insertions, 0 deletions
diff --git a/documentation/ref-manual/figures/build-workspace-directory.png b/documentation/ref-manual/figures/build-workspace-directory.png
new file mode 100644
index 0000000000..5387d33f03
--- /dev/null
+++ b/documentation/ref-manual/figures/build-workspace-directory.png
Binary files differ
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index d5f0b279fd..0f43f0d199 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -80,6 +80,11 @@
80 Describes the tasks defined by the OpenEmbedded build system. 80 Describes the tasks defined by the OpenEmbedded build system.
81 </para></listitem> 81 </para></listitem>
82 <listitem><para><emphasis> 82 <listitem><para><emphasis>
83 <link linkend='ref-devtool-reference'><filename>devtool</filename> Quick Reference</link>:</emphasis>
84 Provides a quick reference for the <filename>devtool</filename>
85 command.
86 </para></listitem>
87 <listitem><para><emphasis>
83 <link linkend='ref-qa-checks'>QA Error and Warning Messages</link>:</emphasis> 88 <link linkend='ref-qa-checks'>QA Error and Warning Messages</link>:</emphasis>
84 Lists and describes QA warning and error messages. 89 Lists and describes QA warning and error messages.
85 </para></listitem> 90 </para></listitem>
diff --git a/documentation/ref-manual/ref-devtool-reference.xml b/documentation/ref-manual/ref-devtool-reference.xml
new file mode 100644
index 0000000000..7506f441ea
--- /dev/null
+++ b/documentation/ref-manual/ref-devtool-reference.xml
@@ -0,0 +1,585 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-devtool-reference'>
6 <title><filename>devtool</filename> Quick Reference</title>
7
8 <section id='devtool-getting-help'>
9 <title>Getting Help</title>
10
11 <para>
12 The easiest way to get help with the
13 <filename>devtool</filename> command is using the
14 <filename>--help</filename> option:
15 <literallayout class='monospaced'>
16 usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q]
17 [--color COLOR] [-h]
18 &lt;subcommand&gt; ...
19
20 OpenEmbedded development tool
21
22 options:
23 --basepath BASEPATH Base directory of SDK / build directory
24 --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it
25 from the metadata
26 -d, --debug Enable debug output
27 -q, --quiet Print only errors
28 --color COLOR Colorize output (where COLOR is auto, always, never)
29 -h, --help show this help message and exit
30
31 subcommands:
32 Beginning work on a recipe:
33 add Add a new recipe
34 modify Modify the source for an existing recipe
35 upgrade Upgrade an existing recipe
36 Getting information:
37 status Show workspace status
38 search Search available recipes
39 Working on a recipe in the workspace:
40 edit-recipe Edit a recipe file in your workspace
41 configure-help Get help on configure script options
42 build Build a recipe
43 update-recipe Apply changes from external source tree to recipe
44 reset Remove a recipe from your workspace
45 finish Finish working on a recipe in your workspace
46 Testing changes on target:
47 deploy-target Deploy recipe output files to live target machine
48 undeploy-target Undeploy recipe output files in live target machine
49 build-image Build image including workspace recipe packages
50 Advanced:
51 create-workspace Set up workspace in an alternative location
52 extract Extract the source for an existing recipe
53 sync Synchronize the source tree for an existing recipe
54 Use devtool &lt;subcommand&gt; --help to get help on a specific command
55 </literallayout>
56 </para>
57
58 <para>
59 As directed in the general help output, you can get more
60 syntax on a specific command by providing the command
61 name and using <filename>--help</filename>:
62 <literallayout class='monospaced'>
63 $ devtool add --help
64 usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
65 [--version VERSION] [--no-git] [--autorev] [--binary]
66 [--also-native] [--src-subdir SUBDIR]
67 [recipename] [srctree] [fetchuri]
68
69 Adds a new recipe to the workspace to build a specified source tree. Can
70 optionally fetch a remote URI and unpack it to create the source tree.
71
72 arguments:
73 recipename Name for new recipe to add (just name - no version,
74 path or extension). If not specified, will attempt to
75 auto-detect it.
76 srctree Path to external source tree. If not specified, a
77 subdirectory of
78 /home/scottrif/poky/build/workspace/sources will be
79 used.
80 fetchuri Fetch the specified URI and extract it to create the
81 source tree
82
83 options:
84 -h, --help show this help message and exit
85 --same-dir, -s Build in same directory as source
86 --no-same-dir Force build in a separate build directory
87 --fetch URI, -f URI Fetch the specified URI and extract it to create the
88 source tree (deprecated - pass as positional argument
89 instead)
90 --version VERSION, -V VERSION
91 Version to use within recipe (PV)
92 --no-git, -g If fetching source, do not set up source tree as a git
93 repository
94 --autorev, -a When fetching from a git repository, set SRCREV in the
95 recipe to a floating revision instead of fixed
96 --binary, -b Treat the source tree as something that should be
97 installed verbatim (no compilation, same directory
98 structure). Useful with binary packages e.g. RPMs.
99 --also-native Also add native variant (i.e. support building recipe
100 for the build host as well as the target machine)
101 --src-subdir SUBDIR Specify subdirectory within source tree to use
102 </literallayout>
103 </para>
104 </section>
105
106 <section id='devtool-the-workspace-layer-structure'>
107 <title>The Workspace Layer Structure</title>
108
109 <para>
110 <filename>devtool</filename> uses a "Workspace" layer
111 in which to accomplish builds.
112 This layer is not specific to any single
113 <filename>devtool</filename> command but is rather a common
114 working area used across the tool.
115 </para>
116
117 <para>
118 The following figure shows the workspace structure:
119 </para>
120
121 <para>
122 <imagedata fileref="figures/build-workspace-directory.png"
123 width="6in" depth="5in" align="left" scale="70" />
124 </para>
125
126 <para>
127 <literallayout class='monospaced'>
128 attic - A directory created if devtool believes it preserve
129 anything when you run "devtool reset". For example, if you
130 run "devtool add", make changes to the recipe, and then
131 run "devtool reset", devtool takes notice that the file has
132 been changed and moves it into the attic should you still
133 want the recipe.
134
135 README - Provides information on what is in workspace layer and how to
136 manage it.
137
138 .devtool_md5 - A checksum file used by devtool.
139
140 appends - A directory that contains *.bbappend files, which point to
141 external source.
142
143 conf - A configuration directory that contains the layer.conf file.
144
145 recipes - A directory containing recipes. This directory contains a
146 folder for each directory added whose name matches that of the
147 added recipe. devtool places the <replaceable>recipe</replaceable>.bb file
148 within that sub-directory.
149
150 sources - A directory containing a working copy of the source files used
151 when building the recipe. This is the default directory used
152 as the location of the source tree when you do not provide a
153 source tree path. This directory contains a folder for each
154 set of source files matched to a corresponding recipe.
155 </literallayout>
156 </para>
157 </section>
158
159 <section id='devtool-adding-a-new-recipe-to-the-workspace'>
160 <title>Adding a New Recipe to the Workspace Layer</title>
161
162 <para>
163 Use the <filename>devtool add</filename> command to add a new recipe
164 to the workspace layer.
165 The recipe you add should not exist -
166 <filename>devtool</filename> creates it for you.
167 The source files the recipe uses should exist in an external
168 area.
169 </para>
170
171 <para>
172 The following example creates and adds a new recipe named
173 <filename>jackson</filename> to a workspace layer the tool creates.
174 The source code built by the recipes resides in
175 <filename>/home/scottrif/sources/jackson</filename>:
176 <literallayout class='monospaced'>
177 $ devtool add jackson /home/scottrif/sources/jackson
178 </literallayout>
179 </para>
180
181 <para>
182 If you add a recipe and the workspace layer does not exist,
183 the command creates the layer and populates it as
184 described in
185 "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>"
186 section.
187 </para>
188
189 <para>
190 Running <filename>devtool add</filename> when the
191 workspace layer exists causes the tool to add the recipe,
192 append files, and source files into the existing workspace layer.
193 The <filename>.bbappend</filename> file is created to point
194 to the external source tree.
195 </para>
196 </section>
197
198 <section id='devtool-extracting-the-source-for-an-existing-recipe'>
199 <title>Extracting the Source for an Existing Recipe</title>
200
201 <para>
202 Use the <filename>devtool extract</filename> command to
203 extract the source for an existing recipe.
204 When you use this command, you must supply the root name
205 of the recipe (i.e. no version, paths, or extensions), and
206 you must supply the directory to which you want the source
207 extracted.
208 </para>
209
210 <para>
211 Additional command options let you control the name of a
212 development branch into which you can checkout the source
213 and whether or not to keep a temporary directory, which is
214 useful for debugging.
215 </para>
216 </section>
217
218 <section id='devtool-synchronizing-a-recipes-extracted-source-tree'>
219 <title>Synchronizing a Recipe's Extracted Source Tree</title>
220
221 <para>
222 Use the <filename>devtool sync</filename> command to
223 synchronize a previously extracted source tree for an
224 existing recipe.
225 When you use this command, you must supply the root name
226 of the recipe (i.e. no version, paths, or extensions), and
227 you must supply the directory to which you want the source
228 extracted.
229 </para>
230
231 <para>
232 Additional command options let you control the name of a
233 development branch into which you can checkout the source
234 and whether or not to keep a temporary directory, which is
235 useful for debugging.
236 </para>
237 </section>
238
239 <section id='devtool-modifying-a-recipe'>
240 <title>Modifying an Existing Recipe</title>
241
242 <para>
243 Use the <filename>devtool modify</filename> command to begin
244 modifying the source of an existing recipe.
245 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>
247 command except that it does not physically create the
248 recipe in the workspace layer because the recipe already
249 exists in an another layer.
250 </para>
251
252 <para>
253 The <filename>devtool modify</filename> command extracts the
254 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
256 branch for development, and applies any patches from the recipe
257 as commits on top.
258 You can use the following command to checkout the source
259 files:
260 <literallayout class='monospaced'>
261 $ devtool modify <replaceable>recipe</replaceable>
262 </literallayout>
263 Using the above command form, <filename>devtool</filename> uses
264 the existing recipe's
265 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
266 statement to locate the upstream source, extracts the source
267 into the default sources location in the workspace.
268 The default development branch used is "devtool".
269 </para>
270 </section>
271
272 <section id='devtool-edit-an-existing-recipe'>
273 <title>Edit an Existing Recipe</title>
274
275 <para>
276 Use the <filename>devtool edit-recipe</filename> command
277 to run the default editor, which is identified using the
278 <filename>EDITOR</filename> variable, on the specified recipe.
279 </para>
280
281 <para>
282 When you use the <filename>devtool edit-recipe</filename>
283 command, you must supply the root name of the recipe
284 (i.e. no version, paths, or extensions).
285 Also, the recipe file itself must reside in the workspace
286 as a result of the <filename>devtool add</filename> or
287 <filename>devtool upgrade</filename> commands.
288 However, you can override that requirement by using the
289 "-a" or "--any-recipe" option.
290 Using either of these options allows you to edit any recipe
291 regardless of its location.
292 </para>
293 </section>
294
295 <section id='devtool-updating-a-recipe'>
296 <title>Updating a Recipe</title>
297
298 <para>
299 Use the <filename>devtool update-recipe</filename> command to
300 update your recipe with patches that reflect changes you make
301 to the source files.
302 For example, if you know you are going to work on some
303 code, you could first use the
304 <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.
306 After which, you could modify, compile, and test the code.
307 </para>
308
309 <para>
310 When you are satisfied with the results and you have committed
311 your changes to the Git repository, you can then
312 run the <filename>devtool update-recipe</filename> to create the
313 patches and update the recipe:
314 <literallayout class='monospaced'>
315 $ devtool update-recipe <replaceable>recipe</replaceable>
316 </literallayout>
317 If you run the <filename>devtool update-recipe</filename>
318 without committing your changes, the command ignores the
319 changes.
320 </para>
321
322 <para>
323 Often, you might want to apply customizations made to your
324 software in your own layer rather than apply them to the
325 original recipe.
326 If so, you can use the
327 <filename>-a</filename> or <filename>--append</filename>
328 option with the <filename>devtool update-recipe</filename>
329 command.
330 These options allow you to specify the layer into which to
331 write an append file:
332 <literallayout class='monospaced'>
333 $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable>
334 </literallayout>
335 The <filename>*.bbappend</filename> file is created at the
336 appropriate path within the specified layer directory, which
337 may or may not be in your <filename>bblayers.conf</filename>
338 file.
339 If an append file already exists, the command updates it
340 appropriately.
341 </para>
342 </section>
343
344 <section id='devtool-upgrading-a-recipe'>
345 <title>Upgrading a Recipe</title>
346
347 <para>
348 Use the <filename>devtool upgrade</filename> command
349 to upgrade an existing recipe to a new upstream version.
350 The command puts the upgraded recipe file into the
351 workspace along with any associated files, and extracts
352 the source tree to a specified location should patches
353 need rebased or added to as a result of the upgrade.
354 </para>
355
356 <para>
357 When you use the <filename>devtool upgrade</filename> command,
358 you must supply the root name of the recipe (i.e. no version,
359 paths, or extensions), and you must supply the directory
360 to which you want the source extracted.
361 Additional command options let you control things such as
362 the version number to which you want to upgrade (i.e. the
363 <link linkend='var-PV'><filename>PV</filename></link>),
364 the source revision to which you want to upgrade (i.e. the
365 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>,
366 whether or not to apply patches, and so forth.
367 </para>
368 </section>
369
370 <section id='devtool-resetting-a-recipe'>
371 <title>Resetting a Recipe</title>
372
373 <para>
374 Use the <filename>devtool reset</filename> command to remove a
375 recipe and its configuration (e.g. the corresponding
376 <filename>.bbappend</filename> file) from the workspace layer.
377 Realize that this command deletes the recipe and the
378 append file.
379 The command does not physically move them for you.
380 Consequently, you must be sure to physically relocate your
381 updated recipe and the append file outside of the workspace
382 layer before running the <filename>devtool reset</filename>
383 command.
384 </para>
385
386 <para>
387 If the <filename>devtool reset</filename> command detects that
388 the recipe or the append files have been modified, the
389 command preserves the modified files in a separate "attic"
390 subdirectory under the workspace layer.
391 </para>
392
393 <para>
394 Here is an example that resets the workspace directory that
395 contains the <filename>mtr</filename> recipe:
396 <literallayout class='monospaced'>
397 $ devtool reset mtr
398 NOTE: Cleaning sysroot for recipe mtr...
399 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
401 $
402 </literallayout>
403 </para>
404 </section>
405
406 <section id='devtool-building-your-recipe'>
407 <title>Building Your Recipe</title>
408
409 <para>
410 Use the <filename>devtool build</filename> command to cause the
411 OpenEmbedded build system to build your recipe.
412 The <filename>devtool build</filename> command is equivalent to
413 <filename>bitbake -c populate_sysroot</filename>.
414 </para>
415
416 <para>
417 When you use the <filename>devtool build</filename> command,
418 you must supply the root name of the recipe (i.e. no version,
419 paths, or extensions).
420 You can use either the "-s" or the "--disable-parallel-make"
421 option to disable parallel makes during the build.
422 Here is an example:
423 <literallayout class='monospaced'>
424 $ devtool build <replaceable>recipe</replaceable>
425 </literallayout>
426 </para>
427 </section>
428
429 <section id='devtool-building-your-image'>
430 <title>Building Your Image</title>
431
432 <para>
433 Use the <filename>devtool build-image</filename> command
434 to build an image, extending it to include packages from
435 recipes in the workspace.
436 Using this command is useful when you want an image that
437 ready for immediate deployment onto a device for testing.
438 For proper integration into a final image, you need to
439 edit your custom image recipe appropriately.
440 </para>
441
442 <para>
443 When you use the <filename>devtool build-image</filename>
444 command, you must supply the name of the image.
445 This command has no command line options:
446 <literallayout class='monospaced'>
447 $ devtool build-image <replaceable>image</replaceable>
448 </literallayout>
449 </para>
450 </section>
451
452 <section id='devtool-deploying-your-software-on-the-target-machine'>
453 <title>Deploying Your Software on the Target Machine</title>
454
455 <para>
456 Use the <filename>devtool deploy-target</filename> command to
457 deploy the recipe's build output to the live target machine:
458 <literallayout class='monospaced'>
459 $ devtool deploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
460 </literallayout>
461 The <replaceable>target</replaceable> is the address of the
462 target machine, which must be running an SSH server (i.e.
463 <filename>user@hostname[:destdir]</filename>).
464 </para>
465
466 <para>
467 This command deploys all files installed during the
468 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
469 task.
470 Furthermore, you do not need to have package management enabled
471 within the target machine.
472 If you do, the package manager is bypassed.
473 <note><title>Notes</title>
474 <para>
475 The <filename>deploy-target</filename>
476 functionality is for development only.
477 You should never use it to update an image that will be
478 used in production.
479 </para>
480 </note>
481 </para>
482 </section>
483
484 <section id='devtool-removing-your-software-from-the-target-machine'>
485 <title>Removing Your Software from the Target Machine</title>
486
487 <para>
488 Use the <filename>devtool undeploy-target</filename> command to
489 remove deployed build output from the target machine.
490 For the <filename>devtool undeploy-target</filename> command to
491 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>
493 command.
494 <literallayout class='monospaced'>
495 $ devtool undeploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
496 </literallayout>
497 The <replaceable>target</replaceable> is the address of the
498 target machine, which must be running an SSH server (i.e.
499 <filename>user@hostname</filename>).
500 </para>
501 </section>
502
503 <section id='devtool-creating-the-workspace'>
504 <title>Creating the Workspace Layer in an Alternative Location</title>
505
506 <para>
507 Use the <filename>devtool create-workspace</filename> command to
508 create a new workspace layer in your
509 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
510 When you create a new workspace layer, it is populated with the
511 <filename>README</filename> file and the
512 <filename>conf</filename> directory only.
513 </para>
514
515 <para>
516 The following example creates a new workspace layer in your
517 current working and by default names the workspace layer
518 "workspace":
519 <literallayout class='monospaced'>
520 $ devtool create-workspace
521 </literallayout>
522 </para>
523
524 <para>
525 You can create a workspace layer anywhere by supplying
526 a pathname with the command.
527 The following command creates a new workspace layer named
528 "new-workspace":
529 <literallayout class='monospaced'>
530 $ devtool create-workspace /home/scottrif/new-workspace
531 </literallayout>
532 </para>
533 </section>
534
535 <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'>
536 <title>Get the Status of the Recipes in Your Workspace</title>
537
538 <para>
539 Use the <filename>devtool status</filename> command to
540 list the recipes currently in your workspace.
541 Information includes the paths to their respective
542 external source trees.
543 </para>
544
545 <para>
546 The <filename>devtool status</filename> command has no
547 command-line options:
548 <literallayout class='monospaced'>
549 devtool status
550 </literallayout>
551 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>
553 to create and add the <filename>mtr_0.86.bb</filename> recipe
554 to the <filename>workspace</filename> directory:
555 <literallayout class='monospaced'>
556 $ devtool status
557 mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
558 $
559 </literallayout>
560 </para>
561 </section>
562
563 <section id='devtool-search-for-available-target-recipes'>
564 <title>Search for Available Target Recipes</title>
565
566 <para>
567 Use the <filename>devtool search</filename> command to
568 search for available target recipes.
569 The command matches the recipe name, package name,
570 description, and installed files.
571 The command displays the recipe name as a result of a
572 match.
573 </para>
574
575 <para>
576 When you use the <filename>devtool search</filename> command,
577 you must supply a <replaceable>keyword</replaceable>.
578 The command uses the <replaceable>keyword</replaceable> when
579 searching for a match.
580 </para>
581 </section>
582</chapter>
583<!--
584vim: expandtab tw=80 ts=4
585-->
diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml
index d375157b73..1aca3898e5 100644
--- a/documentation/ref-manual/ref-manual.xml
+++ b/documentation/ref-manual/ref-manual.xml
@@ -145,6 +145,8 @@
145 145
146 <xi:include href="ref-tasks.xml"/> 146 <xi:include href="ref-tasks.xml"/>
147 147
148 <xi:include href="ref-devtool-reference.xml"/>
149
148 <xi:include href="ref-qa-checks.xml"/> 150 <xi:include href="ref-qa-checks.xml"/>
149 151
150 <xi:include href="ref-images.xml"/> 152 <xi:include href="ref-images.xml"/>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-19 20:31:48 +0000