diff options
Diffstat (limited to 'documentation/overview-manual/concepts.rst')
-rw-r--r-- | documentation/overview-manual/concepts.rst | 73 |
1 files changed, 34 insertions, 39 deletions
diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst index 2e3f1af442..e5bdcdad2a 100644 --- a/documentation/overview-manual/concepts.rst +++ b/documentation/overview-manual/concepts.rst | |||
@@ -139,7 +139,7 @@ hardware-specific configurations allows you to share other metadata by | |||
139 | using a different layer where that metadata might be common across | 139 | using a different layer where that metadata might be common across |
140 | several pieces of hardware. | 140 | several pieces of hardware. |
141 | 141 | ||
142 | Many layers exist that work in the Yocto Project development environment. The | 142 | There are many layers working in the Yocto Project development environment. The |
143 | :yocto_home:`Yocto Project Curated Layer Index </software-overview/layers/>` | 143 | :yocto_home:`Yocto Project Curated Layer Index </software-overview/layers/>` |
144 | and :oe_layerindex:`OpenEmbedded Layer Index <>` both contain layers from | 144 | and :oe_layerindex:`OpenEmbedded Layer Index <>` both contain layers from |
145 | which you can use or leverage. | 145 | which you can use or leverage. |
@@ -370,7 +370,7 @@ BitBake's global behavior. This section takes a closer look at the | |||
370 | layers the build system uses to further control the build. These layers | 370 | layers the build system uses to further control the build. These layers |
371 | provide Metadata for the software, machine, and policies. | 371 | provide Metadata for the software, machine, and policies. |
372 | 372 | ||
373 | In general, three types of layer input exists. You can see them below | 373 | In general, there are three types of layer input. You can see them below |
374 | the "User Configuration" box in the `general workflow | 374 | the "User Configuration" box in the `general workflow |
375 | figure <overview-manual/concepts:openembedded build system concepts>`: | 375 | figure <overview-manual/concepts:openembedded build system concepts>`: |
376 | 376 | ||
@@ -427,8 +427,8 @@ Repositories <>` also shows layers categorized under "Yocto Metadata Layers." | |||
427 | 427 | ||
428 | .. note:: | 428 | .. note:: |
429 | 429 | ||
430 | Layers exist in the Yocto Project Source Repositories that cannot be | 430 | There are layers in the Yocto Project Source Repositories that cannot be |
431 | found in the OpenEmbedded Layer Index. These layers are either | 431 | found in the OpenEmbedded Layer Index. Such layers are either |
432 | deprecated or experimental in nature. | 432 | deprecated or experimental in nature. |
433 | 433 | ||
434 | BitBake uses the ``conf/bblayers.conf`` file, which is part of the user | 434 | BitBake uses the ``conf/bblayers.conf`` file, which is part of the user |
@@ -489,7 +489,7 @@ the machine (``conf/machine/machine.conf``) and, of course, the layer | |||
489 | 489 | ||
490 | The remainder of the layer is dedicated to specific recipes by function: | 490 | The remainder of the layer is dedicated to specific recipes by function: |
491 | ``recipes-bsp``, ``recipes-core``, ``recipes-graphics``, | 491 | ``recipes-bsp``, ``recipes-core``, ``recipes-graphics``, |
492 | ``recipes-kernel``, and so forth. Metadata can exist for multiple | 492 | ``recipes-kernel``, and so forth. There can be metadata for multiple |
493 | formfactors, graphics support systems, and so forth. | 493 | formfactors, graphics support systems, and so forth. |
494 | 494 | ||
495 | .. note:: | 495 | .. note:: |
@@ -528,9 +528,7 @@ project that is more dynamic or experimental in nature, a project might | |||
528 | keep source files in a repository controlled by a Source Control Manager | 528 | keep source files in a repository controlled by a Source Control Manager |
529 | (SCM) such as Git. Pulling source from a repository allows you to | 529 | (SCM) such as Git. Pulling source from a repository allows you to |
530 | control the point in the repository (the revision) from which you want | 530 | control the point in the repository (the revision) from which you want |
531 | to build software. Finally, a combination of the two might exist, which | 531 | to build software. A combination of the two is also possible. |
532 | would give the consumer a choice when deciding where to get source | ||
533 | files. | ||
534 | 532 | ||
535 | BitBake uses the :term:`SRC_URI` | 533 | BitBake uses the :term:`SRC_URI` |
536 | variable to point to source files regardless of their location. Each | 534 | variable to point to source files regardless of their location. Each |
@@ -609,7 +607,7 @@ the specific revision from which to build. | |||
609 | Source Mirror(s) | 607 | Source Mirror(s) |
610 | ~~~~~~~~~~~~~~~~ | 608 | ~~~~~~~~~~~~~~~~ |
611 | 609 | ||
612 | Two kinds of mirrors exist: pre-mirrors and regular mirrors. The | 610 | There are two kinds of mirrors: pre-mirrors and regular mirrors. The |
613 | :term:`PREMIRRORS` and | 611 | :term:`PREMIRRORS` and |
614 | :term:`MIRRORS` variables point to | 612 | :term:`MIRRORS` variables point to |
615 | these, respectively. BitBake checks pre-mirrors before looking upstream | 613 | these, respectively. BitBake checks pre-mirrors before looking upstream |
@@ -667,8 +665,8 @@ package files are kept: | |||
667 | variables are used, respectively. | 665 | variables are used, respectively. |
668 | 666 | ||
669 | - :term:`PACKAGE_ARCH`: Defines | 667 | - :term:`PACKAGE_ARCH`: Defines |
670 | architecture-specific sub-folders. For example, packages could exist | 668 | architecture-specific sub-folders. For example, packages could be |
671 | for the i586 or qemux86 architectures. | 669 | available for the i586 or qemux86 architectures. |
672 | 670 | ||
673 | BitBake uses the | 671 | BitBake uses the |
674 | :ref:`do_package_write_* <ref-tasks-package_write_deb>` | 672 | :ref:`do_package_write_* <ref-tasks-package_write_deb>` |
@@ -681,8 +679,8 @@ and | |||
681 | ":ref:`ref-tasks-package_write_tar`" | 679 | ":ref:`ref-tasks-package_write_tar`" |
682 | sections in the Yocto Project Reference Manual for additional | 680 | sections in the Yocto Project Reference Manual for additional |
683 | information. As an example, consider a scenario where an IPK packaging | 681 | information. As an example, consider a scenario where an IPK packaging |
684 | manager is being used and package architecture support for both i586 and | 682 | manager is being used and there is package architecture support for both |
685 | qemux86 exist. Packages for the i586 architecture are placed in | 683 | i586 and qemux86. Packages for the i586 architecture are placed in |
686 | ``build/tmp/deploy/ipk/i586``, while packages for the qemux86 | 684 | ``build/tmp/deploy/ipk/i586``, while packages for the qemux86 |
687 | architecture are placed in ``build/tmp/deploy/ipk/qemux86``. | 685 | architecture are placed in ``build/tmp/deploy/ipk/qemux86``. |
688 | 686 | ||
@@ -698,7 +696,7 @@ closer look at each of those areas. | |||
698 | 696 | ||
699 | .. note:: | 697 | .. note:: |
700 | 698 | ||
701 | Separate documentation exists for the BitBake tool. See the | 699 | Documentation for the BitBake tool is available separately. See the |
702 | BitBake User Manual | 700 | BitBake User Manual |
703 | for reference material on BitBake. | 701 | for reference material on BitBake. |
704 | 702 | ||
@@ -783,12 +781,10 @@ Build Directory's hierarchy: | |||
783 | 781 | ||
784 | .. note:: | 782 | .. note:: |
785 | 783 | ||
786 | In the previous figure, notice that two sample hierarchies exist: one | 784 | In the previous figure, notice that there are two sample hierarchies: |
787 | based on package architecture (i.e. | 785 | one based on package architecture (i.e. :term:`PACKAGE_ARCH`) |
788 | PACKAGE_ARCH | 786 | and one based on a machine (i.e. :term:`MACHINE`). |
789 | ) and one based on a machine (i.e. | 787 | The underlying structures are identical. The differentiator being |
790 | MACHINE | ||
791 | ). The underlying structures are identical. The differentiator being | ||
792 | what the OpenEmbedded build system is using as a build target (e.g. | 788 | what the OpenEmbedded build system is using as a build target (e.g. |
793 | general architecture, a build host, an SDK, or a specific machine). | 789 | general architecture, a build host, an SDK, or a specific machine). |
794 | 790 | ||
@@ -963,8 +959,7 @@ that part of the build process. | |||
963 | 959 | ||
964 | .. note:: | 960 | .. note:: |
965 | 961 | ||
966 | Support for creating feeds directly from the | 962 | Support for creating feeds directly from the ``deploy/*`` |
967 | deploy/\* | ||
968 | directories does not exist. Creating such feeds usually requires some | 963 | directories does not exist. Creating such feeds usually requires some |
969 | kind of feed maintenance mechanism that would upload the new packages | 964 | kind of feed maintenance mechanism that would upload the new packages |
970 | into an official package feed (e.g. the Ångström distribution). This | 965 | into an official package feed (e.g. the Ångström distribution). This |
@@ -1156,9 +1151,9 @@ checksum <overview-manual/concepts:checksums (signatures)>`. | |||
1156 | OpenEmbedded. | 1151 | OpenEmbedded. |
1157 | 1152 | ||
1158 | To determine if a task needs to be rerun, BitBake checks if a stamp file | 1153 | To determine if a task needs to be rerun, BitBake checks if a stamp file |
1159 | with a matching input checksum exists for the task. If such a stamp file | 1154 | with a matching input checksum exists for the task. In this case, |
1160 | exists, the task's output is assumed to exist and still be valid. If the | 1155 | the task's output is assumed to exist and still be valid. Otherwise, |
1161 | file does not exist, the task is rerun. | 1156 | the task is rerun. |
1162 | 1157 | ||
1163 | .. note:: | 1158 | .. note:: |
1164 | 1159 | ||
@@ -1234,14 +1229,14 @@ to run any of the ``do_fetch``, ``do_unpack``, ``do_patch``, | |||
1234 | 1229 | ||
1235 | It becomes more complicated if everything can come from an sstate cache | 1230 | It becomes more complicated if everything can come from an sstate cache |
1236 | because some objects are simply not required at all. For example, you do | 1231 | because some objects are simply not required at all. For example, you do |
1237 | not need a compiler or native tools, such as quilt, if nothing exists to | 1232 | not need a compiler or native tools, such as quilt, if there isn't anything |
1238 | compile or patch. If the ``do_package_write_*`` packages are available | 1233 | to compile or patch. If the ``do_package_write_*`` packages are available |
1239 | from sstate, BitBake does not need the ``do_package`` task data. | 1234 | from sstate, BitBake does not need the ``do_package`` task data. |
1240 | 1235 | ||
1241 | To handle all these complexities, BitBake runs in two phases. The first | 1236 | To handle all these complexities, BitBake runs in two phases. The first |
1242 | is the "setscene" stage. During this stage, BitBake first checks the | 1237 | is the "setscene" stage. During this stage, BitBake first checks the |
1243 | sstate cache for any targets it is planning to build. BitBake does a | 1238 | sstate cache for any targets it is planning to build. BitBake does a |
1244 | fast check to see if the object exists rather than a complete download. | 1239 | fast check to see if the object exists rather than doing a complete download. |
1245 | If nothing exists, the second phase, which is the setscene stage, | 1240 | If nothing exists, the second phase, which is the setscene stage, |
1246 | completes and the main build proceeds. | 1241 | completes and the main build proceeds. |
1247 | 1242 | ||
@@ -1366,9 +1361,9 @@ can initialize the environment before using the tools. | |||
1366 | 1361 | ||
1367 | All the output files for an SDK are written to the ``deploy/sdk`` folder | 1362 | All the output files for an SDK are written to the ``deploy/sdk`` folder |
1368 | inside the :term:`Build Directory` as | 1363 | inside the :term:`Build Directory` as |
1369 | shown in the previous figure. Depending on the type of SDK, several | 1364 | shown in the previous figure. Depending on the type of SDK, there are |
1370 | variables exist that help configure these files. The following list | 1365 | several variables to configure these files. Here are the variables |
1371 | shows the variables associated with an extensible SDK: | 1366 | associated with an extensible SDK: |
1372 | 1367 | ||
1373 | - :term:`DEPLOY_DIR`: Points to | 1368 | - :term:`DEPLOY_DIR`: Points to |
1374 | the ``deploy`` directory. | 1369 | the ``deploy`` directory. |
@@ -1577,8 +1572,8 @@ Shared State Cache | |||
1577 | By design, the OpenEmbedded build system builds everything from scratch | 1572 | By design, the OpenEmbedded build system builds everything from scratch |
1578 | unless :term:`BitBake` can determine | 1573 | unless :term:`BitBake` can determine |
1579 | that parts do not need to be rebuilt. Fundamentally, building from | 1574 | that parts do not need to be rebuilt. Fundamentally, building from |
1580 | scratch is attractive as it means all parts are built fresh and no | 1575 | scratch is attractive as it means all parts are built fresh and there is |
1581 | possibility of stale data exists that can cause problems. When | 1576 | no possibility of stale data that can cause problems. When |
1582 | developers hit problems, they typically default back to building from | 1577 | developers hit problems, they typically default back to building from |
1583 | scratch so they have a know state from the start. | 1578 | scratch so they have a know state from the start. |
1584 | 1579 | ||
@@ -1617,7 +1612,7 @@ them if they are deemed to be valid. | |||
1617 | 1612 | ||
1618 | - The build system does not maintain | 1613 | - The build system does not maintain |
1619 | :term:`PR` information as part of | 1614 | :term:`PR` information as part of |
1620 | the shared state packages. Consequently, considerations exist that | 1615 | the shared state packages. Consequently, there are considerations that |
1621 | affect maintaining shared state feeds. For information on how the | 1616 | affect maintaining shared state feeds. For information on how the |
1622 | build system works with packages and can track incrementing ``PR`` | 1617 | build system works with packages and can track incrementing ``PR`` |
1623 | information, see the ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" | 1618 | information, see the ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" |
@@ -1687,7 +1682,7 @@ used to prune the "run" scripts down to the minimum set, thereby | |||
1687 | alleviating this problem and making the "run" scripts much more readable | 1682 | alleviating this problem and making the "run" scripts much more readable |
1688 | as a bonus. | 1683 | as a bonus. |
1689 | 1684 | ||
1690 | So far, solutions for shell scripts exist. What about Python tasks? The | 1685 | So far, there are solutions for shell scripts. What about Python tasks? The |
1691 | same approach applies even though these tasks are more difficult. The | 1686 | same approach applies even though these tasks are more difficult. The |
1692 | process needs to figure out what variables a Python function accesses | 1687 | process needs to figure out what variables a Python function accesses |
1693 | and what functions it calls. Again, the incremental build solution | 1688 | and what functions it calls. Again, the incremental build solution |
@@ -1695,7 +1690,7 @@ contains code that first figures out the variable and function | |||
1695 | dependencies, and then creates a checksum for the data used as the input | 1690 | dependencies, and then creates a checksum for the data used as the input |
1696 | to the task. | 1691 | to the task. |
1697 | 1692 | ||
1698 | Like the ``WORKDIR`` case, situations exist where dependencies should be | 1693 | Like the ``WORKDIR`` case, there can be situations where dependencies should be |
1699 | ignored. For these situations, you can instruct the build process to | 1694 | ignored. For these situations, you can instruct the build process to |
1700 | ignore a dependency by using a line like the following:: | 1695 | ignore a dependency by using a line like the following:: |
1701 | 1696 | ||
@@ -1732,7 +1727,7 @@ to add is a policy decision. However, the effect is to generate a master | |||
1732 | checksum that combines the basehash and the hashes of the task's | 1727 | checksum that combines the basehash and the hashes of the task's |
1733 | dependencies. | 1728 | dependencies. |
1734 | 1729 | ||
1735 | At the code level, a variety of ways exist by which both the basehash | 1730 | At the code level, there are multiple ways by which both the basehash |
1736 | and the dependent task hashes can be influenced. Within the BitBake | 1731 | and the dependent task hashes can be influenced. Within the BitBake |
1737 | configuration file, you can give BitBake some extra information to help | 1732 | configuration file, you can give BitBake some extra information to help |
1738 | it construct the basehash. The following statement effectively results | 1733 | it construct the basehash. The following statement effectively results |
@@ -1961,8 +1956,8 @@ Automatically Added Runtime Dependencies | |||
1961 | The OpenEmbedded build system automatically adds common types of runtime | 1956 | The OpenEmbedded build system automatically adds common types of runtime |
1962 | dependencies between packages, which means that you do not need to | 1957 | dependencies between packages, which means that you do not need to |
1963 | explicitly declare the packages using | 1958 | explicitly declare the packages using |
1964 | :term:`RDEPENDS`. Three automatic | 1959 | :term:`RDEPENDS`. There are three automatic |
1965 | mechanisms exist (``shlibdeps``, ``pcdeps``, and ``depchains``) that | 1960 | mechanisms (``shlibdeps``, ``pcdeps``, and ``depchains``) that |
1966 | handle shared libraries, package configuration (pkg-config) modules, and | 1961 | handle shared libraries, package configuration (pkg-config) modules, and |
1967 | ``-dev`` and ``-dbg`` packages, respectively. For other types of runtime | 1962 | ``-dev`` and ``-dbg`` packages, respectively. For other types of runtime |
1968 | dependencies, you must manually declare the dependencies. | 1963 | dependencies, you must manually declare the dependencies. |