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