summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-07-03 15:27:58 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-07-12 00:28:15 +0100
commit293b53674c1c97a29a8beaffc82130e90c0d3c2b (patch)
treeceb465c56599a684e7041803100a94f4646dab92 /documentation
parentb15a65b8ea60032cf113196420a16183d0a0585a (diff)
downloadpoky-293b53674c1c97a29a8beaffc82130e90c0d3c2b.tar.gz
documentation: Moved devtool workflow to sdk manual
Fixes [YOCTO #11630] The section on the devtool workflow in the dev-manual was 99% identical to what was in the sdk-manual. I have moved the workflow procedure from the old "Model" chapter of the dev-manual to be merged with what was in the sdk-manual. In truth, the only things added were a note about devtool not being exclusive to SDK development. The result of moving (deleting) this section was that the "model" chapter of the dev-manual went away. The devtool stuff, Quilt, devshell, and python shell are all out now and there is no chapter left. So, mega-manual had to be adjusted to not pull that chapter in when building the dev-manual. I had to delete three figures that were used in the flow. The figures were already replicated in the sdk-manual. The figures were deleted from the figures folder of both the dev-manual and the mega-manual. I had to make sure all references to the old devtool stuf in the YP doc set were adjusted. (From yocto-docs rev: 5dbd643d31ab502df53a22229e457a03da7772b7) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/Makefile5
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml17
-rw-r--r--documentation/dev-manual/dev-manual-model.xml721
-rw-r--r--documentation/dev-manual/dev-manual-start.xml8
-rw-r--r--documentation/dev-manual/dev-manual.xml2
-rw-r--r--documentation/dev-manual/figures/devtool-add-flow.pngbin177945 -> 0 bytes
-rw-r--r--documentation/dev-manual/figures/devtool-modify-flow.pngbin164192 -> 0 bytes
-rw-r--r--documentation/dev-manual/figures/devtool-upgrade-flow.pngbin139827 -> 0 bytes
-rw-r--r--documentation/kernel-dev/kernel-dev-intro.xml8
-rw-r--r--documentation/mega-manual/figures/devtool-add-flow.pngbin179361 -> 0 bytes
-rw-r--r--documentation/mega-manual/figures/devtool-modify-flow.pngbin152662 -> 0 bytes
-rw-r--r--documentation/mega-manual/figures/devtool-upgrade-flow.pngbin140597 -> 0 bytes
-rw-r--r--documentation/mega-manual/mega-manual.xml2
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml15
-rw-r--r--documentation/yocto-project-qs/yocto-project-qs.xml4
15 files changed, 34 insertions, 748 deletions
diff --git a/documentation/Makefile b/documentation/Makefile
index 770ef93f37..167b73e2cd 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -131,8 +131,6 @@ TARFILES = dev-style.css dev-manual.html \
131TARFILES = dev-style.css dev-manual.html \ 131TARFILES = dev-style.css dev-manual.html \
132 figures/dev-title.png \ 132 figures/dev-title.png \
133 figures/recipe-workflow.png \ 133 figures/recipe-workflow.png \
134 figures/devtool-add-flow.png figures/devtool-modify-flow.png \
135 figures/devtool-upgrade-flow.png \
136 eclipse 134 eclipse
137 endif 135 endif
138 136
@@ -241,8 +239,7 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \
241 figures/sdk-generation.png figures/recipe-workflow.png \ 239 figures/sdk-generation.png figures/recipe-workflow.png \
242 figures/build-workspace-directory.png figures/mega-title.png \ 240 figures/build-workspace-directory.png figures/mega-title.png \
243 figures/toaster-title.png figures/hosted-service.png \ 241 figures/toaster-title.png figures/hosted-service.png \
244 figures/simple-configuration.png figures/devtool-add-flow.png \ 242 figures/simple-configuration.png \
245 figures/devtool-modify-flow.png figures/devtool-upgrade-flow.png \
246 figures/compatible-layers.png figures/import-layer.png figures/new-project.png \ 243 figures/compatible-layers.png figures/import-layer.png figures/new-project.png \
247 figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \ 244 figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \
248 figures/sdk-devtool-add-flow.png figures/sdk-installed-extensible-sdk-directory.png \ 245 figures/sdk-devtool-add-flow.png figures/sdk-installed-extensible-sdk-directory.png \
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index c6efcf6699..f040c402c4 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1516,8 +1516,9 @@
1516 <para> 1516 <para>
1517 You can find a complete description of the 1517 You can find a complete description of the
1518 <filename>devtool add</filename> command in the 1518 <filename>devtool add</filename> command in the
1519 "<link linkend='use-devtool-to-integrate-new-code'>Use <filename>devtool add</filename> to Add an Application</link>" 1519 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-a-closer-look-at-devtool-add'>A Closer Look at <filename>devtool</filename> add</ulink>"
1520 section. 1520 section in the Yocto Project Software Development Kit
1521 (SDK) Developer's Guide.
1521 </para> 1522 </para>
1522 </section> 1523 </section>
1523 1524
@@ -4081,10 +4082,11 @@
4081 <note><title>Tip</title> 4082 <note><title>Tip</title>
4082 With regard to preserving changes to source files, if you 4083 With regard to preserving changes to source files, if you
4083 clean a recipe or have <filename>rm_work</filename> enabled, 4084 clean a recipe or have <filename>rm_work</filename> enabled,
4084 the workflow described in the 4085 the
4085 "<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>" 4086 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink>
4086 section is a safer development flow than the flow that 4087 as described in the Yocto Project Software Development Kit
4087 uses Quilt. 4088 (SDK) Developer's Guide is a safer development flow than the
4089 flow that uses Quilt.
4088 </note> 4090 </note>
4089 </para> 4091 </para>
4090 4092
@@ -6966,7 +6968,8 @@
6966 6968
6967 <para> 6969 <para>
6968 Two methods exist by which you can create the patch: 6970 Two methods exist by which you can create the patch:
6969 <link linkend='using-devtool-in-your-workflow'><filename>devtool</filename></link> and 6971 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
6972 and
6970 <link linkend='using-a-quilt-workflow'>Quilt</link>. 6973 <link linkend='using-a-quilt-workflow'>Quilt</link>.
6971 For kernel patches, the Git workflow is more appropriate. 6974 For kernel patches, the Git workflow is more appropriate.
6972 This section assumes the Git workflow and shows the steps specific to 6975 This section assumes the Git workflow and shows the steps specific to
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
deleted file mode 100644
index aeaa3fd9d3..0000000000
--- a/documentation/dev-manual/dev-manual-model.xml
+++ /dev/null
@@ -1,721 +0,0 @@
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='dev-manual-model'>
6
7<title>Common Development Models</title>
8
9<para>
10 Many development models exist for which you can use the Yocto Project.
11 This chapter overviews simple methods that use tools provided by the
12 Yocto Project:
13 <itemizedlist>
14 <listitem><para><emphasis>System Development:</emphasis>
15 System Development covers Board Support Package (BSP) development
16 and kernel modification or configuration.
17 For an example on how to create a BSP, see the
18 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
19 section in the Yocto Project Board Support Package (BSP)
20 Developer's Guide.
21 For more complete information on how to work with the kernel,
22 see the
23 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
24 </para></listitem>
25 <listitem><para><emphasis>Temporary Source Code Modification:</emphasis>
26 Direct modification of temporary source code is a convenient
27 development model to quickly iterate and develop towards a
28 solution.
29 Once you implement the solution, you should of course take
30 steps to get the changes upstream and applied in the affected
31 recipes.
32 </para></listitem>
33 <listitem><para><emphasis>Using a Development Shell:</emphasis>
34 You can use a
35 <link linkend='platdev-appdev-devshell'><filename>devshell</filename></link>
36 to efficiently debug
37 commands or simply edit packages.
38 Working inside a development shell is a quick way to set up the
39 OpenEmbedded build environment to work on parts of a project.
40 </para></listitem>
41 </itemizedlist>
42</para>
43
44<section id="dev-modifying-source-code">
45 <title>Modifying Source Code</title>
46
47 <para>
48 A common development workflow consists of modifying project source
49 files that are external to the Yocto Project and then integrating
50 that project's build output into an image built using the
51 OpenEmbedded build system.
52 Given this scenario, development engineers typically want to stick
53 to their familiar project development tools and methods, which allows
54 them to just focus on the project.
55 </para>
56
57 <para>
58 Several workflows exist that allow you to develop, build, and test
59 code that is going to be integrated into an image built using the
60 OpenEmbedded build system.
61 This section describes two:
62 <itemizedlist>
63 <listitem><para><emphasis><filename>devtool</filename>:</emphasis>
64 A set of tools to aid in working on the source code built by
65 the OpenEmbedded build system.
66 Section
67 "<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>"
68 describes this workflow.
69 If you want more information that showcases the workflow, click
70 <ulink url='https://drive.google.com/a/linaro.org/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view'>here</ulink>
71 for a presentation by Trevor Woerner that, while somewhat dated,
72 provides detailed background information and a complete
73 working tutorial.
74 </para></listitem>
75 <listitem><para><emphasis><ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>:</emphasis>
76 A powerful tool that allows you to capture source
77 code changes without having a clean source tree.
78 While Quilt is not the preferred workflow of the two, this
79 section includes it for users that are committed to using
80 the tool.
81 See the
82 "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>"
83 section for more information.
84 </para></listitem>
85 </itemizedlist>
86 </para>
87
88 <section id='using-devtool-in-your-workflow'>
89 <title>Using <filename>devtool</filename> in Your Workflow</title>
90
91 <para>
92 As mentioned earlier, <filename>devtool</filename> helps
93 you easily develop projects whose build output must be part of
94 an image built using the OpenEmbedded build system.
95 </para>
96
97 <para>
98 Three entry points exist that allow you to develop using
99 <filename>devtool</filename>:
100 <itemizedlist>
101 <listitem><para><emphasis><filename>devtool add</filename></emphasis>
102 </para></listitem>
103 <listitem><para><emphasis><filename>devtool modify</filename></emphasis>
104 </para></listitem>
105 <listitem><para><emphasis><filename>devtool upgrade</filename></emphasis>
106 </para></listitem>
107 </itemizedlist>
108 </para>
109
110 <para>
111 The remainder of this section presents these workflows.
112 See the
113 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
114 in the Yocto Project Reference Manual for a
115 <filename>devtool</filename> quick reference.
116 </para>
117
118 <section id='use-devtool-to-integrate-new-code'>
119 <title>Use <filename>devtool add</filename> to Add an Application</title>
120
121 <para>
122 The <filename>devtool add</filename> command generates
123 a new recipe based on existing source code.
124 This command takes advantage of the
125 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
126 layer that many <filename>devtool</filename> commands
127 use.
128 The command is flexible enough to allow you to extract source
129 code into both the workspace or a separate local Git repository
130 and to use existing code that does not need to be extracted.
131 </para>
132
133 <para>
134 Depending on your particular scenario, the arguments and options
135 you use with <filename>devtool add</filename> form different
136 combinations.
137 The following diagram shows common development flows
138 you would use with the <filename>devtool add</filename>
139 command:
140 </para>
141
142 <para>
143 <imagedata fileref="figures/devtool-add-flow.png" align="center" />
144 </para>
145
146 <para>
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'>
176 $ devtool add <replaceable>recipe fetchuri</replaceable>
177 </literallayout>
178 With this command, <filename>devtool</filename>
179 creates a recipe and an append file in the
180 workspace as well as extracts the upstream
181 source files into a local Git repository also
182 within the <filename>sources</filename> folder.
183 </para></listitem>
184 <listitem><para><emphasis>Middle</emphasis>:
185 The middle scenario also represents a situation where
186 the source code does not exist locally.
187 In this case, the code is again upstream
188 and needs to be extracted to some
189 local area - this time outside of the default
190 workspace.
191 If required, <filename>devtool</filename>
192 always creates
193 a Git repository locally during the extraction.
194 Furthermore, the first positional argument
195 <replaceable>srctree</replaceable> in this case
196 identifies where the
197 <filename>devtool add</filename> command
198 will locate the extracted code outside of the
199 workspace:
200 <literallayout class='monospaced'>
201 $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
202 </literallayout>
203 In summary, the source code is pulled from
204 <replaceable>fetchuri</replaceable> and extracted
205 into the location defined by
206 <replaceable>srctree</replaceable> as a local
207 Git repository.</para>
208
209 <para>Within workspace, <filename>devtool</filename>
210 creates both the recipe and an append file
211 for the recipe.
212 </para></listitem>
213 <listitem><para><emphasis>Right</emphasis>:
214 The right scenario represents a situation
215 where the source tree (srctree) has been
216 previously prepared outside of the
217 <filename>devtool</filename> workspace.
218 </para>
219
220 <para>The following command names the recipe
221 and identifies where the existing source tree
222 is located:
223 <literallayout class='monospaced'>
224 $ devtool add <replaceable>recipe srctree</replaceable>
225 </literallayout>
226 The command examines the source code and creates
227 a recipe for it placing the recipe into the
228 workspace.</para>
229
230 <para>Because the extracted source code already exists,
231 <filename>devtool</filename> does not try to
232 relocate it into the workspace - just the new
233 the recipe is placed in the workspace.</para>
234
235 <para>Aside from a recipe folder, the command
236 also creates an append folder and places an initial
237 <filename>*.bbappend</filename> within.
238 </para></listitem>
239 </itemizedlist>
240 </para></listitem>
241 <listitem><para><emphasis>Edit the Recipe</emphasis>:
242 At this point, you can use <filename>devtool edit-recipe</filename>
243 to open up the editor as defined by the
244 <filename>$EDITOR</filename> environment variable
245 and modify the file:
246 <literallayout class='monospaced'>
247 $ devtool edit-recipe <replaceable>recipe</replaceable>
248 </literallayout>
249 From within the editor, you can make modifications to the
250 recipe that take affect when you build it later.
251 </para></listitem>
252 <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:
253 At this point in the flow, the next step you
254 take depends on what you are going to do with
255 the new code.</para>
256 <para>If you need to take the build output and eventually
257 move it to the target hardware, you would use
258 <filename>devtool build</filename>:
259 <literallayout class='monospaced'>
260 $ devtool build <replaceable>recipe</replaceable>
261 </literallayout></para>
262 <para>On the other hand, if you want an image to
263 contain the recipe's packages for immediate deployment
264 onto a device (e.g. for testing purposes), you can use
265 the <filename>devtool build-image</filename> command:
266 <literallayout class='monospaced'>
267 $ devtool build-image <replaceable>image</replaceable>
268 </literallayout>
269 </para></listitem>
270 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
271 When you use the <filename>devtool build</filename>
272 command to build out your recipe, you probably want to
273 see if the resulting build output works as expected on target
274 hardware.
275 <note>
276 This step assumes you have a previously built
277 image that is already either running in QEMU or
278 running on actual hardware.
279 Also, it is assumed that for deployment of the image
280 to the target, SSH is installed in the image and if
281 the image is running on real hardware that you have
282 network access to and from your development machine.
283 </note>
284 You can deploy your build output to that target hardware by
285 using the <filename>devtool deploy-target</filename> command:
286 <literallayout class='monospaced'>
287 $ devtool deploy-target <replaceable>recipe target</replaceable>
288 </literallayout>
289 The <replaceable>target</replaceable> is a live target machine
290 running as an SSH server.</para>
291
292 <para>You can, of course, also deploy the image you build
293 using the <filename>devtool build-image</filename> command
294 to actual hardware.
295 However, <filename>devtool</filename> does not provide a
296 specific command that allows you to do this.
297 </para></listitem>
298 <listitem><para>
299 <emphasis>Finish Your Work With the Recipe</emphasis>:
300 The <filename>devtool finish</filename> command creates
301 any patches corresponding to commits in the local
302 Git repository, moves the new recipe to a more permanent
303 layer, and then resets the recipe so that the recipe is
304 built normally rather than from the workspace.
305 <literallayout class='monospaced'>
306 $ devtool finish <replaceable>recipe layer</replaceable>
307 </literallayout>
308 <note>
309 Any changes you want to turn into patches must be
310 committed to the Git repository in the source tree.
311 </note></para>
312
313 <para>As mentioned, the <filename>devtool finish</filename>
314 command moves the final recipe to its permanent layer.
315 </para>
316
317 <para>As a final process of the
318 <filename>devtool finish</filename> command, the state
319 of the standard layers and the upstream source is
320 restored so that you can build the recipe from those
321 areas rather than the workspace.
322 <note>
323 You can use the <filename>devtool reset</filename>
324 command to put things back should you decide you
325 do not want to proceed with your work.
326 If you do use this command, realize that the source
327 tree is preserved.
328 </note>
329 </para></listitem>
330 </orderedlist>
331 </para>
332 </section>
333
334 <section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'>
335 <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title>
336
337 <para>
338 The <filename>devtool modify</filename> command prepares the
339 way to work on existing code that already has a recipe in
340 place.
341 The command is flexible enough to allow you to extract code,
342 specify the existing recipe, and keep track of and gather any
343 patch files from other developers that are
344 associated with the code.
345 </para>
346
347 <para>
348 Depending on your particular scenario, the arguments and options
349 you use with <filename>devtool modify</filename> form different
350 combinations.
351 The following diagram shows common development flows
352 you would use with the <filename>devtool modify</filename>
353 command:
354 </para>
355
356 <para>
357 <imagedata fileref="figures/devtool-modify-flow.png" align="center" />
358 </para>
359
360 <para>
361 <orderedlist>
362 <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
363 The top part of the flow shows three scenarios by which
364 you could use <filename>devtool modify</filename> to
365 prepare to work on source files.
366 Each scenario assumes the following:
367 <itemizedlist>
368 <listitem><para>The recipe exists in some layer external
369 to the <filename>devtool</filename> workspace.
370 </para></listitem>
371 <listitem><para>The source files exist upstream in an
372 un-extracted state or locally in a previously
373 extracted state.
374 </para></listitem>
375 </itemizedlist>
376 The typical situation is where another developer has
377 created some layer for use with the Yocto Project and
378 their recipe already resides in that layer.
379 Furthermore, their source code is readily available
380 either upstream or locally.
381 <itemizedlist>
382 <listitem><para><emphasis>Left</emphasis>:
383 The left scenario represents a common situation
384 where the source code does not exist locally
385 and needs to be extracted.
386 In this situation, the source is extracted
387 into the default workspace location.
388 The recipe, in this scenario, is in its own
389 layer outside the workspace
390 (i.e.
391 <filename>meta-</filename><replaceable>layername</replaceable>).
392 </para>
393
394 <para>The following command identifies the recipe
395 and by default extracts the source files:
396 <literallayout class='monospaced'>
397 $ devtool modify <replaceable>recipe</replaceable>
398 </literallayout>
399 Once <filename>devtool</filename>locates the recipe,
400 it uses the
401 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
402 variable to locate the source code and
403 any local patch files from other developers are
404 located.
405 <note>
406 You cannot provide an URL for
407 <replaceable>srctree</replaceable> when using the
408 <filename>devtool modify</filename> command.
409 </note>
410 With this scenario, however, since no
411 <replaceable>srctree</replaceable> argument exists, the
412 <filename>devtool modify</filename> command by default
413 extracts the source files to a Git structure.
414 Furthermore, the location for the extracted source is the
415 default area within the workspace.
416 The result is that the command sets up both the source
417 code and an append file within the workspace with the
418 recipe remaining in its original location.
419 </para></listitem>
420 <listitem><para><emphasis>Middle</emphasis>:
421 The middle scenario represents a situation where
422 the source code also does not exist locally.
423 In this case, the code is again upstream
424 and needs to be extracted to some
425 local area as a Git repository.
426 The recipe, in this scenario, is again in its own
427 layer outside the workspace.</para>
428
429 <para>The following command tells
430 <filename>devtool</filename> what recipe with
431 which to work and, in this case, identifies a local
432 area for the extracted source files that is outside
433 of the default workspace:
434 <literallayout class='monospaced'>
435 $ devtool modify <replaceable>recipe srctree</replaceable>
436 </literallayout>
437 As with all extractions, the command uses
438 the recipe's <filename>SRC_URI</filename> to locate the
439 source files.
440 Once the files are located, the command by default
441 extracts them.
442 Providing the <replaceable>srctree</replaceable>
443 argument instructs <filename>devtool</filename> where
444 to place the extracted source.</para>
445
446 <para>Within workspace, <filename>devtool</filename>
447 creates an append file for the recipe.
448 The recipe remains in its original location but
449 the source files are extracted to the location you
450 provided with <replaceable>srctree</replaceable>.
451 </para></listitem>
452 <listitem><para><emphasis>Right</emphasis>:
453 The right scenario represents a situation
454 where the source tree
455 (<replaceable>srctree</replaceable>) exists as a
456 previously extracted Git structure outside of
457 the <filename>devtool</filename> workspace.
458 In this example, the recipe also exists
459 elsewhere in its own layer.
460 </para>
461
462 <para>The following command tells
463 <filename>devtool</filename> the recipe
464 with which to work, uses the "-n" option to indicate
465 source does not need to be extracted, and uses
466 <replaceable>srctree</replaceable> to point to the
467 previously extracted source files:
468 <literallayout class='monospaced'>
469 $ devtool modify -n <replaceable>recipe srctree</replaceable>
470 </literallayout>
471 </para>
472
473 <para>Once the command finishes, it creates only
474 an append file for the recipe in the workspace.
475 The recipe and the source code remain in their
476 original locations.
477 </para></listitem>
478 </itemizedlist>
479 </para></listitem>
480 <listitem><para><emphasis>Edit the Source</emphasis>:
481 Once you have used the <filename>devtool modify</filename>
482 command, you are free to make changes to the source
483 files.
484 You can use any editor you like to make and save
485 your source code modifications.
486 </para></listitem>
487 <listitem><para><emphasis>Build the Recipe</emphasis>:
488 Once you have updated the source files, you can build
489 the recipe.
490 </para></listitem>
491 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
492 When you use the <filename>devtool build</filename>
493 command to build out your recipe, you probably want to see
494 if the resulting build output works as expected on target
495 hardware.
496 <note>
497 This step assumes you have a previously built
498 image that is already either running in QEMU or
499 running on actual hardware.
500 Also, it is assumed that for deployment of the image
501 to the target, SSH is installed in the image and if
502 the image is running on real hardware that you have
503 network access to and from your development machine.
504 </note>
505 You can deploy your build output to that target hardware by
506 using the <filename>devtool deploy-target</filename> command:
507 <literallayout class='monospaced'>
508 $ devtool deploy-target <replaceable>recipe target</replaceable>
509 </literallayout>
510 The <replaceable>target</replaceable> is a live target machine
511 running as an SSH server.</para>
512
513 <para>You can, of course, also deploy the image you build
514 using the <filename>devtool build-image</filename> command
515 to actual hardware.
516 However, <filename>devtool</filename> does not provide a
517 specific command that allows you to do this.
518 </para></listitem>
519 <listitem><para>
520 <emphasis>Finish Your Work With the Recipe</emphasis>:
521 The <filename>devtool finish</filename> command creates
522 any patches corresponding to commits in the local
523 Git repository, updates the recipe to point to them
524 (or creates a <filename>.bbappend</filename> file to do
525 so, depending on the specified destination layer), and
526 then resets the recipe so that the recipe is built normally
527 rather than from the workspace.
528 <literallayout class='monospaced'>
529 $ devtool finish <replaceable>recipe layer</replaceable>
530 </literallayout>
531 <note>
532 Any changes you want to turn into patches must be
533 committed to the Git repository in the source tree.
534 </note></para>
535
536 <para>Because there is no need to move the recipe,
537 <filename>devtool finish</filename> either updates the
538 original recipe in the original layer or the command
539 creates a <filename>.bbappend</filename> in a different
540 layer as provided by <replaceable>layer</replaceable>.
541 </para>
542
543 <para>As a final process of the
544 <filename>devtool finish</filename> command, the state
545 of the standard layers and the upstream source is
546 restored so that you can build the recipe from those
547 areas rather than the workspace.
548 <note>
549 You can use the <filename>devtool reset</filename>
550 command to put things back should you decide you
551 do not want to proceed with your work.
552 If you do use this command, realize that the source
553 tree is preserved.
554 </note>
555 </para></listitem>
556 </orderedlist>
557 </para>
558 </section>
559
560 <section id='devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
561 <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
562
563 <para>
564 The <filename>devtool upgrade</filename> command updates
565 an existing recipe so that you can build it for an updated
566 set of source files.
567 The command is flexible enough to allow you to specify
568 source code revision and versioning schemes, extract code into
569 or out of the <filename>devtool</filename> workspace, and
570 work with any source file forms that the fetchers support.
571 </para>
572
573 <para>
574 The following diagram shows the common development flow
575 you would use with the <filename>devtool upgrade</filename>
576 command:
577 </para>
578
579 <para>
580 <imagedata fileref="figures/devtool-upgrade-flow.png" align="center" />
581 </para>
582
583 <para>
584 <orderedlist>
585 <listitem><para><emphasis>Initiate the Upgrade</emphasis>:
586 The top part of the flow shows a typical scenario by which
587 you could use <filename>devtool upgrade</filename>.
588 The following conditions exist:
589 <itemizedlist>
590 <listitem><para>The recipe exists in some layer external
591 to the <filename>devtool</filename> workspace.
592 </para></listitem>
593 <listitem><para>The source files for the new release
594 exist adjacent to the same location pointed to by
595 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
596 in the recipe (e.g. a tarball with the new version
597 number in the name, or as a different revision in
598 the upstream Git repository).
599 </para></listitem>
600 </itemizedlist>
601 A common situation is where third-party software has
602 undergone a revision so that it has been upgraded.
603 The recipe you have access to is likely in your own layer.
604 Thus, you need to upgrade the recipe to use the
605 newer version of the software:
606 <literallayout class='monospaced'>
607 $ devtool upgrade -V <replaceable>version recipe</replaceable>
608 </literallayout>
609 By default, the <filename>devtool upgrade</filename> command
610 extracts source code into the <filename>sources</filename>
611 directory in the workspace.
612 If you want the code extracted to any other location, you
613 need to provide the <replaceable>srctree</replaceable>
614 positional argument with the command as follows:
615 <literallayout class='monospaced'>
616 $ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
617 </literallayout>
618 Also, in this example, the "-V" option is used to specify
619 the new version.
620 If the source files pointed to by the
621 <filename>SRC_URI</filename> statement in the recipe are
622 in a Git repository, you must provide the "-S" option and
623 specify a revision for the software.</para>
624
625 <para>Once <filename>devtool</filename> locates the recipe,
626 it uses the <filename>SRC_URI</filename> variable to locate
627 the source code and any local patch files from other
628 developers are located.
629 The result is that the command sets up the source
630 code, the new version of the recipe, and an append file
631 all within the workspace.
632 </para></listitem>
633 <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
634 At this point, there could be some conflicts due to the
635 software being upgraded to a new version.
636 This would occur if your recipe specifies some patch files in
637 <filename>SRC_URI</filename> that conflict with changes
638 made in the new version of the software.
639 If this is the case, you need to resolve the conflicts
640 by editing the source and following the normal
641 <filename>git rebase</filename> conflict resolution
642 process.</para>
643
644 <para>Before moving onto the next step, be sure to resolve any
645 such conflicts created through use of a newer or different
646 version of the software.
647 </para></listitem>
648 <listitem><para><emphasis>Build the Recipe</emphasis>:
649 Once you have your recipe in order, you can build it.
650 You can either use <filename>devtool build</filename> or
651 <filename>bitbake</filename>.
652 Either method produces build output that is stored
653 in
654 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
655 </para></listitem>
656 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
657 When you use the <filename>devtool build</filename>
658 command or <filename>bitbake</filename> to build out your
659 recipe, you probably want to see if the resulting build
660 output works as expected on target hardware.
661 <note>
662 This step assumes you have a previously built
663 image that is already either running in QEMU or
664 running on actual hardware.
665 Also, it is assumed that for deployment of the image
666 to the target, SSH is installed in the image and if
667 the image is running on real hardware that you have
668 network access to and from your development machine.
669 </note>
670 You can deploy your build output to that target hardware by
671 using the <filename>devtool deploy-target</filename> command:
672 <literallayout class='monospaced'>
673 $ devtool deploy-target <replaceable>recipe target</replaceable>
674 </literallayout>
675 The <replaceable>target</replaceable> is a live target machine
676 running as an SSH server.</para>
677
678 <para>You can, of course, also deploy the image you build
679 using the <filename>devtool build-image</filename> command
680 to actual hardware.
681 However, <filename>devtool</filename> does not provide a
682 specific command that allows you to do this.
683 </para></listitem>
684 <listitem><para>
685 <emphasis>Finish Your Work With the Recipe</emphasis>:
686 The <filename>devtool finish</filename> command creates
687 any patches corresponding to commits in the local
688 Git repository, moves the new recipe to a more permanent
689 layer, and then resets the recipe so that the recipe is
690 built normally rather than from the workspace.
691 If you specify a destination layer that is the same as
692 the original source, then the old version of the
693 recipe and associated files will be removed prior to
694 adding the new version.
695 <literallayout class='monospaced'>
696 $ devtool finish <replaceable>recipe layer</replaceable>
697 </literallayout>
698 <note>
699 Any changes you want to turn into patches must be
700 committed to the Git repository in the source tree.
701 </note></para>
702 <para>As a final process of the
703 <filename>devtool finish</filename> command, the state
704 of the standard layers and the upstream source is
705 restored so that you can build the recipe from those
706 areas rather than the workspace.
707 <note>
708 You can use the <filename>devtool reset</filename>
709 command to put things back should you decide you
710 do not want to proceed with your work.
711 If you do use this command, realize that the source
712 tree is preserved.
713 </note>
714 </para></listitem>
715 </orderedlist>
716 </para>
717 </section>
718 </section>
719</section>
720
721</chapter>
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 37576537b4..09b13c7783 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -199,10 +199,10 @@
199 <title>Setting Up to Work on a Kernel</title> 199 <title>Setting Up to Work on a Kernel</title>
200 200
201 <para> 201 <para>
202 Kernel development is best accomplished using the 202 Kernel development is best accomplished using
203 <filename>devtool</filename> tool and not through traditional 203 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
204 kernel workflow methods. 204 and not through traditional kernel workflow methods.
205 This section provides procedures for both. 205 This section provides procedures to set up for both.
206 </para> 206 </para>
207 207
208 <section id='getting-ready-to-develop-using-devtool'> 208 <section id='getting-ready-to-develop-using-devtool'>
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml
index 55cacb7941..e7eb70d91b 100644
--- a/documentation/dev-manual/dev-manual.xml
+++ b/documentation/dev-manual/dev-manual.xml
@@ -152,8 +152,6 @@
152 152
153 <xi:include href="dev-manual-newbie.xml"/> 153 <xi:include href="dev-manual-newbie.xml"/>
154 154
155 <xi:include href="dev-manual-model.xml"/>
156
157 <xi:include href="dev-manual-common-tasks.xml"/> 155 <xi:include href="dev-manual-common-tasks.xml"/>
158 156
159 <xi:include href="dev-manual-qemu.xml"/> 157 <xi:include href="dev-manual-qemu.xml"/>
diff --git a/documentation/dev-manual/figures/devtool-add-flow.png b/documentation/dev-manual/figures/devtool-add-flow.png
deleted file mode 100644
index 985ac331f1..0000000000
--- a/documentation/dev-manual/figures/devtool-add-flow.png
+++ /dev/null
Binary files differ
diff --git a/documentation/dev-manual/figures/devtool-modify-flow.png b/documentation/dev-manual/figures/devtool-modify-flow.png
deleted file mode 100644
index fd684ffbe9..0000000000
--- a/documentation/dev-manual/figures/devtool-modify-flow.png
+++ /dev/null
Binary files differ
diff --git a/documentation/dev-manual/figures/devtool-upgrade-flow.png b/documentation/dev-manual/figures/devtool-upgrade-flow.png
deleted file mode 100644
index 65474dad02..0000000000
--- a/documentation/dev-manual/figures/devtool-upgrade-flow.png
+++ /dev/null
Binary files differ
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
index e62fb67ed1..bb03c60a2c 100644
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -237,7 +237,7 @@
237 <title>Other Resources</title> 237 <title>Other Resources</title>
238 238
239 <para> 239 <para>
240 The sections that follow provide instructions for completing 240 The remainder of this manual provides instructions for completing
241 specific Linux kernel development tasks. 241 specific Linux kernel development tasks.
242 These instructions assume you are comfortable working with 242 These instructions assume you are comfortable working with
243 <ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink> 243 <ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink>
@@ -251,9 +251,9 @@
251 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink> 251 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
252 </para></listitem> 252 </para></listitem>
253 <listitem><para> 253 <listitem><para>
254 The 254 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink>
255 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-modifying-source-code'>Modifying Source Code</ulink>" 255 as described in the Yocto Project Software Development Kit
256 section in the Yocto Project Development Manual 256 (SDK) Developer's Guide.
257 </para></listitem> 257 </para></listitem>
258 <listitem><para> 258 <listitem><para>
259 The 259 The
diff --git a/documentation/mega-manual/figures/devtool-add-flow.png b/documentation/mega-manual/figures/devtool-add-flow.png
deleted file mode 100644
index c09e60e355..0000000000
--- a/documentation/mega-manual/figures/devtool-add-flow.png
+++ /dev/null
Binary files differ
diff --git a/documentation/mega-manual/figures/devtool-modify-flow.png b/documentation/mega-manual/figures/devtool-modify-flow.png
deleted file mode 100644
index cd7f4d05b1..0000000000
--- a/documentation/mega-manual/figures/devtool-modify-flow.png
+++ /dev/null
Binary files differ
diff --git a/documentation/mega-manual/figures/devtool-upgrade-flow.png b/documentation/mega-manual/figures/devtool-upgrade-flow.png
deleted file mode 100644
index d25168c840..0000000000
--- a/documentation/mega-manual/figures/devtool-upgrade-flow.png
+++ /dev/null
Binary files differ
diff --git a/documentation/mega-manual/mega-manual.xml b/documentation/mega-manual/mega-manual.xml
index a6fdce5e6c..d7d66143a7 100644
--- a/documentation/mega-manual/mega-manual.xml
+++ b/documentation/mega-manual/mega-manual.xml
@@ -131,8 +131,6 @@
131 <xi:include 131 <xi:include
132 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-newbie.xml"/> 132 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-newbie.xml"/>
133 <xi:include 133 <xi:include
134 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-model.xml"/>
135 <xi:include
136 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-common-tasks.xml"/> 134 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-common-tasks.xml"/>
137 <xi:include 135 <xi:include
138 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-qemu.xml"/> 136 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-qemu.xml"/>
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index 415cf679ee..2fd1a7ef6f 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -235,6 +235,13 @@
235 you build, test and package software within the extensible SDK, and 235 you build, test and package software within the extensible SDK, and
236 optionally integrate it into an image built by the OpenEmbedded 236 optionally integrate it into an image built by the OpenEmbedded
237 build system. 237 build system.
238 <note><title>Tip</title>
239 The use of <filename>devtool</filename> is not limited to
240 the extensible SDK.
241 You can use <filename>devtool</filename> to help you easily
242 develop any project whose build output must be part of an
243 image built using the OpenEmbedded build system.
244 </note>
238 </para> 245 </para>
239 246
240 <para> 247 <para>
@@ -244,6 +251,12 @@
244 number of sub-commands for each function. 251 number of sub-commands for each function.
245 You can run <filename>devtool --help</filename> to see all the 252 You can run <filename>devtool --help</filename> to see all the
246 commands. 253 commands.
254 <note>
255 See the
256 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
257 in the Yocto Project Reference Manual for a
258 <filename>devtool</filename> quick reference.
259 </note>
247 </para> 260 </para>
248 261
249 <para> 262 <para>
@@ -1262,7 +1275,7 @@
1262 <title>Working With Recipes</title> 1275 <title>Working With Recipes</title>
1263 1276
1264 <para> 1277 <para>
1265 When building a recipe with <filename>devtool build</filename> the 1278 When building a recipe with <filename>devtool build</filename>, the
1266 typical build progression is as follows: 1279 typical build progression is as follows:
1267 <orderedlist> 1280 <orderedlist>
1268 <listitem><para> 1281 <listitem><para>
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index 78881d4185..409d537645 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -945,9 +945,7 @@
945 is a great place to get a feel for how to use the Yocto 945 is a great place to get a feel for how to use the Yocto
946 Project. 946 Project.
947 The manual contains conceptual and procedural information 947 The manual contains conceptual and procedural information
948 that covers 948 that introduces
949 <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-model'>common development models</ulink>
950 and introduces
951 <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-newbie'>the Yocto Project open source development environment</ulink>. 949 <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-newbie'>the Yocto Project open source development environment</ulink>.
952 The manual also contains several targeted sections that 950 The manual also contains several targeted sections that
953 cover specific 951 cover specific
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-02 03:55:07 +0000