summaryrefslogtreecommitdiffstats
path: root/documentation/overview-manual/concepts.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/overview-manual/concepts.rst')
-rw-r--r--documentation/overview-manual/concepts.rst72
1 files changed, 36 insertions, 36 deletions
diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
index e5bdcdad2a..ab882ff778 100644
--- a/documentation/overview-manual/concepts.rst
+++ b/documentation/overview-manual/concepts.rst
@@ -332,7 +332,7 @@ created by an autobuilder:
332 One useful scenario for using the ``conf/site.conf`` file is to 332 One useful scenario for using the ``conf/site.conf`` file is to
333 extend your :term:`BBPATH` variable 333 extend your :term:`BBPATH` variable
334 to include the path to a ``conf/site.conf``. Then, when BitBake looks 334 to include the path to a ``conf/site.conf``. Then, when BitBake looks
335 for Metadata using ``BBPATH``, it finds the ``conf/site.conf`` file 335 for Metadata using :term:`BBPATH`, it finds the ``conf/site.conf`` file
336 and applies your common configurations found in the file. To override 336 and applies your common configurations found in the file. To override
337 configurations in a particular build directory, alter the similar 337 configurations in a particular build directory, alter the similar
338 configurations within that build directory's ``conf/local.conf`` 338 configurations within that build directory's ``conf/local.conf``
@@ -532,7 +532,7 @@ to build software. A combination of the two is also possible.
532 532
533BitBake uses the :term:`SRC_URI` 533BitBake uses the :term:`SRC_URI`
534variable to point to source files regardless of their location. Each 534variable to point to source files regardless of their location. Each
535recipe must have a ``SRC_URI`` variable that points to the source. 535recipe must have a :term:`SRC_URI` variable that points to the source.
536 536
537Another area that plays a significant role in where source files come 537Another area that plays a significant role in where source files come
538from is pointed to by the 538from is pointed to by the
@@ -540,13 +540,13 @@ from is pointed to by the
540a cache that can hold previously downloaded source. You can also 540a cache that can hold previously downloaded source. You can also
541instruct the OpenEmbedded build system to create tarballs from Git 541instruct the OpenEmbedded build system to create tarballs from Git
542repositories, which is not the default behavior, and store them in the 542repositories, which is not the default behavior, and store them in the
543``DL_DIR`` by using the 543:term:`DL_DIR` by using the
544:term:`BB_GENERATE_MIRROR_TARBALLS` 544:term:`BB_GENERATE_MIRROR_TARBALLS`
545variable. 545variable.
546 546
547Judicious use of a ``DL_DIR`` directory can save the build system a trip 547Judicious use of a :term:`DL_DIR` directory can save the build system a trip
548across the Internet when looking for files. A good method for using a 548across the Internet when looking for files. A good method for using a
549download directory is to have ``DL_DIR`` point to an area outside of 549download directory is to have :term:`DL_DIR` point to an area outside of
550your Build Directory. Doing so allows you to safely delete the Build 550your Build Directory. Doing so allows you to safely delete the Build
551Directory if needed without fear of removing any downloaded source file. 551Directory if needed without fear of removing any downloaded source file.
552 552
@@ -747,7 +747,7 @@ Build Directory's hierarchy:
747 architecture of the built package or packages. Depending on the 747 architecture of the built package or packages. Depending on the
748 eventual destination of the package or packages (i.e. machine 748 eventual destination of the package or packages (i.e. machine
749 architecture, :term:`Build Host`, SDK, or 749 architecture, :term:`Build Host`, SDK, or
750 specific machine), ``PACKAGE_ARCH`` varies. See the variable's 750 specific machine), :term:`PACKAGE_ARCH` varies. See the variable's
751 description for details. 751 description for details.
752 752
753- :term:`TARGET_OS`: The operating 753- :term:`TARGET_OS`: The operating
@@ -756,7 +756,7 @@ Build Directory's hierarchy:
756 756
757- :term:`PN`: The name of the recipe used 757- :term:`PN`: The name of the recipe used
758 to build the package. This variable can have multiple meanings. 758 to build the package. This variable can have multiple meanings.
759 However, when used in the context of input files, ``PN`` represents 759 However, when used in the context of input files, :term:`PN` represents
760 the name of the recipe. 760 the name of the recipe.
761 761
762- :term:`WORKDIR`: The location 762- :term:`WORKDIR`: The location
@@ -773,7 +773,7 @@ Build Directory's hierarchy:
773 files for a given recipe. 773 files for a given recipe.
774 774
775 - :term:`BPN`: The name of the recipe 775 - :term:`BPN`: The name of the recipe
776 used to build the package. The ``BPN`` variable is a version of 776 used to build the package. The :term:`BPN` variable is a version of
777 the ``PN`` variable but with common prefixes and suffixes removed. 777 the ``PN`` variable but with common prefixes and suffixes removed.
778 778
779 - :term:`PV`: The version of the 779 - :term:`PV`: The version of the
@@ -803,13 +803,13 @@ and the :term:`FILESPATH` variable
803to locate applicable patch files. 803to locate applicable patch files.
804 804
805Default processing for patch files assumes the files have either 805Default processing for patch files assumes the files have either
806``*.patch`` or ``*.diff`` file types. You can use ``SRC_URI`` parameters 806``*.patch`` or ``*.diff`` file types. You can use :term:`SRC_URI` parameters
807to change the way the build system recognizes patch files. See the 807to change the way the build system recognizes patch files. See the
808:ref:`ref-tasks-patch` task for more 808:ref:`ref-tasks-patch` task for more
809information. 809information.
810 810
811BitBake finds and applies multiple patches for a single recipe in the 811BitBake finds and applies multiple patches for a single recipe in the
812order in which it locates the patches. The ``FILESPATH`` variable 812order in which it locates the patches. The :term:`FILESPATH` variable
813defines the default set of directories that the build system uses to 813defines the default set of directories that the build system uses to
814search for patch files. Once found, patches are applied to the recipe's 814search for patch files. Once found, patches are applied to the recipe's
815source files, which are located in the 815source files, which are located in the
@@ -877,12 +877,12 @@ This step in the build process consists of the following tasks:
877 :ref:`ref-tasks-compile` task. 877 :ref:`ref-tasks-compile` task.
878 Compilation occurs in the directory pointed to by the 878 Compilation occurs in the directory pointed to by the
879 :term:`B` variable. Realize that the 879 :term:`B` variable. Realize that the
880 ``B`` directory is, by default, the same as the 880 :term:`B` directory is, by default, the same as the
881 :term:`S` directory. 881 :term:`S` directory.
882 882
883- *do_install*: After compilation completes, BitBake executes the 883- *do_install*: After compilation completes, BitBake executes the
884 :ref:`ref-tasks-install` task. 884 :ref:`ref-tasks-install` task.
885 This task copies files from the ``B`` directory and places them in a 885 This task copies files from the :term:`B` directory and places them in a
886 holding area pointed to by the :term:`D` 886 holding area pointed to by the :term:`D`
887 variable. Packaging occurs later using files from this holding 887 variable. Packaging occurs later using files from this holding
888 directory. 888 directory.
@@ -928,7 +928,7 @@ the analysis and package splitting process use several areas:
928- :term:`PKGDATA_DIR`: A shared, 928- :term:`PKGDATA_DIR`: A shared,
929 global-state directory that holds packaging metadata generated during 929 global-state directory that holds packaging metadata generated during
930 the packaging process. The packaging process copies metadata from 930 the packaging process. The packaging process copies metadata from
931 ``PKGDESTWORK`` to the ``PKGDATA_DIR`` area where it becomes globally 931 :term:`PKGDESTWORK` to the :term:`PKGDATA_DIR` area where it becomes globally
932 available. 932 available.
933 933
934- :term:`STAGING_DIR_HOST`: 934- :term:`STAGING_DIR_HOST`:
@@ -1008,7 +1008,7 @@ actually install:
1008 1008
1009With :term:`IMAGE_ROOTFS` 1009With :term:`IMAGE_ROOTFS`
1010pointing to the location of the filesystem under construction and the 1010pointing to the location of the filesystem under construction and the
1011``PACKAGE_INSTALL`` variable providing the final list of packages to 1011:term:`PACKAGE_INSTALL` variable providing the final list of packages to
1012install, the root file system is created. 1012install, the root file system is created.
1013 1013
1014Package installation is under control of the package manager (e.g. 1014Package installation is under control of the package manager (e.g.
@@ -1057,7 +1057,7 @@ based on the image types specified in the
1057The process turns everything into an image file or a set of image files 1057The process turns everything into an image file or a set of image files
1058and can compress the root filesystem image to reduce the overall size of 1058and can compress the root filesystem image to reduce the overall size of
1059the image. The formats used for the root filesystem depend on the 1059the image. The formats used for the root filesystem depend on the
1060``IMAGE_FSTYPES`` variable. Compression depends on whether the formats 1060:term:`IMAGE_FSTYPES` variable. Compression depends on whether the formats
1061support compression. 1061support compression.
1062 1062
1063As an example, a dynamically created task when creating a particular 1063As an example, a dynamically created task when creating a particular
@@ -1066,7 +1066,7 @@ image type would take the following form::
1066 do_image_type 1066 do_image_type
1067 1067
1068So, if the type 1068So, if the type
1069as specified by the ``IMAGE_FSTYPES`` were ``ext4``, the dynamically 1069as specified by the :term:`IMAGE_FSTYPES` were ``ext4``, the dynamically
1070generated task would be as follows:: 1070generated task would be as follows::
1071 1071
1072 do_image_ext4 1072 do_image_ext4
@@ -1171,9 +1171,9 @@ the task is rerun.
1171 the sstate cache mechanism adds is a way to cache task output that 1171 the sstate cache mechanism adds is a way to cache task output that
1172 can then be shared between build machines. 1172 can then be shared between build machines.
1173 1173
1174Since ``STAMPS_DIR`` is usually a subdirectory of ``TMPDIR``, removing 1174Since :term:`STAMPS_DIR` is usually a subdirectory of :term:`TMPDIR`, removing
1175``TMPDIR`` will also remove ``STAMPS_DIR``, which means tasks will 1175:term:`TMPDIR` will also remove :term:`STAMPS_DIR`, which means tasks will
1176properly be rerun to repopulate ``TMPDIR``. 1176properly be rerun to repopulate :term:`TMPDIR`.
1177 1177
1178If you want some task to always be considered "out of date", you can 1178If you want some task to always be considered "out of date", you can
1179mark it with the :ref:`nostamp <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>` 1179mark 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:
1408 1408
1409- :term:`TOOLCHAIN_HOST_TASK`: 1409- :term:`TOOLCHAIN_HOST_TASK`:
1410 Lists packages that make up the host part of the SDK (i.e. the part 1410 Lists packages that make up the host part of the SDK (i.e. the part
1411 that runs on the ``SDKMACHINE``). When you use 1411 that runs on the :term:`SDKMACHINE`). When you use
1412 ``bitbake -c populate_sdk imagename`` to create the SDK, a set of 1412 ``bitbake -c populate_sdk imagename`` to create the SDK, a set of
1413 default packages apply. This variable allows you to add more 1413 default packages apply. This variable allows you to add more
1414 packages. 1414 packages.
@@ -1614,7 +1614,7 @@ them if they are deemed to be valid.
1614 :term:`PR` information as part of 1614 :term:`PR` information as part of
1615 the shared state packages. Consequently, there are considerations that 1615 the shared state packages. Consequently, there are considerations that
1616 affect maintaining shared state feeds. For information on how the 1616 affect maintaining shared state feeds. For information on how the
1617 build system works with packages and can track incrementing ``PR`` 1617 build system works with packages and can track incrementing :term:`PR`
1618 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`"
1619 section in the Yocto Project Development Tasks Manual. 1619 section in the Yocto Project Development Tasks Manual.
1620 1620
@@ -1671,8 +1671,8 @@ objective of making native or cross packages relocatable.
1671 build host. However, cross packages generate output for the target 1671 build host. However, cross packages generate output for the target
1672 architecture. 1672 architecture.
1673 1673
1674The checksum therefore needs to exclude ``WORKDIR``. The simplistic 1674The checksum therefore needs to exclude :term:`WORKDIR`. The simplistic
1675approach for excluding the work directory is to set ``WORKDIR`` to some 1675approach for excluding the work directory is to set :term:`WORKDIR` to some
1676fixed value and create the checksum for the "run" script. 1676fixed value and create the checksum for the "run" script.
1677 1677
1678Another problem results from the "run" scripts containing functions that 1678Another problem results from the "run" scripts containing functions that
@@ -1690,7 +1690,7 @@ contains code that first figures out the variable and function
1690dependencies, and then creates a checksum for the data used as the input 1690dependencies, and then creates a checksum for the data used as the input
1691to the task. 1691to the task.
1692 1692
1693Like the ``WORKDIR`` case, there can be situations where dependencies should be 1693Like the :term:`WORKDIR` case, there can be situations where dependencies should be
1694ignored. For these situations, you can instruct the build process to 1694ignored. For these situations, you can instruct the build process to
1695ignore a dependency by using a line like the following:: 1695ignore a dependency by using a line like the following::
1696 1696
@@ -1707,7 +1707,7 @@ following::
1707 PACKAGE_ARCHS[vardeps] = "MACHINE" 1707 PACKAGE_ARCHS[vardeps] = "MACHINE"
1708 1708
1709This example explicitly 1709This example explicitly
1710adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``. 1710adds the :term:`MACHINE` variable as a dependency for :term:`PACKAGE_ARCHS`.
1711 1711
1712As an example, consider a case with in-line Python where BitBake is not 1712As an example, consider a case with in-line Python where BitBake is not
1713able to figure out dependencies. When running in debug mode (i.e. using 1713able to figure out dependencies. When running in debug mode (i.e. using
@@ -1761,7 +1761,7 @@ through this setting in the ``bitbake.conf`` file::
1761 1761
1762 BB_SIGNATURE_HANDLER ?= "OEBasicHash" 1762 BB_SIGNATURE_HANDLER ?= "OEBasicHash"
1763 1763
1764The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same 1764The "OEBasicHash" :term:`BB_SIGNATURE_HANDLER` is the same
1765as the "OEBasic" version but adds the task hash to the :ref:`stamp 1765as the "OEBasic" version but adds the task hash to the :ref:`stamp
1766files <overview-manual/concepts:stamp files and the rerunning of tasks>`. This 1766files <overview-manual/concepts:stamp files and the rerunning of tasks>`. This
1767results in any metadata change that changes the task hash, automatically causing 1767results in any metadata change that changes the task hash, automatically causing
@@ -1782,7 +1782,7 @@ the build. This information includes:
1782- ``BBHASHDEPS_``\ filename\ ``:``\ taskname: The task dependencies for 1782- ``BBHASHDEPS_``\ filename\ ``:``\ taskname: The task dependencies for
1783 each task. 1783 each task.
1784 1784
1785- ``BB_TASKHASH``: The hash of the currently running task. 1785- :term:`BB_TASKHASH`: The hash of the currently running task.
1786 1786
1787Shared State 1787Shared State
1788------------ 1788------------
@@ -1851,7 +1851,7 @@ The following list explains the previous example:
1851 ``do_deploy`` is in the shared state cache and its signature indicates 1851 ``do_deploy`` is in the shared state cache and its signature indicates
1852 that the cached output is still valid (i.e. if no relevant task inputs 1852 that the cached output is still valid (i.e. if no relevant task inputs
1853 have changed), then the contents of the shared state cache copies 1853 have changed), then the contents of the shared state cache copies
1854 directly to ${``DEPLOY_DIR_IMAGE``} by the ``do_deploy_setscene`` task 1854 directly to ${:term:`DEPLOY_DIR_IMAGE`} by the ``do_deploy_setscene`` task
1855 instead, skipping the ``do_deploy`` task. 1855 instead, skipping the ``do_deploy`` task.
1856 1856
1857- The following task definition is glue logic needed to make the 1857- The following task definition is glue logic needed to make the
@@ -1897,8 +1897,8 @@ The following list explains the previous example:
1897 1897
1898- ``sstate-inputdirs`` and ``sstate-outputdirs`` can also be used with 1898- ``sstate-inputdirs`` and ``sstate-outputdirs`` can also be used with
1899 multiple directories. For example, the following declares 1899 multiple directories. For example, the following declares
1900 ``PKGDESTWORK`` and ``SHLIBWORK`` as shared state input directories, 1900 :term:`PKGDESTWORK` and ``SHLIBWORK`` as shared state input directories,
1901 which populates the shared state cache, and ``PKGDATA_DIR`` and 1901 which populates the shared state cache, and :term:`PKGDATA_DIR` and
1902 ``SHLIBSDIR`` as the corresponding shared state output directories:: 1902 ``SHLIBSDIR`` as the corresponding shared state output directories::
1903 1903
1904 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" 1904 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
@@ -1925,7 +1925,7 @@ shared state files. Here is an example::
1925 subdirectories, where the subdirectory names are based on the first two 1925 subdirectories, where the subdirectory names are based on the first two
1926 characters of the hash. 1926 characters of the hash.
1927 If the shared state directory structure for a mirror has the same structure 1927 If the shared state directory structure for a mirror has the same structure
1928 as ``SSTATE_DIR``, you must specify "PATH" as part of the URI to enable the build 1928 as :term:`SSTATE_DIR`, you must specify "PATH" as part of the URI to enable the build
1929 system to map to the appropriate subdirectory. 1929 system to map to the appropriate subdirectory.
1930 1930
1931The shared state package validity can be detected just by looking at the 1931The shared state package validity can be detected just by looking at the
@@ -1976,7 +1976,7 @@ dependencies, you must manually declare the dependencies.
1976 1976
1977 Simultaneously, all executables and shared libraries installed by the 1977 Simultaneously, all executables and shared libraries installed by the
1978 recipe are inspected to see what shared libraries they link against. 1978 recipe are inspected to see what shared libraries they link against.
1979 For each shared library dependency that is found, ``PKGDATA_DIR`` is 1979 For each shared library dependency that is found, :term:`PKGDATA_DIR` is
1980 queried to see if some package (likely from a different recipe) 1980 queried to see if some package (likely from a different recipe)
1981 contains the shared library. If such a package is found, a runtime 1981 contains the shared library. If such a package is found, a runtime
1982 dependency is added from the package that depends on the shared 1982 dependency is added from the package that depends on the shared
@@ -1985,7 +1985,7 @@ dependencies, you must manually declare the dependencies.
1985 The automatically added runtime dependency also includes a version 1985 The automatically added runtime dependency also includes a version
1986 restriction. This version restriction specifies that at least the 1986 restriction. This version restriction specifies that at least the
1987 current version of the package that provides the shared library must 1987 current version of the package that provides the shared library must
1988 be used, as if "package (>= version)" had been added to ``RDEPENDS``. 1988 be used, as if "package (>= version)" had been added to :term:`RDEPENDS`.
1989 This forces an upgrade of the package containing the shared library 1989 This forces an upgrade of the package containing the shared library
1990 when installing the package that depends on the library, if needed. 1990 when installing the package that depends on the library, if needed.
1991 1991
@@ -1999,14 +1999,14 @@ dependencies, you must manually declare the dependencies.
1999 pkg-config modules (``*.pc`` files) installed by the recipe are 1999 pkg-config modules (``*.pc`` files) installed by the recipe are
2000 located. For each module, the package that contains the module is 2000 located. For each module, the package that contains the module is
2001 registered as providing the module. The resulting module-to-package 2001 registered as providing the module. The resulting module-to-package
2002 mapping is saved globally in ``PKGDATA_DIR`` by the 2002 mapping is saved globally in :term:`PKGDATA_DIR` by the
2003 ``do_packagedata`` task. 2003 ``do_packagedata`` task.
2004 2004
2005 Simultaneously, all pkg-config modules installed by the recipe are 2005 Simultaneously, all pkg-config modules installed by the recipe are
2006 inspected to see what other pkg-config modules they depend on. A 2006 inspected to see what other pkg-config modules they depend on. A
2007 module is seen as depending on another module if it contains a 2007 module is seen as depending on another module if it contains a
2008 "Requires:" line that specifies the other module. For each module 2008 "Requires:" line that specifies the other module. For each module
2009 dependency, ``PKGDATA_DIR`` is queried to see if some package 2009 dependency, :term:`PKGDATA_DIR` is queried to see if some package
2010 contains the module. If such a package is found, a runtime dependency 2010 contains the module. If such a package is found, a runtime dependency
2011 is added from the package that depends on the module to the package 2011 is added from the package that depends on the module to the package
2012 that contains the module. 2012 that contains the module.
@@ -2046,7 +2046,7 @@ recipe in :term:`DEPENDS` through use
2046of a ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` 2046of a ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]``
2047declaration, which guarantees that the required 2047declaration, which guarantees that the required
2048shared-library/module-to-package mapping information will be available 2048shared-library/module-to-package mapping information will be available
2049when needed as long as ``DEPENDS`` has been correctly set. 2049when needed as long as :term:`DEPENDS` has been correctly set.
2050 2050
2051Fakeroot and Pseudo 2051Fakeroot and Pseudo
2052=================== 2052===================