1 files changed, 270 insertions, 0 deletions

diff --git a/documentation/sdk-manual/sdk-appendix-obtain.rst b/documentation/sdk-manual/sdk-appendix-obtain.rst
new file mode 100644
index 0000000000..506f5cffb7
--- /dev/null
+++ b/documentation/sdk-manual/sdk-appendix-obtain.rst
@@ -0,0 +1,270 @@
+*****************
+Obtaining the SDK
+*****************
+
+.. _sdk-locating-pre-built-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:
+
+1. *Go to the Installers Directory:* Go to
+   ` <&YOCTO_TOOLCHAIN_DL_URL;>`__
+
+2. *Open the Folder for Your Build Host:* Open the folder that matches
+   your `build host <&YOCTO_DOCS_REF_URL;#build-system-term>`__ (i.e.
+   ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines).
+
+3. *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
+   Where: host_system is a string representing your development system:
+   "i686" or "x86_64" type is a string representing the image: "sato" or
+   "minimal" arch is a string representing the target architecture:
+   "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586",
+   "mips32r2", "mips64", or "ppc7400" release is the version of 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 target, go into the ``x86_64``
+   folder and download the following installer:
+   poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
+
+4. *Run the Installer:* Be sure you have execution privileges and run
+   the installer. Following is an example from the ``Downloads``
+   directory: $
+   ~/Downloads/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 "`Installed Standard SDK Directory
+   Structure <#sdk-installed-standard-sdk-directory-structure>`__"
+   section and the "`Installed Extensible SDK Directory
+   Structure <#sdk-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:
+
+1. *Set Up the Build Environment:* Be sure you are set up to use BitBake
+   in a shell. See the "`Preparing the Build
+   Host <&YOCTO_DOCS_DEV_URL;#dev-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.
+
+2. *Clone the ``poky`` Repository:* You need to have a local copy of the
+   Yocto Project `Source
+   Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ (i.e. a local
+   ``poky`` repository). See the "`Cloning the ``poky``
+   Repository <&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository>`__" and
+   possibly the "`Checking Out by Branch in
+   Poky <&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky>`__" and
+   "`Checking Out by Tag in
+   Poky <&YOCTO_DOCS_DEV_URL;#checkout-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.
+
+3. *Initialize the Build Environment:* While in the root directory of
+   the Source Directory (i.e. ``poky``), run the
+   ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ environment
+   setup script to define the OpenEmbedded build environment on your
+   build host. $ source OE_INIT_FILE Among other things, the script
+   creates the `Build
+   Directory <&YOCTO_DOCS_REF_URL;#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.
+
+4. *Make Sure You Are Building an Installer for the Correct Machine:*
+   Check to be sure that your
+   ```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable in the
+   ``local.conf`` file in your Build Directory matches the architecture
+   for which you are building.
+
+5. *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 ```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__ variable
+   in the ``local.conf`` file in your Build Directory is correctly set.
+
+   .. note::
+
+      If you are building an SDK installer for the Extensible SDK, the
+      SDKMACHINE
+      value must be set for the architecture of the machine you are
+      using to build the installer. If
+      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.
+                             
+
+6. *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 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
+         ```TOOLCHAIN_TARGET_TASK`` <&YOCTO_DOCS_REF_URL;#var-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. Following is an example using ``libc``
+         static development libraries: TOOLCHAIN_TARGET_TASK_append = "
+         libc-staticdev"
+
+7. *Run the Installer:* You can now run the SDK installer from
+   ``tmp/deploy/sdk`` in the Build Directory. Following 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 "`Installed Standard SDK Directory
+   Structure <#sdk-installed-standard-sdk-directory-structure>`__"
+   section and the "`Installed Extensible SDK Directory
+   Structure <#sdk-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:
+
+1. *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 `Index of
+   Releases <&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/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 these naming
+   conventions: core-image-profile-arch.tar.bz2 Where: profile 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 "`Images <&YOCTO_DOCS_REF_URL;#ref-images>`__" chapter in the
+   Yocto Project Reference Manual. arch 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*. 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
+
+2. *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``).
+
+   Following is an example based on the toolchain installed in the
+   "`Locating Pre-Built SDK
+   Installers <#sdk-locating-pre-built-sdk-installers>`__" section: $
+   source ~/poky_sdk/environment-setup-core2-64-poky-linux
+
+3. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk``
+   command and provide the root filesystem image.
+
+   Following is an example command that extracts the root filesystem
+   from a previously built root filesystem image that was downloaded
+   from the `Index of Releases <&YOCTO_DOCS_OM_URL;#index-downloads>`__.
+   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
+   ``beablebone-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:
+
+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. ````). 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:
+
+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``).