diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-extensible.xml')
| -rw-r--r-- | documentation/sdk-manual/sdk-extensible.xml | 566 |
1 files changed, 517 insertions, 49 deletions
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml index c238dee382..bc9ccd28d3 100644 --- a/documentation/sdk-manual/sdk-extensible.xml +++ b/documentation/sdk-manual/sdk-extensible.xml | |||
| @@ -6,69 +6,537 @@ | |||
| 6 | 6 | ||
| 7 | <title>Using the Extensible SDK</title> | 7 | <title>Using the Extensible SDK</title> |
| 8 | 8 | ||
| 9 | <para role='writernotes'> | 9 | <para> |
| 10 | This chapter describes what you need on your machine in order to use | 10 | This chapter describes the extensible SDK and how to use it. |
| 11 | an extensible SDK. | 11 | The extensible SDK makes it easy to add new applications and libraries |
| 12 | The chapter does not repeat information that also applies to using the | 12 | to an image, modify the source for an existing component, test |
| 13 | standard SDK. | 13 | changes on the target hardware, and ease integration into the rest |
| 14 | The chapter also includes procedures of tasks you can perform using | 14 | of the build system. |
| 15 | an extensible SDK. | ||
| 16 | <note> | ||
| 17 | The tasks you can perform using a standard SDK are also available | ||
| 18 | using an extensible SDK. | ||
| 19 | For information on using the standard SDK, see the | ||
| 20 | "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>" | ||
| 21 | chapter. | ||
| 22 | </note> | ||
| 23 | </para> | 15 | </para> |
| 24 | 16 | ||
| 17 | <para> | ||
| 18 | Information in this chapter covers features that are not part of the | ||
| 19 | standard SDK. | ||
| 20 | In other words, the chapter presents information unique to the | ||
| 21 | extensible SDK only. | ||
| 22 | For information on how to use the standard SDK, see the | ||
| 23 | "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>" | ||
| 24 | chapter. | ||
| 25 | </para> | ||
| 25 | 26 | ||
| 26 | <section id='sdk-setting-up-to-use-the-extensible-sdk'> | 27 | <section id='sdk-setting-up-to-use-the-extensible-sdk'> |
| 27 | <title>Setting Up to Use the Extensible SDK</title> | 28 | <title>Setting Up to Use the Extensible SDK</title> |
| 28 | 29 | ||
| 29 | <para role='writernotes'> | 30 | <para> |
| 30 | Here is a list of items I think need addressed in this section: | 31 | Getting set up to use the extensible SDK is identical to getting set |
| 32 | up to use the standard SDK. | ||
| 33 | You still need to locate and run the installer and then run the | ||
| 34 | environment setup script. | ||
| 35 | See the | ||
| 36 | "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" | ||
| 37 | and the | ||
| 38 | "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>" | ||
| 39 | sections for general information. | ||
| 40 | The following items highlight the only differences between getting | ||
| 41 | set up to use the extensible SDK as compared to the standard SDK: | ||
| 31 | <itemizedlist> | 42 | <itemizedlist> |
| 32 | <listitem><para role='writernotes'><emphasis>Cover differences in the development | 43 | <listitem><para><emphasis>Default Installation Directory:</emphasis> |
| 33 | that might be impacted because they are using an extensible | 44 | By default, the extensible SDK installs into the |
| 34 | SDK</emphasis></para> | 45 | <filename>poky_sdk</filename> folder of your home directory. |
| 35 | <para role='writernotes'>Presumably, the various development scenarios are | 46 | As with the standard SDK, you can choose to install the |
| 36 | covered regarding setup in the previous chapter. | 47 | extensible SDK in any location when you run the installer. |
| 37 | Are these impacted because the developer is going to now be | ||
| 38 | using an extensible SDK? | ||
| 39 | If so, what are the implications? | ||
| 40 | </para></listitem> | 48 | </para></listitem> |
| 41 | <listitem><para role='writernotes'><emphasis>What new recommendations exist now that | 49 | <listitem><para><emphasis>Build Tools and Build System:</emphasis> |
| 42 | the developer is going to be using an extensible SDK?</emphasis></para> | 50 | The extensible SDK installer performs additional tasks as |
| 43 | <para role='writernotes'>We should cover the most common development scenarios | 51 | compared to the standard SDK installer. |
| 44 | that apply when using an extensible SDK. | 52 | The extensible SDK installer extracts build tools specific |
| 45 | Is there a recommended development flow we want to present | 53 | to the SDK and the installer also prepares the build system. |
| 46 | when using an extensible SDK? | 54 | Here is example output for running the extensible SDK |
| 47 | What conditions in a development scenario warrant use of | 55 | installer: |
| 48 | the extensible SDK as compared to the standard SDK? | 56 | <literallayout class='monospaced'> |
| 49 | </para></listitem> | 57 | $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.1+snapshot.sh |
| 50 | <listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set | 58 | Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.1+snapshot |
| 51 | up the extensible SDK?</emphasis></para> | 59 | =================================================================================== |
| 52 | <para role='writernotes'>Is it just a matter of building out the SDK using | 60 | Enter target directory for SDK (default: ~/poky_sdk): |
| 53 | <filename>bitbake -c populate_sdk_ext</filename>? | 61 | You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y |
| 54 | Is there a pre-built extensible SDK laying around they can | 62 | Extracting SDK......................................................................done |
| 55 | find and download if they are using a machine that does not | 63 | Setting it up... |
| 56 | have YP installed, which would prevent them from building their | 64 | Extracting buildtools... |
| 57 | own SDK? | 65 | Preparing build system... |
| 66 | done | ||
| 67 | SDK has been successfully set up and is ready to be used. | ||
| 68 | Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. | ||
| 69 | $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux | ||
| 70 | </literallayout> | ||
| 58 | </para></listitem> | 71 | </para></listitem> |
| 59 | </itemizedlist> | 72 | </itemizedlist> |
| 60 | </para> | 73 | </para> |
| 74 | |||
| 75 | <para> | ||
| 76 | After installing the SDK, you need to run the SDK environment setup | ||
| 77 | script. | ||
| 78 | Here is the output: | ||
| 79 | <literallayout class='monospaced'> | ||
| 80 | $ source environment-setup-core2-64-poky-linux | ||
| 81 | SDK environment now set up; additionally you may now run devtool to perform development tasks. | ||
| 82 | Run devtool --help for further details. | ||
| 83 | </literallayout> | ||
| 84 | Once you run the environment setup script, you have | ||
| 85 | <filename>devtool</filename> available. | ||
| 86 | </para> | ||
| 61 | </section> | 87 | </section> |
| 62 | 88 | ||
| 63 | <section id='sdk-using-the-extensible-sdk-to-task-1'> | 89 | <section id='sdk-use-devtool-to-add-an-application'> |
| 64 | <title>Using the Extensible SDK to <replaceable>item 1</replaceable></title> | 90 | <title>Use <filename>devtool add</filename> to Add an Application</title> |
| 65 | 91 | ||
| 66 | <para role='writernotes'> | 92 | <para> |
| 67 | Describe the specific task you are going to accomplish with the | 93 | The <filename>devtool add</filename> command generates |
| 68 | extensible SDK. | 94 | a new recipe based on existing source code. |
| 69 | Provide a diagram showing the rough flow of the task. | 95 | This command takes advantage of the |
| 70 | Provide specific steps using a real example that works through the | 96 | <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink> |
| 71 | task. | 97 | layer that many <filename>devtool</filename> commands |
| 98 | use. | ||
| 99 | The command is flexible enough to allow you to extract source | ||
| 100 | code into both the workspace or a separate local Git repository | ||
| 101 | and to use existing code that does not need to be extracted. | ||
| 102 | </para> | ||
| 103 | |||
| 104 | <para> | ||
| 105 | Depending on your particular scenario, the arguments and options | ||
| 106 | you use with <filename>devtool add</filename> form different | ||
| 107 | combinations. | ||
| 108 | The following diagram shows common development flows | ||
| 109 | you would use with the <filename>devtool add</filename> | ||
| 110 | command: | ||
| 111 | </para> | ||
| 112 | |||
| 113 | <para> | ||
| 114 | <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" /> | ||
| 115 | </para> | ||
| 116 | |||
| 117 | <para> | ||
| 118 | <orderedlist> | ||
| 119 | <listitem><para><emphasis>Generating the New Recipe</emphasis>: | ||
| 120 | The top part of the flow shows three scenarios by which | ||
| 121 | you could use <filename>devtool add</filename> to | ||
| 122 | generate a recipe based on existing source code.</para> | ||
| 123 | |||
| 124 | <para>In a shared development environment, it is | ||
| 125 | typical where other developers are responsible for | ||
| 126 | various areas of source code. | ||
| 127 | As a developer, you are probably interested in using | ||
| 128 | that source code as part of your development using | ||
| 129 | the Yocto Project. | ||
| 130 | All you need is access to the code, a recipe, and a | ||
| 131 | controlled area in which to do your work.</para> | ||
| 132 | |||
| 133 | <para>Within the diagram, three possible scenarios | ||
| 134 | feed into the <filename>devtool add</filename> workflow: | ||
| 135 | <itemizedlist> | ||
| 136 | <listitem><para><emphasis>Left</emphasis>: | ||
| 137 | The left scenario represents a common situation | ||
| 138 | where the source code does not exist locally | ||
| 139 | and needs to be extracted. | ||
| 140 | In this situation, you just let it get | ||
| 141 | extracted to the default workspace - you do not | ||
| 142 | want it in some specific location outside of the | ||
| 143 | workspace. | ||
| 144 | Thus, everything you need will be located in the | ||
| 145 | workspace: | ||
| 146 | <literallayout class='monospaced'> | ||
| 147 | $ devtool add <replaceable>recipe fetchuri</replaceable> | ||
| 148 | </literallayout> | ||
| 149 | With this command, <filename>devtool</filename> | ||
| 150 | creates a recipe and an append file in the | ||
| 151 | workspace as well as extracts the upstream | ||
| 152 | source files into a local Git repository also | ||
| 153 | within the <filename>sources</filename> folder. | ||
| 154 | </para></listitem> | ||
| 155 | <listitem><para><emphasis>Middle</emphasis>: | ||
| 156 | The middle scenario also represents a situation where | ||
| 157 | the source code does not exist locally. | ||
| 158 | In this case, the code is again upstream | ||
| 159 | and needs to be extracted to some | ||
| 160 | local area - this time outside of the default | ||
| 161 | workspace. | ||
| 162 | As always, if required <filename>devtool</filename> creates | ||
| 163 | a Git repository locally during the extraction. | ||
| 164 | Furthermore, the first positional argument | ||
| 165 | <replaceable>srctree</replaceable> in this case | ||
| 166 | identifies where the | ||
| 167 | <filename>devtool add</filename> command | ||
| 168 | will locate the extracted code outside of the | ||
| 169 | workspace: | ||
| 170 | <literallayout class='monospaced'> | ||
| 171 | $ devtool add <replaceable>recipe srctree fetchuri</replaceable> | ||
| 172 | </literallayout> | ||
| 173 | In summary, the source code is pulled from | ||
| 174 | <replaceable>fetchuri</replaceable> and extracted | ||
| 175 | into the location defined by | ||
| 176 | <replaceable>srctree</replaceable> as a local | ||
| 177 | Git repository.</para> | ||
| 178 | |||
| 179 | <para>Within workspace, <filename>devtool</filename> | ||
| 180 | creates both the recipe and an append file | ||
| 181 | for the recipe. | ||
| 182 | </para></listitem> | ||
| 183 | <listitem><para><emphasis>Right</emphasis>: | ||
| 184 | The right scenario represents a situation | ||
| 185 | where the source tree (srctree) has been | ||
| 186 | previously prepared outside of the | ||
| 187 | <filename>devtool</filename> workspace. | ||
| 188 | </para> | ||
| 189 | |||
| 190 | <para>The following command names the recipe | ||
| 191 | and identifies where the existing source tree | ||
| 192 | is located: | ||
| 193 | <literallayout class='monospaced'> | ||
| 194 | $ devtool add <replaceable>recipe srctree</replaceable> | ||
| 195 | </literallayout> | ||
| 196 | The command examines the source code and creates | ||
| 197 | a recipe for it placing the recipe into the | ||
| 198 | workspace.</para> | ||
| 199 | |||
| 200 | <para>Because the extracted source code already exists, | ||
| 201 | <filename>devtool</filename> does not try to | ||
| 202 | relocate it into the workspace - just the new | ||
| 203 | the recipe is placed in the workspace.</para> | ||
| 204 | |||
| 205 | <para>Aside from a recipe folder, the command | ||
| 206 | also creates an append folder and places an initial | ||
| 207 | <filename>*.bbappend</filename> within. | ||
| 208 | </para></listitem> | ||
| 209 | </itemizedlist> | ||
| 210 | </para></listitem> | ||
| 211 | <listitem><para><emphasis>Edit the Recipe</emphasis>: | ||
| 212 | At this point, you can use <filename>devtool edit-recipe</filename> | ||
| 213 | to open up the editor as defined by the | ||
| 214 | <filename>$EDITOR</filename> environment variable | ||
| 215 | and modify the file: | ||
| 216 | <literallayout class='monospaced'> | ||
| 217 | $ devtool edit-recipe <replaceable>recipe</replaceable> | ||
| 218 | </literallayout> | ||
| 219 | From within the editor, you can make modifications to the | ||
| 220 | recipe that take affect when you build it later. | ||
| 221 | </para></listitem> | ||
| 222 | <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>: | ||
| 223 | At this point in the flow, the next step you | ||
| 224 | take depends on what you are going to do with | ||
| 225 | the new code.</para> | ||
| 226 | <para>If you need to take the build output and eventually | ||
| 227 | move it to the target hardware, you would use | ||
| 228 | <filename>devtool build</filename>: | ||
| 229 | <note> | ||
| 230 | You could use <filename>bitbake</filename> to build | ||
| 231 | the recipe as well. | ||
| 232 | </note> | ||
| 233 | <literallayout class='monospaced'> | ||
| 234 | $ devtool build <replaceable>recipe</replaceable> | ||
| 235 | </literallayout></para> | ||
| 236 | <para>On the other hand, if you want an image to | ||
| 237 | contain the recipe's packages for immediate deployment | ||
| 238 | onto a device (e.g. for testing purposes), you can use | ||
| 239 | the <filename>devtool build-image</filename> command: | ||
| 240 | <literallayout class='monospaced'> | ||
| 241 | $ devtool build-image <replaceable>image</replaceable> | ||
| 242 | </literallayout> | ||
| 243 | </para></listitem> | ||
| 244 | <listitem><para><emphasis>Deploy the Build Output</emphasis>: | ||
| 245 | When you use the <filename>devtool build</filename> | ||
| 246 | command to build out your recipe, you probably want to | ||
| 247 | see if the resulting build output works as expected on target | ||
| 248 | hardware. | ||
| 249 | <note> | ||
| 250 | This step assumes you have a previously built | ||
| 251 | image that is already either running in QEMU or | ||
| 252 | running on actual hardware. | ||
| 253 | Also, it is assumed that for deployment of the image | ||
| 254 | to the target, SSH is installed in the image and if | ||
| 255 | the image is running on real hardware that you have | ||
| 256 | network access to and from your development machine. | ||
| 257 | </note> | ||
| 258 | You can deploy your build output to that target hardware by | ||
| 259 | using the <filename>devtool deploy-target</filename> command: | ||
| 260 | <literallayout class='monospaced'> | ||
| 261 | $ devtool deploy-target <replaceable>recipe target</replaceable> | ||
| 262 | </literallayout> | ||
| 263 | The <replaceable>target</replaceable> is a live target machine | ||
| 264 | running as an SSH server.</para> | ||
| 265 | |||
| 266 | <para>You can, of course, also deploy the image you build | ||
| 267 | using the <filename>devtool build-image</filename> command | ||
| 268 | to actual hardware. | ||
| 269 | However, <filename>devtool</filename> does not provide a | ||
| 270 | specific command that allows you to do this. | ||
| 271 | </para></listitem> | ||
| 272 | <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>: | ||
| 273 | Once you are satisfied with the recipe, if you have made | ||
| 274 | any changes to the source tree that you want to have | ||
| 275 | applied by the recipe, you need to generate patches | ||
| 276 | from those changes. | ||
| 277 | You do this before moving the recipe | ||
| 278 | to its final layer and cleaning up the workspace area | ||
| 279 | <filename>devtool</filename> uses. | ||
| 280 | This optional step is especially relevant if you are | ||
| 281 | using or adding third-party software.</para> | ||
| 282 | <para>To convert commits created using Git to patch files, | ||
| 283 | use the <filename>devtool update-recipe</filename> command. | ||
| 284 | <note> | ||
| 285 | Any changes you want to turn into patches must be | ||
| 286 | committed to the Git repository in the source tree. | ||
| 287 | </note> | ||
| 288 | <literallayout class='monospaced'> | ||
| 289 | $ devtool update-recipe <replaceable>recipe</replaceable> | ||
| 290 | </literallayout> | ||
| 291 | </para></listitem> | ||
| 292 | <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>: | ||
| 293 | Before cleaning up the workspace, you need to move the | ||
| 294 | final recipe to its permanent layer. | ||
| 295 | You must do this before using the | ||
| 296 | <filename>devtool reset</filename> command if you want to | ||
| 297 | retain the recipe. | ||
| 298 | </para></listitem> | ||
| 299 | <listitem><para><emphasis>Reset the Recipe</emphasis>: | ||
| 300 | As a final step, you can restore the state such that | ||
| 301 | standard layers and the upstream source is used to build | ||
| 302 | the recipe rather than data in the workspace. | ||
| 303 | To reset the recipe, use the <filename>devtool reset</filename> | ||
| 304 | command: | ||
| 305 | <literallayout class='monospaced'> | ||
| 306 | $ devtool reset <replaceable>recipe</replaceable> | ||
| 307 | </literallayout> | ||
| 308 | </para></listitem> | ||
| 309 | </orderedlist> | ||
| 310 | </para> | ||
| 311 | </section> | ||
| 312 | |||
| 313 | <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'> | ||
| 314 | <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title> | ||
| 315 | |||
| 316 | <para> | ||
| 317 | The <filename>devtool modify</filename> command prepares the | ||
| 318 | way to work on existing code that already has a recipe in | ||
| 319 | place. | ||
| 320 | The command is flexible enough to allow you to extract code, | ||
| 321 | specify the existing recipe, and keep track of and gather any | ||
| 322 | patch files from other developers that are | ||
| 323 | associated with the code. | ||
| 324 | </para> | ||
| 325 | |||
| 326 | <para> | ||
| 327 | Depending on your particular scenario, the arguments and options | ||
| 328 | you use with <filename>devtool modify</filename> form different | ||
| 329 | combinations. | ||
| 330 | The following diagram shows common development flows | ||
| 331 | you would use with the <filename>devtool modify</filename> | ||
| 332 | command: | ||
| 333 | </para> | ||
| 334 | |||
| 335 | <para> | ||
| 336 | <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" /> | ||
| 337 | </para> | ||
| 338 | |||
| 339 | <para> | ||
| 340 | <orderedlist> | ||
| 341 | <listitem><para><emphasis>Preparing to Modify the Code</emphasis>: | ||
| 342 | The top part of the flow shows three scenarios by which | ||
| 343 | you could use <filename>devtool modify</filename> to | ||
| 344 | prepare to work on source files. | ||
| 345 | Each scenario assumes the following: | ||
| 346 | <itemizedlist> | ||
| 347 | <listitem><para>The recipe exists in some layer external | ||
| 348 | to the <filename>devtool</filename> workspace. | ||
| 349 | </para></listitem> | ||
| 350 | <listitem><para>The source files exist upstream in an | ||
| 351 | un-extracted state or locally in a previously | ||
| 352 | extracted state. | ||
| 353 | </para></listitem> | ||
| 354 | </itemizedlist> | ||
| 355 | The typical situation is where another developer has | ||
| 356 | created some layer for use with the Yocto Project and | ||
| 357 | their recipe already resides in that layer. | ||
| 358 | Furthermore, their source code is readily available | ||
| 359 | either upstream or locally. | ||
| 360 | <itemizedlist> | ||
| 361 | <listitem><para><emphasis>Left</emphasis>: | ||
| 362 | The left scenario represents a common situation | ||
| 363 | where the source code does not exist locally | ||
| 364 | and needs to be extracted. | ||
| 365 | In this situation, the source is extracted | ||
| 366 | into the default workspace location. | ||
| 367 | The recipe, in this scenario, is in its own | ||
| 368 | layer outside the workspace | ||
| 369 | (i.e. | ||
| 370 | <filename>meta-</filename><replaceable>layername</replaceable>). | ||
| 371 | </para> | ||
| 372 | |||
| 373 | <para>The following command identifies the recipe | ||
| 374 | and by default extracts the source files: | ||
| 375 | <literallayout class='monospaced'> | ||
| 376 | $ devtool modify <replaceable>recipe</replaceable> | ||
| 377 | </literallayout> | ||
| 378 | Once <filename>devtool</filename>locates the recipe, | ||
| 379 | it uses the | ||
| 380 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
| 381 | variable to locate the source code and | ||
| 382 | any local patch files from other developers are | ||
| 383 | located. | ||
| 384 | <note> | ||
| 385 | You cannot provide an URL for | ||
| 386 | <replaceable>srctree</replaceable> when using the | ||
| 387 | <filename>devtool modify</filename> command. | ||
| 388 | </note> | ||
| 389 | With this scenario, however, since no | ||
| 390 | <replaceable>srctree</replaceable> argument exists, the | ||
| 391 | <filename>devtool modify</filename> command by default | ||
| 392 | extracts the source files to a Git structure. | ||
| 393 | Furthermore, the location for the extracted source is the | ||
| 394 | default area within the workspace. | ||
| 395 | The result is that the command sets up both the source | ||
| 396 | code and an append file within the workspace with the | ||
| 397 | recipe remaining in its original location. | ||
| 398 | </para></listitem> | ||
| 399 | <listitem><para><emphasis>Middle</emphasis>: | ||
| 400 | The middle scenario represents a situation where | ||
| 401 | the source code also does not exist locally. | ||
| 402 | In this case, the code is again upstream | ||
| 403 | and needs to be extracted to some | ||
| 404 | local area as a Git repository. | ||
| 405 | The recipe, in this scenario, is again in its own | ||
| 406 | layer outside the workspace.</para> | ||
| 407 | |||
| 408 | <para>The following command tells | ||
| 409 | <filename>devtool</filename> what recipe with | ||
| 410 | which to work and, in this case, identifies a local | ||
| 411 | area for the extracted source files that is outside | ||
| 412 | of the default workspace: | ||
| 413 | <literallayout class='monospaced'> | ||
| 414 | $ devtool modify <replaceable>recipe srctree</replaceable> | ||
| 415 | </literallayout> | ||
| 416 | As with all extractions, the command uses | ||
| 417 | the recipe's <filename>SRC_URI</filename> to locate the | ||
| 418 | source files. | ||
| 419 | Once the files are located, the command by default | ||
| 420 | extracts them. | ||
| 421 | Providing the <replaceable>srctree</replaceable> | ||
| 422 | argument instructs <filename>devtool</filename> where | ||
| 423 | place the extracted source.</para> | ||
| 424 | |||
| 425 | <para>Within workspace, <filename>devtool</filename> | ||
| 426 | creates an append file for the recipe. | ||
| 427 | The recipe remains in its original location but | ||
| 428 | the source files are extracted to the location you | ||
| 429 | provided with <replaceable>srctree</replaceable>. | ||
| 430 | </para></listitem> | ||
| 431 | <listitem><para><emphasis>Right</emphasis>: | ||
| 432 | The right scenario represents a situation | ||
| 433 | where the source tree | ||
| 434 | (<replaceable>srctree</replaceable>) exists as a | ||
| 435 | previously extracted Git structure outside of | ||
| 436 | the <filename>devtool</filename> workspace. | ||
| 437 | In this example, the recipe also exists | ||
| 438 | elsewhere in its own layer. | ||
| 439 | </para> | ||
| 440 | |||
| 441 | <para>The following command tells | ||
| 442 | <filename>devtool</filename> the recipe | ||
| 443 | with which to work, uses the "-n" option to indicate | ||
| 444 | source does not need to be extracted, and uses | ||
| 445 | <replaceable>srctree</replaceable> to point to the | ||
| 446 | previously extracted source files: | ||
| 447 | <literallayout class='monospaced'> | ||
| 448 | $ devtool modify -n <replaceable>recipe srctree</replaceable> | ||
| 449 | </literallayout> | ||
| 450 | </para> | ||
| 451 | |||
| 452 | <para>Once the command finishes, it creates only | ||
| 453 | an append file for the recipe in the workspace. | ||
| 454 | The recipe and the source code remain in their | ||
| 455 | original locations. | ||
| 456 | </para></listitem> | ||
| 457 | </itemizedlist> | ||
| 458 | </para></listitem> | ||
| 459 | <listitem><para><emphasis>Edit the Source</emphasis>: | ||
| 460 | Once you have used the <filename>devtool modify</filename> | ||
| 461 | command, you are free to make changes to the source | ||
| 462 | files. | ||
| 463 | You can use any editor you like to make and save | ||
| 464 | your source code modifications. | ||
| 465 | </para></listitem> | ||
| 466 | <listitem><para><emphasis>Build the Recipe</emphasis>: | ||
| 467 | Once you have updated the source files, you can build | ||
| 468 | the recipe. | ||
| 469 | You can either use <filename>devtool build</filename> or | ||
| 470 | <filename>bitbake</filename>. | ||
| 471 | Either method produces build output that is stored | ||
| 472 | in | ||
| 473 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. | ||
| 474 | </para></listitem> | ||
| 475 | <listitem><para><emphasis>Deploy the Build Output</emphasis>: | ||
| 476 | When you use the <filename>devtool build</filename> | ||
| 477 | command or <filename>bitbake</filename> to build out your | ||
| 478 | recipe, you probably want to see if the resulting build | ||
| 479 | output works as expected on target hardware. | ||
| 480 | <note> | ||
| 481 | This step assumes you have a previously built | ||
| 482 | image that is already either running in QEMU or | ||
| 483 | running on actual hardware. | ||
| 484 | Also, it is assumed that for deployment of the image | ||
| 485 | to the target, SSH is installed in the image and if | ||
| 486 | the image is running on real hardware that you have | ||
| 487 | network access to and from your development machine. | ||
| 488 | </note> | ||
| 489 | You can deploy your build output to that target hardware by | ||
| 490 | using the <filename>devtool deploy-target</filename> command: | ||
| 491 | <literallayout class='monospaced'> | ||
| 492 | $ devtool deploy-target <replaceable>recipe target</replaceable> | ||
| 493 | </literallayout> | ||
| 494 | The <replaceable>target</replaceable> is a live target machine | ||
| 495 | running as an SSH server.</para> | ||
| 496 | |||
| 497 | <para>You can, of course, also deploy the image you build | ||
| 498 | using the <filename>devtool build-image</filename> command | ||
| 499 | to actual hardware. | ||
| 500 | However, <filename>devtool</filename> does not provide a | ||
| 501 | specific command that allows you to do this. | ||
| 502 | </para></listitem> | ||
| 503 | <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>: | ||
| 504 | After you have debugged your changes, you can | ||
| 505 | use <filename>devtool update-recipe</filename> to | ||
| 506 | generate patch files for all the commits you have | ||
| 507 | made. | ||
| 508 | <note> | ||
| 509 | Patch files are generated only for changes | ||
| 510 | you have committed. | ||
| 511 | </note> | ||
| 512 | <literallayout class='monospaced'> | ||
| 513 | $ devtool update-recipe <replaceable>recipe</replaceable> | ||
| 514 | </literallayout> | ||
| 515 | By default, the | ||
| 516 | <filename>devtool update-recipe</filename> command | ||
| 517 | creates the patch files in a folder named the same | ||
| 518 | as the recipe beneath the folder in which the recipe | ||
| 519 | resides, and updates the recipe's | ||
| 520 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
| 521 | statement to point to the generated patch files. | ||
| 522 | <note> | ||
| 523 | You can use the | ||
| 524 | "--append <replaceable>LAYERDIR</replaceable>" | ||
| 525 | option to cause the command to create append files | ||
| 526 | in a specific layer rather than the default | ||
| 527 | recipe layer. | ||
| 528 | </note> | ||
| 529 | </para></listitem> | ||
| 530 | <listitem><para><emphasis>Restore the Workspace</emphasis>: | ||
| 531 | The <filename>devtool reset</filename> restores the | ||
| 532 | state so that standard layers and upstream sources are | ||
| 533 | used to build the recipe rather than what is in the | ||
| 534 | workspace. | ||
| 535 | <literallayout class='monospaced'> | ||
| 536 | $ devtool reset <replaceable>recipe</replaceable> | ||
| 537 | </literallayout> | ||
| 538 | </para></listitem> | ||
| 539 | </orderedlist> | ||
| 72 | </para> | 540 | </para> |
| 73 | </section> | 541 | </section> |
| 74 | 542 | ||