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