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