diff options
Diffstat (limited to 'documentation/ref-manual/ref-tasks.rst')
-rw-r--r-- | documentation/ref-manual/ref-tasks.rst | 875 |
1 files changed, 875 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-tasks.rst b/documentation/ref-manual/ref-tasks.rst new file mode 100644 index 0000000000..dcdff05dce --- /dev/null +++ b/documentation/ref-manual/ref-tasks.rst | |||
@@ -0,0 +1,875 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ***** | ||
4 | Tasks | ||
5 | ***** | ||
6 | |||
7 | Tasks are units of execution for BitBake. Recipes (``.bb`` files) use | ||
8 | tasks to complete configuring, compiling, and packaging software. This | ||
9 | chapter provides a reference of the tasks defined in the OpenEmbedded | ||
10 | build system. | ||
11 | |||
12 | Normal Recipe Build Tasks | ||
13 | ========================= | ||
14 | |||
15 | The following sections describe normal tasks associated with building a | ||
16 | recipe. For more information on tasks and dependencies, see the | ||
17 | ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and | ||
18 | ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the | ||
19 | BitBake User Manual. | ||
20 | |||
21 | .. _ref-tasks-build: | ||
22 | |||
23 | ``do_build`` | ||
24 | ------------ | ||
25 | |||
26 | The default task for all recipes. This task depends on all other normal | ||
27 | tasks required to build a recipe. | ||
28 | |||
29 | .. _ref-tasks-compile: | ||
30 | |||
31 | ``do_compile`` | ||
32 | -------------- | ||
33 | |||
34 | Compiles the source code. This task runs with the current working | ||
35 | directory set to ``${``\ :term:`B`\ ``}``. | ||
36 | |||
37 | The default behavior of this task is to run the ``oe_runmake`` function | ||
38 | if a makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found. | ||
39 | If no such file is found, the ``do_compile`` task does nothing. | ||
40 | |||
41 | .. _ref-tasks-compile_ptest_base: | ||
42 | |||
43 | ``do_compile_ptest_base`` | ||
44 | ------------------------- | ||
45 | |||
46 | Compiles the runtime test suite included in the software being built. | ||
47 | |||
48 | .. _ref-tasks-configure: | ||
49 | |||
50 | ``do_configure`` | ||
51 | ---------------- | ||
52 | |||
53 | Configures the source by enabling and disabling any build-time and | ||
54 | configuration options for the software being built. The task runs with | ||
55 | the current working directory set to ``${``\ :term:`B`\ ``}``. | ||
56 | |||
57 | The default behavior of this task is to run ``oe_runmake clean`` if a | ||
58 | makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found and | ||
59 | :term:`CLEANBROKEN` is not set to "1". If no such | ||
60 | file is found or the ``CLEANBROKEN`` variable is set to "1", the | ||
61 | ``do_configure`` task does nothing. | ||
62 | |||
63 | .. _ref-tasks-configure_ptest_base: | ||
64 | |||
65 | ``do_configure_ptest_base`` | ||
66 | --------------------------- | ||
67 | |||
68 | Configures the runtime test suite included in the software being built. | ||
69 | |||
70 | .. _ref-tasks-deploy: | ||
71 | |||
72 | ``do_deploy`` | ||
73 | ------------- | ||
74 | |||
75 | Writes output files that are to be deployed to | ||
76 | ``${``\ :term:`DEPLOY_DIR_IMAGE`\ ``}``. The | ||
77 | task runs with the current working directory set to | ||
78 | ``${``\ :term:`B`\ ``}``. | ||
79 | |||
80 | Recipes implementing this task should inherit the | ||
81 | :ref:`deploy <ref-classes-deploy>` class and should write the output | ||
82 | to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be | ||
83 | confused with ``${DEPLOY_DIR}``. The ``deploy`` class sets up | ||
84 | ``do_deploy`` as a shared state (sstate) task that can be accelerated | ||
85 | through sstate use. The sstate mechanism takes care of copying the | ||
86 | output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``. | ||
87 | |||
88 | .. note:: | ||
89 | |||
90 | Do not write the output directly to | ||
91 | ${DEPLOY_DIR_IMAGE} | ||
92 | , as this causes the sstate mechanism to malfunction. | ||
93 | |||
94 | The ``do_deploy`` task is not added as a task by default and | ||
95 | consequently needs to be added manually. If you want the task to run | ||
96 | after :ref:`ref-tasks-compile`, you can add it by doing | ||
97 | the following: addtask deploy after do_compile Adding ``do_deploy`` | ||
98 | after other tasks works the same way. | ||
99 | |||
100 | .. note:: | ||
101 | |||
102 | You do not need to add | ||
103 | before do_build | ||
104 | to the | ||
105 | addtask | ||
106 | command (though it is harmless), because the | ||
107 | base | ||
108 | class contains the following: | ||
109 | :: | ||
110 | |||
111 | do_build[recrdeptask] += "do_deploy" | ||
112 | |||
113 | |||
114 | See the " | ||
115 | Dependencies | ||
116 | " section in the BitBake User Manual for more information. | ||
117 | |||
118 | If the ``do_deploy`` task re-executes, any previous output is removed | ||
119 | (i.e. "cleaned"). | ||
120 | |||
121 | .. _ref-tasks-fetch: | ||
122 | |||
123 | ``do_fetch`` | ||
124 | ------------ | ||
125 | |||
126 | Fetches the source code. This task uses the | ||
127 | :term:`SRC_URI` variable and the argument's prefix to | ||
128 | determine the correct :ref:`fetcher <bitbake:bb-fetchers>` | ||
129 | module. | ||
130 | |||
131 | .. _ref-tasks-image: | ||
132 | |||
133 | ``do_image`` | ||
134 | ------------ | ||
135 | |||
136 | Starts the image generation process. The ``do_image`` task runs after | ||
137 | the OpenEmbedded build system has run the | ||
138 | :ref:`ref-tasks-rootfs` task during which packages are | ||
139 | identified for installation into the image and the root filesystem is | ||
140 | created, complete with post-processing. | ||
141 | |||
142 | The ``do_image`` task performs pre-processing on the image through the | ||
143 | :term:`IMAGE_PREPROCESS_COMMAND` and | ||
144 | dynamically generates supporting ``do_image_*`` tasks as needed. | ||
145 | |||
146 | For more information on image creation, see the ":ref:`image-generation-dev-environment`" | ||
147 | section in the Yocto Project Overview and Concepts Manual. | ||
148 | |||
149 | .. _ref-tasks-image-complete: | ||
150 | |||
151 | ``do_image_complete`` | ||
152 | --------------------- | ||
153 | |||
154 | Completes the image generation process. The ``do_image_complete`` task | ||
155 | runs after the OpenEmbedded build system has run the | ||
156 | :ref:`ref-tasks-image` task during which image | ||
157 | pre-processing occurs and through dynamically generated ``do_image_*`` | ||
158 | tasks the image is constructed. | ||
159 | |||
160 | The ``do_image_complete`` task performs post-processing on the image | ||
161 | through the | ||
162 | :term:`IMAGE_POSTPROCESS_COMMAND`. | ||
163 | |||
164 | For more information on image creation, see the | ||
165 | ":ref:`image-generation-dev-environment`" | ||
166 | section in the Yocto Project Overview and Concepts Manual. | ||
167 | |||
168 | .. _ref-tasks-install: | ||
169 | |||
170 | ``do_install`` | ||
171 | -------------- | ||
172 | |||
173 | Copies files that are to be packaged into the holding area | ||
174 | ``${``\ :term:`D`\ ``}``. This task runs with the current | ||
175 | working directory set to ``${``\ :term:`B`\ ``}``, which is the | ||
176 | compilation directory. The ``do_install`` task, as well as other tasks | ||
177 | that either directly or indirectly depend on the installed files (e.g. | ||
178 | :ref:`ref-tasks-package`, ``do_package_write_*``, and | ||
179 | :ref:`ref-tasks-rootfs`), run under | ||
180 | :ref:`fakeroot <overview-manual/overview-manual-concepts:fakeroot and pseudo>`. | ||
181 | |||
182 | .. note:: | ||
183 | |||
184 | When installing files, be careful not to set the owner and group IDs | ||
185 | of the installed files to unintended values. Some methods of copying | ||
186 | files, notably when using the recursive ``cp`` command, can preserve | ||
187 | the UID and/or GID of the original file, which is usually not what | ||
188 | you want. The ``host-user-contaminated`` QA check checks for files | ||
189 | that probably have the wrong ownership. | ||
190 | |||
191 | Safe methods for installing files include the following: | ||
192 | |||
193 | - The ``install`` utility. This utility is the preferred method. | ||
194 | |||
195 | - The ``cp`` command with the "--no-preserve=ownership" option. | ||
196 | |||
197 | - The ``tar`` command with the "--no-same-owner" option. See the | ||
198 | ``bin_package.bbclass`` file in the ``meta/classes`` directory of | ||
199 | the :term:`Source Directory` for an example. | ||
200 | |||
201 | .. _ref-tasks-install_ptest_base: | ||
202 | |||
203 | ``do_install_ptest_base`` | ||
204 | ------------------------- | ||
205 | |||
206 | Copies the runtime test suite files from the compilation directory to a | ||
207 | holding area. | ||
208 | |||
209 | .. _ref-tasks-package: | ||
210 | |||
211 | ``do_package`` | ||
212 | -------------- | ||
213 | |||
214 | Analyzes the content of the holding area | ||
215 | ``${``\ :term:`D`\ ``}`` and splits the content into subsets | ||
216 | based on available packages and files. This task makes use of the | ||
217 | :term:`PACKAGES` and :term:`FILES` | ||
218 | variables. | ||
219 | |||
220 | The ``do_package`` task, in conjunction with the | ||
221 | :ref:`ref-tasks-packagedata` task, also saves some | ||
222 | important package metadata. For additional information, see the | ||
223 | :term:`PKGDESTWORK` variable and the | ||
224 | ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`" | ||
225 | section in the Yocto Project Overview and Concepts Manual. | ||
226 | |||
227 | .. _ref-tasks-package_qa: | ||
228 | |||
229 | ``do_package_qa`` | ||
230 | ----------------- | ||
231 | |||
232 | Runs QA checks on packaged files. For more information on these checks, | ||
233 | see the :ref:`insane <ref-classes-insane>` class. | ||
234 | |||
235 | .. _ref-tasks-package_write_deb: | ||
236 | |||
237 | ``do_package_write_deb`` | ||
238 | ------------------------ | ||
239 | |||
240 | Creates Debian packages (i.e. ``*.deb`` files) and places them in the | ||
241 | ``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory in | ||
242 | the package feeds area. For more information, see the | ||
243 | ":ref:`package-feeds-dev-environment`" section in | ||
244 | the Yocto Project Overview and Concepts Manual. | ||
245 | |||
246 | .. _ref-tasks-package_write_ipk: | ||
247 | |||
248 | ``do_package_write_ipk`` | ||
249 | ------------------------ | ||
250 | |||
251 | Creates IPK packages (i.e. ``*.ipk`` files) and places them in the | ||
252 | ``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory in | ||
253 | the package feeds area. For more information, see the | ||
254 | ":ref:`package-feeds-dev-environment`" section in | ||
255 | the Yocto Project Overview and Concepts Manual. | ||
256 | |||
257 | .. _ref-tasks-package_write_rpm: | ||
258 | |||
259 | ``do_package_write_rpm`` | ||
260 | ------------------------ | ||
261 | |||
262 | Creates RPM packages (i.e. ``*.rpm`` files) and places them in the | ||
263 | ``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory in | ||
264 | the package feeds area. For more information, see the | ||
265 | ":ref:`package-feeds-dev-environment`" section in | ||
266 | the Yocto Project Overview and Concepts Manual. | ||
267 | |||
268 | .. _ref-tasks-package_write_tar: | ||
269 | |||
270 | ``do_package_write_tar`` | ||
271 | ------------------------ | ||
272 | |||
273 | Creates tarballs and places them in the | ||
274 | ``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory in | ||
275 | the package feeds area. For more information, see the | ||
276 | ":ref:`package-feeds-dev-environment`" section in | ||
277 | the Yocto Project Overview and Concepts Manual. | ||
278 | |||
279 | .. _ref-tasks-packagedata: | ||
280 | |||
281 | ``do_packagedata`` | ||
282 | ------------------ | ||
283 | |||
284 | Saves package metadata generated by the | ||
285 | :ref:`ref-tasks-package` task in | ||
286 | :term:`PKGDATA_DIR` to make it available globally. | ||
287 | |||
288 | .. _ref-tasks-patch: | ||
289 | |||
290 | ``do_patch`` | ||
291 | ------------ | ||
292 | |||
293 | Locates patch files and applies them to the source code. | ||
294 | |||
295 | After fetching and unpacking source files, the build system uses the | ||
296 | recipe's :term:`SRC_URI` statements | ||
297 | to locate and apply patch files to the source code. | ||
298 | |||
299 | .. note:: | ||
300 | |||
301 | The build system uses the | ||
302 | FILESPATH | ||
303 | variable to determine the default set of directories when searching | ||
304 | for patches. | ||
305 | |||
306 | Patch files, by default, are ``*.patch`` and ``*.diff`` files created | ||
307 | and kept in a subdirectory of the directory holding the recipe file. For | ||
308 | example, consider the | ||
309 | :yocto_git:`bluez5 </cgit/cgit.cgi/poky/tree/meta/recipes-connectivity/bluez5>` | ||
310 | recipe from the OE-Core layer (i.e. ``poky/meta``): | ||
311 | :: | ||
312 | |||
313 | poky/meta/recipes-connectivity/bluez5 | ||
314 | |||
315 | This recipe has two patch files located here: | ||
316 | :: | ||
317 | |||
318 | poky/meta/recipes-connectivity/bluez5/bluez5 | ||
319 | |||
320 | In the ``bluez5`` recipe, the ``SRC_URI`` statements point to the source | ||
321 | and patch files needed to build the package. | ||
322 | |||
323 | .. note:: | ||
324 | |||
325 | In the case for the | ||
326 | bluez5_5.48.bb | ||
327 | recipe, the | ||
328 | SRC_URI | ||
329 | statements are from an include file | ||
330 | bluez5.inc | ||
331 | . | ||
332 | |||
333 | As mentioned earlier, the build system treats files whose file types are | ||
334 | ``.patch`` and ``.diff`` as patch files. However, you can use the | ||
335 | "apply=yes" parameter with the ``SRC_URI`` statement to indicate any | ||
336 | file as a patch file: | ||
337 | :: | ||
338 | |||
339 | SRC_URI = " \\ | ||
340 | git://path_to_repo/some_package \\ | ||
341 | file://file;apply=yes \\ | ||
342 | " | ||
343 | |||
344 | Conversely, if you have a directory full of patch files and you want to | ||
345 | exclude some so that the ``do_patch`` task does not apply them during | ||
346 | the patch phase, you can use the "apply=no" parameter with the | ||
347 | ``SRC_URI`` statement: | ||
348 | :: | ||
349 | |||
350 | SRC_URI = " \ | ||
351 | git://path_to_repo/some_package \ | ||
352 | file://path_to_lots_of_patch_files \ | ||
353 | file://path_to_lots_of_patch_files/patch_file5;apply=no \ | ||
354 | " | ||
355 | |||
356 | In the | ||
357 | previous example, assuming all the files in the directory holding the | ||
358 | patch files end with either ``.patch`` or ``.diff``, every file would be | ||
359 | applied as a patch by default except for the patch_file5 patch. | ||
360 | |||
361 | You can find out more about the patching process in the | ||
362 | ":ref:`patching-dev-environment`" section in | ||
363 | the Yocto Project Overview and Concepts Manual and the | ||
364 | ":ref:`new-recipe-patching-code`" section in the | ||
365 | Yocto Project Development Tasks Manual. | ||
366 | |||
367 | .. _ref-tasks-populate_lic: | ||
368 | |||
369 | ``do_populate_lic`` | ||
370 | ------------------- | ||
371 | |||
372 | Writes license information for the recipe that is collected later when | ||
373 | the image is constructed. | ||
374 | |||
375 | .. _ref-tasks-populate_sdk: | ||
376 | |||
377 | ``do_populate_sdk`` | ||
378 | ------------------- | ||
379 | |||
380 | Creates the file and directory structure for an installable SDK. See the | ||
381 | ":ref:`sdk-generation-dev-environment`" | ||
382 | section in the Yocto Project Overview and Concepts Manual for more | ||
383 | information. | ||
384 | |||
385 | .. _ref-tasks-populate_sdk_ext: | ||
386 | |||
387 | ``do_populate_sdk_ext`` | ||
388 | ----------------------- | ||
389 | |||
390 | Creates the file and directory structure for an installable extensible | ||
391 | SDK (eSDK). See the ":ref:`sdk-generation-dev-environment`" | ||
392 | section in the Yocto Project Overview and Concepts Manual for more | ||
393 | information. | ||
394 | |||
395 | |||
396 | .. _ref-tasks-populate_sysroot: | ||
397 | |||
398 | ``do_populate_sysroot`` | ||
399 | ----------------------- | ||
400 | |||
401 | Stages (copies) a subset of the files installed by the | ||
402 | :ref:`ref-tasks-install` task into the appropriate | ||
403 | sysroot. For information on how to access these files from other | ||
404 | recipes, see the :term:`STAGING_DIR* <STAGING_DIR_HOST>` variables. | ||
405 | Directories that would typically not be needed by other recipes at build | ||
406 | time (e.g. ``/etc``) are not copied by default. | ||
407 | |||
408 | For information on what directories are copied by default, see the | ||
409 | :term:`SYSROOT_DIRS* <SYSROOT_DIRS>` variables. You can change | ||
410 | these variables inside your recipe if you need to make additional (or | ||
411 | fewer) directories available to other recipes at build time. | ||
412 | |||
413 | The ``do_populate_sysroot`` task is a shared state (sstate) task, which | ||
414 | means that the task can be accelerated through sstate use. Realize also | ||
415 | that if the task is re-executed, any previous output is removed (i.e. | ||
416 | "cleaned"). | ||
417 | |||
418 | .. _ref-tasks-prepare_recipe_sysroot: | ||
419 | |||
420 | ``do_prepare_recipe_sysroot`` | ||
421 | ----------------------------- | ||
422 | |||
423 | Installs the files into the individual recipe specific sysroots (i.e. | ||
424 | ``recipe-sysroot`` and ``recipe-sysroot-native`` under | ||
425 | ``${``\ :term:`WORKDIR`\ ``}`` based upon the | ||
426 | dependencies specified by :term:`DEPENDS`). See the | ||
427 | ":ref:`staging <ref-classes-staging>`" class for more information. | ||
428 | |||
429 | .. _ref-tasks-rm_work: | ||
430 | |||
431 | ``do_rm_work`` | ||
432 | -------------- | ||
433 | |||
434 | Removes work files after the OpenEmbedded build system has finished with | ||
435 | them. You can learn more by looking at the | ||
436 | ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section. | ||
437 | |||
438 | .. _ref-tasks-unpack: | ||
439 | |||
440 | ``do_unpack`` | ||
441 | ------------- | ||
442 | |||
443 | Unpacks the source code into a working directory pointed to by | ||
444 | ``${``\ :term:`WORKDIR`\ ``}``. The :term:`S` | ||
445 | variable also plays a role in where unpacked source files ultimately | ||
446 | reside. For more information on how source files are unpacked, see the | ||
447 | ":ref:`source-fetching-dev-environment`" | ||
448 | section in the Yocto Project Overview and Concepts Manual and also see | ||
449 | the ``WORKDIR`` and ``S`` variable descriptions. | ||
450 | |||
451 | Manually Called Tasks | ||
452 | ===================== | ||
453 | |||
454 | These tasks are typically manually triggered (e.g. by using the | ||
455 | ``bitbake -c`` command-line option): | ||
456 | |||
457 | .. _ref-tasks-checkpkg: | ||
458 | |||
459 | ``do_checkpkg`` | ||
460 | --------------- | ||
461 | |||
462 | Provides information about the recipe including its upstream version and | ||
463 | status. The upstream version and status reveals whether or not a version | ||
464 | of the recipe exists upstream and a status of not updated, updated, or | ||
465 | unknown. | ||
466 | |||
467 | To check the upstream version and status of a recipe, use the following | ||
468 | devtool commands: | ||
469 | :: | ||
470 | |||
471 | $ devtool latest-version | ||
472 | $ devtool check-upgrade-status | ||
473 | |||
474 | See the ":ref:`ref-manual/ref-devtool-reference:\`\`devtool\`\` quick reference`" | ||
475 | chapter for more information on | ||
476 | ``devtool``. See the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" | ||
477 | section for information on checking the upgrade status of a recipe. | ||
478 | |||
479 | To build the ``checkpkg`` task, use the ``bitbake`` command with the | ||
480 | "-c" option and task name: | ||
481 | :: | ||
482 | |||
483 | $ bitbake core-image-minimal -c checkpkg | ||
484 | |||
485 | By default, the results are stored in :term:`$LOG_DIR <LOG_DIR>` (e.g. | ||
486 | ``$BUILD_DIR/tmp/log``). | ||
487 | |||
488 | .. _ref-tasks-checkuri: | ||
489 | |||
490 | ``do_checkuri`` | ||
491 | --------------- | ||
492 | |||
493 | Validates the :term:`SRC_URI` value. | ||
494 | |||
495 | .. _ref-tasks-clean: | ||
496 | |||
497 | ``do_clean`` | ||
498 | ------------ | ||
499 | |||
500 | Removes all output files for a target from the | ||
501 | :ref:`ref-tasks-unpack` task forward (i.e. ``do_unpack``, | ||
502 | :ref:`ref-tasks-configure`, | ||
503 | :ref:`ref-tasks-compile`, | ||
504 | :ref:`ref-tasks-install`, and | ||
505 | :ref:`ref-tasks-package`). | ||
506 | |||
507 | You can run this task using BitBake as follows: | ||
508 | :: | ||
509 | |||
510 | $ bitbake -c clean recipe | ||
511 | |||
512 | Running this task does not remove the | ||
513 | :ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>` cache files. | ||
514 | Consequently, if no changes have been made and the recipe is rebuilt | ||
515 | after cleaning, output files are simply restored from the sstate cache. | ||
516 | If you want to remove the sstate cache files for the recipe, you need to | ||
517 | use the :ref:`ref-tasks-cleansstate` task instead | ||
518 | (i.e. ``bitbake -c cleansstate`` recipe). | ||
519 | |||
520 | .. _ref-tasks-cleanall: | ||
521 | |||
522 | ``do_cleanall`` | ||
523 | --------------- | ||
524 | |||
525 | Removes all output files, shared state | ||
526 | (:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) cache, and | ||
527 | downloaded source files for a target (i.e. the contents of | ||
528 | :term:`DL_DIR`). Essentially, the ``do_cleanall`` task is | ||
529 | identical to the :ref:`ref-tasks-cleansstate` task | ||
530 | with the added removal of downloaded source files. | ||
531 | |||
532 | You can run this task using BitBake as follows: | ||
533 | :: | ||
534 | |||
535 | $ bitbake -c cleanall recipe | ||
536 | |||
537 | Typically, you would not normally use the ``cleanall`` task. Do so only | ||
538 | if you want to start fresh with the :ref:`ref-tasks-fetch` | ||
539 | task. | ||
540 | |||
541 | .. _ref-tasks-cleansstate: | ||
542 | |||
543 | ``do_cleansstate`` | ||
544 | ------------------ | ||
545 | |||
546 | Removes all output files and shared state | ||
547 | (:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) cache for a | ||
548 | target. Essentially, the ``do_cleansstate`` task is identical to the | ||
549 | :ref:`ref-tasks-clean` task with the added removal of | ||
550 | shared state (`:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) | ||
551 | cache. | ||
552 | |||
553 | You can run this task using BitBake as follows: | ||
554 | :: | ||
555 | |||
556 | $ bitbake -c cleansstate recipe | ||
557 | |||
558 | When you run the ``do_cleansstate`` task, the OpenEmbedded build system | ||
559 | no longer uses any sstate. Consequently, building the recipe from | ||
560 | scratch is guaranteed. | ||
561 | |||
562 | .. note:: | ||
563 | |||
564 | The | ||
565 | do_cleansstate | ||
566 | task cannot remove sstate from a remote sstate mirror. If you need to | ||
567 | build a target from scratch using remote mirrors, use the "-f" option | ||
568 | as follows: | ||
569 | :: | ||
570 | |||
571 | $ bitbake -f -c do_cleansstate target | ||
572 | |||
573 | |||
574 | .. _ref-tasks-devpyshell: | ||
575 | |||
576 | ``do_devpyshell`` | ||
577 | ----------------- | ||
578 | |||
579 | Starts a shell in which an interactive Python interpreter allows you to | ||
580 | interact with the BitBake build environment. From within this shell, you | ||
581 | can directly examine and set bits from the data store and execute | ||
582 | functions as if within the BitBake environment. See the ":ref:`platdev-appdev-devpyshell`" section in | ||
583 | the Yocto Project Development Tasks Manual for more information about | ||
584 | using ``devpyshell``. | ||
585 | |||
586 | .. _ref-tasks-devshell: | ||
587 | |||
588 | ``do_devshell`` | ||
589 | --------------- | ||
590 | |||
591 | Starts a shell whose environment is set up for development, debugging, | ||
592 | or both. See the ":ref:`platdev-appdev-devshell`" section in the | ||
593 | Yocto Project Development Tasks Manual for more information about using | ||
594 | ``devshell``. | ||
595 | |||
596 | .. _ref-tasks-listtasks: | ||
597 | |||
598 | ``do_listtasks`` | ||
599 | ---------------- | ||
600 | |||
601 | Lists all defined tasks for a target. | ||
602 | |||
603 | .. _ref-tasks-package_index: | ||
604 | |||
605 | ``do_package_index`` | ||
606 | -------------------- | ||
607 | |||
608 | Creates or updates the index in the `:ref:`package-feeds-dev-environment` area. | ||
609 | |||
610 | .. note:: | ||
611 | |||
612 | This task is not triggered with the | ||
613 | bitbake -c | ||
614 | command-line option as are the other tasks in this section. Because | ||
615 | this task is specifically for the | ||
616 | package-index | ||
617 | recipe, you run it using | ||
618 | bitbake package-index | ||
619 | . | ||
620 | |||
621 | Image-Related Tasks | ||
622 | =================== | ||
623 | |||
624 | The following tasks are applicable to image recipes. | ||
625 | |||
626 | .. _ref-tasks-bootimg: | ||
627 | |||
628 | ``do_bootimg`` | ||
629 | -------------- | ||
630 | |||
631 | Creates a bootable live image. See the | ||
632 | :term:`IMAGE_FSTYPES` variable for additional | ||
633 | information on live image types. | ||
634 | |||
635 | .. _ref-tasks-bundle_initramfs: | ||
636 | |||
637 | ``do_bundle_initramfs`` | ||
638 | ----------------------- | ||
639 | |||
640 | Combines an initial RAM disk (initramfs) image and kernel together to | ||
641 | form a single image. The | ||
642 | :term:`CONFIG_INITRAMFS_SOURCE` variable | ||
643 | has some more information about these types of images. | ||
644 | |||
645 | .. _ref-tasks-rootfs: | ||
646 | |||
647 | ``do_rootfs`` | ||
648 | ------------- | ||
649 | |||
650 | Creates the root filesystem (file and directory structure) for an image. | ||
651 | See the ":ref:`image-generation-dev-environment`" | ||
652 | section in the Yocto Project Overview and Concepts Manual for more | ||
653 | information on how the root filesystem is created. | ||
654 | |||
655 | .. _ref-tasks-testimage: | ||
656 | |||
657 | ``do_testimage`` | ||
658 | ---------------- | ||
659 | |||
660 | Boots an image and performs runtime tests within the image. For | ||
661 | information on automatically testing images, see the | ||
662 | ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" | ||
663 | section in the Yocto Project Development Tasks Manual. | ||
664 | |||
665 | .. _ref-tasks-testimage_auto: | ||
666 | |||
667 | ``do_testimage_auto`` | ||
668 | --------------------- | ||
669 | |||
670 | Boots an image and performs runtime tests within the image immediately | ||
671 | after it has been built. This task is enabled when you set | ||
672 | :term:`TESTIMAGE_AUTO` equal to "1". | ||
673 | |||
674 | For information on automatically testing images, see the | ||
675 | ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" | ||
676 | section in the Yocto Project Development Tasks Manual. | ||
677 | |||
678 | Kernel-Related Tasks | ||
679 | ==================== | ||
680 | |||
681 | The following tasks are applicable to kernel recipes. Some of these | ||
682 | tasks (e.g. the :ref:`ref-tasks-menuconfig` task) are | ||
683 | also applicable to recipes that use Linux kernel style configuration | ||
684 | such as the BusyBox recipe. | ||
685 | |||
686 | .. _ref-tasks-compile_kernelmodules: | ||
687 | |||
688 | ``do_compile_kernelmodules`` | ||
689 | ---------------------------- | ||
690 | |||
691 | Runs the step that builds the kernel modules (if needed). Building a | ||
692 | kernel consists of two steps: 1) the kernel (``vmlinux``) is built, and | ||
693 | 2) the modules are built (i.e. ``make modules``). | ||
694 | |||
695 | .. _ref-tasks-diffconfig: | ||
696 | |||
697 | ``do_diffconfig`` | ||
698 | ----------------- | ||
699 | |||
700 | When invoked by the user, this task creates a file containing the | ||
701 | differences between the original config as produced by | ||
702 | :ref:`ref-tasks-kernel_configme` task and the | ||
703 | changes made by the user with other methods (i.e. using | ||
704 | (:ref:`ref-tasks-kernel_menuconfig`). Once the | ||
705 | file of differences is created, it can be used to create a config | ||
706 | fragment that only contains the differences. You can invoke this task | ||
707 | from the command line as follows: | ||
708 | :: | ||
709 | |||
710 | $ bitbake linux-yocto -c diffconfig | ||
711 | |||
712 | For more information, see the | ||
713 | ":ref:`kernel-dev/kernel-dev-common:creating configuration fragments`" | ||
714 | section in the Yocto Project Linux Kernel Development Manual. | ||
715 | |||
716 | .. _ref-tasks-kernel_checkout: | ||
717 | |||
718 | ``do_kernel_checkout`` | ||
719 | ---------------------- | ||
720 | |||
721 | Converts the newly unpacked kernel source into a form with which the | ||
722 | OpenEmbedded build system can work. Because the kernel source can be | ||
723 | fetched in several different ways, the ``do_kernel_checkout`` task makes | ||
724 | sure that subsequent tasks are given a clean working tree copy of the | ||
725 | kernel with the correct branches checked out. | ||
726 | |||
727 | .. _ref-tasks-kernel_configcheck: | ||
728 | |||
729 | ``do_kernel_configcheck`` | ||
730 | ------------------------- | ||
731 | |||
732 | Validates the configuration produced by the | ||
733 | :ref:`ref-tasks-kernel_menuconfig` task. The | ||
734 | ``do_kernel_configcheck`` task produces warnings when a requested | ||
735 | configuration does not appear in the final ``.config`` file or when you | ||
736 | override a policy configuration in a hardware configuration fragment. | ||
737 | You can run this task explicitly and view the output by using the | ||
738 | following command: | ||
739 | :: | ||
740 | |||
741 | $ bitbake linux-yocto -c kernel_configcheck -f | ||
742 | |||
743 | For more information, see the | ||
744 | ":ref:`kernel-dev/kernel-dev-common:validating configuration`" | ||
745 | section in the Yocto Project Linux Kernel Development Manual. | ||
746 | |||
747 | .. _ref-tasks-kernel_configme: | ||
748 | |||
749 | ``do_kernel_configme`` | ||
750 | ---------------------- | ||
751 | |||
752 | After the kernel is patched by the :ref:`ref-tasks-patch` | ||
753 | task, the ``do_kernel_configme`` task assembles and merges all the | ||
754 | kernel config fragments into a merged configuration that can then be | ||
755 | passed to the kernel configuration phase proper. This is also the time | ||
756 | during which user-specified defconfigs are applied if present, and where | ||
757 | configuration modes such as ``--allnoconfig`` are applied. | ||
758 | |||
759 | .. _ref-tasks-kernel_menuconfig: | ||
760 | |||
761 | ``do_kernel_menuconfig`` | ||
762 | ------------------------ | ||
763 | |||
764 | Invoked by the user to manipulate the ``.config`` file used to build a | ||
765 | linux-yocto recipe. This task starts the Linux kernel configuration | ||
766 | tool, which you then use to modify the kernel configuration. | ||
767 | |||
768 | .. note:: | ||
769 | |||
770 | You can also invoke this tool from the command line as follows: | ||
771 | :: | ||
772 | |||
773 | $ bitbake linux-yocto -c menuconfig | ||
774 | |||
775 | |||
776 | See the ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``" | ||
777 | section in the Yocto Project Linux Kernel Development Manual for more | ||
778 | information on this configuration tool. | ||
779 | |||
780 | .. _ref-tasks-kernel_metadata: | ||
781 | |||
782 | ``do_kernel_metadata`` | ||
783 | ---------------------- | ||
784 | |||
785 | Collects all the features required for a given kernel build, whether the | ||
786 | features come from :term:`SRC_URI` or from Git | ||
787 | repositories. After collection, the ``do_kernel_metadata`` task | ||
788 | processes the features into a series of config fragments and patches, | ||
789 | which can then be applied by subsequent tasks such as | ||
790 | :ref:`ref-tasks-patch` and | ||
791 | :ref:`ref-tasks-kernel_configme`. | ||
792 | |||
793 | .. _ref-tasks-menuconfig: | ||
794 | |||
795 | ``do_menuconfig`` | ||
796 | ----------------- | ||
797 | |||
798 | Runs ``make menuconfig`` for the kernel. For information on | ||
799 | ``menuconfig``, see the | ||
800 | ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``" | ||
801 | section in the Yocto Project Linux Kernel Development Manual. | ||
802 | |||
803 | .. _ref-tasks-savedefconfig: | ||
804 | |||
805 | ``do_savedefconfig`` | ||
806 | -------------------- | ||
807 | |||
808 | When invoked by the user, creates a defconfig file that can be used | ||
809 | instead of the default defconfig. The saved defconfig contains the | ||
810 | differences between the default defconfig and the changes made by the | ||
811 | user using other methods (i.e. the | ||
812 | :ref:`ref-tasks-kernel_menuconfig` task. You | ||
813 | can invoke the task using the following command: | ||
814 | :: | ||
815 | |||
816 | $ bitbake linux-yocto -c savedefconfig | ||
817 | |||
818 | .. _ref-tasks-shared_workdir: | ||
819 | |||
820 | ``do_shared_workdir`` | ||
821 | --------------------- | ||
822 | |||
823 | After the kernel has been compiled but before the kernel modules have | ||
824 | been compiled, this task copies files required for module builds and | ||
825 | which are generated from the kernel build into the shared work | ||
826 | directory. With these copies successfully copied, the | ||
827 | :ref:`ref-tasks-compile_kernelmodules` task | ||
828 | can successfully build the kernel modules in the next step of the build. | ||
829 | |||
830 | .. _ref-tasks-sizecheck: | ||
831 | |||
832 | ``do_sizecheck`` | ||
833 | ---------------- | ||
834 | |||
835 | After the kernel has been built, this task checks the size of the | ||
836 | stripped kernel image against | ||
837 | :term:`KERNEL_IMAGE_MAXSIZE`. If that | ||
838 | variable was set and the size of the stripped kernel exceeds that size, | ||
839 | the kernel build produces a warning to that effect. | ||
840 | |||
841 | .. _ref-tasks-strip: | ||
842 | |||
843 | ``do_strip`` | ||
844 | ------------ | ||
845 | |||
846 | If ``KERNEL_IMAGE_STRIP_EXTRA_SECTIONS`` is defined, this task strips | ||
847 | the sections named in that variable from ``vmlinux``. This stripping is | ||
848 | typically used to remove nonessential sections such as ``.comment`` | ||
849 | sections from a size-sensitive configuration. | ||
850 | |||
851 | .. _ref-tasks-validate_branches: | ||
852 | |||
853 | ``do_validate_branches`` | ||
854 | ------------------------ | ||
855 | |||
856 | After the kernel is unpacked but before it is patched, this task makes | ||
857 | sure that the machine and metadata branches as specified by the | ||
858 | :term:`SRCREV` variables actually exist on the specified | ||
859 | branches. If these branches do not exist and | ||
860 | :term:`AUTOREV` is not being used, the | ||
861 | ``do_validate_branches`` task fails during the build. | ||
862 | |||
863 | Miscellaneous Tasks | ||
864 | =================== | ||
865 | |||
866 | The following sections describe miscellaneous tasks. | ||
867 | |||
868 | .. _ref-tasks-spdx: | ||
869 | |||
870 | ``do_spdx`` | ||
871 | ----------- | ||
872 | |||
873 | A build stage that takes the source code and scans it on a remote | ||
874 | FOSSOLOGY server in order to produce an SPDX document. This task applies | ||
875 | only to the :ref:`spdx <ref-classes-spdx>` class. | ||