Complete Yocto mirror with license table for TQMa6UL (2038-compliance)

- 264 license table entries with exact download URLs (224/264 resolved)
- Complete sources/ directory with all BitBake recipes
- Build configuration: tqma6ul-multi-mba6ulx, spaetzle (musl)
- Full traceability for Softwarefreigabeantrag
- GCC 13.4.0, Linux 6.6.102, U-Boot 2023.04, musl 1.2.4
- License distribution: GPL-2.0 (24), MIT (23), GPL-2.0+ (18), BSD-3 (16)

sources/poky/documentation/sdk-manual/appendix-customizing-standard.rst

@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+****************************
+Customizing the Standard SDK
+****************************
+
+This appendix presents customizations you can apply to the standard SDK.
+
+Adding Individual Packages to the Standard SDK
+==============================================
+
+When you build a standard SDK using the ``bitbake -c populate_sdk``, a
+default set of packages is included in the resulting SDK. The
+:term:`TOOLCHAIN_HOST_TASK`
+and
+:term:`TOOLCHAIN_TARGET_TASK`
+variables control the set of packages adding to the SDK.
+
+If you want to add individual packages to the toolchain that runs on the
+host, simply add those packages to the :term:`TOOLCHAIN_HOST_TASK` variable.
+Similarly, if you want to add packages to the default set that is part
+of the toolchain that runs on the target, add the packages to the
+:term:`TOOLCHAIN_TARGET_TASK` variable.
+
+Adding API Documentation to the Standard SDK
+============================================
+
+You can include API documentation as well as any other documentation
+provided by recipes with the standard SDK by adding "api-documentation"
+to the
+:term:`DISTRO_FEATURES`
+variable: DISTRO_FEATURES:append = " api-documentation" Setting this
+variable as shown here causes the OpenEmbedded build system to build the
+documentation and then include it in the standard SDK.

sources/poky/documentation/sdk-manual/appendix-customizing.rst

@@ -0,0 +1,358 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+***************************************************
+Customizing the Extensible SDK standalone installer
+***************************************************
+
+This appendix describes customizations you can apply to the extensible
+SDK when using in the standalone installer version.
+
+.. note::
+
+   It is also possible to use the Extensible SDK functionality directly in a
+   Yocto build, avoiding separate installer artefacts. Please refer to
+   ":ref:`sdk-manual/extensible:Installing the Extensible SDK`"
+
+Configuring the Extensible SDK
+==============================
+
+The extensible SDK primarily consists of a pre-configured copy of the
+OpenEmbedded build system from which it was produced. Thus, the SDK's
+configuration is derived using that build system and the filters shown
+in the following list. When these filters are present, the OpenEmbedded
+build system applies them against ``local.conf`` and ``auto.conf``:
+
+-  Variables whose values start with "/" are excluded since the
+   assumption is that those values are paths that are likely to be
+   specific to the :term:`Build Host`.
+
+-  Variables listed in
+   :term:`ESDK_LOCALCONF_REMOVE`
+   are excluded. These variables are not allowed through from the
+   OpenEmbedded build system configuration into the extensible SDK
+   configuration. Typically, these variables are specific to the machine
+   on which the build system is running and could be problematic as part
+   of the extensible SDK configuration.
+
+   For a list of the variables excluded by default, see the
+   :term:`ESDK_LOCALCONF_REMOVE`
+   in the glossary of the Yocto Project Reference Manual.
+
+-  Variables listed in
+   :term:`ESDK_LOCALCONF_ALLOW`
+   are included. Including a variable in the value of
+   :term:`ESDK_LOCALCONF_ALLOW` overrides either of the previous two
+   filters. The default value is blank.
+
+-  Classes inherited globally with :term:`INHERIT` that are listed in
+   :term:`ESDK_CLASS_INHERIT_DISABLE` are disabled. Using
+   :term:`ESDK_CLASS_INHERIT_DISABLE` to disable these classes is the typical
+   method to disable classes that are problematic or unnecessary in the SDK
+   context. The default value disables the
+   :ref:`ref-classes-buildhistory` and :ref:`ref-classes-icecc` classes.
+
+Additionally, the contents of ``conf/sdk-extra.conf``, when present, are
+appended to the end of ``conf/local.conf`` within the produced SDK,
+without any filtering. The ``sdk-extra.conf`` file is particularly
+useful if you want to set a variable value just for the SDK and not the
+OpenEmbedded build system used to create the SDK.
+
+Adjusting the Extensible SDK to Suit Your Build Host's Setup
+============================================================
+
+In most cases, the extensible SDK defaults should work with your :term:`Build
+Host`'s setup. However, there are cases when you might consider making
+adjustments:
+
+-  If your SDK configuration inherits additional classes using the
+   :term:`INHERIT` variable and you
+   do not need or want those classes enabled in the SDK, you can
+   disable them by adding them to the :term:`ESDK_CLASS_INHERIT_DISABLE`
+   variable as described in the previous section.
+
+   .. note::
+
+      The default value of :term:`ESDK_CLASS_INHERIT_DISABLE`
+      is set using the "?=" operator. Consequently, you will need to
+      either define the entire list by using the "=" operator, or you
+      will need to append a value using either ":append" or the "+="
+      operator. You can learn more about these operators in the
+      ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`"
+      section of the BitBake User Manual.
+
+-  If you have classes or recipes that add additional tasks to the
+   standard build flow (i.e. the tasks execute as the recipe builds as
+   opposed to being called explicitly), then you need to do one of the
+   following:
+
+   -  After ensuring the tasks are :ref:`shared
+      state <overview-manual/concepts:shared state cache>` tasks (i.e. the
+      output of the task is saved to and can be restored from the shared
+      state cache) or ensuring the tasks are able to be produced quickly
+      from a task that is a shared state task, add the task name to the
+      value of
+      :term:`SDK_RECRDEP_TASKS`.
+
+   -  Disable the tasks if they are added by a class and you do not need
+      the functionality the class provides in the extensible SDK. To
+      disable the tasks, add the class to the :term:`ESDK_CLASS_INHERIT_DISABLE`
+      variable as described in the previous section.
+
+-  Generally, you want to have a shared state mirror set up so users of
+   the SDK can add additional items to the SDK after installation
+   without needing to build the items from source. See the
+   ":ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`"
+   section for information.
+
+-  If you want users of the SDK to be able to easily update the SDK, you
+   need to set the
+   :term:`SDK_UPDATE_URL`
+   variable. For more information, see the
+   ":ref:`sdk-manual/appendix-customizing:providing updates to the extensible sdk after installation`"
+   section.
+
+-  If you have adjusted the list of files and directories that appear in
+   :term:`COREBASE` (other than
+   layers that are enabled through ``bblayers.conf``), then you must
+   list these files in
+   :term:`COREBASE_FILES` so
+   that the files are copied into the SDK.
+
+-  If your OpenEmbedded build system setup uses a different environment
+   setup script other than
+   :ref:`structure-core-script`, then you must
+   set
+   :term:`OE_INIT_ENV_SCRIPT`
+   to point to the environment setup script you use.
+
+   .. note::
+
+      You must also reflect this change in the value used for the
+      :term:`COREBASE_FILES` variable as previously described.
+
+Changing the Extensible SDK Installer Title
+===========================================
+
+You can change the displayed title for the SDK installer by setting the
+:term:`SDK_TITLE` variable and then
+rebuilding the SDK installer. For information on how to build an SDK
+installer, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
+section.
+
+By default, this title is derived from
+:term:`DISTRO_NAME` when it is
+set. If the :term:`DISTRO_NAME` variable is not set, the title is derived
+from the :term:`DISTRO` variable.
+
+The
+:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
+class defines the default value of the :term:`SDK_TITLE` variable as
+follows::
+
+   SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
+
+While there are several ways of changing this variable, an efficient method is
+to set the variable in your distribution's configuration file. Doing so
+creates an SDK installer title that applies across your distribution. As
+an example, assume you have your own layer for your distribution named
+"meta-mydistro" and you are using the same type of file hierarchy as
+does the default "poky" distribution. If so, you could update the
+:term:`SDK_TITLE` variable in the
+``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
+form::
+
+   SDK_TITLE = "your_title"
+
+Providing Updates to the Extensible SDK After Installation
+==========================================================
+
+When you make changes to your configuration or to the metadata and if
+you want those changes to be reflected in installed SDKs, you need to
+perform additional steps. These steps make it possible for anyone using
+the installed SDKs to update the installed SDKs by using the
+``devtool sdk-update`` command:
+
+#. Create a directory that can be shared over HTTP or HTTPS. You can do
+   this by setting up a web server such as an :wikipedia:`Apache HTTP Server
+   <Apache_HTTP_Server>` or :wikipedia:`Nginx <Nginx>` server in the cloud
+   to host the directory. This directory must contain the published SDK.
+
+#. Set the
+   :term:`SDK_UPDATE_URL`
+   variable to point to the corresponding HTTP or HTTPS URL. Setting
+   this variable causes any SDK built to default to that URL and thus,
+   the user does not have to pass the URL to the ``devtool sdk-update``
+   command as described in the
+   ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
+   section.
+
+#. Build the extensible SDK normally (i.e., use the
+   ``bitbake -c populate_sdk_ext`` imagename command).
+
+#. Publish the SDK using the following command::
+
+      $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory
+
+   You must
+   repeat this step each time you rebuild the SDK with changes that you
+   want to make available through the update mechanism.
+
+Completing the above steps allows users of the existing installed SDKs
+to simply run ``devtool sdk-update`` to retrieve and apply the latest
+updates. See the
+":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
+section for further information.
+
+Changing the Default SDK Installation Directory
+===============================================
+
+When you build the installer for the Extensible SDK, the default
+installation directory for the SDK is based on the
+:term:`DISTRO` and
+:term:`SDKEXTPATH` variables from
+within the
+:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
+class as follows::
+
+   SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
+
+You can
+change this default installation directory by specifically setting the
+:term:`SDKEXTPATH` variable.
+
+While there are several ways of setting this variable,
+the method that makes the most sense is to set the variable in your
+distribution's configuration file. Doing so creates an SDK installer
+default directory that applies across your distribution. As an example,
+assume you have your own layer for your distribution named
+"meta-mydistro" and you are using the same type of file hierarchy as
+does the default "poky" distribution. If so, you could update the
+:term:`SDKEXTPATH` variable in the
+``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
+form::
+
+   SDKEXTPATH = "some_path_for_your_installed_sdk"
+
+After building your installer, running it prompts the user for
+acceptance of the some_path_for_your_installed_sdk directory as the
+default location to install the Extensible SDK.
+
+Providing Additional Installable Extensible SDK Content
+=======================================================
+
+If you want the users of an extensible SDK you build to be able to add
+items to the SDK without requiring the users to build the items from
+source, you need to do a number of things:
+
+#. Ensure the additional items you want the user to be able to install
+   are already built:
+
+   -  Build the items explicitly. You could use one or more "meta"
+      recipes that depend on lists of other recipes.
+
+   -  Build the "world" target and set
+      ``EXCLUDE_FROM_WORLD:pn-``\ recipename for the recipes you do not
+      want built. See the
+      :term:`EXCLUDE_FROM_WORLD`
+      variable for additional information.
+
+#. Expose the ``sstate-cache`` directory produced by the build.
+   Typically, you expose this directory by making it available through
+   an :wikipedia:`Apache HTTP Server <Apache_HTTP_Server>` or
+   :wikipedia:`Nginx <Nginx>` server.
+
+#. Set the appropriate configuration so that the produced SDK knows how
+   to find the configuration. The variable you need to set is
+   :term:`SSTATE_MIRRORS`::
+
+      SSTATE_MIRRORS = "file://.* https://example.com/some_path/sstate-cache/PATH"
+
+   You can set the :term:`SSTATE_MIRRORS` variable in two different places:
+
+   -  If the mirror value you are setting is appropriate to be set for
+      both the OpenEmbedded build system that is actually building the
+      SDK and the SDK itself (i.e. the mirror is accessible in both
+      places or it will fail quickly on the OpenEmbedded build system
+      side, and its contents will not interfere with the build), then
+      you can set the variable in your ``local.conf`` or custom distro
+      configuration file. You can then pass the variable to the SDK by
+      adding the following::
+
+         ESDK_LOCALCONF_ALLOW = "SSTATE_MIRRORS"
+
+   -  Alternatively, if you just want to set the :term:`SSTATE_MIRRORS`
+      variable's value for the SDK alone, create a ``conf/sdk-extra.conf``
+      file either in your :term:`Build Directory` or within any
+      layer and put your :term:`SSTATE_MIRRORS` setting within that file.
+
+      .. note::
+
+         This second option is the safest option should you have any
+         doubts as to which method to use when setting
+         :term:`SSTATE_MIRRORS`
+
+Minimizing the Size of the Extensible SDK Installer Download
+============================================================
+
+By default, the extensible SDK bundles the shared state artifacts for
+everything needed to reconstruct the image for which the SDK was built.
+This bundling can lead to an SDK installer file that is a Gigabyte or
+more in size. If the size of this file causes a problem, you can build
+an SDK that has just enough in it to install and provide access to the
+``devtool command`` by setting the following in your configuration::
+
+   SDK_EXT_TYPE = "minimal"
+
+Setting
+:term:`SDK_EXT_TYPE` to
+"minimal" produces an SDK installer that is around 35 Mbytes in size,
+which downloads and installs quickly. You need to realize, though, that
+the minimal installer does not install any libraries or tools out of the
+box. These libraries and tools must be installed either "on the fly" or
+through actions you perform using ``devtool`` or explicitly with the
+``devtool sdk-install`` command.
+
+In most cases, when building a minimal SDK you need to also enable
+bringing in the information on a wider range of packages produced by the
+system. Requiring this wider range of information is particularly true
+so that ``devtool add`` is able to effectively map dependencies it
+discovers in a source tree to the appropriate recipes. Additionally, the
+information enables the ``devtool search`` command to return useful
+results.
+
+To facilitate this wider range of information, you would need to set the
+following::
+
+   SDK_INCLUDE_PKGDATA = "1"
+
+See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information.
+
+Setting the :term:`SDK_INCLUDE_PKGDATA` variable as shown causes the "world"
+target to be built so that information for all of the recipes included
+within it are available. Having these recipes available increases build
+time significantly and increases the size of the SDK installer by 30-80
+Mbytes depending on how many recipes are included in your configuration.
+
+You can use ``EXCLUDE_FROM_WORLD:pn-``\ recipename for recipes you want
+to exclude. However, it is assumed that you would need to be building
+the "world" target if you want to provide additional items to the SDK.
+Consequently, building for "world" should not represent undue overhead
+in most cases.
+
+.. note::
+
+   If you set
+   SDK_EXT_TYPE
+   to "minimal", then providing a shared state mirror is mandatory so
+   that items can be installed as needed. See the
+   :ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`
+   section for more information.
+
+You can explicitly control whether or not to include the toolchain when
+you build an SDK by setting the
+:term:`SDK_INCLUDE_TOOLCHAIN`
+variable to "1". In particular, it is useful to include the toolchain
+when you have set :term:`SDK_EXT_TYPE` to "minimal", which by default,
+excludes the toolchain. Also, it is helpful if you are building a small
+SDK for use with an IDE or some other tool where you do not want to take
+extra steps to install a toolchain.

sources/poky/documentation/sdk-manual/appendix-obtain.rst

@@ -0,0 +1,306 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+*****************
+Obtaining the SDK
+*****************
+
+Working with the SDK components directly in a Yocto build
+=========================================================
+
+Please refer to section
+":ref:`sdk-manual/extensible:Setting up the Extensible SDK environment directly in a Yocto build`"
+
+Note that to use this feature effectively either a powerful build
+machine, or a well-functioning sstate cache infrastructure is required:
+otherwise significant time could be spent waiting for components to be built
+by BitBake from source code.
+
+Working with standalone SDK Installers
+======================================
+
+Locating Pre-Built SDK Installers
+---------------------------------
+
+You can use existing, pre-built toolchains by locating and running an
+SDK installer script that ships with the Yocto Project. Using this
+method, you select and download an architecture-specific SDK installer
+and then run the script to hand-install the toolchain.
+
+Follow these steps to locate and hand-install the toolchain:
+
+#. *Go to the Installers Directory:* Go to
+   :yocto_dl:`/releases/yocto/&DISTRO_REL_LATEST_TAG;/toolchain/`
+
+#. *Open the Folder for Your Build Host:* Open the folder that matches
+   your :term:`Build Host` (i.e.
+   ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines).
+
+#. *Locate and Download the SDK Installer:* You need to find and
+   download the installer appropriate for your build host, target
+   hardware, and image type.
+
+   The installer files (``*.sh``) follow this naming convention:
+   ``poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh``:
+
+   -  ``host_system``: string representing your development system: ``i686`` or ``x86_64``
+
+   -  ``type``: string representing the image: ``sato`` or ``minimal``
+
+   -  ``arch``: string representing the target architecture such as ``cortexa57-qemuarm64``
+
+   -  ``release``: version of the Yocto Project.
+
+   .. note::
+      The standard SDK installer does not have the ``-ext`` string as
+      part of the filename.
+
+   The toolchains provided by the Yocto
+   Project are based off of the ``core-image-sato`` and
+   ``core-image-minimal`` images and contain libraries appropriate for
+   developing against those images.
+
+   For example, if your build host is a 64-bit x86 system and you need
+   an extended SDK for a 64-bit core2 QEMU target, go into the ``x86_64``
+   folder and download the following installer::
+
+      poky-glibc-x86_64-core-image-sato-core2-64-qemux86-64-toolchain-&DISTRO;.sh
+
+#. *Run the Installer:* Be sure you have execution privileges and run
+   the installer. Here is an example from the ``Downloads``
+   directory::
+
+      $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-qemux86-64-toolchain-&DISTRO;.sh
+
+   During execution of the script, you choose the root location for the
+   toolchain. See the
+   ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
+   section and the
+   ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
+   section for more information.
+
+Building an SDK Installer
+-------------------------
+
+As an alternative to locating and downloading an SDK installer, you can
+build the SDK installer. Follow these steps:
+
+#. *Set Up the Build Environment:* Be sure you are set up to use BitBake
+   in a shell. See the ":ref:`dev-manual/start:preparing the build host`" section
+   in the Yocto Project Development Tasks Manual for information on how
+   to get a build host ready that is either a native Linux machine or a
+   machine that uses CROPS.
+
+#. *Clone the ``poky`` Repository:* You need to have a local copy of the
+   Yocto Project :term:`Source Directory`
+   (i.e. a local
+   ``poky`` repository). See the ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and
+   possibly the ":ref:`dev-manual/start:checking out by branch in poky`" and
+   ":ref:`dev-manual/start:checking out by tag in poky`" sections
+   all in the Yocto Project Development Tasks Manual for information on
+   how to clone the ``poky`` repository and check out the appropriate
+   branch for your work.
+
+#. *Initialize the Build Environment:* While in the root directory of
+   the Source Directory (i.e. ``poky``), run the
+   :ref:`structure-core-script` environment
+   setup script to define the OpenEmbedded build environment on your
+   build host::
+
+      $ source oe-init-build-env
+
+   Among other things, the script creates the :term:`Build Directory`, which
+   is ``build`` in this case and is located in the Source Directory. After
+   the script runs, your current working directory is set to the ``build``
+   directory.
+
+#. *Make Sure You Are Building an Installer for the Correct Machine:*
+   Check to be sure that your :term:`MACHINE` variable in the ``local.conf``
+   file in your :term:`Build Directory` matches the architecture
+   for which you are building.
+
+#. *Make Sure Your SDK Machine is Correctly Set:* If you are building a
+   toolchain designed to run on an architecture that differs from your
+   current development host machine (i.e. the build host), be sure that
+   the :term:`SDKMACHINE` variable in the ``local.conf`` file in your
+   :term:`Build Directory` is correctly set.
+
+   .. note::
+
+      If you are building an SDK installer for the Extensible SDK, the
+      :term:`SDKMACHINE` value must be set for the architecture of the
+      machine you are using to build the installer. If :term:`SDKMACHINE`
+      is not set appropriately, the build fails and provides an error
+      message similar to the following::
+
+         The extensible SDK can currently only be built for the same
+         architecture as the machine being built on - SDK_ARCH
+         is set to i686 (likely via setting SDKMACHINE) which is
+         different from the architecture of the build machine (x86_64).
+         Unable to continue.
+
+
+#. *Build the SDK Installer:* To build the SDK installer for a standard
+   SDK and populate the SDK image, use the following command form. Be
+   sure to replace ``image`` with an image (e.g. "core-image-sato")::
+
+      $ bitbake image -c populate_sdk
+
+   You can do the same for the extensible SDK using this command form::
+
+      $ bitbake image -c populate_sdk_ext
+
+   These commands produce an SDK installer that contains the sysroot
+   that matches your target root filesystem.
+
+   When the ``bitbake`` command completes, the SDK installer will be in
+   ``tmp/deploy/sdk`` in the :term:`Build Directory`.
+
+   .. note::
+
+      -  By default, the previous BitBake command does not build static
+         binaries. If you want to use the toolchain to build these types
+         of libraries, you need to be sure your SDK has the appropriate
+         static development libraries. Use the
+         :term:`TOOLCHAIN_TARGET_TASK`
+         variable inside your ``local.conf`` file before building the
+         SDK installer. Doing so ensures that the eventual SDK
+         installation process installs the appropriate library packages
+         as part of the SDK. Here is an example using ``libc``
+         static development libraries: TOOLCHAIN_TARGET_TASK:append = "
+         libc-staticdev"
+
+#. *Run the Installer:* You can now run the SDK installer from
+   ``tmp/deploy/sdk`` in the :term:`Build Directory`. Here is an example::
+
+      $ cd poky/build/tmp/deploy/sdk
+      $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
+
+   During execution of the script, you choose the root location for the
+   toolchain. See the
+   ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
+   section and the
+   ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
+   section for more information.
+
+Extracting the Root Filesystem
+==============================
+
+After installing the toolchain, for some use cases you might need to
+separately extract a root filesystem:
+
+-  You want to boot the image using NFS.
+
+-  You want to use the root filesystem as the target sysroot.
+
+-  You want to develop your target application using the root filesystem
+   as the target sysroot.
+
+Follow these steps to extract the root filesystem:
+
+#. *Locate and Download the Tarball for the Pre-Built Root Filesystem
+   Image File:* You need to find and download the root filesystem image
+   file that is appropriate for your target system. These files are kept
+   in machine-specific folders in the
+   :yocto_dl:`Index of Releases </releases/yocto/&DISTRO_REL_LATEST_TAG;/machines/>`
+   in the "machines" directory.
+
+   The machine-specific folders of the "machines" directory contain
+   tarballs (``*.tar.bz2``) for supported machines. These directories
+   also contain flattened root filesystem image files (``*.ext4``),
+   which you can use with QEMU directly.
+
+   The pre-built root filesystem image files follow the
+   ``core-image-profile-machine.tar.bz2`` naming convention:
+
+   -  ``profile``: filesystem image's profile, such as ``minimal``,
+      ``minimal-dev`` or ``sato``. For information on these types of image
+      profiles, see the "Images" chapter in the Yocto Project Reference Manual.
+
+   -  ``machine``:  same string as the name of the parent download directory.
+
+   The root filesystems
+   provided by the Yocto Project are based off of the
+   ``core-image-sato`` and ``core-image-minimal`` images.
+
+   For example, if you plan on using a BeagleBone device as your target
+   hardware and your image is a ``core-image-sato-sdk`` image, you can
+   download the following file::
+
+      core-image-sato-sdk-beaglebone-yocto.tar.bz2
+
+#. *Initialize the Cross-Development Environment:* You must ``source``
+   the cross-development environment setup script to establish necessary
+   environment variables.
+
+   This script is located in the top-level directory in which you
+   installed the toolchain (e.g. ``poky_sdk``).
+
+   Here is an example based on the toolchain installed in the
+   ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section::
+
+      $ source poky_sdk/environment-setup-core2-64-poky-linux
+
+#. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk``
+   command and provide the root filesystem image.
+
+   Here is an example command that extracts the root filesystem
+   from a previously built root filesystem image that was downloaded
+   from the :yocto_dl:`Index of Releases </releases/yocto/&DISTRO_REL_LATEST_TAG;/machines/>`.
+   This command extracts the root filesystem into the ``core2-64-sato``
+   directory::
+
+      $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
+
+   You could now point to the target sysroot at ``beaglebone-sato``.
+
+Installed Standard SDK Directory Structure
+==========================================
+
+The following figure shows the resulting directory structure after you
+install the Standard SDK by running the ``*.sh`` SDK installation
+script:
+
+.. image:: figures/sdk-installed-standard-sdk-directory.png
+   :scale: 100%
+
+The installed SDK consists of an environment setup script for the SDK, a
+configuration file for the target, a version file for the target, and
+the root filesystem (``sysroots``) needed to develop objects for the
+target system.
+
+Within the figure, italicized text is used to indicate replaceable
+portions of the file or directory name. For example, install_dir/version
+is the directory where the SDK is installed. By default, this directory
+is ``/opt/poky/``. And, version represents the specific snapshot of the
+SDK (e.g. &DISTRO;). Furthermore, target represents the target architecture
+(e.g. ``i586``) and host represents the development system's
+architecture (e.g. ``x86_64``). Thus, the complete names of the two
+directories within the ``sysroots`` could be ``i586-poky-linux`` and
+``x86_64-pokysdk-linux`` for the target and host, respectively.
+
+Installed Extensible SDK Directory Structure
+============================================
+
+The following figure shows the resulting directory structure after you
+install the Extensible SDK by running the ``*.sh`` SDK installation
+script:
+
+.. image:: figures/sdk-installed-extensible-sdk-directory.png
+   :scale: 80%
+   :align: center
+
+The installed directory structure for the extensible SDK is quite
+different than the installed structure for the standard SDK. The
+extensible SDK does not separate host and target parts in the same
+manner as does the standard SDK. The extensible SDK uses an embedded
+copy of the OpenEmbedded build system, which has its own sysroots.
+
+Of note in the directory structure are an environment setup script for
+the SDK, a configuration file for the target, a version file for the
+target, and log files for the OpenEmbedded build system preparation
+script run by the installer and BitBake.
+
+Within the figure, italicized text is used to indicate replaceable
+portions of the file or directory name. For example, install_dir is the
+directory where the SDK is installed, which is ``poky_sdk`` by default,
+and target represents the target architecture (e.g. ``i586``).

sources/poky/documentation/sdk-manual/index.rst

@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+========================================================================================
+Yocto Project Application Development and the Extensible Software Development Kit (eSDK)
+========================================================================================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   intro
+   extensible
+   using
+   working-projects
+   appendix-obtain
+   appendix-customizing
+   appendix-customizing-standard
+
+.. include:: /boilerplate.rst

sources/poky/documentation/sdk-manual/intro.rst

@@ -0,0 +1,208 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+************
+Introduction
+************
+
+eSDK Introduction
+=================
+
+Welcome to the Yocto Project Application Development and the Extensible
+Software Development Kit (eSDK) manual. This manual
+explains how to use both the Yocto Project extensible and standard
+SDKs to develop applications and images.
+
+All SDKs consist of the following:
+
+-  *Cross-Development Toolchain*: This toolchain contains a compiler,
+   debugger, and various associated tools.
+
+-  *Libraries, Headers, and Symbols*: The libraries, headers, and
+   symbols are specific to the image (i.e. they match the image
+   against which the SDK was built).
+
+-  *Environment Setup Script*: This ``*.sh`` file, once sourced, sets up the
+   cross-development environment by defining variables and preparing for
+   SDK use.
+
+Additionally, an extensible SDK has tools that allow you to easily add
+new applications and libraries to an image, modify the source of an
+existing component, test changes on the target hardware, and easily
+integrate an application into the :term:`OpenEmbedded Build System`.
+
+You can use an SDK to independently develop and test code that is
+destined to run on some target machine. SDKs are completely
+self-contained. The binaries are linked against their own copy of
+``libc``, which results in no dependencies on the target system. To
+achieve this, the pointer to the dynamic loader is configured at install
+time since that path cannot be dynamically altered. This is the reason
+for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext``
+archives.
+
+Another feature of the SDKs is that only one set of cross-compiler
+toolchain binaries are produced for any given architecture. This feature
+takes advantage of the fact that the target hardware can be passed to
+``gcc`` as a set of compiler options. Those options are set up by the
+environment script and contained in variables such as
+:term:`CC` and
+:term:`LD`. This reduces the space needed
+for the tools. Understand, however, that every target still needs its own
+sysroot because those binaries are target-specific.
+
+The SDK development environment consists of the following:
+
+-  The self-contained SDK, which is an architecture-specific
+   cross-toolchain and matching sysroots (target and native) all built
+   by the OpenEmbedded build system (e.g. the SDK). The toolchain and
+   sysroots are based on a :term:`Metadata`
+   configuration and extensions, which allows you to cross-develop on
+   the host machine for the target hardware. Additionally, the
+   extensible SDK contains the ``devtool`` functionality.
+
+-  The Quick EMUlator (QEMU), which lets you simulate target hardware.
+   QEMU is not literally part of the SDK. You must build and include
+   this emulator separately. However, QEMU plays an important role in
+   the development process that revolves around use of the SDK.
+
+In summary, the extensible and standard SDK share many features.
+However, the extensible SDK has powerful development tools to help you
+more quickly develop applications. Here is a table that summarizes
+the primary differences between the standard and extensible SDK types
+when considering which to build:
+
++-----------------------+-----------------------+-----------------------+
+| *Feature*             | *Standard SDK*        | *Extensible SDK*      |
++=======================+=======================+=======================+
+| Toolchain             | Yes                   | Yes [1]_              |
++-----------------------+-----------------------+-----------------------+
+| Debugger              | Yes                   | Yes [1]_              |
++-----------------------+-----------------------+-----------------------+
+| Size                  | 100+ MBytes           | 1+ GBytes (or 300+    |
+|                       |                       | MBytes for minimal    |
+|                       |                       | w/toolchain)          |
++-----------------------+-----------------------+-----------------------+
+| ``devtool``           | No                    | Yes                   |
++-----------------------+-----------------------+-----------------------+
+| Build Images          | No                    | Yes                   |
++-----------------------+-----------------------+-----------------------+
+| Updateable            | No                    | Yes                   |
++-----------------------+-----------------------+-----------------------+
+| Managed Sysroot [2]_  | No                    | Yes                   |
++-----------------------+-----------------------+-----------------------+
+| Installed Packages    | No  [3]_              | Yes  [4]_             |
++-----------------------+-----------------------+-----------------------+
+| Construction          | Packages              | Shared State          |
++-----------------------+-----------------------+-----------------------+
+
+.. [1] Extensible SDK contains the toolchain and debugger if :term:`SDK_EXT_TYPE`
+       is "full" or :term:`SDK_INCLUDE_TOOLCHAIN` is "1", which is the default.
+.. [2] Sysroot is managed through the use of ``devtool``. Thus, it is less
+       likely that you will corrupt your SDK sysroot when you try to add
+       additional libraries.
+.. [3] You can add runtime package management to the standard SDK but it is not
+       supported by default.
+.. [4] You must build and make the shared state available to extensible SDK
+       users for "packages" you want to enable users to install.
+
+The Cross-Development Toolchain
+-------------------------------
+
+The :term:`Cross-Development Toolchain` consists
+of a cross-compiler, cross-linker, and cross-debugger that are used to
+develop user-space applications for targeted hardware; in addition,
+the extensible SDK comes with built-in ``devtool``
+functionality. This toolchain is created by running a SDK installer
+script or through a :term:`Build Directory` that is based on
+your metadata configuration or extension for your targeted device. The
+cross-toolchain works with a matching target sysroot.
+
+Sysroots
+--------
+
+The native and target sysroots contain needed headers and libraries for
+generating binaries that run on the target architecture. The target
+sysroot is based on the target root filesystem image that is built by
+the OpenEmbedded build system and uses the same metadata configuration
+used to build the cross-toolchain.
+
+The QEMU Emulator
+-----------------
+
+The QEMU emulator allows you to simulate your hardware while running
+your application or image. QEMU is not part of the SDK but is
+automatically installed and available if you have done any one of
+the following:
+
+-  cloned the ``poky`` Git repository to create a
+   :term:`Source Directory` and sourced the environment setup script.
+
+-  downloaded a Yocto Project release and unpacked it to
+   create a Source Directory and sourced the environment setup
+   script.
+
+-  installed the cross-toolchain tarball and
+   sourced the toolchain's setup environment script.
+
+SDK Development Model
+=====================
+
+Fundamentally, the SDK fits into the development process as follows:
+
+.. image:: figures/sdk-environment.png
+   :width: 100%
+
+The SDK is installed on any machine and can be used to develop applications,
+images, and kernels. An SDK can even be used by a QA Engineer or Release
+Engineer. The fundamental concept is that the machine that has the SDK
+installed does not have to be associated with the machine that has the
+Yocto Project installed. A developer can independently compile and test
+an object on their machine and then, when the object is ready for
+integration into an image, they can simply make it available to the
+machine that has the Yocto Project. Once the object is available, the
+image can be rebuilt using the Yocto Project to produce the modified
+image.
+
+You just need to follow these general steps:
+
+#. *Install the SDK for your target hardware:* For information on how to
+   install the SDK, see the ":ref:`sdk-manual/using:installing the sdk`"
+   section.
+
+#. *Download or Build the Target Image:* The Yocto Project supports
+   several target architectures and has many pre-built kernel images and
+   root filesystem images.
+
+   If you are going to develop your application on hardware, go to the
+   :yocto_dl:`machines </releases/yocto/&DISTRO_REL_LATEST_TAG;/machines/>` download area and choose a
+   target machine area from which to download the kernel image and root
+   filesystem. This download area could have several files in it that
+   support development using actual hardware. For example, the area
+   might contain ``.hddimg`` files that combine the kernel image with
+   the filesystem, boot loaders, and so forth. Be sure to get the files
+   you need for your particular development process.
+
+   If you are going to develop your application and then run and test it
+   using the QEMU emulator, go to the
+   :yocto_dl:`machines/qemu </releases/yocto/&DISTRO_REL_LATEST_TAG;/machines/qemu>` download area. From this
+   area, go down into the directory for your target architecture (e.g.
+   ``qemux86_64`` for an Intel-based 64-bit architecture). Download the
+   kernel, root filesystem, and any other files you need for your
+   process.
+
+   .. note::
+
+      To use the root filesystem in QEMU, you need to extract it. See the
+      ":ref:`sdk-manual/appendix-obtain:extracting the root filesystem`"
+      section for information on how to do this extraction.
+
+#. *Develop and Test your Application:* At this point, you have the
+   tools to develop your application. If you need to separately install
+   and use the QEMU emulator, you can go to `QEMU Home
+   Page <https://wiki.qemu.org/Main_Page>`__ to download and learn about
+   the emulator. See the ":doc:`/dev-manual/qemu`" chapter in the
+   Yocto Project Development Tasks Manual for information on using QEMU
+   within the Yocto Project.
+
+The remainder of this manual describes how to use the extensible and
+standard SDKs. There is also information in appendix form describing
+how you can build, install, and modify an SDK.

sources/poky/documentation/sdk-manual/using.rst

@@ -0,0 +1,147 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+**********************
+Using the Standard SDK
+**********************
+
+This chapter describes the standard SDK and how to install it.
+Information includes unique installation and setup aspects for the
+standard SDK.
+
+.. note::
+
+   For a side-by-side comparison of main features supported for a
+   standard SDK as compared to an extensible SDK, see the
+   ":ref:`sdk-manual/intro:introduction`" section.
+
+You can use a standard SDK to work on Makefile and Autotools-based
+projects. See the
+":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter
+for more information.
+
+Why use the Standard SDK and What is in It?
+===========================================
+
+The Standard SDK provides a cross-development toolchain and libraries
+tailored to the contents of a specific image. You would use the Standard
+SDK if you want a more traditional toolchain experience as compared to
+the extensible SDK, which provides an internal build system and the
+``devtool`` functionality.
+
+The installed Standard SDK consists of several files and directories.
+Basically, it contains an SDK environment setup script, some
+configuration files, and host and target root filesystems to support
+usage. You can see the directory structure in the
+":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
+section.
+
+Installing the SDK
+==================
+
+The first thing you need to do is install the SDK on your :term:`Build
+Host` by running the ``*.sh`` installation script.
+
+You can download a tarball installer, which includes the pre-built
+toolchain, the ``runqemu`` script, and support files from the
+appropriate :yocto_dl:`toolchain </releases/yocto/&DISTRO_REL_LATEST_TAG;/toolchain/>` directory within
+the Index of Releases. Toolchains are available for several 32-bit and
+64-bit architectures with the ``x86_64`` directories, respectively. The
+toolchains the Yocto Project provides are based off the
+``core-image-sato`` and ``core-image-minimal`` images and contain
+libraries appropriate for developing against the corresponding image.
+
+The names of the tarball installer scripts are such that a string
+representing the host system appears first in the filename and then is
+immediately followed by a string representing the target architecture::
+
+   poky-glibc-host_system-image_type-arch-toolchain-release_version.sh
+
+   Where:
+       host_system is a string representing your development system:
+
+                  i686 or x86_64.
+
+       image_type is the image for which the SDK was built:
+
+                  core-image-minimal or core-image-sato.
+
+       arch is a string representing the tuned target architecture:
+
+                  aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon.
+
+       release_version is a string representing the release number of the Yocto Project:
+
+                  &DISTRO;, &DISTRO;+snapshot
+
+For example, the following SDK installer is for a 64-bit
+development host system and a i586-tuned target architecture based off
+the SDK for ``core-image-sato`` and using the current DISTRO snapshot::
+
+   poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh
+
+.. note::
+
+   As an alternative to downloading an SDK, you can build the SDK
+   installer. For information on building the installer, see the
+   ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
+   section.
+
+The SDK and toolchains are self-contained and by default are installed
+into the ``poky_sdk`` folder in your home directory. You can choose to
+install the extensible SDK in any location when you run the installer.
+However, because files need to be written under that directory during
+the normal course of operation, the location you choose for installation
+must be writable for whichever users need to use the SDK.
+
+The following command shows how to run the installer given a toolchain
+tarball for a 64-bit x86 development host system and a 64-bit x86 target
+architecture. The example assumes the SDK installer is located in
+``~/Downloads/`` and has execution rights::
+
+   $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+   Poky (Yocto Project Reference Distro) SDK installer version &DISTRO;
+   ===============================================================
+   Enter target directory for SDK (default: /opt/poky/&DISTRO;):
+   You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed [Y/n]? Y
+   Extracting SDK........................................ ..............................done
+   Setting it up...done
+   SDK has been successfully set up and is ready to be used.
+   Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
+    $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+
+.. note::
+
+   If you do not have write permissions for the directory into which you
+   are installing the SDK, the installer notifies you and exits. For
+   that case, set up the proper permissions in the directory and run the
+   installer again.
+
+Again, reference the
+":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
+section for more details on the resulting directory structure of the installed
+SDK.
+
+Running the SDK Environment Setup Script
+========================================
+
+Once you have the SDK installed, you must run the SDK environment setup
+script before you can actually use the SDK. This setup script resides in
+the directory you chose when you installed the SDK, which is either the
+default ``/opt/poky/&DISTRO;`` directory or the directory you chose during
+installation.
+
+Before running the script, be sure it is the one that matches the
+architecture for which you are developing. Environment setup scripts
+begin with the string "``environment-setup``" and include as part of
+their name the tuned target architecture. As an example, the following
+commands set the working directory to where the SDK was installed and
+then source the environment setup script. In this example, the setup
+script is for an IA-based target machine using i586 tuning::
+
+   $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+
+When you run the
+setup script, the same environment variables are defined as are when you
+run the setup script for an extensible SDK. See the
+":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
+section for more information.

sources/poky/documentation/sdk-manual/working-projects.rst

@@ -0,0 +1,403 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+********************************
+Using the SDK Toolchain Directly
+********************************
+
+You can use the SDK toolchain directly with Makefile and Autotools-based
+projects.
+
+Autotools-Based Projects
+========================
+
+Once you have a suitable :ref:`sdk-manual/intro:the cross-development toolchain`
+installed, it is very easy to develop a project using the :wikipedia:`GNU
+Autotools-based <GNU_Build_System>` workflow, which is outside of the
+:term:`OpenEmbedded Build System`.
+
+The following figure presents a simple Autotools workflow.
+
+.. image:: figures/sdk-autotools-flow.png
+   :align: center
+   :width: 70%
+
+Follow these steps to create a simple Autotools-based "Hello World"
+project:
+
+.. note::
+
+   For more information on the GNU Autotools workflow, see the same
+   example on the
+   GNOME Developer
+   site.
+
+#. *Create a Working Directory and Populate It:* Create a clean
+   directory for your project and then make that directory your working
+   location::
+
+      $ mkdir $HOME/helloworld
+      $ cd $HOME/helloworld
+
+   After setting up the directory, populate it with files needed for the flow.
+   You need a project source file, a file to help with configuration,
+   and a file to help create the Makefile, and a README file:
+   ``hello.c``, ``configure.ac``, ``Makefile.am``, and ``README``,
+   respectively.
+
+   Use the following command to create an empty README file, which is
+   required by GNU Coding Standards::
+
+      $ touch README
+
+   Create the remaining
+   three files as follows:
+
+   -  ``hello.c``::
+
+         #include <stdio.h>
+
+         main()
+             {
+                 printf("Hello World!\n");
+             }
+
+   -  ``configure.ac``::
+
+         AC_INIT(hello,0.1)
+         AM_INIT_AUTOMAKE([foreign])
+         AC_PROG_CC
+         AC_CONFIG_FILES(Makefile)
+         AC_OUTPUT
+
+   -  ``Makefile.am``::
+
+         bin_PROGRAMS = hello
+         hello_SOURCES = hello.c
+
+#. *Source the Cross-Toolchain Environment Setup File:* As described
+   earlier in the manual, installing the cross-toolchain creates a
+   cross-toolchain environment setup script in the directory that the
+   SDK was installed. Before you can use the tools to develop your
+   project, you must source this setup script. The script begins with
+   the string "environment-setup" and contains the machine architecture,
+   which is followed by the string "poky-linux". For this example, the
+   command sources a script from the default SDK installation directory
+   that uses the 32-bit Intel x86 Architecture and the &DISTRO; Yocto
+   Project release::
+
+      $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+
+   Another example is sourcing the environment setup directly in a Yocto
+   build::
+
+      $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux
+
+#. *Create the configure Script:* Use the ``autoreconf`` command to
+   generate the ``configure`` script::
+
+      $ autoreconf
+
+   The ``autoreconf``
+   tool takes care of running the other Autotools such as ``aclocal``,
+   ``autoconf``, and ``automake``.
+
+   .. note::
+
+      If you get errors from ``configure.ac``, which ``autoreconf``
+      runs, that indicate missing files, you can use the "-i" option,
+      which ensures missing auxiliary files are copied to the build
+      host.
+
+#. *Cross-Compile the Project:* This command compiles the project using
+   the cross-compiler. The
+   :term:`CONFIGURE_FLAGS`
+   environment variable provides the minimal arguments for GNU
+   configure::
+
+      $ ./configure ${CONFIGURE_FLAGS}
+
+   For an Autotools-based
+   project, you can use the cross-toolchain by just passing the
+   appropriate host option to ``configure.sh``. The host option you use
+   is derived from the name of the environment setup script found in the
+   directory in which you installed the cross-toolchain. For example,
+   the host option for an ARM-based target that uses the GNU EABI is
+   ``armv5te-poky-linux-gnueabi``. You will notice that the name of the
+   script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the
+   following command works to update your project and rebuild it using
+   the appropriate cross-toolchain tools::
+
+     $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
+
+#. *Make and Install the Project:* These two commands generate and
+   install the project into the destination directory::
+
+      $ make
+      $ make install DESTDIR=./tmp
+
+   .. note::
+
+      To learn about environment variables established when you run the
+      cross-toolchain environment setup script and how they are used or
+      overridden by the Makefile, see the
+      :ref:`sdk-manual/working-projects:makefile-based projects` section.
+
+   This next command is a simple way to verify the installation of your
+   project. Running the command prints the architecture on which the
+   binary file can run. This architecture should be the same
+   architecture that the installed cross-toolchain supports::
+
+      $ file ./tmp/usr/local/bin/hello
+
+#. *Execute Your Project:* To execute the project, you would need to run
+   it on your target hardware. If your target hardware happens to be
+   your build host, you could run the project as follows::
+
+      $ ./tmp/usr/local/bin/hello
+
+   As expected, the project displays the "Hello World!" message.
+
+Makefile-Based Projects
+=======================
+
+Simple Makefile-based projects use and interact with the cross-toolchain
+environment variables established when you run the cross-toolchain
+environment setup script. The environment variables are subject to
+general ``make`` rules.
+
+This section presents a simple Makefile development flow and provides an
+example that lets you see how you can use cross-toolchain environment
+variables and Makefile variables during development.
+
+.. image:: figures/sdk-makefile-flow.png
+   :align: center
+   :width: 70%
+
+The main point of this section is to explain the following three cases
+regarding variable behavior:
+
+-  *Case 1 --- No Variables Set in the Makefile Map to Equivalent
+   Environment Variables Set in the SDK Setup Script:* Because matching
+   variables are not specifically set in the ``Makefile``, the variables
+   retain their values based on the environment setup script.
+
+-  *Case 2 --- Variables Are Set in the Makefile that Map to Equivalent
+   Environment Variables from the SDK Setup Script:* Specifically
+   setting matching variables in the ``Makefile`` during the build
+   results in the environment settings of the variables being
+   overwritten. In this case, the variables you set in the ``Makefile``
+   are used.
+
+-  *Case 3 --- Variables Are Set Using the Command Line that Map to
+   Equivalent Environment Variables from the SDK Setup Script:*
+   Executing the ``Makefile`` from the command line results in the
+   environment variables being overwritten. In this case, the
+   command-line content is used.
+
+.. note::
+
+   Regardless of how you set your variables, if you use the "-e" option
+   with ``make``, the variables from the SDK setup script take precedence::
+
+      $ make -e target
+
+
+The remainder of this section presents a simple Makefile example that
+demonstrates these variable behaviors.
+
+In a new shell environment variables are not established for the SDK
+until you run the setup script. For example, the following commands show
+a null value for the compiler variable (i.e.
+:term:`CC`)::
+
+   $ echo ${CC}
+
+   $
+
+Running the
+SDK setup script for a 64-bit build host and an i586-tuned target
+architecture for a ``core-image-sato`` image using the current &DISTRO;
+Yocto Project release and then echoing that variable shows the value
+established through the script::
+
+   $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+   $ echo ${CC}
+   i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
+
+To illustrate variable use, work through this simple "Hello World!"
+example:
+
+#. *Create a Working Directory and Populate It:* Create a clean
+   directory for your project and then make that directory your working
+   location::
+
+      $ mkdir $HOME/helloworld
+      $ cd $HOME/helloworld
+
+   After
+   setting up the directory, populate it with files needed for the flow.
+   You need a ``main.c`` file from which you call your function, a
+   ``module.h`` file to contain headers, and a ``module.c`` that defines
+   your function.
+
+   Create the three files as follows:
+
+   -  ``main.c``::
+
+         #include "module.h"
+         void sample_func();
+         int main()
+         {
+             sample_func();
+             return 0;
+         }
+
+   -  ``module.h``::
+
+         #include <stdio.h>
+         void sample_func();
+
+   -  ``module.c``::
+
+         #include "module.h"
+         void sample_func()
+         {
+             printf("Hello World!");
+             printf("\n");
+         }
+
+#. *Source the Cross-Toolchain Environment Setup File:* As described
+   earlier in the manual, installing the cross-toolchain creates a
+   cross-toolchain environment setup script in the directory that the
+   SDK was installed. Before you can use the tools to develop your
+   project, you must source this setup script. The script begins with
+   the string "environment-setup" and contains the machine architecture,
+   which is followed by the string "poky-linux". For this example, the
+   command sources a script from the default SDK installation directory
+   that uses the 32-bit Intel x86 Architecture and the &DISTRO_NAME; Yocto
+   Project release::
+
+      $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+
+   Another example is sourcing the environment setup directly in a Yocto
+   build::
+
+      $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux
+
+#. *Create the Makefile:* For this example, the Makefile contains
+   two lines that can be used to set the :term:`CC` variable. One line is
+   identical to the value that is set when you run the SDK environment
+   setup script, and the other line sets :term:`CC` to "gcc", the default
+   GNU compiler on the build host::
+
+      # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
+      # CC="gcc"
+      all: main.o module.o
+        ${CC} main.o module.o -o target_bin
+      main.o: main.c module.h
+        ${CC} -I . -c main.c
+      module.o: module.c module.h
+        ${CC} -I . -c module.c
+      clean:
+        rm -rf *.o
+        rm target_bin
+
+#. *Make the Project:* Use the ``make`` command to create the binary
+   output file. Because variables are commented out in the Makefile, the
+   value used for :term:`CC` is the value set when the SDK environment setup
+   file was run::
+
+      $ make
+      i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
+      i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
+      i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
+
+   From the results of the previous command, you can see that
+   the compiler used was the compiler established through the :term:`CC`
+   variable defined in the setup script.
+
+   You can override the :term:`CC` environment variable with the same
+   variable as set from the Makefile by uncommenting the line in the
+   Makefile and running ``make`` again::
+
+      $ make clean
+      rm -rf *.o
+      rm target_bin
+      #
+      # Edit the Makefile by uncommenting the line that sets CC to "gcc"
+      #
+      $ make
+      gcc -I . -c main.c
+      gcc -I . -c module.c
+      gcc main.o module.o -o target_bin
+
+   As shown in the previous example, the
+   cross-toolchain compiler is not used. Rather, the default compiler is
+   used.
+
+   This next case shows how to override a variable by providing the
+   variable as part of the command line. Go into the Makefile and
+   re-insert the comment character so that running ``make`` uses the
+   established SDK compiler. However, when you run ``make``, use a
+   command-line argument to set :term:`CC` to "gcc"::
+
+      $ make clean
+      rm -rf *.o
+      rm target_bin
+      #
+      # Edit the Makefile to comment out the line setting CC to "gcc"
+      #
+      $ make
+      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
+      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
+      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
+      $ make clean
+      rm -rf *.o
+      rm target_bin
+      $ make CC="gcc"
+      gcc -I . -c main.c
+      gcc -I . -c module.c
+      gcc main.o module.o -o target_bin
+
+   In the previous case, the command-line argument overrides the SDK
+   environment variable.
+
+   In this last case, edit Makefile again to use the "gcc" compiler but
+   then use the "-e" option on the ``make`` command line::
+
+      $ make clean
+      rm -rf *.o
+      rm target_bin
+      #
+      # Edit the Makefile to use "gcc"
+      #
+      $ make
+      gcc -I . -c main.c
+      gcc -I . -c module.c
+      gcc main.o module.o -o target_bin
+      $ make clean
+      rm -rf *.o
+      rm target_bin
+      $ make -e
+      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
+      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
+      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
+
+   In the previous case, the "-e" option forces ``make`` to
+   use the SDK environment variables regardless of the values in the
+   Makefile.
+
+#. *Execute Your Project:* To execute the project (i.e. ``target_bin``),
+   use the following command::
+
+      $ ./target_bin
+      Hello World!
+
+   .. note::
+
+      If you used the cross-toolchain compiler to build
+      target_bin
+      and your build host differs in architecture from that of the
+      target machine, you need to run your project on the target device.
+
+   As expected, the project displays the "Hello World!" message.