diff options
Diffstat (limited to 'documentation/ref-manual/ref-structure.rst')
-rw-r--r-- | documentation/ref-manual/ref-structure.rst | 890 |
1 files changed, 890 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-structure.rst b/documentation/ref-manual/ref-structure.rst new file mode 100644 index 0000000000..48a443331b --- /dev/null +++ b/documentation/ref-manual/ref-structure.rst | |||
@@ -0,0 +1,890 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ************************** | ||
4 | Source Directory Structure | ||
5 | ************************** | ||
6 | |||
7 | The :term:`Source Directory` consists of numerous files, | ||
8 | directories and subdirectories; understanding their locations and | ||
9 | contents is key to using the Yocto Project effectively. This chapter | ||
10 | describes the Source Directory and gives information about those files | ||
11 | and directories. | ||
12 | |||
13 | For information on how to establish a local Source Directory on your | ||
14 | development system, see the | ||
15 | ":ref:`dev-manual/dev-manual-start:locating yocto project source files`" | ||
16 | section in the Yocto Project Development Tasks Manual. | ||
17 | |||
18 | .. note:: | ||
19 | |||
20 | The OpenEmbedded build system does not support file or directory | ||
21 | names that contain spaces. Be sure that the Source Directory you use | ||
22 | does not contain these types of names. | ||
23 | |||
24 | .. _structure-core: | ||
25 | |||
26 | Top-Level Core Components | ||
27 | ========================= | ||
28 | |||
29 | This section describes the top-level components of the :term:`Source Directory`. | ||
30 | |||
31 | .. _structure-core-bitbake: | ||
32 | |||
33 | ``bitbake/`` | ||
34 | ------------ | ||
35 | |||
36 | This directory includes a copy of BitBake for ease of use. The copy | ||
37 | usually matches the current stable BitBake release from the BitBake | ||
38 | project. BitBake, a :term:`Metadata` interpreter, reads the | ||
39 | Yocto Project Metadata and runs the tasks defined by that data. Failures | ||
40 | are usually caused by errors in your Metadata and not from BitBake | ||
41 | itself; consequently, most users do not need to worry about BitBake. | ||
42 | |||
43 | When you run the ``bitbake`` command, the main BitBake executable (which | ||
44 | resides in the ``bitbake/bin/`` directory) starts. Sourcing the | ||
45 | environment setup script (i.e. :ref:`structure-core-script`) places | ||
46 | the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into | ||
47 | the shell's ``PATH`` environment variable. | ||
48 | |||
49 | For more information on BitBake, see the :doc:`BitBake User Manual | ||
50 | <bitbake:index>`. | ||
51 | |||
52 | .. _structure-core-build: | ||
53 | |||
54 | ``build/`` | ||
55 | ---------- | ||
56 | |||
57 | This directory contains user configuration files and the output | ||
58 | generated by the OpenEmbedded build system in its standard configuration | ||
59 | where the source tree is combined with the output. The :term:`Build Directory` | ||
60 | is created initially when you ``source`` | ||
61 | the OpenEmbedded build environment setup script (i.e. | ||
62 | :ref:`structure-core-script`). | ||
63 | |||
64 | It is also possible to place output and configuration files in a | ||
65 | directory separate from the :term:`Source Directory` by | ||
66 | providing a directory name when you ``source`` the setup script. For | ||
67 | information on separating output from your local Source Directory files | ||
68 | (commonly described as an "out of tree" build), see the | ||
69 | ":ref:`structure-core-script`" section. | ||
70 | |||
71 | .. _handbook: | ||
72 | |||
73 | ``documentation/`` | ||
74 | ------------------ | ||
75 | |||
76 | This directory holds the source for the Yocto Project documentation as | ||
77 | well as templates and tools that allow you to generate PDF and HTML | ||
78 | versions of the manuals. Each manual is contained in its own sub-folder; | ||
79 | for example, the files for this reference manual reside in the | ||
80 | ``ref-manual/`` directory. | ||
81 | |||
82 | .. _structure-core-meta: | ||
83 | |||
84 | ``meta/`` | ||
85 | --------- | ||
86 | |||
87 | This directory contains the minimal, underlying OpenEmbedded-Core | ||
88 | metadata. The directory holds recipes, common classes, and machine | ||
89 | configuration for strictly emulated targets (``qemux86``, ``qemuarm``, | ||
90 | and so forth.) | ||
91 | |||
92 | .. _structure-core-meta-poky: | ||
93 | |||
94 | ``meta-poky/`` | ||
95 | -------------- | ||
96 | |||
97 | Designed above the ``meta/`` content, this directory adds just enough | ||
98 | metadata to define the Poky reference distribution. | ||
99 | |||
100 | .. _structure-core-meta-yocto-bsp: | ||
101 | |||
102 | ``meta-yocto-bsp/`` | ||
103 | ------------------- | ||
104 | |||
105 | This directory contains the Yocto Project reference hardware Board | ||
106 | Support Packages (BSPs). For more information on BSPs, see the | ||
107 | :doc:`../bsp-guide/bsp-guide`. | ||
108 | |||
109 | .. _structure-meta-selftest: | ||
110 | |||
111 | ``meta-selftest/`` | ||
112 | ------------------ | ||
113 | |||
114 | This directory adds additional recipes and append files used by the | ||
115 | OpenEmbedded selftests to verify the behavior of the build system. You | ||
116 | do not have to add this layer to your ``bblayers.conf`` file unless you | ||
117 | want to run the selftests. | ||
118 | |||
119 | .. _structure-meta-skeleton: | ||
120 | |||
121 | ``meta-skeleton/`` | ||
122 | ------------------ | ||
123 | |||
124 | This directory contains template recipes for BSP and kernel development. | ||
125 | |||
126 | .. _structure-core-scripts: | ||
127 | |||
128 | ``scripts/`` | ||
129 | ------------ | ||
130 | |||
131 | This directory contains various integration scripts that implement extra | ||
132 | functionality in the Yocto Project environment (e.g. QEMU scripts). The | ||
133 | :ref:`structure-core-script` script prepends this directory to the | ||
134 | shell's ``PATH`` environment variable. | ||
135 | |||
136 | The ``scripts`` directory has useful scripts that assist in contributing | ||
137 | back to the Yocto Project, such as ``create-pull-request`` and | ||
138 | ``send-pull-request``. | ||
139 | |||
140 | .. _structure-core-script: | ||
141 | |||
142 | ``oe-init-build-env`` | ||
143 | --------------------- | ||
144 | |||
145 | This script sets up the OpenEmbedded build environment. Running this | ||
146 | script with the ``source`` command in a shell makes changes to ``PATH`` | ||
147 | and sets other core BitBake variables based on the current working | ||
148 | directory. You need to run an environment setup script before running | ||
149 | BitBake commands. The script uses other scripts within the ``scripts`` | ||
150 | directory to do the bulk of the work. | ||
151 | |||
152 | When you run this script, your Yocto Project environment is set up, a | ||
153 | :term:`Build Directory` is created, your working | ||
154 | directory becomes the Build Directory, and you are presented with some | ||
155 | simple suggestions as to what to do next, including a list of some | ||
156 | possible targets to build. Here is an example: | ||
157 | :: | ||
158 | |||
159 | $ source oe-init-build-env | ||
160 | |||
161 | ### Shell environment set up for builds. ### | ||
162 | |||
163 | You can now run 'bitbake <target>' | ||
164 | |||
165 | Common targets are: | ||
166 | core-image-minimal | ||
167 | core-image-sato | ||
168 | meta-toolchain | ||
169 | meta-ide-support | ||
170 | |||
171 | You can also run generated qemu images with a command like 'runqemu qemux86-64' | ||
172 | |||
173 | The default output of the ``oe-init-build-env`` script is from the | ||
174 | ``conf-notes.txt`` file, which is found in the ``meta-poky`` directory | ||
175 | within the :term:`Source Directory`. If you design a | ||
176 | custom distribution, you can include your own version of this | ||
177 | configuration file to mention the targets defined by your distribution. | ||
178 | See the | ||
179 | ":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`" | ||
180 | section in the Yocto Project Development Tasks Manual for more | ||
181 | information. | ||
182 | |||
183 | By default, running this script without a Build Directory argument | ||
184 | creates the ``build/`` directory in your current working directory. If | ||
185 | you provide a Build Directory argument when you ``source`` the script, | ||
186 | you direct the OpenEmbedded build system to create a Build Directory of | ||
187 | your choice. For example, the following command creates a Build | ||
188 | Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`: | ||
189 | :: | ||
190 | |||
191 | $ source OE_INIT_FILE ~/mybuilds | ||
192 | |||
193 | The OpenEmbedded build system uses the template configuration files, which | ||
194 | are found by default in the ``meta-poky/conf/`` directory in the Source | ||
195 | Directory. See the | ||
196 | ":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`" | ||
197 | section in the Yocto Project Development Tasks Manual for more | ||
198 | information. | ||
199 | |||
200 | .. note:: | ||
201 | |||
202 | The OpenEmbedded build system does not support file or directory | ||
203 | names that contain spaces. If you attempt to run the | ||
204 | OE_INIT_FILE | ||
205 | script from a Source Directory that contains spaces in either the | ||
206 | filenames or directory names, the script returns an error indicating | ||
207 | no such file or directory. Be sure to use a Source Directory free of | ||
208 | names containing spaces. | ||
209 | |||
210 | .. _structure-basic-top-level: | ||
211 | |||
212 | ``LICENSE, README, and README.hardware`` | ||
213 | ---------------------------------------- | ||
214 | |||
215 | These files are standard top-level files. | ||
216 | |||
217 | .. _structure-build: | ||
218 | |||
219 | The Build Directory - ``build/`` | ||
220 | ================================ | ||
221 | |||
222 | The OpenEmbedded build system creates the :term:`Build Directory` | ||
223 | when you run the build environment setup | ||
224 | script :ref:`structure-core-script`. If you do not give the Build | ||
225 | Directory a specific name when you run the setup script, the name | ||
226 | defaults to ``build/``. | ||
227 | |||
228 | For subsequent parsing and processing, the name of the Build directory | ||
229 | is available via the :term:`TOPDIR` variable. | ||
230 | |||
231 | .. _structure-build-buildhistory: | ||
232 | |||
233 | ``build/buildhistory/`` | ||
234 | ----------------------- | ||
235 | |||
236 | The OpenEmbedded build system creates this directory when you enable | ||
237 | build history via the ``buildhistory`` class file. The directory | ||
238 | organizes build information into image, packages, and SDK | ||
239 | subdirectories. For information on the build history feature, see the | ||
240 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" | ||
241 | section in the Yocto Project Development Tasks Manual. | ||
242 | |||
243 | .. _structure-build-conf-local.conf: | ||
244 | |||
245 | ``build/conf/local.conf`` | ||
246 | ------------------------- | ||
247 | |||
248 | This configuration file contains all the local user configurations for | ||
249 | your build environment. The ``local.conf`` file contains documentation | ||
250 | on the various configuration options. Any variable set here overrides | ||
251 | any variable set elsewhere within the environment unless that variable | ||
252 | is hard-coded within a file (e.g. by using '=' instead of '?='). Some | ||
253 | variables are hard-coded for various reasons but such variables are | ||
254 | relatively rare. | ||
255 | |||
256 | At a minimum, you would normally edit this file to select the target | ||
257 | ``MACHINE``, which package types you wish to use | ||
258 | (:term:`PACKAGE_CLASSES`), and the location from | ||
259 | which you want to access downloaded files (``DL_DIR``). | ||
260 | |||
261 | If ``local.conf`` is not present when you start the build, the | ||
262 | OpenEmbedded build system creates it from ``local.conf.sample`` when you | ||
263 | ``source`` the top-level build environment setup script | ||
264 | :ref:`structure-core-script`. | ||
265 | |||
266 | The source ``local.conf.sample`` file used depends on the | ||
267 | ``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/`` | ||
268 | when you are building from the Yocto Project development environment, | ||
269 | and to ``meta/conf/`` when you are building from the OpenEmbedded-Core | ||
270 | environment. Because the script variable points to the source of the | ||
271 | ``local.conf.sample`` file, this implies that you can configure your | ||
272 | build environment from any layer by setting the variable in the | ||
273 | top-level build environment setup script as follows: | ||
274 | :: | ||
275 | |||
276 | TEMPLATECONF=your_layer/conf | ||
277 | |||
278 | Once the build process gets the sample | ||
279 | file, it uses ``sed`` to substitute final | ||
280 | ``${``\ :term:`OEROOT`\ ``}`` values for all | ||
281 | ``##OEROOT##`` values. | ||
282 | |||
283 | .. note:: | ||
284 | |||
285 | You can see how the | ||
286 | TEMPLATECONF | ||
287 | variable is used by looking at the | ||
288 | scripts/oe-setup-builddir | ||
289 | script in the | ||
290 | Source Directory | ||
291 | . You can find the Yocto Project version of the | ||
292 | local.conf.sample | ||
293 | file in the | ||
294 | meta-poky/conf | ||
295 | directory. | ||
296 | |||
297 | .. _structure-build-conf-bblayers.conf: | ||
298 | |||
299 | ``build/conf/bblayers.conf`` | ||
300 | ---------------------------- | ||
301 | |||
302 | This configuration file defines | ||
303 | :ref:`layers <dev-manual/dev-manual-common-tasks:understanding and creating layers>`, | ||
304 | which are directory trees, traversed (or walked) by BitBake. The | ||
305 | ``bblayers.conf`` file uses the :term:`BBLAYERS` | ||
306 | variable to list the layers BitBake tries to find. | ||
307 | |||
308 | If ``bblayers.conf`` is not present when you start the build, the | ||
309 | OpenEmbedded build system creates it from ``bblayers.conf.sample`` when | ||
310 | you ``source`` the top-level build environment setup script (i.e. | ||
311 | :ref:`structure-core-script`). | ||
312 | |||
313 | As with the ``local.conf`` file, the source ``bblayers.conf.sample`` | ||
314 | file used depends on the ``$TEMPLATECONF`` script variable, which | ||
315 | defaults to ``meta-poky/conf/`` when you are building from the Yocto | ||
316 | Project development environment, and to ``meta/conf/`` when you are | ||
317 | building from the OpenEmbedded-Core environment. Because the script | ||
318 | variable points to the source of the ``bblayers.conf.sample`` file, this | ||
319 | implies that you can base your build from any layer by setting the | ||
320 | variable in the top-level build environment setup script as follows: | ||
321 | :: | ||
322 | |||
323 | TEMPLATECONF=your_layer/conf | ||
324 | |||
325 | Once the build process gets the sample file, it uses ``sed`` to substitute final | ||
326 | ``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values. | ||
327 | |||
328 | .. note:: | ||
329 | |||
330 | You can see how the | ||
331 | TEMPLATECONF | ||
332 | variable | ||
333 | scripts/oe-setup-builddir | ||
334 | script in the | ||
335 | Source Directory | ||
336 | . You can find the Yocto Project version of the | ||
337 | bblayers.conf.sample | ||
338 | file in the | ||
339 | meta-poky/conf/ | ||
340 | directory. | ||
341 | |||
342 | .. _structure-build-conf-sanity_info: | ||
343 | |||
344 | ``build/cache/sanity_info`` | ||
345 | --------------------------- | ||
346 | |||
347 | This file indicates the state of the sanity checks and is created during | ||
348 | the build. | ||
349 | |||
350 | .. _structure-build-downloads: | ||
351 | |||
352 | ``build/downloads/`` | ||
353 | -------------------- | ||
354 | |||
355 | This directory contains downloaded upstream source tarballs. You can | ||
356 | reuse the directory for multiple builds or move the directory to another | ||
357 | location. You can control the location of this directory through the | ||
358 | ``DL_DIR`` variable. | ||
359 | |||
360 | .. _structure-build-sstate-cache: | ||
361 | |||
362 | ``build/sstate-cache/`` | ||
363 | ----------------------- | ||
364 | |||
365 | This directory contains the shared state cache. You can reuse the | ||
366 | directory for multiple builds or move the directory to another location. | ||
367 | You can control the location of this directory through the | ||
368 | ``SSTATE_DIR`` variable. | ||
369 | |||
370 | .. _structure-build-tmp: | ||
371 | |||
372 | ``build/tmp/`` | ||
373 | -------------- | ||
374 | |||
375 | The OpenEmbedded build system creates and uses this directory for all | ||
376 | the build system's output. The :term:`TMPDIR` variable | ||
377 | points to this directory. | ||
378 | |||
379 | BitBake creates this directory if it does not exist. As a last resort, | ||
380 | to clean up a build and start it from scratch (other than the | ||
381 | downloads), you can remove everything in the ``tmp`` directory or get | ||
382 | rid of the directory completely. If you do, you should also completely | ||
383 | remove the ``build/sstate-cache`` directory. | ||
384 | |||
385 | .. _structure-build-tmp-buildstats: | ||
386 | |||
387 | ``build/tmp/buildstats/`` | ||
388 | ------------------------- | ||
389 | |||
390 | This directory stores the build statistics. | ||
391 | |||
392 | .. _structure-build-tmp-cache: | ||
393 | |||
394 | ``build/tmp/cache/`` | ||
395 | -------------------- | ||
396 | |||
397 | When BitBake parses the metadata (recipes and configuration files), it | ||
398 | caches the results in ``build/tmp/cache/`` to speed up future builds. | ||
399 | The results are stored on a per-machine basis. | ||
400 | |||
401 | During subsequent builds, BitBake checks each recipe (together with, for | ||
402 | example, any files included or appended to it) to see if they have been | ||
403 | modified. Changes can be detected, for example, through file | ||
404 | modification time (mtime) changes and hashing of file contents. If no | ||
405 | changes to the file are detected, then the parsed result stored in the | ||
406 | cache is reused. If the file has changed, it is reparsed. | ||
407 | |||
408 | .. _structure-build-tmp-deploy: | ||
409 | |||
410 | ``build/tmp/deploy/`` | ||
411 | --------------------- | ||
412 | |||
413 | This directory contains any "end result" output from the OpenEmbedded | ||
414 | build process. The :term:`DEPLOY_DIR` variable points | ||
415 | to this directory. For more detail on the contents of the ``deploy`` | ||
416 | directory, see the | ||
417 | ":ref:`images-dev-environment`" and | ||
418 | ":ref:`sdk-dev-environment`" sections in the Yocto | ||
419 | Project Overview and Concepts Manual. | ||
420 | |||
421 | .. _structure-build-tmp-deploy-deb: | ||
422 | |||
423 | ``build/tmp/deploy/deb/`` | ||
424 | ------------------------- | ||
425 | |||
426 | This directory receives any ``.deb`` packages produced by the build | ||
427 | process. The packages are sorted into feeds for different architecture | ||
428 | types. | ||
429 | |||
430 | .. _structure-build-tmp-deploy-rpm: | ||
431 | |||
432 | ``build/tmp/deploy/rpm/`` | ||
433 | ------------------------- | ||
434 | |||
435 | This directory receives any ``.rpm`` packages produced by the build | ||
436 | process. The packages are sorted into feeds for different architecture | ||
437 | types. | ||
438 | |||
439 | .. _structure-build-tmp-deploy-ipk: | ||
440 | |||
441 | ``build/tmp/deploy/ipk/`` | ||
442 | ------------------------- | ||
443 | |||
444 | This directory receives ``.ipk`` packages produced by the build process. | ||
445 | |||
446 | .. _structure-build-tmp-deploy-licenses: | ||
447 | |||
448 | ``build/tmp/deploy/licenses/`` | ||
449 | ------------------------------ | ||
450 | |||
451 | This directory receives package licensing information. For example, the | ||
452 | directory contains sub-directories for ``bash``, ``busybox``, and | ||
453 | ``glibc`` (among others) that in turn contain appropriate ``COPYING`` | ||
454 | license files with other licensing information. For information on | ||
455 | licensing, see the | ||
456 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" | ||
457 | section in the Yocto Project Development Tasks Manual. | ||
458 | |||
459 | .. _structure-build-tmp-deploy-images: | ||
460 | |||
461 | ``build/tmp/deploy/images/`` | ||
462 | ---------------------------- | ||
463 | |||
464 | This directory is populated with the basic output objects of the build | ||
465 | (think of them as the "generated artifacts" of the build process), | ||
466 | including things like the boot loader image, kernel, root filesystem and | ||
467 | more. If you want to flash the resulting image from a build onto a | ||
468 | device, look here for the necessary components. | ||
469 | |||
470 | Be careful when deleting files in this directory. You can safely delete | ||
471 | old images from this directory (e.g. ``core-image-*``). However, the | ||
472 | kernel (``*zImage*``, ``*uImage*``, etc.), bootloader and other | ||
473 | supplementary files might be deployed here prior to building an image. | ||
474 | Because these files are not directly produced from the image, if you | ||
475 | delete them they will not be automatically re-created when you build the | ||
476 | image again. | ||
477 | |||
478 | If you do accidentally delete files here, you will need to force them to | ||
479 | be re-created. In order to do that, you will need to know the target | ||
480 | that produced them. For example, these commands rebuild and re-create | ||
481 | the kernel files: | ||
482 | :: | ||
483 | |||
484 | $ bitbake -c clean virtual/kernel | ||
485 | $ bitbake virtual/kernel | ||
486 | |||
487 | .. _structure-build-tmp-deploy-sdk: | ||
488 | |||
489 | ``build/tmp/deploy/sdk/`` | ||
490 | ------------------------- | ||
491 | |||
492 | The OpenEmbedded build system creates this directory to hold toolchain | ||
493 | installer scripts which, when executed, install the sysroot that matches | ||
494 | your target hardware. You can find out more about these installers in | ||
495 | the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`" | ||
496 | section in the Yocto Project Application Development and the Extensible | ||
497 | Software Development Kit (eSDK) manual. | ||
498 | |||
499 | .. _structure-build-tmp-sstate-control: | ||
500 | |||
501 | ``build/tmp/sstate-control/`` | ||
502 | ----------------------------- | ||
503 | |||
504 | The OpenEmbedded build system uses this directory for the shared state | ||
505 | manifest files. The shared state code uses these files to record the | ||
506 | files installed by each sstate task so that the files can be removed | ||
507 | when cleaning the recipe or when a newer version is about to be | ||
508 | installed. The build system also uses the manifests to detect and | ||
509 | produce a warning when files from one task are overwriting those from | ||
510 | another. | ||
511 | |||
512 | .. _structure-build-tmp-sysroots-components: | ||
513 | |||
514 | ``build/tmp/sysroots-components/`` | ||
515 | ---------------------------------- | ||
516 | |||
517 | This directory is the location of the sysroot contents that the task | ||
518 | :ref:`ref-tasks-prepare_recipe_sysroot` | ||
519 | links or copies into the recipe-specific sysroot for each recipe listed | ||
520 | in :term:`DEPENDS`. Population of this directory is | ||
521 | handled through shared state, while the path is specified by the | ||
522 | :term:`COMPONENTS_DIR` variable. Apart from a few | ||
523 | unusual circumstances, handling of the ``sysroots-components`` directory | ||
524 | should be automatic, and recipes should not directly reference | ||
525 | ``build/tmp/sysroots-components``. | ||
526 | |||
527 | .. _structure-build-tmp-sysroots: | ||
528 | |||
529 | ``build/tmp/sysroots/`` | ||
530 | ----------------------- | ||
531 | |||
532 | Previous versions of the OpenEmbedded build system used to create a | ||
533 | global shared sysroot per machine along with a native sysroot. Beginning | ||
534 | with the DISTRO version of the Yocto Project, sysroots exist in | ||
535 | recipe-specific :term:`WORKDIR` directories. Thus, the | ||
536 | ``build/tmp/sysroots/`` directory is unused. | ||
537 | |||
538 | .. note:: | ||
539 | |||
540 | The | ||
541 | build/tmp/sysroots/ | ||
542 | directory can still be populated using the | ||
543 | bitbake build-sysroots | ||
544 | command and can be used for compatibility in some cases. However, in | ||
545 | general it is not recommended to populate this directory. Individual | ||
546 | recipe-specific sysroots should be used. | ||
547 | |||
548 | .. _structure-build-tmp-stamps: | ||
549 | |||
550 | ``build/tmp/stamps/`` | ||
551 | --------------------- | ||
552 | |||
553 | This directory holds information that BitBake uses for accounting | ||
554 | purposes to track what tasks have run and when they have run. The | ||
555 | directory is sub-divided by architecture, package name, and version. | ||
556 | Following is an example: | ||
557 | stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do Although | ||
558 | the files in the directory are empty of data, BitBake uses the filenames | ||
559 | and timestamps for tracking purposes. | ||
560 | |||
561 | For information on how BitBake uses stamp files to determine if a task | ||
562 | should be rerun, see the | ||
563 | ":ref:`overview-manual/overview-manual-concepts:stamp files and the rerunning of tasks`" | ||
564 | section in the Yocto Project Overview and Concepts Manual. | ||
565 | |||
566 | .. _structure-build-tmp-log: | ||
567 | |||
568 | ``build/tmp/log/`` | ||
569 | ------------------ | ||
570 | |||
571 | This directory contains general logs that are not otherwise placed using | ||
572 | the package's ``WORKDIR``. Examples of logs are the output from the | ||
573 | ``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not | ||
574 | necessarily mean this directory is created. | ||
575 | |||
576 | .. _structure-build-tmp-work: | ||
577 | |||
578 | ``build/tmp/work/`` | ||
579 | ------------------- | ||
580 | |||
581 | This directory contains architecture-specific work sub-directories for | ||
582 | packages built by BitBake. All tasks execute from the appropriate work | ||
583 | directory. For example, the source for a particular package is unpacked, | ||
584 | patched, configured and compiled all within its own work directory. | ||
585 | Within the work directory, organization is based on the package group | ||
586 | and version for which the source is being compiled as defined by the | ||
587 | :term:`WORKDIR`. | ||
588 | |||
589 | It is worth considering the structure of a typical work directory. As an | ||
590 | example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86`` | ||
591 | built within the Yocto Project. For this package, a work directory of | ||
592 | ``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred | ||
593 | to as the ``WORKDIR``, is created. Within this directory, the source is | ||
594 | unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. | ||
595 | (See the ":ref:`using-a-quilt-workflow`" section in | ||
596 | the Yocto Project Development Tasks Manual for more information.) Within | ||
597 | the ``linux-qemux86-standard-build`` directory, standard Quilt | ||
598 | directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and | ||
599 | standard Quilt commands can be used. | ||
600 | |||
601 | There are other directories generated within ``WORKDIR``. The most | ||
602 | important directory is ``WORKDIR/temp/``, which has log files for each | ||
603 | task (``log.do_*.pid``) and contains the scripts BitBake runs for each | ||
604 | task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make | ||
605 | install" places its output that is then split into sub-packages within | ||
606 | ``WORKDIR/packages-split/``. | ||
607 | |||
608 | .. _structure-build-tmp-work-tunearch-recipename-version: | ||
609 | |||
610 | ``build/tmp/work/tunearch/recipename/version/`` | ||
611 | ----------------------------------------------- | ||
612 | |||
613 | The recipe work directory - ``${WORKDIR}``. | ||
614 | |||
615 | As described earlier in the | ||
616 | "```build/tmp/sysroots/`` <#structure-build-tmp-sysroots>`__" section, | ||
617 | beginning with the DISTRO release of the Yocto Project, the OpenEmbedded | ||
618 | build system builds each recipe in its own work directory (i.e. | ||
619 | :term:`WORKDIR`). The path to the work directory is | ||
620 | constructed using the architecture of the given build (e.g. | ||
621 | :term:`TUNE_PKGARCH`, | ||
622 | :term:`MACHINE_ARCH`, or "allarch"), the recipe | ||
623 | name, and the version of the recipe (i.e. | ||
624 | :term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`). | ||
625 | |||
626 | A number of key subdirectories exist within each recipe work directory: | ||
627 | |||
628 | - ``${WORKDIR}/temp``: Contains the log files of each task executed for | ||
629 | this recipe, the "run" files for each executed task, which contain | ||
630 | the code run, and a ``log.task_order`` file, which lists the order in | ||
631 | which tasks were executed. | ||
632 | |||
633 | - ``${WORKDIR}/image``: Contains the output of the | ||
634 | :ref:`ref-tasks-install` task, which corresponds to | ||
635 | the ``${``\ :term:`D`\ ``}`` variable in that task. | ||
636 | |||
637 | - ``${WORKDIR}/pseudo``: Contains the pseudo database and log for any | ||
638 | tasks executed under pseudo for the recipe. | ||
639 | |||
640 | - ``${WORKDIR}/sysroot-destdir``: Contains the output of the | ||
641 | :ref:`ref-tasks-populate_sysroot` task. | ||
642 | |||
643 | - ``${WORKDIR}/package``: Contains the output of the | ||
644 | :ref:`ref-tasks-package` task before the output is | ||
645 | split into individual packages. | ||
646 | |||
647 | - ``${WORKDIR}/packages-split``: Contains the output of the | ||
648 | ``do_package`` task after the output has been split into individual | ||
649 | packages. Subdirectories exist for each individual package created by | ||
650 | the recipe. | ||
651 | |||
652 | - ``${WORKDIR}/recipe-sysroot``: A directory populated with the target | ||
653 | dependencies of the recipe. This directory looks like the target | ||
654 | filesystem and contains libraries that the recipe might need to link | ||
655 | against (e.g. the C library). | ||
656 | |||
657 | - ``${WORKDIR}/recipe-sysroot-native``: A directory populated with the | ||
658 | native dependencies of the recipe. This directory contains the tools | ||
659 | the recipe needs to build (e.g. the compiler, Autoconf, libtool, and | ||
660 | so forth). | ||
661 | |||
662 | - ``${WORKDIR}/build``: This subdirectory applies only to recipes that | ||
663 | support builds where the source is separate from the build artifacts. | ||
664 | The OpenEmbedded build system uses this directory as a separate build | ||
665 | directory (i.e. ``${``\ :term:`B`\ ``}``). | ||
666 | |||
667 | .. _structure-build-work-shared: | ||
668 | |||
669 | ``build/tmp/work-shared/`` | ||
670 | -------------------------- | ||
671 | |||
672 | For efficiency, the OpenEmbedded build system creates and uses this | ||
673 | directory to hold recipes that share a work directory with other | ||
674 | recipes. In practice, this is only used for ``gcc`` and its variants | ||
675 | (e.g. ``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth). | ||
676 | |||
677 | .. _structure-meta: | ||
678 | |||
679 | The Metadata - ``meta/`` | ||
680 | ======================== | ||
681 | |||
682 | As mentioned previously, :term:`Metadata` is the core of the | ||
683 | Yocto Project. Metadata has several important subdivisions: | ||
684 | |||
685 | .. _structure-meta-classes: | ||
686 | |||
687 | ``meta/classes/`` | ||
688 | ----------------- | ||
689 | |||
690 | This directory contains the ``*.bbclass`` files. Class files are used to | ||
691 | abstract common code so it can be reused by multiple packages. Every | ||
692 | package inherits the ``base.bbclass`` file. Examples of other important | ||
693 | classes are ``autotools.bbclass``, which in theory allows any | ||
694 | Autotool-enabled package to work with the Yocto Project with minimal | ||
695 | effort. Another example is ``kernel.bbclass`` that contains common code | ||
696 | and functions for working with the Linux kernel. Functions like image | ||
697 | generation or packaging also have their specific class files such as | ||
698 | ``image.bbclass``, ``rootfs_*.bbclass`` and ``package*.bbclass``. | ||
699 | |||
700 | For reference information on classes, see the | ||
701 | ":ref:`ref-manual/ref-classes:Classes`" chapter. | ||
702 | |||
703 | .. _structure-meta-conf: | ||
704 | |||
705 | ``meta/conf/`` | ||
706 | -------------- | ||
707 | |||
708 | This directory contains the core set of configuration files that start | ||
709 | from ``bitbake.conf`` and from which all other configuration files are | ||
710 | included. See the include statements at the end of the ``bitbake.conf`` | ||
711 | file and you will note that even ``local.conf`` is loaded from there. | ||
712 | While ``bitbake.conf`` sets up the defaults, you can often override | ||
713 | these by using the (``local.conf``) file, machine file or the | ||
714 | distribution configuration file. | ||
715 | |||
716 | .. _structure-meta-conf-machine: | ||
717 | |||
718 | ``meta/conf/machine/`` | ||
719 | ---------------------- | ||
720 | |||
721 | This directory contains all the machine configuration files. If you set | ||
722 | ``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a | ||
723 | ``qemux86.conf`` file in this directory. The ``include`` directory | ||
724 | contains various data common to multiple machines. If you want to add | ||
725 | support for a new machine to the Yocto Project, look in this directory. | ||
726 | |||
727 | .. _structure-meta-conf-distro: | ||
728 | |||
729 | ``meta/conf/distro/`` | ||
730 | --------------------- | ||
731 | |||
732 | The contents of this directory controls any distribution-specific | ||
733 | configurations. For the Yocto Project, the ``defaultsetup.conf`` is the | ||
734 | main file here. This directory includes the versions and the ``SRCDATE`` | ||
735 | definitions for applications that are configured here. An example of an | ||
736 | alternative configuration might be ``poky-bleeding.conf``. Although this | ||
737 | file mainly inherits its configuration from Poky. | ||
738 | |||
739 | .. _structure-meta-conf-machine-sdk: | ||
740 | |||
741 | ``meta/conf/machine-sdk/`` | ||
742 | -------------------------- | ||
743 | |||
744 | The OpenEmbedded build system searches this directory for configuration | ||
745 | files that correspond to the value of | ||
746 | :term:`SDKMACHINE`. By default, 32-bit and 64-bit x86 | ||
747 | files ship with the Yocto Project that support some SDK hosts. However, | ||
748 | it is possible to extend that support to other SDK hosts by adding | ||
749 | additional configuration files in this subdirectory within another | ||
750 | layer. | ||
751 | |||
752 | .. _structure-meta-files: | ||
753 | |||
754 | ``meta/files/`` | ||
755 | --------------- | ||
756 | |||
757 | This directory contains common license files and several text files used | ||
758 | by the build system. The text files contain minimal device information | ||
759 | and lists of files and directories with known permissions. | ||
760 | |||
761 | .. _structure-meta-lib: | ||
762 | |||
763 | ``meta/lib/`` | ||
764 | ------------- | ||
765 | |||
766 | This directory contains OpenEmbedded Python library code used during the | ||
767 | build process. | ||
768 | |||
769 | .. _structure-meta-recipes-bsp: | ||
770 | |||
771 | ``meta/recipes-bsp/`` | ||
772 | --------------------- | ||
773 | |||
774 | This directory contains anything linking to specific hardware or | ||
775 | hardware configuration information such as "u-boot" and "grub". | ||
776 | |||
777 | .. _structure-meta-recipes-connectivity: | ||
778 | |||
779 | ``meta/recipes-connectivity/`` | ||
780 | ------------------------------ | ||
781 | |||
782 | This directory contains libraries and applications related to | ||
783 | communication with other devices. | ||
784 | |||
785 | .. _structure-meta-recipes-core: | ||
786 | |||
787 | ``meta/recipes-core/`` | ||
788 | ---------------------- | ||
789 | |||
790 | This directory contains what is needed to build a basic working Linux | ||
791 | image including commonly used dependencies. | ||
792 | |||
793 | .. _structure-meta-recipes-devtools: | ||
794 | |||
795 | ``meta/recipes-devtools/`` | ||
796 | -------------------------- | ||
797 | |||
798 | This directory contains tools that are primarily used by the build | ||
799 | system. The tools, however, can also be used on targets. | ||
800 | |||
801 | .. _structure-meta-recipes-extended: | ||
802 | |||
803 | ``meta/recipes-extended/`` | ||
804 | -------------------------- | ||
805 | |||
806 | This directory contains non-essential applications that add features | ||
807 | compared to the alternatives in core. You might need this directory for | ||
808 | full tool functionality or for Linux Standard Base (LSB) compliance. | ||
809 | |||
810 | .. _structure-meta-recipes-gnome: | ||
811 | |||
812 | ``meta/recipes-gnome/`` | ||
813 | ----------------------- | ||
814 | |||
815 | This directory contains all things related to the GTK+ application | ||
816 | framework. | ||
817 | |||
818 | .. _structure-meta-recipes-graphics: | ||
819 | |||
820 | ``meta/recipes-graphics/`` | ||
821 | -------------------------- | ||
822 | |||
823 | This directory contains X and other graphically related system | ||
824 | libraries. | ||
825 | |||
826 | .. _structure-meta-recipes-kernel: | ||
827 | |||
828 | ``meta/recipes-kernel/`` | ||
829 | ------------------------ | ||
830 | |||
831 | This directory contains the kernel and generic applications and | ||
832 | libraries that have strong kernel dependencies. | ||
833 | |||
834 | .. _structure-meta-recipes-lsb4: | ||
835 | |||
836 | ``meta/recipes-lsb4/`` | ||
837 | ---------------------- | ||
838 | |||
839 | This directory contains recipes specifically added to support the Linux | ||
840 | Standard Base (LSB) version 4.x. | ||
841 | |||
842 | .. _structure-meta-recipes-multimedia: | ||
843 | |||
844 | ``meta/recipes-multimedia/`` | ||
845 | ---------------------------- | ||
846 | |||
847 | This directory contains codecs and support utilities for audio, images | ||
848 | and video. | ||
849 | |||
850 | .. _structure-meta-recipes-rt: | ||
851 | |||
852 | ``meta/recipes-rt/`` | ||
853 | -------------------- | ||
854 | |||
855 | This directory contains package and image recipes for using and testing | ||
856 | the ``PREEMPT_RT`` kernel. | ||
857 | |||
858 | .. _structure-meta-recipes-sato: | ||
859 | |||
860 | ``meta/recipes-sato/`` | ||
861 | ---------------------- | ||
862 | |||
863 | This directory contains the Sato demo/reference UI/UX and its associated | ||
864 | applications and configuration data. | ||
865 | |||
866 | .. _structure-meta-recipes-support: | ||
867 | |||
868 | ``meta/recipes-support/`` | ||
869 | ------------------------- | ||
870 | |||
871 | This directory contains recipes used by other recipes, but that are not | ||
872 | directly included in images (i.e. dependencies of other recipes). | ||
873 | |||
874 | .. _structure-meta-site: | ||
875 | |||
876 | ``meta/site/`` | ||
877 | -------------- | ||
878 | |||
879 | This directory contains a list of cached results for various | ||
880 | architectures. Because certain "autoconf" test results cannot be | ||
881 | determined when cross-compiling due to the tests not able to run on a | ||
882 | live system, the information in this directory is passed to "autoconf" | ||
883 | for the various architectures. | ||
884 | |||
885 | .. _structure-meta-recipes-txt: | ||
886 | |||
887 | ``meta/recipes.txt`` | ||
888 | -------------------- | ||
889 | |||
890 | This file is a description of the contents of ``recipes-*``. | ||