blob: c28cd7a94a1691166d561f27e95e12b10a9c30dc [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
Andrew Geisslerfc113ea2023-03-31 09:59:46 -050017":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
18":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050019BitBake 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.
Patrick Williams2194f502022-10-16 14:26:09 -050039If no such file is found, the :ref:`ref-tasks-compile` task does nothing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050040
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
Patrick Williams2194f502022-10-16 14:26:09 -050061:ref:`ref-tasks-configure` task does nothing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050062
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
Andrew Geissler517393d2023-01-13 08:55:19 -060081:ref:`ref-classes-deploy` class and should write the output
Andrew Geisslerc9f78652020-09-18 14:11:35 -050082to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be
Andrew Geissler517393d2023-01-13 08:55:19 -060083confused with ``${DEPLOY_DIR}``. The :ref:`ref-classes-deploy` class sets up
Patrick Williams2194f502022-10-16 14:26:09 -050084:ref:`ref-tasks-deploy` as a shared state (sstate) task that can be accelerated
Andrew Geisslerc9f78652020-09-18 14:11:35 -050085through 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
Patrick Williams2194f502022-10-16 14:26:09 -050093The :ref:`ref-tasks-deploy` task is not added as a task by default and
Andrew Geisslerc9f78652020-09-18 14:11:35 -050094consequently 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
Patrick Williams2194f502022-10-16 14:26:09 -0500100Adding :ref:`ref-tasks-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 Geissler517393d2023-01-13 08:55:19 -0600105 (though it is harmless), because the :ref:`ref-classes-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
Patrick Williams2194f502022-10-16 14:26:09 -0500113If the :ref:`ref-tasks-deploy` task re-executes, any previous output is removed
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500114(i.e. "cleaned").
115
116.. _ref-tasks-fetch:
117
118``do_fetch``
119------------
120
Andrew Geisslerfc113ea2023-03-31 09:59:46 -0500121Fetches the source code. This task uses the :term:`SRC_URI` variable and the
122argument's prefix to determine the correct
123:ref:`fetcher <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
Patrick Williams2194f502022-10-16 14:26:09 -0500131Starts the image generation process. The :ref:`ref-tasks-image` task runs after
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500132the 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
Patrick Williams2194f502022-10-16 14:26:09 -0500137The :ref:`ref-tasks-image` task performs pre-processing on the image through the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500138:term:`IMAGE_PREPROCESS_COMMAND` and
Patrick Williams2194f502022-10-16 14:26:09 -0500139dynamically generates supporting :ref:`do_image_* <ref-tasks-image>` tasks as needed.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500140
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
Patrick Williams2194f502022-10-16 14:26:09 -0500149Completes the image generation process. The :ref:`do_image_complete <ref-tasks-image-complete>` task
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500150runs after the OpenEmbedded build system has run the
151:ref:`ref-tasks-image` task during which image
Patrick Williams2194f502022-10-16 14:26:09 -0500152pre-processing occurs and through dynamically generated :ref:`do_image_* <ref-tasks-image>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500153tasks the image is constructed.
154
Patrick Williams2194f502022-10-16 14:26:09 -0500155The :ref:`do_image_complete <ref-tasks-image-complete>` task performs post-processing on the image
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500156through 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
Patrick Williams2194f502022-10-16 14:26:09 -0500171compilation directory. The :ref:`ref-tasks-install` task, as well as other tasks
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500172that either directly or indirectly depend on the installed files (e.g.
Patrick Williams2194f502022-10-16 14:26:09 -0500173:ref:`ref-tasks-package`, :ref:`do_package_write_* <ref-tasks-package_write_deb>`, and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500174: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
Patrick Williams45852732022-04-02 08:58:32 -0500190 - The ``cp`` command with the ``--no-preserve=ownership`` option.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500191
Patrick Williams45852732022-04-02 08:58:32 -0500192 - The ``tar`` command with the ``--no-same-owner`` option. See the
Patrick Williams975a06f2022-10-21 14:42:47 -0500193 ``bin_package.bbclass`` file in the ``meta/classes-recipe``
194 subdirectory of the :term:`Source Directory` for an example.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500195
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
Patrick Williams2194f502022-10-16 14:26:09 -0500215The :ref:`ref-tasks-package` task, in conjunction with the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500216: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,
Andrew Geissler517393d2023-01-13 08:55:19 -0600228see the :ref:`ref-classes-insane` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500229
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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500263.. _ref-tasks-packagedata:
264
265``do_packagedata``
266------------------
267
268Saves package metadata generated by the
269:ref:`ref-tasks-package` task in
270:term:`PKGDATA_DIR` to make it available globally.
271
272.. _ref-tasks-patch:
273
274``do_patch``
275------------
276
277Locates patch files and applies them to the source code.
278
279After fetching and unpacking source files, the build system uses the
280recipe's :term:`SRC_URI` statements
281to locate and apply patch files to the source code.
282
283.. note::
284
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500285 The build system uses the :term:`FILESPATH` variable to determine the
286 default set of directories when searching for patches.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500287
288Patch files, by default, are ``*.patch`` and ``*.diff`` files created
289and kept in a subdirectory of the directory holding the recipe file. For
290example, consider the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600291:yocto_git:`bluez5 </poky/tree/meta/recipes-connectivity/bluez5>`
Andrew Geisslerc926e172021-05-07 16:11:35 -0500292recipe from the OE-Core layer (i.e. ``poky/meta``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500293
294 poky/meta/recipes-connectivity/bluez5
295
Andrew Geisslerc926e172021-05-07 16:11:35 -0500296This recipe has two patch files located here::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500297
298 poky/meta/recipes-connectivity/bluez5/bluez5
299
Andrew Geissler09036742021-06-25 14:25:14 -0500300In the ``bluez5`` recipe, the :term:`SRC_URI` statements point to the source
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500301and patch files needed to build the package.
302
303.. note::
304
Andrew Geissler09036742021-06-25 14:25:14 -0500305 In the case for the ``bluez5_5.48.bb`` recipe, the :term:`SRC_URI` statements
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500306 are from an include file ``bluez5.inc``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500307
308As mentioned earlier, the build system treats files whose file types are
309``.patch`` and ``.diff`` as patch files. However, you can use the
Andrew Geissler09036742021-06-25 14:25:14 -0500310"apply=yes" parameter with the :term:`SRC_URI` statement to indicate any
Andrew Geisslerc926e172021-05-07 16:11:35 -0500311file as a patch file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500312
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500313 SRC_URI = " \
314 git://path_to_repo/some_package \
315 file://file;apply=yes \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500316 "
317
Andrew Geissler595f6302022-01-24 19:11:47 +0000318Conversely, if you have a file whose file type is ``.patch`` or ``.diff``
Patrick Williams2194f502022-10-16 14:26:09 -0500319and you want to exclude it so that the :ref:`ref-tasks-patch` task does not apply
Andrew Geissler595f6302022-01-24 19:11:47 +0000320it during the patch phase, you can use the "apply=no" parameter with the
Andrew Geissler09036742021-06-25 14:25:14 -0500321:term:`SRC_URI` statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500322
323 SRC_URI = " \
324 git://path_to_repo/some_package \
Andrew Geissler595f6302022-01-24 19:11:47 +0000325 file://file1.patch \
326 file://file2.patch;apply=no \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500327 "
328
Andrew Geissler595f6302022-01-24 19:11:47 +0000329In the previous example ``file1.patch`` would be applied as a patch by default
330while ``file2.patch`` would not be applied.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500331
332You can find out more about the patching process in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600333":ref:`overview-manual/concepts:patching`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500334the Yocto Project Overview and Concepts Manual and the
Andrew Geissler517393d2023-01-13 08:55:19 -0600335":ref:`dev-manual/new-recipe:patching code`" section in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500336Yocto Project Development Tasks Manual.
337
338.. _ref-tasks-populate_lic:
339
340``do_populate_lic``
341-------------------
342
343Writes license information for the recipe that is collected later when
344the image is constructed.
345
346.. _ref-tasks-populate_sdk:
347
348``do_populate_sdk``
349-------------------
350
351Creates the file and directory structure for an installable SDK. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600352":ref:`overview-manual/concepts:sdk generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500353section in the Yocto Project Overview and Concepts Manual for more
354information.
355
356.. _ref-tasks-populate_sdk_ext:
357
358``do_populate_sdk_ext``
359-----------------------
360
361Creates the file and directory structure for an installable extensible
Andrew Geissler09209ee2020-12-13 08:44:15 -0600362SDK (eSDK). See the ":ref:`overview-manual/concepts:sdk generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500363section in the Yocto Project Overview and Concepts Manual for more
364information.
365
366
367.. _ref-tasks-populate_sysroot:
368
369``do_populate_sysroot``
370-----------------------
371
372Stages (copies) a subset of the files installed by the
373:ref:`ref-tasks-install` task into the appropriate
374sysroot. For information on how to access these files from other
375recipes, see the :term:`STAGING_DIR* <STAGING_DIR_HOST>` variables.
376Directories that would typically not be needed by other recipes at build
377time (e.g. ``/etc``) are not copied by default.
378
379For information on what directories are copied by default, see the
380:term:`SYSROOT_DIRS* <SYSROOT_DIRS>` variables. You can change
381these variables inside your recipe if you need to make additional (or
382fewer) directories available to other recipes at build time.
383
Patrick Williams2194f502022-10-16 14:26:09 -0500384The :ref:`ref-tasks-populate_sysroot` task is a shared state (sstate) task, which
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500385means that the task can be accelerated through sstate use. Realize also
386that if the task is re-executed, any previous output is removed (i.e.
387"cleaned").
388
389.. _ref-tasks-prepare_recipe_sysroot:
390
391``do_prepare_recipe_sysroot``
392-----------------------------
393
394Installs the files into the individual recipe specific sysroots (i.e.
395``recipe-sysroot`` and ``recipe-sysroot-native`` under
396``${``\ :term:`WORKDIR`\ ``}`` based upon the
397dependencies specified by :term:`DEPENDS`). See the
Andrew Geissler517393d2023-01-13 08:55:19 -0600398":ref:`ref-classes-staging`" class for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500399
400.. _ref-tasks-rm_work:
401
402``do_rm_work``
403--------------
404
405Removes work files after the OpenEmbedded build system has finished with
406them. You can learn more by looking at the
Andrew Geissler595f6302022-01-24 19:11:47 +0000407":ref:`ref-classes-rm-work`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500408
409.. _ref-tasks-unpack:
410
411``do_unpack``
412-------------
413
414Unpacks the source code into a working directory pointed to by
415``${``\ :term:`WORKDIR`\ ``}``. The :term:`S`
416variable also plays a role in where unpacked source files ultimately
417reside. For more information on how source files are unpacked, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600418":ref:`overview-manual/concepts:source fetching`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500419section in the Yocto Project Overview and Concepts Manual and also see
Andrew Geissler09036742021-06-25 14:25:14 -0500420the :term:`WORKDIR` and :term:`S` variable descriptions.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500421
422Manually Called Tasks
423=====================
424
425These tasks are typically manually triggered (e.g. by using the
426``bitbake -c`` command-line option):
427
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500428``do_checkuri``
429---------------
430
431Validates the :term:`SRC_URI` value.
432
433.. _ref-tasks-clean:
434
435``do_clean``
436------------
437
438Removes all output files for a target from the
Patrick Williams2194f502022-10-16 14:26:09 -0500439:ref:`ref-tasks-unpack` task forward (i.e. :ref:`ref-tasks-unpack`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500440:ref:`ref-tasks-configure`,
441:ref:`ref-tasks-compile`,
442:ref:`ref-tasks-install`, and
443:ref:`ref-tasks-package`).
444
Andrew Geisslerc926e172021-05-07 16:11:35 -0500445You can run this task using BitBake as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500446
447 $ bitbake -c clean recipe
448
449Running this task does not remove the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600450:ref:`sstate <overview-manual/concepts:shared state cache>` cache files.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500451Consequently, if no changes have been made and the recipe is rebuilt
452after cleaning, output files are simply restored from the sstate cache.
453If you want to remove the sstate cache files for the recipe, you need to
454use the :ref:`ref-tasks-cleansstate` task instead
455(i.e. ``bitbake -c cleansstate`` recipe).
456
457.. _ref-tasks-cleanall:
458
459``do_cleanall``
460---------------
461
462Removes all output files, shared state
Andrew Geissler09209ee2020-12-13 08:44:15 -0600463(:ref:`sstate <overview-manual/concepts:shared state cache>`) cache, and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500464downloaded source files for a target (i.e. the contents of
Patrick Williams2194f502022-10-16 14:26:09 -0500465:term:`DL_DIR`). Essentially, the :ref:`ref-tasks-cleanall` task is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500466identical to the :ref:`ref-tasks-cleansstate` task
467with the added removal of downloaded source files.
468
Andrew Geisslerc926e172021-05-07 16:11:35 -0500469You can run this task using BitBake as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500470
471 $ bitbake -c cleanall recipe
472
Patrick Williamsb58112e2024-03-07 11:16:36 -0600473You should never use the :ref:`ref-tasks-cleanall` task in a normal
474scenario. If you want to start fresh with the :ref:`ref-tasks-fetch` task,
475use instead::
476
477 $ bitbake -f -c fetch recipe
478
479.. note::
480
481 The reason to prefer ``bitbake -f -c fetch`` is that the
482 :ref:`ref-tasks-cleanall` task would break in some cases, such as::
483
484 $ bitbake -c fetch recipe
485 $ bitbake -c cleanall recipe-native
486 $ bitbake -c unpack recipe
487
488 because after step 1 there is a stamp file for the
489 :ref:`ref-tasks-fetch` task of ``recipe``, and it won't be removed at
490 step 2 because step 2 uses a different work directory. So the unpack task
491 at step 3 will try to extract the downloaded archive and fail as it has
492 been deleted in step 2.
493
494 Note that this also applies to BitBake from concurrent processes when a
495 shared download directory (:term:`DL_DIR`) is setup.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500496
497.. _ref-tasks-cleansstate:
498
499``do_cleansstate``
500------------------
501
502Removes all output files and shared state
Andrew Geissler09209ee2020-12-13 08:44:15 -0600503(:ref:`sstate <overview-manual/concepts:shared state cache>`) cache for a
Patrick Williams2194f502022-10-16 14:26:09 -0500504target. Essentially, the :ref:`ref-tasks-cleansstate` task is identical to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500505:ref:`ref-tasks-clean` task with the added removal of
Andrew Geissler09209ee2020-12-13 08:44:15 -0600506shared state (:ref:`sstate <overview-manual/concepts:shared state cache>`)
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500507cache.
508
Andrew Geisslerc926e172021-05-07 16:11:35 -0500509You can run this task using BitBake as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500510
511 $ bitbake -c cleansstate recipe
512
Patrick Williams2194f502022-10-16 14:26:09 -0500513When you run the :ref:`ref-tasks-cleansstate` task, the OpenEmbedded build system
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500514no longer uses any sstate. Consequently, building the recipe from
515scratch is guaranteed.
516
517.. note::
518
Patrick Williamsb58112e2024-03-07 11:16:36 -0600519 Using :ref:`ref-tasks-cleansstate` with a shared :term:`SSTATE_DIR` is
520 not recommended because it could trigger an error during the build of a
521 separate BitBake instance. This is because the builds check sstate "up
522 front" but download the files later, so it if is deleted in the
523 meantime, it will cause an error but not a total failure as it will
524 rebuild it.
525
526 The reliable and preferred way to force a new build is to use ``bitbake
527 -f`` instead.
528
529.. note::
530
Patrick Williams2194f502022-10-16 14:26:09 -0500531 The :ref:`ref-tasks-cleansstate` task cannot remove sstate from a remote sstate
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500532 mirror. If you need to build a target from scratch using remote mirrors, use
Andrew Geisslerc926e172021-05-07 16:11:35 -0500533 the "-f" option as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500534
535 $ bitbake -f -c do_cleansstate target
536
537
Andrew Geisslereff27472021-10-29 15:35:00 -0500538.. _ref-tasks-pydevshell:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500539
Andrew Geisslereff27472021-10-29 15:35:00 -0500540``do_pydevshell``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500541-----------------
542
543Starts a shell in which an interactive Python interpreter allows you to
544interact with the BitBake build environment. From within this shell, you
545can directly examine and set bits from the data store and execute
Andrew Geissler517393d2023-01-13 08:55:19 -0600546functions as if within the BitBake environment. See the ":ref:`dev-manual/python-development-shell:using a Python development shell`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500547the Yocto Project Development Tasks Manual for more information about
Andrew Geisslereff27472021-10-29 15:35:00 -0500548using ``pydevshell``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500549
550.. _ref-tasks-devshell:
551
552``do_devshell``
553---------------
554
555Starts a shell whose environment is set up for development, debugging,
Andrew Geissler517393d2023-01-13 08:55:19 -0600556or both. See the ":ref:`dev-manual/development-shell:using a development shell`" section in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500557Yocto Project Development Tasks Manual for more information about using
558``devshell``.
559
560.. _ref-tasks-listtasks:
561
562``do_listtasks``
563----------------
564
565Lists all defined tasks for a target.
566
567.. _ref-tasks-package_index:
568
569``do_package_index``
570--------------------
571
Andrew Geissler09209ee2020-12-13 08:44:15 -0600572Creates or updates the index in the :ref:`overview-manual/concepts:package feeds` area.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500573
574.. note::
575
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500576 This task is not triggered with the ``bitbake -c`` command-line option as
577 are the other tasks in this section. Because this task is specifically for
578 the ``package-index`` recipe, you run it using ``bitbake package-index``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500579
580Image-Related Tasks
581===================
582
583The following tasks are applicable to image recipes.
584
585.. _ref-tasks-bootimg:
586
587``do_bootimg``
588--------------
589
590Creates a bootable live image. See the
591:term:`IMAGE_FSTYPES` variable for additional
592information on live image types.
593
594.. _ref-tasks-bundle_initramfs:
595
596``do_bundle_initramfs``
597-----------------------
598
Patrick Williams2194f502022-10-16 14:26:09 -0500599Combines an :term:`Initramfs` image and kernel together to
600form a single image.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500601
602.. _ref-tasks-rootfs:
603
604``do_rootfs``
605-------------
606
607Creates the root filesystem (file and directory structure) for an image.
Andrew Geissler09209ee2020-12-13 08:44:15 -0600608See the ":ref:`overview-manual/concepts:image generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500609section in the Yocto Project Overview and Concepts Manual for more
610information on how the root filesystem is created.
611
612.. _ref-tasks-testimage:
613
614``do_testimage``
615----------------
616
617Boots an image and performs runtime tests within the image. For
618information on automatically testing images, see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600619":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500620section in the Yocto Project Development Tasks Manual.
621
622.. _ref-tasks-testimage_auto:
623
624``do_testimage_auto``
625---------------------
626
627Boots an image and performs runtime tests within the image immediately
628after it has been built. This task is enabled when you set
629:term:`TESTIMAGE_AUTO` equal to "1".
630
631For information on automatically testing images, see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600632":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500633section in the Yocto Project Development Tasks Manual.
634
635Kernel-Related Tasks
636====================
637
638The following tasks are applicable to kernel recipes. Some of these
639tasks (e.g. the :ref:`ref-tasks-menuconfig` task) are
640also applicable to recipes that use Linux kernel style configuration
641such as the BusyBox recipe.
642
643.. _ref-tasks-compile_kernelmodules:
644
645``do_compile_kernelmodules``
646----------------------------
647
648Runs the step that builds the kernel modules (if needed). Building a
649kernel consists of two steps: 1) the kernel (``vmlinux``) is built, and
6502) the modules are built (i.e. ``make modules``).
651
652.. _ref-tasks-diffconfig:
653
654``do_diffconfig``
655-----------------
656
657When invoked by the user, this task creates a file containing the
658differences between the original config as produced by
659:ref:`ref-tasks-kernel_configme` task and the
660changes made by the user with other methods (i.e. using
661(:ref:`ref-tasks-kernel_menuconfig`). Once the
662file of differences is created, it can be used to create a config
663fragment that only contains the differences. You can invoke this task
Andrew Geisslerc926e172021-05-07 16:11:35 -0500664from the command line as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500665
666 $ bitbake linux-yocto -c diffconfig
667
668For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600669":ref:`kernel-dev/common:creating configuration fragments`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500670section in the Yocto Project Linux Kernel Development Manual.
671
672.. _ref-tasks-kernel_checkout:
673
674``do_kernel_checkout``
675----------------------
676
677Converts the newly unpacked kernel source into a form with which the
678OpenEmbedded build system can work. Because the kernel source can be
Patrick Williams2194f502022-10-16 14:26:09 -0500679fetched in several different ways, the :ref:`ref-tasks-kernel_checkout` task makes
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500680sure that subsequent tasks are given a clean working tree copy of the
681kernel with the correct branches checked out.
682
683.. _ref-tasks-kernel_configcheck:
684
685``do_kernel_configcheck``
686-------------------------
687
688Validates the configuration produced by the
689:ref:`ref-tasks-kernel_menuconfig` task. The
Patrick Williams2194f502022-10-16 14:26:09 -0500690:ref:`ref-tasks-kernel_configcheck` task produces warnings when a requested
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500691configuration does not appear in the final ``.config`` file or when you
692override a policy configuration in a hardware configuration fragment.
693You can run this task explicitly and view the output by using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500694following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500695
696 $ bitbake linux-yocto -c kernel_configcheck -f
697
698For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600699":ref:`kernel-dev/common:validating configuration`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500700section in the Yocto Project Linux Kernel Development Manual.
701
702.. _ref-tasks-kernel_configme:
703
704``do_kernel_configme``
705----------------------
706
707After the kernel is patched by the :ref:`ref-tasks-patch`
Patrick Williams2194f502022-10-16 14:26:09 -0500708task, the :ref:`ref-tasks-kernel_configme` task assembles and merges all the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500709kernel config fragments into a merged configuration that can then be
710passed to the kernel configuration phase proper. This is also the time
711during which user-specified defconfigs are applied if present, and where
712configuration modes such as ``--allnoconfig`` are applied.
713
714.. _ref-tasks-kernel_menuconfig:
715
716``do_kernel_menuconfig``
717------------------------
718
719Invoked by the user to manipulate the ``.config`` file used to build a
720linux-yocto recipe. This task starts the Linux kernel configuration
721tool, which you then use to modify the kernel configuration.
722
723.. note::
724
Andrew Geisslerc926e172021-05-07 16:11:35 -0500725 You can also invoke this tool from the command line as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500726
727 $ bitbake linux-yocto -c menuconfig
728
729
Andrew Geissler09209ee2020-12-13 08:44:15 -0600730See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500731section in the Yocto Project Linux Kernel Development Manual for more
732information on this configuration tool.
733
734.. _ref-tasks-kernel_metadata:
735
736``do_kernel_metadata``
737----------------------
738
739Collects all the features required for a given kernel build, whether the
740features come from :term:`SRC_URI` or from Git
Patrick Williams2194f502022-10-16 14:26:09 -0500741repositories. After collection, the :ref:`ref-tasks-kernel_metadata` task
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500742processes the features into a series of config fragments and patches,
743which can then be applied by subsequent tasks such as
744:ref:`ref-tasks-patch` and
745:ref:`ref-tasks-kernel_configme`.
746
747.. _ref-tasks-menuconfig:
748
749``do_menuconfig``
750-----------------
751
752Runs ``make menuconfig`` for the kernel. For information on
753``menuconfig``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600754":ref:`kernel-dev/common:using \`\`menuconfig\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500755section in the Yocto Project Linux Kernel Development Manual.
756
757.. _ref-tasks-savedefconfig:
758
759``do_savedefconfig``
760--------------------
761
762When invoked by the user, creates a defconfig file that can be used
763instead of the default defconfig. The saved defconfig contains the
764differences between the default defconfig and the changes made by the
765user using other methods (i.e. the
766:ref:`ref-tasks-kernel_menuconfig` task. You
Andrew Geisslerc926e172021-05-07 16:11:35 -0500767can invoke the task using the following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500768
769 $ bitbake linux-yocto -c savedefconfig
770
771.. _ref-tasks-shared_workdir:
772
773``do_shared_workdir``
774---------------------
775
776After the kernel has been compiled but before the kernel modules have
777been compiled, this task copies files required for module builds and
778which are generated from the kernel build into the shared work
779directory. With these copies successfully copied, the
780:ref:`ref-tasks-compile_kernelmodules` task
781can successfully build the kernel modules in the next step of the build.
782
783.. _ref-tasks-sizecheck:
784
785``do_sizecheck``
786----------------
787
788After the kernel has been built, this task checks the size of the
789stripped kernel image against
790:term:`KERNEL_IMAGE_MAXSIZE`. If that
791variable was set and the size of the stripped kernel exceeds that size,
792the kernel build produces a warning to that effect.
793
794.. _ref-tasks-strip:
795
796``do_strip``
797------------
798
799If ``KERNEL_IMAGE_STRIP_EXTRA_SECTIONS`` is defined, this task strips
800the sections named in that variable from ``vmlinux``. This stripping is
801typically used to remove nonessential sections such as ``.comment``
802sections from a size-sensitive configuration.
803
804.. _ref-tasks-validate_branches:
805
806``do_validate_branches``
807------------------------
808
809After the kernel is unpacked but before it is patched, this task makes
810sure that the machine and metadata branches as specified by the
811:term:`SRCREV` variables actually exist on the specified
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700812branches. Otherwise, if :term:`AUTOREV` is not being used, the
Patrick Williams2194f502022-10-16 14:26:09 -0500813:ref:`ref-tasks-validate_branches` task fails during the build.