Revert "poky: subtree update:b23aa6b753..ad30a6d470"

This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.

This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.

Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c

1 files changed, 444 insertions, 0 deletions

diff --git a/poky/documentation/sdk-manual/sdk-appendix-obtain.xml b/poky/documentation/sdk-manual/sdk-appendix-obtain.xml
new file mode 100644
index 0000000000..de7f75e2bb
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-appendix-obtain.xml
@@ -0,0 +1,444 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<appendix id='sdk-appendix-obtain'>
+
+<title>Obtaining the SDK</title>
+
+<section id='sdk-locating-pre-built-sdk-installers'>
+    <title>Locating Pre-Built SDK Installers</title>
+
+    <para>
+        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.
+    </para>
+
+    <para>
+        Follow these steps to locate and hand-install the toolchain:
+        <orderedlist>
+            <listitem><para>
+                <emphasis>Go to the Installers Directory:</emphasis>
+                Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Open the Folder for Your Build Host:</emphasis>
+                Open the folder that matches your
+                <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>build host</ulink>
+                (i.e. <filename>i686</filename> for 32-bit machines or
+                <filename>x86_64</filename> for 64-bit machines).
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Locate and Download the SDK Installer:</emphasis>
+                You need to find and download the installer appropriate for
+                your build host, target hardware, and image type.
+                </para>
+
+                <para>The installer files (<filename>*.sh</filename>) follow
+                this naming convention:
+                <literallayout class='monospaced'>
+     poky-glibc-<replaceable>host_system</replaceable>-core-image-<replaceable>type</replaceable>-<replaceable>arch</replaceable>-toolchain[-ext]-<replaceable>release</replaceable>.sh
+
+     Where:
+         <replaceable>host_system</replaceable> is a string representing your development system:
+                "i686" or "x86_64"
+
+         <replaceable>type</replaceable> is a string representing the image:
+                "sato" or "minimal"
+
+         <replaceable>arch</replaceable> is a string representing the target architecture:
+                "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2",
+                "mips64", or "ppc7400"
+
+         <replaceable>release</replaceable> is the version of Yocto Project.
+
+         NOTE:
+            The standard SDK installer does not have the "-ext" string as
+            part of the filename.
+
+                </literallayout>
+                The toolchains provided by the Yocto Project are based off of
+                the <filename>core-image-sato</filename> and
+                <filename>core-image-minimal</filename> images and contain
+                libraries appropriate for developing against those images.
+                </para>
+
+                <para>For example, if your build host is a 64-bit x86 system
+                and you need an extended SDK for a 64-bit core2 target, go
+                into the <filename>x86_64</filename> folder and download the
+                following installer:
+                <literallayout class='monospaced'>
+     poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
+                </literallayout>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Run the Installer:</emphasis>
+                Be sure you have execution privileges and run the installer.
+                Following is an example from the <filename>Downloads</filename>
+                directory:
+                <literallayout class='monospaced'>
+     $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
+                </literallayout>
+                During execution of the script, you choose the root location
+                for the toolchain.
+                See the
+                "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
+                section and the
+                "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>"
+                section for more information.
+                </para></listitem>
+        </orderedlist>
+    </para>
+</section>
+
+<section id='sdk-building-an-sdk-installer'>
+    <title>Building an SDK Installer</title>
+
+    <para>
+        As an alternative to locating and downloading an SDK installer,
+        you can build the SDK installer.
+        Follow these steps:
+        <orderedlist>
+            <listitem><para>
+                <emphasis>Set Up the Build Environment:</emphasis>
+                Be sure you are set up to use BitBake in a shell.
+                See the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
+                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.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
+                You need to have a local copy of the Yocto Project
+                <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+                (i.e. a local <filename>poky</filename> repository).
+                See the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
+                and possibly the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
+                and
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
+                sections all in the Yocto Project Development Tasks Manual for
+                information on how to clone the <filename>poky</filename>
+                repository and check out the appropriate branch for your work.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Initialize the Build Environment:</emphasis>
+                While in the root directory of the Source Directory (i.e.
+                <filename>poky</filename>), run the
+                <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                environment setup script to define the OpenEmbedded
+                build environment on your build host.
+                <literallayout class='monospaced'>
+     $ source &OE_INIT_FILE;
+                </literallayout>
+                Among other things, the script creates the
+                <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+                which is <filename>build</filename> in this case
+                and is located in the Source Directory.
+                After the script runs, your current working directory
+                is set to the <filename>build</filename> directory.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Make Sure You Are Building an Installer for the Correct Machine:</emphasis>
+                Check to be sure that your
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+                variable in the <filename>local.conf</filename> file in your
+                Build Directory matches the architecture for which you are
+                building.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Make Sure Your SDK Machine is Correctly Set:</emphasis>
+                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
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
+                variable in the <filename>local.conf</filename> file in your
+                Build Directory is correctly set.
+                <note>
+                    If you are building an SDK installer for the Extensible
+                    SDK, the <filename>SDKMACHINE</filename> value must be
+                    set for the architecture of the machine you are using to
+                    build the installer.
+                    If <filename>SDKMACHINE</filename> is not set appropriately,
+                    the build fails and provides an error message similar to
+                    the following:
+                    <literallayout class='monospaced'>
+     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.
+                    </literallayout>
+                </note>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Build the SDK Installer:</emphasis>
+                To build the SDK installer for a standard SDK and populate
+                the SDK image, use the following command form.
+                Be sure to replace <replaceable>image</replaceable> with
+                an image (e.g. "core-image-sato"):
+                <literallayout class='monospaced'>
+     $ bitbake <replaceable>image</replaceable> -c populate_sdk
+                </literallayout>
+                You can do the same for the extensible SDK using this command
+                form:
+                <literallayout class='monospaced'>
+     $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext
+                </literallayout>
+                These commands produce an SDK installer that contains the
+                sysroot that matches your target root filesystem.</para>
+
+                <para>When the <filename>bitbake</filename> command completes,
+                the SDK installer will be in
+                <filename>tmp/deploy/sdk</filename> in the Build Directory.
+                <note><title>Notes</title>
+                    <itemizedlist>
+                        <listitem><para>
+                            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
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>
+                            variable inside your <filename>local.conf</filename>
+                            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.
+                            Following is an example using
+                            <filename>libc</filename> static development
+                            libraries:
+                            <literallayout class='monospaced'>
+     TOOLCHAIN_TARGET_TASK_append = " libc-staticdev"
+                            </literallayout>
+                            </para></listitem>
+                    </itemizedlist>
+                </note>
+            </para></listitem>
+            <listitem><para>
+                <emphasis>Run the Installer:</emphasis>
+                You can now run the SDK installer from
+                <filename>tmp/deploy/sdk</filename> in the Build Directory.
+                Following is an example:
+                <literallayout class='monospaced'>
+     $ cd ~/poky/build/tmp/deploy/sdk
+     $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
+                </literallayout>
+                During execution of the script, you choose the root location
+                for the toolchain.
+                See the
+                "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
+                section and the
+                "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>"
+                section for more information.
+                </para></listitem>
+        </orderedlist>
+    </para>
+</section>
+
+<section id='sdk-extracting-the-root-filesystem'>
+    <title>Extracting the Root Filesystem</title>
+
+    <para>
+        After installing the toolchain, for some use cases you
+        might need to separately extract a root filesystem:
+        <itemizedlist>
+            <listitem><para>
+                You want to boot the image using NFS.
+                </para></listitem>
+            <listitem><para>
+                You want to use the root filesystem as the
+                target sysroot.
+                </para></listitem>
+            <listitem><para>
+                You want to develop your target application
+                using the root filesystem as the target sysroot.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        Follow these steps to extract the root filesystem:
+        <orderedlist>
+            <listitem><para>
+                <emphasis>Locate and Download the Tarball for the Pre-Built
+                Root Filesystem Image File:</emphasis>
+                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
+                <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/machines/'>Index of Releases</ulink>
+                in the "machines" directory.</para>
+
+                <para>The machine-specific folders of the "machines" directory
+                contain tarballs (<filename>*.tar.bz2</filename>) for supported
+                machines.
+                These directories also contain flattened root filesystem
+                image files (<filename>*.ext4</filename>), which you can use
+                with QEMU directly.</para>
+
+                <para>The pre-built root filesystem image files
+                follow these naming conventions:
+                <literallayout class='monospaced'>
+<!--
+     core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>-<replaceable>date_time</replaceable>.rootfs.tar.bz2
+-->
+     core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>.tar.bz2
+
+     Where:
+         <replaceable>profile</replaceable> is the filesystem image's profile:
+                   lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs,
+                   sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on
+                   these types of image profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
+                   the Yocto Project Reference Manual.
+
+         <replaceable>arch</replaceable> is a string representing the target architecture:
+                   beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb,
+                   genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*.
+
+<!-->
+         <replaceable>date_time</replaceable> is a date and time stamp.
+-->
+
+                </literallayout>
+                The root filesystems provided by the Yocto Project are based
+                off of the <filename>core-image-sato</filename> and
+                <filename>core-image-minimal</filename> images.
+                </para>
+
+                <para>For example, if you plan on using a BeagleBone device
+                as your target hardware and your image is a
+                <filename>core-image-sato-sdk</filename>
+                image, you can download the following file:
+                <literallayout class='monospaced'>
+     core-image-sato-sdk-beaglebone-yocto.tar.bz2
+                </literallayout>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Initialize the Cross-Development Environment:</emphasis>
+                You must <filename>source</filename> the cross-development
+                environment setup script to establish necessary environment
+                variables.</para>
+
+                <para>This script is located in the top-level directory in
+                which you installed the toolchain (e.g.
+                <filename>poky_sdk</filename>).</para>
+
+                <para>Following is an example based on the toolchain installed
+                in the
+                "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>"
+                section:
+                <literallayout class='monospaced'>
+     $ source ~/poky_sdk/environment-setup-core2-64-poky-linux
+                </literallayout>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Extract the Root Filesystem:</emphasis>
+                Use the <filename>runqemu-extract-sdk</filename> command
+                and provide the root filesystem image.</para>
+
+                <para>Following is an example command that extracts the root
+                filesystem from a previously built root filesystem image that
+                was downloaded from the
+                <ulink url='&YOCTO_DOCS_OM_URL;#index-downloads'>Index of Releases</ulink>.
+                This command extracts the root filesystem into the
+                <filename>core2-64-sato</filename> directory:
+                <literallayout class='monospaced'>
+     $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
+                </literallayout>
+                You could now point to the target sysroot at
+                <filename>beablebone-sato</filename>.
+                </para></listitem>
+        </orderedlist>
+    </para>
+</section>
+
+<section id='sdk-installed-standard-sdk-directory-structure'>
+    <title>Installed Standard SDK Directory Structure</title>
+
+    <para>
+        The following figure shows the resulting directory structure after
+        you install the Standard SDK by running the <filename>*.sh</filename>
+        SDK installation script:
+    </para>
+
+    <para>
+        <imagedata fileref="figures/sdk-installed-standard-sdk-directory.png" scale="80" align="center" />
+    </para>
+
+    <para>
+        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 (<filename>sysroots</filename>) needed to
+        develop objects for the target system.
+    </para>
+
+    <para>
+        Within the figure, italicized text is used to indicate replaceable
+        portions of the file or directory name.
+        For example,
+        <replaceable>install_dir</replaceable>/<replaceable>version</replaceable>
+        is the directory where the SDK is installed.
+        By default, this directory is <filename>/opt/poky/</filename>.
+        And, <replaceable>version</replaceable> represents the specific
+        snapshot of the SDK (e.g. <filename>&DISTRO;</filename>).
+        Furthermore, <replaceable>target</replaceable> represents the target
+        architecture (e.g. <filename>i586</filename>) and
+        <replaceable>host</replaceable> represents the development system's
+        architecture (e.g. <filename>x86_64</filename>).
+        Thus, the complete names of the two directories within the
+        <filename>sysroots</filename> could be
+        <filename>i586-poky-linux</filename> and
+        <filename>x86_64-pokysdk-linux</filename> for the target and host,
+        respectively.
+    </para>
+</section>
+
+<section id='sdk-installed-extensible-sdk-directory-structure'>
+    <title>Installed Extensible SDK Directory Structure</title>
+
+    <para>
+        The following figure shows the resulting directory structure after
+        you install the Extensible SDK by running the <filename>*.sh</filename>
+        SDK installation script:
+    </para>
+
+    <para>
+        <imagedata fileref="figures/sdk-installed-extensible-sdk-directory.png" scale="80" align="center" />
+    </para>
+
+    <para>
+        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.
+    </para>
+
+    <para>
+        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.
+    </para>
+
+    <para>
+        Within the figure, italicized text is used to indicate replaceable
+        portions of the file or directory name.
+        For example,
+        <replaceable>install_dir</replaceable> is the directory where the SDK
+        is installed, which is <filename>poky_sdk</filename> by default, and
+        <replaceable>target</replaceable> represents the target
+        architecture (e.g. <filename>i586</filename>).
+    </para>
+</section>
+
+</appendix>
+<!--
+vim: expandtab tw=80 ts=4
+-->