diff options
Diffstat (limited to 'documentation/overview-manual/concepts.rst')
-rw-r--r-- | documentation/overview-manual/concepts.rst | 93 |
1 files changed, 49 insertions, 44 deletions
diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst index f0c7dab4c8..ada5143b2a 100644 --- a/documentation/overview-manual/concepts.rst +++ b/documentation/overview-manual/concepts.rst | |||
@@ -132,7 +132,7 @@ Layers | |||
132 | 132 | ||
133 | Layers are repositories that contain related metadata (i.e. sets of | 133 | Layers are repositories that contain related metadata (i.e. sets of |
134 | instructions) that tell the OpenEmbedded build system how to build a | 134 | instructions) that tell the OpenEmbedded build system how to build a |
135 | target. Yocto Project's `layer model <#the-yocto-project-layer-model>`__ | 135 | target. :ref:`overview-manual/yp-intro:the yocto project layer model` |
136 | facilitates collaboration, sharing, customization, and reuse within the | 136 | facilitates collaboration, sharing, customization, and reuse within the |
137 | Yocto Project development environment. Layers logically separate | 137 | Yocto Project development environment. Layers logically separate |
138 | information for your project. For example, you can use a layer to hold | 138 | information for your project. For example, you can use a layer to hold |
@@ -207,8 +207,8 @@ you can tell BitBake the target architecture for which you are building | |||
207 | the image, where to store downloaded source, and other build properties. | 207 | the image, where to store downloaded source, and other build properties. |
208 | 208 | ||
209 | The following figure shows an expanded representation of the "User | 209 | The following figure shows an expanded representation of the "User |
210 | Configuration" box of the `general workflow | 210 | Configuration" box of the :ref:`general workflow |
211 | figure <#general-workflow-figure>`__: | 211 | figure <overview-manual/concepts:openembedded build system concepts>`: |
212 | 212 | ||
213 | .. image:: figures/user-configuration.png | 213 | .. image:: figures/user-configuration.png |
214 | :align: center | 214 | :align: center |
@@ -374,7 +374,7 @@ provide Metadata for the software, machine, and policies. | |||
374 | 374 | ||
375 | In general, three types of layer input exists. You can see them below | 375 | In general, three types of layer input exists. You can see them below |
376 | the "User Configuration" box in the `general workflow | 376 | the "User Configuration" box in the `general workflow |
377 | figure <#general-workflow-figure>`__: | 377 | figure <overview-manual/concepts:openembedded build system concepts>`: |
378 | 378 | ||
379 | - *Metadata (.bb + Patches):* Software layers containing | 379 | - *Metadata (.bb + Patches):* Software layers containing |
380 | user-supplied recipe files, patches, and append files. A good example | 380 | user-supplied recipe files, patches, and append files. A good example |
@@ -387,8 +387,8 @@ figure <#general-workflow-figure>`__: | |||
387 | - *Machine BSP Configuration:* Board Support Package (BSP) layers (i.e. | 387 | - *Machine BSP Configuration:* Board Support Package (BSP) layers (i.e. |
388 | "BSP Layer" in the following figure) providing machine-specific | 388 | "BSP Layer" in the following figure) providing machine-specific |
389 | configurations. This type of information is specific to a particular | 389 | configurations. This type of information is specific to a particular |
390 | target architecture. A good example of a BSP layer from the `Poky | 390 | target architecture. A good example of a BSP layer from the |
391 | Reference Distribution <#gs-reference-distribution-poky>`__ is the | 391 | :ref:`overview-manual/yp-intro:reference distribution (poky)` is the |
392 | :yocto_git:`meta-yocto-bsp </poky/tree/meta-yocto-bsp>` | 392 | :yocto_git:`meta-yocto-bsp </poky/tree/meta-yocto-bsp>` |
393 | layer. | 393 | layer. |
394 | 394 | ||
@@ -403,7 +403,8 @@ figure <#general-workflow-figure>`__: | |||
403 | that contain many policy configurations for the Poky distribution. | 403 | that contain many policy configurations for the Poky distribution. |
404 | 404 | ||
405 | The following figure shows an expanded representation of these three | 405 | The following figure shows an expanded representation of these three |
406 | layers from the `general workflow figure <#general-workflow-figure>`__: | 406 | layers from the :ref:`general workflow figure |
407 | <overview-manual/concepts:openembedded build system concepts>`: | ||
407 | 408 | ||
408 | .. image:: figures/layer-input.png | 409 | .. image:: figures/layer-input.png |
409 | :align: center | 410 | :align: center |
@@ -418,9 +419,9 @@ in the | |||
418 | section in the | 419 | section in the |
419 | Yocto Project Development Tasks Manual. For a general discussion on | 420 | Yocto Project Development Tasks Manual. For a general discussion on |
420 | layers and the many layers from which you can draw, see the | 421 | layers and the many layers from which you can draw, see the |
421 | "`Layers <#overview-layers>`__" and "`The Yocto Project Layer | 422 | ":ref:`overview-manual/concepts:layers`" and |
422 | Model <#the-yocto-project-layer-model>`__" sections both earlier in this | 423 | ":ref:`overview-manual/yp-intro:the yocto project layer model`" sections both |
423 | manual. | 424 | earlier in this manual. |
424 | 425 | ||
425 | If you explored the previous links, you discovered some areas where many | 426 | If you explored the previous links, you discovered some areas where many |
426 | layers that work with the Yocto Project exist. The :yocto_git:`Source | 427 | layers that work with the Yocto Project exist. The :yocto_git:`Source |
@@ -514,11 +515,12 @@ Sources | |||
514 | ------- | 515 | ------- |
515 | 516 | ||
516 | In order for the OpenEmbedded build system to create an image or any | 517 | In order for the OpenEmbedded build system to create an image or any |
517 | target, it must be able to access source files. The `general workflow | 518 | target, it must be able to access source files. The :ref:`general workflow |
518 | figure <#general-workflow-figure>`__ represents source files using the | 519 | figure <overview-manual/concepts:openembedded build system concepts>` |
519 | "Upstream Project Releases", "Local Projects", and "SCMs (optional)" | 520 | represents source files using the "Upstream Project Releases", "Local |
520 | boxes. The figure represents mirrors, which also play a role in locating | 521 | Projects", and "SCMs (optional)" boxes. The figure represents mirrors, |
521 | source files, with the "Source Materials" box. | 522 | which also play a role in locating source files, with the "Source |
523 | Materials" box. | ||
522 | 524 | ||
523 | The method by which source files are ultimately organized is a function | 525 | The method by which source files are ultimately organized is a function |
524 | of the project. For example, for released software, projects tend to use | 526 | of the project. For example, for released software, projects tend to use |
@@ -554,7 +556,7 @@ Directory if needed without fear of removing any downloaded source file. | |||
554 | 556 | ||
555 | The remainder of this section provides a deeper look into the source | 557 | The remainder of this section provides a deeper look into the source |
556 | files and the mirrors. Here is a more detailed look at the source file | 558 | files and the mirrors. Here is a more detailed look at the source file |
557 | area of the `general workflow figure <#general-workflow-figure>`__: | 559 | area of the :ref:`general workflow figure <overview-manual/concepts:openembedded build system concepts>`: |
558 | 560 | ||
559 | .. image:: figures/source-input.png | 561 | .. image:: figures/source-input.png |
560 | :align: center | 562 | :align: center |
@@ -628,9 +630,9 @@ Package Feeds | |||
628 | 630 | ||
629 | When the OpenEmbedded build system generates an image or an SDK, it gets | 631 | When the OpenEmbedded build system generates an image or an SDK, it gets |
630 | the packages from a package feed area located in the | 632 | the packages from a package feed area located in the |
631 | :term:`Build Directory`. The `general | 633 | :term:`Build Directory`. The :ref:`general workflow figure |
632 | workflow figure <#general-workflow-figure>`__ shows this package feeds | 634 | <overview-manual/concepts:openembedded build system concepts>` |
633 | area in the upper-right corner. | 635 | shows this package feeds area in the upper-right corner. |
634 | 636 | ||
635 | This section looks a little closer into the package feeds area used by | 637 | This section looks a little closer into the package feeds area used by |
636 | the build system. Here is a more detailed look at the area: | 638 | the build system. Here is a more detailed look at the area: |
@@ -691,10 +693,10 @@ BitBake Tool | |||
691 | 693 | ||
692 | The OpenEmbedded build system uses | 694 | The OpenEmbedded build system uses |
693 | :term:`BitBake` to produce images and | 695 | :term:`BitBake` to produce images and |
694 | Software Development Kits (SDKs). You can see from the `general workflow | 696 | Software Development Kits (SDKs). You can see from the :ref:`general workflow |
695 | figure <#general-workflow-figure>`__, the BitBake area consists of | 697 | figure <overview-manual/concepts:openembedded build system concepts>`, |
696 | several functional areas. This section takes a closer look at each of | 698 | the BitBake area consists of several functional areas. This section takes a |
697 | those areas. | 699 | closer look at each of those areas. |
698 | 700 | ||
699 | .. note:: | 701 | .. note:: |
700 | 702 | ||
@@ -820,7 +822,7 @@ source files, which are located in the | |||
820 | :term:`S` directory. | 822 | :term:`S` directory. |
821 | 823 | ||
822 | For more information on how the source directories are created, see the | 824 | For more information on how the source directories are created, see the |
823 | "`Source Fetching <#source-fetching-dev-environment>`__" section. For | 825 | ":ref:`overview-manual/concepts:source fetching`" section. For |
824 | more information on how to create patches and how the build system | 826 | more information on how to create patches and how the build system |
825 | processes patches, see the | 827 | processes patches, see the |
826 | ":ref:`dev-manual/common-tasks:patching code`" | 828 | ":ref:`dev-manual/common-tasks:patching code`" |
@@ -957,8 +959,8 @@ details on how this is accomplished, you can look at | |||
957 | Depending on the type of packages being created (RPM, DEB, or IPK), the | 959 | Depending on the type of packages being created (RPM, DEB, or IPK), the |
958 | :ref:`do_package_write_* <ref-tasks-package_write_deb>` | 960 | :ref:`do_package_write_* <ref-tasks-package_write_deb>` |
959 | task creates the actual packages and places them in the Package Feed | 961 | task creates the actual packages and places them in the Package Feed |
960 | area, which is ``${TMPDIR}/deploy``. You can see the "`Package | 962 | area, which is ``${TMPDIR}/deploy``. You can see the |
961 | Feeds <#package-feeds-dev-environment>`__" section for more detail on | 963 | ":ref:`overview-manual/concepts:package feeds`" section for more detail on |
962 | that part of the build process. | 964 | that part of the build process. |
963 | 965 | ||
964 | .. note:: | 966 | .. note:: |
@@ -1119,7 +1121,7 @@ and | |||
1119 | :ref:`ref-tasks-populate_sdk_ext` | 1121 | :ref:`ref-tasks-populate_sdk_ext` |
1120 | tasks use these key variables to help create the list of packages to | 1122 | tasks use these key variables to help create the list of packages to |
1121 | actually install. For information on the variables listed in the figure, | 1123 | actually install. For information on the variables listed in the figure, |
1122 | see the "`Application Development SDK <#sdk-dev-environment>`__" | 1124 | see the ":ref:`overview-manual/concepts:application development sdk`" |
1123 | section. | 1125 | section. |
1124 | 1126 | ||
1125 | The ``do_populate_sdk`` task helps create the standard SDK and handles | 1127 | The ``do_populate_sdk`` task helps create the standard SDK and handles |
@@ -1147,8 +1149,8 @@ For each task that completes successfully, BitBake writes a stamp file | |||
1147 | into the :term:`STAMPS_DIR` | 1149 | into the :term:`STAMPS_DIR` |
1148 | directory. The beginning of the stamp file's filename is determined by | 1150 | directory. The beginning of the stamp file's filename is determined by |
1149 | the :term:`STAMP` variable, and the end | 1151 | the :term:`STAMP` variable, and the end |
1150 | of the name consists of the task's name and current `input | 1152 | of the name consists of the task's name and current :ref:`input |
1151 | checksum <#overview-checksums>`__. | 1153 | checksum <overview-manual/concepts:checksums (signatures)>`. |
1152 | 1154 | ||
1153 | .. note:: | 1155 | .. note:: |
1154 | 1156 | ||
@@ -1165,10 +1167,10 @@ file does not exist, the task is rerun. | |||
1165 | .. note:: | 1167 | .. note:: |
1166 | 1168 | ||
1167 | The stamp mechanism is more general than the shared state (sstate) | 1169 | The stamp mechanism is more general than the shared state (sstate) |
1168 | cache mechanism described in the "`Setscene Tasks and Shared | 1170 | cache mechanism described in the |
1169 | State <#setscene-tasks-and-shared-state>`__" section. BitBake avoids | 1171 | ":ref:`overview-manual/concepts:setscene tasks and shared state`" section. |
1170 | rerunning any task that has a valid stamp file, not just tasks that | 1172 | BitBake avoids rerunning any task that has a valid stamp file, not just |
1171 | can be accelerated through the sstate cache. | 1173 | tasks that can be accelerated through the sstate cache. |
1172 | 1174 | ||
1173 | However, you should realize that stamp files only serve as a marker | 1175 | However, you should realize that stamp files only serve as a marker |
1174 | that some work has been done and that these files do not record task | 1176 | that some work has been done and that these files do not record task |
@@ -1271,7 +1273,8 @@ Images | |||
1271 | 1273 | ||
1272 | The images produced by the build system are compressed forms of the root | 1274 | The images produced by the build system are compressed forms of the root |
1273 | filesystem and are ready to boot on a target device. You can see from | 1275 | filesystem and are ready to boot on a target device. You can see from |
1274 | the `general workflow figure <#general-workflow-figure>`__ that BitBake | 1276 | the :ref:`general workflow figure |
1277 | <overview-manual/concepts:openembedded build system concepts>` that BitBake | ||
1275 | output, in part, consists of images. This section takes a closer look at | 1278 | output, in part, consists of images. This section takes a closer look at |
1276 | this output: | 1279 | this output: |
1277 | 1280 | ||
@@ -1327,7 +1330,8 @@ current configuration. | |||
1327 | Application Development SDK | 1330 | Application Development SDK |
1328 | --------------------------- | 1331 | --------------------------- |
1329 | 1332 | ||
1330 | In the `general workflow figure <#general-workflow-figure>`__, the | 1333 | In the :ref:`general workflow figure |
1334 | <overview-manual/concepts:openembedded build system concepts>`, the | ||
1331 | output labeled "Application Development SDK" represents an SDK. The SDK | 1335 | output labeled "Application Development SDK" represents an SDK. The SDK |
1332 | generation process differs depending on whether you build an extensible | 1336 | generation process differs depending on whether you build an extensible |
1333 | SDK (e.g. ``bitbake -c populate_sdk_ext`` imagename) or a standard SDK | 1337 | SDK (e.g. ``bitbake -c populate_sdk_ext`` imagename) or a standard SDK |
@@ -1357,8 +1361,8 @@ can initialize the environment before using the tools. | |||
1357 | your own SDK installer. | 1361 | your own SDK installer. |
1358 | 1362 | ||
1359 | - For background information on cross-development toolchains in the | 1363 | - For background information on cross-development toolchains in the |
1360 | Yocto Project development environment, see the "`Cross-Development | 1364 | Yocto Project development environment, see the |
1361 | Toolchain Generation <#cross-development-toolchain-generation>`__" | 1365 | ":ref:`overview-manual/concepts:cross-development toolchain generation`" |
1362 | section. | 1366 | section. |
1363 | 1367 | ||
1364 | - For information on setting up a cross-development environment, see | 1368 | - For information on setting up a cross-development environment, see |
@@ -1773,10 +1777,10 @@ through this setting in the ``bitbake.conf`` file: | |||
1773 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" | 1777 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" |
1774 | 1778 | ||
1775 | The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same | 1779 | The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same |
1776 | as the "OEBasic" version but adds the task hash to the `stamp | 1780 | as the "OEBasic" version but adds the task hash to the :ref:`stamp |
1777 | files <#stamp-files-and-the-rerunning-of-tasks>`__. This results in any | 1781 | files <overview-manual/concepts:stamp files and the rerunning of tasks>`. This |
1778 | metadata change that changes the task hash, automatically causing the | 1782 | results in any metadata change that changes the task hash, automatically causing |
1779 | task to be run again. This removes the need to bump | 1783 | the task to be run again. This removes the need to bump |
1780 | :term:`PR` values, and changes to metadata | 1784 | :term:`PR` values, and changes to metadata |
1781 | automatically ripple across the build. | 1785 | automatically ripple across the build. |
1782 | 1786 | ||
@@ -1901,9 +1905,10 @@ The following list explains the previous example: | |||
1901 | 1905 | ||
1902 | 1906 | ||
1903 | - The ``do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"`` line appends | 1907 | - The ``do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"`` line appends |
1904 | extra metadata to the `stamp | 1908 | extra metadata to the :ref:`stamp |
1905 | file <#stamp-files-and-the-rerunning-of-tasks>`__. In this case, the | 1909 | file <overview-manual/concepts:stamp files and the rerunning of tasks>`. In |
1906 | metadata makes the task specific to a machine's architecture. See | 1910 | this case, the metadata makes the task specific to a machine's architecture. |
1911 | See | ||
1907 | ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:the task list`" | 1912 | ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:the task list`" |
1908 | section in the BitBake User Manual for more information on the | 1913 | section in the BitBake User Manual for more information on the |
1909 | ``stamp-extra-info`` flag. | 1914 | ``stamp-extra-info`` flag. |