diff options
Diffstat (limited to 'documentation/sdk-manual/extensible.rst')
-rw-r--r-- | documentation/sdk-manual/extensible.rst | 870 |
1 files changed, 571 insertions, 299 deletions
diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst index 5962e9460a..3f6a754d88 100644 --- a/documentation/sdk-manual/extensible.rst +++ b/documentation/sdk-manual/extensible.rst | |||
@@ -15,14 +15,14 @@ hardware, and ease integration into the rest of the | |||
15 | .. note:: | 15 | .. note:: |
16 | 16 | ||
17 | For a side-by-side comparison of main features supported for an | 17 | For a side-by-side comparison of main features supported for an |
18 | extensible SDK as compared to a standard SDK, see the " | 18 | extensible SDK as compared to a standard SDK, see the |
19 | Introduction | 19 | :ref:`sdk-manual/intro:introduction` section. |
20 | " section. | ||
21 | 20 | ||
22 | In addition to the functionality available through ``devtool``, you can | 21 | In addition to the functionality available through ``devtool``, you can |
23 | alternatively make use of the toolchain directly, for example from | 22 | alternatively make use of the toolchain directly, for example from |
24 | Makefile and Autotools. See the "`Using the SDK Toolchain | 23 | Makefile and Autotools. See the |
25 | Directly <#sdk-working-projects>`__" chapter for more information. | 24 | ":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter |
25 | for more information. | ||
26 | 26 | ||
27 | Why use the Extensible SDK and What is in It? | 27 | Why use the Extensible SDK and What is in It? |
28 | ============================================= | 28 | ============================================= |
@@ -41,6 +41,46 @@ functionality. | |||
41 | Installing the Extensible SDK | 41 | Installing the Extensible SDK |
42 | ============================= | 42 | ============================= |
43 | 43 | ||
44 | Two ways to install the Extensible SDK | ||
45 | -------------------------------------- | ||
46 | |||
47 | Extensible SDK can be installed in two different ways, and both have | ||
48 | their own pros and cons: | ||
49 | |||
50 | #. *Setting up the Extensible SDK environment directly in a Yocto build*. This | ||
51 | avoids having to produce, test, distribute and maintain separate SDK | ||
52 | installer archives, which can get very large. There is only one environment | ||
53 | for the regular Yocto build and the SDK and less code paths where things can | ||
54 | go not according to plan. It's easier to update the SDK: it simply means | ||
55 | updating the Yocto layers with git fetch or layer management tooling. The | ||
56 | SDK extensibility is better than in the second option: just run ``bitbake`` | ||
57 | again to add more things to the sysroot, or add layers if even more things | ||
58 | are required. | ||
59 | |||
60 | #. *Setting up the Extensible SDK from a standalone installer*. This has the | ||
61 | benefit of having a single, self-contained archive that includes all the | ||
62 | needed binary artifacts. So nothing needs to be rebuilt, and there is no | ||
63 | need to provide a well-functioning binary artefact cache over the network | ||
64 | for developers with underpowered laptops. | ||
65 | |||
66 | .. _setting_up_ext_sdk_in_build: | ||
67 | |||
68 | Setting up the Extensible SDK environment directly in a Yocto build | ||
69 | ------------------------------------------------------------------- | ||
70 | |||
71 | #. Set up all the needed layers and a Yocto :term:`Build Directory`, e.g. a regular Yocto | ||
72 | build where ``bitbake`` can be executed. | ||
73 | |||
74 | #. Run:: | ||
75 | |||
76 | $ bitbake meta-ide-support | ||
77 | $ bitbake -c populate_sysroot gtk+3 | ||
78 | # or any other target or native item that the application developer would need | ||
79 | $ bitbake build-sysroots -c build_native_sysroot && bitbake build-sysroots -c build_target_sysroot | ||
80 | |||
81 | Setting up the Extensible SDK from a standalone installer | ||
82 | --------------------------------------------------------- | ||
83 | |||
44 | The first thing you need to do is install the SDK on your :term:`Build | 84 | The first thing you need to do is install the SDK on your :term:`Build |
45 | Host` by running the ``*.sh`` installation script. | 85 | Host` by running the ``*.sh`` installation script. |
46 | 86 | ||
@@ -58,8 +98,7 @@ The names of the tarball installer scripts are such that a string | |||
58 | representing the host system appears first in the filename and then is | 98 | representing the host system appears first in the filename and then is |
59 | immediately followed by a string representing the target architecture. | 99 | immediately followed by a string representing the target architecture. |
60 | An extensible SDK has the string "-ext" as part of the name. Following | 100 | An extensible SDK has the string "-ext" as part of the name. Following |
61 | is the general form: | 101 | is the general form:: |
62 | :: | ||
63 | 102 | ||
64 | poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh | 103 | poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh |
65 | 104 | ||
@@ -82,17 +121,16 @@ is the general form: | |||
82 | 121 | ||
83 | For example, the following SDK installer is for a 64-bit | 122 | For example, the following SDK installer is for a 64-bit |
84 | development host system and a i586-tuned target architecture based off | 123 | development host system and a i586-tuned target architecture based off |
85 | the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot: | 124 | the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot:: |
86 | :: | ||
87 | 125 | ||
88 | poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh | 126 | poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh |
89 | 127 | ||
90 | .. note:: | 128 | .. note:: |
91 | 129 | ||
92 | As an alternative to downloading an SDK, you can build the SDK | 130 | As an alternative to downloading an SDK, you can build the SDK |
93 | installer. For information on building the installer, see the " | 131 | installer. For information on building the installer, see the |
94 | Building an SDK Installer | 132 | :ref:`sdk-manual/appendix-obtain:building an sdk installer` |
95 | " section. | 133 | section. |
96 | 134 | ||
97 | The SDK and toolchains are self-contained and by default are installed | 135 | The SDK and toolchains are self-contained and by default are installed |
98 | into the ``poky_sdk`` folder in your home directory. You can choose to | 136 | into the ``poky_sdk`` folder in your home directory. You can choose to |
@@ -104,21 +142,12 @@ must be writable for whichever users need to use the SDK. | |||
104 | The following command shows how to run the installer given a toolchain | 142 | The following command shows how to run the installer given a toolchain |
105 | tarball for a 64-bit x86 development host system and a 64-bit x86 target | 143 | tarball for a 64-bit x86 development host system and a 64-bit x86 target |
106 | architecture. The example assumes the SDK installer is located in | 144 | architecture. The example assumes the SDK installer is located in |
107 | ``~/Downloads/`` and has execution rights. | 145 | ``~/Downloads/`` and has execution rights:: |
108 | |||
109 | .. note:: | ||
110 | |||
111 | If you do not have write permissions for the directory into which you | ||
112 | are installing the SDK, the installer notifies you and exits. For | ||
113 | that case, set up the proper permissions in the directory and run the | ||
114 | installer again. | ||
115 | |||
116 | :: | ||
117 | 146 | ||
118 | $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh | 147 | $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh |
119 | Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5 | 148 | Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5 |
120 | ========================================================================== | 149 | ========================================================================== |
121 | Enter target directory for SDK (default: ~/poky_sdk): | 150 | Enter target directory for SDK (default: poky_sdk): |
122 | You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y | 151 | You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y |
123 | Extracting SDK..............done | 152 | Extracting SDK..............done |
124 | Setting it up... | 153 | Setting it up... |
@@ -134,11 +163,25 @@ architecture. The example assumes the SDK installer is located in | |||
134 | Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. | 163 | Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. |
135 | $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux | 164 | $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux |
136 | 165 | ||
166 | .. note:: | ||
167 | |||
168 | If you do not have write permissions for the directory into which you | ||
169 | are installing the SDK, the installer notifies you and exits. For | ||
170 | that case, set up the proper permissions in the directory and run the | ||
171 | installer again. | ||
172 | |||
173 | .. _running_the_ext_sdk_env: | ||
174 | |||
137 | Running the Extensible SDK Environment Setup Script | 175 | Running the Extensible SDK Environment Setup Script |
138 | =================================================== | 176 | =================================================== |
139 | 177 | ||
140 | Once you have the SDK installed, you must run the SDK environment setup | 178 | Once you have the SDK installed, you must run the SDK environment setup |
141 | script before you can actually use the SDK. This setup script resides in | 179 | script before you can actually use the SDK. |
180 | |||
181 | When using a SDK directly in a Yocto build, you will find the script in | ||
182 | ``tmp/deploy/images/qemux86-64/`` in your :term:`Build Directory`. | ||
183 | |||
184 | When using a standalone SDK installer, this setup script resides in | ||
142 | the directory you chose when you installed the SDK, which is either the | 185 | the directory you chose when you installed the SDK, which is either the |
143 | default ``poky_sdk`` directory or the directory you chose during | 186 | default ``poky_sdk`` directory or the directory you chose during |
144 | installation. | 187 | installation. |
@@ -149,21 +192,25 @@ begin with the string "``environment-setup``" and include as part of | |||
149 | their name the tuned target architecture. As an example, the following | 192 | their name the tuned target architecture. As an example, the following |
150 | commands set the working directory to where the SDK was installed and | 193 | commands set the working directory to where the SDK was installed and |
151 | then source the environment setup script. In this example, the setup | 194 | then source the environment setup script. In this example, the setup |
152 | script is for an IA-based target machine using i586 tuning: | 195 | script is for an IA-based target machine using i586 tuning:: |
153 | :: | ||
154 | 196 | ||
155 | $ cd /home/scottrif/poky_sdk | 197 | $ cd /home/scottrif/poky_sdk |
156 | $ source environment-setup-core2-64-poky-linux | 198 | $ source environment-setup-core2-64-poky-linux |
157 | SDK environment now set up; additionally you may now run devtool to perform development tasks. | 199 | SDK environment now set up; additionally you may now run devtool to perform development tasks. |
158 | Run devtool --help for further details. | 200 | Run devtool --help for further details. |
159 | 201 | ||
160 | Running the setup script defines many environment variables needed in | 202 | When using the environment script directly in a Yocto build, it can |
161 | order to use the SDK (e.g. ``PATH``, | 203 | be run similarly:: |
162 | :term:`CC`, | 204 | |
163 | :term:`LD`, and so forth). If you want to | 205 | $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux |
164 | see all the environment variables the script exports, examine the | 206 | |
207 | Running the setup script defines many environment variables needed in order to | ||
208 | use the SDK (e.g. ``PATH``, :term:`CC`, :term:`LD`, and so forth). If you want | ||
209 | to see all the environment variables the script exports, examine the | ||
165 | installation file itself. | 210 | installation file itself. |
166 | 211 | ||
212 | .. _using_devtool: | ||
213 | |||
167 | Using ``devtool`` in Your SDK Workflow | 214 | Using ``devtool`` in Your SDK Workflow |
168 | ====================================== | 215 | ====================================== |
169 | 216 | ||
@@ -175,11 +222,8 @@ system. | |||
175 | 222 | ||
176 | .. note:: | 223 | .. note:: |
177 | 224 | ||
178 | The use of | 225 | The use of ``devtool`` is not limited to the extensible SDK. You can use |
179 | devtool | 226 | ``devtool`` to help you easily develop any project whose build output must be |
180 | is not limited to the extensible SDK. You can use | ||
181 | devtool | ||
182 | to help you easily develop any project whose build output must be | ||
183 | part of an image built using the build system. | 227 | part of an image built using the build system. |
184 | 228 | ||
185 | The ``devtool`` command line is organized similarly to | 229 | The ``devtool`` command line is organized similarly to |
@@ -189,21 +233,18 @@ all the commands. | |||
189 | 233 | ||
190 | .. note:: | 234 | .. note:: |
191 | 235 | ||
192 | See the " | 236 | See the ":doc:`/ref-manual/devtool-reference`" |
193 | devtool | 237 | section in the Yocto Project Reference Manual. |
194 | Â Quick Reference | ||
195 | " in the Yocto Project Reference Manual for a | ||
196 | devtool | ||
197 | quick reference. | ||
198 | 238 | ||
199 | Three ``devtool`` subcommands exist that provide entry-points into | 239 | ``devtool`` subcommands provide entry-points into development: |
200 | development: | ||
201 | 240 | ||
202 | - *devtool add*: Assists in adding new software to be built. | 241 | - *devtool add*: Assists in adding new software to be built. |
203 | 242 | ||
204 | - *devtool modify*: Sets up an environment to enable you to modify | 243 | - *devtool modify*: Sets up an environment to enable you to modify |
205 | the source of an existing component. | 244 | the source of an existing component. |
206 | 245 | ||
246 | - *devtool ide-sdk*: Generates a configuration for an IDE. | ||
247 | |||
207 | - *devtool upgrade*: Updates an existing recipe so that you can | 248 | - *devtool upgrade*: Updates an existing recipe so that you can |
208 | build it for an updated set of source files. | 249 | build it for an updated set of source files. |
209 | 250 | ||
@@ -236,9 +277,9 @@ shows common development flows you would use with the ``devtool add`` | |||
236 | command: | 277 | command: |
237 | 278 | ||
238 | .. image:: figures/sdk-devtool-add-flow.png | 279 | .. image:: figures/sdk-devtool-add-flow.png |
239 | :align: center | 280 | :width: 100% |
240 | 281 | ||
241 | 1. *Generating the New Recipe*: The top part of the flow shows three | 282 | #. *Generating the New Recipe*: The top part of the flow shows three |
242 | scenarios by which you could use ``devtool add`` to generate a recipe | 283 | scenarios by which you could use ``devtool add`` to generate a recipe |
243 | based on existing source code. | 284 | based on existing source code. |
244 | 285 | ||
@@ -255,10 +296,9 @@ command: | |||
255 | - *Left*: The left scenario in the figure represents a common | 296 | - *Left*: The left scenario in the figure represents a common |
256 | situation where the source code does not exist locally and needs | 297 | situation where the source code does not exist locally and needs |
257 | to be extracted. In this situation, the source code is extracted | 298 | to be extracted. In this situation, the source code is extracted |
258 | to the default workspace - you do not want the files in some | 299 | to the default workspace --- you do not want the files in some |
259 | specific location outside of the workspace. Thus, everything you | 300 | specific location outside of the workspace. Thus, everything you |
260 | need will be located in the workspace: | 301 | need will be located in the workspace:: |
261 | :: | ||
262 | 302 | ||
263 | $ devtool add recipe fetchuri | 303 | $ devtool add recipe fetchuri |
264 | 304 | ||
@@ -271,36 +311,32 @@ command: | |||
271 | - *Middle*: The middle scenario in the figure also represents a | 311 | - *Middle*: The middle scenario in the figure also represents a |
272 | situation where the source code does not exist locally. In this | 312 | situation where the source code does not exist locally. In this |
273 | case, the code is again upstream and needs to be extracted to some | 313 | case, the code is again upstream and needs to be extracted to some |
274 | local area - this time outside of the default workspace. | 314 | local area --- this time outside of the default workspace. |
275 | 315 | ||
276 | .. note:: | 316 | .. note:: |
277 | 317 | ||
278 | If required, | 318 | If required, ``devtool`` always creates a Git repository locally |
279 | devtool | 319 | during the extraction. |
280 | always creates a Git repository locally during the extraction. | ||
281 | 320 | ||
282 | Furthermore, the first positional argument srctree in this case | 321 | Furthermore, the first positional argument ``srctree`` in this case |
283 | identifies where the ``devtool add`` command will locate the | 322 | identifies where the ``devtool add`` command will locate the |
284 | extracted code outside of the workspace. You need to specify an | 323 | extracted code outside of the workspace. You need to specify an |
285 | empty directory: | 324 | empty directory:: |
286 | :: | ||
287 | 325 | ||
288 | $ devtool add recipe srctree fetchuri | 326 | $ devtool add recipe srctree fetchuri |
289 | 327 | ||
290 | In summary, | 328 | In summary, the source code is pulled from fetchuri and extracted into the |
291 | the source code is pulled from fetchuri and extracted into the | 329 | location defined by ``srctree`` as a local Git repository. |
292 | location defined by srctree as a local Git repository. | ||
293 | 330 | ||
294 | Within workspace, ``devtool`` creates a recipe named recipe along | 331 | Within workspace, ``devtool`` creates a recipe named recipe along |
295 | with an associated append file. | 332 | with an associated append file. |
296 | 333 | ||
297 | - *Right*: The right scenario in the figure represents a situation | 334 | - *Right*: The right scenario in the figure represents a situation |
298 | where the srctree has been previously prepared outside of the | 335 | where the ``srctree`` has been previously prepared outside of the |
299 | ``devtool`` workspace. | 336 | ``devtool`` workspace. |
300 | 337 | ||
301 | The following command provides a new recipe name and identifies | 338 | The following command provides a new recipe name and identifies |
302 | the existing source tree location: | 339 | the existing source tree location:: |
303 | :: | ||
304 | 340 | ||
305 | $ devtool add recipe srctree | 341 | $ devtool add recipe srctree |
306 | 342 | ||
@@ -308,41 +344,37 @@ command: | |||
308 | recipe for the code and places the recipe into the workspace. | 344 | recipe for the code and places the recipe into the workspace. |
309 | 345 | ||
310 | Because the extracted source code already exists, ``devtool`` does | 346 | Because the extracted source code already exists, ``devtool`` does |
311 | not try to relocate the source code into the workspace - only the | 347 | not try to relocate the source code into the workspace --- only the |
312 | new recipe is placed in the workspace. | 348 | new recipe is placed in the workspace. |
313 | 349 | ||
314 | Aside from a recipe folder, the command also creates an associated | 350 | Aside from a recipe folder, the command also creates an associated |
315 | append folder and places an initial ``*.bbappend`` file within. | 351 | append folder and places an initial ``*.bbappend`` file within. |
316 | 352 | ||
317 | 2. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the | 353 | #. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the |
318 | editor as defined by the ``$EDITOR`` environment variable and modify | 354 | editor as defined by the ``$EDITOR`` environment variable and modify |
319 | the file: | 355 | the file:: |
320 | :: | ||
321 | 356 | ||
322 | $ devtool edit-recipe recipe | 357 | $ devtool edit-recipe recipe |
323 | 358 | ||
324 | From within the editor, you | 359 | From within the editor, you can make modifications to the recipe that |
325 | can make modifications to the recipe that take affect when you build | 360 | take effect when you build it later. |
326 | it later. | ||
327 | 361 | ||
328 | 3. *Build the Recipe or Rebuild the Image*: The next step you take | 362 | #. *Build the Recipe or Rebuild the Image*: The next step you take |
329 | depends on what you are going to do with the new code. | 363 | depends on what you are going to do with the new code. |
330 | 364 | ||
331 | If you need to eventually move the build output to the target | 365 | If you need to eventually move the build output to the target |
332 | hardware, use the following ``devtool`` command: | 366 | hardware, use the following ``devtool`` command:: |
333 | :; | ||
334 | 367 | ||
335 | $ devtool build recipe | 368 | $ devtool build recipe |
336 | 369 | ||
337 | On the other hand, if you want an image to contain the recipe's | 370 | On the other hand, if you want an image to contain the recipe's |
338 | packages from the workspace for immediate deployment onto a device | 371 | packages from the workspace for immediate deployment onto a device |
339 | (e.g. for testing purposes), you can use the ``devtool build-image`` | 372 | (e.g. for testing purposes), you can use the ``devtool build-image`` |
340 | command: | 373 | command:: |
341 | :: | ||
342 | 374 | ||
343 | $ devtool build-image image | 375 | $ devtool build-image image |
344 | 376 | ||
345 | 4. *Deploy the Build Output*: When you use the ``devtool build`` command | 377 | #. *Deploy the Build Output*: When you use the ``devtool build`` command |
346 | to build out your recipe, you probably want to see if the resulting | 378 | to build out your recipe, you probably want to see if the resulting |
347 | build output works as expected on the target hardware. | 379 | build output works as expected on the target hardware. |
348 | 380 | ||
@@ -356,20 +388,22 @@ command: | |||
356 | development machine. | 388 | development machine. |
357 | 389 | ||
358 | You can deploy your build output to that target hardware by using the | 390 | You can deploy your build output to that target hardware by using the |
359 | ``devtool deploy-target`` command: $ devtool deploy-target recipe | 391 | ``devtool deploy-target`` command:: |
360 | target The target is a live target machine running as an SSH server. | 392 | |
393 | $ devtool deploy-target recipe target | ||
394 | |||
395 | The target is a live target machine running as an SSH server. | ||
361 | 396 | ||
362 | You can, of course, also deploy the image you build to actual | 397 | You can, of course, also deploy the image you build to actual |
363 | hardware by using the ``devtool build-image`` command. However, | 398 | hardware by using the ``devtool build-image`` command. However, |
364 | ``devtool`` does not provide a specific command that allows you to | 399 | ``devtool`` does not provide a specific command that allows you to |
365 | deploy the image to actual hardware. | 400 | deploy the image to actual hardware. |
366 | 401 | ||
367 | 5. *Finish Your Work With the Recipe*: The ``devtool finish`` command | 402 | #. *Finish Your Work With the Recipe*: The ``devtool finish`` command |
368 | creates any patches corresponding to commits in the local Git | 403 | creates any patches corresponding to commits in the local Git |
369 | repository, moves the new recipe to a more permanent layer, and then | 404 | repository, moves the new recipe to a more permanent layer, and then |
370 | resets the recipe so that the recipe is built normally rather than | 405 | resets the recipe so that the recipe is built normally rather than |
371 | from the workspace. | 406 | from the workspace:: |
372 | :: | ||
373 | 407 | ||
374 | $ devtool finish recipe layer | 408 | $ devtool finish recipe layer |
375 | 409 | ||
@@ -387,11 +421,9 @@ command: | |||
387 | 421 | ||
388 | .. note:: | 422 | .. note:: |
389 | 423 | ||
390 | You can use the | 424 | You can use the ``devtool reset`` command to put things back should you |
391 | devtool reset | 425 | decide you do not want to proceed with your work. If you do use this |
392 | command to put things back should you decide you do not want to | 426 | command, realize that the source tree is preserved. |
393 | proceed with your work. If you do use this command, realize that | ||
394 | the source tree is preserved. | ||
395 | 427 | ||
396 | Use ``devtool modify`` to Modify the Source of an Existing Component | 428 | Use ``devtool modify`` to Modify the Source of an Existing Component |
397 | -------------------------------------------------------------------- | 429 | -------------------------------------------------------------------- |
@@ -409,9 +441,9 @@ diagram shows common development flows for the ``devtool modify`` | |||
409 | command: | 441 | command: |
410 | 442 | ||
411 | .. image:: figures/sdk-devtool-modify-flow.png | 443 | .. image:: figures/sdk-devtool-modify-flow.png |
412 | :align: center | 444 | :width: 100% |
413 | 445 | ||
414 | 1. *Preparing to Modify the Code*: The top part of the flow shows three | 446 | #. *Preparing to Modify the Code*: The top part of the flow shows three |
415 | scenarios by which you could use ``devtool modify`` to prepare to | 447 | scenarios by which you could use ``devtool modify`` to prepare to |
416 | work on source files. Each scenario assumes the following: | 448 | work on source files. Each scenario assumes the following: |
417 | 449 | ||
@@ -434,20 +466,17 @@ command: | |||
434 | outside the workspace (i.e. ``meta-``\ layername). | 466 | outside the workspace (i.e. ``meta-``\ layername). |
435 | 467 | ||
436 | The following command identifies the recipe and, by default, | 468 | The following command identifies the recipe and, by default, |
437 | extracts the source files: | 469 | extracts the source files:: |
438 | :: | ||
439 | 470 | ||
440 | $ devtool modify recipe | 471 | $ devtool modify recipe |
441 | 472 | ||
442 | Once | 473 | Once ``devtool`` locates the recipe, ``devtool`` uses the recipe's |
443 | ``devtool``\ locates the recipe, ``devtool`` uses the recipe's | 474 | :term:`SRC_URI` statements to locate the source code and any local |
444 | :term:`SRC_URI` statements to | 475 | patch files from other developers. |
445 | locate the source code and any local patch files from other | ||
446 | developers. | ||
447 | 476 | ||
448 | With this scenario, no srctree argument exists. Consequently, the | 477 | With this scenario, there is no ``srctree`` argument. Consequently, the |
449 | default behavior of the ``devtool modify`` command is to extract | 478 | default behavior of the ``devtool modify`` command is to extract |
450 | the source files pointed to by the ``SRC_URI`` statements into a | 479 | the source files pointed to by the :term:`SRC_URI` statements into a |
451 | local Git structure. Furthermore, the location for the extracted | 480 | local Git structure. Furthermore, the location for the extracted |
452 | source is the default area within the ``devtool`` workspace. The | 481 | source is the default area within the ``devtool`` workspace. The |
453 | result is that the command sets up both the source code and an | 482 | result is that the command sets up both the source code and an |
@@ -455,7 +484,7 @@ command: | |||
455 | original location. | 484 | original location. |
456 | 485 | ||
457 | Additionally, if you have any non-patch local files (i.e. files | 486 | Additionally, if you have any non-patch local files (i.e. files |
458 | referred to with ``file://`` entries in ``SRC_URI`` statement | 487 | referred to with ``file://`` entries in :term:`SRC_URI` statement |
459 | excluding ``*.patch/`` or ``*.diff``), these files are copied to | 488 | excluding ``*.patch/`` or ``*.diff``), these files are copied to |
460 | an ``oe-local-files`` folder under the newly created source tree. | 489 | an ``oe-local-files`` folder under the newly created source tree. |
461 | Copying the files here gives you a convenient area from which you | 490 | Copying the files here gives you a convenient area from which you |
@@ -473,42 +502,36 @@ command: | |||
473 | The following command tells ``devtool`` the recipe with which to | 502 | The following command tells ``devtool`` the recipe with which to |
474 | work and, in this case, identifies a local area for the extracted | 503 | work and, in this case, identifies a local area for the extracted |
475 | source files that exists outside of the default ``devtool`` | 504 | source files that exists outside of the default ``devtool`` |
476 | workspace: | 505 | workspace:: |
477 | :: | ||
478 | 506 | ||
479 | $ devtool modify recipe srctree | 507 | $ devtool modify recipe srctree |
480 | 508 | ||
481 | .. note:: | 509 | .. note:: |
482 | 510 | ||
483 | You cannot provide a URL for | 511 | You cannot provide a URL for ``srctree`` using the ``devtool`` command. |
484 | srctree | ||
485 | using the | ||
486 | devtool | ||
487 | command. | ||
488 | 512 | ||
489 | As with all extractions, the command uses the recipe's ``SRC_URI`` | 513 | As with all extractions, the command uses the recipe's :term:`SRC_URI` |
490 | statements to locate the source files and any associated patch | 514 | statements to locate the source files and any associated patch |
491 | files. Non-patch files are copied to an ``oe-local-files`` folder | 515 | files. Non-patch files are copied to an ``oe-local-files`` folder |
492 | under the newly created source tree. | 516 | under the newly created source tree. |
493 | 517 | ||
494 | Once the files are located, the command by default extracts them | 518 | Once the files are located, the command by default extracts them |
495 | into srctree. | 519 | into ``srctree``. |
496 | 520 | ||
497 | Within workspace, ``devtool`` creates an append file for the | 521 | Within workspace, ``devtool`` creates an append file for the |
498 | recipe. The recipe remains in its original location but the source | 522 | recipe. The recipe remains in its original location but the source |
499 | files are extracted to the location you provide with srctree. | 523 | files are extracted to the location you provide with ``srctree``. |
500 | 524 | ||
501 | - *Right*: The right scenario in the figure represents a situation | 525 | - *Right*: The right scenario in the figure represents a situation |
502 | where the source tree (srctree) already exists locally as a | 526 | where the source tree (``srctree``) already exists locally as a |
503 | previously extracted Git structure outside of the ``devtool`` | 527 | previously extracted Git structure outside of the ``devtool`` |
504 | workspace. In this example, the recipe also exists elsewhere | 528 | workspace. In this example, the recipe also exists elsewhere |
505 | locally in its own layer. | 529 | locally in its own layer. |
506 | 530 | ||
507 | The following command tells ``devtool`` the recipe with which to | 531 | The following command tells ``devtool`` the recipe with which to |
508 | work, uses the "-n" option to indicate source does not need to be | 532 | work, uses the "-n" option to indicate source does not need to be |
509 | extracted, and uses srctree to point to the previously extracted | 533 | extracted, and uses ``srctree`` to point to the previously extracted |
510 | source files: | 534 | source files:: |
511 | :: | ||
512 | 535 | ||
513 | $ devtool modify -n recipe srctree | 536 | $ devtool modify -n recipe srctree |
514 | 537 | ||
@@ -523,25 +546,26 @@ command: | |||
523 | append file for the recipe in the ``devtool`` workspace. The | 546 | append file for the recipe in the ``devtool`` workspace. The |
524 | recipe and the source code remain in their original locations. | 547 | recipe and the source code remain in their original locations. |
525 | 548 | ||
526 | 2. *Edit the Source*: Once you have used the ``devtool modify`` command, | 549 | #. *Edit the Source*: Once you have used the ``devtool modify`` command, |
527 | you are free to make changes to the source files. You can use any | 550 | you are free to make changes to the source files. You can use any |
528 | editor you like to make and save your source code modifications. | 551 | editor you like to make and save your source code modifications. |
529 | 552 | ||
530 | 3. *Build the Recipe or Rebuild the Image*: The next step you take | 553 | #. *Build the Recipe or Rebuild the Image*: The next step you take |
531 | depends on what you are going to do with the new code. | 554 | depends on what you are going to do with the new code. |
532 | 555 | ||
533 | If you need to eventually move the build output to the target | 556 | If you need to eventually move the build output to the target |
534 | hardware, use the following ``devtool`` command: | 557 | hardware, use the following ``devtool`` command:: |
535 | :: | ||
536 | 558 | ||
537 | $ devtool build recipe | 559 | $ devtool build recipe |
538 | 560 | ||
539 | On the other hand, if you want an image to contain the recipe's | 561 | On the other hand, if you want an image to contain the recipe's |
540 | packages from the workspace for immediate deployment onto a device | 562 | packages from the workspace for immediate deployment onto a device |
541 | (e.g. for testing purposes), you can use the ``devtool build-image`` | 563 | (e.g. for testing purposes), you can use the ``devtool build-image`` |
542 | command: $ devtool build-image image | 564 | command:: |
543 | 565 | ||
544 | 4. *Deploy the Build Output*: When you use the ``devtool build`` command | 566 | $ devtool build-image image |
567 | |||
568 | #. *Deploy the Build Output*: When you use the ``devtool build`` command | ||
545 | to build out your recipe, you probably want to see if the resulting | 569 | to build out your recipe, you probably want to see if the resulting |
546 | build output works as expected on target hardware. | 570 | build output works as expected on target hardware. |
547 | 571 | ||
@@ -555,8 +579,7 @@ command: | |||
555 | development machine. | 579 | development machine. |
556 | 580 | ||
557 | You can deploy your build output to that target hardware by using the | 581 | You can deploy your build output to that target hardware by using the |
558 | ``devtool deploy-target`` command: | 582 | ``devtool deploy-target`` command:: |
559 | :: | ||
560 | 583 | ||
561 | $ devtool deploy-target recipe target | 584 | $ devtool deploy-target recipe target |
562 | 585 | ||
@@ -567,13 +590,12 @@ command: | |||
567 | ``devtool`` does not provide a specific command to deploy the image | 590 | ``devtool`` does not provide a specific command to deploy the image |
568 | to actual hardware. | 591 | to actual hardware. |
569 | 592 | ||
570 | 5. *Finish Your Work With the Recipe*: The ``devtool finish`` command | 593 | #. *Finish Your Work With the Recipe*: The ``devtool finish`` command |
571 | creates any patches corresponding to commits in the local Git | 594 | creates any patches corresponding to commits in the local Git |
572 | repository, updates the recipe to point to them (or creates a | 595 | repository, updates the recipe to point to them (or creates a |
573 | ``.bbappend`` file to do so, depending on the specified destination | 596 | ``.bbappend`` file to do so, depending on the specified destination |
574 | layer), and then resets the recipe so that the recipe is built | 597 | layer), and then resets the recipe so that the recipe is built |
575 | normally rather than from the workspace. | 598 | normally rather than from the workspace:: |
576 | :: | ||
577 | 599 | ||
578 | $ devtool finish recipe layer | 600 | $ devtool finish recipe layer |
579 | 601 | ||
@@ -581,8 +603,7 @@ command: | |||
581 | 603 | ||
582 | Any changes you want to turn into patches must be staged and | 604 | Any changes you want to turn into patches must be staged and |
583 | committed within the local Git repository before you use the | 605 | committed within the local Git repository before you use the |
584 | devtool finish | 606 | ``devtool finish`` command. |
585 | command. | ||
586 | 607 | ||
587 | Because there is no need to move the recipe, ``devtool finish`` | 608 | Because there is no need to move the recipe, ``devtool finish`` |
588 | either updates the original recipe in the original layer or the | 609 | either updates the original recipe in the original layer or the |
@@ -597,11 +618,282 @@ command: | |||
597 | 618 | ||
598 | .. note:: | 619 | .. note:: |
599 | 620 | ||
600 | You can use the | 621 | You can use the ``devtool reset`` command to put things back should you |
601 | devtool reset | 622 | decide you do not want to proceed with your work. If you do use this |
602 | command to put things back should you decide you do not want to | 623 | command, realize that the source tree is preserved. |
603 | proceed with your work. If you do use this command, realize that | 624 | |
604 | the source tree is preserved. | 625 | ``devtool ide-sdk`` configures IDEs for the extensible SDK |
626 | ---------------------------------------------------------- | ||
627 | |||
628 | ``devtool ide-sdk`` automatically configures IDEs to use the extensible SDK. | ||
629 | To make sure that all parts of the extensible SDK required by the generated | ||
630 | IDE configuration are available, ``devtool ide-sdk`` uses BitBake in the | ||
631 | background to bootstrap the extensible SDK. | ||
632 | |||
633 | The extensible SDK supports two different development modes. | ||
634 | ``devtool ide-sdk`` supports both of them: | ||
635 | |||
636 | #. *Modified mode*: | ||
637 | |||
638 | By default ``devtool ide-sdk`` generates IDE configurations for recipes in | ||
639 | workspaces created by ``devtool modify`` or ``devtool add`` as described in | ||
640 | :ref:`using_devtool`. This mode creates IDE configurations with support for | ||
641 | advanced features, such as deploying the binaries to the remote target | ||
642 | device and performing remote debugging sessions. The generated IDE | ||
643 | configurations use the per recipe sysroots as Bitbake does internally. | ||
644 | |||
645 | In order to use the tool, a few settings are needed. As a starting example, | ||
646 | the following lines of code can be added to the ``local.conf`` file:: | ||
647 | |||
648 | # Build the companion debug file system | ||
649 | IMAGE_GEN_DEBUGFS = "1" | ||
650 | # Optimize build time: with devtool ide-sdk the dbg tar is not needed | ||
651 | IMAGE_FSTYPES_DEBUGFS = "" | ||
652 | # Without copying the binaries into roofs-dbg, GDB does not find all source files. | ||
653 | IMAGE_CLASSES += "image-combined-dbg" | ||
654 | |||
655 | # SSH is mandatory, no password simplifies the usage | ||
656 | EXTRA_IMAGE_FEATURES += "\ | ||
657 | ssh-server-openssh \ | ||
658 | debug-tweaks \ | ||
659 | " | ||
660 | |||
661 | # Remote debugging needs gdbserver on the target device | ||
662 | IMAGE_INSTALL:append = " gdbserver" | ||
663 | |||
664 | # Add the recipes which should be modified to the image | ||
665 | # Otherwise some dependencies might be missing. | ||
666 | IMAGE_INSTALL:append = " my-recipe" | ||
667 | |||
668 | Assuming the BitBake environment is set up correctly and a workspace has | ||
669 | been created for the recipe using ``devtool modify my-recipe``, the | ||
670 | following command can create the SDK and the configuration for VSCode in | ||
671 | the recipe workspace:: | ||
672 | |||
673 | $ devtool ide-sdk my-recipe core-image-minimal --target root@192.168.7.2 | ||
674 | |||
675 | The command requires an image recipe (``core-image-minimal`` for this example) | ||
676 | that is used to create the SDK. This firmware image should also be installed | ||
677 | on the target device. It is possible to pass multiple package recipes. | ||
678 | ``devtool ide-sdk`` tries to create an IDE configuration for all package | ||
679 | recipes. | ||
680 | |||
681 | What this command does exactly depends on the recipe, more precisely on the | ||
682 | build tool used by the recipe. The basic idea is to configure the IDE so | ||
683 | that it calls the build tool exactly as ``bitbake`` does. | ||
684 | |||
685 | For example, a CMake preset is created for a recipe that inherits | ||
686 | :ref:`ref-classes-cmake`. In the case of VSCode, CMake presets are supported | ||
687 | by the CMake Tools plugin. This is an example of how the build | ||
688 | configuration used by ``bitbake`` is exported to an IDE configuration that | ||
689 | gives exactly the same build results. | ||
690 | |||
691 | Support for remote debugging with seamless integration into the IDE is | ||
692 | important for a cross-SDK. ``devtool ide-sdk`` automatically generates the | ||
693 | necessary helper scripts for deploying the compiled artifacts to the target | ||
694 | device as well as the necessary configuration for the debugger and the IDE. | ||
695 | |||
696 | .. note:: | ||
697 | |||
698 | To ensure that the debug symbols on the build machine match the binaries | ||
699 | running on the target device, it is essential that the image built by | ||
700 | ``devtool ide-sdk`` is running on the target device. | ||
701 | |||
702 | ``devtool ide-sdk`` aims to support multiple programming languages and | ||
703 | multiple IDEs natively. "Natively" means that the IDE is configured to call | ||
704 | the build tool (e.g. CMake or Meson) directly. This has several advantages. | ||
705 | First of all, it is much faster than ``devtool build``, but it also allows | ||
706 | to use the very good integration of tools like CMake or GDB in VSCode and | ||
707 | other IDEs. However, supporting many programming languages and multiple | ||
708 | IDEs is quite an elaborate and constantly evolving thing. Support for IDEs | ||
709 | is therefore implemented as plugins. Plugins can also be provided by | ||
710 | optional layers. | ||
711 | |||
712 | The default IDE is VSCode. Some hints about using VSCode: | ||
713 | |||
714 | - To work on the source code of a recipe an instance of VSCode is started in | ||
715 | the recipe's workspace. Example:: | ||
716 | |||
717 | code build/workspace/sources/my-recipe | ||
718 | |||
719 | - To work with CMake press ``Ctrl + Shift + p``, type ``cmake``. This will | ||
720 | show some possible commands like selecting a CMake preset, compiling or | ||
721 | running CTest. | ||
722 | |||
723 | For recipes inheriting :ref:`ref-classes-cmake-qemu` rather than | ||
724 | :ref:`ref-classes-cmake`, executing cross-compiled unit tests on the host | ||
725 | can be supported transparently with QEMU user-mode. | ||
726 | |||
727 | - To work with Meson press ``Ctrl + Shift + p``, type ``meson``. This will | ||
728 | show some possible commands like compiling or executing the unit tests. | ||
729 | |||
730 | A note on running cross-compiled unit tests on the host: Meson enables | ||
731 | support for QEMU user-mode by default. It is expected that the execution | ||
732 | of the unit tests from the IDE will work easily without any additional | ||
733 | steps, provided that the code is suitable for execution on the host | ||
734 | machine. | ||
735 | |||
736 | - For the deployment to the target device, just press ``Ctrl + Shift + p``, | ||
737 | type ``task``. Select ``install && deploy-target``. | ||
738 | |||
739 | - For remote debugging, switch to the debugging view by pressing the "play" | ||
740 | button with the ``bug icon`` on the left side. This will provide a green | ||
741 | play button with a drop-down list where a debug configuration can be | ||
742 | selected. After selecting one of the generated configurations, press the | ||
743 | "play" button. | ||
744 | |||
745 | Starting a remote debugging session automatically initiates the deployment | ||
746 | to the target device. If this is not desired, the | ||
747 | ``"dependsOn": ["install && deploy-target...]`` parameter of the tasks | ||
748 | with ``"label": "gdbserver start...`` can be removed from the | ||
749 | ``tasks.json`` file. | ||
750 | |||
751 | VSCode supports GDB with many different setups and configurations for many | ||
752 | different use cases. However, most of these setups have some limitations | ||
753 | when it comes to cross-development, support only a few target | ||
754 | architectures or require a high performance target device. Therefore | ||
755 | ``devtool ide-sdk`` supports the classic, generic setup with GDB on the | ||
756 | development host and gdbserver on the target device. | ||
757 | |||
758 | Roughly summarized, this means: | ||
759 | |||
760 | - The binaries are copied via SSH to the remote target device by a script | ||
761 | referred by ``tasks.json``. | ||
762 | |||
763 | - gdbserver is started on the remote target device via SSH by a script | ||
764 | referred by ``tasks.json``. | ||
765 | |||
766 | Changing the parameters that are passed to the debugging executable | ||
767 | requires modifying the generated script. The script is located at | ||
768 | ``oe-scripts/gdbserver_*``. Defining the parameters in the ``args`` | ||
769 | field in the ``launch.json`` file does not work. | ||
770 | |||
771 | - VSCode connects to gdbserver as documented in | ||
772 | `Remote debugging or debugging with a local debugger server | ||
773 | <https://code.visualstudio.com/docs/cpp/launch-json-reference#_remote-debugging-or-debugging-with-a-local-debugger-server>`__. | ||
774 | |||
775 | Additionally ``--ide=none`` is supported. With the ``none`` IDE parameter, | ||
776 | some generic configuration files like ``gdbinit`` files and some helper | ||
777 | scripts starting gdbserver remotely on the target device as well as the GDB | ||
778 | client on the host are generated. | ||
779 | |||
780 | Here is a usage example for the ``cmake-example`` recipe from the | ||
781 | ``meta-selftest`` layer which inherits :ref:`ref-classes-cmake-qemu`: | ||
782 | |||
783 | .. code-block:: sh | ||
784 | |||
785 | # Create the SDK | ||
786 | devtool modify cmake-example | ||
787 | devtool ide-sdk cmake-example core-image-minimal -c --debug-build-config --ide=none | ||
788 | |||
789 | # Install the firmware on a target device or start QEMU | ||
790 | runqemu | ||
791 | |||
792 | # From exploring the workspace of cmake-example | ||
793 | cd build/workspace/sources/cmake-example | ||
794 | |||
795 | # Find cmake-native and save the path into a variable | ||
796 | # Note: using just cmake instead of $CMAKE_NATIVE would work in many cases | ||
797 | CMAKE_NATIVE="$(jq -r '.configurePresets[0] | "\(.cmakeExecutable)"' CMakeUserPresets.json)" | ||
798 | |||
799 | # List available CMake presets | ||
800 | "$CMAKE_NATIVE" --list-presets | ||
801 | Available configure presets: | ||
802 | |||
803 | "cmake-example-cortexa57" - cmake-example: cortexa57 | ||
804 | |||
805 | # Re-compile the already compiled sources | ||
806 | "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 | ||
807 | ninja: no work to do. | ||
808 | # Do a clean re-build | ||
809 | "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target clean | ||
810 | [1/1] Cleaning all built files... | ||
811 | Cleaning... 8 files. | ||
812 | "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target all | ||
813 | [7/7] Linking CXX executable cmake-example | ||
814 | |||
815 | # Run the cross-compiled unit tests with QEMU user-mode | ||
816 | "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target test | ||
817 | [0/1] Running tests... | ||
818 | Test project .../build/tmp/work/cortexa57-poky-linux/cmake-example/1.0/cmake-example-1.0 | ||
819 | Start 1: test-cmake-example | ||
820 | 1/1 Test #1: test-cmake-example ............... Passed 0.03 sec | ||
821 | |||
822 | 100% tests passed, 0 tests failed out of 1 | ||
823 | |||
824 | Total Test time (real) = 0.03 sec | ||
825 | |||
826 | # Using CTest directly is possible as well | ||
827 | CTEST_NATIVE="$(dirname "$CMAKE_NATIVE")/ctest" | ||
828 | |||
829 | # List available CMake presets | ||
830 | "$CTEST_NATIVE" --list-presets | ||
831 | Available test presets: | ||
832 | |||
833 | "cmake-example-cortexa57" - cmake-example: cortexa57 | ||
834 | |||
835 | # Run the cross-compiled unit tests with QEMU user-mode | ||
836 | "$CTEST_NATIVE" --preset "cmake-example-cortexa57" | ||
837 | Test project ...build/tmp/work/cortexa57-poky-linux/cmake-example/1.0/cmake-example-1.0 | ||
838 | Start 1: test-cmake-example | ||
839 | 1/1 Test #1: test-cmake-example ............... Passed 0.03 sec | ||
840 | |||
841 | 100% tests passed, 0 tests failed out of 1 | ||
842 | |||
843 | Total Test time (real) = 0.03 sec | ||
844 | |||
845 | # Deploying the new build to the target device (default is QEUM at 192.168.7.2) | ||
846 | oe-scripts/install_and_deploy_cmake-example-cortexa57 | ||
847 | |||
848 | # Start a remote debugging session with gdbserver on the target and GDB on the host | ||
849 | oe-scripts/gdbserver_1234_usr-bin-cmake-example_m | ||
850 | oe-scripts/gdb_1234_usr-bin-cmake-example | ||
851 | break main | ||
852 | run | ||
853 | step | ||
854 | stepi | ||
855 | continue | ||
856 | quit | ||
857 | |||
858 | # Stop gdbserver on the target device | ||
859 | oe-scripts/gdbserver_1234_usr-bin-cmake-example_m stop | ||
860 | |||
861 | #. *Shared sysroots mode* | ||
862 | |||
863 | For some recipes and use cases a per-recipe sysroot based SDK is not | ||
864 | suitable. Optionally ``devtool ide-sdk`` configures the IDE to use the | ||
865 | toolchain provided by the extensible SDK as described in | ||
866 | :ref:`running_the_ext_sdk_env`. ``devtool ide-sdk --mode=shared`` is | ||
867 | basically a wrapper for the setup of the extensible SDK as described in | ||
868 | :ref:`setting_up_ext_sdk_in_build`. The IDE gets a configuration to use the | ||
869 | shared sysroots. | ||
870 | |||
871 | Creating a SDK with shared sysroots that contains all the dependencies needed | ||
872 | to work with ``my-recipe`` is possible with the following example command:: | ||
873 | |||
874 | $ devtool ide-sdk --mode=shared my-recipe | ||
875 | |||
876 | For VSCode the cross-toolchain is exposed as a CMake kit. CMake kits are | ||
877 | defined in ``~/.local/share/CMakeTools/cmake-tools-kits.json``. | ||
878 | The following example shows how the cross-toolchain can be selected in | ||
879 | VSCode. First of all we need a folder containing a CMake project. | ||
880 | For this example, let's create a CMake project and start VSCode:: | ||
881 | |||
882 | mkdir kit-test | ||
883 | echo "project(foo VERSION 1.0)" > kit-test/CMakeLists.txt | ||
884 | code kit-test | ||
885 | |||
886 | If there is a CMake project in the workspace, cross-compilation is supported: | ||
887 | |||
888 | - Press ``Ctrl + Shift + P``, type ``CMake: Scan for Kits`` | ||
889 | - Press ``Ctrl + Shift + P``, type ``CMake: Select a Kit`` | ||
890 | |||
891 | Finally most of the features provided by CMake and the IDE should be available. | ||
892 | |||
893 | Other IDEs than VSCode are supported as well. However, | ||
894 | ``devtool ide-sdk --mode=shared --ide=none my-recipe`` is currently | ||
895 | just a simple wrapper for the setup of the extensible SDK, as described in | ||
896 | :ref:`setting_up_ext_sdk_in_build`. | ||
605 | 897 | ||
606 | Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a Newer Version of the Software | 898 | Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a Newer Version of the Software |
607 | ------------------------------------------------------------------------------------------------------- | 899 | ------------------------------------------------------------------------------------------------------- |
@@ -615,27 +907,25 @@ counterparts. | |||
615 | 907 | ||
616 | .. note:: | 908 | .. note:: |
617 | 909 | ||
618 | Several methods exist by which you can upgrade recipes - | 910 | Several methods exist by which you can upgrade recipes --- |
619 | devtool upgrade | 911 | ``devtool upgrade`` happens to be one. You can read about all the methods by |
620 | happens to be one. You can read about all the methods by which you | 912 | which you can upgrade recipes in the |
621 | can upgrade recipes in the " | 913 | :ref:`dev-manual/upgrading-recipes:upgrading recipes` section of the Yocto |
622 | Upgrading Recipes | 914 | Project Development Tasks Manual. |
623 | " section of the Yocto Project Development Tasks Manual. | ||
624 | 915 | ||
625 | The ``devtool upgrade`` command is flexible enough to allow you to | 916 | The ``devtool upgrade`` command is flexible enough to allow you to specify |
626 | specify source code revision and versioning schemes, extract code into | 917 | source code revision and versioning schemes, extract code into or out of the |
627 | or out of the ``devtool`` | 918 | ``devtool`` :ref:`devtool-the-workspace-layer-structure`, and work with any |
628 | :ref:`devtool-the-workspace-layer-structure`, | 919 | source file forms that the |
629 | and work with any source file forms that the | 920 | :ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers` support. |
630 | :ref:`fetchers <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` support. | ||
631 | 921 | ||
632 | The following diagram shows the common development flow used with the | 922 | The following diagram shows the common development flow used with the |
633 | ``devtool upgrade`` command: | 923 | ``devtool upgrade`` command: |
634 | 924 | ||
635 | .. image:: figures/sdk-devtool-upgrade-flow.png | 925 | .. image:: figures/sdk-devtool-upgrade-flow.png |
636 | :align: center | 926 | :width: 100% |
637 | 927 | ||
638 | 1. *Initiate the Upgrade*: The top part of the flow shows the typical | 928 | #. *Initiate the Upgrade*: The top part of the flow shows the typical |
639 | scenario by which you use the ``devtool upgrade`` command. The | 929 | scenario by which you use the ``devtool upgrade`` command. The |
640 | following conditions exist: | 930 | following conditions exist: |
641 | 931 | ||
@@ -650,8 +940,7 @@ The following diagram shows the common development flow used with the | |||
650 | A common situation is where third-party software has undergone a | 940 | A common situation is where third-party software has undergone a |
651 | revision so that it has been upgraded. The recipe you have access to | 941 | revision so that it has been upgraded. The recipe you have access to |
652 | is likely in your own layer. Thus, you need to upgrade the recipe to | 942 | is likely in your own layer. Thus, you need to upgrade the recipe to |
653 | use the newer version of the software: | 943 | use the newer version of the software:: |
654 | :: | ||
655 | 944 | ||
656 | $ devtool upgrade -V version recipe | 945 | $ devtool upgrade -V version recipe |
657 | 946 | ||
@@ -659,8 +948,9 @@ The following diagram shows the common development flow used with the | |||
659 | code into the ``sources`` directory in the | 948 | code into the ``sources`` directory in the |
660 | :ref:`devtool-the-workspace-layer-structure`. | 949 | :ref:`devtool-the-workspace-layer-structure`. |
661 | If you want the code extracted to any other location, you need to | 950 | If you want the code extracted to any other location, you need to |
662 | provide the srctree positional argument with the command as follows: | 951 | provide the ``srctree`` positional argument with the command as follows:: |
663 | $ devtool upgrade -V version recipe srctree | 952 | |
953 | $ devtool upgrade -V version recipe srctree | ||
664 | 954 | ||
665 | .. note:: | 955 | .. note:: |
666 | 956 | ||
@@ -668,18 +958,18 @@ The following diagram shows the common development flow used with the | |||
668 | don't use "-V", the command upgrades the recipe to the latest | 958 | don't use "-V", the command upgrades the recipe to the latest |
669 | version. | 959 | version. |
670 | 960 | ||
671 | If the source files pointed to by the ``SRC_URI`` statement in the | 961 | If the source files pointed to by the :term:`SRC_URI` statement in the |
672 | recipe are in a Git repository, you must provide the "-S" option and | 962 | recipe are in a Git repository, you must provide the "-S" option and |
673 | specify a revision for the software. | 963 | specify a revision for the software. |
674 | 964 | ||
675 | Once ``devtool`` locates the recipe, it uses the ``SRC_URI`` variable | 965 | Once ``devtool`` locates the recipe, it uses the :term:`SRC_URI` variable |
676 | to locate the source code and any local patch files from other | 966 | to locate the source code and any local patch files from other |
677 | developers. The result is that the command sets up the source code, | 967 | developers. The result is that the command sets up the source code, |
678 | the new version of the recipe, and an append file all within the | 968 | the new version of the recipe, and an append file all within the |
679 | workspace. | 969 | workspace. |
680 | 970 | ||
681 | Additionally, if you have any non-patch local files (i.e. files | 971 | Additionally, if you have any non-patch local files (i.e. files |
682 | referred to with ``file://`` entries in ``SRC_URI`` statement | 972 | referred to with ``file://`` entries in :term:`SRC_URI` statement |
683 | excluding ``*.patch/`` or ``*.diff``), these files are copied to an | 973 | excluding ``*.patch/`` or ``*.diff``), these files are copied to an |
684 | ``oe-local-files`` folder under the newly created source tree. | 974 | ``oe-local-files`` folder under the newly created source tree. |
685 | Copying the files here gives you a convenient area from which you can | 975 | Copying the files here gives you a convenient area from which you can |
@@ -687,9 +977,9 @@ The following diagram shows the common development flow used with the | |||
687 | are incorporated into the build the next time you build the software | 977 | are incorporated into the build the next time you build the software |
688 | just as are other changes you might have made to the source. | 978 | just as are other changes you might have made to the source. |
689 | 979 | ||
690 | 2. *Resolve any Conflicts created by the Upgrade*: Conflicts could exist | 980 | #. *Resolve any Conflicts created by the Upgrade*: Conflicts could happen |
691 | due to the software being upgraded to a new version. Conflicts occur | 981 | after upgrading the software to a new version. Conflicts occur |
692 | if your recipe specifies some patch files in ``SRC_URI`` that | 982 | if your recipe specifies some patch files in :term:`SRC_URI` that |
693 | conflict with changes made in the new version of the software. For | 983 | conflict with changes made in the new version of the software. For |
694 | such cases, you need to resolve the conflicts by editing the source | 984 | such cases, you need to resolve the conflicts by editing the source |
695 | and following the normal ``git rebase`` conflict resolution process. | 985 | and following the normal ``git rebase`` conflict resolution process. |
@@ -698,24 +988,22 @@ The following diagram shows the common development flow used with the | |||
698 | conflicts created through use of a newer or different version of the | 988 | conflicts created through use of a newer or different version of the |
699 | software. | 989 | software. |
700 | 990 | ||
701 | 3. *Build the Recipe or Rebuild the Image*: The next step you take | 991 | #. *Build the Recipe or Rebuild the Image*: The next step you take |
702 | depends on what you are going to do with the new code. | 992 | depends on what you are going to do with the new code. |
703 | 993 | ||
704 | If you need to eventually move the build output to the target | 994 | If you need to eventually move the build output to the target |
705 | hardware, use the following ``devtool`` command: | 995 | hardware, use the following ``devtool`` command:: |
706 | :: | ||
707 | 996 | ||
708 | $ devtool build recipe | 997 | $ devtool build recipe |
709 | 998 | ||
710 | On the other hand, if you want an image to contain the recipe's | 999 | On the other hand, if you want an image to contain the recipe's |
711 | packages from the workspace for immediate deployment onto a device | 1000 | packages from the workspace for immediate deployment onto a device |
712 | (e.g. for testing purposes), you can use the ``devtool build-image`` | 1001 | (e.g. for testing purposes), you can use the ``devtool build-image`` |
713 | command: | 1002 | command:: |
714 | :: | ||
715 | 1003 | ||
716 | $ devtool build-image image | 1004 | $ devtool build-image image |
717 | 1005 | ||
718 | 4. *Deploy the Build Output*: When you use the ``devtool build`` command | 1006 | #. *Deploy the Build Output*: When you use the ``devtool build`` command |
719 | or ``bitbake`` to build your recipe, you probably want to see if the | 1007 | or ``bitbake`` to build your recipe, you probably want to see if the |
720 | resulting build output works as expected on target hardware. | 1008 | resulting build output works as expected on target hardware. |
721 | 1009 | ||
@@ -729,15 +1017,18 @@ The following diagram shows the common development flow used with the | |||
729 | development machine. | 1017 | development machine. |
730 | 1018 | ||
731 | You can deploy your build output to that target hardware by using the | 1019 | You can deploy your build output to that target hardware by using the |
732 | ``devtool deploy-target`` command: $ devtool deploy-target recipe | 1020 | ``devtool deploy-target`` command:: |
733 | target The target is a live target machine running as an SSH server. | 1021 | |
1022 | $ devtool deploy-target recipe target | ||
1023 | |||
1024 | The target is a live target machine running as an SSH server. | ||
734 | 1025 | ||
735 | You can, of course, also deploy the image you build using the | 1026 | You can, of course, also deploy the image you build using the |
736 | ``devtool build-image`` command to actual hardware. However, | 1027 | ``devtool build-image`` command to actual hardware. However, |
737 | ``devtool`` does not provide a specific command that allows you to do | 1028 | ``devtool`` does not provide a specific command that allows you to do |
738 | this. | 1029 | this. |
739 | 1030 | ||
740 | 5. *Finish Your Work With the Recipe*: The ``devtool finish`` command | 1031 | #. *Finish Your Work With the Recipe*: The ``devtool finish`` command |
741 | creates any patches corresponding to commits in the local Git | 1032 | creates any patches corresponding to commits in the local Git |
742 | repository, moves the new recipe to a more permanent layer, and then | 1033 | repository, moves the new recipe to a more permanent layer, and then |
743 | resets the recipe so that the recipe is built normally rather than | 1034 | resets the recipe so that the recipe is built normally rather than |
@@ -749,8 +1040,7 @@ The following diagram shows the common development flow used with the | |||
749 | 1040 | ||
750 | If you specify a destination layer that is the same as the original | 1041 | If you specify a destination layer that is the same as the original |
751 | source, then the old version of the recipe and associated files are | 1042 | source, then the old version of the recipe and associated files are |
752 | removed prior to adding the new version. | 1043 | removed prior to adding the new version:: |
753 | :: | ||
754 | 1044 | ||
755 | $ devtool finish recipe layer | 1045 | $ devtool finish recipe layer |
756 | 1046 | ||
@@ -765,11 +1055,9 @@ The following diagram shows the common development flow used with the | |||
765 | 1055 | ||
766 | .. note:: | 1056 | .. note:: |
767 | 1057 | ||
768 | You can use the | 1058 | You can use the ``devtool reset`` command to put things back should you |
769 | devtool reset | 1059 | decide you do not want to proceed with your work. If you do use this |
770 | command to put things back should you decide you do not want to | 1060 | command, realize that the source tree is preserved. |
771 | proceed with your work. If you do use this command, realize that | ||
772 | the source tree is preserved. | ||
773 | 1061 | ||
774 | A Closer Look at ``devtool add`` | 1062 | A Closer Look at ``devtool add`` |
775 | ================================ | 1063 | ================================ |
@@ -827,8 +1115,7 @@ name and version, just the name, or just the version as part of the | |||
827 | command line. | 1115 | command line. |
828 | 1116 | ||
829 | Sometimes the name or version determined from the source tree might be | 1117 | Sometimes the name or version determined from the source tree might be |
830 | incorrect. For such a case, you must reset the recipe: | 1118 | incorrect. For such a case, you must reset the recipe:: |
831 | :: | ||
832 | 1119 | ||
833 | $ devtool reset -n recipename | 1120 | $ devtool reset -n recipename |
834 | 1121 | ||
@@ -838,31 +1125,27 @@ run ``devtool add`` again and provide the name or the version. | |||
838 | Dependency Detection and Mapping | 1125 | Dependency Detection and Mapping |
839 | -------------------------------- | 1126 | -------------------------------- |
840 | 1127 | ||
841 | The ``devtool add`` command attempts to detect build-time dependencies | 1128 | The ``devtool add`` command attempts to detect build-time dependencies and map |
842 | and map them to other recipes in the system. During this mapping, the | 1129 | them to other recipes in the system. During this mapping, the command fills in |
843 | command fills in the names of those recipes as part of the | 1130 | the names of those recipes as part of the :term:`DEPENDS` variable within the |
844 | :term:`DEPENDS` variable within the | ||
845 | recipe. If a dependency cannot be mapped, ``devtool`` places a comment | 1131 | recipe. If a dependency cannot be mapped, ``devtool`` places a comment |
846 | in the recipe indicating such. The inability to map a dependency can | 1132 | in the recipe indicating such. The inability to map a dependency can |
847 | result from naming not being recognized or because the dependency simply | 1133 | result from naming not being recognized or because the dependency simply |
848 | is not available. For cases where the dependency is not available, you | 1134 | is not available. For cases where the dependency is not available, you |
849 | must use the ``devtool add`` command to add an additional recipe that | 1135 | must use the ``devtool add`` command to add an additional recipe that |
850 | satisfies the dependency. Once you add that recipe, you need to update | 1136 | satisfies the dependency. Once you add that recipe, you need to update |
851 | the ``DEPENDS`` variable in the original recipe to include the new | 1137 | the :term:`DEPENDS` variable in the original recipe to include the new |
852 | recipe. | 1138 | recipe. |
853 | 1139 | ||
854 | If you need to add runtime dependencies, you can do so by adding the | 1140 | If you need to add runtime dependencies, you can do so by adding the |
855 | following to your recipe: | 1141 | following to your recipe:: |
856 | :: | ||
857 | 1142 | ||
858 | RDEPENDS_${PN} += "dependency1 dependency2 ..." | 1143 | RDEPENDS:${PN} += "dependency1 dependency2 ..." |
859 | 1144 | ||
860 | .. note:: | 1145 | .. note:: |
861 | 1146 | ||
862 | The | 1147 | The ``devtool add`` command often cannot distinguish between mandatory and |
863 | devtool add | 1148 | optional dependencies. Consequently, some of the detected dependencies might |
864 | command often cannot distinguish between mandatory and optional | ||
865 | dependencies. Consequently, some of the detected dependencies might | ||
866 | in fact be optional. When in doubt, consult the documentation or the | 1149 | in fact be optional. When in doubt, consult the documentation or the |
867 | configure script for the software the recipe is building for further | 1150 | configure script for the software the recipe is building for further |
868 | details. In some cases, you might find you can substitute the | 1151 | details. In some cases, you might find you can substitute the |
@@ -872,30 +1155,28 @@ following to your recipe: | |||
872 | License Detection | 1155 | License Detection |
873 | ----------------- | 1156 | ----------------- |
874 | 1157 | ||
875 | The ``devtool add`` command attempts to determine if the software you | 1158 | The ``devtool add`` command attempts to determine if the software you are |
876 | are adding is able to be distributed under a common, open-source | 1159 | adding is able to be distributed under a common, open-source license. If |
877 | license. If so, the command sets the | 1160 | so, the command sets the :term:`LICENSE` value accordingly. |
878 | :term:`LICENSE` value accordingly. | ||
879 | You should double-check the value added by the command against the | 1161 | You should double-check the value added by the command against the |
880 | documentation or source files for the software you are building and, if | 1162 | documentation or source files for the software you are building and, if |
881 | necessary, update that ``LICENSE`` value. | 1163 | necessary, update that :term:`LICENSE` value. |
882 | 1164 | ||
883 | The ``devtool add`` command also sets the | 1165 | The ``devtool add`` command also sets the :term:`LIC_FILES_CHKSUM` |
884 | :term:`LIC_FILES_CHKSUM` | ||
885 | value to point to all files that appear to be license-related. Realize | 1166 | value to point to all files that appear to be license-related. Realize |
886 | that license statements often appear in comments at the top of source | 1167 | that license statements often appear in comments at the top of source |
887 | files or within the documentation. In such cases, the command does not | 1168 | files or within the documentation. In such cases, the command does not |
888 | recognize those license statements. Consequently, you might need to | 1169 | recognize those license statements. Consequently, you might need to |
889 | amend the ``LIC_FILES_CHKSUM`` variable to point to one or more of those | 1170 | amend the :term:`LIC_FILES_CHKSUM` variable to point to one or more of those |
890 | comments if present. Setting ``LIC_FILES_CHKSUM`` is particularly | 1171 | comments if present. Setting :term:`LIC_FILES_CHKSUM` is particularly |
891 | important for third-party software. The mechanism attempts to ensure | 1172 | important for third-party software. The mechanism attempts to ensure |
892 | correct licensing should you upgrade the recipe to a newer upstream | 1173 | correct licensing should you upgrade the recipe to a newer upstream |
893 | version in future. Any change in licensing is detected and you receive | 1174 | version in future. Any change in licensing is detected and you receive |
894 | an error prompting you to check the license text again. | 1175 | an error prompting you to check the license text again. |
895 | 1176 | ||
896 | If the ``devtool add`` command cannot determine licensing information, | 1177 | If the ``devtool add`` command cannot determine licensing information, |
897 | ``devtool`` sets the ``LICENSE`` value to "CLOSED" and leaves the | 1178 | ``devtool`` sets the :term:`LICENSE` value to "CLOSED" and leaves the |
898 | ``LIC_FILES_CHKSUM`` value unset. This behavior allows you to continue | 1179 | :term:`LIC_FILES_CHKSUM` value unset. This behavior allows you to continue |
899 | with development even though the settings are unlikely to be correct in | 1180 | with development even though the settings are unlikely to be correct in |
900 | all cases. You should check the documentation or source files for the | 1181 | all cases. You should check the documentation or source files for the |
901 | software you are building to determine the actual license. | 1182 | software you are building to determine the actual license. |
@@ -921,12 +1202,12 @@ mind: | |||
921 | hardcoding tools within the toolchain such as ``gcc`` and ``g++``. | 1202 | hardcoding tools within the toolchain such as ``gcc`` and ``g++``. |
922 | 1203 | ||
923 | - The environment in which Make runs is set up with various standard | 1204 | - The environment in which Make runs is set up with various standard |
924 | variables for compilation (e.g. ``CC``, ``CXX``, and so forth) in a | 1205 | variables for compilation (e.g. :term:`CC`, :term:`CXX`, and so forth) in a |
925 | similar manner to the environment set up by the SDK's environment | 1206 | similar manner to the environment set up by the SDK's environment |
926 | setup script. One easy way to see these variables is to run the | 1207 | setup script. One easy way to see these variables is to run the |
927 | ``devtool build`` command on the recipe and then look in | 1208 | ``devtool build`` command on the recipe and then look in |
928 | ``oe-logs/run.do_compile``. Towards the top of this file, a list of | 1209 | ``oe-logs/run.do_compile``. Towards the top of this file, there is |
929 | environment variables exists that are being set. You can take | 1210 | a list of environment variables that are set. You can take |
930 | advantage of these variables within the Makefile. | 1211 | advantage of these variables within the Makefile. |
931 | 1212 | ||
932 | - If the Makefile sets a default for a variable using "=", that default | 1213 | - If the Makefile sets a default for a variable using "=", that default |
@@ -937,8 +1218,7 @@ mind: | |||
937 | the command line, add the variable setting to | 1218 | the command line, add the variable setting to |
938 | :term:`EXTRA_OEMAKE` or | 1219 | :term:`EXTRA_OEMAKE` or |
939 | :term:`PACKAGECONFIG_CONFARGS` | 1220 | :term:`PACKAGECONFIG_CONFARGS` |
940 | within the recipe. Here is an example using ``EXTRA_OEMAKE``: | 1221 | within the recipe. Here is an example using :term:`EXTRA_OEMAKE`:: |
941 | :: | ||
942 | 1222 | ||
943 | EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" | 1223 | EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" |
944 | 1224 | ||
@@ -962,16 +1242,15 @@ mind: | |||
962 | Adding Native Tools | 1242 | Adding Native Tools |
963 | ------------------- | 1243 | ------------------- |
964 | 1244 | ||
965 | Often, you need to build additional tools that run on the :term:`Build | 1245 | Often, you need to build additional tools that run on the :term:`Build Host` |
966 | Host` as opposed to | 1246 | as opposed to the target. You should indicate this requirement by using one of |
967 | the target. You should indicate this requirement by using one of the | 1247 | the following methods when you run ``devtool add``: |
968 | following methods when you run ``devtool add``: | ||
969 | 1248 | ||
970 | - Specify the name of the recipe such that it ends with "-native". | 1249 | - Specify the name of the recipe such that it ends with "-native". |
971 | Specifying the name like this produces a recipe that only builds for | 1250 | Specifying the name like this produces a recipe that only builds for |
972 | the build host. | 1251 | the build host. |
973 | 1252 | ||
974 | - Specify the "DASHDASHalso-native" option with the ``devtool add`` | 1253 | - Specify the "--also-native" option with the ``devtool add`` |
975 | command. Specifying this option creates a recipe file that still | 1254 | command. Specifying this option creates a recipe file that still |
976 | builds for the target but also creates a variant with a "-native" | 1255 | builds for the target but also creates a variant with a "-native" |
977 | suffix that builds for the build host. | 1256 | suffix that builds for the build host. |
@@ -982,18 +1261,16 @@ following methods when you run ``devtool add``: | |||
982 | that builds code for the target, you can typically accomplish this by | 1261 | that builds code for the target, you can typically accomplish this by |
983 | building the native and target parts separately rather than within | 1262 | building the native and target parts separately rather than within |
984 | the same compilation process. Realize though that with the | 1263 | the same compilation process. Realize though that with the |
985 | "DASHDASHalso-native" option, you can add the tool using just one | 1264 | "--also-native" option, you can add the tool using just one |
986 | recipe file. | 1265 | recipe file. |
987 | 1266 | ||
988 | Adding Node.js Modules | 1267 | Adding Node.js Modules |
989 | ---------------------- | 1268 | ---------------------- |
990 | 1269 | ||
991 | You can use the ``devtool add`` command two different ways to add | 1270 | You can use the ``devtool add`` command two different ways to add |
992 | Node.js modules: 1) Through ``npm`` and, 2) from a repository or local | 1271 | Node.js modules: through ``npm`` or from a repository or local source. |
993 | source. | ||
994 | 1272 | ||
995 | Use the following form to add Node.js modules through ``npm``: | 1273 | Use the following form to add Node.js modules through ``npm``:: |
996 | :: | ||
997 | 1274 | ||
998 | $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" | 1275 | $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" |
999 | 1276 | ||
@@ -1006,7 +1283,7 @@ these behaviors ensure the reproducibility and integrity of the build. | |||
1006 | 1283 | ||
1007 | .. note:: | 1284 | .. note:: |
1008 | 1285 | ||
1009 | - You must use quotes around the URL. The ``devtool add`` does not | 1286 | - You must use quotes around the URL. ``devtool add`` does not |
1010 | require the quotes, but the shell considers ";" as a splitter | 1287 | require the quotes, but the shell considers ";" as a splitter |
1011 | between multiple commands. Thus, without the quotes, | 1288 | between multiple commands. Thus, without the quotes, |
1012 | ``devtool add`` does not receive the other parts, which results in | 1289 | ``devtool add`` does not receive the other parts, which results in |
@@ -1017,14 +1294,12 @@ these behaviors ensure the reproducibility and integrity of the build. | |||
1017 | 1294 | ||
1018 | As mentioned earlier, you can also add Node.js modules directly from a | 1295 | As mentioned earlier, you can also add Node.js modules directly from a |
1019 | repository or local source tree. To add modules this way, use | 1296 | repository or local source tree. To add modules this way, use |
1020 | ``devtool add`` in the following form: | 1297 | ``devtool add`` in the following form:: |
1021 | :: | ||
1022 | 1298 | ||
1023 | $ devtool add https://github.com/diversario/node-ssdp | 1299 | $ devtool add https://github.com/diversario/node-ssdp |
1024 | 1300 | ||
1025 | In this example, ``devtool`` | 1301 | In this example, ``devtool`` fetches the specified Git repository, detects the |
1026 | fetches the specified Git repository, detects the code as Node.js code, | 1302 | code as Node.js code, fetches dependencies using ``npm``, and sets |
1027 | fetches dependencies using ``npm``, and sets | ||
1028 | :term:`SRC_URI` accordingly. | 1303 | :term:`SRC_URI` accordingly. |
1029 | 1304 | ||
1030 | Working With Recipes | 1305 | Working With Recipes |
@@ -1033,17 +1308,17 @@ Working With Recipes | |||
1033 | When building a recipe using the ``devtool build`` command, the typical | 1308 | When building a recipe using the ``devtool build`` command, the typical |
1034 | build progresses as follows: | 1309 | build progresses as follows: |
1035 | 1310 | ||
1036 | 1. Fetch the source | 1311 | #. Fetch the source |
1037 | 1312 | ||
1038 | 2. Unpack the source | 1313 | #. Unpack the source |
1039 | 1314 | ||
1040 | 3. Configure the source | 1315 | #. Configure the source |
1041 | 1316 | ||
1042 | 4. Compile the source | 1317 | #. Compile the source |
1043 | 1318 | ||
1044 | 5. Install the build output | 1319 | #. Install the build output |
1045 | 1320 | ||
1046 | 6. Package the installed output | 1321 | #. Package the installed output |
1047 | 1322 | ||
1048 | For recipes in the workspace, fetching and unpacking is disabled as the | 1323 | For recipes in the workspace, fetching and unpacking is disabled as the |
1049 | source tree has already been prepared and is persistent. Each of these | 1324 | source tree has already been prepared and is persistent. Each of these |
@@ -1057,10 +1332,9 @@ If you look at the contents of a recipe, you will see that the recipe | |||
1057 | does not include complete instructions for building the software. | 1332 | does not include complete instructions for building the software. |
1058 | Instead, common functionality is encapsulated in classes inherited with | 1333 | Instead, common functionality is encapsulated in classes inherited with |
1059 | the ``inherit`` directive. This technique leaves the recipe to describe | 1334 | the ``inherit`` directive. This technique leaves the recipe to describe |
1060 | just the things that are specific to the software being built. A | 1335 | just the things that are specific to the software being built. There is |
1061 | :ref:`base <ref-classes-base>` class exists that | 1336 | a :ref:`ref-classes-base` class that is implicitly inherited by all recipes |
1062 | is implicitly inherited by all recipes and provides the functionality | 1337 | and provides the functionality that most recipes typically need. |
1063 | that most recipes typically need. | ||
1064 | 1338 | ||
1065 | The remainder of this section presents information useful when working | 1339 | The remainder of this section presents information useful when working |
1066 | with recipes. | 1340 | with recipes. |
@@ -1086,13 +1360,13 @@ links created within the source tree: | |||
1086 | ``${``\ :term:`D`\ ``}``. | 1360 | ``${``\ :term:`D`\ ``}``. |
1087 | 1361 | ||
1088 | - ``sysroot-destdir/``: Contains a subset of files installed within | 1362 | - ``sysroot-destdir/``: Contains a subset of files installed within |
1089 | ``do_install`` that have been put into the shared sysroot. For | 1363 | :ref:`ref-tasks-install` that have been put into the shared sysroot. For |
1090 | more information, see the "`Sharing Files Between | 1364 | more information, see the |
1091 | Recipes <#sdk-sharing-files-between-recipes>`__" section. | 1365 | ":ref:`dev-manual/new-recipe:sharing files between recipes`" section. |
1092 | 1366 | ||
1093 | - ``packages-split/``: Contains subdirectories for each package | 1367 | - ``packages-split/``: Contains subdirectories for each package |
1094 | produced by the recipe. For more information, see the | 1368 | produced by the recipe. For more information, see the |
1095 | "`Packaging <#sdk-packaging>`__" section. | 1369 | ":ref:`sdk-manual/extensible:packaging`" section. |
1096 | 1370 | ||
1097 | You can use these links to get more information on what is happening at | 1371 | You can use these links to get more information on what is happening at |
1098 | each build step. | 1372 | each build step. |
@@ -1102,25 +1376,20 @@ Setting Configure Arguments | |||
1102 | 1376 | ||
1103 | If the software your recipe is building uses GNU autoconf, then a fixed | 1377 | If the software your recipe is building uses GNU autoconf, then a fixed |
1104 | set of arguments is passed to it to enable cross-compilation plus any | 1378 | set of arguments is passed to it to enable cross-compilation plus any |
1105 | extras specified by | 1379 | extras specified by :term:`EXTRA_OECONF` or :term:`PACKAGECONFIG_CONFARGS` |
1106 | :term:`EXTRA_OECONF` or | ||
1107 | :term:`PACKAGECONFIG_CONFARGS` | ||
1108 | set within the recipe. If you wish to pass additional options, add them | 1380 | set within the recipe. If you wish to pass additional options, add them |
1109 | to ``EXTRA_OECONF`` or ``PACKAGECONFIG_CONFARGS``. Other supported build | 1381 | to :term:`EXTRA_OECONF` or :term:`PACKAGECONFIG_CONFARGS`. Other supported build |
1110 | tools have similar variables (e.g. | 1382 | tools have similar variables (e.g. :term:`EXTRA_OECMAKE` for CMake, |
1111 | :term:`EXTRA_OECMAKE` for | 1383 | :term:`EXTRA_OESCONS` for Scons, and so forth). If you need to pass anything on |
1112 | CMake, :term:`EXTRA_OESCONS` | 1384 | the ``make`` command line, you can use :term:`EXTRA_OEMAKE` or the |
1113 | for Scons, and so forth). If you need to pass anything on the ``make`` | 1385 | :term:`PACKAGECONFIG_CONFARGS` variables to do so. |
1114 | command line, you can use ``EXTRA_OEMAKE`` or the | ||
1115 | :term:`PACKAGECONFIG_CONFARGS` | ||
1116 | variables to do so. | ||
1117 | 1386 | ||
1118 | You can use the ``devtool configure-help`` command to help you set the | 1387 | You can use the ``devtool configure-help`` command to help you set the |
1119 | arguments listed in the previous paragraph. The command determines the | 1388 | arguments listed in the previous paragraph. The command determines the |
1120 | exact options being passed, and shows them to you along with any custom | 1389 | exact options being passed, and shows them to you along with any custom |
1121 | arguments specified through ``EXTRA_OECONF`` or | 1390 | arguments specified through :term:`EXTRA_OECONF` or |
1122 | ``PACKAGECONFIG_CONFARGS``. If applicable, the command also shows you | 1391 | :term:`PACKAGECONFIG_CONFARGS`. If applicable, the command also shows you |
1123 | the output of the configure script's "DASHDASHhelp" option as a | 1392 | the output of the configure script's "--help" option as a |
1124 | reference. | 1393 | reference. |
1125 | 1394 | ||
1126 | Sharing Files Between Recipes | 1395 | Sharing Files Between Recipes |
@@ -1130,15 +1399,14 @@ Recipes often need to use files provided by other recipes on the | |||
1130 | :term:`Build Host`. For example, | 1399 | :term:`Build Host`. For example, |
1131 | an application linking to a common library needs access to the library | 1400 | an application linking to a common library needs access to the library |
1132 | itself and its associated headers. The way this access is accomplished | 1401 | itself and its associated headers. The way this access is accomplished |
1133 | within the extensible SDK is through the sysroot. One sysroot exists per | 1402 | within the extensible SDK is through the sysroot. There is one sysroot per |
1134 | "machine" for which the SDK is being built. In practical terms, this | 1403 | "machine" for which the SDK is being built. In practical terms, this |
1135 | means a sysroot exists for the target machine, and a sysroot exists for | 1404 | means there is a sysroot for the target machine, and a sysroot for |
1136 | the build host. | 1405 | the build host. |
1137 | 1406 | ||
1138 | Recipes should never write files directly into the sysroot. Instead, | 1407 | Recipes should never write files directly into the sysroot. Instead, |
1139 | files should be installed into standard locations during the | 1408 | files should be installed into standard locations during the |
1140 | :ref:`ref-tasks-install` task within | 1409 | :ref:`ref-tasks-install` task within the ``${``\ :term:`D`\ ``}`` directory. A |
1141 | the ``${``\ :term:`D`\ ``}`` directory. A | ||
1142 | subset of these files automatically goes into the sysroot. The reason | 1410 | subset of these files automatically goes into the sysroot. The reason |
1143 | for this limitation is that almost all files that go into the sysroot | 1411 | for this limitation is that almost all files that go into the sysroot |
1144 | are cataloged in manifests in order to ensure they can be removed later | 1412 | are cataloged in manifests in order to ensure they can be removed later |
@@ -1154,14 +1422,12 @@ the target device, it is important to understand packaging because the | |||
1154 | contents of the image are expressed in terms of packages and not | 1422 | contents of the image are expressed in terms of packages and not |
1155 | recipes. | 1423 | recipes. |
1156 | 1424 | ||
1157 | During the :ref:`ref-tasks-package` | 1425 | During the :ref:`ref-tasks-package` task, files installed during the |
1158 | task, files installed during the | 1426 | :ref:`ref-tasks-install` task are split into one main package, which is almost |
1159 | :ref:`ref-tasks-install` task are | 1427 | always named the same as the recipe, and into several other packages. This |
1160 | split into one main package, which is almost always named the same as | 1428 | separation exists because not all of those installed files are useful in every |
1161 | the recipe, and into several other packages. This separation exists | 1429 | image. For example, you probably do not need any of the documentation installed |
1162 | because not all of those installed files are useful in every image. For | 1430 | in a production image. Consequently, for each recipe the documentation |
1163 | example, you probably do not need any of the documentation installed in | ||
1164 | a production image. Consequently, for each recipe the documentation | ||
1165 | files are separated into a ``-doc`` package. Recipes that package | 1431 | files are separated into a ``-doc`` package. Recipes that package |
1166 | software containing optional modules or plugins might undergo additional | 1432 | software containing optional modules or plugins might undergo additional |
1167 | package splitting as well. | 1433 | package splitting as well. |
@@ -1169,18 +1435,17 @@ package splitting as well. | |||
1169 | After building a recipe, you can see where files have gone by looking in | 1435 | After building a recipe, you can see where files have gone by looking in |
1170 | the ``oe-workdir/packages-split`` directory, which contains a | 1436 | the ``oe-workdir/packages-split`` directory, which contains a |
1171 | subdirectory for each package. Apart from some advanced cases, the | 1437 | subdirectory for each package. Apart from some advanced cases, the |
1172 | :term:`PACKAGES` and | 1438 | :term:`PACKAGES` and :term:`FILES` variables controls |
1173 | :term:`FILES` variables controls | 1439 | splitting. The :term:`PACKAGES` variable lists all of the packages to be |
1174 | splitting. The ``PACKAGES`` variable lists all of the packages to be | 1440 | produced, while the :term:`FILES` variable specifies which files to include |
1175 | produced, while the ``FILES`` variable specifies which files to include | ||
1176 | in each package by using an override to specify the package. For | 1441 | in each package by using an override to specify the package. For |
1177 | example, ``FILES_${PN}`` specifies the files to go into the main package | 1442 | example, ``FILES:${PN}`` specifies the files to go into the main package |
1178 | (i.e. the main package has the same name as the recipe and | 1443 | (i.e. the main package has the same name as the recipe and |
1179 | ``${``\ :term:`PN`\ ``}`` evaluates to the | 1444 | ``${``\ :term:`PN`\ ``}`` evaluates to the |
1180 | recipe name). The order of the ``PACKAGES`` value is significant. For | 1445 | recipe name). The order of the :term:`PACKAGES` value is significant. For |
1181 | each installed file, the first package whose ``FILES`` value matches the | 1446 | each installed file, the first package whose :term:`FILES` value matches the |
1182 | file is the package into which the file goes. Defaults exist for both | 1447 | file is the package into which the file goes. Both the :term:`PACKAGES` and |
1183 | the ``PACKAGES`` and ``FILES`` variables. Consequently, you might find | 1448 | :term:`FILES` variables have default values. Consequently, you might find |
1184 | you do not even need to set these variables in your recipe unless the | 1449 | you do not even need to set these variables in your recipe unless the |
1185 | software the recipe is building installs files into non-standard | 1450 | software the recipe is building installs files into non-standard |
1186 | locations. | 1451 | locations. |
@@ -1195,15 +1460,13 @@ need to restore the original files that existed prior to running the | |||
1195 | ``devtool deploy-target`` command. Because the ``devtool deploy-target`` | 1460 | ``devtool deploy-target`` command. Because the ``devtool deploy-target`` |
1196 | command backs up any files it overwrites, you can use the | 1461 | command backs up any files it overwrites, you can use the |
1197 | ``devtool undeploy-target`` command to restore those files and remove | 1462 | ``devtool undeploy-target`` command to restore those files and remove |
1198 | any other files the recipe deployed. Consider the following example: | 1463 | any other files the recipe deployed. Consider the following example:: |
1199 | :: | ||
1200 | 1464 | ||
1201 | $ devtool undeploy-target lighttpd root@192.168.7.2 | 1465 | $ devtool undeploy-target lighttpd root@192.168.7.2 |
1202 | 1466 | ||
1203 | If you have deployed | 1467 | If you have deployed |
1204 | multiple applications, you can remove them all using the "-a" option | 1468 | multiple applications, you can remove them all using the "-a" option |
1205 | thus restoring the target device to its original state: | 1469 | thus restoring the target device to its original state:: |
1206 | :: | ||
1207 | 1470 | ||
1208 | $ devtool undeploy-target -a root@192.168.7.2 | 1471 | $ devtool undeploy-target -a root@192.168.7.2 |
1209 | 1472 | ||
@@ -1214,16 +1477,11 @@ target machine. | |||
1214 | 1477 | ||
1215 | .. note:: | 1478 | .. note:: |
1216 | 1479 | ||
1217 | The | 1480 | The ``devtool deploy-target`` and ``devtool undeploy-target`` commands do |
1218 | devtool deploy-target | 1481 | not currently interact with any package management system on the target |
1219 | and | 1482 | device (e.g. RPM or OPKG). Consequently, you should not intermingle |
1220 | devtool undeploy-target | 1483 | ``devtool deploy-target`` and package manager operations on the target |
1221 | commands do not currently interact with any package management system | 1484 | device. Doing so could result in a conflicting set of files. |
1222 | on the target device (e.g. RPM or OPKG). Consequently, you should not | ||
1223 | intermingle | ||
1224 | devtool deploy-target | ||
1225 | and package manager operations on the target device. Doing so could | ||
1226 | result in a conflicting set of files. | ||
1227 | 1485 | ||
1228 | Installing Additional Items Into the Extensible SDK | 1486 | Installing Additional Items Into the Extensible SDK |
1229 | =================================================== | 1487 | =================================================== |
@@ -1234,13 +1492,31 @@ populated on-demand. Sometimes you must explicitly install extra items | |||
1234 | into the SDK. If you need these extra items, you can first search for | 1492 | into the SDK. If you need these extra items, you can first search for |
1235 | the items using the ``devtool search`` command. For example, suppose you | 1493 | the items using the ``devtool search`` command. For example, suppose you |
1236 | need to link to libGL but you are not sure which recipe provides libGL. | 1494 | need to link to libGL but you are not sure which recipe provides libGL. |
1237 | You can use the following command to find out: | 1495 | You can use the following command to find out:: |
1238 | :: | ||
1239 | 1496 | ||
1240 | $ devtool search libGL mesa | 1497 | $ devtool search libGL mesa |
1498 | A free implementation of the OpenGL API | ||
1499 | |||
1500 | Once you know the recipe | ||
1501 | (i.e. ``mesa`` in this example), you can install it. | ||
1502 | |||
1503 | When using the extensible SDK directly in a Yocto build | ||
1504 | ------------------------------------------------------- | ||
1505 | |||
1506 | In this scenario, the Yocto build tooling, e.g. ``bitbake`` | ||
1507 | is directly accessible to build additional items, and it | ||
1508 | can simply be executed directly:: | ||
1509 | |||
1510 | $ bitbake curl-native | ||
1511 | # Add newly built native items to native sysroot | ||
1512 | $ bitbake build-sysroots -c build_native_sysroot | ||
1513 | $ bitbake mesa | ||
1514 | # Add newly built target items to target sysroot | ||
1515 | $ bitbake build-sysroots -c build_target_sysroot | ||
1516 | |||
1517 | When using a standalone installer for the Extensible SDK | ||
1518 | -------------------------------------------------------- | ||
1241 | 1519 | ||
1242 | A free implementation of the OpenGL API Once you know the recipe | ||
1243 | (i.e. ``mesa`` in this example), you can install it: | ||
1244 | :: | 1520 | :: |
1245 | 1521 | ||
1246 | $ devtool sdk-install mesa | 1522 | $ devtool sdk-install mesa |
@@ -1248,14 +1524,13 @@ A free implementation of the OpenGL API Once you know the recipe | |||
1248 | By default, the ``devtool sdk-install`` command assumes | 1524 | By default, the ``devtool sdk-install`` command assumes |
1249 | the item is available in pre-built form from your SDK provider. If the | 1525 | the item is available in pre-built form from your SDK provider. If the |
1250 | item is not available and it is acceptable to build the item from | 1526 | item is not available and it is acceptable to build the item from |
1251 | source, you can add the "-s" option as follows: | 1527 | source, you can add the "-s" option as follows:: |
1252 | :: | ||
1253 | 1528 | ||
1254 | $ devtool sdk-install -s mesa | 1529 | $ devtool sdk-install -s mesa |
1255 | 1530 | ||
1256 | It is important to remember that building the item from source | 1531 | It is important to remember that building the item from source |
1257 | takes significantly longer than installing the pre-built artifact. Also, | 1532 | takes significantly longer than installing the pre-built artifact. Also, |
1258 | if no recipe exists for the item you want to add to the SDK, you must | 1533 | if there is no recipe for the item you want to add to the SDK, you must |
1259 | instead add the item using the ``devtool add`` command. | 1534 | instead add the item using the ``devtool add`` command. |
1260 | 1535 | ||
1261 | Applying Updates to an Installed Extensible SDK | 1536 | Applying Updates to an Installed Extensible SDK |
@@ -1265,20 +1540,17 @@ If you are working with an installed extensible SDK that gets | |||
1265 | occasionally updated (e.g. a third-party SDK), then you will need to | 1540 | occasionally updated (e.g. a third-party SDK), then you will need to |
1266 | manually "pull down" the updates into the installed SDK. | 1541 | manually "pull down" the updates into the installed SDK. |
1267 | 1542 | ||
1268 | To update your installed SDK, use ``devtool`` as follows: | 1543 | To update your installed SDK, use ``devtool`` as follows:: |
1269 | :: | ||
1270 | 1544 | ||
1271 | $ devtool sdk-update | 1545 | $ devtool sdk-update |
1272 | 1546 | ||
1273 | The previous command assumes your SDK provider has set the | 1547 | The previous command assumes your SDK provider has set the default update URL |
1274 | default update URL for you through the | 1548 | for you through the :term:`SDK_UPDATE_URL` variable as described in the |
1275 | :term:`SDK_UPDATE_URL` | 1549 | ":ref:`sdk-manual/appendix-customizing:Providing Updates to the Extensible SDK After Installation`" |
1276 | variable as described in the "`Providing Updates to the Extensible SDK | ||
1277 | After | ||
1278 | Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__" | ||
1279 | section. If the SDK provider has not set that default URL, you need to | 1550 | section. If the SDK provider has not set that default URL, you need to |
1280 | specify it yourself in the command as follows: $ devtool sdk-update | 1551 | specify it yourself in the command as follows:: |
1281 | path_to_update_directory | 1552 | |
1553 | $ devtool sdk-update path_to_update_directory | ||
1282 | 1554 | ||
1283 | .. note:: | 1555 | .. note:: |
1284 | 1556 | ||
@@ -1295,15 +1567,15 @@ those customers need an SDK that has custom libraries. In such a case, | |||
1295 | you can produce a derivative SDK based on the currently installed SDK | 1567 | you can produce a derivative SDK based on the currently installed SDK |
1296 | fairly easily by following these steps: | 1568 | fairly easily by following these steps: |
1297 | 1569 | ||
1298 | 1. If necessary, install an extensible SDK that you want to use as a | 1570 | #. If necessary, install an extensible SDK that you want to use as a |
1299 | base for your derivative SDK. | 1571 | base for your derivative SDK. |
1300 | 1572 | ||
1301 | 2. Source the environment script for the SDK. | 1573 | #. Source the environment script for the SDK. |
1302 | 1574 | ||
1303 | 3. Add the extra libraries or other components you want by using the | 1575 | #. Add the extra libraries or other components you want by using the |
1304 | ``devtool add`` command. | 1576 | ``devtool add`` command. |
1305 | 1577 | ||
1306 | 4. Run the ``devtool build-sdk`` command. | 1578 | #. Run the ``devtool build-sdk`` command. |
1307 | 1579 | ||
1308 | The previous steps take the recipes added to the workspace and construct | 1580 | The previous steps take the recipes added to the workspace and construct |
1309 | a new SDK installer that contains those recipes and the resulting binary | 1581 | a new SDK installer that contains those recipes and the resulting binary |