summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/brief-yoctoprojectqs/index.rst12
-rw-r--r--documentation/dev-manual/common-tasks.rst269
-rw-r--r--documentation/dev-manual/qemu.rst12
-rw-r--r--documentation/dev-manual/start.rst4
-rw-r--r--documentation/kernel-dev/common.rst45
-rw-r--r--documentation/kernel-dev/concepts-appx.rst3
-rw-r--r--documentation/kernel-dev/intro.rst4
-rw-r--r--documentation/kernel-dev/maint-appx.rst5
-rw-r--r--documentation/migration-guides/migration-1.5.rst7
-rw-r--r--documentation/migration-guides/migration-1.6.rst4
-rw-r--r--documentation/migration-guides/migration-1.7.rst2
-rw-r--r--documentation/migration-guides/migration-2.6.rst3
-rw-r--r--documentation/migration-guides/migration-general.rst2
-rw-r--r--documentation/overview-manual/concepts.rst74
-rw-r--r--documentation/overview-manual/development-environment.rst8
-rw-r--r--documentation/profile-manual/usage.rst4
-rw-r--r--documentation/ref-manual/classes.rst11
-rw-r--r--documentation/ref-manual/faq.rst17
-rw-r--r--documentation/ref-manual/structure.rst33
-rw-r--r--documentation/ref-manual/terms.rst26
-rw-r--r--documentation/ref-manual/variables.rst63
-rw-r--r--documentation/sdk-manual/appendix-customizing.rst5
-rw-r--r--documentation/sdk-manual/appendix-obtain.rst21
-rw-r--r--documentation/sdk-manual/extensible.rst4
-rw-r--r--documentation/test-manual/understand-autobuilder.rst2
-rw-r--r--documentation/toaster-manual/reference.rst11
-rw-r--r--documentation/toaster-manual/setup-and-use.rst19
27 files changed, 294 insertions, 376 deletions
diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index 100022ceba..d322bbca6b 100644
--- a/documentation/brief-yoctoprojectqs/index.rst
+++ b/documentation/brief-yoctoprojectqs/index.rst
@@ -224,13 +224,13 @@ an entire Linux distribution, including the toolchain, from source.
224 224
225 Among other things, the script creates the :term:`Build Directory`, which is 225 Among other things, the script creates the :term:`Build Directory`, which is
226 ``build`` in this case and is located in the :term:`Source Directory`. After 226 ``build`` in this case and is located in the :term:`Source Directory`. After
227 the script runs, your current working directory is set to the Build 227 the script runs, your current working directory is set to the
228 Directory. Later, when the build completes, the Build Directory contains all the 228 :term:`Build Directory`. Later, when the build completes, the
229 files created during the build. 229 :term:`Build Directory` contains all the files created during the build.
230 230
231#. **Examine Your Local Configuration File:** When you set up the build 231#. **Examine Your Local Configuration File:** When you set up the build
232 environment, a local configuration file named ``local.conf`` becomes 232 environment, a local configuration file named ``local.conf`` becomes
233 available in a ``conf`` subdirectory of the Build Directory. For this 233 available in a ``conf`` subdirectory of the :term:`Build Directory`. For this
234 example, the defaults are set to build for a ``qemux86`` target, 234 example, the defaults are set to build for a ``qemux86`` target,
235 which is suitable for emulation. The package manager used is set to 235 which is suitable for emulation. The package manager used is set to
236 the RPM package manager. 236 the RPM package manager.
@@ -345,9 +345,7 @@ Follow these steps to add a hardware layer:
345 345
346#. **Add Your Layer to the Layer Configuration File:** Before you can use 346#. **Add Your Layer to the Layer Configuration File:** Before you can use
347 a layer during a build, you must add it to your ``bblayers.conf`` 347 a layer during a build, you must add it to your ``bblayers.conf``
348 file, which is found in the 348 file, which is found in the :term:`Build Directory` ``conf`` directory.
349 :term:`Build Directory` ``conf``
350 directory.
351 349
352 Use the ``bitbake-layers add-layer`` command to add the layer to the 350 Use the ``bitbake-layers add-layer`` command to add the layer to the
353 configuration file: 351 configuration file:
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index 189f415c8c..c747c0deac 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -418,10 +418,10 @@ Enabling Your Layer
418Before the OpenEmbedded build system can use your new layer, you need to 418Before the OpenEmbedded build system can use your new layer, you need to
419enable it. To enable your layer, simply add your layer's path to the 419enable it. To enable your layer, simply add your layer's path to the
420:term:`BBLAYERS` variable in your ``conf/bblayers.conf`` file, which is 420:term:`BBLAYERS` variable in your ``conf/bblayers.conf`` file, which is
421found in the :term:`Build Directory`. 421found in the :term:`Build Directory`. The following example shows how to
422The following example shows how to enable your new 422enable your new ``meta-mylayer`` layer (note how your new layer exists
423``meta-mylayer`` layer (note how your new layer exists outside of 423outside of the official ``poky`` repository which you would have checked
424the official ``poky`` repository which you would have checked out earlier):: 424out earlier)::
425 425
426 # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf 426 # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
427 # changes incompatibly 427 # changes incompatibly
@@ -969,8 +969,7 @@ high-level image features by using the
969variables. Although the functions for both variables are nearly 969variables. Although the functions for both variables are nearly
970equivalent, best practices dictate using :term:`IMAGE_FEATURES` from within 970equivalent, best practices dictate using :term:`IMAGE_FEATURES` from within
971a recipe and using :term:`EXTRA_IMAGE_FEATURES` from within your 971a recipe and using :term:`EXTRA_IMAGE_FEATURES` from within your
972``local.conf`` file, which is found in the 972``local.conf`` file, which is found in the :term:`Build Directory`.
973:term:`Build Directory`.
974 973
975To understand how these features work, the best reference is 974To understand how these features work, the best reference is
976:ref:`meta/classes-recipe/image.bbclass <ref-classes-image>`. 975:ref:`meta/classes-recipe/image.bbclass <ref-classes-image>`.
@@ -1206,11 +1205,10 @@ application that builds using Autotools. Creating the base recipe using
1206``recipetool`` results in a recipe that has the pre-build dependencies, 1205``recipetool`` results in a recipe that has the pre-build dependencies,
1207license requirements, and checksums configured. 1206license requirements, and checksums configured.
1208 1207
1209To run the tool, you just need to be in your 1208To run the tool, you just need to be in your :term:`Build Directory` and
1210:term:`Build Directory` and have sourced the 1209have sourced the build environment setup script (i.e.
1211build environment setup script (i.e. 1210:ref:`structure-core-script`). To get help on the tool, use the following
1212:ref:`structure-core-script`). 1211command::
1213To get help on the tool, use the following command::
1214 1212
1215 $ recipetool -h 1213 $ recipetool -h
1216 NOTE: Starting bitbake server... 1214 NOTE: Starting bitbake server...
@@ -1342,8 +1340,7 @@ using BitBake to process the recipe multiple times in order to
1342progressively discover and add information to the recipe file. 1340progressively discover and add information to the recipe file.
1343 1341
1344Assuming you have sourced the build environment setup script (i.e. 1342Assuming you have sourced the build environment setup script (i.e.
1345:ref:`structure-core-script`) and you are in 1343:ref:`structure-core-script`) and you are in the :term:`Build Directory`, use
1346the :term:`Build Directory`, use
1347BitBake to process your recipe. All you need to provide is the 1344BitBake to process your recipe. All you need to provide is the
1348``basename`` of the recipe as described in the previous section:: 1345``basename`` of the recipe as described in the previous section::
1349 1346
@@ -1362,7 +1359,7 @@ is to have BitBake return it by running the following::
1362 $ bitbake -e basename | grep ^WORKDIR= 1359 $ bitbake -e basename | grep ^WORKDIR=
1363 1360
1364As an example, assume a Source Directory 1361As an example, assume a Source Directory
1365top-level folder named ``poky``, a default Build Directory at 1362top-level folder named ``poky``, a default :term:`Build Directory` at
1366``poky/build``, and a ``qemux86-poky-linux`` machine target system. 1363``poky/build``, and a ``qemux86-poky-linux`` machine target system.
1367Furthermore, suppose your recipe is named ``foo_1.3.0.bb``. In this 1364Furthermore, suppose your recipe is named ``foo_1.3.0.bb``. In this
1368case, the work directory the build system uses to build the package 1365case, the work directory the build system uses to build the package
@@ -3017,15 +3014,14 @@ The following steps describe how to set up the AUH utility:
3017 AUH is not part of the :term:`OpenEmbedded-Core (OE-Core)` or 3014 AUH is not part of the :term:`OpenEmbedded-Core (OE-Core)` or
3018 :term:`Poky` repositories. 3015 :term:`Poky` repositories.
3019 3016
30204. *Create a Dedicated Build Directory:* Run the 30174. *Create a Dedicated Build Directory:* Run the :ref:`structure-core-script`
3021 :ref:`structure-core-script` 3018 script to create a fresh :term:`Build Directory` that you use exclusively
3022 script to create a fresh build directory that you use exclusively for 3019 for running the AUH utility::
3023 running the AUH utility::
3024 3020
3025 $ cd poky 3021 $ cd poky
3026 $ source oe-init-build-env your_AUH_build_directory 3022 $ source oe-init-build-env your_AUH_build_directory
3027 3023
3028 Re-using an existing build directory and its configurations is not 3024 Re-using an existing :term:`Build Directory` and its configurations is not
3029 recommended as existing settings could cause AUH to fail or behave 3025 recommended as existing settings could cause AUH to fail or behave
3030 undesirably. 3026 undesirably.
3031 3027
@@ -3045,7 +3041,7 @@ The following steps describe how to set up the AUH utility:
3045 With this configuration and a successful 3041 With this configuration and a successful
3046 upgrade, a build history "diff" file appears in the 3042 upgrade, a build history "diff" file appears in the
3047 ``upgrade-helper/work/recipe/buildhistory-diff.txt`` file found in 3043 ``upgrade-helper/work/recipe/buildhistory-diff.txt`` file found in
3048 your build directory. 3044 your :term:`Build Directory`.
3049 3045
3050 - If you want to enable testing through the 3046 - If you want to enable testing through the
3051 :ref:`testimage <ref-classes-testimage>` 3047 :ref:`testimage <ref-classes-testimage>`
@@ -3070,7 +3066,7 @@ The following steps describe how to set up the AUH utility:
3070 3066
30717. *Create and Edit an AUH Configuration File:* You need to have the 30677. *Create and Edit an AUH Configuration File:* You need to have the
3072 ``upgrade-helper/upgrade-helper.conf`` configuration file in your 3068 ``upgrade-helper/upgrade-helper.conf`` configuration file in your
3073 build directory. You can find a sample configuration file in the 3069 :term:`Build Directory`. You can find a sample configuration file in the
3074 :yocto_git:`AUH source repository </auto-upgrade-helper/tree/>`. 3070 :yocto_git:`AUH source repository </auto-upgrade-helper/tree/>`.
3075 3071
3076 Read through the sample file and make configurations as needed. For 3072 Read through the sample file and make configurations as needed. For
@@ -3118,7 +3114,7 @@ This next set of examples describes how to use the AUH:
3118 $ upgrade-helper.py -e all 3114 $ upgrade-helper.py -e all
3119 3115
3120Once you have run the AUH utility, you can find the results in the AUH 3116Once you have run the AUH utility, you can find the results in the AUH
3121build directory:: 3117:term:`Build Directory`::
3122 3118
3123 ${BUILDDIR}/upgrade-helper/timestamp 3119 ${BUILDDIR}/upgrade-helper/timestamp
3124 3120
@@ -3179,8 +3175,7 @@ example, assume that the layer has been cloned into following area::
3179 3175
3180 /home/scottrif/meta-openembedded 3176 /home/scottrif/meta-openembedded
3181 3177
3182The following command from your 3178The following command from your :term:`Build Directory` adds the layer to
3183:term:`Build Directory` adds the layer to
3184your build configuration (i.e. ``${BUILDDIR}/conf/bblayers.conf``):: 3179your build configuration (i.e. ``${BUILDDIR}/conf/bblayers.conf``)::
3185 3180
3186 $ bitbake-layers add-layer /home/scottrif/meta-openembedded/meta-oe 3181 $ bitbake-layers add-layer /home/scottrif/meta-openembedded/meta-oe
@@ -3341,16 +3336,14 @@ source code used by recipes to build packages. For example, suppose you
3341are developing a patch and you need to experiment a bit to figure out 3336are developing a patch and you need to experiment a bit to figure out
3342your solution. After you have initially built the package, you can 3337your solution. After you have initially built the package, you can
3343iteratively tweak the source code, which is located in the 3338iteratively tweak the source code, which is located in the
3344:term:`Build Directory`, and then you can 3339:term:`Build Directory`, and then you can force a re-compile and quickly
3345force a re-compile and quickly test your altered code. Once you settle 3340test your altered code. Once you settle on a solution, you can then preserve
3346on a solution, you can then preserve your changes in the form of 3341your changes in the form of patches.
3347patches.
3348 3342
3349During a build, the unpacked temporary source code used by recipes to 3343During a build, the unpacked temporary source code used by recipes to
3350build packages is available in the Build Directory as defined by the 3344build packages is available in the :term:`Build Directory` as defined by the
3351:term:`S` variable. Below is the default 3345:term:`S` variable. Below is the default value for the :term:`S` variable as
3352value for the :term:`S` variable as defined in the 3346defined in the ``meta/conf/bitbake.conf`` configuration file in the
3353``meta/conf/bitbake.conf`` configuration file in the
3354:term:`Source Directory`:: 3347:term:`Source Directory`::
3355 3348
3356 S = "${WORKDIR}/${BP}" 3349 S = "${WORKDIR}/${BP}"
@@ -3392,7 +3385,7 @@ The actual directory depends on several things:
3392- :term:`PR`: The recipe revision. 3385- :term:`PR`: The recipe revision.
3393 3386
3394As an example, assume a Source Directory top-level folder named 3387As an example, assume a Source Directory top-level folder named
3395``poky``, a default Build Directory at ``poky/build``, and a 3388``poky``, a default :term:`Build Directory` at ``poky/build``, and a
3396``qemux86-poky-linux`` machine target system. Furthermore, suppose your 3389``qemux86-poky-linux`` machine target system. Furthermore, suppose your
3397recipe is named ``foo_1.3.0.bb``. In this case, the work directory the 3390recipe is named ``foo_1.3.0.bb``. In this case, the work directory the
3398build system uses to build the package would be as follows:: 3391build system uses to build the package would be as follows::
@@ -3420,8 +3413,7 @@ form of a patch all using Quilt.
3420Follow these general steps: 3413Follow these general steps:
3421 3414
34221. *Find the Source Code:* Temporary source code used by the 34151. *Find the Source Code:* Temporary source code used by the
3423 OpenEmbedded build system is kept in the 3416 OpenEmbedded build system is kept in the :term:`Build Directory`. See the
3424 :term:`Build Directory`. See the
3425 ":ref:`dev-manual/common-tasks:finding temporary source code`" section to 3417 ":ref:`dev-manual/common-tasks:finding temporary source code`" section to
3426 learn how to locate the directory that has the temporary source code for a 3418 learn how to locate the directory that has the temporary source code for a
3427 particular package. 3419 particular package.
@@ -3649,10 +3641,10 @@ build host running Linux.
3649 :doc:`/brief-yoctoprojectqs/index` document. 3641 :doc:`/brief-yoctoprojectqs/index` document.
3650 3642
3651The build process creates an entire Linux distribution from source and 3643The build process creates an entire Linux distribution from source and
3652places it in your :term:`Build Directory` under 3644places it in your :term:`Build Directory` under ``tmp/deploy/images``. For
3653``tmp/deploy/images``. For detailed information on the build process 3645detailed information on the build process using BitBake, see the
3654using BitBake, see the ":ref:`overview-manual/concepts:images`" section in the 3646":ref:`overview-manual/concepts:images`" section in the Yocto Project Overview
3655Yocto Project Overview and Concepts Manual. 3647and Concepts Manual.
3656 3648
3657The following figure and list overviews the build process: 3649The following figure and list overviews the build process:
3658 3650
@@ -3672,25 +3664,23 @@ The following figure and list overviews the build process:
3672 When you use the initialization script, the OpenEmbedded build system 3664 When you use the initialization script, the OpenEmbedded build system
3673 uses ``build`` as the default :term:`Build Directory` in your current work 3665 uses ``build`` as the default :term:`Build Directory` in your current work
3674 directory. You can use a `build_dir` argument with the script to 3666 directory. You can use a `build_dir` argument with the script to
3675 specify a different build directory. 3667 specify a different :term:`Build Directory`.
3676 3668
3677 .. note:: 3669 .. note::
3678 3670
3679 A common practice is to use a different Build Directory for 3671 A common practice is to use a different :term:`Build Directory` for
3680 different targets; for example, ``~/build/x86`` for a ``qemux86`` 3672 different targets; for example, ``~/build/x86`` for a ``qemux86``
3681 target, and ``~/build/arm`` for a ``qemuarm`` target. In any 3673 target, and ``~/build/arm`` for a ``qemuarm`` target. In any
3682 event, it's typically cleaner to locate the build directory 3674 event, it's typically cleaner to locate the :term:`Build Directory`
3683 somewhere outside of your source directory. 3675 somewhere outside of your source directory.
3684 3676
36853. *Make Sure Your* ``local.conf`` *File is Correct*: Ensure the 36773. *Make Sure Your* ``local.conf`` *File is Correct*: Ensure the
3686 ``conf/local.conf`` configuration file, which is found in the Build 3678 ``conf/local.conf`` configuration file, which is found in the
3687 Directory, is set up how you want it. This file defines many aspects 3679 :term:`Build Directory`, is set up how you want it. This file defines many
3688 of the build environment including the target machine architecture 3680 aspects of the build environment including the target machine architecture
3689 through the :term:`MACHINE` variable, the packaging format used during 3681 through the :term:`MACHINE` variable, the packaging format used during
3690 the build 3682 the build (:term:`PACKAGE_CLASSES`), and a centralized tarball download
3691 (:term:`PACKAGE_CLASSES`), 3683 directory through the :term:`DL_DIR` variable.
3692 and a centralized tarball download directory through the
3693 :term:`DL_DIR` variable.
3694 3684
36954. *Build the Image:* Build the image using the ``bitbake`` command:: 36854. *Build the Image:* Build the image using the ``bitbake`` command::
3696 3686
@@ -3718,7 +3708,7 @@ The following figure and list overviews the build process:
3718 Once an 3708 Once an
3719 image has been built, it often needs to be installed. The images and 3709 image has been built, it often needs to be installed. The images and
3720 kernels built by the OpenEmbedded build system are placed in the 3710 kernels built by the OpenEmbedded build system are placed in the
3721 Build Directory in ``tmp/deploy/images``. For information on how to 3711 :term:`Build Directory` in ``tmp/deploy/images``. For information on how to
3722 run pre-built images such as ``qemux86`` and ``qemuarm``, see the 3712 run pre-built images such as ``qemux86`` and ``qemuarm``, see the
3723 :doc:`/sdk-manual/index` manual. For 3713 :doc:`/sdk-manual/index` manual. For
3724 information about how to install these images, see the documentation 3714 information about how to install these images, see the documentation
@@ -3772,7 +3762,7 @@ Follow these steps to set up and execute multiple configuration builds:
3772 TMPDIR = "${TOPDIR}/tmpmultix86" 3762 TMPDIR = "${TOPDIR}/tmpmultix86"
3773 3763
3774 The location for these multiconfig configuration files is specific. 3764 The location for these multiconfig configuration files is specific.
3775 They must reside in the current build directory in a sub-directory of 3765 They must reside in the current :term:`Build Directory` in a sub-directory of
3776 ``conf`` named ``multiconfig`` or within a layer's ``conf`` directory 3766 ``conf`` named ``multiconfig`` or within a layer's ``conf`` directory
3777 under a directory named ``multiconfig``. Following is an example that defines 3767 under a directory named ``multiconfig``. Following is an example that defines
3778 two configuration files for the "x86" and "arm" multiconfigs: 3768 two configuration files for the "x86" and "arm" multiconfigs:
@@ -4275,15 +4265,13 @@ If build speed and package feed maintenance are considerations, you
4275should consider the points in this section that can help you optimize 4265should consider the points in this section that can help you optimize
4276your tunings to best consider build times and package feed maintenance. 4266your tunings to best consider build times and package feed maintenance.
4277 4267
4278- *Share the Build Directory:* If at all possible, share the 4268- *Share the :term:`Build Directory`:* If at all possible, share the
4279 :term:`TMPDIR` across builds. The 4269 :term:`TMPDIR` across builds. The Yocto Project supports switching between
4280 Yocto Project supports switching between different 4270 different :term:`MACHINE` values in the same :term:`TMPDIR`. This practice
4281 :term:`MACHINE` values in the same 4271 is well supported and regularly used by developers when building for
4282 :term:`TMPDIR`. This practice is well supported and regularly used by 4272 multiple machines. When you use the same :term:`TMPDIR` for multiple
4283 developers when building for multiple machines. When you use the same 4273 machine builds, the OpenEmbedded build system can reuse the existing native
4284 :term:`TMPDIR` for multiple machine builds, the OpenEmbedded build system 4274 and often cross-recipes for multiple machines. Thus, build time decreases.
4285 can reuse the existing native and often cross-recipes for multiple
4286 machines. Thus, build time decreases.
4287 4275
4288 .. note:: 4276 .. note::
4289 4277
@@ -4399,10 +4387,10 @@ your tunings to best consider build times and package feed maintenance.
4399Building Software from an External Source 4387Building Software from an External Source
4400----------------------------------------- 4388-----------------------------------------
4401 4389
4402By default, the OpenEmbedded build system uses the 4390By default, the OpenEmbedded build system uses the :term:`Build Directory`
4403:term:`Build Directory` when building source 4391when building source code. The build process involves fetching the source
4404code. The build process involves fetching the source files, unpacking 4392files, unpacking them, and then patching them if necessary before the build
4405them, and then patching them if necessary before the build takes place. 4393takes place.
4406 4394
4407There are situations where you might want to build software from source 4395There are situations where you might want to build software from source
4408files that are external to and thus outside of the OpenEmbedded build 4396files that are external to and thus outside of the OpenEmbedded build
@@ -4519,9 +4507,8 @@ directory:
4519 from your "own-mirror" are used. 4507 from your "own-mirror" are used.
4520 4508
45212. *Start With a Clean Build:* You can start with a clean build by 45092. *Start With a Clean Build:* You can start with a clean build by
4522 removing the 4510 removing the ``${``\ :term:`TMPDIR`\ ``}`` directory or using a new
4523 ``${``\ :term:`TMPDIR`\ ``}`` 4511 :term:`Build Directory`.
4524 directory or using a new :term:`Build Directory`.
4525 4512
45263. *Build Your Target:* Use BitBake to build your target:: 45133. *Build Your Target:* Use BitBake to build your target::
4527 4514
@@ -4622,8 +4609,7 @@ Following are additional factors that can affect build speed:
4622 the benefits are limited due to the compiler using ``-pipe``. The 4609 the benefits are limited due to the compiler using ``-pipe``. The
4623 build system goes to some lengths to avoid ``sync()`` calls into the 4610 build system goes to some lengths to avoid ``sync()`` calls into the
4624 file system on the principle that if there was a significant failure, 4611 file system on the principle that if there was a significant failure,
4625 the :term:`Build Directory` 4612 the :term:`Build Directory` contents could easily be rebuilt.
4626 contents could easily be rebuilt.
4627 4613
4628- Inheriting the 4614- Inheriting the
4629 :ref:`rm_work <ref-classes-rm-work>` class: 4615 :ref:`rm_work <ref-classes-rm-work>` class:
@@ -4820,8 +4806,7 @@ Using Multilib
4820After you have set up the recipes, you need to define the actual 4806After you have set up the recipes, you need to define the actual
4821combination of multiple libraries you want to build. You accomplish this 4807combination of multiple libraries you want to build. You accomplish this
4822through your ``local.conf`` configuration file in the 4808through your ``local.conf`` configuration file in the
4823:term:`Build Directory`. An example 4809:term:`Build Directory`. An example configuration would be as follows::
4824configuration would be as follows::
4825 4810
4826 MACHINE = "qemux86-64" 4811 MACHINE = "qemux86-64"
4827 require conf/multilib.conf 4812 require conf/multilib.conf
@@ -4871,10 +4856,9 @@ Here are the implementation details for the RPM Package Management System:
4871 4856
4872- A unique architecture is defined for the Multilib packages, along 4857- A unique architecture is defined for the Multilib packages, along
4873 with creating a unique deploy folder under ``tmp/deploy/rpm`` in the 4858 with creating a unique deploy folder under ``tmp/deploy/rpm`` in the
4874 :term:`Build Directory`. For 4859 :term:`Build Directory`. For example, consider ``lib32`` in a
4875 example, consider ``lib32`` in a ``qemux86-64`` image. The possible 4860 ``qemux86-64`` image. The possible architectures in the system are "all",
4876 architectures in the system are "all", "qemux86_64", 4861 "qemux86_64", "lib32:qemux86_64", and "lib32:x86".
4877 "lib32:qemux86_64", and "lib32:x86".
4878 4862
4879- The ``${MLPREFIX}`` variable is stripped from ``${PN}`` during RPM 4863- The ``${MLPREFIX}`` variable is stripped from ``${PN}`` during RPM
4880 packaging. The naming for a normal RPM package and a Multilib RPM 4864 packaging. The naming for a normal RPM package and a Multilib RPM
@@ -5460,8 +5444,7 @@ system needs to meet the following requirements:
5460 your development host system. 5444 your development host system.
5461 5445
5462- You must have sourced the build environment setup script (i.e. 5446- You must have sourced the build environment setup script (i.e.
5463 :ref:`structure-core-script`) found in the 5447 :ref:`structure-core-script`) found in the :term:`Build Directory`.
5464 :term:`Build Directory`.
5465 5448
5466- You need to have the build artifacts already available, which 5449- You need to have the build artifacts already available, which
5467 typically means that you must have already created an image using the 5450 typically means that you must have already created an image using the
@@ -5569,11 +5552,10 @@ Raw Mode
5569 5552
5570Running Wic in raw mode allows you to specify all the partitions through 5553Running Wic in raw mode allows you to specify all the partitions through
5571the ``wic`` command line. The primary use for raw mode is if you have 5554the ``wic`` command line. The primary use for raw mode is if you have
5572built your kernel outside of the Yocto Project 5555built your kernel outside of the Yocto Project :term:`Build Directory`.
5573:term:`Build Directory`. In other words, you 5556In other words, you can point to arbitrary kernel, root filesystem locations,
5574can point to arbitrary kernel, root filesystem locations, and so forth. 5557and so forth. Contrast this behavior with cooked mode where Wic looks in the
5575Contrast this behavior with cooked mode where Wic looks in the Build 5558:term:`Build Directory` (e.g. ``tmp/deploy/images/``\ machine).
5576Directory (e.g. ``tmp/deploy/images/``\ machine).
5577 5559
5578The general form of the ``wic`` command in raw mode is:: 5560The general form of the ``wic`` command in raw mode is::
5579 5561
@@ -5626,11 +5608,11 @@ The general form of the ``wic`` command in raw mode is::
5626Cooked Mode 5608Cooked Mode
5627~~~~~~~~~~~ 5609~~~~~~~~~~~
5628 5610
5629Running Wic in cooked mode leverages off artifacts in the Build 5611Running Wic in cooked mode leverages off artifacts in the
5630Directory. In other words, you do not have to specify kernel or root 5612:term:`Build Directory`. In other words, you do not have to specify kernel or
5631filesystem locations as part of the command. All you need to provide is 5613root filesystem locations as part of the command. All you need to provide is
5632a kickstart file and the name of the image from which to use artifacts 5614a kickstart file and the name of the image from which to use artifacts
5633by using the "-e" option. Wic looks in the Build Directory (e.g. 5615by using the "-e" option. Wic looks in the :term:`Build Directory` (e.g.
5634``tmp/deploy/images/``\ machine) for artifacts. 5616``tmp/deploy/images/``\ machine) for artifacts.
5635 5617
5636The general form of the ``wic`` command using Cooked Mode is as follows:: 5618The general form of the ``wic`` command using Cooked Mode is as follows::
@@ -5878,9 +5860,9 @@ and kickstart file information.
5878 You should always verify the details provided in the output to make 5860 You should always verify the details provided in the output to make
5879 sure that the image was indeed created exactly as expected. 5861 sure that the image was indeed created exactly as expected.
5880 5862
5881Continuing with the example, you can now write the image from the Build 5863Continuing with the example, you can now write the image from the
5882Directory onto a USB stick, or whatever media for which you built your 5864:term:`Build Directory` onto a USB stick, or whatever media for which you
5883image, and boot from the media. You can write the image by using 5865built your image, and boot from the media. You can write the image by using
5884``bmaptool`` or ``dd``:: 5866``bmaptool`` or ``dd``::
5885 5867
5886 $ oe-run-native bmap-tools-native bmaptool copy mkefidisk-201804191017-sda.direct /dev/sdX 5868 $ oe-run-native bmap-tools-native bmaptool copy mkefidisk-201804191017-sda.direct /dev/sdX
@@ -6152,7 +6134,7 @@ any type of image. Use these steps to flash an image using Bmaptool:
6152 6134
61533. *Flash the Device:* Flash the device with the image by using Bmaptool 61353. *Flash the Device:* Flash the device with the image by using Bmaptool
6154 depending on your particular setup. The following commands assume the 6136 depending on your particular setup. The following commands assume the
6155 image resides in the Build Directory's ``deploy/images/`` area: 6137 image resides in the :term:`Build Directory`'s ``deploy/images/`` area:
6156 6138
6157 - If you have write access to the media, use this command form:: 6139 - If you have write access to the media, use this command form::
6158 6140
@@ -6399,11 +6381,9 @@ layer. The following steps provide some more detail:
6399 variable from the ``local.conf`` file. The variables you use are not 6381 variable from the ``local.conf`` file. The variables you use are not
6400 limited to the list in the previous bulleted item. 6382 limited to the list in the previous bulleted item.
6401 6383
6402- *Point to Your distribution configuration file:* In your 6384- *Point to Your distribution configuration file:* In your ``local.conf``
6403 ``local.conf`` file in the :term:`Build Directory`, 6385 file in the :term:`Build Directory`, set your :term:`DISTRO` variable to
6404 set your 6386 point to your distribution's configuration file. For example, if your
6405 :term:`DISTRO` variable to point to
6406 your distribution's configuration file. For example, if your
6407 distribution's configuration file is named ``mydistro.conf``, then 6387 distribution's configuration file is named ``mydistro.conf``, then
6408 you point to it as follows:: 6388 you point to it as follows::
6409 6389
@@ -6438,7 +6418,7 @@ Creating a Custom Template Configuration Directory
6438If you are producing your own customized version of the build system for 6418If you are producing your own customized version of the build system for
6439use by other users, you might want to provide a custom build configuration 6419use by other users, you might want to provide a custom build configuration
6440that includes all the necessary settings and layers (i.e. ``local.conf`` and 6420that includes all the necessary settings and layers (i.e. ``local.conf`` and
6441``bblayers.conf`` that are created in a new build directory) and a custom 6421``bblayers.conf`` that are created in a new :term:`Build Directory`) and a custom
6442message that is shown when setting up the build. This can be done by 6422message that is shown when setting up the build. This can be done by
6443creating one or more template configuration directories in your 6423creating one or more template configuration directories in your
6444custom distribution layer. 6424custom distribution layer.
@@ -6452,7 +6432,7 @@ This can be done by using ``bitbake-layers save-build-conf``::
6452 You can try out the configuration with 6432 You can try out the configuration with
6453 TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . /srv/work/alex/poky/oe-init-build-env build-try-test-1 6433 TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . /srv/work/alex/poky/oe-init-build-env build-try-test-1
6454 6434
6455The above command takes the config files from the currently active build directory under ``conf``, 6435The above command takes the config files from the currently active :term:`Build Directory` under ``conf``,
6456replaces site-specific paths in ``bblayers.conf`` with ``##OECORE##``-relative paths, and copies 6436replaces site-specific paths in ``bblayers.conf`` with ``##OECORE##``-relative paths, and copies
6457the config files into a specified layer under a specified template name. 6437the config files into a specified layer under a specified template name.
6458 6438
@@ -6684,10 +6664,9 @@ generated are just "self consistent". The build system adds and removes
6684packages and there are no guarantees about upgrade paths but images will 6664packages and there are no guarantees about upgrade paths but images will
6685be consistent and correct with the latest changes. 6665be consistent and correct with the latest changes.
6686 6666
6687The simplest form for a PR Service is for a single host 6667The simplest form for a PR Service is for a single host development system
6688development system that builds the package feed (building system). For 6668that builds the package feed (building system). For this scenario, you can
6689this scenario, you can enable a local PR Service by setting 6669enable a local PR Service by setting :term:`PRSERV_HOST` in your
6690:term:`PRSERV_HOST` in your
6691``local.conf`` file in the :term:`Build Directory`:: 6670``local.conf`` file in the :term:`Build Directory`::
6692 6671
6693 PRSERV_HOST = "localhost:0" 6672 PRSERV_HOST = "localhost:0"
@@ -7043,7 +7022,7 @@ machine does not necessarily have to be the package server. The build
7043machine could push its artifacts to another machine that acts as the 7022machine could push its artifacts to another machine that acts as the
7044server (e.g. Internet-facing). In fact, doing so is advantageous for a 7023server (e.g. Internet-facing). In fact, doing so is advantageous for a
7045production environment as getting the packages away from the development 7024production environment as getting the packages away from the development
7046system's build directory prevents accidental overwrites. 7025system's :term:`Build Directory` prevents accidental overwrites.
7047 7026
7048A simple build that targets just one device produces more than one 7027A simple build that targets just one device produces more than one
7049package database. In other words, the packages produced by a build are 7028package database. In other words, the packages produced by a build are
@@ -7075,8 +7054,7 @@ to use. In your configuration, you use the
7075:term:`PACKAGE_CLASSES` 7054:term:`PACKAGE_CLASSES`
7076variable to specify the format: 7055variable to specify the format:
7077 7056
70781. Open the ``local.conf`` file inside your 70571. Open the ``local.conf`` file inside your :term:`Build Directory` (e.g.
7079 :term:`Build Directory` (e.g.
7080 ``poky/build/conf/local.conf``). 7058 ``poky/build/conf/local.conf``).
7081 7059
70822. Select the desired package format as follows:: 70602. Select the desired package format as follows::
@@ -7162,12 +7140,10 @@ environment, the setup is simple and straight forward. Should you want
7162to use a different server more suited for production (e.g. Apache 2, 7140to use a different server more suited for production (e.g. Apache 2,
7163Lighttpd, or Nginx), take the appropriate steps to do so. 7141Lighttpd, or Nginx), take the appropriate steps to do so.
7164 7142
7165From within the build directory where you have built an image based on 7143From within the :term:`Build Directory` where you have built an image based on
7166your packaging choice (i.e. the 7144your packaging choice (i.e. the :term:`PACKAGE_CLASSES` setting), simply start
7167:term:`PACKAGE_CLASSES` 7145the server. The following example assumes a :term:`Build Directory` of ``poky/build``
7168setting), simply start the server. The following example assumes a build 7146and a :term:`PACKAGE_CLASSES` setting of "package_rpm"::
7169directory of ``poky/build/tmp/deploy/rpm`` and a :term:`PACKAGE_CLASSES`
7170setting of "package_rpm"::
7171 7147
7172 $ cd poky/build/tmp/deploy/rpm 7148 $ cd poky/build/tmp/deploy/rpm
7173 $ python3 -m http.server 7149 $ python3 -m http.server
@@ -7439,11 +7415,9 @@ see the :yocto_wiki:`Ptest </Ptest>` wiki page.
7439Adding ptest to Your Build 7415Adding ptest to Your Build
7440~~~~~~~~~~~~~~~~~~~~~~~~~~ 7416~~~~~~~~~~~~~~~~~~~~~~~~~~
7441 7417
7442To add package testing to your build, add the 7418To add package testing to your build, add the :term:`DISTRO_FEATURES` and
7443:term:`DISTRO_FEATURES` and 7419:term:`EXTRA_IMAGE_FEATURES` variables to your ``local.conf`` file, which
7444:term:`EXTRA_IMAGE_FEATURES` 7420is found in the :term:`Build Directory`::
7445variables to your ``local.conf`` file, which is found in the
7446:term:`Build Directory`::
7447 7421
7448 DISTRO_FEATURES:append = " ptest" 7422 DISTRO_FEATURES:append = " ptest"
7449 EXTRA_IMAGE_FEATURES += "ptest-pkgs" 7423 EXTRA_IMAGE_FEATURES += "ptest-pkgs"
@@ -8093,7 +8067,7 @@ image's recipe file via the :term:`IMAGE_FEATURES` variable::
8093 IMAGE_FEATURES += "read-only-rootfs" 8067 IMAGE_FEATURES += "read-only-rootfs"
8094 8068
8095As an alternative, you can add the same feature 8069As an alternative, you can add the same feature
8096from within your build directory's ``local.conf`` file with the 8070from within your :term:`Build Directory`'s ``local.conf`` file with the
8097associated :term:`EXTRA_IMAGE_FEATURES` variable, as in:: 8071associated :term:`EXTRA_IMAGE_FEATURES` variable, as in::
8098 8072
8099 EXTRA_IMAGE_FEATURES = "read-only-rootfs" 8073 EXTRA_IMAGE_FEATURES = "read-only-rootfs"
@@ -8188,9 +8162,8 @@ Enabling and Disabling Build History
8188------------------------------------ 8162------------------------------------
8189 8163
8190Build history is disabled by default. To enable it, add the following 8164Build history is disabled by default. To enable it, add the following
8191:term:`INHERIT` statement and set the 8165:term:`INHERIT` statement and set the :term:`BUILDHISTORY_COMMIT` variable to
8192:term:`BUILDHISTORY_COMMIT` 8166"1" at the end of your ``conf/local.conf`` file found in the
8193variable to "1" at the end of your ``conf/local.conf`` file found in the
8194:term:`Build Directory`:: 8167:term:`Build Directory`::
8195 8168
8196 INHERIT += "buildhistory" 8169 INHERIT += "buildhistory"
@@ -8213,10 +8186,8 @@ your ``conf/local.conf`` file.
8213Understanding What the Build History Contains 8186Understanding What the Build History Contains
8214--------------------------------------------- 8187---------------------------------------------
8215 8188
8216Build history information is kept in 8189Build history information is kept in ``${``\ :term:`TOPDIR`\ ``}/buildhistory``
8217``${``\ :term:`TOPDIR`\ ``}/buildhistory`` 8190in the :term:`Build Directory` as defined by the :term:`BUILDHISTORY_DIR`
8218in the Build Directory as defined by the
8219:term:`BUILDHISTORY_DIR`
8220variable. Here is an example abbreviated listing: 8191variable. Here is an example abbreviated listing:
8221 8192
8222.. image:: figures/buildhistory.png 8193.. image:: figures/buildhistory.png
@@ -8883,11 +8854,9 @@ Running Tests
8883 8854
8884You can start the tests automatically or manually: 8855You can start the tests automatically or manually:
8885 8856
8886- *Automatically running tests:* To run the tests automatically after 8857- *Automatically running tests:* To run the tests automatically after the
8887 the OpenEmbedded build system successfully creates an image, first 8858 OpenEmbedded build system successfully creates an image, first set the
8888 set the 8859 :term:`TESTIMAGE_AUTO` variable to "1" in your ``local.conf`` file in the
8889 :term:`TESTIMAGE_AUTO`
8890 variable to "1" in your ``local.conf`` file in the
8891 :term:`Build Directory`:: 8860 :term:`Build Directory`::
8892 8861
8893 TESTIMAGE_AUTO = "1" 8862 TESTIMAGE_AUTO = "1"
@@ -8982,10 +8951,9 @@ following BitBake command form::
8982 8951
8983 $ bitbake image -c testexport 8952 $ bitbake image -c testexport
8984 8953
8985Exporting the tests places them in the 8954Exporting the tests places them in the :term:`Build Directory` in
8986:term:`Build Directory` in 8955``tmp/testexport/``\ image, which is controlled by the :term:`TEST_EXPORT_DIR`
8987``tmp/testexport/``\ image, which is controlled by the 8956variable.
8988:term:`TEST_EXPORT_DIR` variable.
8989 8957
8990You can now run the tests outside of the build environment:: 8958You can now run the tests outside of the build environment::
8991 8959
@@ -9212,9 +9180,8 @@ section:
9212 9180
9213- ":ref:`dev-manual/common-tasks:viewing task variable dependencies`" describes 9181- ":ref:`dev-manual/common-tasks:viewing task variable dependencies`" describes
9214 how to use the ``bitbake-dumpsig`` command in conjunction with key 9182 how to use the ``bitbake-dumpsig`` command in conjunction with key
9215 subdirectories in the 9183 subdirectories in the :term:`Build Directory` to determine variable
9216 :term:`Build Directory` to determine 9184 dependencies.
9217 variable dependencies.
9218 9185
9219- ":ref:`dev-manual/common-tasks:running specific tasks`" describes 9186- ":ref:`dev-manual/common-tasks:running specific tasks`" describes
9220 how to use several BitBake options (e.g. ``-c``, ``-C``, and ``-f``) 9187 how to use several BitBake options (e.g. ``-c``, ``-C``, and ``-f``)
@@ -10363,13 +10330,11 @@ Here are some other tips that you might find useful:
10363 is also possible to switch out of the splashscreen by switching the 10330 is also possible to switch out of the splashscreen by switching the
10364 virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). 10331 virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
10365 10332
10366- Removing :term:`TMPDIR` (usually 10333- Removing :term:`TMPDIR` (usually ``tmp/``, within the
10367 ``tmp/``, within the 10334 :term:`Build Directory`) can often fix temporary build issues. Removing
10368 :term:`Build Directory`) can often fix 10335 :term:`TMPDIR` is usually a relatively cheap operation, because task output
10369 temporary build issues. Removing :term:`TMPDIR` is usually a relatively 10336 will be cached in :term:`SSTATE_DIR` (usually ``sstate-cache/``, which is
10370 cheap operation, because task output will be cached in 10337 also in the :term:`Build Directory`).
10371 :term:`SSTATE_DIR` (usually
10372 ``sstate-cache/``, which is also in the Build Directory).
10373 10338
10374 .. note:: 10339 .. note::
10375 10340
@@ -10383,8 +10348,8 @@ Here are some other tips that you might find useful:
10383 10348
10384 Using GNU Grep, you can use the following shell function to 10349 Using GNU Grep, you can use the following shell function to
10385 recursively search through common recipe-related files, skipping 10350 recursively search through common recipe-related files, skipping
10386 binary files, ``.git`` directories, and the Build Directory (assuming 10351 binary files, ``.git`` directories, and the :term:`Build Directory`
10387 its name starts with "build"):: 10352 (assuming its name starts with "build")::
10388 10353
10389 g() { 10354 g() {
10390 grep -Ir \ 10355 grep -Ir \
@@ -11282,8 +11247,7 @@ of compliance in mind.
11282 11247
11283One way of doing this (but certainly not the only way) is to release 11248One way of doing this (but certainly not the only way) is to release
11284just the source as a tarball. You can do this by adding the following to 11249just the source as a tarball. You can do this by adding the following to
11285the ``local.conf`` file found in the 11250the ``local.conf`` file found in the :term:`Build Directory`::
11286:term:`Build Directory`::
11287 11251
11288 INHERIT += "archiver" 11252 INHERIT += "archiver"
11289 ARCHIVER_MODE[src] = "original" 11253 ARCHIVER_MODE[src] = "original"
@@ -11442,9 +11406,9 @@ this function, you have to follow the following steps:
11442 11406
114433. Meta-spdxscanner provides several methods within the bbclass to create spdx files. 114073. Meta-spdxscanner provides several methods within the bbclass to create spdx files.
11444 Please choose one that you want to use and enable the spdx task. You have to 11408 Please choose one that you want to use and enable the spdx task. You have to
11445 add some config options in ``local.conf`` file in your :term:`Build 11409 add some config options in ``local.conf`` file in your :term:`Build Directory`.
11446 Directory`. Here is an example showing how to generate spdx files 11410 Here is an example showing how to generate spdx files during BitBake using the
11447 during BitBake using the fossology-python.bbclass:: 11411 fossology-python.bbclass::
11448 11412
11449 # Select fossology-python.bbclass. 11413 # Select fossology-python.bbclass.
11450 INHERIT += "fossology-python" 11414 INHERIT += "fossology-python"
@@ -11737,12 +11701,9 @@ Enabling and Using the Tool
11737--------------------------- 11701---------------------------
11738 11702
11739By default, the error reporting tool is disabled. You can enable it by 11703By default, the error reporting tool is disabled. You can enable it by
11740inheriting the 11704inheriting the :ref:`report-error <ref-classes-report-error>`
11741:ref:`report-error <ref-classes-report-error>`
11742class by adding the following statement to the end of your 11705class by adding the following statement to the end of your
11743``local.conf`` file in your 11706``local.conf`` file in your :term:`Build Directory`::
11744:term:`Build Directory`.
11745::
11746 11707
11747 INHERIT += "report-error" 11708 INHERIT += "report-error"
11748 11709
diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst
index 9f4bc264a3..5a4a82ce6f 100644
--- a/documentation/dev-manual/qemu.rst
+++ b/documentation/dev-manual/qemu.rst
@@ -99,8 +99,7 @@ available. Follow these general steps to run QEMU:
99 Here are some additional examples to help illustrate further QEMU: 99 Here are some additional examples to help illustrate further QEMU:
100 100
101 - This example starts QEMU with MACHINE set to "qemux86-64". 101 - This example starts QEMU with MACHINE set to "qemux86-64".
102 Assuming a standard 102 Assuming a standard :term:`Build Directory`, ``runqemu``
103 :term:`Build Directory`, ``runqemu``
104 automatically finds the ``bzImage-qemux86-64.bin`` image file and 103 automatically finds the ``bzImage-qemux86-64.bin`` image file and
105 the ``core-image-minimal-qemux86-64-20200218002850.rootfs.ext4`` 104 the ``core-image-minimal-qemux86-64-20200218002850.rootfs.ext4``
106 (assuming the current build created a ``core-image-minimal`` 105 (assuming the current build created a ``core-image-minimal``
@@ -246,11 +245,10 @@ be a problem when QEMU is running with KVM enabled. Specifically,
246software compiled with a certain CPU feature crashes when run on a CPU 245software compiled with a certain CPU feature crashes when run on a CPU
247under KVM that does not support that feature. To work around this 246under KVM that does not support that feature. To work around this
248problem, you can override QEMU's runtime CPU setting by changing the 247problem, you can override QEMU's runtime CPU setting by changing the
249``QB_CPU_KVM`` variable in ``qemuboot.conf`` in the 248``QB_CPU_KVM`` variable in ``qemuboot.conf`` in the :term:`Build Directory`
250:term:`Build Directory` ``deploy/image`` 249``deploy/image`` directory. This setting specifies a ``-cpu`` option passed
251directory. This setting specifies a ``-cpu`` option passed into QEMU in 250into QEMU in the ``runqemu`` script. Running ``qemu -cpu help`` returns a
252the ``runqemu`` script. Running ``qemu -cpu help`` returns a list of 251list of available supported CPU types.
253available supported CPU types.
254 252
255QEMU Performance 253QEMU Performance
256================ 254================
diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
index 23d5643d12..f90375471f 100644
--- a/documentation/dev-manual/start.rst
+++ b/documentation/dev-manual/start.rst
@@ -558,8 +558,8 @@ your Yocto Project build host:
558 access to external devices such as those connected through a USB 558 access to external devices such as those connected through a USB
559 port, but it automatically mounts your ``C:`` drive on ``/mnt/c/`` 559 port, but it automatically mounts your ``C:`` drive on ``/mnt/c/``
560 (and others), which you can use to share deploy artifacts to be later 560 (and others), which you can use to share deploy artifacts to be later
561 flashed on hardware through Windows, but your build directory should 561 flashed on hardware through Windows, but your :term:`Build Directory`
562 not reside inside this mountpoint. 562 should not reside inside this mountpoint.
563 563
564Once you have WSL 2 set up, everything is in place to develop just as if 564Once you have WSL 2 set up, everything is in place to develop just as if
565you were running on a native Linux machine. If you are going to use the 565you were running on a native Linux machine. If you are going to use the
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 0a1819ceae..690f61110b 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -66,19 +66,15 @@ section:
66 (i.e. ``poky``) have been cloned using Git and the local repository is named 66 (i.e. ``poky``) have been cloned using Git and the local repository is named
67 "poky". 67 "poky".
68 68
692. *Prepare Your local.conf File:* By default, the 692. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable
70 :term:`MACHINE` variable is set to 70 is set to "qemux86-64", which is fine if you are building for the QEMU
71 "qemux86-64", which is fine if you are building for the QEMU emulator 71 emulator in 64-bit mode. However, if you are not, you need to set the
72 in 64-bit mode. However, if you are not, you need to set the
73 :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file 72 :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file
74 found in the 73 found in the :term:`Build Directory` (i.e. ``poky/build`` in this example).
75 :term:`Build Directory` (i.e.
76 ``poky/build`` in this example).
77 74
78 Also, since you are preparing to work on the kernel image, you need 75 Also, since you are preparing to work on the kernel image, you need
79 to set the 76 to set the :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable to include
80 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` 77 kernel modules.
81 variable to include kernel modules.
82 78
83 In this example we wish to build for qemux86 so we must set the 79 In this example we wish to build for qemux86 so we must set the
84 :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules". 80 :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
@@ -186,14 +182,11 @@ section:
186 (i.e. ``poky``) have been cloned using Git and the local repository is named 182 (i.e. ``poky``) have been cloned using Git and the local repository is named
187 "poky". 183 "poky".
188 184
1892. *Prepare Your local.conf File:* By default, the 1852. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable is
190 :term:`MACHINE` variable is set to 186 set to "qemux86-64", which is fine if you are building for the QEMU emulator
191 "qemux86-64", which is fine if you are building for the QEMU emulator 187 in 64-bit mode. However, if you are not, you need to set the :term:`MACHINE`
192 in 64-bit mode. However, if you are not, you need to set the 188 variable appropriately in your ``conf/local.conf`` file found in the
193 :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file 189 :term:`Build Directory` (i.e. ``poky/build`` in this example).
194 found in the
195 :term:`Build Directory` (i.e.
196 ``poky/build`` in this example).
197 190
198 Also, since you are preparing to work on the kernel image, you need 191 Also, since you are preparing to work on the kernel image, you need
199 to set the 192 to set the
@@ -836,8 +829,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
836 829
8378. *Build the Image With Your Modified Kernel:* You can now build an 8308. *Build the Image With Your Modified Kernel:* You can now build an
838 image that includes your kernel patches. Execute the following 831 image that includes your kernel patches. Execute the following
839 command from your 832 command from your :term:`Build Directory` in the terminal
840 :term:`Build Directory` in the terminal
841 set up to run BitBake:: 833 set up to run BitBake::
842 834
843 $ cd poky/build 835 $ cd poky/build
@@ -1057,9 +1049,8 @@ To use the ``menuconfig`` tool in the Yocto Project development
1057environment, you must do the following: 1049environment, you must do the following:
1058 1050
1059- Because you launch ``menuconfig`` using BitBake, you must be sure to 1051- Because you launch ``menuconfig`` using BitBake, you must be sure to
1060 set up your environment by running the 1052 set up your environment by running the :ref:`structure-core-script` script
1061 :ref:`structure-core-script` script found in 1053 found in the :term:`Build Directory`.
1062 the :term:`Build Directory`.
1063 1054
1064- You must be sure of the state of your build's configuration in the 1055- You must be sure of the state of your build's configuration in the
1065 :term:`Source Directory`. 1056 :term:`Source Directory`.
@@ -1111,10 +1102,10 @@ can find the option under "Processor Type and Features". To deselect
1111Multi-Processing Support" and enter "N" to clear the asterisk. When you 1102Multi-Processing Support" and enter "N" to clear the asterisk. When you
1112are finished, exit out and save the change. 1103are finished, exit out and save the change.
1113 1104
1114Saving the selections updates the ``.config`` configuration file. This 1105Saving the selections updates the ``.config`` configuration file. This is the
1115is the file that the OpenEmbedded build system uses to configure the 1106file that the OpenEmbedded build system uses to configure the kernel during
1116kernel during the build. You can find and examine this file in the Build 1107the build. You can find and examine this file in the :term:`Build Directory`
1117Directory in ``tmp/work/``. The actual ``.config`` is located in the 1108in ``tmp/work/``. The actual ``.config`` is located in the
1118area where the specific kernel is built. For example, if you were 1109area where the specific kernel is built. For example, if you were
1119building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel 1110building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel
1120and you were building a QEMU image targeted for ``x86`` architecture, 1111and you were building a QEMU image targeted for ``x86`` architecture,
diff --git a/documentation/kernel-dev/concepts-appx.rst b/documentation/kernel-dev/concepts-appx.rst
index 63c5124a57..6a2fe4bb0b 100644
--- a/documentation/kernel-dev/concepts-appx.rst
+++ b/documentation/kernel-dev/concepts-appx.rst
@@ -319,8 +319,7 @@ image.
319 319
320The following figure shows the temporary file structure created on your 320The following figure shows the temporary file structure created on your
321host system when you build the kernel using BitBake. This 321host system when you build the kernel using BitBake. This
322:term:`Build Directory` contains all the 322:term:`Build Directory` contains all the source files used during the build.
323source files used during the build.
324 323
325.. image:: figures/kernel-overview-2-generic.png 324.. image:: figures/kernel-overview-2-generic.png
326 :align: center 325 :align: center
diff --git a/documentation/kernel-dev/intro.rst b/documentation/kernel-dev/intro.rst
index 4ff4dc7d35..267b7e7797 100644
--- a/documentation/kernel-dev/intro.rst
+++ b/documentation/kernel-dev/intro.rst
@@ -134,7 +134,7 @@ general information and references for further information.
1343. *Make Changes to the Kernel Source Code if applicable:* Modifying the 1343. *Make Changes to the Kernel Source Code if applicable:* Modifying the
135 kernel does not always mean directly changing source files. However, 135 kernel does not always mean directly changing source files. However,
136 if you have to do this, you make the changes to the files in the 136 if you have to do this, you make the changes to the files in the
137 Yocto's Build Directory if you are using ``devtool``. For more 137 Yocto's :term:`Build Directory` if you are using ``devtool``. For more
138 information, see the 138 information, see the
139 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" 139 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
140 section. 140 section.
@@ -155,7 +155,7 @@ general information and references for further information.
155 .. note:: 155 .. note::
156 156
157 Try to resist the temptation to directly edit an existing ``.config`` 157 Try to resist the temptation to directly edit an existing ``.config``
158 file, which is found in the Build Directory among the source code 158 file, which is found in the :term:`Build Directory` among the source code
159 used for the build. Doing so, can produce unexpected results when 159 used for the build. Doing so, can produce unexpected results when
160 the OpenEmbedded build system regenerates the configuration file. 160 the OpenEmbedded build system regenerates the configuration file.
161 161
diff --git a/documentation/kernel-dev/maint-appx.rst b/documentation/kernel-dev/maint-appx.rst
index d968c856f6..6aa2fb7cf1 100644
--- a/documentation/kernel-dev/maint-appx.rst
+++ b/documentation/kernel-dev/maint-appx.rst
@@ -229,6 +229,5 @@ This behavior means that all the generated files for a particular
229machine or BSP are now in the build tree directory. The files include 229machine or BSP are now in the build tree directory. The files include
230the final ``.config`` file, all the ``.o`` files, the ``.a`` files, and 230the final ``.config`` file, all the ``.o`` files, the ``.a`` files, and
231so forth. Since each machine or BSP has its own separate 231so forth. Since each machine or BSP has its own separate
232:term:`Build Directory` in its own separate 232:term:`Build Directory` in its own separate branch of the Git repository,
233branch of the Git repository, you can easily switch between different 233you can easily switch between different builds.
234builds.
diff --git a/documentation/migration-guides/migration-1.5.rst b/documentation/migration-guides/migration-1.5.rst
index 1b78e99809..70a087ff1a 100644
--- a/documentation/migration-guides/migration-1.5.rst
+++ b/documentation/migration-guides/migration-1.5.rst
@@ -126,10 +126,9 @@ The following directory changes exist:
126 :term:`DEPLOY_DIR_IMAGE` variable in the external environment. 126 :term:`DEPLOY_DIR_IMAGE` variable in the external environment.
127 127
128- When buildhistory is enabled, its output is now written under the 128- When buildhistory is enabled, its output is now written under the
129 :term:`Build Directory` rather than 129 :term:`Build Directory` rather than :term:`TMPDIR`. Doing so makes
130 :term:`TMPDIR`. Doing so makes it easier to delete 130 it easier to delete :term:`TMPDIR` and preserve the build history.
131 :term:`TMPDIR` and preserve the build history. Additionally, data for 131 Additionally, data for produced SDKs is now split by :term:`IMAGE_NAME`.
132 produced SDKs is now split by :term:`IMAGE_NAME`.
133 132
134- The ``pkgdata`` directory produced as part of the packaging process 133- The ``pkgdata`` directory produced as part of the packaging process
135 has been collapsed into a single machine-specific directory. This 134 has been collapsed into a single machine-specific directory. This
diff --git a/documentation/migration-guides/migration-1.6.rst b/documentation/migration-guides/migration-1.6.rst
index f54d4ba729..d3de264650 100644
--- a/documentation/migration-guides/migration-1.6.rst
+++ b/documentation/migration-guides/migration-1.6.rst
@@ -233,9 +233,9 @@ Separate build and source directories have been enabled by default for
233selected recipes where it is known to work and for all 233selected recipes where it is known to work and for all
234recipes that inherit the :ref:`cmake <ref-classes-cmake>` class. In 234recipes that inherit the :ref:`cmake <ref-classes-cmake>` class. In
235future releases the :ref:`autotools <ref-classes-autotools>` class 235future releases the :ref:`autotools <ref-classes-autotools>` class
236will enable a separate build directory by default as well. Recipes 236will enable a separate :term:`Build Directory` by default as well. Recipes
237building Autotools-based software that fails to build with a separate 237building Autotools-based software that fails to build with a separate
238build directory should be changed to inherit from the 238:term:`Build Directory` should be changed to inherit from the
239:ref:`autotools-brokensep <ref-classes-autotools>` class instead of 239:ref:`autotools-brokensep <ref-classes-autotools>` class instead of
240the ``autotools`` or ``autotools_stage``\ classes. 240the ``autotools`` or ``autotools_stage``\ classes.
241 241
diff --git a/documentation/migration-guides/migration-1.7.rst b/documentation/migration-guides/migration-1.7.rst
index 7b179f2aa1..e1a7594fb1 100644
--- a/documentation/migration-guides/migration-1.7.rst
+++ b/documentation/migration-guides/migration-1.7.rst
@@ -42,7 +42,7 @@ Autotools Class Changes
42The following :ref:`autotools <ref-classes-autotools>` class changes 42The following :ref:`autotools <ref-classes-autotools>` class changes
43occurred: 43occurred:
44 44
45- *A separate build directory is now used by default:* The 45- *A separate :term:`Build Directory` is now used by default:* The
46 :ref:`autotools <ref-classes-autotools>` class has been 46 :ref:`autotools <ref-classes-autotools>` class has been
47 changed to use a directory for building 47 changed to use a directory for building
48 (:term:`B`), which is separate from the source directory 48 (:term:`B`), which is separate from the source directory
diff --git a/documentation/migration-guides/migration-2.6.rst b/documentation/migration-guides/migration-2.6.rst
index b36eb194b3..eedede2457 100644
--- a/documentation/migration-guides/migration-2.6.rst
+++ b/documentation/migration-guides/migration-2.6.rst
@@ -343,8 +343,7 @@ BitBake Changes
343--------------- 343---------------
344 344
345The server logfile ``bitbake-cookerdaemon.log`` is now always placed in 345The server logfile ``bitbake-cookerdaemon.log`` is now always placed in
346the :term:`Build Directory` instead of the current 346the :term:`Build Directory` instead of the current directory.
347directory.
348 347
349.. _migration-2.6-security-changes: 348.. _migration-2.6-security-changes:
350 349
diff --git a/documentation/migration-guides/migration-general.rst b/documentation/migration-guides/migration-general.rst
index 0f0408e51f..847bdad739 100644
--- a/documentation/migration-guides/migration-general.rst
+++ b/documentation/migration-guides/migration-general.rst
@@ -86,7 +86,7 @@ any new Yocto Project release.
86 3. Capture the buildhistory output (as specified by :term:`BUILDHISTORY_DIR`) 86 3. Capture the buildhistory output (as specified by :term:`BUILDHISTORY_DIR`)
87 and ensure it is preserved for subsequent builds. How you would do this 87 and ensure it is preserved for subsequent builds. How you would do this
88 depends on how you are running your builds - if you are doing this all on 88 depends on how you are running your builds - if you are doing this all on
89 one workstation in the same build directory you may not need to do 89 one workstation in the same :term:`Build Directory` you may not need to do
90 anything other than not deleting the buildhistory output directory. For 90 anything other than not deleting the buildhistory output directory. For
91 builds in a pipeline it may be more complicated. 91 builds in a pipeline it may be more complicated.
92 92
diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
index 931bec79e8..b323a6fdf4 100644
--- a/documentation/overview-manual/concepts.rst
+++ b/documentation/overview-manual/concepts.rst
@@ -233,13 +233,12 @@ for creating actual configuration files when you source
233:ref:`structure-core-script`, which is the 233:ref:`structure-core-script`, which is the
234build environment script. 234build environment script.
235 235
236Sourcing the build environment script creates a 236Sourcing the build environment script creates a :term:`Build Directory`
237:term:`Build Directory` if one does not 237if one does not already exist. BitBake uses the :term:`Build Directory`
238already exist. BitBake uses the Build Directory for all its work during 238for all its work during builds. The Build Directory has a ``conf`` directory
239builds. The Build Directory has a ``conf`` directory that contains 239that contains default versions of your ``local.conf`` and ``bblayers.conf``
240default versions of your ``local.conf`` and ``bblayers.conf``
241configuration files. These default configuration files are created only 240configuration files. These default configuration files are created only
242if versions do not already exist in the Build Directory at the time you 241if versions do not already exist in the :term:`Build Directory` at the time you
243source the build environment setup script. 242source the build environment setup script.
244 243
245Because the Poky repository is fundamentally an aggregation of existing 244Because the Poky repository is fundamentally an aggregation of existing
@@ -251,9 +250,9 @@ assumes the script is executed from within a cloned or unpacked version
251of Poky. 250of Poky.
252 251
253Depending on where the script is sourced, different sub-scripts are 252Depending on where the script is sourced, different sub-scripts are
254called to set up the Build Directory (Yocto or OpenEmbedded). 253called to set up the :term:`Build Directory` (Yocto or OpenEmbedded).
255Specifically, the script ``scripts/oe-setup-builddir`` inside the poky 254Specifically, the script ``scripts/oe-setup-builddir`` inside the poky
256directory sets up the Build Directory and seeds the directory (if 255directory sets up the :term:`Build Directory` and seeds the directory (if
257necessary) with configuration files appropriate for the Yocto Project 256necessary) with configuration files appropriate for the Yocto Project
258development environment. 257development environment.
259 258
@@ -428,7 +427,7 @@ The distribution layer provides policy configurations for your
428distribution. Best practices dictate that you isolate these types of 427distribution. Best practices dictate that you isolate these types of
429configurations into their own layer. Settings you provide in 428configurations into their own layer. Settings you provide in
430``conf/distro/distro.conf`` override similar settings that BitBake finds 429``conf/distro/distro.conf`` override similar settings that BitBake finds
431in your ``conf/local.conf`` file in the Build Directory. 430in your ``conf/local.conf`` file in the :term:`Build Directory`.
432 431
433The following list provides some explanation and references for what you 432The following list provides some explanation and references for what you
434typically find in the distribution layer: 433typically find in the distribution layer:
@@ -531,10 +530,11 @@ repositories, which is not the default behavior, and store them in the
531variable. 530variable.
532 531
533Judicious use of a :term:`DL_DIR` directory can save the build system a trip 532Judicious use of a :term:`DL_DIR` directory can save the build system a trip
534across the Internet when looking for files. A good method for using a 533across the Internet when looking for files. A good method for using a download
535download directory is to have :term:`DL_DIR` point to an area outside of 534directory is to have :term:`DL_DIR` point to an area outside of your
536your Build Directory. Doing so allows you to safely delete the Build 535:term:`Build Directory`. Doing so allows you to safely delete the
537Directory if needed without fear of removing any downloaded source file. 536:term:`Build Directory` if needed without fear of removing any downloaded
537source file.
538 538
539The remainder of this section provides a deeper look into the source 539The remainder of this section provides a deeper look into the source
540files and the mirrors. Here is a more detailed look at the source file 540files and the mirrors. Here is a more detailed look at the source file
@@ -632,15 +632,14 @@ process validates them with generated output quality assurance checks
632through the :ref:`insane <ref-classes-insane>` 632through the :ref:`insane <ref-classes-insane>`
633class. 633class.
634 634
635The package feed area resides in the Build Directory. The directory the 635The package feed area resides in the :term:`Build Directory`. The directory the
636build system uses to temporarily store packages is determined by a 636build system uses to temporarily store packages is determined by a
637combination of variables and the particular package manager in use. See 637combination of variables and the particular package manager in use. See
638the "Package Feeds" box in the illustration and note the information to 638the "Package Feeds" box in the illustration and note the information to
639the right of that area. In particular, the following defines where 639the right of that area. In particular, the following defines where
640package files are kept: 640package files are kept:
641 641
642- :term:`DEPLOY_DIR`: Defined as 642- :term:`DEPLOY_DIR`: Defined as ``tmp/deploy`` in the :term:`Build Directory`.
643 ``tmp/deploy`` in the Build Directory.
644 643
645- ``DEPLOY_DIR_*``: Depending on the package manager used, the package 644- ``DEPLOY_DIR_*``: Depending on the package manager used, the package
646 type sub-folder. Given RPM, IPK, or DEB packaging and tarball 645 type sub-folder. Given RPM, IPK, or DEB packaging and tarball
@@ -696,10 +695,8 @@ code:
696.. image:: figures/source-fetching.png 695.. image:: figures/source-fetching.png
697 :width: 100% 696 :width: 100%
698 697
699The :ref:`ref-tasks-fetch` and 698The :ref:`ref-tasks-fetch` and :ref:`ref-tasks-unpack` tasks fetch
700:ref:`ref-tasks-unpack` tasks fetch 699the source files and unpack them into the :term:`Build Directory`.
701the source files and unpack them into the
702:term:`Build Directory`.
703 700
704.. note:: 701.. note::
705 702
@@ -710,17 +707,16 @@ the source files and unpack them into the
710 file has been modified, the :ref:`ref-tasks-fetch` task and all 707 file has been modified, the :ref:`ref-tasks-fetch` task and all
711 tasks that depend on it are re-executed. 708 tasks that depend on it are re-executed.
712 709
713By default, everything is accomplished in the Build Directory, which has 710By default, everything is accomplished in the :term:`Build Directory`, which has
714a defined structure. For additional general information on the Build 711a defined structure. For additional general information on the
715Directory, see the ":ref:`structure-core-build`" section in 712:term:`Build Directory`, see the ":ref:`structure-core-build`" section in
716the Yocto Project Reference Manual. 713the Yocto Project Reference Manual.
717 714
718Each recipe has an area in the Build Directory where the unpacked source 715Each recipe has an area in the :term:`Build Directory` where the unpacked
719code resides. The :term:`S` variable points 716source code resides. The :term:`S` variable points to this area for a recipe's
720to this area for a recipe's unpacked source code. The name of that 717unpacked source code. The name of that directory for any given recipe is
721directory for any given recipe is defined from several different 718defined from several different variables. The preceding figure and the
722variables. The preceding figure and the following list describe the 719following list describe the :term:`Build Directory`'s hierarchy:
723Build Directory's hierarchy:
724 720
725- :term:`TMPDIR`: The base directory 721- :term:`TMPDIR`: The base directory
726 where the OpenEmbedded build system performs all its work during the 722 where the OpenEmbedded build system performs all its work during the
@@ -1258,15 +1254,12 @@ this output:
1258 ":doc:`/ref-manual/images`" chapter in the Yocto Project Reference 1254 ":doc:`/ref-manual/images`" chapter in the Yocto Project Reference
1259 Manual. 1255 Manual.
1260 1256
1261The build process writes images out to the :term:`Build Directory` 1257The build process writes images out to the :term:`Build Directory` inside
1262inside the 1258the ``tmp/deploy/images/machine/`` folder as shown in the figure. This
1263``tmp/deploy/images/machine/`` folder as shown in the figure. This
1264folder contains any files expected to be loaded on the target device. 1259folder contains any files expected to be loaded on the target device.
1265The :term:`DEPLOY_DIR` variable 1260The :term:`DEPLOY_DIR` variable points to the ``deploy`` directory, while the
1266points to the ``deploy`` directory, while the 1261:term:`DEPLOY_DIR_IMAGE` variable points to the appropriate directory
1267:term:`DEPLOY_DIR_IMAGE` 1262containing images for the current configuration.
1268variable points to the appropriate directory containing images for the
1269current configuration.
1270 1263
1271- kernel-image: A kernel binary file. The 1264- kernel-image: A kernel binary file. The
1272 :term:`KERNEL_IMAGETYPE` 1265 :term:`KERNEL_IMAGETYPE`
@@ -1340,10 +1333,9 @@ can initialize the environment before using the tools.
1340 the :doc:`/sdk-manual/index` manual. 1333 the :doc:`/sdk-manual/index` manual.
1341 1334
1342All the output files for an SDK are written to the ``deploy/sdk`` folder 1335All the output files for an SDK are written to the ``deploy/sdk`` folder
1343inside the :term:`Build Directory` as 1336inside the :term:`Build Directory` as shown in the previous figure. Depending
1344shown in the previous figure. Depending on the type of SDK, there are 1337on the type of SDK, there are several variables to configure these files.
1345several variables to configure these files. Here are the variables 1338Here are the variables associated with an extensible SDK:
1346associated with an extensible SDK:
1347 1339
1348- :term:`DEPLOY_DIR`: Points to 1340- :term:`DEPLOY_DIR`: Points to
1349 the ``deploy`` directory. 1341 the ``deploy`` directory.
diff --git a/documentation/overview-manual/development-environment.rst b/documentation/overview-manual/development-environment.rst
index 43a6f1b480..04aea1373c 100644
--- a/documentation/overview-manual/development-environment.rst
+++ b/documentation/overview-manual/development-environment.rst
@@ -623,11 +623,9 @@ MIT license `here <https://en.wikipedia.org/wiki/MIT_License>`__.
623 623
624When you build an image using the Yocto Project, the build process uses 624When you build an image using the Yocto Project, the build process uses
625a known list of licenses to ensure compliance. You can find this list in 625a known list of licenses to ensure compliance. You can find this list in
626the :term:`Source Directory` at 626the :term:`Source Directory` at ``meta/files/common-licenses``. Once the
627``meta/files/common-licenses``. Once the build completes, the list of 627build completes, the list of all licenses found and used during that build
628all licenses found and used during that build are kept in the 628are kept in the :term:`Build Directory` at ``tmp/deploy/licenses``.
629:term:`Build Directory` at
630``tmp/deploy/licenses``.
631 629
632If a module requires a license that is not in the base list, the build 630If a module requires a license that is not in the base list, the build
633process generates a warning during the build. These tools make it easier 631process generates a warning during the build. These tools make it easier
diff --git a/documentation/profile-manual/usage.rst b/documentation/profile-manual/usage.rst
index 49f8af4a74..01fbde1411 100644
--- a/documentation/profile-manual/usage.rst
+++ b/documentation/profile-manual/usage.rst
@@ -1895,9 +1895,9 @@ manual, and boot the resulting target image.
1895 1895
1896.. note:: 1896.. note::
1897 1897
1898 If you have a build directory containing multiple machines, you need 1898 If you have a :term:`Build Directory` containing multiple machines, you need
1899 to have the MACHINE you're connecting to selected in local.conf, and 1899 to have the MACHINE you're connecting to selected in local.conf, and
1900 the kernel in that machine's build directory must match the kernel on 1900 the kernel in that machine's :term:`Build Directory` must match the kernel on
1901 the booted system exactly, or you'll get the above 'crosstap' message 1901 the booted system exactly, or you'll get the above 'crosstap' message
1902 when you try to invoke a script. 1902 when you try to invoke a script.
1903 1903
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:
1912You can control the list of resulting package formats by using the 1912You can control the list of resulting package formats by using the
1913:term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf`` 1913:term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf``
1914configuration file, which is located in the :term:`Build Directory`. 1914configuration file, which is located in the :term:`Build Directory`.
1915When defining the variable, you can 1915When defining the variable, you can specify one or more package types.
1916specify one or more package types. Since images are generated from 1916Since images are generated from packages, a packaging class is needed
1917packages, a packaging class is needed to enable image generation. The 1917to enable image generation. The first class listed in this variable is
1918first class listed in this variable is used for image generation. 1918used for image generation.
1919 1919
1920If you take the optional step to set up a repository (package feed) on 1920If you take the optional step to set up a repository (package feed) on
1921the development host that can be used by DNF, you can install packages 1921the 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
2401preserves these files for inspection and possible debugging purposes. If 2401preserves these files for inspection and possible debugging purposes. If
2402you would rather have these files deleted to save disk space as the 2402you would rather have these files deleted to save disk space as the
2403build progresses, you can enable :ref:`rm_work <ref-classes-rm-work>` by adding the following to 2403build progresses, you can enable :ref:`rm_work <ref-classes-rm-work>` by adding the following to
2404your ``local.conf`` file, which is found in the :term:`Build Directory`. 2404your ``local.conf`` file, which is found in the :term:`Build Directory`::
2405::
2406 2405
2407 INHERIT += "rm_work" 2406 INHERIT += "rm_work"
2408 2407
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`).
270By default, this :term:`Build Directory` is named ``build`` but can be named 270By default, this :term:`Build Directory` is named ``build`` but can be named
271anything you want. 271anything you want.
272 272
273Within the Build Directory, is the ``tmp`` directory. To remove all the 273Within the :term:`Build Directory`, is the ``tmp`` directory. To remove all the
274build output yet preserve any source code or downloaded files from 274build output yet preserve any source code or downloaded files from
275previous builds, simply remove the ``tmp`` directory. 275previous builds, simply remove the ``tmp`` directory.
276 276
@@ -381,14 +381,13 @@ system of that image. Thus, the build system provides a value of
381forth. 381forth.
382 382
383Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`. 383Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`.
384However, when the recipe builds a 384However, when the recipe builds a native program (i.e. one that is
385native program (i.e. one that is intended to run on the build machine), 385intended to run on the build machine), that program is never installed
386that program is never installed directly to the build machine's root 386directly to the build machine's root file system. Consequently, the build
387file system. Consequently, the build system uses paths within the Build 387system uses paths within the Build Directory for ``DESTDIR``, ``bindir``
388Directory for ``DESTDIR``, ``bindir`` and related variables. To better 388and related variables. To better understand this, consider the following
389understand this, consider the following two paths (artificially broken 389two paths (artificially broken across lines for readability) where the
390across lines for readability) where the first is relatively normal and 390first is relatively normal and the second is not::
391the second is not::
392 391
393 /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ 392 /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
394 1.2.8-r0/sysroot-destdir/usr/bin 393 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
57This directory contains user configuration files and the output 57This directory contains user configuration files and the output
58generated by the OpenEmbedded build system in its standard configuration 58generated by the OpenEmbedded build system in its standard configuration
59where the source tree is combined with the output. The :term:`Build Directory` 59where the source tree is combined with the output. The :term:`Build Directory`
60is created initially when you ``source`` 60is created initially when you ``source`` the OpenEmbedded build environment
61the OpenEmbedded build environment setup script (i.e. 61setup script (i.e. :ref:`structure-core-script`).
62:ref:`structure-core-script`).
63 62
64It is also possible to place output and configuration files in a 63It is also possible to place output and configuration files in a
65directory separate from the :term:`Source Directory` by 64directory separate from the :term:`Source Directory` by
@@ -153,10 +152,10 @@ BitBake commands. The script uses other scripts within the ``scripts``
153directory to do the bulk of the work. 152directory to do the bulk of the work.
154 153
155When you run this script, your Yocto Project environment is set up, a 154When you run this script, your Yocto Project environment is set up, a
156:term:`Build Directory` is created, your working 155:term:`Build Directory` is created, your working directory becomes the
157directory becomes the Build Directory, and you are presented with some 156:term:`Build Directory`, and you are presented with some simple
158simple suggestions as to what to do next, including a list of some 157suggestions as to what to do next, including a list of some possible
159possible targets to build. Here is an example:: 158targets to build. Here is an example::
160 159
161 $ source oe-init-build-env 160 $ source oe-init-build-env
162 161
@@ -182,12 +181,13 @@ See the
182section in the Yocto Project Development Tasks Manual for more 181section in the Yocto Project Development Tasks Manual for more
183information. 182information.
184 183
185By default, running this script without a Build Directory argument 184By default, running this script without a :term:`Build Directory` argument
186creates the ``build/`` directory in your current working directory. If 185creates the ``build/`` directory in your current working directory. If
187you provide a Build Directory argument when you ``source`` the script, 186you provide a :term:`Build Directory` argument when you ``source`` the script,
188you direct the OpenEmbedded build system to create a Build Directory of 187you direct the OpenEmbedded build system to create a :term:`Build Directory` of
189your choice. For example, the following command creates a Build 188your choice. For example, the following command creates a
190Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:: 189:term:`Build Directory` named ``mybuilds/`` that is outside of the
190:term:`Source Directory`::
191 191
192 $ source oe-init-build-env ~/mybuilds 192 $ source oe-init-build-env ~/mybuilds
193 193
@@ -219,11 +219,10 @@ These files are standard top-level files.
219The Build Directory --- ``build/`` 219The Build Directory --- ``build/``
220================================== 220==================================
221 221
222The OpenEmbedded build system creates the :term:`Build Directory` 222The OpenEmbedded build system creates the :term:`Build Directory` when you run
223when you run the build environment setup 223the build environment setup script :ref:`structure-core-script`. If you do not
224script :ref:`structure-core-script`. If you do not give the Build 224give the :term:`Build Directory` a specific name when you run the setup script,
225Directory a specific name when you run the setup script, the name 225the name defaults to ``build/``.
226defaults to ``build/``.
227 226
228For subsequent parsing and processing, the name of the Build directory 227For subsequent parsing and processing, the name of the Build directory
229is available via the :term:`TOPDIR` variable. 228is 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:
64 builds. The area is created when you ``source`` the setup environment 64 builds. The area is created when you ``source`` the setup environment
65 script that is found in the Source Directory 65 script that is found in the Source Directory
66 (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). The 66 (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). The
67 :term:`TOPDIR` variable points to the Build Directory. 67 :term:`TOPDIR` variable points to the :term:`Build Directory`.
68 68
69 You have a lot of flexibility when creating the Build Directory. 69 You have a lot of flexibility when creating the :term:`Build Directory`.
70 Following are some examples that show how to create the directory. The 70 Following are some examples that show how to create the directory. The
71 examples assume your :term:`Source Directory` is named ``poky``: 71 examples assume your :term:`Source Directory` is named ``poky``:
72 72
73 - Create the Build Directory inside your Source Directory and let 73 - Create the :term:`Build Directory` inside your Source Directory and let
74 the name of the Build Directory default to ``build``: 74 the name of the :term:`Build Directory` default to ``build``:
75 75
76 .. code-block:: shell 76 .. code-block:: shell
77 77
78 $ cd poky 78 $ cd poky
79 $ source oe-init-build-env 79 $ source oe-init-build-env
80 80
81 - Create the Build Directory inside your home directory and 81 - Create the :term:`Build Directory` inside your home directory and
82 specifically name it ``test-builds``: 82 specifically name it ``test-builds``:
83 83
84 .. code-block:: shell 84 .. code-block:: shell
85 85
86 $ source poky/oe-init-build-env test-builds 86 $ source poky/oe-init-build-env test-builds
87 87
88 - Provide a directory path and specifically name the Build 88 - Provide a directory path and specifically name the
89 Directory. Any intermediate folders in the pathname must exist. 89 :term:`Build Directory`. Any intermediate folders in the pathname
90 This next example creates a Build Directory named 90 must exist. This next example creates a :term:`Build Directory`
91 ``YP-&DISTRO;`` within the existing directory ``mybuilds``: 91 named ``YP-&DISTRO;`` within the existing directory ``mybuilds``:
92 92
93 .. code-block:: shell 93 .. code-block:: shell
94 94
@@ -96,13 +96,13 @@ universal, the list includes them just in case:
96 96
97 .. note:: 97 .. note::
98 98
99 By default, the Build Directory contains :term:`TMPDIR`, which is a 99 By default, the :term:`Build Directory` contains :term:`TMPDIR`, which is a
100 temporary directory the build system uses for its work. :term:`TMPDIR` cannot 100 temporary directory the build system uses for its work. :term:`TMPDIR` cannot
101 be under NFS. Thus, by default, the Build Directory cannot be under 101 be under NFS. Thus, by default, the :term:`Build Directory` cannot be under
102 NFS. However, if you need the Build Directory to be under NFS, you can 102 NFS. However, if you need the :term:`Build Directory` to be under NFS, you can
103 set this up by setting :term:`TMPDIR` in your ``local.conf`` file to use a local 103 set this up by setting :term:`TMPDIR` in your ``local.conf`` file to use a local
104 drive. Doing so effectively separates :term:`TMPDIR` from :term:`TOPDIR`, which is the 104 drive. Doing so effectively separates :term:`TMPDIR` from :term:`TOPDIR`, which is the
105 Build Directory. 105 :term:`Build Directory`.
106 106
107 :term:`Build Host` 107 :term:`Build Host`
108 The system used to build images in a Yocto Project Development 108 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.
260 https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview 260 https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview
261 261
262 :term:`B` 262 :term:`B`
263 The directory within the :term:`Build Directory` in 263 The directory within the :term:`Build Directory` in which the
264 which the OpenEmbedded build system places generated objects during a 264 OpenEmbedded build system places generated objects during a recipe's
265 recipe's build process. By default, this directory is the same as the 265 build process. By default, this directory is the same as the
266 :term:`S` directory, which is defined as:: 266 :term:`S` directory, which is defined as::
267 267
268 S = "${WORKDIR}/${BP}" 268 S = "${WORKDIR}/${BP}"
@@ -903,12 +903,11 @@ system and gives an overview of their function and contents.
903 The default value is an empty string (""). 903 The default value is an empty string ("").
904 904
905 :term:`BUILDDIR` 905 :term:`BUILDDIR`
906 Points to the location of the :term:`Build Directory`. 906 Points to the location of the :term:`Build Directory`. You can define
907 You can define this directory indirectly through the 907 this directory indirectly through the :ref:`structure-core-script` script
908 :ref:`structure-core-script` script by passing in a Build 908 by passing in a :term:`Build Directory` path when you run the script. If
909 Directory path when you run the script. If you run the script and do 909 you run the script and do not provide a :term:`Build Directory` path, the
910 not provide a Build Directory path, the :term:`BUILDDIR` defaults to 910 :term:`BUILDDIR` defaults to ``build`` in the current directory.
911 ``build`` in the current directory.
912 911
913 :term:`BUILDHISTORY_COMMIT` 912 :term:`BUILDHISTORY_COMMIT`
914 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 913 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
@@ -1712,8 +1711,7 @@ system and gives an overview of their function and contents.
1712 Points to the general area that the OpenEmbedded build system uses to 1711 Points to the general area that the OpenEmbedded build system uses to
1713 place images, packages, SDKs, and other output files that are ready 1712 place images, packages, SDKs, and other output files that are ready
1714 to be used outside of the build system. By default, this directory 1713 to be used outside of the build system. By default, this directory
1715 resides within the :term:`Build Directory` as 1714 resides within the :term:`Build Directory` as ``${TMPDIR}/deploy``.
1716 ``${TMPDIR}/deploy``.
1717 1715
1718 For more information on the structure of the Build Directory, see 1716 For more information on the structure of the Build Directory, see
1719 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section. 1717 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section.
@@ -1759,7 +1757,7 @@ system and gives an overview of their function and contents.
1759 with the contents of :term:`IMGDEPLOYDIR` by the :ref:`image 1757 with the contents of :term:`IMGDEPLOYDIR` by the :ref:`image
1760 <ref-classes-image>` class. 1758 <ref-classes-image>` class.
1761 1759
1762 For more information on the structure of the Build Directory, see 1760 For more information on the structure of the :term:`Build Directory`, see
1763 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section. 1761 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section.
1764 For more detail on the contents of the ``deploy`` directory, see the 1762 For more detail on the contents of the ``deploy`` directory, see the
1765 ":ref:`overview-manual/concepts:images`" and 1763 ":ref:`overview-manual/concepts:images`" and
@@ -2042,8 +2040,7 @@ system and gives an overview of their function and contents.
2042 You can set this directory by defining the :term:`DL_DIR` variable in the 2040 You can set this directory by defining the :term:`DL_DIR` variable in the
2043 ``conf/local.conf`` file. This directory is self-maintaining and you 2041 ``conf/local.conf`` file. This directory is self-maintaining and you
2044 should not have to touch it. By default, the directory is 2042 should not have to touch it. By default, the directory is
2045 ``downloads`` in the :term:`Build Directory`. 2043 ``downloads`` in the :term:`Build Directory`::
2046 ::
2047 2044
2048 #DL_DIR ?= "${TOPDIR}/downloads" 2045 #DL_DIR ?= "${TOPDIR}/downloads"
2049 2046
@@ -2264,8 +2261,8 @@ system and gives an overview of their function and contents.
2264 class, this variable points to the directory in which the recipe's 2261 class, this variable points to the directory in which the recipe's
2265 source code is built, which is outside of the OpenEmbedded build 2262 source code is built, which is outside of the OpenEmbedded build
2266 system. When set, this variable sets the :term:`B` variable, 2263 system. When set, this variable sets the :term:`B` variable,
2267 which is what the OpenEmbedded build system uses to locate the Build 2264 which is what the OpenEmbedded build system uses to locate the
2268 Directory. 2265 :term:`Build Directory`.
2269 2266
2270 See the ":ref:`ref-classes-externalsrc`" section for details. You 2267 See the ":ref:`ref-classes-externalsrc`" section for details. You
2271 can also find information on how to use this variable in the 2268 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.
2285 more than one feature, separate them with a space. 2282 more than one feature, separate them with a space.
2286 2283
2287 Typically, you configure this variable in your ``local.conf`` file, 2284 Typically, you configure this variable in your ``local.conf`` file,
2288 which is found in the :term:`Build Directory`. 2285 which is found in the :term:`Build Directory`. Although you can use this
2289 Although you can use this variable from within a recipe, best 2286 variable from within a recipe, best practices dictate that you do not.
2290 practices dictate that you do not.
2291 2287
2292 .. note:: 2288 .. note::
2293 2289
@@ -2684,10 +2680,9 @@ system and gives an overview of their function and contents.
2684 2680
2685 You define the :term:`FILESYSTEM_PERMS_TABLES` variable in the 2681 You define the :term:`FILESYSTEM_PERMS_TABLES` variable in the
2686 ``conf/local.conf`` file, which is found in the :term:`Build Directory`, 2682 ``conf/local.conf`` file, which is found in the :term:`Build Directory`,
2687 to point to your custom 2683 to point to your custom ``fs-perms.txt``. You can specify more than a
2688 ``fs-perms.txt``. You can specify more than a single file permissions 2684 single file permissions setting table. The paths you specify to these
2689 setting table. The paths you specify to these files must be defined 2685 files must be defined within the :term:`BBPATH` variable.
2690 within the :term:`BBPATH` variable.
2691 2686
2692 For guidance on how to create your own file permissions settings 2687 For guidance on how to create your own file permissions settings
2693 table file, examine the existing ``fs-perms.txt``. 2688 table file, examine the existing ``fs-perms.txt``.
@@ -6747,7 +6742,7 @@ system and gives an overview of their function and contents.
6747 to find the unpacked source. 6742 to find the unpacked source.
6748 6743
6749 As an example, assume a :term:`Source Directory` 6744 As an example, assume a :term:`Source Directory`
6750 top-level folder named ``poky`` and a default Build Directory at 6745 top-level folder named ``poky`` and a default :term:`Build Directory` at
6751 ``poky/build``. In this case, the work directory the build system 6746 ``poky/build``. In this case, the work directory the build system
6752 uses to keep the unpacked recipe for ``db`` is the following:: 6747 uses to keep the unpacked recipe for ``db`` is the following::
6753 6748
@@ -6792,7 +6787,7 @@ system and gives an overview of their function and contents.
6792 6787
6793 :term:`SDK_CUSTOM_TEMPLATECONF` 6788 :term:`SDK_CUSTOM_TEMPLATECONF`
6794 When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to 6789 When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to
6795 "1" and a ``conf/templateconf.cfg`` file exists in the build directory 6790 "1" and a ``conf/templateconf.cfg`` file exists in the :term:`Build Directory`
6796 (:term:`TOPDIR`) then this will be copied into the SDK. 6791 (:term:`TOPDIR`) then this will be copied into the SDK.
6797 6792
6798 :term:`SDK_DEPLOY` 6793 :term:`SDK_DEPLOY`
@@ -7195,8 +7190,7 @@ system and gives an overview of their function and contents.
7195 7190
7196 To enable file removal, set the variable to "1" in your 7191 To enable file removal, set the variable to "1" in your
7197 ``conf/local.conf`` configuration file in your: 7192 ``conf/local.conf`` configuration file in your:
7198 :term:`Build Directory`. 7193 :term:`Build Directory`::
7199 ::
7200 7194
7201 SKIP_FILEDEPS = "1" 7195 SKIP_FILEDEPS = "1"
7202 7196
@@ -8126,12 +8120,11 @@ system and gives an overview of their function and contents.
8126 You can select "glibc", "musl", "newlib", or "baremetal". 8120 You can select "glibc", "musl", "newlib", or "baremetal".
8127 8121
8128 :term:`TCLIBCAPPEND` 8122 :term:`TCLIBCAPPEND`
8129 Specifies a suffix to be appended onto the 8123 Specifies a suffix to be appended onto the :term:`TMPDIR` value. The
8130 :term:`TMPDIR` value. The suffix identifies the 8124 suffix identifies the ``libc`` variant for building. When you are
8131 ``libc`` variant for building. When you are building for multiple 8125 building for multiple variants with the same :term:`Build Directory`,
8132 variants with the same :term:`Build Directory`, this 8126 this mechanism ensures that output for different ``libc`` variants is
8133 mechanism ensures that output for different ``libc`` variants is kept 8127 kept separate to avoid potential conflicts.
8134 separate to avoid potential conflicts.
8135 8128
8136 In the ``defaultsetup.conf`` file, the default value of 8129 In the ``defaultsetup.conf`` file, the default value of
8137 :term:`TCLIBCAPPEND` is "-${TCLIBC}". However, distros such as poky, 8130 :term:`TCLIBCAPPEND` is "-${TCLIBC}". However, distros such as poky,
@@ -8419,7 +8412,7 @@ system and gives an overview of their function and contents.
8419 #TMPDIR = "${TOPDIR}/tmp" 8412 #TMPDIR = "${TOPDIR}/tmp"
8420 8413
8421 An example use for this scenario is to set :term:`TMPDIR` to a local disk, 8414 An example use for this scenario is to set :term:`TMPDIR` to a local disk,
8422 which does not use NFS, while having the Build Directory use NFS. 8415 which does not use NFS, while having the :term:`Build Directory` use NFS.
8423 8416
8424 The filesystem used by :term:`TMPDIR` must have standard filesystem 8417 The filesystem used by :term:`TMPDIR` must have standard filesystem
8425 semantics (i.e. mixed-case files are unique, POSIX file locking, and 8418 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.
9105 - :term:`PR`: The recipe revision 9098 - :term:`PR`: The recipe revision
9106 9099
9107 As an example, assume a Source Directory top-level folder name 9100 As an example, assume a Source Directory top-level folder name
9108 ``poky``, a default Build Directory at ``poky/build``, and a 9101 ``poky``, a default :term:`Build Directory` at ``poky/build``, and a
9109 ``qemux86-poky-linux`` machine target system. Furthermore, suppose 9102 ``qemux86-poky-linux`` machine target system. Furthermore, suppose
9110 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work 9103 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work
9111 directory the build system uses to build the package would be as 9104 directory the build system uses to build the package would be as
diff --git a/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst
index 23a437eb9d..d6bca44947 100644
--- a/documentation/sdk-manual/appendix-customizing.rst
+++ b/documentation/sdk-manual/appendix-customizing.rst
@@ -286,9 +286,8 @@ source, you need to do a number of things:
286 ESDK_LOCALCONF_ALLOW = "SSTATE_MIRRORS" 286 ESDK_LOCALCONF_ALLOW = "SSTATE_MIRRORS"
287 287
288 - Alternatively, if you just want to set the :term:`SSTATE_MIRRORS` 288 - Alternatively, if you just want to set the :term:`SSTATE_MIRRORS`
289 variable's value for the SDK alone, create a 289 variable's value for the SDK alone, create a ``conf/sdk-extra.conf``
290 ``conf/sdk-extra.conf`` file either in your 290 file either in your :term:`Build Directory` or within any
291 :term:`Build Directory` or within any
292 layer and put your :term:`SSTATE_MIRRORS` setting within that file. 291 layer and put your :term:`SSTATE_MIRRORS` setting within that file.
293 292
294 .. note:: 293 .. note::
diff --git a/documentation/sdk-manual/appendix-obtain.rst b/documentation/sdk-manual/appendix-obtain.rst
index 7d62293cd6..b90247d2e0 100644
--- a/documentation/sdk-manual/appendix-obtain.rst
+++ b/documentation/sdk-manual/appendix-obtain.rst
@@ -116,24 +116,21 @@ build the SDK installer. Follow these steps:
116 116
117 $ source oe-init-build-env 117 $ source oe-init-build-env
118 118
119 Among other things, the script 119 Among other things, the script creates the :term:`Build Directory`, which
120 creates the :term:`Build Directory`, 120 is ``build`` in this case and is located in the Source Directory. After
121 which is 121 the script runs, your current working directory is set to the ``build``
122 ``build`` in this case and is located in the Source Directory. After 122 directory.
123 the script runs, your current working directory is set to the
124 ``build`` directory.
125 123
1264. *Make Sure You Are Building an Installer for the Correct Machine:* 1244. *Make Sure You Are Building an Installer for the Correct Machine:*
127 Check to be sure that your 125 Check to be sure that your :term:`MACHINE` variable in the ``local.conf``
128 :term:`MACHINE` variable in the 126 file in your :term:`Build Directory` matches the architecture
129 ``local.conf`` file in your Build Directory matches the architecture
130 for which you are building. 127 for which you are building.
131 128
1325. *Make Sure Your SDK Machine is Correctly Set:* If you are building a 1295. *Make Sure Your SDK Machine is Correctly Set:* If you are building a
133 toolchain designed to run on an architecture that differs from your 130 toolchain designed to run on an architecture that differs from your
134 current development host machine (i.e. the build host), be sure that 131 current development host machine (i.e. the build host), be sure that
135 the :term:`SDKMACHINE` variable in the ``local.conf`` file in your 132 the :term:`SDKMACHINE` variable in the ``local.conf`` file in your
136 Build Directory is correctly set. 133 :term:`Build Directory` is correctly set.
137 134
138 .. note:: 135 .. note::
139 136
@@ -163,7 +160,7 @@ build the SDK installer. Follow these steps:
163 that matches your target root filesystem. 160 that matches your target root filesystem.
164 161
165 When the ``bitbake`` command completes, the SDK installer will be in 162 When the ``bitbake`` command completes, the SDK installer will be in
166 ``tmp/deploy/sdk`` in the Build Directory. 163 ``tmp/deploy/sdk`` in the :term:`Build Directory`.
167 164
168 .. note:: 165 .. note::
169 166
@@ -180,7 +177,7 @@ build the SDK installer. Follow these steps:
180 libc-staticdev" 177 libc-staticdev"
181 178
1827. *Run the Installer:* You can now run the SDK installer from 1797. *Run the Installer:* You can now run the SDK installer from
183 ``tmp/deploy/sdk`` in the Build Directory. Following is an example:: 180 ``tmp/deploy/sdk`` in the :term:`Build Directory`. Following is an example::
184 181
185 $ cd poky/build/tmp/deploy/sdk 182 $ cd poky/build/tmp/deploy/sdk
186 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh 183 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst
index 3e3fa6c05a..ed38ac3f3f 100644
--- a/documentation/sdk-manual/extensible.rst
+++ b/documentation/sdk-manual/extensible.rst
@@ -64,7 +64,7 @@ binary artefact cache over the network for developers with underpowered laptops.
64Setting up the Extensible SDK environment directly in a Yocto build 64Setting up the Extensible SDK environment directly in a Yocto build
65------------------------------------------------------------------- 65-------------------------------------------------------------------
66 66
671. Set up all the needed layers and a Yocto build directory, e.g. a regular Yocto 671. Set up all the needed layers and a Yocto :term:`Build Directory`, e.g. a regular Yocto
68 build where ``bitbake`` can be executed. 68 build where ``bitbake`` can be executed.
69 69
702. Run: 702. Run:
@@ -175,7 +175,7 @@ Once you have the SDK installed, you must run the SDK environment setup
175script before you can actually use the SDK. 175script before you can actually use the SDK.
176 176
177When using a SDK directly in a Yocto build, you will find the script in 177When using a SDK directly in a Yocto build, you will find the script in
178``tmp/deploy/images/qemux86-64/`` in your build directory. 178``tmp/deploy/images/qemux86-64/`` in your :term:`Build Directory`.
179 179
180When using a standalone SDK installer, this setup script resides in 180When using a standalone SDK installer, this setup script resides in
181the directory you chose when you installed the SDK, which is either the 181the directory you chose when you installed the SDK, which is either the
diff --git a/documentation/test-manual/understand-autobuilder.rst b/documentation/test-manual/understand-autobuilder.rst
index bfd75c81e0..66471972de 100644
--- a/documentation/test-manual/understand-autobuilder.rst
+++ b/documentation/test-manual/understand-autobuilder.rst
@@ -242,7 +242,7 @@ of post-build steps, including:
242#. Call ``scripts/upload-error-reports`` to send any error reports 242#. Call ``scripts/upload-error-reports`` to send any error reports
243 generated to the remote server. 243 generated to the remote server.
244 244
245#. Cleanup the build directory using 245#. Cleanup the :term:`Build Directory` using
246 :ref:`test-manual/understand-autobuilder:clobberdir` if the build was successful, 246 :ref:`test-manual/understand-autobuilder:clobberdir` if the build was successful,
247 else rename it to "build-renamed" for potential future debugging. 247 else rename it to "build-renamed" for potential future debugging.
248 248
diff --git a/documentation/toaster-manual/reference.rst b/documentation/toaster-manual/reference.rst
index 1bb9f98cca..b181d12d86 100644
--- a/documentation/toaster-manual/reference.rst
+++ b/documentation/toaster-manual/reference.rst
@@ -522,14 +522,13 @@ tasks. You can locate these commands in the
522 522
523 - When using ``manage.py`` commands given a default configuration, 523 - When using ``manage.py`` commands given a default configuration,
524 you must be sure that your working directory is set to the 524 you must be sure that your working directory is set to the
525 :term:`Build Directory`. Using 525 :term:`Build Directory`. Using ``manage.py`` commands from the
526 ``manage.py`` commands from the Build Directory allows Toaster to 526 :term:`Build Directory` allows Toaster to find the ``toaster.sqlite``
527 find the ``toaster.sqlite`` file, which is located in the Build 527 file, which is located in the :term:`Build Directory`.
528 Directory.
529 528
530 - For non-default database configurations, it is possible that you 529 - For non-default database configurations, it is possible that you
531 can use ``manage.py`` commands from a directory other than the 530 can use ``manage.py`` commands from a directory other than the
532 Build Directory. To do so, the ``toastermain/settings.py`` file 531 :term:`Build Directory`. To do so, the ``toastermain/settings.py`` file
533 must be configured to point to the correct database backend. 532 must be configured to point to the correct database backend.
534 533
535``buildslist`` 534``buildslist``
@@ -549,7 +548,7 @@ database.
549You need to run the ``buildslist`` command first to identify existing 548You need to run the ``buildslist`` command first to identify existing
550builds in the database before using the 549builds in the database before using the
551:ref:`toaster-manual/reference:\`\`builddelete\`\`` command. Here is an 550:ref:`toaster-manual/reference:\`\`builddelete\`\`` command. Here is an
552example that assumes default repository and build directory names: 551example that assumes default repository and :term:`Build Directory` names:
553 552
554.. code-block:: shell 553.. code-block:: shell
555 554
diff --git a/documentation/toaster-manual/setup-and-use.rst b/documentation/toaster-manual/setup-and-use.rst
index 72a15b5f2d..c5521edda1 100644
--- a/documentation/toaster-manual/setup-and-use.rst
+++ b/documentation/toaster-manual/setup-and-use.rst
@@ -23,8 +23,8 @@ Once in that directory, source the build environment script::
23 23
24 $ source oe-init-build-env 24 $ source oe-init-build-env
25 25
26Next, from the build directory (e.g. 26Next, from the :term:`Build Directory` (e.g. ``poky/build``), start Toaster
27``poky/build``), start Toaster using this command:: 27using this command::
28 28
29 $ source toaster start 29 $ source toaster start
30 30
@@ -124,14 +124,14 @@ causes Toaster to create and use ``$TOASTER_DIR./_toaster_clones``.
124The Build Directory 124The Build Directory
125=================== 125===================
126 126
127Toaster creates a build directory within your Source Directory (e.g. 127Toaster creates a :term:`Build Directory` within your Source Directory (e.g.
128``poky``) to execute the builds. 128``poky``) to execute the builds.
129 129
130Alternatively, if you would like all of your Toaster related files and 130Alternatively, if you would like all of your Toaster related files and
131directories to be in a particular location, you can set the 131directories to be in a particular location, you can set the
132``TOASTER_DIR`` environment variable, which takes precedence over your 132``TOASTER_DIR`` environment variable, which takes precedence over your
133current working directory. Setting this environment variable causes 133current working directory. Setting this environment variable causes
134Toaster to use ``$TOASTER_DIR/build`` as the build directory. 134Toaster to use ``$TOASTER_DIR/build`` as the :term:`Build Directory`.
135 135
136Creating a Django Superuser 136Creating a Django Superuser
137=========================== 137===========================
@@ -152,8 +152,8 @@ superuser by following these steps:
152 $ export PATH=$PATH:$HOME/.local/bin 152 $ export PATH=$PATH:$HOME/.local/bin
153 153
154#. From the directory containing the Toaster database, which by default 154#. From the directory containing the Toaster database, which by default
155 is the :term:`Build Directory`, 155 is the :term:`Build Directory`, invoke the ``createsuperuser`` command from
156 invoke the ``createsuperuser`` command from ``manage.py``:: 156 ``manage.py``::
157 157
158 $ cd poky/build 158 $ cd poky/build
159 $ ../bitbake/lib/toaster/manage.py createsuperuser 159 $ ../bitbake/lib/toaster/manage.py createsuperuser
@@ -179,7 +179,7 @@ example, if you are running Toaster locally, use the following URL::
179 http://127.0.0.1:8000/admin 179 http://127.0.0.1:8000/admin
180 180
181You can use the Django administration interface to set Toaster configuration 181You can use the Django administration interface to set Toaster configuration
182parameters such as the build directory, layer sources, default variable 182parameters such as the :term:`Build Directory`, layer sources, default variable
183values, and BitBake versions. 183values, and BitBake versions.
184 184
185Setting Up a Production Instance of Toaster 185Setting Up a Production Instance of Toaster
@@ -317,8 +317,7 @@ Perform the following steps to install Toaster:
317 the ":ref:`toaster-manual/reference:Configuring Toaster`" section. 317 the ":ref:`toaster-manual/reference:Configuring Toaster`" section.
318 318
319 This line also runs the ``checksettings`` command, which configures 319 This line also runs the ``checksettings`` command, which configures
320 the location of the Toaster :term:`Build Directory`. 320 the location of the Toaster :term:`Build Directory`. The Toaster
321 The Toaster
322 root directory ``TOASTER_DIR`` determines where the Toaster build 321 root directory ``TOASTER_DIR`` determines where the Toaster build
323 directory is created on the file system. In the example above, 322 directory is created on the file system. In the example above,
324 ``TOASTER_DIR`` is set as follows:: 323 ``TOASTER_DIR`` is set as follows::
@@ -326,7 +325,7 @@ Perform the following steps to install Toaster:
326 /var/www/toaster/poky 325 /var/www/toaster/poky
327 326
328 327
329 This setting causes the Toaster build directory to be:: 328 This setting causes the Toaster :term:`Build Directory` to be::
330 329
331 /var/www/toaster/poky/build 330 /var/www/toaster/poky/build
332 331