manuals: update references to buildtools

Also fix number of corresponding paragraphs

(From yocto-docs rev: 28ee2d91fe4dd0549940dc5df1ff1d59363fcc0f)

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Steve Sakoman <steve@sakoman.com>

1 files changed, 41 insertions, 46 deletions

diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
index e0b8400178..1a6f7647b6 100644
--- a/documentation/ref-manual/system-requirements.rst
+++ b/documentation/ref-manual/system-requirements.rst
@@ -276,8 +276,10 @@ supported CentOS-8 Linux distribution:
       $ sudo dnf install make python3-pip which
       &PIP3_HOST_PACKAGES_DOC;
 
-Required Git, tar, Python and gcc Versions
-==========================================
+.. _system-requirements-buildtools:
+
+Required Git, tar, Python, make and gcc Versions
+================================================
 
 In order to use the build system, your host development system must meet
 the following version requirements for Git, tar, and Python:
@@ -288,10 +290,12 @@ the following version requirements for Git, tar, and Python:
 
 -  Python &MIN_PYTHON_VERSION; or greater
 
+-  GNU make &MIN_MAKE_VERSION; or greater
+
 If your host development system does not meet all these requirements,
-you can resolve this by installing a ``buildtools`` tarball that
-contains these tools. You can get the tarball one of two ways: download
-a pre-built tarball or use BitBake to build the tarball.
+you can resolve this by installing a :term:`buildtools` tarball that
+contains these tools. You can either download a pre-built tarball or
+use BitBake to build one.
 
 In addition, your host development system must meet the following
 version requirement for gcc:
@@ -299,26 +303,26 @@ version requirement for gcc:
 -  gcc &MIN_GCC_VERSION; or greater
 
 If your host development system does not meet this requirement, you can
-resolve this by installing a ``buildtools-extended`` tarball that
+resolve this by installing a :term:`buildtools-extended` tarball that
 contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential``
 package.
 
 For systems with a broken make version (e.g. make 4.2.1 without patches) but
-where the rest of the host tools are usable, you can use the ``buildtools-make``
+where the rest of the host tools are usable, you can use the :term:`buildtools-make`
 tarball instead.
 
 In the sections that follow, three different methods will be described for
-installing the ``buildtools``, ``buildtools-extended`` or ``buildtools-make``
+installing the :term:`buildtools`, :term:`buildtools-extended` or :term:`buildtools-make`
 toolset.
 
 Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script
 --------------------------------------------------------------------------------
 
 The ``install-buildtools`` script is the easiest of the three methods by
-which you can get these tools. It downloads a pre-built buildtools
+which you can get these tools. It downloads a pre-built :term:`buildtools`
 installer and automatically installs the tools for you:
 
-1. Execute the ``install-buildtools`` script. Here is an example::
+#. Execute the ``install-buildtools`` script. Here is an example::
 
       $ cd poky
       $ scripts/install-buildtools \
@@ -327,7 +331,7 @@ installer and automatically installs the tools for you:
         --release yocto-&DISTRO; \
         --installer-version &DISTRO;
 
-   During execution, the buildtools tarball will be downloaded, the
+   During execution, the :term:`buildtools` tarball will be downloaded, the
    checksum of the download will be verified, the installer will be run
    for you, and some basic checks will be run to make sure the
    installation is functional.
@@ -338,7 +342,7 @@ installer and automatically installs the tools for you:
       /path/to/poky/buildtools
 
    If your host development system needs the additional tools provided
-   in the ``buildtools-extended`` tarball, you can instead execute the
+   in the :term:`buildtools-extended` tarball, you can instead execute the
    ``install-buildtools`` script with the default parameters::
 
       $ cd poky
@@ -346,24 +350,21 @@ installer and automatically installs the tools for you:
 
    Alternatively if your host development system has a broken ``make``
    version such that you only need a known good version of ``make``,
-   you can use the ``--make-only`` option:
+   you can use the ``--make-only`` option::
 
       $ cd poky
       $ scripts/install-buildtools --make-only
 
-2. Source the tools environment setup script by using a command like the
+#. Source the tools environment setup script by using a command like the
    following::
 
       $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux
 
-   Of course, you need to supply your installation directory and be sure to
-   use the right file (i.e. i586 or x86_64).
-
    After you have sourced the setup script, the tools are added to
    ``PATH`` and any other environment variables required to run the
    tools are initialized. The results are working versions versions of
    Git, tar, Python and ``chrpath``. And in the case of the
-   ``buildtools-extended`` tarball, additional working versions of tools
+   :term:`buildtools-extended` tarball, additional working versions of tools
    including ``gcc``, ``make`` and the other tools included in
    ``packagegroup-core-buildessential``.
 
@@ -371,12 +372,14 @@ Downloading a Pre-Built ``buildtools`` Tarball
 ----------------------------------------------
 
 If you would prefer not to use the ``install-buildtools`` script, you can instead
-download and run a pre-built buildtools installer yourself with the following
+download and run a pre-built :term:`buildtools` installer yourself with the following
 steps:
 
-1. Locate and download the ``*.sh`` at :yocto_dl:`/releases/yocto/yocto-&DISTRO;/buildtools/`
+#. Go to :yocto_dl:`/releases/yocto/yocto-&DISTRO;/buildtools/`, locate and
+   download the ``.sh`` file corresponding to your host architecture
+   and to :term:`buildtools`, :term:`buildtools-extended` or :term:`buildtools-make`.
 
-2. Execute the installation script. Here is an example for the
+#. Execute the installation script. Here is an example for the
    traditional installer::
 
       $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
@@ -393,44 +396,40 @@ steps:
    installation directory. For example, you could choose the following:
    ``/home/your-username/buildtools``
 
-3. Source the tools environment setup script by using a command like the
-   following::
+#. As instructed by the installer script, you will have to source the tools
+   environment setup script::
 
-      $ source /home/your_username/buildtools/environment-setup-i586-poky-linux
-
-   Of
-   course, you need to supply your installation directory and be sure to
-   use the right file (i.e. i585 or x86-64).
+      $ source /home/your_username/buildtools/environment-setup-x86_64-pokysdk-linux
 
    After you have sourced the setup script, the tools are added to
    ``PATH`` and any other environment variables required to run the
    tools are initialized. The results are working versions versions of
    Git, tar, Python and ``chrpath``. And in the case of the
-   ``buildtools-extended`` tarball, additional working versions of tools
+   :term:`buildtools-extended` tarball, additional working versions of tools
    including ``gcc``, ``make`` and the other tools included in
    ``packagegroup-core-buildessential``.
 
 Building Your Own ``buildtools`` Tarball
 ----------------------------------------
 
-Building and running your own buildtools installer applies only when you
+Building and running your own :term:`buildtools` installer applies only when you
 have a build host that can already run BitBake. In this case, you use
 that machine to build the ``.sh`` file and then take steps to transfer
 and run it on a machine that does not meet the minimal Git, tar, and
 Python (or gcc) requirements.
 
-Here are the steps to take to build and run your own buildtools
+Here are the steps to take to build and run your own :term:`buildtools`
 installer:
 
-1. On the machine that is able to run BitBake, be sure you have set up
+#. On the machine that is able to run BitBake, be sure you have set up
    your build environment with the setup script
    (:ref:`structure-core-script`).
 
-2. Run the BitBake command to build the tarball::
+#. Run the BitBake command to build the tarball::
 
       $ bitbake buildtools-tarball
 
-   or run the BitBake command to build the extended tarball::
+   or to build the extended tarball::
 
       $ bitbake buildtools-extended-tarball
 
@@ -446,22 +445,21 @@ installer:
    Once the build completes, you can find the ``.sh`` file that installs
    the tools in the ``tmp/deploy/sdk`` subdirectory of the
    :term:`Build Directory`. The installer file has the string
-   "buildtools" (or "buildtools-extended") in the name.
+   "buildtools" or "buildtools-extended" in the name.
 
-3. Transfer the ``.sh`` file from the build host to the machine that
+#. Transfer the ``.sh`` file from the build host to the machine that
    does not meet the Git, tar, or Python (or gcc) requirements.
 
-4. On the machine that does not meet the requirements, run the ``.sh``
-   file to install the tools. Here is an example for the traditional
-   installer::
+#. On this machine, run the ``.sh`` file to install the tools. Here is an
+   example for the traditional installer::
 
       $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
 
-   Here is an example for the extended installer::
+   For the extended installer::
 
       $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
 
-   or for the make-only installer::
+   And for the make-only installer::
 
       $ sh ~/Downloads/x86_64-buildtools-make-nativesdk-standalone-&DISTRO;.sh
 
@@ -469,18 +467,15 @@ installer:
    installation directory. For example, you could choose the following:
    ``/home/your_username/buildtools``
 
-5. Source the tools environment setup script by using a command like the
+#. Source the tools environment setup script by using a command like the
    following::
 
       $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux
 
-   Of course, you need to supply your installation directory and be sure to
-   use the right file (i.e. i586 or x86_64).
-
    After you have sourced the setup script, the tools are added to
    ``PATH`` and any other environment variables required to run the
    tools are initialized. The results are working versions versions of
    Git, tar, Python and ``chrpath``. And in the case of the
-   ``buildtools-extended`` tarball, additional working versions of tools
+   :term:`buildtools-extended` tarball, additional working versions of tools
    including ``gcc``, ``make`` and the other tools included in
    ``packagegroup-core-buildessential``.