From b44fbe5b1b425b8a8c23e4f0ba80583944ab303a Mon Sep 17 00:00:00 2001 From: Michael Opdenacker Date: Thu, 27 Oct 2022 15:09:08 +0200 Subject: manuals: use references to the "Build Directory" term Replace instances of "Build Directory" and "build directory" (when applicable) by :term:`Build Directory` as already done in most places. Doing this, fix the indentation of the paragraphs with this term. (From yocto-docs rev: dce50679242d39f133e0cde5c8483b5e69f3eb54) Signed-off-by: Michael Opdenacker Signed-off-by: Richard Purdie --- documentation/ref-manual/classes.rst | 11 +++--- documentation/ref-manual/faq.rst | 17 +++++---- documentation/ref-manual/structure.rst | 33 +++++++++--------- documentation/ref-manual/terms.rst | 26 +++++++------- documentation/ref-manual/variables.rst | 63 +++++++++++++++------------------- 5 files changed, 70 insertions(+), 80 deletions(-) (limited to 'documentation/ref-manual') diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index e352abc4d8..3b33783c58 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -1912,10 +1912,10 @@ package-specific classes: You can control the list of resulting package formats by using the :term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf`` configuration file, which is located in the :term:`Build Directory`. -When defining the variable, you can -specify one or more package types. Since images are generated from -packages, a packaging class is needed to enable image generation. The -first class listed in this variable is used for image generation. +When defining the variable, you can specify one or more package types. +Since images are generated from packages, a packaging class is needed +to enable image generation. The first class listed in this variable is +used for image generation. If you take the optional step to set up a repository (package feed) on the development host that can be used by DNF, you can install packages @@ -2401,8 +2401,7 @@ recipe are no longer needed. However, by default, the build system preserves these files for inspection and possible debugging purposes. If you would rather have these files deleted to save disk space as the build progresses, you can enable :ref:`rm_work ` by adding the following to -your ``local.conf`` file, which is found in the :term:`Build Directory`. -:: +your ``local.conf`` file, which is found in the :term:`Build Directory`:: INHERIT += "rm_work" diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst index a570c40e7d..d35ab78bff 100644 --- a/documentation/ref-manual/faq.rst +++ b/documentation/ref-manual/faq.rst @@ -270,7 +270,7 @@ the build environment setup script (i.e. :ref:`structure-core-script`). By default, this :term:`Build Directory` is named ``build`` but can be named anything you want. -Within the Build Directory, is the ``tmp`` directory. To remove all the +Within the :term:`Build Directory`, is the ``tmp`` directory. To remove all the build output yet preserve any source code or downloaded files from previous builds, simply remove the ``tmp`` directory. @@ -381,14 +381,13 @@ system of that image. Thus, the build system provides a value of forth. Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`. -However, when the recipe builds a -native program (i.e. one that is intended to run on the build machine), -that program is never installed directly to the build machine's root -file system. Consequently, the build system uses paths within the Build -Directory for ``DESTDIR``, ``bindir`` and related variables. To better -understand this, consider the following two paths (artificially broken -across lines for readability) where the first is relatively normal and -the second is not:: +However, when the recipe builds a native program (i.e. one that is +intended to run on the build machine), that program is never installed +directly to the build machine's root file system. Consequently, the build +system uses paths within the Build Directory for ``DESTDIR``, ``bindir`` +and related variables. To better understand this, consider the following +two paths (artificially broken across lines for readability) where the +first is relatively normal and the second is not:: /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ 1.2.8-r0/sysroot-destdir/usr/bin diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst index fe27d17caa..8b08f88969 100644 --- a/documentation/ref-manual/structure.rst +++ b/documentation/ref-manual/structure.rst @@ -57,9 +57,8 @@ For more information on BitBake, see the :doc:`BitBake User Manual This directory contains user configuration files and the output generated by the OpenEmbedded build system in its standard configuration where the source tree is combined with the output. The :term:`Build Directory` -is created initially when you ``source`` -the OpenEmbedded build environment setup script (i.e. -:ref:`structure-core-script`). +is created initially when you ``source`` the OpenEmbedded build environment +setup script (i.e. :ref:`structure-core-script`). It is also possible to place output and configuration files in a directory separate from the :term:`Source Directory` by @@ -153,10 +152,10 @@ BitBake commands. The script uses other scripts within the ``scripts`` directory to do the bulk of the work. When you run this script, your Yocto Project environment is set up, a -:term:`Build Directory` is created, your working -directory becomes the Build Directory, and you are presented with some -simple suggestions as to what to do next, including a list of some -possible targets to build. Here is an example:: +:term:`Build Directory` is created, your working directory becomes the +:term:`Build Directory`, and you are presented with some simple +suggestions as to what to do next, including a list of some possible +targets to build. Here is an example:: $ source oe-init-build-env @@ -182,12 +181,13 @@ See the section in the Yocto Project Development Tasks Manual for more information. -By default, running this script without a Build Directory argument +By default, running this script without a :term:`Build Directory` argument creates the ``build/`` directory in your current working directory. If -you provide a Build Directory argument when you ``source`` the script, -you direct the OpenEmbedded build system to create a Build Directory of -your choice. For example, the following command creates a Build -Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:: +you provide a :term:`Build Directory` argument when you ``source`` the script, +you direct the OpenEmbedded build system to create a :term:`Build Directory` of +your choice. For example, the following command creates a +:term:`Build Directory` named ``mybuilds/`` that is outside of the +:term:`Source Directory`:: $ source oe-init-build-env ~/mybuilds @@ -219,11 +219,10 @@ These files are standard top-level files. The Build Directory --- ``build/`` ================================== -The OpenEmbedded build system creates the :term:`Build Directory` -when you run the build environment setup -script :ref:`structure-core-script`. If you do not give the Build -Directory a specific name when you run the setup script, the name -defaults to ``build/``. +The OpenEmbedded build system creates the :term:`Build Directory` when you run +the build environment setup script :ref:`structure-core-script`. If you do not +give the :term:`Build Directory` a specific name when you run the setup script, +the name defaults to ``build/``. For subsequent parsing and processing, the name of the Build directory is available via the :term:`TOPDIR` variable. diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst index ee14df5684..40209528ba 100644 --- a/documentation/ref-manual/terms.rst +++ b/documentation/ref-manual/terms.rst @@ -64,31 +64,31 @@ universal, the list includes them just in case: builds. The area is created when you ``source`` the setup environment script that is found in the Source Directory (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). The - :term:`TOPDIR` variable points to the Build Directory. + :term:`TOPDIR` variable points to the :term:`Build Directory`. - You have a lot of flexibility when creating the Build Directory. + You have a lot of flexibility when creating the :term:`Build Directory`. Following are some examples that show how to create the directory. The examples assume your :term:`Source Directory` is named ``poky``: - - Create the Build Directory inside your Source Directory and let - the name of the Build Directory default to ``build``: + - Create the :term:`Build Directory` inside your Source Directory and let + the name of the :term:`Build Directory` default to ``build``: .. code-block:: shell $ cd poky $ source oe-init-build-env - - Create the Build Directory inside your home directory and + - Create the :term:`Build Directory` inside your home directory and specifically name it ``test-builds``: .. code-block:: shell $ source poky/oe-init-build-env test-builds - - Provide a directory path and specifically name the Build - Directory. Any intermediate folders in the pathname must exist. - This next example creates a Build Directory named - ``YP-&DISTRO;`` within the existing directory ``mybuilds``: + - Provide a directory path and specifically name the + :term:`Build Directory`. Any intermediate folders in the pathname + must exist. This next example creates a :term:`Build Directory` + named ``YP-&DISTRO;`` within the existing directory ``mybuilds``: .. code-block:: shell @@ -96,13 +96,13 @@ universal, the list includes them just in case: .. note:: - By default, the Build Directory contains :term:`TMPDIR`, which is a + By default, the :term:`Build Directory` contains :term:`TMPDIR`, which is a temporary directory the build system uses for its work. :term:`TMPDIR` cannot - be under NFS. Thus, by default, the Build Directory cannot be under - NFS. However, if you need the Build Directory to be under NFS, you can + be under NFS. Thus, by default, the :term:`Build Directory` cannot be under + NFS. However, if you need the :term:`Build Directory` to be under NFS, you can set this up by setting :term:`TMPDIR` in your ``local.conf`` file to use a local drive. Doing so effectively separates :term:`TMPDIR` from :term:`TOPDIR`, which is the - Build Directory. + :term:`Build Directory`. :term:`Build Host` The system used to build images in a Yocto Project Development diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index f8c6e6db1e..dc6eccb314 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -260,9 +260,9 @@ system and gives an overview of their function and contents. https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview :term:`B` - The directory within the :term:`Build Directory` in - which the OpenEmbedded build system places generated objects during a - recipe's build process. By default, this directory is the same as the + The directory within the :term:`Build Directory` in which the + OpenEmbedded build system places generated objects during a recipe's + build process. By default, this directory is the same as the :term:`S` directory, which is defined as:: S = "${WORKDIR}/${BP}" @@ -903,12 +903,11 @@ system and gives an overview of their function and contents. The default value is an empty string (""). :term:`BUILDDIR` - Points to the location of the :term:`Build Directory`. - You can define this directory indirectly through the - :ref:`structure-core-script` script by passing in a Build - Directory path when you run the script. If you run the script and do - not provide a Build Directory path, the :term:`BUILDDIR` defaults to - ``build`` in the current directory. + Points to the location of the :term:`Build Directory`. You can define + this directory indirectly through the :ref:`structure-core-script` script + by passing in a :term:`Build Directory` path when you run the script. If + you run the script and do not provide a :term:`Build Directory` path, the + :term:`BUILDDIR` defaults to ``build`` in the current directory. :term:`BUILDHISTORY_COMMIT` When inheriting the :ref:`buildhistory ` @@ -1712,8 +1711,7 @@ system and gives an overview of their function and contents. Points to the general area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system. By default, this directory - resides within the :term:`Build Directory` as - ``${TMPDIR}/deploy``. + resides within the :term:`Build Directory` as ``${TMPDIR}/deploy``. For more information on the structure of the Build Directory, see ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section. @@ -1759,7 +1757,7 @@ system and gives an overview of their function and contents. with the contents of :term:`IMGDEPLOYDIR` by the :ref:`image ` class. - For more information on the structure of the Build Directory, see + For more information on the structure of the :term:`Build Directory`, see ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section. For more detail on the contents of the ``deploy`` directory, see the ":ref:`overview-manual/concepts:images`" and @@ -2042,8 +2040,7 @@ system and gives an overview of their function and contents. You can set this directory by defining the :term:`DL_DIR` variable in the ``conf/local.conf`` file. This directory is self-maintaining and you should not have to touch it. By default, the directory is - ``downloads`` in the :term:`Build Directory`. - :: + ``downloads`` in the :term:`Build Directory`:: #DL_DIR ?= "${TOPDIR}/downloads" @@ -2264,8 +2261,8 @@ system and gives an overview of their function and contents. class, this variable points to the directory in which the recipe's source code is built, which is outside of the OpenEmbedded build system. When set, this variable sets the :term:`B` variable, - which is what the OpenEmbedded build system uses to locate the Build - Directory. + which is what the OpenEmbedded build system uses to locate the + :term:`Build Directory`. See the ":ref:`ref-classes-externalsrc`" section for details. You can also find information on how to use this variable in the @@ -2285,9 +2282,8 @@ system and gives an overview of their function and contents. more than one feature, separate them with a space. Typically, you configure this variable in your ``local.conf`` file, - which is found in the :term:`Build Directory`. - Although you can use this variable from within a recipe, best - practices dictate that you do not. + which is found in the :term:`Build Directory`. Although you can use this + variable from within a recipe, best practices dictate that you do not. .. note:: @@ -2684,10 +2680,9 @@ system and gives an overview of their function and contents. You define the :term:`FILESYSTEM_PERMS_TABLES` variable in the ``conf/local.conf`` file, which is found in the :term:`Build Directory`, - to point to your custom - ``fs-perms.txt``. You can specify more than a single file permissions - setting table. The paths you specify to these files must be defined - within the :term:`BBPATH` variable. + to point to your custom ``fs-perms.txt``. You can specify more than a + single file permissions setting table. The paths you specify to these + files must be defined within the :term:`BBPATH` variable. For guidance on how to create your own file permissions settings table file, examine the existing ``fs-perms.txt``. @@ -6747,7 +6742,7 @@ system and gives an overview of their function and contents. to find the unpacked source. As an example, assume a :term:`Source Directory` - top-level folder named ``poky`` and a default Build Directory at + top-level folder named ``poky`` and a default :term:`Build Directory` at ``poky/build``. In this case, the work directory the build system uses to keep the unpacked recipe for ``db`` is the following:: @@ -6792,7 +6787,7 @@ system and gives an overview of their function and contents. :term:`SDK_CUSTOM_TEMPLATECONF` When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to - "1" and a ``conf/templateconf.cfg`` file exists in the build directory + "1" and a ``conf/templateconf.cfg`` file exists in the :term:`Build Directory` (:term:`TOPDIR`) then this will be copied into the SDK. :term:`SDK_DEPLOY` @@ -7195,8 +7190,7 @@ system and gives an overview of their function and contents. To enable file removal, set the variable to "1" in your ``conf/local.conf`` configuration file in your: - :term:`Build Directory`. - :: + :term:`Build Directory`:: SKIP_FILEDEPS = "1" @@ -8126,12 +8120,11 @@ system and gives an overview of their function and contents. You can select "glibc", "musl", "newlib", or "baremetal". :term:`TCLIBCAPPEND` - Specifies a suffix to be appended onto the - :term:`TMPDIR` value. The suffix identifies the - ``libc`` variant for building. When you are building for multiple - variants with the same :term:`Build Directory`, this - mechanism ensures that output for different ``libc`` variants is kept - separate to avoid potential conflicts. + Specifies a suffix to be appended onto the :term:`TMPDIR` value. The + suffix identifies the ``libc`` variant for building. When you are + building for multiple variants with the same :term:`Build Directory`, + this mechanism ensures that output for different ``libc`` variants is + kept separate to avoid potential conflicts. In the ``defaultsetup.conf`` file, the default value of :term:`TCLIBCAPPEND` is "-${TCLIBC}". However, distros such as poky, @@ -8419,7 +8412,7 @@ system and gives an overview of their function and contents. #TMPDIR = "${TOPDIR}/tmp" An example use for this scenario is to set :term:`TMPDIR` to a local disk, - which does not use NFS, while having the Build Directory use NFS. + which does not use NFS, while having the :term:`Build Directory` use NFS. The filesystem used by :term:`TMPDIR` must have standard filesystem semantics (i.e. mixed-case files are unique, POSIX file locking, and @@ -9105,7 +9098,7 @@ system and gives an overview of their function and contents. - :term:`PR`: The recipe revision As an example, assume a Source Directory top-level folder name - ``poky``, a default Build Directory at ``poky/build``, and a + ``poky``, a default :term:`Build Directory` at ``poky/build``, and a ``qemux86-poky-linux`` machine target system. Furthermore, suppose your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work directory the build system uses to build the package would be as -- cgit v1.2.3-54-g00ecf