blob: 970b0839423f4fc04e3a35c5425356aa0dbe7c39 [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
Andrew Geissler09036742021-06-25 14:25:14 -050060file is found or the :term:`CLEANBROKEN` variable is set to "1", the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050061``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 Geisslerc926e172021-05-07 16:11:35 -050096the following::
Andrew Geissler4c19ea12020-10-27 13:52:24 -050097
98 addtask deploy after do_compile
99
100Adding ``do_deploy`` after other tasks works the same way.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500101
102.. note::
103
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500104 You do not need to add ``before do_build`` to the ``addtask`` command
Andrew Geisslerc926e172021-05-07 16:11:35 -0500105 (though it is harmless), because the ``base`` class contains the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500106
107 do_build[recrdeptask] += "do_deploy"
108
109
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500110 See the ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`"
111 section in the BitBake User Manual for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112
113If the ``do_deploy`` task re-executes, any previous output is removed
114(i.e. "cleaned").
115
116.. _ref-tasks-fetch:
117
118``do_fetch``
119------------
120
121Fetches the source code. This task uses the
122:term:`SRC_URI` variable and the argument's prefix to
Andrew Geissler09209ee2020-12-13 08:44:15 -0600123determine the correct :ref:`fetcher <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500124module.
125
126.. _ref-tasks-image:
127
128``do_image``
129------------
130
131Starts the image generation process. The ``do_image`` task runs after
132the OpenEmbedded build system has run the
133:ref:`ref-tasks-rootfs` task during which packages are
134identified for installation into the image and the root filesystem is
135created, complete with post-processing.
136
137The ``do_image`` task performs pre-processing on the image through the
138:term:`IMAGE_PREPROCESS_COMMAND` and
139dynamically generates supporting ``do_image_*`` tasks as needed.
140
Andrew Geissler09209ee2020-12-13 08:44:15 -0600141For more information on image creation, see the ":ref:`overview-manual/concepts:image generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500142section in the Yocto Project Overview and Concepts Manual.
143
144.. _ref-tasks-image-complete:
145
146``do_image_complete``
147---------------------
148
149Completes the image generation process. The ``do_image_complete`` task
150runs after the OpenEmbedded build system has run the
151:ref:`ref-tasks-image` task during which image
152pre-processing occurs and through dynamically generated ``do_image_*``
153tasks the image is constructed.
154
155The ``do_image_complete`` task performs post-processing on the image
156through the
157:term:`IMAGE_POSTPROCESS_COMMAND`.
158
159For more information on image creation, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600160":ref:`overview-manual/concepts:image generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500161section in the Yocto Project Overview and Concepts Manual.
162
163.. _ref-tasks-install:
164
165``do_install``
166--------------
167
168Copies files that are to be packaged into the holding area
169``${``\ :term:`D`\ ``}``. This task runs with the current
170working directory set to ``${``\ :term:`B`\ ``}``, which is the
171compilation directory. The ``do_install`` task, as well as other tasks
172that either directly or indirectly depend on the installed files (e.g.
173:ref:`ref-tasks-package`, ``do_package_write_*``, and
174:ref:`ref-tasks-rootfs`), run under
Andrew Geissler09209ee2020-12-13 08:44:15 -0600175:ref:`fakeroot <overview-manual/concepts:fakeroot and pseudo>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500176
177.. note::
178
179 When installing files, be careful not to set the owner and group IDs
180 of the installed files to unintended values. Some methods of copying
181 files, notably when using the recursive ``cp`` command, can preserve
182 the UID and/or GID of the original file, which is usually not what
183 you want. The ``host-user-contaminated`` QA check checks for files
184 that probably have the wrong ownership.
185
186 Safe methods for installing files include the following:
187
188 - The ``install`` utility. This utility is the preferred method.
189
190 - The ``cp`` command with the "--no-preserve=ownership" option.
191
192 - The ``tar`` command with the "--no-same-owner" option. See the
193 ``bin_package.bbclass`` file in the ``meta/classes`` directory of
194 the :term:`Source Directory` for an example.
195
196.. _ref-tasks-install_ptest_base:
197
198``do_install_ptest_base``
199-------------------------
200
201Copies the runtime test suite files from the compilation directory to a
202holding area.
203
204.. _ref-tasks-package:
205
206``do_package``
207--------------
208
209Analyzes the content of the holding area
210``${``\ :term:`D`\ ``}`` and splits the content into subsets
211based on available packages and files. This task makes use of the
212:term:`PACKAGES` and :term:`FILES`
213variables.
214
215The ``do_package`` task, in conjunction with the
216:ref:`ref-tasks-packagedata` task, also saves some
217important package metadata. For additional information, see the
218:term:`PKGDESTWORK` variable and the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600219":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500220section in the Yocto Project Overview and Concepts Manual.
221
222.. _ref-tasks-package_qa:
223
224``do_package_qa``
225-----------------
226
227Runs QA checks on packaged files. For more information on these checks,
228see the :ref:`insane <ref-classes-insane>` class.
229
230.. _ref-tasks-package_write_deb:
231
232``do_package_write_deb``
233------------------------
234
235Creates Debian packages (i.e. ``*.deb`` files) and places them in the
236``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory in
237the package feeds area. For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600238":ref:`overview-manual/concepts:package feeds`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500239the Yocto Project Overview and Concepts Manual.
240
241.. _ref-tasks-package_write_ipk:
242
243``do_package_write_ipk``
244------------------------
245
246Creates IPK packages (i.e. ``*.ipk`` files) and places them in the
247``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory in
248the package feeds area. For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600249":ref:`overview-manual/concepts:package feeds`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500250the Yocto Project Overview and Concepts Manual.
251
252.. _ref-tasks-package_write_rpm:
253
254``do_package_write_rpm``
255------------------------
256
257Creates RPM packages (i.e. ``*.rpm`` files) and places them in the
258``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory in
259the package feeds area. For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600260":ref:`overview-manual/concepts:package feeds`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500261the Yocto Project Overview and Concepts Manual.
262
263.. _ref-tasks-package_write_tar:
264
265``do_package_write_tar``
266------------------------
267
268Creates tarballs and places them in the
269``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory in
270the package feeds area. For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600271":ref:`overview-manual/concepts:package feeds`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500272the Yocto Project Overview and Concepts Manual.
273
274.. _ref-tasks-packagedata:
275
276``do_packagedata``
277------------------
278
279Saves package metadata generated by the
280:ref:`ref-tasks-package` task in
281:term:`PKGDATA_DIR` to make it available globally.
282
283.. _ref-tasks-patch:
284
285``do_patch``
286------------
287
288Locates patch files and applies them to the source code.
289
290After fetching and unpacking source files, the build system uses the
291recipe's :term:`SRC_URI` statements
292to locate and apply patch files to the source code.
293
294.. note::
295
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500296 The build system uses the :term:`FILESPATH` variable to determine the
297 default set of directories when searching for patches.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500298
299Patch files, by default, are ``*.patch`` and ``*.diff`` files created
300and kept in a subdirectory of the directory holding the recipe file. For
301example, consider the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600302:yocto_git:`bluez5 </poky/tree/meta/recipes-connectivity/bluez5>`
Andrew Geisslerc926e172021-05-07 16:11:35 -0500303recipe from the OE-Core layer (i.e. ``poky/meta``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500304
305 poky/meta/recipes-connectivity/bluez5
306
Andrew Geisslerc926e172021-05-07 16:11:35 -0500307This recipe has two patch files located here::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500308
309 poky/meta/recipes-connectivity/bluez5/bluez5
310
Andrew Geissler09036742021-06-25 14:25:14 -0500311In the ``bluez5`` recipe, the :term:`SRC_URI` statements point to the source
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500312and patch files needed to build the package.
313
314.. note::
315
Andrew Geissler09036742021-06-25 14:25:14 -0500316 In the case for the ``bluez5_5.48.bb`` recipe, the :term:`SRC_URI` statements
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500317 are from an include file ``bluez5.inc``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500318
319As mentioned earlier, the build system treats files whose file types are
320``.patch`` and ``.diff`` as patch files. However, you can use the
Andrew Geissler09036742021-06-25 14:25:14 -0500321"apply=yes" parameter with the :term:`SRC_URI` statement to indicate any
Andrew Geisslerc926e172021-05-07 16:11:35 -0500322file as a patch file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500323
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500324 SRC_URI = " \
325 git://path_to_repo/some_package \
326 file://file;apply=yes \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500327 "
328
329Conversely, if you have a directory full of patch files and you want to
330exclude some so that the ``do_patch`` task does not apply them during
331the patch phase, you can use the "apply=no" parameter with the
Andrew Geissler09036742021-06-25 14:25:14 -0500332:term:`SRC_URI` statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500333
334 SRC_URI = " \
335 git://path_to_repo/some_package \
336 file://path_to_lots_of_patch_files \
337 file://path_to_lots_of_patch_files/patch_file5;apply=no \
338 "
339
340In the
341previous example, assuming all the files in the directory holding the
342patch files end with either ``.patch`` or ``.diff``, every file would be
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500343applied as a patch by default except for the ``patch_file5`` patch.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500344
345You can find out more about the patching process in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600346":ref:`overview-manual/concepts:patching`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500347the Yocto Project Overview and Concepts Manual and the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600348":ref:`dev-manual/common-tasks:patching code`" section in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500349Yocto Project Development Tasks Manual.
350
351.. _ref-tasks-populate_lic:
352
353``do_populate_lic``
354-------------------
355
356Writes license information for the recipe that is collected later when
357the image is constructed.
358
359.. _ref-tasks-populate_sdk:
360
361``do_populate_sdk``
362-------------------
363
364Creates the file and directory structure for an installable SDK. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600365":ref:`overview-manual/concepts:sdk generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500366section in the Yocto Project Overview and Concepts Manual for more
367information.
368
369.. _ref-tasks-populate_sdk_ext:
370
371``do_populate_sdk_ext``
372-----------------------
373
374Creates the file and directory structure for an installable extensible
Andrew Geissler09209ee2020-12-13 08:44:15 -0600375SDK (eSDK). See the ":ref:`overview-manual/concepts:sdk generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500376section in the Yocto Project Overview and Concepts Manual for more
377information.
378
379
380.. _ref-tasks-populate_sysroot:
381
382``do_populate_sysroot``
383-----------------------
384
385Stages (copies) a subset of the files installed by the
386:ref:`ref-tasks-install` task into the appropriate
387sysroot. For information on how to access these files from other
388recipes, see the :term:`STAGING_DIR* <STAGING_DIR_HOST>` variables.
389Directories that would typically not be needed by other recipes at build
390time (e.g. ``/etc``) are not copied by default.
391
392For information on what directories are copied by default, see the
393:term:`SYSROOT_DIRS* <SYSROOT_DIRS>` variables. You can change
394these variables inside your recipe if you need to make additional (or
395fewer) directories available to other recipes at build time.
396
397The ``do_populate_sysroot`` task is a shared state (sstate) task, which
398means that the task can be accelerated through sstate use. Realize also
399that if the task is re-executed, any previous output is removed (i.e.
400"cleaned").
401
402.. _ref-tasks-prepare_recipe_sysroot:
403
404``do_prepare_recipe_sysroot``
405-----------------------------
406
407Installs the files into the individual recipe specific sysroots (i.e.
408``recipe-sysroot`` and ``recipe-sysroot-native`` under
409``${``\ :term:`WORKDIR`\ ``}`` based upon the
410dependencies specified by :term:`DEPENDS`). See the
411":ref:`staging <ref-classes-staging>`" class for more information.
412
413.. _ref-tasks-rm_work:
414
415``do_rm_work``
416--------------
417
418Removes work files after the OpenEmbedded build system has finished with
419them. You can learn more by looking at the
420":ref:`rm_work.bbclass <ref-classes-rm-work>`" section.
421
422.. _ref-tasks-unpack:
423
424``do_unpack``
425-------------
426
427Unpacks the source code into a working directory pointed to by
428``${``\ :term:`WORKDIR`\ ``}``. The :term:`S`
429variable also plays a role in where unpacked source files ultimately
430reside. For more information on how source files are unpacked, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600431":ref:`overview-manual/concepts:source fetching`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500432section in the Yocto Project Overview and Concepts Manual and also see
Andrew Geissler09036742021-06-25 14:25:14 -0500433the :term:`WORKDIR` and :term:`S` variable descriptions.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500434
435Manually Called Tasks
436=====================
437
438These tasks are typically manually triggered (e.g. by using the
439``bitbake -c`` command-line option):
440
441.. _ref-tasks-checkpkg:
442
443``do_checkpkg``
444---------------
445
446Provides information about the recipe including its upstream version and
447status. The upstream version and status reveals whether or not a version
448of the recipe exists upstream and a status of not updated, updated, or
449unknown.
450
451To check the upstream version and status of a recipe, use the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500452devtool commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500453
454 $ devtool latest-version
455 $ devtool check-upgrade-status
456
Andrew Geissler09209ee2020-12-13 08:44:15 -0600457See the ":ref:`ref-manual/devtool-reference:\`\`devtool\`\` quick reference`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500458chapter for more information on
459``devtool``. See the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`"
460section for information on checking the upgrade status of a recipe.
461
462To build the ``checkpkg`` task, use the ``bitbake`` command with the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500463"-c" option and task name::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500464
465 $ bitbake core-image-minimal -c checkpkg
466
467By default, the results are stored in :term:`$LOG_DIR <LOG_DIR>` (e.g.
468``$BUILD_DIR/tmp/log``).
469
470.. _ref-tasks-checkuri:
471
472``do_checkuri``
473---------------
474
475Validates the :term:`SRC_URI` value.
476
477.. _ref-tasks-clean:
478
479``do_clean``
480------------
481
482Removes all output files for a target from the
483:ref:`ref-tasks-unpack` task forward (i.e. ``do_unpack``,
484:ref:`ref-tasks-configure`,
485:ref:`ref-tasks-compile`,
486:ref:`ref-tasks-install`, and
487:ref:`ref-tasks-package`).
488
Andrew Geisslerc926e172021-05-07 16:11:35 -0500489You can run this task using BitBake as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500490
491 $ bitbake -c clean recipe
492
493Running this task does not remove the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600494:ref:`sstate <overview-manual/concepts:shared state cache>` cache files.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500495Consequently, if no changes have been made and the recipe is rebuilt
496after cleaning, output files are simply restored from the sstate cache.
497If you want to remove the sstate cache files for the recipe, you need to
498use the :ref:`ref-tasks-cleansstate` task instead
499(i.e. ``bitbake -c cleansstate`` recipe).
500
501.. _ref-tasks-cleanall:
502
503``do_cleanall``
504---------------
505
506Removes all output files, shared state
Andrew Geissler09209ee2020-12-13 08:44:15 -0600507(:ref:`sstate <overview-manual/concepts:shared state cache>`) cache, and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500508downloaded source files for a target (i.e. the contents of
509:term:`DL_DIR`). Essentially, the ``do_cleanall`` task is
510identical to the :ref:`ref-tasks-cleansstate` task
511with the added removal of downloaded source files.
512
Andrew Geisslerc926e172021-05-07 16:11:35 -0500513You can run this task using BitBake as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500514
515 $ bitbake -c cleanall recipe
516
517Typically, you would not normally use the ``cleanall`` task. Do so only
518if you want to start fresh with the :ref:`ref-tasks-fetch`
519task.
520
521.. _ref-tasks-cleansstate:
522
523``do_cleansstate``
524------------------
525
526Removes all output files and shared state
Andrew Geissler09209ee2020-12-13 08:44:15 -0600527(:ref:`sstate <overview-manual/concepts:shared state cache>`) cache for a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500528target. Essentially, the ``do_cleansstate`` task is identical to the
529:ref:`ref-tasks-clean` task with the added removal of
Andrew Geissler09209ee2020-12-13 08:44:15 -0600530shared state (:ref:`sstate <overview-manual/concepts:shared state cache>`)
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500531cache.
532
Andrew Geisslerc926e172021-05-07 16:11:35 -0500533You can run this task using BitBake as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500534
535 $ bitbake -c cleansstate recipe
536
537When you run the ``do_cleansstate`` task, the OpenEmbedded build system
538no longer uses any sstate. Consequently, building the recipe from
539scratch is guaranteed.
540
541.. note::
542
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500543 The ``do_cleansstate`` task cannot remove sstate from a remote sstate
544 mirror. If you need to build a target from scratch using remote mirrors, use
Andrew Geisslerc926e172021-05-07 16:11:35 -0500545 the "-f" option as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500546
547 $ bitbake -f -c do_cleansstate target
548
549
550.. _ref-tasks-devpyshell:
551
552``do_devpyshell``
553-----------------
554
555Starts a shell in which an interactive Python interpreter allows you to
556interact with the BitBake build environment. From within this shell, you
557can directly examine and set bits from the data store and execute
Andrew Geissler09209ee2020-12-13 08:44:15 -0600558functions 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 -0500559the Yocto Project Development Tasks Manual for more information about
560using ``devpyshell``.
561
562.. _ref-tasks-devshell:
563
564``do_devshell``
565---------------
566
567Starts a shell whose environment is set up for development, debugging,
Andrew Geissler09209ee2020-12-13 08:44:15 -0600568or both. See the ":ref:`dev-manual/common-tasks:using a development shell`" section in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500569Yocto Project Development Tasks Manual for more information about using
570``devshell``.
571
572.. _ref-tasks-listtasks:
573
574``do_listtasks``
575----------------
576
577Lists all defined tasks for a target.
578
579.. _ref-tasks-package_index:
580
581``do_package_index``
582--------------------
583
Andrew Geissler09209ee2020-12-13 08:44:15 -0600584Creates or updates the index in the :ref:`overview-manual/concepts:package feeds` area.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500585
586.. note::
587
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500588 This task is not triggered with the ``bitbake -c`` command-line option as
589 are the other tasks in this section. Because this task is specifically for
590 the ``package-index`` recipe, you run it using ``bitbake package-index``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500591
592Image-Related Tasks
593===================
594
595The following tasks are applicable to image recipes.
596
597.. _ref-tasks-bootimg:
598
599``do_bootimg``
600--------------
601
602Creates a bootable live image. See the
603:term:`IMAGE_FSTYPES` variable for additional
604information on live image types.
605
606.. _ref-tasks-bundle_initramfs:
607
608``do_bundle_initramfs``
609-----------------------
610
611Combines an initial RAM disk (initramfs) image and kernel together to
612form a single image. The
613:term:`CONFIG_INITRAMFS_SOURCE` variable
614has some more information about these types of images.
615
616.. _ref-tasks-rootfs:
617
618``do_rootfs``
619-------------
620
621Creates the root filesystem (file and directory structure) for an image.
Andrew Geissler09209ee2020-12-13 08:44:15 -0600622See the ":ref:`overview-manual/concepts:image generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500623section in the Yocto Project Overview and Concepts Manual for more
624information on how the root filesystem is created.
625
626.. _ref-tasks-testimage:
627
628``do_testimage``
629----------------
630
631Boots an image and performs runtime tests within the image. For
632information on automatically testing images, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600633":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500634section in the Yocto Project Development Tasks Manual.
635
636.. _ref-tasks-testimage_auto:
637
638``do_testimage_auto``
639---------------------
640
641Boots an image and performs runtime tests within the image immediately
642after it has been built. This task is enabled when you set
643:term:`TESTIMAGE_AUTO` equal to "1".
644
645For information on automatically testing images, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600646":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500647section in the Yocto Project Development Tasks Manual.
648
649Kernel-Related Tasks
650====================
651
652The following tasks are applicable to kernel recipes. Some of these
653tasks (e.g. the :ref:`ref-tasks-menuconfig` task) are
654also applicable to recipes that use Linux kernel style configuration
655such as the BusyBox recipe.
656
657.. _ref-tasks-compile_kernelmodules:
658
659``do_compile_kernelmodules``
660----------------------------
661
662Runs the step that builds the kernel modules (if needed). Building a
663kernel consists of two steps: 1) the kernel (``vmlinux``) is built, and
6642) the modules are built (i.e. ``make modules``).
665
666.. _ref-tasks-diffconfig:
667
668``do_diffconfig``
669-----------------
670
671When invoked by the user, this task creates a file containing the
672differences between the original config as produced by
673:ref:`ref-tasks-kernel_configme` task and the
674changes made by the user with other methods (i.e. using
675(:ref:`ref-tasks-kernel_menuconfig`). Once the
676file of differences is created, it can be used to create a config
677fragment that only contains the differences. You can invoke this task
Andrew Geisslerc926e172021-05-07 16:11:35 -0500678from the command line as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500679
680 $ bitbake linux-yocto -c diffconfig
681
682For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600683":ref:`kernel-dev/common:creating configuration fragments`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500684section in the Yocto Project Linux Kernel Development Manual.
685
686.. _ref-tasks-kernel_checkout:
687
688``do_kernel_checkout``
689----------------------
690
691Converts the newly unpacked kernel source into a form with which the
692OpenEmbedded build system can work. Because the kernel source can be
693fetched in several different ways, the ``do_kernel_checkout`` task makes
694sure that subsequent tasks are given a clean working tree copy of the
695kernel with the correct branches checked out.
696
697.. _ref-tasks-kernel_configcheck:
698
699``do_kernel_configcheck``
700-------------------------
701
702Validates the configuration produced by the
703:ref:`ref-tasks-kernel_menuconfig` task. The
704``do_kernel_configcheck`` task produces warnings when a requested
705configuration does not appear in the final ``.config`` file or when you
706override a policy configuration in a hardware configuration fragment.
707You can run this task explicitly and view the output by using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500708following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500709
710 $ bitbake linux-yocto -c kernel_configcheck -f
711
712For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600713":ref:`kernel-dev/common:validating configuration`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500714section in the Yocto Project Linux Kernel Development Manual.
715
716.. _ref-tasks-kernel_configme:
717
718``do_kernel_configme``
719----------------------
720
721After the kernel is patched by the :ref:`ref-tasks-patch`
722task, the ``do_kernel_configme`` task assembles and merges all the
723kernel config fragments into a merged configuration that can then be
724passed to the kernel configuration phase proper. This is also the time
725during which user-specified defconfigs are applied if present, and where
726configuration modes such as ``--allnoconfig`` are applied.
727
728.. _ref-tasks-kernel_menuconfig:
729
730``do_kernel_menuconfig``
731------------------------
732
733Invoked by the user to manipulate the ``.config`` file used to build a
734linux-yocto recipe. This task starts the Linux kernel configuration
735tool, which you then use to modify the kernel configuration.
736
737.. note::
738
Andrew Geisslerc926e172021-05-07 16:11:35 -0500739 You can also invoke this tool from the command line as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500740
741 $ bitbake linux-yocto -c menuconfig
742
743
Andrew Geissler09209ee2020-12-13 08:44:15 -0600744See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500745section in the Yocto Project Linux Kernel Development Manual for more
746information on this configuration tool.
747
748.. _ref-tasks-kernel_metadata:
749
750``do_kernel_metadata``
751----------------------
752
753Collects all the features required for a given kernel build, whether the
754features come from :term:`SRC_URI` or from Git
755repositories. After collection, the ``do_kernel_metadata`` task
756processes the features into a series of config fragments and patches,
757which can then be applied by subsequent tasks such as
758:ref:`ref-tasks-patch` and
759:ref:`ref-tasks-kernel_configme`.
760
761.. _ref-tasks-menuconfig:
762
763``do_menuconfig``
764-----------------
765
766Runs ``make menuconfig`` for the kernel. For information on
767``menuconfig``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600768":ref:`kernel-dev/common:using \`\`menuconfig\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500769section in the Yocto Project Linux Kernel Development Manual.
770
771.. _ref-tasks-savedefconfig:
772
773``do_savedefconfig``
774--------------------
775
776When invoked by the user, creates a defconfig file that can be used
777instead of the default defconfig. The saved defconfig contains the
778differences between the default defconfig and the changes made by the
779user using other methods (i.e. the
780:ref:`ref-tasks-kernel_menuconfig` task. You
Andrew Geisslerc926e172021-05-07 16:11:35 -0500781can invoke the task using the following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500782
783 $ bitbake linux-yocto -c savedefconfig
784
785.. _ref-tasks-shared_workdir:
786
787``do_shared_workdir``
788---------------------
789
790After the kernel has been compiled but before the kernel modules have
791been compiled, this task copies files required for module builds and
792which are generated from the kernel build into the shared work
793directory. With these copies successfully copied, the
794:ref:`ref-tasks-compile_kernelmodules` task
795can successfully build the kernel modules in the next step of the build.
796
797.. _ref-tasks-sizecheck:
798
799``do_sizecheck``
800----------------
801
802After the kernel has been built, this task checks the size of the
803stripped kernel image against
804:term:`KERNEL_IMAGE_MAXSIZE`. If that
805variable was set and the size of the stripped kernel exceeds that size,
806the kernel build produces a warning to that effect.
807
808.. _ref-tasks-strip:
809
810``do_strip``
811------------
812
813If ``KERNEL_IMAGE_STRIP_EXTRA_SECTIONS`` is defined, this task strips
814the sections named in that variable from ``vmlinux``. This stripping is
815typically used to remove nonessential sections such as ``.comment``
816sections from a size-sensitive configuration.
817
818.. _ref-tasks-validate_branches:
819
820``do_validate_branches``
821------------------------
822
823After the kernel is unpacked but before it is patched, this task makes
824sure that the machine and metadata branches as specified by the
825:term:`SRCREV` variables actually exist on the specified
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700826branches. Otherwise, if :term:`AUTOREV` is not being used, the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500827``do_validate_branches`` task fails during the build.