From c473fa229239752367c5d573160fc8738cf1907e Mon Sep 17 00:00:00 2001 From: Nicolas Dechesne Date: Fri, 24 Jul 2020 16:27:54 +0200 Subject: sphinx: fix internal links Many of the internal links were not converted probably from DocBook using pandoc. After looking at the various patterns, the follow series of 'naive' Python regexp were used to perform some additional automatic conversion. Also, since we rely on built-in glossary, all links to terms need to use the sphinx :term: syntax. This commit is generated using the following Python series of regexp: line = re.sub("`+(\w+)`* <(\&YOCTO_DOCS_REF_URL;)?#var-\\1>`__", ":term:`\\1`", line) line = re.sub("`+do_([a-z_]+)`* <(\&YOCTO_DOCS_REF_URL;)?#ref-tasks-\\1>`__", ":ref:`ref-tasks-\\1`", line) line = re.sub("`+([a-z_\-\*\.]+).bbclass`* <(\&YOCTO_DOCS_REF_URL;)?#ref-classes-\\1>`__", ":ref:`\\1.bbclass `", line) line = re.sub("`+([a-z_\-\*\.]+)`* <(\&YOCTO_DOCS_REF_URL;)?#ref-classes-\\1>`__", ":ref:`\\1 `", line) line = re.sub("`Source Directory <(\&YOCTO_DOCS_REF_URL;)?#source-directory>`__", ":term:`Source Directory`", line) line = re.sub("`Build Directory <(\&YOCTO_DOCS_REF_URL;)?#build-directory>`__", ":term:`Build Directory`", line) line = re.sub("`Metadata <(\&YOCTO_DOCS_REF_URL;)?#metadata>`__", ":term:`Metadata`", line) line = re.sub("`BitBake <(\&YOCTO_DOCS_REF_URL;)?#bitbake-term>`__", ":term:`BitBake`", line) line = re.sub("`Images <(\&YOCTO_DOCS_REF_URL;)?#ref-images>`__", ":ref:`ref-manual/ref-images:Images`", line) line = re.sub("`Classes <(\&YOCTO_DOCS_REF_URL;)?#ref-classes>`__", ":ref:`ref-manual/ref-classes:Classes`", line) line = re.sub("`workspace <(\&YOCTO_DOCS_REF_URL;)?#devtool-the-workspace-layer-structure>`__", ":ref:`devtool-the-workspace-layer-structure`", line) line = re.sub("`Open-?Embedded b?B?uild s?S?ystem <(\&YOCTO_DOCS_REF_URL;)?#build-system-term>`__", ":term:`OpenEmbedded Build System`", line) line = re.sub("`(OpenEmbedded-Core )?(\(?OE-Core\)? )?<(\&YOCTO_DOCS_REF_URL;)?#oe-core>`__", ":term:`OpenEmbedded-Core (OE-Core)`", line) It won't catch multiline strings, but it catches a very large number of occurences! (From yocto-docs rev: 3f537d17de5b1fb76ba3bee196481984a4826378) Signed-off-by: Nicolas Dechesne Signed-off-by: Richard Purdie --- .../overview-manual/overview-manual-concepts.rst | 342 ++++++++++----------- .../overview-manual-development-environment.rst | 6 +- .../overview-manual/overview-manual-yp-intro.rst | 20 +- 3 files changed, 184 insertions(+), 184 deletions(-) (limited to 'documentation/overview-manual') diff --git a/documentation/overview-manual/overview-manual-concepts.rst b/documentation/overview-manual/overview-manual-concepts.rst index 3f4aa4f4c4..59096fbebf 100644 --- a/documentation/overview-manual/overview-manual-concepts.rst +++ b/documentation/overview-manual/overview-manual-concepts.rst @@ -14,9 +14,9 @@ explained. Yocto Project Components ======================== -The `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ task executor +The :term:`BitBake` task executor together with various types of configuration files form the -`OpenEmbedded-Core <&YOCTO_DOCS_REF_URL;#oe-core>`__. This section +:term:`OpenEmbedded-Core (OE-Core)`. This section overviews these components by describing their use and how they interact. @@ -50,7 +50,7 @@ BitBake BitBake is the tool at the heart of the `OpenEmbedded build system <&YOCTO_DOCS_REF_URL;#build-system-term>`__ and is responsible -for parsing the `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__, generating +for parsing the :term:`Metadata`, generating a list of tasks from it, and then executing those tasks. This section briefly introduces BitBake. If you want more information on @@ -107,7 +107,7 @@ Classes Class files (``.bbclass``) contain information that is useful to share between recipes files. An example is the -```autotools`` <&YOCTO_DOCS_REF_URL;#ref-classes-autotools>`__ class, +:ref:`autotools ` class, which contains common settings for any application that Autotools uses. The "`Classes <&YOCTO_DOCS_REF_URL;#ref-classes>`__" chapter in the Yocto Project Reference Manual provides details about classes and how to @@ -187,7 +187,7 @@ In general, the build's workflow consists of several functional areas: - *Source Files:* Upstream releases, local projects, and SCMs. - *Build System:* Processes under the control of - `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__. This block expands + :term:`BitBake`. This block expands on how BitBake fetches source, applies patches, completes compilation, analyzes output for package generation, creates and tests packages, generates images, and generates cross-development @@ -253,7 +253,7 @@ source the build environment setup script. Because the Poky repository is fundamentally an aggregation of existing repositories, some users might be familiar with running the ```` script in the context of separate -`OpenEmbedded-Core <&YOCTO_DOCS_REF_URL;#oe-core>`__ and BitBake +:term:`OpenEmbedded-Core (OE-Core)` and BitBake repositories rather than a single Poky repository. This discussion assumes the script is executed from within a cloned or unpacked version of Poky. @@ -281,29 +281,29 @@ script, see the in the ``meta-poky`` layer: - *Target Machine Selection:* Controlled by the - ```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable. + :term:`MACHINE` variable. - *Download Directory:* Controlled by the - ```DL_DIR`` <&YOCTO_DOCS_REF_URL;#var-DL_DIR>`__ variable. + :term:`DL_DIR` variable. - *Shared State Directory:* Controlled by the - ```SSTATE_DIR`` <&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR>`__ variable. + :term:`SSTATE_DIR` variable. - *Build Output:* Controlled by the - ```TMPDIR`` <&YOCTO_DOCS_REF_URL;#var-TMPDIR>`__ variable. + :term:`TMPDIR` variable. - *Distribution Policy:* Controlled by the - ```DISTRO`` <&YOCTO_DOCS_REF_URL;#var-DISTRO>`__ variable. + :term:`DISTRO` variable. - *Packaging Format:* Controlled by the - ```PACKAGE_CLASSES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES>`__ + :term:`PACKAGE_CLASSES` variable. - *SDK Target Architecture:* Controlled by the - ```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__ variable. + :term:`SDKMACHINE` variable. - *Extra Image Packages:* Controlled by the - ```EXTRA_IMAGE_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES>`__ + :term:`EXTRA_IMAGE_FEATURES` variable. .. note:: @@ -334,11 +334,11 @@ created by an autobuilder: you had several build environments and they shared some common features. You can set these default build properties here. A good example is perhaps the packaging format to use through the - ```PACKAGE_CLASSES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES>`__ + :term:`PACKAGE_CLASSES` variable. One useful scenario for using the ``conf/site.conf`` file is to - extend your ```BBPATH`` <&YOCTO_DOCS_REF_URL;#var-BBPATH>`__ variable + 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 and applies your common configurations found in the file. To override @@ -543,18 +543,18 @@ to build software. Finally, a combination of the two might exist, which would give the consumer a choice when deciding where to get source files. -BitBake uses the ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ +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. Another area that plays a significant role in where source files come from is pointed to by the -```DL_DIR`` <&YOCTO_DOCS_REF_URL;#var-DL_DIR>`__ variable. This area is +:term:`DL_DIR` variable. This area is 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 -```BB_GENERATE_MIRROR_TARBALLS`` <&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS>`__ +:term:`BB_GENERATE_MIRROR_TARBALLS` variable. Judicious use of a ``DL_DIR`` directory can save the build system a trip @@ -588,7 +588,7 @@ user checks in items (e.g. a local directory containing a development source tree used by the group). The canonical method through which to include a local project is to use -the ```externalsrc`` <&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc>`__ +the :ref:`externalsrc ` class to include that local project. You use either the ``local.conf`` or a recipe's append file to override or set the recipe to point to the local directory on your disk to pull in the whole source tree. @@ -602,8 +602,8 @@ Another place from which the build system can get source files is with `fetchers <&YOCTO_DOCS_BB_URL;#bb-fetchers>`__ employing various Source Control Managers (SCMs) such as Git or Subversion. In such cases, a repository is cloned or checked out. The -```do_fetch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-fetch>`__ task inside -BitBake uses the ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ +:ref:`ref-tasks-fetch` task inside +BitBake uses the :term:`SRC_URI` variable and the argument's prefix to determine the correct fetcher module. @@ -617,19 +617,19 @@ module. variable in the Yocto Project Reference Manual. When fetching a repository, BitBake uses the -```SRCREV`` <&YOCTO_DOCS_REF_URL;#var-SRCREV>`__ variable to determine +:term:`SRCREV` variable to determine the specific revision from which to build. Source Mirror(s) ~~~~~~~~~~~~~~~~ Two kinds of mirrors exist: pre-mirrors and regular mirrors. The -```PREMIRRORS`` <&YOCTO_DOCS_REF_URL;#var-PREMIRRORS>`__ and -```MIRRORS`` <&YOCTO_DOCS_REF_URL;#var-MIRRORS>`__ variables point to +:term:`PREMIRRORS` and +:term:`MIRRORS` variables point to these, respectively. BitBake checks pre-mirrors before looking upstream for any source files. Pre-mirrors are appropriate when you have a shared directory that is not a directory defined by the -```DL_DIR`` <&YOCTO_DOCS_REF_URL;#var-DL_DIR>`__ variable. A Pre-mirror +:term:`DL_DIR` variable. A Pre-mirror typically points to a shared directory that is local to your organization. @@ -657,10 +657,10 @@ the build system. Here is a more detailed look at the area: Package feeds are an intermediary step in the build process. The OpenEmbedded build system provides classes to generate different package types, and you specify which classes to enable through the -```PACKAGE_CLASSES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES>`__ +:term:`PACKAGE_CLASSES` variable. Before placing the packages into package feeds, the build process validates them with generated output quality assurance checks -through the ```insane`` <&YOCTO_DOCS_REF_URL;#ref-classes-insane>`__ +through the :ref:`insane ` class. The package feed area resides in the Build Directory. The directory the @@ -670,19 +670,19 @@ the "Package Feeds" box in the illustration and note the information to the right of that area. In particular, the following defines where package files are kept: -- ```DEPLOY_DIR`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR>`__: Defined as +- :term:`DEPLOY_DIR`: Defined as ``tmp/deploy`` in the Build Directory. - ``DEPLOY_DIR_*``: Depending on the package manager used, the package type sub-folder. Given RPM, IPK, or DEB packaging and tarball creation, the - ```DEPLOY_DIR_RPM`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_RPM>`__, - ```DEPLOY_DIR_IPK`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IPK>`__, - ```DEPLOY_DIR_DEB`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_DEB>`__, or - ```DEPLOY_DIR_TAR`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_TAR>`__, + :term:`DEPLOY_DIR_RPM`, + :term:`DEPLOY_DIR_IPK`, + :term:`DEPLOY_DIR_DEB`, or + :term:`DEPLOY_DIR_TAR`, variables are used, respectively. -- ```PACKAGE_ARCH`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH>`__: Defines +- :term:`PACKAGE_ARCH`: Defines architecture-specific sub-folders. For example, packages could exist for the i586 or qemux86 architectures. @@ -690,11 +690,11 @@ BitBake uses the ```do_package_write_*`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb>`__ tasks to generate packages and place them into the package holding area (e.g. ``do_package_write_ipk`` for IPK packages). See the -"```do_package_write_deb`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb>`__", -"```do_package_write_ipk`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk>`__", -"```do_package_write_rpm`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_rpm>`__", +":ref:`ref-tasks-package_write_deb`", +":ref:`ref-tasks-package_write_ipk`", +":ref:`ref-tasks-package_write_rpm`", and -"```do_package_write_tar`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_tar>`__" +":ref:`ref-tasks-package_write_tar`" sections in the Yocto Project Reference Manual for additional information. As an example, consider a scenario where an IPK packaging manager is being used and package architecture support for both i586 and @@ -708,7 +708,7 @@ BitBake ------- The OpenEmbedded build system uses -`BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ to produce images and +:term:`BitBake` to produce images and Software Development Kits (SDKs). You can see from the `general workflow figure <#general-workflow-figure>`__, the BitBake area consists of several functional areas. This section takes a closer look at each of @@ -731,8 +731,8 @@ code: .. image:: figures/source-fetching.png :align: center -The ```do_fetch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-fetch>`__ and -```do_unpack`` <&YOCTO_DOCS_REF_URL;#ref-tasks-unpack>`__ tasks fetch +The :ref:`ref-tasks-fetch` and +:ref:`ref-tasks-unpack` tasks fetch the source files and unpack them into the `Build Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__. @@ -756,17 +756,17 @@ Directory, see the the Yocto Project Reference Manual. Each recipe has an area in the Build Directory where the unpacked source -code resides. The ```S`` <&YOCTO_DOCS_REF_URL;#var-S>`__ variable points +code resides. The :term:`S` variable points to this area for a recipe's unpacked source code. The name of that directory for any given recipe is defined from several different variables. The preceding figure and the following list describe the Build Directory's hierarchy: -- ```TMPDIR`` <&YOCTO_DOCS_REF_URL;#var-TMPDIR>`__: The base directory +- :term:`TMPDIR`: The base directory where the OpenEmbedded build system performs all its work during the build. The default base directory is the ``tmp`` directory. -- ```PACKAGE_ARCH`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH>`__: The +- :term:`PACKAGE_ARCH`: The architecture of the built package or packages. Depending on the eventual destination of the package or packages (i.e. machine architecture, `build @@ -774,33 +774,33 @@ Build Directory's hierarchy: specific machine), ``PACKAGE_ARCH`` varies. See the variable's description for details. -- ```TARGET_OS`` <&YOCTO_DOCS_REF_URL;#var-TARGET_OS>`__: The operating +- :term:`TARGET_OS`: The operating system of the target device. A typical value would be "linux" (e.g. "qemux86-poky-linux"). -- ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__: The name of the recipe used +- :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 the the name of the recipe. -- ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__: The location +- :term:`WORKDIR`: The location where the OpenEmbedded build system builds a recipe (i.e. does the work to create the package). - - ```PV`` <&YOCTO_DOCS_REF_URL;#var-PV>`__: The version of the + - :term:`PV`: The version of the recipe used to build the package. - - ```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__: The revision of the + - :term:`PR`: The revision of the recipe used to build the package. -- ```S`` <&YOCTO_DOCS_REF_URL;#var-S>`__: Contains the unpacked source +- :term:`S`: Contains the unpacked source files for a given recipe. - - ```BPN`` <&YOCTO_DOCS_REF_URL;#var-BPN>`__: The name of the recipe + - :term:`BPN`: The name of the recipe used to build the package. The ``BPN`` variable is a version of the ``PN`` variable but with common prefixes and suffixes removed. - - ```PV`` <&YOCTO_DOCS_REF_URL;#var-PV>`__: The version of the + - :term:`PV`: The version of the recipe used to build the package. .. note:: @@ -825,15 +825,15 @@ and applies them to the source files: .. image:: figures/patching.png :align: center -The ```do_patch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-patch>`__ task uses a -recipe's ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements -and the ```FILESPATH`` <&YOCTO_DOCS_REF_URL;#var-FILESPATH>`__ variable +The :ref:`ref-tasks-patch` task uses a +recipe's :term:`SRC_URI` statements +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 to change the way the build system recognizes patch files. See the -```do_patch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-patch>`__ task for more +:ref:`ref-tasks-patch` task for more information. BitBake finds and applies multiple patches for a single recipe in the @@ -841,7 +841,7 @@ order in which it locates the patches. The ``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 -```S`` <&YOCTO_DOCS_REF_URL;#var-S>`__ directory. +:term:`S` directory. For more information on how the source directories are created, see the "`Source Fetching <#source-fetching-dev-environment>`__" section. For @@ -871,13 +871,13 @@ to a holding area (staged) in preparation for packaging: This step in the build process consists of the following tasks: -- ```do_prepare_recipe_sysroot`` <&YOCTO_DOCS_REF_URL;#ref-tasks-prepare_recipe_sysroot>`__: +- :ref:`ref-tasks-prepare_recipe_sysroot`: This task sets up the two sysroots in - ``${``\ ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__\ ``}`` + ``${``\ :term:`WORKDIR`\ ``}`` (i.e. ``recipe-sysroot`` and ``recipe-sysroot-native``) so that during the packaging phase the sysroots can contain the contents of the - ```do_populate_sysroot`` <&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot>`__ + :ref:`ref-tasks-populate_sysroot` tasks of the recipes on which the recipe containing the tasks depends. A sysroot exists for both the target and for the native binaries, which run on the host system. @@ -889,32 +889,32 @@ This step in the build process consists of the following tasks: configure itself depending on the target for which it is being built. The configurations handled by the - ```do_configure`` <&YOCTO_DOCS_REF_URL;#ref-tasks-configure>`__ task + :ref:`ref-tasks-configure` task are specific to configurations for the source code being built by the recipe. If you are using the - ```autotools`` <&YOCTO_DOCS_REF_URL;#ref-classes-autotools>`__ class, + :ref:`autotools ` class, you can add additional configuration options by using the - ```EXTRA_OECONF`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF>`__ or - ```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__ + :term:`EXTRA_OECONF` or + :term:`PACKAGECONFIG_CONFARGS` variables. For information on how this variable works within that class, see the - ```autotools`` <&YOCTO_DOCS_REF_URL;#ref-classes-autotools>`__ class + :ref:`autotools ` class `here <&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/autotools.bbclass>`__. - *``do_compile``*: Once a configuration task has been satisfied, BitBake compiles the source using the - ```do_compile`` <&YOCTO_DOCS_REF_URL;#ref-tasks-compile>`__ task. + :ref:`ref-tasks-compile` task. Compilation occurs in the directory pointed to by the - ```B`` <&YOCTO_DOCS_REF_URL;#var-B>`__ variable. Realize that the + :term:`B` variable. Realize that the ``B`` directory is, by default, the same as the - ```S`` <&YOCTO_DOCS_REF_URL;#var-S>`__ directory. + :term:`S` directory. - *``do_install``*: After compilation completes, BitBake executes the - ```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ task. + :ref:`ref-tasks-install` task. This task copies files from the ``B`` directory and places them in a - holding area pointed to by the ```D`` <&YOCTO_DOCS_REF_URL;#var-D>`__ + holding area pointed to by the :term:`D` variable. Packaging occurs later using files from this holding directory. @@ -929,10 +929,10 @@ analyzes the results and splits the output into packages: .. image:: figures/analysis-for-package-splitting.png :align: center -The ```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__ and -```do_packagedata`` <&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata>`__ +The :ref:`ref-tasks-package` and +:ref:`ref-tasks-packagedata` tasks combine to analyze the files found in the -```D`` <&YOCTO_DOCS_REF_URL;#var-D>`__ directory and split them into +:term:`D` directory and split them into subsets based on available packages and files. Analysis involves the following as well as other items: splitting out debugging symbols, looking at shared library dependencies between packages, and looking at @@ -940,46 +940,46 @@ package relationships. The ``do_packagedata`` task creates package metadata based on the analysis such that the build system can generate the final packages. The -```do_populate_sysroot`` <&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot>`__ +:ref:`ref-tasks-populate_sysroot` task stages (copies) a subset of the files installed by the -```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ task into +:ref:`ref-tasks-install` task into the appropriate sysroot. Working, staged, and intermediate results of the analysis and package splitting process use several areas: -- ```PKGD`` <&YOCTO_DOCS_REF_URL;#var-PKGD>`__: The destination +- :term:`PKGD`: The destination directory (i.e. ``package``) for packages before they are split into individual packages. -- ```PKGDESTWORK`` <&YOCTO_DOCS_REF_URL;#var-PKGDESTWORK>`__: A +- :term:`PKGDESTWORK`: A temporary work area (i.e. ``pkgdata``) used by the ``do_package`` task to save package metadata. -- ```PKGDEST`` <&YOCTO_DOCS_REF_URL;#var-PKGDEST>`__: The parent +- :term:`PKGDEST`: The parent directory (i.e. ``packages-split``) for packages after they have been split. -- ```PKGDATA_DIR`` <&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR>`__: A shared, +- :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 available. -- ```STAGING_DIR_HOST`` <&YOCTO_DOCS_REF_URL;#var-STAGING_DIR_HOST>`__: +- :term:`STAGING_DIR_HOST`: The path for the sysroot for the system on which a component is built to run (i.e. ``recipe-sysroot``). -- ```STAGING_DIR_NATIVE`` <&YOCTO_DOCS_REF_URL;#var-STAGING_DIR_NATIVE>`__: +- :term:`STAGING_DIR_NATIVE`: The path for the sysroot used when building components for the build host (i.e. ``recipe-sysroot-native``). -- ```STAGING_DIR_TARGET`` <&YOCTO_DOCS_REF_URL;#var-STAGING_DIR_TARGET>`__: +- :term:`STAGING_DIR_TARGET`: The path for the sysroot used when a component that is built to execute on a system and it generates code for yet another machine (e.g. cross-canadian recipes). -The ```FILES`` <&YOCTO_DOCS_REF_URL;#var-FILES>`__ variable defines the +The :term:`FILES` variable defines the files that go into each package in -```PACKAGES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGES>`__. If you want +:term:`PACKAGES`. If you want details on how this is accomplished, you can look at ```package.bbclass`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/package.bbclass>`__. @@ -1013,36 +1013,36 @@ system uses BitBake to generate the root filesystem image: The image generation process consists of several stages and depends on several tasks and variables. The -```do_rootfs`` <&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs>`__ task creates +:ref:`ref-tasks-rootfs` task creates the root filesystem (file and directory structure) for an image. This task uses several key variables to help create the list of packages to actually install: -- ```IMAGE_INSTALL`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL>`__: Lists +- :term:`IMAGE_INSTALL`: Lists out the base set of packages from which to install from the Package Feeds area. -- ```PACKAGE_EXCLUDE`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE>`__: +- :term:`PACKAGE_EXCLUDE`: Specifies packages that should not be installed into the image. -- ```IMAGE_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES>`__: +- :term:`IMAGE_FEATURES`: Specifies features to include in the image. Most of these features map to additional packages for installation. -- ```PACKAGE_CLASSES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES>`__: +- :term:`PACKAGE_CLASSES`: Specifies the package backend (e.g. RPM, DEB, or IPK) to use and consequently helps determine where to locate packages within the Package Feeds area. -- ```IMAGE_LINGUAS`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_LINGUAS>`__: +- :term:`IMAGE_LINGUAS`: Determines the language(s) for which additional language support packages are installed. -- ```PACKAGE_INSTALL`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL>`__: +- :term:`PACKAGE_INSTALL`: The final list of packages passed to the package manager for installation into the image. -With ```IMAGE_ROOTFS`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_ROOTFS>`__ +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 install, the root file system is created. @@ -1069,27 +1069,27 @@ root filesystem image. This file lists out, line-by-line, the installed packages. The manifest file is useful for the ```testimage`` <&YOCTO_DOCS_REF_URL;#ref-classes-testimage*>`__ class, for example, to determine whether or not to run specific tests. See the -```IMAGE_MANIFEST`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_MANIFEST>`__ +:term:`IMAGE_MANIFEST` variable for additional information. Optimizing processes that are run across the image include ``mklibs``, ``prelink``, and any other post-processing commands as defined by the -```ROOTFS_POSTPROCESS_COMMAND`` <&YOCTO_DOCS_REF_URL;#var-ROOTFS_POSTPROCESS_COMMAND>`__ +:term:`ROOTFS_POSTPROCESS_COMMAND` variable. The ``mklibs`` process optimizes the size of the libraries, while the ``prelink`` process optimizes the dynamic linking of shared libraries to reduce start up time of executables. After the root filesystem is built, processing begins on the image -through the ```do_image`` <&YOCTO_DOCS_REF_URL;#ref-tasks-image>`__ +through the :ref:`ref-tasks-image` task. The build system runs any pre-processing commands as defined by the -```IMAGE_PREPROCESS_COMMAND`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_PREPROCESS_COMMAND>`__ +:term:`IMAGE_PREPROCESS_COMMAND` variable. This variable specifies a list of functions to call before the build system creates the final image output files. The build system dynamically creates ``do_image_*`` tasks as needed, based on the image types specified in the -```IMAGE_FSTYPES`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES>`__ variable. +:term:`IMAGE_FSTYPES` variable. 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 @@ -1105,7 +1105,7 @@ The final task involved in image creation is the ```do_image_complete`` <&YOCTO_DOCS_REF_URL;#ref-tasks-image-complete>`__ task. This task completes the image by applying any image post processing as defined through the -```IMAGE_POSTPROCESS_COMMAND`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_POSTPROCESS_COMMAND>`__ +:term:`IMAGE_POSTPROCESS_COMMAND` variable. The variable specifies a list of functions to call once the build system has created the final image output files. @@ -1143,9 +1143,9 @@ the extensible SDK (eSDK): Like image generation, the SDK script process consists of several stages and depends on many variables. The -```do_populate_sdk`` <&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk>`__ +:ref:`ref-tasks-populate_sdk` and -```do_populate_sdk_ext`` <&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk_ext>`__ +:ref:`ref-tasks-populate_sdk_ext` tasks use these key variables to help create the list of packages to actually install. For information on the variables listed in the figure, see the "`Application Development SDK <#sdk-dev-environment>`__" @@ -1155,7 +1155,7 @@ The ``do_populate_sdk`` task helps create the standard SDK and handles two parts: a target part and a host part. The target part is the part built for the target hardware and includes libraries and headers. The host part is the part of the SDK that runs on the -```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__. +:term:`SDKMACHINE`. The ``do_populate_sdk_ext`` task helps create the extensible SDK and handles host and target parts differently than its counter part does for @@ -1173,9 +1173,9 @@ Stamp Files and the Rerunning of Tasks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For each task that completes successfully, BitBake writes a stamp file -into the ```STAMPS_DIR`` <&YOCTO_DOCS_REF_URL;#var-STAMPS_DIR>`__ +into the :term:`STAMPS_DIR` directory. The beginning of the stamp file's filename is determined by -the ```STAMP`` <&YOCTO_DOCS_REF_URL;#var-STAMP>`__ variable, and the end +the :term:`STAMP` variable, and the end of the name consists of the task's name and current `input checksum <#overview-checksums>`__. @@ -1202,8 +1202,8 @@ file does not exist, the task is rerun. However, you should realize that stamp files only serve as a marker that some work has been done and that these files do not record task output. The actual task output would usually be somewhere in - ```TMPDIR`` <&YOCTO_DOCS_REF_URL;#var-TMPDIR>`__ (e.g. in some - recipe's ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__.) What + :term:`TMPDIR` (e.g. in some + recipe's :term:`WORKDIR`.) What the sstate cache mechanism adds is a way to cache task output that can then be shared between build machines. @@ -1244,16 +1244,16 @@ locations as needed. In some cases, it makes sense to have a setscene task variant (e.g. generating package files in the ```do_package_write_*`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb>`__ task). In other cases, it does not make sense (e.g. a -```do_patch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-patch>`__ task or a -```do_unpack`` <&YOCTO_DOCS_REF_URL;#ref-tasks-unpack>`__ task) since +:ref:`ref-tasks-patch` task or a +:ref:`ref-tasks-unpack` task) since the work involved would be equal to or greater than the underlying task. In the build system, the common tasks that have setscene variants are -```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__, +:ref:`ref-tasks-package`, ``do_package_write_*``, -```do_deploy`` <&YOCTO_DOCS_REF_URL;#ref-tasks-deploy>`__, -```do_packagedata`` <&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata>`__, and -```do_populate_sysroot`` <&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot>`__. +:ref:`ref-tasks-deploy`, +:ref:`ref-tasks-packagedata`, and +:ref:`ref-tasks-populate_sysroot`. Notice that these tasks represent most of the tasks whose output is an end result. @@ -1321,14 +1321,14 @@ The build process writes images out to the `Build Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ inside the ``tmp/deploy/images/machine/`` folder as shown in the figure. This folder contains any files expected to be loaded on the target device. -The ```DEPLOY_DIR`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR>`__ variable +The :term:`DEPLOY_DIR` variable points to the ``deploy`` directory, while the -```DEPLOY_DIR_IMAGE`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IMAGE>`__ +:term:`DEPLOY_DIR_IMAGE` variable points to the appropriate directory containing images for the current configuration. - kernel-image: A kernel binary file. The - ```KERNEL_IMAGETYPE`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE>`__ + :term:`KERNEL_IMAGETYPE` variable determines the naming scheme for the kernel image file. Depending on this variable, the file could begin with a variety of naming strings. The ``deploy/images/``\ machine directory can contain @@ -1336,7 +1336,7 @@ current configuration. - root-filesystem-image: Root filesystems for the target device (e.g. ``*.ext3`` or ``*.bz2`` files). The - ```IMAGE_FSTYPES`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES>`__ + :term:`IMAGE_FSTYPES` variable determines the root filesystem image type. The ``deploy/images/``\ machine directory can contain multiple root filesystems for the machine. @@ -1344,7 +1344,7 @@ current configuration. - kernel-modules: Tarballs that contain all the modules built for the kernel. Kernel module tarballs exist for legacy purposes and can be suppressed by setting the - ```MODULE_TARBALL_DEPLOY`` <&YOCTO_DOCS_REF_URL;#var-MODULE_TARBALL_DEPLOY>`__ + :term:`MODULE_TARBALL_DEPLOY` variable to "0". The ``deploy/images/``\ machine directory can contain multiple kernel module tarballs for the machine. @@ -1401,72 +1401,72 @@ can initialize the environment before using the tools. Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual. All the output files for an SDK are written to the ``deploy/sdk`` folder -inside the `Build Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ as +inside the :term:`Build Directory` as shown in the previous figure. Depending on the type of SDK, several variables exist that help configure these files. The following list shows the variables associated with an extensible SDK: -- ```DEPLOY_DIR`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR>`__: Points to +- :term:`DEPLOY_DIR`: Points to the ``deploy`` directory. -- ```SDK_EXT_TYPE`` <&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE>`__: +- :term:`SDK_EXT_TYPE`: Controls whether or not shared state artifacts are copied into the extensible SDK. By default, all required shared state artifacts are copied into the SDK. -- ```SDK_INCLUDE_PKGDATA`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA>`__: +- :term:`SDK_INCLUDE_PKGDATA`: Specifies whether or not packagedata is included in the extensible SDK for all recipes in the "world" target. -- ```SDK_INCLUDE_TOOLCHAIN`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN>`__: +- :term:`SDK_INCLUDE_TOOLCHAIN`: Specifies whether or not the toolchain is included when building the extensible SDK. -- ```SDK_LOCAL_CONF_WHITELIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST>`__: +- :term:`SDK_LOCAL_CONF_WHITELIST`: A list of variables allowed through from the build system configuration into the extensible SDK configuration. -- ```SDK_LOCAL_CONF_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST>`__: +- :term:`SDK_LOCAL_CONF_BLACKLIST`: A list of variables not allowed through from the build system configuration into the extensible SDK configuration. -- ```SDK_INHERIT_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST>`__: +- :term:`SDK_INHERIT_BLACKLIST`: A list of classes to remove from the - ```INHERIT`` <&YOCTO_DOCS_REF_URL;#var-INHERIT>`__ value globally + :term:`INHERIT` value globally within the extensible SDK configuration. This next list, shows the variables associated with a standard SDK: -- ```DEPLOY_DIR`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR>`__: Points to +- :term:`DEPLOY_DIR`: Points to the ``deploy`` directory. -- ```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__: Specifies +- :term:`SDKMACHINE`: Specifies the architecture of the machine on which the cross-development tools are run to create packages for the target hardware. -- ```SDKIMAGE_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-SDKIMAGE_FEATURES>`__: +- :term:`SDKIMAGE_FEATURES`: Lists the features to include in the "target" part of the SDK. -- ```TOOLCHAIN_HOST_TASK`` <&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK>`__: +- :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 ``bitbake -c populate_sdk imagename`` to create the SDK, a set of default packages apply. This variable allows you to add more packages. -- ```TOOLCHAIN_TARGET_TASK`` <&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK>`__: +- :term:`TOOLCHAIN_TARGET_TASK`: Lists packages that make up the target part of the SDK (i.e. the part built for the target hardware). -- ```SDKPATH`` <&YOCTO_DOCS_REF_URL;#var-SDKPATH>`__: Defines the +- :term:`SDKPATH`: Defines the default SDK installation path offered by the installation script. -- ```SDK_HOST_MANIFEST`` <&YOCTO_DOCS_REF_URL;#var-SDK_HOST_MANIFEST>`__: +- :term:`SDK_HOST_MANIFEST`: Lists all the installed packages that make up the host part of the SDK. This variable also plays a minor role for extensible SDK development as well. However, it is mainly used for the standard SDK. -- ```SDK_TARGET_MANIFEST`` <&YOCTO_DOCS_REF_URL;#var-SDK_TARGET_MANIFEST>`__: +- :term:`SDK_TARGET_MANIFEST`: Lists all the installed packages that make up the target part of the SDK. This variable also plays a minor role for extensible SDK development as well. However, it is mainly used for the standard SDK. @@ -1497,7 +1497,7 @@ toolchain construction and use. Most of the work occurs on the Build Host. This is the machine used to build images and generally work within the the Yocto Project environment. When you run -`BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ to create an image, the +:term:`BitBake` to create an image, the OpenEmbedded build system uses the host ``gcc`` compiler to bootstrap a cross-compiler named ``gcc-cross``. The ``gcc-cross`` compiler is what BitBake uses to compile source files when creating the target image. You @@ -1558,11 +1558,11 @@ relocatable SDK used to develop applications. When you run the installer, it installs the toolchain, which contains the development tools (e.g., ``gcc-cross-canadian``, ``binutils-cross-canadian``, and other ``nativesdk-*`` tools), which are tools native to the SDK (i.e. -native to ```SDK_ARCH`` <&YOCTO_DOCS_REF_URL;#var-SDK_ARCH>`__), you +native to :term:`SDK_ARCH`), you need to cross-compile and test your software. The figure shows the commands you use to easily build out this toolchain. This cross-development toolchain is built to execute on the -```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__, which might or +:term:`SDKMACHINE`, which might or might not be the same machine as the Build Host. .. note:: @@ -1603,7 +1603,7 @@ glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian (i.e. it is designed to run on the build host). - ``gcc-cross-canadian``: The final relocatable cross-compiler. When - run on the ```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__, + run on the :term:`SDKMACHINE`, this tool produces executable code that runs on the target device. Only one cross-canadian compiler is produced per architecture since they can be targeted at different processor optimizations using @@ -1623,7 +1623,7 @@ Shared State Cache ================== By design, the OpenEmbedded build system builds everything from scratch -unless `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ can determine +unless :term:`BitBake` can determine that parts do not need to be rebuilt. Fundamentally, building from scratch is attractive as it means all parts are built fresh and no possibility of stale data exists that can cause problems. When @@ -1664,7 +1664,7 @@ them if they are deemed to be valid. .. note:: - The build system does not maintain - ```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__ information as part of + :term:`PR` information as part of the shared state packages. Consequently, considerations exist that affect maintaining shared state feeds. For information on how the build system works with packages and can track incrementing ``PR`` @@ -1695,8 +1695,8 @@ works on a per-task basis rather than a per-recipe basis. You might wonder why using a per-task basis is preferred over a per-recipe basis. To help explain, consider having the IPK packaging backend enabled and then switching to DEB. In this case, the -```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ and -```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__ task outputs +:ref:`ref-tasks-install` and +:ref:`ref-tasks-package` task outputs are still valid. However, with a per-recipe approach, the build would not include the ``.deb`` files. Consequently, you would have to invalidate the whole build and rerun it. Rerunning everything is not the @@ -1720,7 +1720,7 @@ you a good idea of when the task's data changes. To complicate the problem, there are things that should not be included in the checksum. First, there is the actual specific build path of a -given task - the ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__. It +given task - the :term:`WORKDIR`. It does not matter if the work directory changes because it should not affect the output for target packages. Also, the build process has the objective of making native or cross packages relocatable. @@ -1755,9 +1755,9 @@ Like the ``WORKDIR`` case, situations exist 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: PACKAGE_ARCHS[vardepsexclude] = "MACHINE" This example ensures that the -```PACKAGE_ARCHS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCHS>`__ variable +:term:`PACKAGE_ARCHS` variable does not depend on the value of -```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__, even if it does +:term:`MACHINE`, even if it does reference it. Equally, there are cases where you need to add dependencies BitBake is @@ -1795,9 +1795,9 @@ STAGING_DIR_TARGET COREBASE PRSERV_HOST \\ PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \\ CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" The previous example excludes -```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__ since that variable +:term:`WORKDIR` since that variable is actually constructed as a path within -```TMPDIR`` <&YOCTO_DOCS_REF_URL;#var-TMPDIR>`__, which is on the +:term:`TMPDIR`, which is on the whitelist. The rules for deciding which hashes of dependent tasks to include @@ -1806,7 +1806,7 @@ accomplished with a Python function. The code in ``meta/lib/oe/sstatesig.py`` shows two examples of this and also illustrates how you can insert your own policy into the system if so desired. This file defines the two basic signature generators -`OE-Core <&YOCTO_DOCS_REF_URL;#oe-core>`__ uses: "OEBasic" and +:term:`OpenEmbedded-Core (OE-Core)` uses: "OEBasic" and "OEBasicHash". By default, a dummy "noop" signature handler is enabled in BitBake. This means that behavior is unchanged from previous versions. OE-Core uses the "OEBasicHash" signature handler by default @@ -1816,7 +1816,7 @@ as the "OEBasic" version but adds the task hash to the `stamp files <#stamp-files-and-the-rerunning-of-tasks>`__. This results in any metadata change that changes the task hash, automatically causing the task to be run again. This removes the need to bump -```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__ values, and changes to metadata +:term:`PR` values, and changes to metadata automatically ripple across the build. It is also worth noting that the end result of these signature @@ -1842,7 +1842,7 @@ half the problem of supporting a shared state. The other half of the problem is being able to use checksum information during the build and being able to reuse or rebuild specific components. -The ```sstate`` <&YOCTO_DOCS_REF_URL;#ref-classes-sstate>`__ class is a +The :ref:`sstate ` class is a relatively generic implementation of how to "capture" a snapshot of a given task. The idea is that the build process does not care about the source of a task's output. Output could be freshly built or it could be @@ -1850,18 +1850,18 @@ downloaded and unpacked from somewhere. In other words, the build process does not need to worry about its origin. Two types of output exist. One type is just about creating a directory -in ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__. A good example is +in :term:`WORKDIR`. A good example is the output of either -```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ or -```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__. The other +:ref:`ref-tasks-install` or +:ref:`ref-tasks-package`. The other type of output occurs when a set of data is merged into a shared directory tree such as the sysroot. The Yocto Project team has tried to keep the details of the implementation hidden in ``sstate`` class. From a user's perspective, adding shared state wrapping to a task is as simple as this -```do_deploy`` <&YOCTO_DOCS_REF_URL;#ref-tasks-deploy>`__ example taken -from the ```deploy`` <&YOCTO_DOCS_REF_URL;#ref-classes-deploy>`__ class: +:ref:`ref-tasks-deploy` example taken +from the :ref:`deploy ` class: DEPLOYDIR = "${WORKDIR}/deploy-${PN}" SSTATETASKS += "do_deploy" do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" python @@ -1871,9 +1871,9 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] = - Adding "do_deploy" to ``SSTATETASKS`` adds some required sstate-related processing, which is implemented in the - ```sstate`` <&YOCTO_DOCS_REF_URL;#ref-classes-sstate>`__ class, to + :ref:`sstate ` class, to before and after the - ```do_deploy`` <&YOCTO_DOCS_REF_URL;#ref-tasks-deploy>`__ task. + :ref:`ref-tasks-deploy` task. - The ``do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"`` declares that ``do_deploy`` places its output in ``${DEPLOYDIR}`` when run normally @@ -1965,8 +1965,8 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] = "${PACKAGELOCK}" Behind the scenes, the shared state code works by looking in -```SSTATE_DIR`` <&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR>`__ and -```SSTATE_MIRRORS`` <&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS>`__ for +:term:`SSTATE_DIR` and +:term:`SSTATE_MIRRORS` for shared state files. Here is an example: SSTATE_MIRRORS ?= "\\ file://.\* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \\n \\ file://.\* file:///some/local/dir/sstate/PATH" @@ -1998,7 +1998,7 @@ tasks on which it is dependent are not executed. As a real world example, the aim is when building an IPK-based image, only the -```do_package_write_ipk`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk>`__ +:ref:`ref-tasks-package_write_ipk` tasks would have their shared state packages fetched and extracted. Since the sysroot is not used, it would never get extracted. This is another reason why a task-based approach is preferred over a @@ -2011,22 +2011,22 @@ Automatically Added Runtime Dependencies The OpenEmbedded build system automatically adds common types of runtime dependencies between packages, which means that you do not need to explicitly declare the packages using -```RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-RDEPENDS>`__. Three automatic +:term:`RDEPENDS`. Three automatic mechanisms exist (``shlibdeps``, ``pcdeps``, and ``depchains``) that handle shared libraries, package configuration (pkg-config) modules, and ``-dev`` and ``-dbg`` packages, respectively. For other types of runtime dependencies, you must manually declare the dependencies. - ``shlibdeps``: During the - ```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__ task of + :ref:`ref-tasks-package` task of each recipe, all shared libraries installed by the recipe are located. For each shared library, the package that contains the shared library is registered as providing the shared library. More specifically, the package is registered as providing the `soname `__ of the library. The resulting shared-library-to-package mapping is saved globally in - ```PKGDATA_DIR`` <&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR>`__ by the - ```do_packagedata`` <&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata>`__ + :term:`PKGDATA_DIR` by the + :ref:`ref-tasks-packagedata` task. Simultaneously, all executables and shared libraries installed by the @@ -2047,7 +2047,7 @@ dependencies, you must manually declare the dependencies. If you want to avoid a package being registered as providing a particular shared library (e.g. because the library is for internal use only), then add the library to - ```PRIVATE_LIBS`` <&YOCTO_DOCS_REF_URL;#var-PRIVATE_LIBS>`__ inside + :term:`PRIVATE_LIBS` inside the package's recipe. - ``pcdeps``: During the ``do_package`` task of each recipe, all @@ -2082,7 +2082,7 @@ dependencies, you must manually declare the dependencies. need for a dependency between the packages. The dependencies added by ``depchains`` are in the form of - ```RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS>`__. + :term:`RRECOMMENDS`. .. note:: @@ -2101,11 +2101,11 @@ dependencies, you must manually declare the dependencies. To ensure that the dependency chain is never broken, ``-dev`` and ``-dbg`` packages are always generated by default, even if the packages turn out to be empty. See the - ```ALLOW_EMPTY`` <&YOCTO_DOCS_REF_URL;#var-ALLOW_EMPTY>`__ variable + :term:`ALLOW_EMPTY` variable for more information. The ``do_package`` task depends on the ``do_packagedata`` task of each -recipe in ```DEPENDS`` <&YOCTO_DOCS_REF_URL;#var-DEPENDS>`__ through use +recipe in :term:`DEPENDS` through use of a ``[``\ ```deptask`` <&YOCTO_DOCS_BB_URL;#variable-flags>`__\ ``]`` declaration, which guarantees that the required shared-library/module-to-package mapping information will be available @@ -2116,15 +2116,15 @@ Fakeroot and Pseudo Some tasks are easier to implement when allowed to perform certain operations that are normally reserved for the root user (e.g. -```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__, +:ref:`ref-tasks-install`, ```do_package_write*`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb>`__, -```do_rootfs`` <&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs>`__, and +:ref:`ref-tasks-rootfs`, and ```do_image*`` <&YOCTO_DOCS_REF_URL;#ref-tasks-image>`__). For example, the ``do_install`` task benefits from being able to set the UID and GID of installed files to arbitrary values. One approach to allowing tasks to perform root-only operations would be -to require `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ to run as +to require :term:`BitBake` to run as root. However, this method is cumbersome and has security issues. The approach that is actually used is to run tasks that benefit from root privileges in a "fake" root environment. Within this environment, the @@ -2148,7 +2148,7 @@ which results in the illusion of running as root. To keep track of "fake" file ownership and permissions resulting from operations that require root permissions, Pseudo uses an SQLite 3 database. This database is stored in -``${``\ ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__\ ``}/pseudo/files.db`` +``${``\ :term:`WORKDIR`\ ``}/pseudo/files.db`` for individual recipes. Storing the database in a file as opposed to in memory gives persistence between tasks and builds, which is not accomplished using fakeroot. diff --git a/documentation/overview-manual/overview-manual-development-environment.rst b/documentation/overview-manual/overview-manual-development-environment.rst index d59e52c488..745d2ecf91 100644 --- a/documentation/overview-manual/overview-manual-development-environment.rst +++ b/documentation/overview-manual/overview-manual-development-environment.rst @@ -149,7 +149,7 @@ Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. From the interface, you can click on any particular item in the "Name" column and see the URL at the bottom of the page that you need to clone a Git repository for that particular item. Having a local Git repository of -the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__, which +the :term:`Source Directory`, which is usually named "poky", allows you to make changes, contribute to the history, and ultimately enhance the Yocto Project's tools, Board Support Packages, and so forth. @@ -636,7 +636,7 @@ find information on the GNU GPL When you build an image using the Yocto Project, the build process uses a known list of licenses to ensure compliance. You can find this list in -the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ at +the :term:`Source Directory` at ``meta/files/common-licenses``. Once the build completes, the list of all licenses found and used during that build are kept in the `Build Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ at @@ -660,7 +660,7 @@ that conform to the Open Source Definition (OSD). You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses in the ``meta/files/common-licenses`` directory in your -`Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__. +:term:`Source Directory`. For information that can help you maintain compliance with various open source licensing during the lifecycle of a product created using the diff --git a/documentation/overview-manual/overview-manual-yp-intro.rst b/documentation/overview-manual/overview-manual-yp-intro.rst index 3f845731a0..b27412cb25 100644 --- a/documentation/overview-manual/overview-manual-yp-intro.rst +++ b/documentation/overview-manual/overview-manual-yp-intro.rst @@ -260,7 +260,7 @@ accomplish this through a recipe that is a BitBake append Yocto Project Board Support Packages (BSP) Developer's Guide . -The `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ +The :term:`Source Directory` contains both general layers and BSP layers right out of the box. You can easily identify layers that ship with a Yocto Project release in the Source Directory by their names. Layers typically have names that begin @@ -461,7 +461,7 @@ Open-Embedded Build System Components ------------------------------------- The following list consists of components associated with the -`OpenEmbedded build system <&YOCTO_DOCS_REF_URL;#build-system-term>`__: +:term:`OpenEmbedded Build System`: - *BitBake:* BitBake is a core component of the Yocto Project and is used by the OpenEmbedded build system to build images. While BitBake @@ -508,7 +508,7 @@ Reference Distribution (Poky) ----------------------------- Poky is the Yocto Project reference distribution. It contains the -`Open-Embedded build system <&YOCTO_DOCS_REF_URL;#build-system-term>`__ +:term:`OpenEmbedded Build System` (BitBake and OE-Core) as well as a set of metadata to get you started building your own distribution. See the `figure <#what-is-the-yocto-project>`__ in "What is the Yocto Project?" @@ -618,7 +618,7 @@ Project. - *Native Linux Host:* By far the best option for a Build Host. A system running Linux as its native operating system allows you to develop software by directly using the - `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ tool. You can + :term:`BitBake` tool. You can accomplish all aspects of development from a familiar shell of a supported Linux distribution. @@ -684,9 +684,9 @@ Reference Embedded Distribution (Poky) "Poky", which is pronounced *Pock*-ee, is the name of the Yocto Project's reference distribution or Reference OS Kit. Poky contains the -`OpenEmbedded Build System <&YOCTO_DOCS_REF_URL;#build-system-term>`__ -(`BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ and -`OpenEmbedded-Core <&YOCTO_DOCS_REF_URL;#oe-core>`__) as well as a set +:term:`OpenEmbedded Build System` +(:term:`BitBake` and +:term:`OpenEmbedded-Core (OE-Core)`) as well as a set of `metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ to get you started building your own distro. In other words, Poky is a base specification of the functionality needed for a typical embedded system as well as the @@ -923,9 +923,9 @@ helpful for getting started: Another point worth noting is that historically within the Yocto Project, recipes were referred to as packages - thus, the existence of several BitBake variables that are seemingly mis-named, (e.g. - ```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__, - ```PV`` <&YOCTO_DOCS_REF_URL;#var-PV>`__, and - ```PE`` <&YOCTO_DOCS_REF_URL;#var-PE>`__). + :term:`PR`, + :term:`PV`, and + :term:`PE`). - *Poky:* Poky is a reference embedded distribution and a reference test configuration. Poky provides the following: -- cgit v1.2.3-54-g00ecf