diff options
Diffstat (limited to 'poky/documentation/overview-manual/concepts.rst')
| -rw-r--r-- | poky/documentation/overview-manual/concepts.rst | 79 |
1 files changed, 38 insertions, 41 deletions
diff --git a/poky/documentation/overview-manual/concepts.rst b/poky/documentation/overview-manual/concepts.rst index e5bdcdad2..642ef15fe 100644 --- a/poky/documentation/overview-manual/concepts.rst +++ b/poky/documentation/overview-manual/concepts.rst @@ -332,7 +332,7 @@ created by an autobuilder: One useful scenario for using the ``conf/site.conf`` file is to extend your :term:`BBPATH` variable to include the path to a ``conf/site.conf``. Then, when BitBake looks - for Metadata using ``BBPATH``, it finds the ``conf/site.conf`` file + for Metadata using :term:`BBPATH`, it finds the ``conf/site.conf`` file and applies your common configurations found in the file. To override configurations in a particular build directory, alter the similar configurations within that build directory's ``conf/local.conf`` @@ -532,7 +532,7 @@ to build software. A combination of the two is also possible. BitBake uses the :term:`SRC_URI` variable to point to source files regardless of their location. Each -recipe must have a ``SRC_URI`` variable that points to the source. +recipe must have a :term:`SRC_URI` variable that points to the source. Another area that plays a significant role in where source files come from is pointed to by the @@ -540,13 +540,13 @@ from is pointed to by the a cache that can hold previously downloaded source. You can also instruct the OpenEmbedded build system to create tarballs from Git repositories, which is not the default behavior, and store them in the -``DL_DIR`` by using the +:term:`DL_DIR` by using the :term:`BB_GENERATE_MIRROR_TARBALLS` variable. -Judicious use of a ``DL_DIR`` directory can save the build system a trip +Judicious use of a :term:`DL_DIR` directory can save the build system a trip across the Internet when looking for files. A good method for using a -download directory is to have ``DL_DIR`` point to an area outside of +download directory is to have :term:`DL_DIR` point to an area outside of your Build Directory. Doing so allows you to safely delete the Build Directory if needed without fear of removing any downloaded source file. @@ -747,7 +747,7 @@ Build Directory's hierarchy: architecture of the built package or packages. Depending on the eventual destination of the package or packages (i.e. machine architecture, :term:`Build Host`, SDK, or - specific machine), ``PACKAGE_ARCH`` varies. See the variable's + specific machine), :term:`PACKAGE_ARCH` varies. See the variable's description for details. - :term:`TARGET_OS`: The operating @@ -756,7 +756,7 @@ Build Directory's hierarchy: - :term:`PN`: The name of the recipe used to build the package. This variable can have multiple meanings. - However, when used in the context of input files, ``PN`` represents + However, when used in the context of input files, :term:`PN` represents the name of the recipe. - :term:`WORKDIR`: The location @@ -773,7 +773,7 @@ Build Directory's hierarchy: files for a given recipe. - :term:`BPN`: The name of the recipe - used to build the package. The ``BPN`` variable is a version of + used to build the package. The :term:`BPN` variable is a version of the ``PN`` variable but with common prefixes and suffixes removed. - :term:`PV`: The version of the @@ -803,13 +803,13 @@ and the :term:`FILESPATH` variable to locate applicable patch files. Default processing for patch files assumes the files have either -``*.patch`` or ``*.diff`` file types. You can use ``SRC_URI`` parameters +``*.patch`` or ``*.diff`` file types. You can use :term:`SRC_URI` parameters to change the way the build system recognizes patch files. See the :ref:`ref-tasks-patch` task for more information. BitBake finds and applies multiple patches for a single recipe in the -order in which it locates the patches. The ``FILESPATH`` variable +order in which it locates the patches. The :term:`FILESPATH` variable defines the default set of directories that the build system uses to search for patch files. Once found, patches are applied to the recipe's source files, which are located in the @@ -877,12 +877,12 @@ This step in the build process consists of the following tasks: :ref:`ref-tasks-compile` task. Compilation occurs in the directory pointed to by the :term:`B` variable. Realize that the - ``B`` directory is, by default, the same as the + :term:`B` directory is, by default, the same as the :term:`S` directory. - *do_install*: After compilation completes, BitBake executes the :ref:`ref-tasks-install` task. - This task copies files from the ``B`` directory and places them in a + This task copies files from the :term:`B` directory and places them in a holding area pointed to by the :term:`D` variable. Packaging occurs later using files from this holding directory. @@ -928,7 +928,7 @@ the analysis and package splitting process use several areas: - :term:`PKGDATA_DIR`: A shared, global-state directory that holds packaging metadata generated during the packaging process. The packaging process copies metadata from - ``PKGDESTWORK`` to the ``PKGDATA_DIR`` area where it becomes globally + :term:`PKGDESTWORK` to the :term:`PKGDATA_DIR` area where it becomes globally available. - :term:`STAGING_DIR_HOST`: @@ -1008,7 +1008,7 @@ actually install: With :term:`IMAGE_ROOTFS` pointing to the location of the filesystem under construction and the -``PACKAGE_INSTALL`` variable providing the final list of packages to +:term:`PACKAGE_INSTALL` variable providing the final list of packages to install, the root file system is created. Package installation is under control of the package manager (e.g. @@ -1057,7 +1057,7 @@ based on the image types specified in the The process turns everything into an image file or a set of image files and can compress the root filesystem image to reduce the overall size of the image. The formats used for the root filesystem depend on the -``IMAGE_FSTYPES`` variable. Compression depends on whether the formats +:term:`IMAGE_FSTYPES` variable. Compression depends on whether the formats support compression. As an example, a dynamically created task when creating a particular @@ -1066,7 +1066,7 @@ image type would take the following form:: do_image_type So, if the type -as specified by the ``IMAGE_FSTYPES`` were ``ext4``, the dynamically +as specified by the :term:`IMAGE_FSTYPES` were ``ext4``, the dynamically generated task would be as follows:: do_image_ext4 @@ -1171,9 +1171,9 @@ the task is rerun. the sstate cache mechanism adds is a way to cache task output that can then be shared between build machines. -Since ``STAMPS_DIR`` is usually a subdirectory of ``TMPDIR``, removing -``TMPDIR`` will also remove ``STAMPS_DIR``, which means tasks will -properly be rerun to repopulate ``TMPDIR``. +Since :term:`STAMPS_DIR` is usually a subdirectory of :term:`TMPDIR`, removing +:term:`TMPDIR` will also remove :term:`STAMPS_DIR`, which means tasks will +properly be rerun to repopulate :term:`TMPDIR`. If you want some task to always be considered "out of date", you can mark it with the :ref:`nostamp <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>` @@ -1408,7 +1408,7 @@ This next list, shows the variables associated with a standard SDK: - :term:`TOOLCHAIN_HOST_TASK`: Lists packages that make up the host part of the SDK (i.e. the part - that runs on the ``SDKMACHINE``). When you use + that runs on the :term:`SDKMACHINE`). When you use ``bitbake -c populate_sdk imagename`` to create the SDK, a set of default packages apply. This variable allows you to add more packages. @@ -1462,12 +1462,9 @@ cross-compiler that is used internally within BitBake only. .. note:: - The extensible SDK does not use - gcc-cross-canadian + The extensible SDK does not use ``gcc-cross-canadian`` since this SDK ships a copy of the OpenEmbedded build system and the - sysroot within it contains - gcc-cross - . + sysroot within it contains ``gcc-cross``. The chain of events that occurs when the standard toolchain is bootstrapped:: @@ -1614,7 +1611,7 @@ them if they are deemed to be valid. :term:`PR` information as part of the shared state packages. Consequently, there are considerations that affect maintaining shared state feeds. For information on how the - build system works with packages and can track incrementing ``PR`` + build system works with packages and can track incrementing :term:`PR` information, see the ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" section in the Yocto Project Development Tasks Manual. @@ -1671,8 +1668,8 @@ objective of making native or cross packages relocatable. build host. However, cross packages generate output for the target architecture. -The checksum therefore needs to exclude ``WORKDIR``. The simplistic -approach for excluding the work directory is to set ``WORKDIR`` to some +The checksum therefore needs to exclude :term:`WORKDIR`. The simplistic +approach for excluding the work directory is to set :term:`WORKDIR` to some fixed value and create the checksum for the "run" script. Another problem results from the "run" scripts containing functions that @@ -1690,7 +1687,7 @@ contains code that first figures out the variable and function dependencies, and then creates a checksum for the data used as the input to the task. -Like the ``WORKDIR`` case, there can be situations where dependencies should be +Like the :term:`WORKDIR` case, there can be situations where dependencies should be ignored. For these situations, you can instruct the build process to ignore a dependency by using a line like the following:: @@ -1707,7 +1704,7 @@ following:: PACKAGE_ARCHS[vardeps] = "MACHINE" This example explicitly -adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``. +adds the :term:`MACHINE` variable as a dependency for :term:`PACKAGE_ARCHS`. As an example, consider a case with in-line Python where BitBake is not able to figure out dependencies. When running in debug mode (i.e. using @@ -1761,7 +1758,7 @@ through this setting in the ``bitbake.conf`` file:: BB_SIGNATURE_HANDLER ?= "OEBasicHash" -The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same +The "OEBasicHash" :term:`BB_SIGNATURE_HANDLER` is the same as the "OEBasic" version but adds the task hash to the :ref:`stamp files <overview-manual/concepts:stamp files and the rerunning of tasks>`. This results in any metadata change that changes the task hash, automatically causing @@ -1782,7 +1779,7 @@ the build. This information includes: - ``BBHASHDEPS_``\ filename\ ``:``\ taskname: The task dependencies for each task. -- ``BB_TASKHASH``: The hash of the currently running task. +- :term:`BB_TASKHASH`: The hash of the currently running task. Shared State ------------ @@ -1851,7 +1848,7 @@ The following list explains the previous example: ``do_deploy`` is in the shared state cache and its signature indicates that the cached output is still valid (i.e. if no relevant task inputs have changed), then the contents of the shared state cache copies - directly to ${``DEPLOY_DIR_IMAGE``} by the ``do_deploy_setscene`` task + directly to ${:term:`DEPLOY_DIR_IMAGE`} by the ``do_deploy_setscene`` task instead, skipping the ``do_deploy`` task. - The following task definition is glue logic needed to make the @@ -1897,8 +1894,8 @@ The following list explains the previous example: - ``sstate-inputdirs`` and ``sstate-outputdirs`` can also be used with multiple directories. For example, the following declares - ``PKGDESTWORK`` and ``SHLIBWORK`` as shared state input directories, - which populates the shared state cache, and ``PKGDATA_DIR`` and + :term:`PKGDESTWORK` and ``SHLIBWORK`` as shared state input directories, + which populates the shared state cache, and :term:`PKGDATA_DIR` and ``SHLIBSDIR`` as the corresponding shared state output directories:: do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" @@ -1925,7 +1922,7 @@ shared state files. Here is an example:: subdirectories, where the subdirectory names are based on the first two characters of the hash. If the shared state directory structure for a mirror has the same structure - as ``SSTATE_DIR``, you must specify "PATH" as part of the URI to enable the build + as :term:`SSTATE_DIR`, you must specify "PATH" as part of the URI to enable the build system to map to the appropriate subdirectory. The shared state package validity can be detected just by looking at the @@ -1976,7 +1973,7 @@ dependencies, you must manually declare the dependencies. Simultaneously, all executables and shared libraries installed by the recipe are inspected to see what shared libraries they link against. - For each shared library dependency that is found, ``PKGDATA_DIR`` is + For each shared library dependency that is found, :term:`PKGDATA_DIR` is queried to see if some package (likely from a different recipe) contains the shared library. If such a package is found, a runtime dependency is added from the package that depends on the shared @@ -1985,7 +1982,7 @@ dependencies, you must manually declare the dependencies. The automatically added runtime dependency also includes a version restriction. This version restriction specifies that at least the current version of the package that provides the shared library must - be used, as if "package (>= version)" had been added to ``RDEPENDS``. + be used, as if "package (>= version)" had been added to :term:`RDEPENDS`. This forces an upgrade of the package containing the shared library when installing the package that depends on the library, if needed. @@ -1999,14 +1996,14 @@ dependencies, you must manually declare the dependencies. pkg-config modules (``*.pc`` files) installed by the recipe are located. For each module, the package that contains the module is registered as providing the module. The resulting module-to-package - mapping is saved globally in ``PKGDATA_DIR`` by the + mapping is saved globally in :term:`PKGDATA_DIR` by the ``do_packagedata`` task. Simultaneously, all pkg-config modules installed by the recipe are inspected to see what other pkg-config modules they depend on. A module is seen as depending on another module if it contains a "Requires:" line that specifies the other module. For each module - dependency, ``PKGDATA_DIR`` is queried to see if some package + dependency, :term:`PKGDATA_DIR` is queried to see if some package contains the module. If such a package is found, a runtime dependency is added from the package that depends on the module to the package that contains the module. @@ -2046,7 +2043,7 @@ recipe in :term:`DEPENDS` through use of a ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` declaration, which guarantees that the required shared-library/module-to-package mapping information will be available -when needed as long as ``DEPENDS`` has been correctly set. +when needed as long as :term:`DEPENDS` has been correctly set. Fakeroot and Pseudo =================== |