poky/documentation/sdk-manual/sdk-appendix-obtain.xml - mdmillerii/openbmc - Gitiles

 <!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; ] >

 <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
 -->
	<!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; ] >

	<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
	-->