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