diff options
| author | Scott Rifenbark <srifenbark@gmail.com> | 2017-07-03 15:27:58 -0700 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2017-07-12 00:28:15 +0100 |
| commit | 293b53674c1c97a29a8beaffc82130e90c0d3c2b (patch) | |
| tree | ceb465c56599a684e7041803100a94f4646dab92 /documentation/dev-manual | |
| parent | b15a65b8ea60032cf113196420a16183d0a0585a (diff) | |
| download | poky-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/dev-manual')
| -rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 17 | ||||
| -rw-r--r-- | documentation/dev-manual/dev-manual-model.xml | 721 | ||||
| -rw-r--r-- | documentation/dev-manual/dev-manual-start.xml | 8 | ||||
| -rw-r--r-- | documentation/dev-manual/dev-manual.xml | 2 | ||||
| -rw-r--r-- | documentation/dev-manual/figures/devtool-add-flow.png | bin | 177945 -> 0 bytes | |||
| -rw-r--r-- | documentation/dev-manual/figures/devtool-modify-flow.png | bin | 164192 -> 0 bytes | |||
| -rw-r--r-- | documentation/dev-manual/figures/devtool-upgrade-flow.png | bin | 139827 -> 0 bytes |
7 files changed, 14 insertions, 734 deletions
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> 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 | |||
