diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2014-05-09 10:36:57 +0300 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-05-13 07:50:58 +0100 |
commit | 2f4d0722ce42e6381228b335d2bbd5a5901bb594 (patch) | |
tree | 2d4aeb39f465cf7687fa28a4dcb1708d4a73b849 /documentation/ref-manual | |
parent | ab864d71fb85628e0f1980b84a23bad7a7e2baea (diff) | |
download | poky-2f4d0722ce42e6381228b335d2bbd5a5901bb594.tar.gz |
ref-manual: Added new chapter on task documentation
Changes to support a new chapter on the 51 tasks that the
OpenEmbedded build system defines. The changes include a new
file called ref-tasks.xml, changes to the ref-manual.xml
building file to include the new chapter, and a new bullet
item to the list that describes what is in the reference
manual.
(From yocto-docs rev: a816746051ec025014e515fb848b3e0e58d4c7be)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r-- | documentation/ref-manual/introduction.xml | 4 | ||||
-rw-r--r-- | documentation/ref-manual/ref-manual.xml | 2 | ||||
-rw-r--r-- | documentation/ref-manual/ref-tasks.xml | 497 |
3 files changed, 503 insertions, 0 deletions
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml index f48489a563..a61740d48b 100644 --- a/documentation/ref-manual/introduction.xml +++ b/documentation/ref-manual/introduction.xml | |||
@@ -69,6 +69,10 @@ | |||
69 | <link linkend='ref-classes'>Classes</link>:</emphasis> | 69 | <link linkend='ref-classes'>Classes</link>:</emphasis> |
70 | Describes the classes used in the Yocto Project.</para></listitem> | 70 | Describes the classes used in the Yocto Project.</para></listitem> |
71 | <listitem><para><emphasis> | 71 | <listitem><para><emphasis> |
72 | <link linkend='ref-tasks'>Tasks</link>:</emphasis> | ||
73 | Describes the tasks defined by the OpenEmbedded build system. | ||
74 | </para></listitem> | ||
75 | <listitem><para><emphasis> | ||
72 | <link linkend='ref-images'>Images</link>:</emphasis> | 76 | <link linkend='ref-images'>Images</link>:</emphasis> |
73 | Describes the standard images that the Yocto Project supports. | 77 | Describes the standard images that the Yocto Project supports. |
74 | </para></listitem> | 78 | </para></listitem> |
diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml index 22f652de55..1ec1458f2d 100644 --- a/documentation/ref-manual/ref-manual.xml +++ b/documentation/ref-manual/ref-manual.xml | |||
@@ -123,6 +123,8 @@ | |||
123 | 123 | ||
124 | <xi:include href="ref-classes.xml"/> | 124 | <xi:include href="ref-classes.xml"/> |
125 | 125 | ||
126 | <xi:include href="ref-tasks.xml"/> | ||
127 | |||
126 | <xi:include href="ref-images.xml"/> | 128 | <xi:include href="ref-images.xml"/> |
127 | 129 | ||
128 | <xi:include href="ref-features.xml"/> | 130 | <xi:include href="ref-features.xml"/> |
diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml new file mode 100644 index 0000000000..aea0858f73 --- /dev/null +++ b/documentation/ref-manual/ref-tasks.xml | |||
@@ -0,0 +1,497 @@ | |||
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 | |||
5 | <chapter id='ref-tasks'> | ||
6 | <title>Tasks</title> | ||
7 | |||
8 | <para> | ||
9 | Tasks are units of execution for BitBake. | ||
10 | Recipes (<filename>.bb</filename> files) use tasks to complete | ||
11 | configuring, compiling, and packaging software. | ||
12 | This chapter provides a reference of the tasks defined in the | ||
13 | OpenEmbedded build system. | ||
14 | </para> | ||
15 | |||
16 | <section id='normal-recipe-build-tasks'> | ||
17 | <title>Normal Recipe Build Tasks</title> | ||
18 | |||
19 | <para> | ||
20 | The following sections describe normal tasks associated with building | ||
21 | a recipe. | ||
22 | </para> | ||
23 | |||
24 | <section id='ref-tasks-build'> | ||
25 | <title><filename>do_build</filename></title> | ||
26 | |||
27 | <para> | ||
28 | Default task for a recipe - depends on all other normal tasks | ||
29 | required to 'build' a recipe. | ||
30 | </para> | ||
31 | </section> | ||
32 | |||
33 | <section id='ref-tasks-compile'> | ||
34 | <title><filename>do_compile</filename></title> | ||
35 | |||
36 | <para> | ||
37 | Compiles the source in the compilation directory. | ||
38 | </para> | ||
39 | </section> | ||
40 | |||
41 | <section id='ref-tasks-compile_ptest_base'> | ||
42 | <title><filename>do_compile_ptest_base</filename></title> | ||
43 | |||
44 | <para> | ||
45 | Compiles the runtime test suite included in the software being | ||
46 | built. | ||
47 | </para> | ||
48 | </section> | ||
49 | |||
50 | <section id='ref-tasks-configure'> | ||
51 | <title><filename>do_configure</filename></title> | ||
52 | |||
53 | <para> | ||
54 | Configures the source by enabling and disabling any build-time and | ||
55 | configuration options for the software being built. | ||
56 | </para> | ||
57 | </section> | ||
58 | |||
59 | <section id='ref-tasks-configure_ptest_base'> | ||
60 | <title><filename>do_configure_ptest_base</filename></title> | ||
61 | |||
62 | <para> | ||
63 | Configures the runtime test suite included in the software being | ||
64 | built. | ||
65 | </para> | ||
66 | </section> | ||
67 | |||
68 | <section id='ref-tasks-deploy'> | ||
69 | <title><filename>do_deploy</filename></title> | ||
70 | |||
71 | <para> | ||
72 | Writes deployable output files to the deploy directory. | ||
73 | </para> | ||
74 | </section> | ||
75 | |||
76 | <section id='ref-tasks-fetch'> | ||
77 | <title><filename>do_fetch</filename></title> | ||
78 | |||
79 | <para> | ||
80 | Fetches the source code. | ||
81 | </para> | ||
82 | </section> | ||
83 | |||
84 | <section id='ref-tasks-install'> | ||
85 | <title><filename>do_install</filename></title> | ||
86 | |||
87 | <para> | ||
88 | Copies files from the compilation directory to a holding area. | ||
89 | </para> | ||
90 | </section> | ||
91 | |||
92 | <section id='ref-tasks-install_ptest_base'> | ||
93 | <title><filename>do_install_ptest_base</filename></title> | ||
94 | |||
95 | <para> | ||
96 | Copies the runtime test suite files from the compilation directory | ||
97 | to a holding area. | ||
98 | </para> | ||
99 | </section> | ||
100 | |||
101 | <section id='ref-tasks-package'> | ||
102 | <title><filename>do_package</filename></title> | ||
103 | |||
104 | <para> | ||
105 | Analyzes the content of the holding area and splits it into subsets | ||
106 | based on available packages and files. | ||
107 | </para> | ||
108 | </section> | ||
109 | |||
110 | <section id='ref-tasks-package_index'> | ||
111 | <title><filename>do_package_index</filename></title> | ||
112 | |||
113 | <para> | ||
114 | Creates or updates the index in the Package Feed area. | ||
115 | </para> | ||
116 | </section> | ||
117 | |||
118 | <section id='ref-tasks-package_write_deb'> | ||
119 | <title><filename>do_package_write_deb</filename></title> | ||
120 | |||
121 | <para> | ||
122 | Creates the actual DEB packages and places them in the Package Feed | ||
123 | area. | ||
124 | </para> | ||
125 | </section> | ||
126 | |||
127 | <section id='ref-tasks-package_write_ipk'> | ||
128 | <title><filename>do_package_write_ipk</filename></title> | ||
129 | |||
130 | <para> | ||
131 | Creates the actual IPK packages and places them in the Package Feed | ||
132 | area. | ||
133 | </para> | ||
134 | </section> | ||
135 | |||
136 | <section id='ref-tasks-package_write_rpm'> | ||
137 | <title><filename>do_package_write_rpm</filename></title> | ||
138 | |||
139 | <para> | ||
140 | Creates the actual RPM packages and places them in the Package Feed | ||
141 | area. | ||
142 | </para> | ||
143 | </section> | ||
144 | |||
145 | <section id='ref-tasks-package_write_tar'> | ||
146 | <title><filename>do_package_write_tar</filename></title> | ||
147 | |||
148 | <para> | ||
149 | Creates tar archives for packages and places them in the Package | ||
150 | Feed area. | ||
151 | </para> | ||
152 | </section> | ||
153 | |||
154 | <section id='ref-tasks-packagedata'> | ||
155 | <title><filename>do_packagedata</filename></title> | ||
156 | |||
157 | <para> | ||
158 | Creates package metadata used by the build system to generate the | ||
159 | final packages. | ||
160 | </para> | ||
161 | </section> | ||
162 | |||
163 | <section id='ref-tasks-patch'> | ||
164 | <title><filename>do_patch</filename></title> | ||
165 | |||
166 | <para> | ||
167 | Locates patch files and applies them to the source code. | ||
168 | </para> | ||
169 | </section> | ||
170 | |||
171 | <section id='ref-tasks-populate_lic'> | ||
172 | <title><filename>do_populate_lic</filename></title> | ||
173 | |||
174 | <para> | ||
175 | Writes license information for the recipe that is collected later | ||
176 | when the image is constructed. | ||
177 | </para> | ||
178 | </section> | ||
179 | |||
180 | <section id='ref-tasks-populate_sdk'> | ||
181 | <title><filename>do_populate_sdk</filename></title> | ||
182 | |||
183 | <para> | ||
184 | Creates the file and directory structure for an installable SDK. | ||
185 | </para> | ||
186 | </section> | ||
187 | |||
188 | <section id='ref-tasks-populate_sysroot'> | ||
189 | <title><filename>do_populate_sysroot</filename></title> | ||
190 | |||
191 | <para> | ||
192 | Copies a subset of files installed by do_install into the sysroot | ||
193 | in order to make them available to other recipes. | ||
194 | </para> | ||
195 | </section> | ||
196 | |||
197 | <section id='ref-tasks-rm_work'> | ||
198 | <title><filename>do_rm_work</filename></title> | ||
199 | |||
200 | <para> | ||
201 | Removes work files after the build system has finished with them. | ||
202 | </para> | ||
203 | </section> | ||
204 | |||
205 | <section id='ref-tasks-rm_work_all'> | ||
206 | <title><filename>do_rm_work_all</filename></title> | ||
207 | |||
208 | <para> | ||
209 | Top-level task for removing work files after the build system has | ||
210 | finished with them. | ||
211 | </para> | ||
212 | </section> | ||
213 | |||
214 | <section id='ref-tasks-unpack'> | ||
215 | <title><filename>do_unpack</filename></title> | ||
216 | |||
217 | <para> | ||
218 | Unpacks the source code into a working directory. | ||
219 | </para> | ||
220 | </section> | ||
221 | </section> | ||
222 | |||
223 | <section id='manually-called-tasks'> | ||
224 | <title>Manually Called Tasks</title> | ||
225 | |||
226 | <para> | ||
227 | These tasks are typically manually triggered (e.g. by using the | ||
228 | <filename>bitbake -c</filename> command line option): | ||
229 | </para> | ||
230 | |||
231 | <section id='ref-tasks-checkuri'> | ||
232 | <title><filename>do_checkuri</filename></title> | ||
233 | |||
234 | <para> | ||
235 | Validates the SRC_URI value. | ||
236 | </para> | ||
237 | </section> | ||
238 | |||
239 | <section id='ref-tasks-checkuriall'> | ||
240 | <title><filename>do_checkuriall</filename></title> | ||
241 | |||
242 | <para> | ||
243 | Validates the SRC_URI value for all recipes required to build a | ||
244 | target. | ||
245 | </para> | ||
246 | </section> | ||
247 | |||
248 | <section id='ref-tasks-clean'> | ||
249 | <title><filename>do_clean</filename></title> | ||
250 | |||
251 | <para> | ||
252 | Removes all output files for a target. | ||
253 | </para> | ||
254 | </section> | ||
255 | |||
256 | <section id='ref-tasks-cleanall'> | ||
257 | <title><filename>do_cleanall</filename></title> | ||
258 | |||
259 | <para> | ||
260 | Removes all output files, shared state cache, and downloaded source | ||
261 | files for a target. | ||
262 | </para> | ||
263 | </section> | ||
264 | |||
265 | <section id='ref-tasks-cleansstate'> | ||
266 | <title><filename>do_cleansstate</filename></title> | ||
267 | |||
268 | <para> | ||
269 | Removes all output files and shared state cache for a target. | ||
270 | </para> | ||
271 | </section> | ||
272 | |||
273 | <section id='ref-tasks-fetchall'> | ||
274 | <title><filename>do_fetchall</filename></title> | ||
275 | |||
276 | <para> | ||
277 | Fetches all remote sources required to build a target. | ||
278 | </para> | ||
279 | </section> | ||
280 | |||
281 | <section id='ref-tasks-devshell'> | ||
282 | <title><filename>do_devshell</filename></title> | ||
283 | |||
284 | <para> | ||
285 | Starts a shell with the environment set up for | ||
286 | development/debugging. | ||
287 | </para> | ||
288 | </section> | ||
289 | |||
290 | <section id='ref-tasks-listtasks'> | ||
291 | <title><filename>do_listtasks</filename></title> | ||
292 | |||
293 | <para> | ||
294 | Lists all defined tasks for a target. | ||
295 | </para> | ||
296 | </section> | ||
297 | </section> | ||
298 | |||
299 | <section id='image-related-tasks'> | ||
300 | <title>Image-Related Tasks</title> | ||
301 | |||
302 | <para> | ||
303 | The following tasks are applicable to image recipes. | ||
304 | </para> | ||
305 | |||
306 | <section id='ref-tasks-bootimg'> | ||
307 | <title><filename>do_bootimg</filename></title> | ||
308 | |||
309 | <para> | ||
310 | Creates a bootable live image. | ||
311 | </para> | ||
312 | </section> | ||
313 | |||
314 | <section id='ref-tasks-bundle_initramfs'> | ||
315 | <title><filename>do_bundle_initramfs</filename></title> | ||
316 | |||
317 | <para> | ||
318 | Combines an initial ramdisk image and kernel together to form | ||
319 | a single image. | ||
320 | </para> | ||
321 | </section> | ||
322 | |||
323 | <section id='ref-tasks-rootfs'> | ||
324 | <title><filename>do_rootfs</filename></title> | ||
325 | |||
326 | <para> | ||
327 | Creates the root filesystem (file and directory structure) for an | ||
328 | image. | ||
329 | </para> | ||
330 | </section> | ||
331 | |||
332 | <section id='ref-tasks-testimage'> | ||
333 | <title><filename>do_testimage</filename></title> | ||
334 | |||
335 | <para> | ||
336 | Boots an image and performs runtime tests within the image. | ||
337 | </para> | ||
338 | </section> | ||
339 | |||
340 | <section id='ref-tasks-testimage_auto'> | ||
341 | <title><filename>do_testimage_auto</filename></title> | ||
342 | |||
343 | <para> | ||
344 | Boots an image and performs runtime tests within the image | ||
345 | immediately after it has been built. | ||
346 | </para> | ||
347 | </section> | ||
348 | |||
349 | <section id='ref-tasks-vmdkimg'> | ||
350 | <title><filename>do_vmdkimg</filename></title> | ||
351 | |||
352 | <para> | ||
353 | Creates a .vmdk image for use with VMware and compatible virtual | ||
354 | machine hosts. | ||
355 | </para> | ||
356 | </section> | ||
357 | </section> | ||
358 | |||
359 | <section id='kernel-related-tasks'> | ||
360 | <title>Kernel-Related Tasks</title> | ||
361 | |||
362 | <para> | ||
363 | The following tasks are applicable to kernel recipes. Some of them | ||
364 | (for example do_menuconfig) are also applicable to recipes which use | ||
365 | Linux kernel style configuration (e.g. busybox). | ||
366 | </para> | ||
367 | |||
368 | <section id='ref-tasks-compile_kernelmodules'> | ||
369 | <title><filename>do_compile_kernelmodules</filename></title> | ||
370 | |||
371 | <para> | ||
372 | Compiles loadable modules for the Linux kernel. | ||
373 | </para> | ||
374 | </section> | ||
375 | |||
376 | <section id='ref-tasks-diffconfig'> | ||
377 | <title><filename>do_diffconfig</filename></title> | ||
378 | |||
379 | <para> | ||
380 | Compares the old and new config files after running do_menuconfig | ||
381 | for the kernel. | ||
382 | </para> | ||
383 | </section> | ||
384 | |||
385 | <section id='ref-tasks-kernel_checkout'> | ||
386 | <title><filename>do_kernel_checkout</filename></title> | ||
387 | |||
388 | <para> | ||
389 | Checks out source/meta branches for a linux-yocto style kernel. | ||
390 | </para> | ||
391 | </section> | ||
392 | |||
393 | <section id='ref-tasks-kernel_configcheck'> | ||
394 | <title><filename>do_kernel_configcheck</filename></title> | ||
395 | |||
396 | <para> | ||
397 | Validates the kernel configuration for a linux-yocto style kernel. | ||
398 | </para> | ||
399 | </section> | ||
400 | |||
401 | <section id='ref-tasks-kernel_configme'> | ||
402 | <title><filename>do_kernel_configme</filename></title> | ||
403 | |||
404 | <para> | ||
405 | Assembles the kernel configuration for a linux-yocto style kernel. | ||
406 | </para> | ||
407 | </section> | ||
408 | |||
409 | <section id='ref-tasks-kernel_link_vmlinux'> | ||
410 | <title><filename>do_kernel_link_vmlinux</filename></title> | ||
411 | |||
412 | <para> | ||
413 | Creates a symbolic link in arch/$arch/boot for vmlinux kernel | ||
414 | images. | ||
415 | </para> | ||
416 | </section> | ||
417 | |||
418 | <section id='ref-tasks-menuconfig'> | ||
419 | <title><filename>do_menuconfig</filename></title> | ||
420 | |||
421 | <para> | ||
422 | Runs 'make menuconfig' for the kernel. | ||
423 | </para> | ||
424 | </section> | ||
425 | |||
426 | <section id='ref-tasks-savedefconfig'> | ||
427 | <title><filename>do_savedefconfig</filename></title> | ||
428 | |||
429 | <para> | ||
430 | Creates a minimal Linux kernel configuration file. | ||
431 | </para> | ||
432 | </section> | ||
433 | |||
434 | <section id='ref-tasks-sizecheck'> | ||
435 | <title><filename>do_sizecheck</filename></title> | ||
436 | |||
437 | <para> | ||
438 | Checks the size of the kernel image against KERNEL_IMAGE_MAXSIZE | ||
439 | (if set). | ||
440 | </para> | ||
441 | </section> | ||
442 | |||
443 | <section id='ref-tasks-strip'> | ||
444 | <title><filename>do_strip</filename></title> | ||
445 | |||
446 | <para> | ||
447 | Strips unneeded sections out of the Linux kernel image. | ||
448 | </para> | ||
449 | </section> | ||
450 | |||
451 | <section id='ref-tasks-uboot_mkimage'> | ||
452 | <title><filename>do_uboot_mkimage</filename></title> | ||
453 | |||
454 | <para> | ||
455 | Creates a uImage file from the kernel for the U-Boot bootloader. | ||
456 | </para> | ||
457 | </section> | ||
458 | |||
459 | <section id='ref-tasks-validate_branches'> | ||
460 | <title><filename>do_validate_branches</filename></title> | ||
461 | |||
462 | <para> | ||
463 | Ensures that the source/meta branches are on the locations | ||
464 | specified by their SRCREV values for a linux-yocto style kernel. | ||
465 | </para> | ||
466 | </section> | ||
467 | </section> | ||
468 | |||
469 | <section id='miscellaneous-tasks'> | ||
470 | <title>Miscellaneous Tasks</title> | ||
471 | |||
472 | <para> | ||
473 | The following sections describe miscellaneous tasks. | ||
474 | </para> | ||
475 | |||
476 | <section id='ref-tasks-generate_qt_config_file'> | ||
477 | <title><filename>do_generate_qt_config_file</filename></title> | ||
478 | |||
479 | <para> | ||
480 | Writes a qt.conf file for building a Qt-based application. | ||
481 | </para> | ||
482 | </section> | ||
483 | |||
484 | <section id='ref-tasks-spdx'> | ||
485 | <title><filename>do_spdx</filename></title> | ||
486 | |||
487 | <para> | ||
488 | A build stage that takes the source code and scans it on a remote | ||
489 | FOSSOLOGY server in order to produce an SPDX document. | ||
490 | </para> | ||
491 | </section> | ||
492 | </section> | ||
493 | |||
494 | </chapter> | ||
495 | <!-- | ||
496 | vim: expandtab tw=80 ts=4 | ||
497 | --> | ||