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