diff options
| author | Richard Purdie <richard.purdie@linuxfoundation.org> | 2025-11-07 13:31:53 +0000 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2025-11-07 13:31:53 +0000 |
| commit | 8c22ff0d8b70d9b12f0487ef696a7e915b9e3173 (patch) | |
| tree | efdc32587159d0050a69009bdf2330a531727d95 /documentation/dev-manual/devtool.rst | |
| parent | d412d2747595c1cc4a5e3ca975e3adc31b2f7891 (diff) | |
| download | poky-8c22ff0d8b70d9b12f0487ef696a7e915b9e3173.tar.gz | |
The poky repository master branch is no longer being updated.
You can either:
a) switch to individual clones of bitbake, openembedded-core, meta-yocto and yocto-docs
b) use the new bitbake-setup
You can find information about either approach in our documentation:
https://docs.yoctoproject.org/
Note that "poky" the distro setting is still available in meta-yocto as
before and we continue to use and maintain that.
Long live Poky!
Some further information on the background of this change can be found
in: https://lists.openembedded.org/g/openembedded-architecture/message/2179
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/devtool.rst')
| -rw-r--r-- | documentation/dev-manual/devtool.rst | 1322 |
1 files changed, 0 insertions, 1322 deletions
diff --git a/documentation/dev-manual/devtool.rst b/documentation/dev-manual/devtool.rst deleted file mode 100644 index c82dc9c333..0000000000 --- a/documentation/dev-manual/devtool.rst +++ /dev/null | |||
| @@ -1,1322 +0,0 @@ | |||
| 1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
| 2 | |||
| 3 | Using the ``devtool`` command-line tool | ||
| 4 | *************************************** | ||
| 5 | |||
| 6 | The ``devtool`` command-line tool provides a number of features that | ||
| 7 | help you build, test, and package software. This command is available | ||
| 8 | alongside the ``bitbake`` command. Additionally, the ``devtool`` command | ||
| 9 | is a key part of the :term:`Extensible Software Development Kit (eSDK)`. | ||
| 10 | |||
| 11 | Use ``devtool add`` to Add an Application | ||
| 12 | ========================================= | ||
| 13 | |||
| 14 | The ``devtool add`` command generates a new recipe based on existing | ||
| 15 | source code. This command takes advantage of the | ||
| 16 | :ref:`devtool-the-workspace-layer-structure` | ||
| 17 | layer that many ``devtool`` commands use. The command is flexible enough | ||
| 18 | to allow you to extract source code into both the workspace or a | ||
| 19 | separate local Git repository and to use existing code that does not | ||
| 20 | need to be extracted. | ||
| 21 | |||
| 22 | Depending on your particular scenario, the arguments and options you use | ||
| 23 | with ``devtool add`` form different combinations. The following diagram | ||
| 24 | shows common development flows you would use with the ``devtool add`` | ||
| 25 | command: | ||
| 26 | |||
| 27 | .. image:: figures/devtool-add-flow.png | ||
| 28 | :width: 100% | ||
| 29 | |||
| 30 | #. *Generating the New Recipe*: The top part of the flow shows three | ||
| 31 | scenarios by which you could use ``devtool add`` to generate a recipe | ||
| 32 | based on existing source code. | ||
| 33 | |||
| 34 | In a shared development environment, it is typical for other | ||
| 35 | developers to be responsible for various areas of source code. As a | ||
| 36 | developer, you are probably interested in using that source code as | ||
| 37 | part of your development within the Yocto Project. All you need is | ||
| 38 | access to the code, a recipe, and a controlled area in which to do | ||
| 39 | your work. | ||
| 40 | |||
| 41 | Within the diagram, three possible scenarios feed into the | ||
| 42 | ``devtool add`` workflow: | ||
| 43 | |||
| 44 | - *Left*: The left scenario in the figure represents a common | ||
| 45 | situation where the source code does not exist locally and needs | ||
| 46 | to be extracted. In this situation, the source code is extracted | ||
| 47 | to the default workspace --- you do not want the files in some | ||
| 48 | specific location outside of the workspace. Thus, everything you | ||
| 49 | need will be located in the workspace:: | ||
| 50 | |||
| 51 | $ devtool add recipe fetchuri | ||
| 52 | |||
| 53 | With this command, ``devtool`` extracts the upstream | ||
| 54 | source files into a local Git repository within the ``sources`` | ||
| 55 | folder. The command then creates a recipe named recipe and a | ||
| 56 | corresponding append file in the workspace. If you do not provide | ||
| 57 | recipe, the command makes an attempt to determine the recipe name. | ||
| 58 | |||
| 59 | - *Middle*: The middle scenario in the figure also represents a | ||
| 60 | situation where the source code does not exist locally. In this | ||
| 61 | case, the code is again upstream and needs to be extracted to some | ||
| 62 | local area --- this time outside of the default workspace. | ||
| 63 | |||
| 64 | .. note:: | ||
| 65 | |||
| 66 | If required, ``devtool`` always creates a Git repository locally | ||
| 67 | during the extraction. | ||
| 68 | |||
| 69 | Furthermore, the first positional argument ``srctree`` in this case | ||
| 70 | identifies where the ``devtool add`` command will locate the | ||
| 71 | extracted code outside of the workspace. You need to specify an | ||
| 72 | empty directory:: | ||
| 73 | |||
| 74 | $ devtool add recipe srctree fetchuri | ||
| 75 | |||
| 76 | In summary, the source code is pulled from fetchuri and extracted into the | ||
| 77 | location defined by ``srctree`` as a local Git repository. | ||
| 78 | |||
| 79 | Within workspace, ``devtool`` creates a recipe named recipe along | ||
| 80 | with an associated append file. | ||
| 81 | |||
| 82 | - *Right*: The right scenario in the figure represents a situation | ||
| 83 | where the ``srctree`` has been previously prepared outside of the | ||
| 84 | ``devtool`` workspace. | ||
| 85 | |||
| 86 | The following command provides a new recipe name and identifies | ||
| 87 | the existing source tree location:: | ||
| 88 | |||
| 89 | $ devtool add recipe srctree | ||
| 90 | |||
| 91 | The command examines the source code and creates a recipe named | ||
| 92 | recipe for the code and places the recipe into the workspace. | ||
| 93 | |||
| 94 | Because the extracted source code already exists, ``devtool`` does | ||
| 95 | not try to relocate the source code into the workspace --- only the | ||
| 96 | new recipe is placed in the workspace. | ||
| 97 | |||
| 98 | Aside from a recipe folder, the command also creates an associated | ||
| 99 | append folder and places an initial ``*.bbappend`` file within. | ||
| 100 | |||
| 101 | #. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the | ||
| 102 | editor as defined by the ``$EDITOR`` environment variable and modify | ||
| 103 | the file:: | ||
| 104 | |||
| 105 | $ devtool edit-recipe recipe | ||
| 106 | |||
| 107 | From within the editor, you can make modifications to the recipe that | ||
| 108 | take effect when you build it later. | ||
| 109 | |||
| 110 | #. *Build the Recipe or Rebuild the Image*: The next step you take | ||
| 111 | depends on what you are going to do with the new code. | ||
| 112 | |||
| 113 | If you need to eventually move the build output to the target | ||
| 114 | hardware, use the following ``devtool`` command:: | ||
| 115 | |||
| 116 | $ devtool build recipe | ||
| 117 | |||
| 118 | On the other hand, if you want an image to contain the recipe's | ||
| 119 | packages from the workspace for immediate deployment onto a device | ||
| 120 | (e.g. for testing purposes), you can use the ``devtool build-image`` | ||
| 121 | command:: | ||
| 122 | |||
| 123 | $ devtool build-image image | ||
| 124 | |||
| 125 | #. *Deploy the Build Output*: When you use the ``devtool build`` command | ||
| 126 | to build out your recipe, you probably want to see if the resulting | ||
| 127 | build output works as expected on the target hardware. | ||
| 128 | |||
| 129 | .. note:: | ||
| 130 | |||
| 131 | This step assumes you have a previously built image that is | ||
| 132 | already either running in QEMU or is running on actual hardware. | ||
| 133 | Also, it is assumed that for deployment of the image to the | ||
| 134 | target, SSH is installed in the image and, if the image is running | ||
| 135 | on real hardware, you have network access to and from your | ||
| 136 | development machine. | ||
| 137 | |||
| 138 | You can deploy your build output to that target hardware by using the | ||
| 139 | ``devtool deploy-target`` command:: | ||
| 140 | |||
| 141 | $ devtool deploy-target recipe target | ||
| 142 | |||
| 143 | The target is a live target machine running as an SSH server. | ||
| 144 | |||
| 145 | You can, of course, also deploy the image you build to actual | ||
| 146 | hardware by using the ``devtool build-image`` command. However, | ||
| 147 | ``devtool`` does not provide a specific command that allows you to | ||
| 148 | deploy the image to actual hardware. | ||
| 149 | |||
| 150 | #. *Finish Your Work With the Recipe*: The ``devtool finish`` command | ||
| 151 | creates any patches corresponding to commits in the local Git | ||
| 152 | repository, moves the new recipe to a more permanent layer, and then | ||
| 153 | resets the recipe so that the recipe is built normally rather than | ||
| 154 | from the workspace:: | ||
| 155 | |||
| 156 | $ devtool finish recipe layer | ||
| 157 | |||
| 158 | .. note:: | ||
| 159 | |||
| 160 | Any changes you want to turn into patches must be committed to the | ||
| 161 | Git repository in the source tree. | ||
| 162 | |||
| 163 | As mentioned, the ``devtool finish`` command moves the final recipe | ||
| 164 | to its permanent layer. | ||
| 165 | |||
| 166 | As a final process of the ``devtool finish`` command, the state of | ||
| 167 | the standard layers and the upstream source is restored so that you | ||
| 168 | can build the recipe from those areas rather than the workspace. | ||
| 169 | |||
| 170 | .. note:: | ||
| 171 | |||
| 172 | You can use the ``devtool reset`` command to put things back should you | ||
| 173 | decide you do not want to proceed with your work. If you do use this | ||
| 174 | command, realize that the source tree is preserved. | ||
| 175 | |||
| 176 | Use ``devtool modify`` to Modify the Source of an Existing Component | ||
| 177 | ==================================================================== | ||
| 178 | |||
| 179 | The ``devtool modify`` command prepares the way to work on existing code | ||
| 180 | that already has a local recipe in place that is used to build the | ||
| 181 | software. The command is flexible enough to allow you to extract code | ||
| 182 | from an upstream source, specify the existing recipe, and keep track of | ||
| 183 | and gather any patch files from other developers that are associated | ||
| 184 | with the code. | ||
| 185 | |||
| 186 | Depending on your particular scenario, the arguments and options you use | ||
| 187 | with ``devtool modify`` form different combinations. The following | ||
| 188 | diagram shows common development flows for the ``devtool modify`` | ||
| 189 | command: | ||
| 190 | |||
| 191 | .. image:: figures/devtool-modify-flow.png | ||
| 192 | :width: 100% | ||
| 193 | |||
| 194 | #. *Preparing to Modify the Code*: The top part of the flow shows three | ||
| 195 | scenarios by which you could use ``devtool modify`` to prepare to | ||
| 196 | work on source files. Each scenario assumes the following: | ||
| 197 | |||
| 198 | - The recipe exists locally in a layer external to the ``devtool`` | ||
| 199 | workspace. | ||
| 200 | |||
| 201 | - The source files exist either upstream in an un-extracted state or | ||
| 202 | locally in a previously extracted state. | ||
| 203 | |||
| 204 | The typical situation is where another developer has created a layer | ||
| 205 | for use with the Yocto Project and their recipe already resides in | ||
| 206 | that layer. Furthermore, their source code is readily available | ||
| 207 | either upstream or locally. | ||
| 208 | |||
| 209 | - *Left*: The left scenario in the figure represents a common | ||
| 210 | situation where the source code does not exist locally and it | ||
| 211 | needs to be extracted from an upstream source. In this situation, | ||
| 212 | the source is extracted into the default ``devtool`` workspace | ||
| 213 | location. The recipe, in this scenario, is in its own layer | ||
| 214 | outside the workspace (i.e. ``meta-``\ layername). | ||
| 215 | |||
| 216 | The following command identifies the recipe and, by default, | ||
| 217 | extracts the source files:: | ||
| 218 | |||
| 219 | $ devtool modify recipe | ||
| 220 | |||
| 221 | Once ``devtool`` locates the recipe, ``devtool`` uses the recipe's | ||
| 222 | :term:`SRC_URI` statements to locate the source code and any local | ||
| 223 | patch files from other developers. | ||
| 224 | |||
| 225 | With this scenario, there is no ``srctree`` argument. Consequently, the | ||
| 226 | default behavior of the ``devtool modify`` command is to extract | ||
| 227 | the source files pointed to by the :term:`SRC_URI` statements into a | ||
| 228 | local Git structure. Furthermore, the location for the extracted | ||
| 229 | source is the default area within the ``devtool`` workspace. The | ||
| 230 | result is that the command sets up both the source code and an | ||
| 231 | append file within the workspace while the recipe remains in its | ||
| 232 | original location. | ||
| 233 | |||
| 234 | Additionally, if you have any non-patch local files (i.e. files | ||
| 235 | referred to with ``file://`` entries in :term:`SRC_URI` statement | ||
| 236 | excluding ``*.patch/`` or ``*.diff``), these files are copied to | ||
| 237 | an ``oe-local-files`` folder under the newly created source tree. | ||
| 238 | Copying the files here gives you a convenient area from which you | ||
| 239 | can modify the files. Any changes or additions you make to those | ||
| 240 | files are incorporated into the build the next time you build the | ||
| 241 | software just as are other changes you might have made to the | ||
| 242 | source. | ||
| 243 | |||
| 244 | - *Middle*: The middle scenario in the figure represents a situation | ||
| 245 | where the source code also does not exist locally. In this case, | ||
| 246 | the code is again upstream and needs to be extracted to some local | ||
| 247 | area as a Git repository. The recipe, in this scenario, is again | ||
| 248 | local and in its own layer outside the workspace. | ||
| 249 | |||
| 250 | The following command tells ``devtool`` the recipe with which to | ||
| 251 | work and, in this case, identifies a local area for the extracted | ||
| 252 | source files that exists outside of the default ``devtool`` | ||
| 253 | workspace:: | ||
| 254 | |||
| 255 | $ devtool modify recipe srctree | ||
| 256 | |||
| 257 | .. note:: | ||
| 258 | |||
| 259 | You cannot provide a URL for ``srctree`` using the ``devtool`` command. | ||
| 260 | |||
| 261 | As with all extractions, the command uses the recipe's :term:`SRC_URI` | ||
| 262 | statements to locate the source files and any associated patch | ||
| 263 | files. Non-patch files are copied to an ``oe-local-files`` folder | ||
| 264 | under the newly created source tree. | ||
| 265 | |||
| 266 | Once the files are located, the command by default extracts them | ||
| 267 | into ``srctree``. | ||
| 268 | |||
| 269 | Within workspace, ``devtool`` creates an append file for the | ||
| 270 | recipe. The recipe remains in its original location but the source | ||
| 271 | files are extracted to the location you provide with ``srctree``. | ||
| 272 | |||
| 273 | - *Right*: The right scenario in the figure represents a situation | ||
| 274 | where the source tree (``srctree``) already exists locally as a | ||
| 275 | previously extracted Git structure outside of the ``devtool`` | ||
| 276 | workspace. In this example, the recipe also exists elsewhere | ||
| 277 | locally in its own layer. | ||
| 278 | |||
| 279 | The following command tells ``devtool`` the recipe with which to | ||
| 280 | work, uses the "-n" option to indicate source does not need to be | ||
| 281 | extracted, and uses ``srctree`` to point to the previously extracted | ||
| 282 | source files:: | ||
| 283 | |||
| 284 | $ devtool modify -n recipe srctree | ||
| 285 | |||
| 286 | If an ``oe-local-files`` subdirectory happens to exist and it | ||
| 287 | contains non-patch files, the files are used. However, if the | ||
| 288 | subdirectory does not exist and you run the ``devtool finish`` | ||
| 289 | command, any non-patch files that might exist next to the recipe | ||
| 290 | are removed because it appears to ``devtool`` that you have | ||
| 291 | deleted those files. | ||
| 292 | |||
| 293 | Once the ``devtool modify`` command finishes, it creates only an | ||
| 294 | append file for the recipe in the ``devtool`` workspace. The | ||
| 295 | recipe and the source code remain in their original locations. | ||
| 296 | |||
| 297 | #. *Edit the Source*: Once you have used the ``devtool modify`` command, | ||
| 298 | you are free to make changes to the source files. You can use any | ||
| 299 | editor you like to make and save your source code modifications. | ||
| 300 | |||
| 301 | #. *Build the Recipe or Rebuild the Image*: The next step you take | ||
| 302 | depends on what you are going to do with the new code. | ||
| 303 | |||
| 304 | If you need to eventually move the build output to the target | ||
| 305 | hardware, use the following ``devtool`` command:: | ||
| 306 | |||
| 307 | $ devtool build recipe | ||
| 308 | |||
| 309 | On the other hand, if you want an image to contain the recipe's | ||
| 310 | packages from the workspace for immediate deployment onto a device | ||
| 311 | (e.g. for testing purposes), you can use the ``devtool build-image`` | ||
| 312 | command:: | ||
| 313 | |||
| 314 | $ devtool build-image image | ||
| 315 | |||
| 316 | #. *Deploy the Build Output*: When you use the ``devtool build`` command | ||
| 317 | to build out your recipe, you probably want to see if the resulting | ||
| 318 | build output works as expected on target hardware. | ||
| 319 | |||
| 320 | .. note:: | ||
| 321 | |||
| 322 | This step assumes you have a previously built image that is | ||
| 323 | already either running in QEMU or running on actual hardware. | ||
| 324 | Also, it is assumed that for deployment of the image to the | ||
| 325 | target, SSH is installed in the image and if the image is running | ||
| 326 | on real hardware that you have network access to and from your | ||
| 327 | development machine. | ||
| 328 | |||
| 329 | You can deploy your build output to that target hardware by using the | ||
| 330 | ``devtool deploy-target`` command:: | ||
| 331 | |||
| 332 | $ devtool deploy-target recipe target | ||
| 333 | |||
| 334 | The target is a live target machine running as an SSH server. | ||
| 335 | |||
| 336 | You can, of course, use other methods to deploy the image you built | ||
| 337 | using the ``devtool build-image`` command to actual hardware. | ||
| 338 | ``devtool`` does not provide a specific command to deploy the image | ||
| 339 | to actual hardware. | ||
| 340 | |||
| 341 | #. *Finish Your Work With the Recipe*: The ``devtool finish`` command | ||
| 342 | creates any patches corresponding to commits in the local Git | ||
| 343 | repository, updates the recipe to point to them (or creates a | ||
| 344 | ``.bbappend`` file to do so, depending on the specified destination | ||
| 345 | layer), and then resets the recipe so that the recipe is built | ||
| 346 | normally rather than from the workspace:: | ||
| 347 | |||
| 348 | $ devtool finish recipe layer | ||
| 349 | |||
| 350 | .. note:: | ||
| 351 | |||
| 352 | Any changes you want to turn into patches must be staged and | ||
| 353 | committed within the local Git repository before you use the | ||
| 354 | ``devtool finish`` command. | ||
| 355 | |||
| 356 | Because there is no need to move the recipe, ``devtool finish`` | ||
| 357 | either updates the original recipe in the original layer or the | ||
| 358 | command creates a ``.bbappend`` file in a different layer as provided | ||
| 359 | by layer. Any work you did in the ``oe-local-files`` directory is | ||
| 360 | preserved in the original files next to the recipe during the | ||
| 361 | ``devtool finish`` command. | ||
| 362 | |||
| 363 | As a final process of the ``devtool finish`` command, the state of | ||
| 364 | the standard layers and the upstream source is restored so that you | ||
| 365 | can build the recipe from those areas rather than from the workspace. | ||
| 366 | |||
| 367 | .. note:: | ||
| 368 | |||
| 369 | You can use the ``devtool reset`` command to put things back should you | ||
| 370 | decide you do not want to proceed with your work. If you do use this | ||
| 371 | command, realize that the source tree is preserved. | ||
| 372 | |||
| 373 | ``devtool ide-sdk`` configures IDEs and bootstraps SDKs | ||
| 374 | ======================================================= | ||
| 375 | |||
| 376 | The ``devtool ide-sdk`` command can provide an IDE configuration for IDEs when | ||
| 377 | working on the source code of one or more recipes. | ||
| 378 | Depending on the programming language, and the build system used by the recipe, | ||
| 379 | the tools required for cross-development and remote debugging are different. | ||
| 380 | For example: | ||
| 381 | |||
| 382 | - A C/C++ project usually uses CMake or Meson. | ||
| 383 | |||
| 384 | - A Python project uses setuptools or one of its successors. | ||
| 385 | |||
| 386 | - A Rust project uses Cargo. | ||
| 387 | |||
| 388 | Also, the IDE plugins needed for the integration of a build system with the | ||
| 389 | IDE and the corresponding settings are usually specific to these build-systems. | ||
| 390 | To hide all these details from the user, ``devtool ide-sdk`` does two things: | ||
| 391 | |||
| 392 | - It generates any kind of SDK needed for cross-development and remote | ||
| 393 | debugging of the specified recipes. | ||
| 394 | |||
| 395 | - It generates the configuration for the IDE (and the IDE plugins) for using | ||
| 396 | the cross-toolchain and remote debugging tools provided by the SDK directly | ||
| 397 | from the IDE. | ||
| 398 | |||
| 399 | For supported build systems the configurations generated by ``devtool ide-sdk`` | ||
| 400 | combine the advantages of the ``devtool modify`` based workflow | ||
| 401 | (see :ref:`using_devtool`) with the advantages of the simple Environment Setup | ||
| 402 | script based workflow (see :ref:`running_the_ext_sdk_env`) provided by Yocto's | ||
| 403 | SDK or eSDK: | ||
| 404 | |||
| 405 | - The source code of the recipe is in the workspace created by | ||
| 406 | ``devtool modify`` or ``devtool add``. | ||
| 407 | Using ``devtool build``, ``devtool build-image``, | ||
| 408 | ``devtool deploy-target`` or ``bitbake`` is possible. | ||
| 409 | Also ``devtool ide-sdk`` can be used to update the SDK and the IDE | ||
| 410 | configuration at any time. | ||
| 411 | |||
| 412 | - ``devtool ide-sdk`` aims to support multiple programming languages and | ||
| 413 | multiple IDEs natively. "Natively" means that the IDE is configured to call | ||
| 414 | the build tool (e.g. ``cmake`` or ``meson``) directly. This has several | ||
| 415 | advantages. | ||
| 416 | First of all, it is usually much faster to call for example ``cmake`` than | ||
| 417 | ``devtool build``. | ||
| 418 | It also allows to benefit from the very good integration that IDEs like | ||
| 419 | VSCode offer for tools like CMake or GDB. | ||
| 420 | |||
| 421 | However, supporting many programming languages and multiple | ||
| 422 | IDEs is quite an elaborate and constantly evolving thing. Support for IDEs | ||
| 423 | is therefore implemented as plugins. Plugins can also be provided by | ||
| 424 | optional layers. | ||
| 425 | |||
| 426 | So much about the introduction to the default mode of ``devtool sdk-ide`` which | ||
| 427 | is called the "modified" mode because it uses the workspace created by | ||
| 428 | ``devtool modify`` and the per recipe :term:`Sysroots <Sysroot>` of BitBake. | ||
| 429 | |||
| 430 | For some recipes and use cases, this default behavior of ``devtool ide-sdk`` | ||
| 431 | with full ``devtool`` and ``bitbake`` integration might not be suitable. | ||
| 432 | To offer full feature parity with the SDK and the eSDK, ``devtool ide-sdk`` has | ||
| 433 | a second mode called "shared" mode. | ||
| 434 | If ``devtool ide-sdk`` is called with the ``--mode=shared`` option, it | ||
| 435 | bootstraps an SDK directly from the BitBake environment, which offers the same | ||
| 436 | Environment Setup script as described in :ref:`running_the_ext_sdk_env`. | ||
| 437 | In addition to the (e)SDK installer-based setup, the IDE gets configured | ||
| 438 | to use the shared :term:`Sysroots <Sysroot>` and the tools from the SDK. | ||
| 439 | ``devtool ide-sdk --mode=shared`` is basically a wrapper for the setup of the | ||
| 440 | extensible SDK as described in :ref:`setting_up_ext_sdk_in_build`. | ||
| 441 | |||
| 442 | The use of ``devtool ide-sdk`` is an alternative to using one of the SDK | ||
| 443 | installers. | ||
| 444 | ``devtool ide-sdk`` allows the creation of SDKs that offer all the | ||
| 445 | functionality of the SDK and the eSDK installers. Compared to the installers, | ||
| 446 | however, the SDK created with ``devtool ide-sdk`` is much more flexible. | ||
| 447 | For example, it is very easy to change the :term:`MACHINE` in the | ||
| 448 | ``local.conf`` file, update the layer meta data and then regenerate the SDK. | ||
| 449 | |||
| 450 | Let's take a look at an example of how to use ``devtool ide-sdk`` in each of | ||
| 451 | the two modes: | ||
| 452 | |||
| 453 | #. *Modified mode*: | ||
| 454 | |||
| 455 | In order to use the ``devtool ide-sdk``, a few settings are needed. As a | ||
| 456 | starting example, the following lines of code can be added to the | ||
| 457 | ``local.conf`` file:: | ||
| 458 | |||
| 459 | # Build the companion debug file system | ||
| 460 | IMAGE_GEN_DEBUGFS = "1" | ||
| 461 | # Optimize build time: with devtool ide-sdk the dbg tar is not needed | ||
| 462 | IMAGE_FSTYPES_DEBUGFS = "" | ||
| 463 | # Without copying the binaries into roofs-dbg, GDB does not find all source files. | ||
| 464 | IMAGE_CLASSES += "image-combined-dbg" | ||
| 465 | |||
| 466 | # SSH is mandatory, no password simplifies the usage | ||
| 467 | EXTRA_IMAGE_FEATURES += "\ | ||
| 468 | ssh-server-openssh \ | ||
| 469 | allow-empty-password \ | ||
| 470 | allow-root-login \ | ||
| 471 | empty-root-password \ | ||
| 472 | " | ||
| 473 | |||
| 474 | # Remote debugging needs gdbserver on the target device | ||
| 475 | IMAGE_INSTALL:append = " gdbserver" | ||
| 476 | |||
| 477 | # Add the recipes which should be modified to the image | ||
| 478 | # Otherwise some dependencies might be missing. | ||
| 479 | IMAGE_INSTALL:append = " my-recipe" | ||
| 480 | |||
| 481 | Assuming the BitBake environment is set up correctly and a workspace has | ||
| 482 | been created for the recipe using ``devtool modify my-recipe`` or probably | ||
| 483 | even better by using ``devtool modify my-recipe --debug-build``, the | ||
| 484 | following command can create the SDK and the configuration for VSCode in | ||
| 485 | the recipe workspace:: | ||
| 486 | |||
| 487 | $ devtool ide-sdk my-recipe core-image-minimal --target root@192.168.7.2 | ||
| 488 | |||
| 489 | The command requires an image recipe (``core-image-minimal`` for this | ||
| 490 | example) that is used to create the SDK. | ||
| 491 | This firmware image should also be installed on the target device. | ||
| 492 | It is possible to pass multiple package recipes:: | ||
| 493 | |||
| 494 | $ devtool ide-sdk my-recipe-1 my-recipe-2 core-image-minimal --target root@192.168.7.2 | ||
| 495 | |||
| 496 | ``devtool ide-sdk`` tries to create an IDE configuration for all package | ||
| 497 | recipes. | ||
| 498 | |||
| 499 | What this command does exactly depends on the recipe, more precisely on the | ||
| 500 | build tool used by the recipe. The basic idea is to configure the IDE so | ||
| 501 | that it calls the build tool exactly as ``bitbake`` does. | ||
| 502 | |||
| 503 | For example, a CMake preset is created for a recipe that inherits | ||
| 504 | :ref:`ref-classes-cmake`. In the case of VSCode, CMake presets are supported | ||
| 505 | by the CMake Tools plugin. This is an example of how the build configuration | ||
| 506 | used by ``bitbake`` is exported to an IDE configuration that gives exactly | ||
| 507 | the same build results. | ||
| 508 | |||
| 509 | Support for remote debugging with seamless integration into the IDE is | ||
| 510 | important for a cross-SDK. ``devtool ide-sdk`` automatically generates the | ||
| 511 | necessary helper scripts for deploying the compiled artifacts to the target | ||
| 512 | device as well as the necessary configuration for the debugger and the IDE. | ||
| 513 | |||
| 514 | .. note:: | ||
| 515 | |||
| 516 | To ensure that the debug symbols on the build machine match the binaries | ||
| 517 | running on the target device, it is essential that the image built by | ||
| 518 | ``devtool ide-sdk`` is running on the target device. | ||
| 519 | |||
| 520 | The default IDE is VSCode. Some hints about using VSCode: | ||
| 521 | |||
| 522 | - VSCode can be used to work on the BitBake recipes or the application | ||
| 523 | source code. | ||
| 524 | Usually there is one instance of VSCode running in the folder where the | ||
| 525 | BitBake recipes are. This instance has the | ||
| 526 | `Yocto Project BitBake plugin <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`_ | ||
| 527 | running. | ||
| 528 | |||
| 529 | .. warning:: | ||
| 530 | |||
| 531 | Some VSCode plugins (Python, BitBake and others) need a reasonable | ||
| 532 | configuration to work as expected. Otherwise, some plugins try to | ||
| 533 | index the build directory of BitBake, which keeps your system quite | ||
| 534 | busy until an out of memory exception stops this nonsense. | ||
| 535 | Other plugins, such as the BitBake plugin, do not behave as expected. | ||
| 536 | |||
| 537 | To work around such issues, the ``oe-init-build-env`` script creates | ||
| 538 | an initial ``.vscode/settings.json`` file if ``code`` can be found | ||
| 539 | and the ``.vscode`` folder does not yet exist. | ||
| 540 | It is best to run ``oe-init-build-env`` once before starting VSCode. | ||
| 541 | An alternative approach is to use a build folder outside the layers, | ||
| 542 | e.g. ``oe-init-build-env ../build``. | ||
| 543 | |||
| 544 | The BitBake plugin also offers to create devtool workspaces and run | ||
| 545 | ``devtool ide-sdk`` with a few mouse clicks. | ||
| 546 | Of course, issuing commands in the terminal works as well. | ||
| 547 | |||
| 548 | - To work on the source code of a recipe another instance of VSCode is | ||
| 549 | started in the recipe's workspace. Example:: | ||
| 550 | |||
| 551 | code build/workspace/sources/my-recipe | ||
| 552 | |||
| 553 | This instance of VSCode uses plugins that are useful for the development | ||
| 554 | of the application. ``devtool ide-sdk`` generates the necessary | ||
| 555 | ``extensions.json``, ``settings.json``, ``tasks.json`` and ``launch.json`` | ||
| 556 | configuration files for all the involved plugins. | ||
| 557 | |||
| 558 | When the source code folder present in the workspace folder is opened in | ||
| 559 | VSCode for the first time, a pop-up message recommends installing the | ||
| 560 | required plugins. | ||
| 561 | After accepting the installation of the plugins, working with the source | ||
| 562 | code or some debugging tasks should work as usual with VSCode. | ||
| 563 | |||
| 564 | Starting the VSCode instances in the recipe workspace folders can also be | ||
| 565 | done by a mouse click on the recipe workspaces in the first VSCode | ||
| 566 | instance. | ||
| 567 | |||
| 568 | - To work with CMake press ``Ctrl + Shift + p``, type ``cmake``. This will | ||
| 569 | show some possible commands like selecting a CMake preset, compiling or | ||
| 570 | running CTest. | ||
| 571 | |||
| 572 | For recipes inheriting :ref:`ref-classes-cmake-qemu` rather than | ||
| 573 | :ref:`ref-classes-cmake`, executing cross-compiled unit tests on the host | ||
| 574 | can be supported transparently with QEMU user-mode. | ||
| 575 | |||
| 576 | - To work with Meson press ``Ctrl + Shift + p``, type ``meson``. This will | ||
| 577 | show some possible commands like compiling or executing the unit tests. | ||
| 578 | |||
| 579 | A note on running cross-compiled unit tests on the host: Meson enables | ||
| 580 | support for QEMU user mode by default. It is expected that the execution | ||
| 581 | of the unit tests from the IDE will work without any additional steps, | ||
| 582 | given that the code is suitable for the execution on the host machine. | ||
| 583 | |||
| 584 | - For the deployment to the target device, just press ``Ctrl + Shift + p``, | ||
| 585 | type ``task``. Select ``install && deploy-target``. | ||
| 586 | |||
| 587 | - For remote debugging, switch to the debugging view by pressing the "play" | ||
| 588 | button with the ``bug icon`` on the left side. This will provide a green | ||
| 589 | play button with a drop-down list where a debug configuration can be | ||
| 590 | selected. After selecting one of the generated configurations, press the | ||
| 591 | "play" button. | ||
| 592 | |||
| 593 | Starting a remote debugging session automatically initiates the | ||
| 594 | deployment to the target device. If this is not desired, the | ||
| 595 | ``"dependsOn": ["install && deploy-target...]`` parameter of the tasks | ||
| 596 | with ``"label": "gdbserver start...`` can be removed from the | ||
| 597 | ``tasks.json`` file. | ||
| 598 | |||
| 599 | VSCode supports GDB with many different setups and configurations for | ||
| 600 | many different use cases. However, most of these setups have some | ||
| 601 | limitations when it comes to cross-development, support only a few target | ||
| 602 | architectures or require a high performance target device. Therefore | ||
| 603 | ``devtool ide-sdk`` supports the classic, generic setup with GDB on the | ||
| 604 | development host and gdbserver on the target device. | ||
| 605 | |||
| 606 | Roughly summarized, this means: | ||
| 607 | |||
| 608 | - The binaries are copied via SSH to the remote target device by a | ||
| 609 | script referred by ``tasks.json``. | ||
| 610 | |||
| 611 | - gdbserver is started on the remote target device via SSH by a script | ||
| 612 | referred by ``tasks.json``. | ||
| 613 | |||
| 614 | Changing the parameters that are passed to the debugging executable | ||
| 615 | requires modifying the generated script. The script is located at | ||
| 616 | ``oe-scripts/gdbserver_*``. Defining the parameters in the ``args`` | ||
| 617 | field in the ``launch.json`` file does not work. | ||
| 618 | |||
| 619 | - VSCode connects to gdbserver as documented in | ||
| 620 | `Remote debugging or debugging with a local debugger server | ||
| 621 | <https://code.visualstudio.com/docs/cpp/launch-json-reference#_remote-debugging-or-debugging-with-a-local-debugger-server>`__. | ||
| 622 | |||
| 623 | Additionally ``--ide=none`` is supported. With the ``none`` IDE parameter, | ||
| 624 | some generic configuration files like ``gdbinit`` files and some helper | ||
| 625 | scripts starting gdbserver remotely on the target device as well as the GDB | ||
| 626 | client on the host are generated. | ||
| 627 | |||
| 628 | Here is a usage example for the ``cmake-example`` recipe from the | ||
| 629 | ``meta-selftest`` layer which inherits :ref:`ref-classes-cmake-qemu`: | ||
| 630 | |||
| 631 | .. code-block:: sh | ||
| 632 | |||
| 633 | # Create the SDK | ||
| 634 | devtool modify cmake-example --debug-build | ||
| 635 | devtool ide-sdk cmake-example core-image-minimal -c --ide=none | ||
| 636 | |||
| 637 | # Install the firmware on a target device or start QEMU | ||
| 638 | runqemu | ||
| 639 | |||
| 640 | # From exploring the workspace of cmake-example | ||
| 641 | cd build/workspace/sources/cmake-example | ||
| 642 | |||
| 643 | # Find cmake-native and save the path into a variable | ||
| 644 | # Note: using just cmake instead of $CMAKE_NATIVE would work in many cases | ||
| 645 | CMAKE_NATIVE="$(jq -r '.configurePresets[0] | "\(.cmakeExecutable)"' CMakeUserPresets.json)" | ||
| 646 | |||
| 647 | # List available CMake presets | ||
| 648 | "$CMAKE_NATIVE" --list-presets | ||
| 649 | Available configure presets: | ||
| 650 | |||
| 651 | "cmake-example-cortexa57" - cmake-example: cortexa57 | ||
| 652 | |||
| 653 | # Re-compile the already compiled sources | ||
| 654 | "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 | ||
| 655 | ninja: no work to do. | ||
| 656 | # Do a clean re-build | ||
| 657 | "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target clean | ||
| 658 | [1/1] Cleaning all built files... | ||
| 659 | Cleaning... 8 files. | ||
| 660 | "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target all | ||
| 661 | [7/7] Linking CXX executable cmake-example | ||
| 662 | |||
| 663 | # Run the cross-compiled unit tests with QEMU user-mode | ||
| 664 | "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target test | ||
| 665 | [0/1] Running tests... | ||
| 666 | Test project .../build/tmp/work/cortexa57-poky-linux/cmake-example/1.0/cmake-example-1.0 | ||
| 667 | Start 1: test-cmake-example | ||
| 668 | 1/1 Test #1: test-cmake-example ............... Passed 0.03 sec | ||
| 669 | |||
| 670 | 100% tests passed, 0 tests failed out of 1 | ||
| 671 | |||
| 672 | Total Test time (real) = 0.03 sec | ||
| 673 | |||
| 674 | # Using CTest directly is possible as well | ||
| 675 | CTEST_NATIVE="$(dirname "$CMAKE_NATIVE")/ctest" | ||
| 676 | |||
| 677 | # List available CMake presets | ||
| 678 | "$CTEST_NATIVE" --list-presets | ||
| 679 | Available test presets: | ||
| 680 | |||
| 681 | "cmake-example-cortexa57" - cmake-example: cortexa57 | ||
| 682 | |||
| 683 | # Run the cross-compiled unit tests with QEMU user-mode | ||
| 684 | "$CTEST_NATIVE" --preset "cmake-example-cortexa57" | ||
| 685 | Test project ...build/tmp/work/cortexa57-poky-linux/cmake-example/1.0/cmake-example-1.0 | ||
| 686 | Start 1: test-cmake-example | ||
| 687 | 1/1 Test #1: test-cmake-example ............... Passed 0.03 sec | ||
| 688 | |||
| 689 | 100% tests passed, 0 tests failed out of 1 | ||
| 690 | |||
| 691 | Total Test time (real) = 0.03 sec | ||
| 692 | |||
| 693 | # Deploying the new build to the target device (default is QEUM at 192.168.7.2) | ||
| 694 | oe-scripts/install_and_deploy_cmake-example-cortexa57 | ||
| 695 | |||
| 696 | # Start a remote debugging session with gdbserver on the target and GDB on the host | ||
| 697 | oe-scripts/gdbserver_1234_usr-bin-cmake-example_m | ||
| 698 | oe-scripts/gdb_1234_usr-bin-cmake-example | ||
| 699 | break main | ||
| 700 | run | ||
| 701 | step | ||
| 702 | stepi | ||
| 703 | continue | ||
| 704 | quit | ||
| 705 | |||
| 706 | # Stop gdbserver on the target device | ||
| 707 | oe-scripts/gdbserver_1234_usr-bin-cmake-example_m stop | ||
| 708 | |||
| 709 | #. *Shared sysroots mode* | ||
| 710 | |||
| 711 | Creating an SDK with shared :term:`Sysroots <Sysroot>` that contains all the | ||
| 712 | dependencies needed to work with ``my-recipe`` is possible with the following | ||
| 713 | example command:: | ||
| 714 | |||
| 715 | $ devtool ide-sdk --mode=shared my-recipe | ||
| 716 | |||
| 717 | For VSCode the cross-toolchain is exposed as a CMake kit. CMake kits are | ||
| 718 | defined in ``~/.local/share/CMakeTools/cmake-tools-kits.json``. | ||
| 719 | The following example shows how the cross-toolchain can be selected in | ||
| 720 | VSCode. First of all we need a folder containing a CMake project. | ||
| 721 | For this example, let's create a CMake project and start VSCode:: | ||
| 722 | |||
| 723 | mkdir kit-test | ||
| 724 | echo "project(foo VERSION 1.0)" > kit-test/CMakeLists.txt | ||
| 725 | code kit-test | ||
| 726 | |||
| 727 | If there is a CMake project in the workspace, cross-compilation is | ||
| 728 | supported: | ||
| 729 | |||
| 730 | - Press ``Ctrl + Shift + P``, type ``CMake: Scan for Kits`` | ||
| 731 | - Press ``Ctrl + Shift + P``, type ``CMake: Select a Kit`` | ||
| 732 | |||
| 733 | Finally most of the features provided by CMake and the IDE should be | ||
| 734 | available. | ||
| 735 | |||
| 736 | Other IDEs than VSCode are supported as well. However, | ||
| 737 | ``devtool ide-sdk --mode=shared --ide=none my-recipe`` is currently | ||
| 738 | just a simple wrapper for the setup of the extensible SDK, as described in | ||
| 739 | :ref:`setting_up_ext_sdk_in_build`. | ||
| 740 | |||
| 741 | Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a Newer Version of the Software | ||
| 742 | ======================================================================================================= | ||
| 743 | |||
| 744 | The ``devtool upgrade`` command upgrades an existing recipe to that of a | ||
| 745 | more up-to-date version found upstream. Throughout the life of software, | ||
| 746 | recipes continually undergo version upgrades by their upstream | ||
| 747 | publishers. You can use the ``devtool upgrade`` workflow to make sure | ||
| 748 | your recipes you are using for builds are up-to-date with their upstream | ||
| 749 | counterparts. | ||
| 750 | |||
| 751 | .. note:: | ||
| 752 | |||
| 753 | Several methods exist by which you can upgrade recipes --- | ||
| 754 | ``devtool upgrade`` happens to be one. You can read about all the methods by | ||
| 755 | which you can upgrade recipes in the | ||
| 756 | :ref:`dev-manual/upgrading-recipes:upgrading recipes` section of the Yocto | ||
| 757 | Project Development Tasks Manual. | ||
| 758 | |||
| 759 | The ``devtool upgrade`` command is flexible enough to allow you to specify | ||
| 760 | source code revision and versioning schemes, extract code into or out of the | ||
| 761 | ``devtool`` :ref:`devtool-the-workspace-layer-structure`, and work with any | ||
| 762 | source file forms that the | ||
| 763 | :ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers` support. | ||
| 764 | |||
| 765 | The following diagram shows the common development flow used with the | ||
| 766 | ``devtool upgrade`` command: | ||
| 767 | |||
| 768 | .. image:: figures/devtool-upgrade-flow.png | ||
| 769 | :width: 100% | ||
| 770 | |||
| 771 | #. *Initiate the Upgrade*: The top part of the flow shows the typical | ||
| 772 | scenario by which you use the ``devtool upgrade`` command. The | ||
| 773 | following conditions exist: | ||
| 774 | |||
| 775 | - The recipe exists in a local layer external to the ``devtool`` | ||
| 776 | workspace. | ||
| 777 | |||
| 778 | - The source files for the new release exist in the same location | ||
| 779 | pointed to by :term:`SRC_URI` | ||
| 780 | in the recipe (e.g. a tarball with the new version number in the | ||
| 781 | name, or as a different revision in the upstream Git repository). | ||
| 782 | |||
| 783 | A common situation is where third-party software has undergone a | ||
| 784 | revision so that it has been upgraded. The recipe you have access to | ||
| 785 | is likely in your own layer. Thus, you need to upgrade the recipe to | ||
| 786 | use the newer version of the software:: | ||
| 787 | |||
| 788 | $ devtool upgrade -V version recipe | ||
| 789 | |||
| 790 | By default, the ``devtool upgrade`` command extracts source | ||
| 791 | code into the ``sources`` directory in the | ||
| 792 | :ref:`devtool-the-workspace-layer-structure`. | ||
| 793 | If you want the code extracted to any other location, you need to | ||
| 794 | provide the ``srctree`` positional argument with the command as follows:: | ||
| 795 | |||
| 796 | $ devtool upgrade -V version recipe srctree | ||
| 797 | |||
| 798 | .. note:: | ||
| 799 | |||
| 800 | In this example, the "-V" option specifies the new version. If you | ||
| 801 | don't use "-V", the command upgrades the recipe to the latest | ||
| 802 | version. | ||
| 803 | |||
| 804 | If the source files pointed to by the :term:`SRC_URI` statement in the | ||
| 805 | recipe are in a Git repository, you must provide the "-S" option and | ||
| 806 | specify a revision for the software. | ||
| 807 | |||
| 808 | Once ``devtool`` locates the recipe, it uses the :term:`SRC_URI` variable | ||
| 809 | to locate the source code and any local patch files from other | ||
| 810 | developers. The result is that the command sets up the source code, | ||
| 811 | the new version of the recipe, and an append file all within the | ||
| 812 | workspace. | ||
| 813 | |||
| 814 | Additionally, if you have any non-patch local files (i.e. files | ||
| 815 | referred to with ``file://`` entries in :term:`SRC_URI` statement | ||
| 816 | excluding ``*.patch/`` or ``*.diff``), these files are copied to an | ||
| 817 | ``oe-local-files`` folder under the newly created source tree. | ||
| 818 | Copying the files here gives you a convenient area from which you can | ||
| 819 | modify the files. Any changes or additions you make to those files | ||
| 820 | are incorporated into the build the next time you build the software | ||
| 821 | just as are other changes you might have made to the source. | ||
| 822 | |||
| 823 | #. *Resolve any Conflicts created by the Upgrade*: Conflicts could happen | ||
| 824 | after upgrading the software to a new version. Conflicts occur | ||
| 825 | if your recipe specifies some patch files in :term:`SRC_URI` that | ||
| 826 | conflict with changes made in the new version of the software. For | ||
| 827 | such cases, you need to resolve the conflicts by editing the source | ||
| 828 | and following the normal ``git rebase`` conflict resolution process. | ||
| 829 | |||
| 830 | Before moving onto the next step, be sure to resolve any such | ||
| 831 | conflicts created through use of a newer or different version of the | ||
| 832 | software. | ||
| 833 | |||
| 834 | #. *Build the Recipe or Rebuild the Image*: The next step you take | ||
| 835 | depends on what you are going to do with the new code. | ||
| 836 | |||
| 837 | If you need to eventually move the build output to the target | ||
| 838 | hardware, use the following ``devtool`` command:: | ||
| 839 | |||
| 840 | $ devtool build recipe | ||
| 841 | |||
| 842 | On the other hand, if you want an image to contain the recipe's | ||
| 843 | packages from the workspace for immediate deployment onto a device | ||
| 844 | (e.g. for testing purposes), you can use the ``devtool build-image`` | ||
| 845 | command:: | ||
| 846 | |||
| 847 | $ devtool build-image image | ||
| 848 | |||
| 849 | #. *Deploy the Build Output*: When you use the ``devtool build`` command | ||
| 850 | or ``bitbake`` to build your recipe, you probably want to see if the | ||
| 851 | resulting build output works as expected on target hardware. | ||
| 852 | |||
| 853 | .. note:: | ||
| 854 | |||
| 855 | This step assumes you have a previously built image that is | ||
| 856 | already either running in QEMU or running on actual hardware. | ||
| 857 | Also, it is assumed that for deployment of the image to the | ||
| 858 | target, SSH is installed in the image and if the image is running | ||
| 859 | on real hardware that you have network access to and from your | ||
| 860 | development machine. | ||
| 861 | |||
| 862 | You can deploy your build output to that target hardware by using the | ||
| 863 | ``devtool deploy-target`` command:: | ||
| 864 | |||
| 865 | $ devtool deploy-target recipe target | ||
| 866 | |||
| 867 | The target is a live target machine running as an SSH server. | ||
| 868 | |||
| 869 | You can, of course, also deploy the image you build using the | ||
| 870 | ``devtool build-image`` command to actual hardware. However, | ||
| 871 | ``devtool`` does not provide a specific command that allows you to do | ||
| 872 | this. | ||
| 873 | |||
| 874 | #. *Finish Your Work With the Recipe*: The ``devtool finish`` command | ||
| 875 | creates any patches corresponding to commits in the local Git | ||
| 876 | repository, moves the new recipe to a more permanent layer, and then | ||
| 877 | resets the recipe so that the recipe is built normally rather than | ||
| 878 | from the workspace. | ||
| 879 | |||
| 880 | Any work you did in the ``oe-local-files`` directory is preserved in | ||
| 881 | the original files next to the recipe during the ``devtool finish`` | ||
| 882 | command. | ||
| 883 | |||
| 884 | If you specify a destination layer that is the same as the original | ||
| 885 | source, then the old version of the recipe and associated files are | ||
| 886 | removed prior to adding the new version:: | ||
| 887 | |||
| 888 | $ devtool finish recipe layer | ||
| 889 | |||
| 890 | .. note:: | ||
| 891 | |||
| 892 | Any changes you want to turn into patches must be committed to the | ||
| 893 | Git repository in the source tree. | ||
| 894 | |||
| 895 | As a final process of the ``devtool finish`` command, the state of | ||
| 896 | the standard layers and the upstream source is restored so that you | ||
| 897 | can build the recipe from those areas rather than the workspace. | ||
| 898 | |||
| 899 | .. note:: | ||
| 900 | |||
| 901 | You can use the ``devtool reset`` command to put things back should you | ||
| 902 | decide you do not want to proceed with your work. If you do use this | ||
| 903 | command, realize that the source tree is preserved. | ||
| 904 | |||
| 905 | A Closer Look at ``devtool add`` | ||
| 906 | ================================ | ||
| 907 | |||
| 908 | The ``devtool add`` command automatically creates a recipe based on the | ||
| 909 | source tree you provide with the command. Currently, the command has | ||
| 910 | support for the following: | ||
| 911 | |||
| 912 | - Autotools (``autoconf`` and ``automake``) | ||
| 913 | |||
| 914 | - CMake | ||
| 915 | |||
| 916 | - Scons | ||
| 917 | |||
| 918 | - ``qmake`` | ||
| 919 | |||
| 920 | - Plain ``Makefile`` | ||
| 921 | |||
| 922 | - Out-of-tree kernel module | ||
| 923 | |||
| 924 | - Binary package (i.e. "-b" option) | ||
| 925 | |||
| 926 | - Node.js module | ||
| 927 | |||
| 928 | - Python modules that use ``setuptools`` or ``distutils`` | ||
| 929 | |||
| 930 | Apart from binary packages, the determination of how a source tree | ||
| 931 | should be treated is automatic based on the files present within that | ||
| 932 | source tree. For example, if a ``CMakeLists.txt`` file is found, then | ||
| 933 | the source tree is assumed to be using CMake and is treated accordingly. | ||
| 934 | |||
| 935 | .. note:: | ||
| 936 | |||
| 937 | In most cases, you need to edit the automatically generated recipe in | ||
| 938 | order to make it build properly. Typically, you would go through | ||
| 939 | several edit and build cycles until the recipe successfully builds. | ||
| 940 | Once the recipe builds, you could use possible further iterations to | ||
| 941 | test the recipe on the target device. | ||
| 942 | |||
| 943 | The remainder of this section covers specifics regarding how parts of | ||
| 944 | the recipe are generated. | ||
| 945 | |||
| 946 | Name and Version | ||
| 947 | ---------------- | ||
| 948 | |||
| 949 | If you do not specify a name and version on the command line, | ||
| 950 | ``devtool add`` uses various metadata within the source tree in an | ||
| 951 | attempt to determine the name and version of the software being built. | ||
| 952 | Based on what the tool determines, ``devtool`` sets the name of the | ||
| 953 | created recipe file accordingly. | ||
| 954 | |||
| 955 | If ``devtool`` cannot determine the name and version, the command prints | ||
| 956 | an error. For such cases, you must re-run the command and provide the | ||
| 957 | name and version, just the name, or just the version as part of the | ||
| 958 | command line. | ||
| 959 | |||
| 960 | Sometimes the name or version determined from the source tree might be | ||
| 961 | incorrect. For such a case, you must reset the recipe:: | ||
| 962 | |||
| 963 | $ devtool reset -n recipename | ||
| 964 | |||
| 965 | After running the ``devtool reset`` command, you need to | ||
| 966 | run ``devtool add`` again and provide the name or the version. | ||
| 967 | |||
| 968 | Dependency Detection and Mapping | ||
| 969 | -------------------------------- | ||
| 970 | |||
| 971 | The ``devtool add`` command attempts to detect build-time dependencies and map | ||
| 972 | them to other recipes in the system. During this mapping, the command fills in | ||
| 973 | the names of those recipes as part of the :term:`DEPENDS` variable within the | ||
| 974 | recipe. If a dependency cannot be mapped, ``devtool`` places a comment | ||
| 975 | in the recipe indicating such. The inability to map a dependency can | ||
| 976 | result from naming not being recognized or because the dependency simply | ||
| 977 | is not available. For cases where the dependency is not available, you | ||
| 978 | must use the ``devtool add`` command to add an additional recipe that | ||
| 979 | satisfies the dependency. Once you add that recipe, you need to update | ||
| 980 | the :term:`DEPENDS` variable in the original recipe to include the new | ||
| 981 | recipe. | ||
| 982 | |||
| 983 | If you need to add runtime dependencies, you can do so by adding the | ||
| 984 | following to your recipe:: | ||
| 985 | |||
| 986 | RDEPENDS:${PN} += "dependency1 dependency2 ..." | ||
| 987 | |||
| 988 | .. note:: | ||
| 989 | |||
| 990 | The ``devtool add`` command often cannot distinguish between mandatory and | ||
| 991 | optional dependencies. Consequently, some of the detected dependencies might | ||
| 992 | in fact be optional. When in doubt, consult the documentation or the | ||
| 993 | configure script for the software the recipe is building for further | ||
| 994 | details. In some cases, you might find you can substitute the | ||
| 995 | dependency with an option that disables the associated functionality | ||
| 996 | passed to the configure script. | ||
| 997 | |||
| 998 | License Detection | ||
| 999 | ----------------- | ||
| 1000 | |||
| 1001 | The ``devtool add`` command attempts to determine if the software you are | ||
| 1002 | adding is able to be distributed under a common, open-source license. If | ||
| 1003 | so, the command sets the :term:`LICENSE` value accordingly. | ||
| 1004 | You should double-check the value added by the command against the | ||
| 1005 | documentation or source files for the software you are building and, if | ||
| 1006 | necessary, update that :term:`LICENSE` value. | ||
| 1007 | |||
| 1008 | The ``devtool add`` command also sets the :term:`LIC_FILES_CHKSUM` | ||
| 1009 | value to point to all files that appear to be license-related. Realize | ||
| 1010 | that license statements often appear in comments at the top of source | ||
| 1011 | files or within the documentation. In such cases, the command does not | ||
| 1012 | recognize those license statements. Consequently, you might need to | ||
| 1013 | amend the :term:`LIC_FILES_CHKSUM` variable to point to one or more of those | ||
| 1014 | comments if present. Setting :term:`LIC_FILES_CHKSUM` is particularly | ||
| 1015 | important for third-party software. The mechanism attempts to ensure | ||
| 1016 | correct licensing should you upgrade the recipe to a newer upstream | ||
| 1017 | version in future. Any change in licensing is detected and you receive | ||
| 1018 | an error prompting you to check the license text again. | ||
| 1019 | |||
| 1020 | If the ``devtool add`` command cannot determine licensing information, | ||
| 1021 | ``devtool`` sets the :term:`LICENSE` value to "CLOSED" and leaves the | ||
| 1022 | :term:`LIC_FILES_CHKSUM` value unset. This behavior allows you to continue | ||
| 1023 | with development even though the settings are unlikely to be correct in | ||
| 1024 | all cases. You should check the documentation or source files for the | ||
| 1025 | software you are building to determine the actual license. | ||
| 1026 | |||
| 1027 | Adding Makefile-Only Software | ||
| 1028 | ----------------------------- | ||
| 1029 | |||
| 1030 | The use of Make by itself is very common in both proprietary and | ||
| 1031 | open-source software. Unfortunately, Makefiles are often not written | ||
| 1032 | with cross-compilation in mind. Thus, ``devtool add`` often cannot do | ||
| 1033 | very much to ensure that these Makefiles build correctly. It is very | ||
| 1034 | common, for example, to explicitly call ``gcc`` instead of using the | ||
| 1035 | :term:`CC` variable. Usually, in a | ||
| 1036 | cross-compilation environment, ``gcc`` is the compiler for the build | ||
| 1037 | host and the cross-compiler is named something similar to | ||
| 1038 | ``arm-poky-linux-gnueabi-gcc`` and might require arguments (e.g. to | ||
| 1039 | point to the associated sysroot for the target machine). | ||
| 1040 | |||
| 1041 | When writing a recipe for Makefile-only software, keep the following in | ||
| 1042 | mind: | ||
| 1043 | |||
| 1044 | - You probably need to patch the Makefile to use variables instead of | ||
| 1045 | hardcoding tools within the toolchain such as ``gcc`` and ``g++``. | ||
| 1046 | |||
| 1047 | - The environment in which Make runs is set up with various standard | ||
| 1048 | variables for compilation (e.g. :term:`CC`, :term:`CXX`, and so forth) in a | ||
| 1049 | similar manner to the environment set up by an :ref:`SDK | ||
| 1050 | <overview-manual/concepts:Application Development SDK>`'s environment | ||
| 1051 | setup script. One easy way to see these variables is to run the | ||
| 1052 | ``devtool build`` command on the recipe and then look in | ||
| 1053 | ``oe-logs/run.do_compile``. Towards the top of this file, there is | ||
| 1054 | a list of environment variables that are set. You can take | ||
| 1055 | advantage of these variables within the Makefile. | ||
| 1056 | |||
| 1057 | - If the Makefile sets a default for a variable using "=", that default | ||
| 1058 | overrides the value set in the environment, which is usually not | ||
| 1059 | desirable. For this case, you can either patch the Makefile so it | ||
| 1060 | sets the default using the "?=" operator, or you can alternatively | ||
| 1061 | force the value on the ``make`` command line. To force the value on | ||
| 1062 | the command line, add the variable setting to | ||
| 1063 | :term:`EXTRA_OEMAKE` or | ||
| 1064 | :term:`PACKAGECONFIG_CONFARGS` | ||
| 1065 | within the recipe. Here is an example using :term:`EXTRA_OEMAKE`:: | ||
| 1066 | |||
| 1067 | EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" | ||
| 1068 | |||
| 1069 | In the above example, | ||
| 1070 | single quotes are used around the variable settings as the values are | ||
| 1071 | likely to contain spaces because required default options are passed | ||
| 1072 | to the compiler. | ||
| 1073 | |||
| 1074 | - Hardcoding paths inside Makefiles is often problematic in a | ||
| 1075 | cross-compilation environment. This is particularly true because | ||
| 1076 | those hardcoded paths often point to locations on the build host and | ||
| 1077 | thus will either be read-only or will introduce contamination into | ||
| 1078 | the cross-compilation because they are specific to the build host | ||
| 1079 | rather than the target. Patching the Makefile to use prefix variables | ||
| 1080 | or other path variables is usually the way to handle this situation. | ||
| 1081 | |||
| 1082 | - Sometimes a Makefile runs target-specific commands such as | ||
| 1083 | ``ldconfig``. For such cases, you might be able to apply patches that | ||
| 1084 | remove these commands from the Makefile. | ||
| 1085 | |||
| 1086 | Adding Native Tools | ||
| 1087 | ------------------- | ||
| 1088 | |||
| 1089 | Often, you need to build additional tools that run on the :term:`Build Host` | ||
| 1090 | as opposed to the target. You should indicate this requirement by using one of | ||
| 1091 | the following methods when you run ``devtool add``: | ||
| 1092 | |||
| 1093 | - Specify the name of the recipe such that it ends with "-native". | ||
| 1094 | Specifying the name like this produces a recipe that only builds for | ||
| 1095 | the build host. | ||
| 1096 | |||
| 1097 | - Specify the "--also-native" option with the ``devtool add`` | ||
| 1098 | command. Specifying this option creates a recipe file that still | ||
| 1099 | builds for the target but also creates a variant with a "-native" | ||
| 1100 | suffix that builds for the build host. | ||
| 1101 | |||
| 1102 | .. note:: | ||
| 1103 | |||
| 1104 | If you need to add a tool that is shipped as part of a source tree | ||
| 1105 | that builds code for the target, you can typically accomplish this by | ||
| 1106 | building the native and target parts separately rather than within | ||
| 1107 | the same compilation process. Realize though that with the | ||
| 1108 | "--also-native" option, you can add the tool using just one | ||
| 1109 | recipe file. | ||
| 1110 | |||
| 1111 | Adding Node.js Modules | ||
| 1112 | ---------------------- | ||
| 1113 | |||
| 1114 | You can use the ``devtool add`` command two different ways to add | ||
| 1115 | Node.js modules: through ``npm`` or from a repository or local source. | ||
| 1116 | |||
| 1117 | Use the following form to add Node.js modules through ``npm``:: | ||
| 1118 | |||
| 1119 | $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" | ||
| 1120 | |||
| 1121 | The name and | ||
| 1122 | version parameters are mandatory. Lockdown and shrinkwrap files are | ||
| 1123 | generated and pointed to by the recipe in order to freeze the version | ||
| 1124 | that is fetched for the dependencies according to the first time. This | ||
| 1125 | also saves checksums that are verified on future fetches. Together, | ||
| 1126 | these behaviors ensure the reproducibility and integrity of the build. | ||
| 1127 | |||
| 1128 | .. note:: | ||
| 1129 | |||
| 1130 | - You must use quotes around the URL. ``devtool add`` does not | ||
| 1131 | require the quotes, but the shell considers ";" as a splitter | ||
| 1132 | between multiple commands. Thus, without the quotes, | ||
| 1133 | ``devtool add`` does not receive the other parts, which results in | ||
| 1134 | several "command not found" errors. | ||
| 1135 | |||
| 1136 | As mentioned earlier, you can also add Node.js modules directly from a | ||
| 1137 | repository or local source tree. To add modules this way, use | ||
| 1138 | ``devtool add`` in the following form:: | ||
| 1139 | |||
| 1140 | $ devtool add https://github.com/diversario/node-ssdp | ||
| 1141 | |||
| 1142 | In this example, ``devtool`` fetches the specified Git repository, detects the | ||
| 1143 | code as Node.js code, fetches dependencies using ``npm``, and sets | ||
| 1144 | :term:`SRC_URI` accordingly. | ||
| 1145 | |||
| 1146 | Working With Recipes | ||
| 1147 | ==================== | ||
| 1148 | |||
| 1149 | When building a recipe using the ``devtool build`` command, the typical | ||
| 1150 | build progresses as follows: | ||
| 1151 | |||
| 1152 | #. Fetch the source | ||
| 1153 | |||
| 1154 | #. Unpack the source | ||
| 1155 | |||
| 1156 | #. Configure the source | ||
| 1157 | |||
| 1158 | #. Compile the source | ||
| 1159 | |||
| 1160 | #. Install the build output | ||
| 1161 | |||
| 1162 | #. Package the installed output | ||
| 1163 | |||
| 1164 | For recipes in the workspace, fetching and unpacking is disabled as the | ||
| 1165 | source tree has already been prepared and is persistent. Each of these | ||
| 1166 | build steps is defined as a function (task), usually with a "do\_" prefix | ||
| 1167 | (e.g. :ref:`ref-tasks-fetch`, | ||
| 1168 | :ref:`ref-tasks-unpack`, and so | ||
| 1169 | forth). These functions are typically shell scripts but can instead be | ||
| 1170 | written in Python. | ||
| 1171 | |||
| 1172 | If you look at the contents of a recipe, you will see that the recipe | ||
| 1173 | does not include complete instructions for building the software. | ||
| 1174 | Instead, common functionality is encapsulated in classes inherited with | ||
| 1175 | the ``inherit`` directive. This technique leaves the recipe to describe | ||
| 1176 | just the things that are specific to the software being built. There is | ||
| 1177 | a :ref:`ref-classes-base` class that is implicitly inherited by all recipes | ||
| 1178 | and provides the functionality that most recipes typically need. | ||
| 1179 | |||
| 1180 | The remainder of this section presents information useful when working | ||
| 1181 | with recipes. | ||
| 1182 | |||
| 1183 | Finding Logs and Work Files | ||
| 1184 | --------------------------- | ||
| 1185 | |||
| 1186 | After the first run of the ``devtool build`` command, recipes that were | ||
| 1187 | previously created using the ``devtool add`` command or whose sources | ||
| 1188 | were modified using the ``devtool modify`` command contain symbolic | ||
| 1189 | links created within the source tree: | ||
| 1190 | |||
| 1191 | - ``oe-logs``: This link points to the directory in which log files and | ||
| 1192 | run scripts for each build step are created. | ||
| 1193 | |||
| 1194 | - ``oe-workdir``: This link points to the temporary work area for the | ||
| 1195 | recipe. The following locations under ``oe-workdir`` are particularly | ||
| 1196 | useful: | ||
| 1197 | |||
| 1198 | - ``image/``: Contains all of the files installed during the | ||
| 1199 | :ref:`ref-tasks-install` stage. | ||
| 1200 | Within a recipe, this directory is referred to by the expression | ||
| 1201 | ``${``\ :term:`D`\ ``}``. | ||
| 1202 | |||
| 1203 | - ``sysroot-destdir/``: Contains a subset of files installed within | ||
| 1204 | :ref:`ref-tasks-install` that have been put into the shared sysroot. For | ||
| 1205 | more information, see the | ||
| 1206 | ":ref:`dev-manual/new-recipe:sharing files between recipes`" section. | ||
| 1207 | |||
| 1208 | - ``packages-split/``: Contains subdirectories for each package | ||
| 1209 | produced by the recipe. For more information, see the | ||
| 1210 | ":ref:`dev-manual/devtool:packaging`" section. | ||
| 1211 | |||
| 1212 | You can use these links to get more information on what is happening at | ||
| 1213 | each build step. | ||
| 1214 | |||
| 1215 | Setting Configure Arguments | ||
| 1216 | --------------------------- | ||
| 1217 | |||
| 1218 | If the software your recipe is building uses GNU autoconf, then a fixed | ||
| 1219 | set of arguments is passed to it to enable cross-compilation plus any | ||
| 1220 | extras specified by :term:`EXTRA_OECONF` or :term:`PACKAGECONFIG_CONFARGS` | ||
| 1221 | set within the recipe. If you wish to pass additional options, add them | ||
| 1222 | to :term:`EXTRA_OECONF` or :term:`PACKAGECONFIG_CONFARGS`. Other supported build | ||
| 1223 | tools have similar variables (e.g. :term:`EXTRA_OECMAKE` for CMake, | ||
| 1224 | :term:`EXTRA_OESCONS` for Scons, and so forth). If you need to pass anything on | ||
| 1225 | the ``make`` command line, you can use :term:`EXTRA_OEMAKE` or the | ||
| 1226 | :term:`PACKAGECONFIG_CONFARGS` variables to do so. | ||
| 1227 | |||
| 1228 | You can use the ``devtool configure-help`` command to help you set the | ||
| 1229 | arguments listed in the previous paragraph. The command determines the | ||
| 1230 | exact options being passed, and shows them to you along with any custom | ||
| 1231 | arguments specified through :term:`EXTRA_OECONF` or | ||
| 1232 | :term:`PACKAGECONFIG_CONFARGS`. If applicable, the command also shows you | ||
| 1233 | the output of the configure script's "--help" option as a | ||
| 1234 | reference. | ||
| 1235 | |||
| 1236 | Sharing Files Between Recipes | ||
| 1237 | ----------------------------- | ||
| 1238 | |||
| 1239 | Recipes often need to use files provided by other recipes on the | ||
| 1240 | :term:`Build Host`. For example, | ||
| 1241 | an application linking to a common library needs access to the library | ||
| 1242 | itself and its associated headers. The way this access is accomplished | ||
| 1243 | is through the :term:`Sysroot`. There is a sysroot for the target machine, and a | ||
| 1244 | sysroot for the build host. | ||
| 1245 | |||
| 1246 | Recipes should never write files directly into the sysroot. Instead, | ||
| 1247 | files should be installed into standard locations during the | ||
| 1248 | :ref:`ref-tasks-install` task within the ``${``\ :term:`D`\ ``}`` directory. A | ||
| 1249 | subset of these files automatically goes into the sysroot. The reason | ||
| 1250 | for this limitation is that almost all files that go into the sysroot | ||
| 1251 | are cataloged in manifests in order to ensure they can be removed later | ||
| 1252 | when a recipe is modified or removed. Thus, the sysroot is able to | ||
| 1253 | remain free from stale files. | ||
| 1254 | |||
| 1255 | Packaging | ||
| 1256 | --------- | ||
| 1257 | |||
| 1258 | If you examine how build output gets into the final image on | ||
| 1259 | the target device, it is important to understand packaging because the | ||
| 1260 | contents of the image are expressed in terms of packages and not | ||
| 1261 | recipes. | ||
| 1262 | |||
| 1263 | During the :ref:`ref-tasks-package` task, files installed during the | ||
| 1264 | :ref:`ref-tasks-install` task are split into one main package, which is almost | ||
| 1265 | always named the same as the recipe, and into several other packages. This | ||
| 1266 | separation exists because not all of those installed files are useful in every | ||
| 1267 | image. For example, you probably do not need any of the documentation installed | ||
| 1268 | in a production image. Consequently, for each recipe the documentation | ||
| 1269 | files are separated into a ``-doc`` package. Recipes that package | ||
| 1270 | software containing optional modules or plugins might undergo additional | ||
| 1271 | package splitting as well. | ||
| 1272 | |||
| 1273 | After building a recipe, you can see where files have gone by looking in | ||
| 1274 | the ``oe-workdir/packages-split`` directory, which contains a | ||
| 1275 | subdirectory for each package. Apart from some advanced cases, the | ||
| 1276 | :term:`PACKAGES` and :term:`FILES` variables controls | ||
| 1277 | splitting. The :term:`PACKAGES` variable lists all of the packages to be | ||
| 1278 | produced, while the :term:`FILES` variable specifies which files to include | ||
| 1279 | in each package by using an override to specify the package. For | ||
| 1280 | example, ``FILES:${PN}`` specifies the files to go into the main package | ||
| 1281 | (i.e. the main package has the same name as the recipe and | ||
| 1282 | ``${``\ :term:`PN`\ ``}`` evaluates to the | ||
| 1283 | recipe name). The order of the :term:`PACKAGES` value is significant. For | ||
| 1284 | each installed file, the first package whose :term:`FILES` value matches the | ||
| 1285 | file is the package into which the file goes. Both the :term:`PACKAGES` and | ||
| 1286 | :term:`FILES` variables have default values. Consequently, you might find | ||
| 1287 | you do not even need to set these variables in your recipe unless the | ||
| 1288 | software the recipe is building installs files into non-standard | ||
| 1289 | locations. | ||
| 1290 | |||
| 1291 | Restoring the Target Device to its Original State | ||
| 1292 | ================================================= | ||
| 1293 | |||
| 1294 | If you use the ``devtool deploy-target`` command to write a recipe's | ||
| 1295 | build output to the target, and you are working on an existing component | ||
| 1296 | of the system, then you might find yourself in a situation where you | ||
| 1297 | need to restore the original files that existed prior to running the | ||
| 1298 | ``devtool deploy-target`` command. Because the ``devtool deploy-target`` | ||
| 1299 | command backs up any files it overwrites, you can use the | ||
| 1300 | ``devtool undeploy-target`` command to restore those files and remove | ||
| 1301 | any other files the recipe deployed. Consider the following example:: | ||
| 1302 | |||
| 1303 | $ devtool undeploy-target lighttpd root@192.168.7.2 | ||
| 1304 | |||
| 1305 | If you have deployed | ||
| 1306 | multiple applications, you can remove them all using the "-a" option | ||
| 1307 | thus restoring the target device to its original state:: | ||
| 1308 | |||
| 1309 | $ devtool undeploy-target -a root@192.168.7.2 | ||
| 1310 | |||
| 1311 | Information about files deployed to | ||
| 1312 | the target as well as any backed up files are stored on the target | ||
| 1313 | itself. This storage, of course, requires some additional space on the | ||
| 1314 | target machine. | ||
| 1315 | |||
| 1316 | .. note:: | ||
| 1317 | |||
| 1318 | The ``devtool deploy-target`` and ``devtool undeploy-target`` commands do | ||
| 1319 | not currently interact with any package management system on the target | ||
| 1320 | device (e.g. RPM or OPKG). Consequently, you should not intermingle | ||
| 1321 | ``devtool deploy-target`` and package manager operations on the target | ||
| 1322 | device. Doing so could result in a conflicting set of files. | ||