8 files changed, 2537 insertions, 0 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-customizing-standard.rst b/documentation/sdk-manual/sdk-appendix-customizing-standard.rst
new file mode 100644
index 0000000000..4c61925725
--- /dev/null
+++ b/documentation/sdk-manual/sdk-appendix-customizing-standard.rst
@@ -0,0 +1,32 @@
+****************************
+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
+```TOOLCHAIN_HOST_TASK`` <&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK>`__
+and
+```TOOLCHAIN_TARGET_TASK`` <&YOCTO_DOCS_REF_URL;#var-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 ``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
+``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
+```DISTRO_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-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.
diff --git a/documentation/sdk-manual/sdk-appendix-customizing.rst b/documentation/sdk-manual/sdk-appendix-customizing.rst
new file mode 100644
index 0000000000..b613a12f23
--- /dev/null
+++ b/documentation/sdk-manual/sdk-appendix-customizing.rst
@@ -0,0 +1,347 @@
+******************************
+Customizing the Extensible SDK
+******************************
+This appendix describes customizations you can apply to 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 `build
+   host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__.
+-  Variables listed in
+   ```SDK_LOCAL_CONF_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST>`__
+   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
+   ```SDK_LOCAL_CONF_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST>`__
+   in the glossary of the Yocto Project Reference Manual.
+-  Variables listed in
+   ```SDK_LOCAL_CONF_WHITELIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST>`__
+   are included. Including a variable in the value of
+   ``SDK_LOCAL_CONF_WHITELIST`` overrides either of the previous two
+   filters. The default value is blank.
+-  Classes inherited globally with
+   ```INHERIT`` <&YOCTO_DOCS_REF_URL;#var-INHERIT>`__ that are listed in
+   ```SDK_INHERIT_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST>`__
+   are disabled. Using ``SDK_INHERIT_BLACKLIST`` to disable these
+   classes is the typical method to disable classes that are problematic
+   or unnecessary in the SDK context. The default value blacklists the
+   ```buildhistory`` <&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory>`__
+   and ```icecc`` <&YOCTO_DOCS_REF_URL;#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 `build
+host's <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ setup.
+However, some cases exist for which you might consider making
+adjustments:
+-  If your SDK configuration inherits additional classes using the
+   ```INHERIT`` <&YOCTO_DOCS_REF_URL;#var-INHERIT>`__ variable and you
+   do not need or want those classes enabled in the SDK, you can
+   blacklist them by adding them to the
+   ```SDK_INHERIT_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST>`__
+   variable as described in the fourth bullet of the previous section.
+   .. note::
+      The default value of
+      SDK_INHERIT_BLACKLIST
+      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 "
+      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 `shared
+      state <&YOCTO_DOCS_OM_URL;#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
+      ```SDK_RECRDEP_TASKS`` <&YOCTO_DOCS_REF_URL;#var-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 ``SDK_INHERIT_BLACKLIST``
+      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 "`Providing
+   Additional Installable Extensible SDK
+   Content <#sdk-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
+   ```SDK_UPDATE_URL`` <&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL>`__
+   variable. For more information, see the "`Providing Updates to the
+   Extensible SDK After
+   Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__"
+   section.
+-  If you have adjusted the list of files and directories that appear in
+   ```COREBASE`` <&YOCTO_DOCS_REF_URL;#var-COREBASE>`__ (other than
+   layers that are enabled through ``bblayers.conf``), then you must
+   list these files in
+   ```COREBASE_FILES`` <&YOCTO_DOCS_REF_URL;#var-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
+   ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__, then you must
+   set
+   ```OE_INIT_ENV_SCRIPT`` <&YOCTO_DOCS_REF_URL;#var-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
+      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
+```SDK_TITLE`` <&YOCTO_DOCS_REF_URL;#var-SDK_TITLE>`__ variable and then
+rebuilding the the SDK installer. For information on how to build an SDK
+installer, see the "`Building an SDK
+Installer <#sdk-building-an-sdk-installer>`__" section.
+By default, this title is derived from
+```DISTRO_NAME`` <&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME>`__ when it is
+set. If the ``DISTRO_NAME`` variable is not set, the title is derived
+from the ```DISTRO`` <&YOCTO_DOCS_REF_URL;#var-DISTRO>`__ variable.
+The
+```populate_sdk_base`` <&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*>`__
+class defines the default value of the ``SDK_TITLE`` variable as
+follows: SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or
+d.getVar('DISTRO')} SDK"
+While several ways exist to change 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
+``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:
+1. Create a directory that can be shared over HTTP or HTTPS. You can do
+   this by setting up a web server such as an `Apache HTTP
+   Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or
+   `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server in the cloud
+   to host the directory. This directory must contain the published SDK.
+2. Set the
+   ```SDK_UPDATE_URL`` <&YOCTO_DOCS_REF_URL;#var-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 "`Applying Updates to an Installed
+   Extensible
+   SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__"
+   section.
+3. Build the extensible SDK normally (i.e., use the
+   ``bitbake -c populate_sdk_ext`` imagename command).
+4. 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 "`Applying Updates to an Installed Extensible
+SDK <#sdk-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
+```DISTRO`` <&YOCTO_DOCS_REF_URL;#var-DISTRO>`__ and
+```SDKEXTPATH`` <&YOCTO_DOCS_REF_URL;#var-SDKEXTPATH>`__ variables from
+within the
+```populate_sdk_base`` <&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*>`__
+class as follows: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" You can
+change this default installation directory by specifically setting the
+``SDKEXTPATH`` variable.
+While a number of ways exist through which you can set 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
+``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:
+1. 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
+      ```EXCLUDE_FROM_WORLD`` <&YOCTO_DOCS_REF_URL;#var-EXCLUDE_FROM_WORLD>`__
+      variable for additional information.
+2. Expose the ``sstate-cache`` directory produced by the build.
+   Typically, you expose this directory by making it available through
+   an `Apache HTTP
+   Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or
+   `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server.
+3. Set the appropriate configuration so that the produced SDK knows how
+   to find the configuration. The variable you need to set is
+   ```SSTATE_MIRRORS`` <&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS>`__:
+   SSTATE_MIRRORS = "file://.\*
+   http://example.com/some_path/sstate-cache/PATH" You can set the
+   ``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 "whitelist" the variable through
+      to the SDK by adding the following: SDK_LOCAL_CONF_WHITELIST =
+      "SSTATE_MIRRORS"
+   -  Alternatively, if you just want to set the ``SSTATE_MIRRORS``
+      variable's value for the SDK alone, create a
+      ``conf/sdk-extra.conf`` file either in your `Build
+      Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ or within any
+      layer and put your ``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
+         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
+```SDK_EXT_TYPE`` <&YOCTO_DOCS_REF_URL;#var-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
+```SDK_INCLUDE_PKGDATA`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA>`__
+variable for additional information.
+Setting the ``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 "
+   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
+```SDK_INCLUDE_TOOLCHAIN`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN>`__
+variable to "1". In particular, it is useful to include the toolchain
+when you have set ``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.
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``).
diff --git a/documentation/sdk-manual/sdk-extensible.rst b/documentation/sdk-manual/sdk-extensible.rst
new file mode 100644
index 0000000000..db6bfb4394
--- /dev/null
+++ b/documentation/sdk-manual/sdk-extensible.rst
@@ -0,0 +1,1230 @@
+************************
+Using the Extensible SDK
+************************
+This chapter describes the extensible SDK and how to install it.
+Information covers the pieces of the SDK, how to install it, and
+presents a look at using the ``devtool`` functionality. The extensible
+SDK makes it easy to add new applications and libraries to an image,
+modify the source for an existing component, test changes on the target
+hardware, and ease integration into the rest of the `OpenEmbedded build
+system <&YOCTO_DOCS_REF_URL;#build-system-term>`__.
+.. note::
+   For a side-by-side comparison of main features supported for an
+   extensible SDK as compared to a standard SDK, see the "
+   Introduction
+   " section.
+In addition to the functionality available through ``devtool``, you can
+alternatively make use of the toolchain directly, for example from
+Makefile and Autotools. See the "`Using the SDK Toolchain
+Directly <#sdk-working-projects>`__" chapter for more information.
+.. _sdk-extensible-sdk-intro:
+Why use the Extensible SDK and What is in It?
+=============================================
+The extensible SDK provides a cross-development toolchain and libraries
+tailored to the contents of a specific image. You would use the
+Extensible SDK if you want a toolchain experience supplemented with the
+powerful set of ``devtool`` commands tailored for the Yocto Project
+environment.
+The installed extensible SDK consists of several files and directories.
+Basically, it contains an SDK environment setup script, some
+configuration files, an internal build system, and the ``devtool``
+functionality.
+.. _sdk-installing-the-extensible-sdk:
+Installing the Extensible SDK
+=============================
+The first thing you need to do is install the SDK on your `Build
+Host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ by running the
+``*.sh`` installation script.
+You can download a tarball installer, which includes the pre-built
+toolchain, the ``runqemu`` script, the internal build system,
+``devtool``, and support files from the appropriate
+`toolchain <&YOCTO_TOOLCHAIN_DL_URL;>`__ 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 that 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.
+An extensible SDK has the string "-ext" as part of the name. Following
+is the general form:
+poky-glibc-host_system-image_type-arch-toolchain-ext-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-sato or core-image-minimal 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-ext-DISTRO.sh
+.. note::
+   As an alternative to downloading an SDK, you can build the SDK
+   installer. For information on building the installer, see the "
+   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.
+.. 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.
+$
+./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh
+Poky (Yocto Project Reference Distro) Extensible SDK installer version
+2.5
+==========================================================================
+Enter target directory for SDK (default: ~/poky_sdk): You are about to
+install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
+Extracting SDK..............done Setting it up... Extracting
+buildtools... Preparing build system... Parsing recipes: 100%
+\|##################################################################\|
+Time: 0:00:52 Initialising tasks: 100%
+\|###############################################################\|
+Time: 0:00:00 Checking sstate mirror object availability: 100%
+\|#######################################\| Time: 0:00:00 Loading cache:
+100%
+\|####################################################################\|
+Time: 0:00:00 Initialising tasks: 100%
+\|###############################################################\|
+Time: 0:00:00 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. $ .
+/home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
+.. _sdk-running-the-extensible-sdk-environment-setup-script:
+Running the Extensible 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 ``poky_sdk`` 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: $ cd
+/home/scottrif/poky_sdk $ source environment-setup-core2-64-poky-linux
+SDK environment now set up; additionally you may now run devtool to
+perform development tasks. Run devtool --help for further details.
+Running the setup script defines many environment variables needed in
+order to use the SDK (e.g. ``PATH``,
+```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__,
+```LD`` <&YOCTO_DOCS_REF_URL;#var-LD>`__, and so forth). If you want to
+see all the environment variables the script exports, examine the
+installation file itself.
+Using ``devtool`` in Your SDK Workflow
+======================================
+The cornerstone of the extensible SDK is a command-line tool called
+``devtool``. This tool provides a number of features that help you
+build, test and package software within the extensible SDK, and
+optionally integrate it into an image built by the OpenEmbedded build
+system.
+.. note::
+   The use of
+   devtool
+   is not limited to the extensible SDK. You can use
+   devtool
+   to help you easily develop any project whose build output must be
+   part of an image built using the build system.
+The ``devtool`` command line is organized similarly to
+`Git <&YOCTO_DOCS_OM_URL;#git>`__ in that it has a number of
+sub-commands for each function. You can run ``devtool --help`` to see
+all the commands.
+.. note::
+   See the "
+   devtool
+    Quick Reference
+   " in the Yocto Project Reference Manual for a
+   devtool
+   quick reference.
+Three ``devtool`` subcommands exist that provide entry-points into
+development:
+-  *``devtool add``*: Assists in adding new software to be built.
+-  *``devtool modify``*: Sets up an environment to enable you to modify
+   the source of an existing component.
+-  *``devtool upgrade``*: Updates an existing recipe so that you can
+   build it for an updated set of source files.
+As with the build system, "recipes" represent software packages within
+``devtool``. When you use ``devtool add``, a recipe is automatically
+created. When you use ``devtool modify``, the specified existing recipe
+is used in order to determine where to get the source code and how to
+patch it. In both cases, an environment is set up so that when you build
+the recipe a source tree that is under your control is used in order to
+allow you to make changes to the source as desired. By default, new
+recipes and the source go into a "workspace" directory under the SDK.
+The remainder of this section presents the ``devtool add``,
+``devtool modify``, and ``devtool upgrade`` workflows.
+.. _sdk-use-devtool-to-add-an-application:
+Use ``devtool add`` to Add an Application
+-----------------------------------------
+The ``devtool add`` command generates a new recipe based on existing
+source code. This command takes advantage of the
+`workspace <&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure>`__
+layer that many ``devtool`` commands use. The command is flexible enough
+to allow you to extract source code into both the workspace or a
+separate local Git repository and to use existing code that does not
+need to be extracted.
+Depending on your particular scenario, the arguments and options you use
+with ``devtool add`` form different combinations. The following diagram
+shows common development flows you would use with the ``devtool add``
+command:
+1. *Generating the New Recipe*: The top part of the flow shows three
+   scenarios by which you could use ``devtool add`` to generate a recipe
+   based on existing source code.
+   In a shared development environment, it is typical for other
+   developers to be responsible for various areas of source code. As a
+   developer, you are probably interested in using that source code as
+   part of your development within the Yocto Project. All you need is
+   access to the code, a recipe, and a controlled area in which to do
+   your work.
+   Within the diagram, three possible scenarios feed into the
+   ``devtool add`` workflow:
+   -  *Left*: The left scenario in the figure represents a common
+      situation where the source code does not exist locally and needs
+      to be extracted. In this situation, the source code is extracted
+      to the default workspace - you do not want the files in some
+      specific location outside of the workspace. Thus, everything you
+      need will be located in the workspace: $ devtool add recipe
+      fetchuri With this command, ``devtool`` extracts the upstream
+      source files into a local Git repository within the ``sources``
+      folder. The command then creates a recipe named recipe and a
+      corresponding append file in the workspace. If you do not provide
+      recipe, the command makes an attempt to determine the recipe name.
+   -  *Middle*: The middle scenario in the figure also represents a
+      situation where the source code does not exist locally. In this
+      case, the code is again upstream and needs to be extracted to some
+      local area - this time outside of the default workspace.
+      .. note::
+         If required,
+         devtool
+         always creates a Git repository locally during the extraction.
+      Furthermore, the first positional argument srctree in this case
+      identifies where the ``devtool add`` command will locate the
+      extracted code outside of the workspace. You need to specify an
+      empty directory: $ devtool add recipe srctree fetchuri In summary,
+      the source code is pulled from fetchuri and extracted into the
+      location defined by srctree as a local Git repository.
+      Within workspace, ``devtool`` creates a recipe named recipe along
+      with an associated append file.
+   -  *Right*: The right scenario in the figure represents a situation
+      where the srctree has been previously prepared outside of the
+      ``devtool`` workspace.
+      The following command provides a new recipe name and identifies
+      the existing source tree location: $ devtool add recipe srctree
+      The command examines the source code and creates a recipe named
+      recipe for the code and places the recipe into the workspace.
+      Because the extracted source code already exists, ``devtool`` does
+      not try to relocate the source code into the workspace - only the
+      new recipe is placed in the workspace.
+      Aside from a recipe folder, the command also creates an associated
+      append folder and places an initial ``*.bbappend`` file within.
+2. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the
+   editor as defined by the ``$EDITOR`` environment variable and modify
+   the file: $ devtool edit-recipe recipe From within the editor, you
+   can make modifications to the recipe that take affect when you build
+   it later.
+3. *Build the Recipe or Rebuild the Image*: The next step you take
+   depends on what you are going to do with the new code.
+   If you need to eventually move the build output to the target
+   hardware, use the following ``devtool`` command: $ devtool build
+   recipe
+   On the other hand, if you want an image to contain the recipe's
+   packages from the workspace for immediate deployment onto a device
+   (e.g. for testing purposes), you can use the ``devtool build-image``
+   command: $ devtool build-image image
+4. *Deploy the Build Output*: When you use the ``devtool build`` command
+   to build out your recipe, you probably want to see if the resulting
+   build output works as expected on the target hardware.
+   .. note::
+      This step assumes you have a previously built image that is
+      already either running in QEMU or is running on actual hardware.
+      Also, it is assumed that for deployment of the image to the
+      target, SSH is installed in the image and, if the image is running
+      on real hardware, you have network access to and from your
+      development machine.
+   You can deploy your build output to that target hardware by using the
+   ``devtool deploy-target`` command: $ devtool deploy-target recipe
+   target The target is a live target machine running as an SSH server.
+   You can, of course, also deploy the image you build to actual
+   hardware by using the ``devtool build-image`` command. However,
+   ``devtool`` does not provide a specific command that allows you to
+   deploy the image to actual hardware.
+5. *Finish Your Work With the Recipe*: The ``devtool finish`` command
+   creates any patches corresponding to commits in the local Git
+   repository, moves the new recipe to a more permanent layer, and then
+   resets the recipe so that the recipe is built normally rather than
+   from the workspace. $ devtool finish recipe layer
+   .. note::
+      Any changes you want to turn into patches must be committed to the
+      Git repository in the source tree.
+   As mentioned, the ``devtool finish`` command moves the final recipe
+   to its permanent layer.
+   As a final process of the ``devtool finish`` command, the state of
+   the standard layers and the upstream source is restored so that you
+   can build the recipe from those areas rather than the workspace.
+   .. note::
+      You can use the
+      devtool reset
+      command to put things back should you decide you do not want to
+      proceed with your work. If you do use this command, realize that
+      the source tree is preserved.
+.. _sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component:
+Use ``devtool modify`` to Modify the Source of an Existing Component
+--------------------------------------------------------------------
+The ``devtool modify`` command prepares the way to work on existing code
+that already has a local recipe in place that is used to build the
+software. The command is flexible enough to allow you to extract code
+from an upstream source, specify the existing recipe, and keep track of
+and gather any patch files from other developers that are associated
+with the code.
+Depending on your particular scenario, the arguments and options you use
+with ``devtool modify`` form different combinations. The following
+diagram shows common development flows for the ``devtool modify``
+command:
+1. *Preparing to Modify the Code*: The top part of the flow shows three
+   scenarios by which you could use ``devtool modify`` to prepare to
+   work on source files. Each scenario assumes the following:
+   -  The recipe exists locally in a layer external to the ``devtool``
+      workspace.
+   -  The source files exist either upstream in an un-extracted state or
+      locally in a previously extracted state.
+   The typical situation is where another developer has created a layer
+   for use with the Yocto Project and their recipe already resides in
+   that layer. Furthermore, their source code is readily available
+   either upstream or locally.
+   -  *Left*: The left scenario in the figure represents a common
+      situation where the source code does not exist locally and it
+      needs to be extracted from an upstream source. In this situation,
+      the source is extracted into the default ``devtool`` workspace
+      location. The recipe, in this scenario, is in its own layer
+      outside the workspace (i.e. ``meta-``\ layername).
+      The following command identifies the recipe and, by default,
+      extracts the source files: $ devtool modify recipe Once
+      ``devtool``\ locates the recipe, ``devtool`` uses the recipe's
+      ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements to
+      locate the source code and any local patch files from other
+      developers.
+      With this scenario, no srctree argument exists. Consequently, the
+      default behavior of the ``devtool modify`` command is to extract
+      the source files pointed to by the ``SRC_URI`` statements into a
+      local Git structure. Furthermore, the location for the extracted
+      source is the default area within the ``devtool`` workspace. The
+      result is that the command sets up both the source code and an
+      append file within the workspace while the recipe remains in its
+      original location.
+      Additionally, if you have any non-patch local files (i.e. files
+      referred to with ``file://`` entries in ``SRC_URI`` statement
+      excluding ``*.patch/`` or ``*.diff``), these files are copied to
+      an ``oe-local-files`` folder under the newly created source tree.
+      Copying the files here gives you a convenient area from which you
+      can modify the files. Any changes or additions you make to those
+      files are incorporated into the build the next time you build the
+      software just as are other changes you might have made to the
+      source.
+   -  *Middle*: The middle scenario in the figure represents a situation
+      where the source code also does not exist locally. In this case,
+      the code is again upstream and needs to be extracted to some local
+      area as a Git repository. The recipe, in this scenario, is again
+      local and in its own layer outside the workspace.
+      The following command tells ``devtool`` the recipe with which to
+      work and, in this case, identifies a local area for the extracted
+      source files that exists outside of the default ``devtool``
+      workspace: $ devtool modify recipe srctree
+      .. note::
+         You cannot provide a URL for
+         srctree
+         using the
+         devtool
+         command.
+      As with all extractions, the command uses the recipe's ``SRC_URI``
+      statements to locate the source files and any associated patch
+      files. Non-patch files are copied to an ``oe-local-files`` folder
+      under the newly created source tree.
+      Once the files are located, the command by default extracts them
+      into srctree.
+      Within workspace, ``devtool`` creates an append file for the
+      recipe. The recipe remains in its original location but the source
+      files are extracted to the location you provide with srctree.
+   -  *Right*: The right scenario in the figure represents a situation
+      where the source tree (srctree) already exists locally as a
+      previously extracted Git structure outside of the ``devtool``
+      workspace. In this example, the recipe also exists elsewhere
+      locally in its own layer.
+      The following command tells ``devtool`` the recipe with which to
+      work, uses the "-n" option to indicate source does not need to be
+      extracted, and uses srctree to point to the previously extracted
+      source files: $ devtool modify -n recipe srctree
+      If an ``oe-local-files`` subdirectory happens to exist and it
+      contains non-patch files, the files are used. However, if the
+      subdirectory does not exist and you run the ``devtool finish``
+      command, any non-patch files that might exist next to the recipe
+      are removed because it appears to ``devtool`` that you have
+      deleted those files.
+      Once the ``devtool modify`` command finishes, it creates only an
+      append file for the recipe in the ``devtool`` workspace. The
+      recipe and the source code remain in their original locations.
+2. *Edit the Source*: Once you have used the ``devtool modify`` command,
+   you are free to make changes to the source files. You can use any
+   editor you like to make and save your source code modifications.
+3. *Build the Recipe or Rebuild the Image*: The next step you take
+   depends on what you are going to do with the new code.
+   If you need to eventually move the build output to the target
+   hardware, use the following ``devtool`` command: $ devtool build
+   recipe
+   On the other hand, if you want an image to contain the recipe's
+   packages from the workspace for immediate deployment onto a device
+   (e.g. for testing purposes), you can use the ``devtool build-image``
+   command: $ devtool build-image image
+4. *Deploy the Build Output*: When you use the ``devtool build`` command
+   to build out your recipe, you probably want to see if the resulting
+   build output works as expected on target hardware.
+   .. note::
+      This step assumes you have a previously built image that is
+      already either running in QEMU or running on actual hardware.
+      Also, it is assumed that for deployment of the image to the
+      target, SSH is installed in the image and if the image is running
+      on real hardware that you have network access to and from your
+      development machine.
+   You can deploy your build output to that target hardware by using the
+   ``devtool deploy-target`` command: $ devtool deploy-target recipe
+   target The target is a live target machine running as an SSH server.
+   You can, of course, use other methods to deploy the image you built
+   using the ``devtool build-image`` command to actual hardware.
+   ``devtool`` does not provide a specific command to deploy the image
+   to actual hardware.
+5. *Finish Your Work With the Recipe*: The ``devtool finish`` command
+   creates any patches corresponding to commits in the local Git
+   repository, updates the recipe to point to them (or creates a
+   ``.bbappend`` file to do so, depending on the specified destination
+   layer), and then resets the recipe so that the recipe is built
+   normally rather than from the workspace. $ devtool finish recipe
+   layer
+   .. note::
+      Any changes you want to turn into patches must be staged and
+      committed within the local Git repository before you use the
+      devtool finish
+      command.
+   Because there is no need to move the recipe, ``devtool finish``
+   either updates the original recipe in the original layer or the
+   command creates a ``.bbappend`` file in a different layer as provided
+   by layer. Any work you did in the ``oe-local-files`` directory is
+   preserved in the original files next to the recipe during the
+   ``devtool finish`` command.
+   As a final process of the ``devtool finish`` command, the state of
+   the standard layers and the upstream source is restored so that you
+   can build the recipe from those areas rather than from the workspace.
+   .. note::
+      You can use the
+      devtool reset
+      command to put things back should you decide you do not want to
+      proceed with your work. If you do use this command, realize that
+      the source tree is preserved.
+.. _sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software:
+Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a Newer Version of the Software
+-------------------------------------------------------------------------------------------------------
+The ``devtool upgrade`` command upgrades an existing recipe to that of a
+more up-to-date version found upstream. Throughout the life of software,
+recipes continually undergo version upgrades by their upstream
+publishers. You can use the ``devtool upgrade`` workflow to make sure
+your recipes you are using for builds are up-to-date with their upstream
+counterparts.
+.. note::
+   Several methods exist by which you can upgrade recipes -
+   devtool upgrade
+   happens to be one. You can read about all the methods by which you
+   can upgrade recipes in the "
+   Upgrading Recipes
+   " section of the Yocto Project Development Tasks Manual.
+The ``devtool upgrade`` command is flexible enough to allow you to
+specify source code revision and versioning schemes, extract code into
+or out of the ``devtool``
+`workspace <&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure>`__,
+and work with any source file forms that the
+`fetchers <&YOCTO_DOCS_BB_URL;#bb-fetchers>`__ support.
+The following diagram shows the common development flow used with the
+``devtool upgrade`` command:
+1. *Initiate the Upgrade*: The top part of the flow shows the typical
+   scenario by which you use the ``devtool upgrade`` command. The
+   following conditions exist:
+   -  The recipe exists in a local layer external to the ``devtool``
+      workspace.
+   -  The source files for the new release exist in the same location
+      pointed to by ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__
+      in the recipe (e.g. a tarball with the new version number in the
+      name, or as a different revision in the upstream Git repository).
+   A common situation is where third-party software has undergone a
+   revision so that it has been upgraded. The recipe you have access to
+   is likely in your own layer. Thus, you need to upgrade the recipe to
+   use the newer version of the software: $ devtool upgrade -V version
+   recipe By default, the ``devtool upgrade`` command extracts source
+   code into the ``sources`` directory in the
+   `workspace <&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure>`__.
+   If you want the code extracted to any other location, you need to
+   provide the srctree positional argument with the command as follows:
+   $ devtool upgrade -V version recipe srctree
+   .. note::
+      In this example, the "-V" option specifies the new version. If you
+      don't use "-V", the command upgrades the recipe to the latest
+      version.
+   If the source files pointed to by the ``SRC_URI`` statement in the
+   recipe are in a Git repository, you must provide the "-S" option and
+   specify a revision for the software.
+   Once ``devtool`` locates the recipe, it uses the ``SRC_URI`` variable
+   to locate the source code and any local patch files from other
+   developers. The result is that the command sets up the source code,
+   the new version of the recipe, and an append file all within the
+   workspace.
+   Additionally, if you have any non-patch local files (i.e. files
+   referred to with ``file://`` entries in ``SRC_URI`` statement
+   excluding ``*.patch/`` or ``*.diff``), these files are copied to an
+   ``oe-local-files`` folder under the newly created source tree.
+   Copying the files here gives you a convenient area from which you can
+   modify the files. Any changes or additions you make to those files
+   are incorporated into the build the next time you build the software
+   just as are other changes you might have made to the source.
+2. *Resolve any Conflicts created by the Upgrade*: Conflicts could exist
+   due to the software being upgraded to a new version. Conflicts occur
+   if your recipe specifies some patch files in ``SRC_URI`` that
+   conflict with changes made in the new version of the software. For
+   such cases, you need to resolve the conflicts by editing the source
+   and following the normal ``git rebase`` conflict resolution process.
+   Before moving onto the next step, be sure to resolve any such
+   conflicts created through use of a newer or different version of the
+   software.
+3. *Build the Recipe or Rebuild the Image*: The next step you take
+   depends on what you are going to do with the new code.
+   If you need to eventually move the build output to the target
+   hardware, use the following ``devtool`` command: $ devtool build
+   recipe
+   On the other hand, if you want an image to contain the recipe's
+   packages from the workspace for immediate deployment onto a device
+   (e.g. for testing purposes), you can use the ``devtool build-image``
+   command: $ devtool build-image image
+4. *Deploy the Build Output*: When you use the ``devtool build`` command
+   or ``bitbake`` to build your recipe, you probably want to see if the
+   resulting build output works as expected on target hardware.
+   .. note::
+      This step assumes you have a previously built image that is
+      already either running in QEMU or running on actual hardware.
+      Also, it is assumed that for deployment of the image to the
+      target, SSH is installed in the image and if the image is running
+      on real hardware that you have network access to and from your
+      development machine.
+   You can deploy your build output to that target hardware by using the
+   ``devtool deploy-target`` command: $ devtool deploy-target recipe
+   target The target is a live target machine running as an SSH server.
+   You can, of course, also deploy the image you build using the
+   ``devtool build-image`` command to actual hardware. However,
+   ``devtool`` does not provide a specific command that allows you to do
+   this.
+5. *Finish Your Work With the Recipe*: The ``devtool finish`` command
+   creates any patches corresponding to commits in the local Git
+   repository, moves the new recipe to a more permanent layer, and then
+   resets the recipe so that the recipe is built normally rather than
+   from the workspace.
+   Any work you did in the ``oe-local-files`` directory is preserved in
+   the original files next to the recipe during the ``devtool finish``
+   command.
+   If you specify a destination layer that is the same as the original
+   source, then the old version of the recipe and associated files are
+   removed prior to adding the new version. $ devtool finish recipe
+   layer
+   .. note::
+      Any changes you want to turn into patches must be committed to the
+      Git repository in the source tree.
+   As a final process of the ``devtool finish`` command, the state of
+   the standard layers and the upstream source is restored so that you
+   can build the recipe from those areas rather than the workspace.
+   .. note::
+      You can use the
+      devtool reset
+      command to put things back should you decide you do not want to
+      proceed with your work. If you do use this command, realize that
+      the source tree is preserved.
+.. _sdk-a-closer-look-at-devtool-add:
+A Closer Look at ``devtool add``
+================================
+The ``devtool add`` command automatically creates a recipe based on the
+source tree you provide with the command. Currently, the command has
+support for the following:
+-  Autotools (``autoconf`` and ``automake``)
+-  CMake
+-  Scons
+-  ``qmake``
+-  Plain ``Makefile``
+-  Out-of-tree kernel module
+-  Binary package (i.e. "-b" option)
+-  Node.js module
+-  Python modules that use ``setuptools`` or ``distutils``
+Apart from binary packages, the determination of how a source tree
+should be treated is automatic based on the files present within that
+source tree. For example, if a ``CMakeLists.txt`` file is found, then
+the source tree is assumed to be using CMake and is treated accordingly.
+.. note::
+   In most cases, you need to edit the automatically generated recipe in
+   order to make it build properly. Typically, you would go through
+   several edit and build cycles until the recipe successfully builds.
+   Once the recipe builds, you could use possible further iterations to
+   test the recipe on the target device.
+The remainder of this section covers specifics regarding how parts of
+the recipe are generated.
+.. _sdk-name-and-version:
+Name and Version
+----------------
+If you do not specify a name and version on the command line,
+``devtool add`` uses various metadata within the source tree in an
+attempt to determine the name and version of the software being built.
+Based on what the tool determines, ``devtool`` sets the name of the
+created recipe file accordingly.
+If ``devtool`` cannot determine the name and version, the command prints
+an error. For such cases, you must re-run the command and provide the
+name and version, just the name, or just the version as part of the
+command line.
+Sometimes the name or version determined from the source tree might be
+incorrect. For such a case, you must reset the recipe: $ devtool reset
+-n recipename After running the ``devtool reset`` command, you need to
+run ``devtool add`` again and provide the name or the version.
+.. _sdk-dependency-detection-and-mapping:
+Dependency Detection and Mapping
+--------------------------------
+The ``devtool add`` command attempts to detect build-time dependencies
+and map them to other recipes in the system. During this mapping, the
+command fills in the names of those recipes as part of the
+```DEPENDS`` <&YOCTO_DOCS_REF_URL;#var-DEPENDS>`__ variable within the
+recipe. If a dependency cannot be mapped, ``devtool`` places a comment
+in the recipe indicating such. The inability to map a dependency can
+result from naming not being recognized or because the dependency simply
+is not available. For cases where the dependency is not available, you
+must use the ``devtool add`` command to add an additional recipe that
+satisfies the dependency. Once you add that recipe, you need to update
+the ``DEPENDS`` variable in the original recipe to include the new
+recipe.
+If you need to add runtime dependencies, you can do so by adding the
+following to your recipe: RDEPENDS_${PN} += "dependency1 dependency2
+..."
+.. note::
+   The
+   devtool add
+   command often cannot distinguish between mandatory and optional
+   dependencies. Consequently, some of the detected dependencies might
+   in fact be optional. When in doubt, consult the documentation or the
+   configure script for the software the recipe is building for further
+   details. In some cases, you might find you can substitute the
+   dependency with an option that disables the associated functionality
+   passed to the configure script.
+.. _sdk-license-detection:
+License Detection
+-----------------
+The ``devtool add`` command attempts to determine if the software you
+are adding is able to be distributed under a common, open-source
+license. If so, the command sets the
+```LICENSE`` <&YOCTO_DOCS_REF_URL;#var-LICENSE>`__ value accordingly.
+You should double-check the value added by the command against the
+documentation or source files for the software you are building and, if
+necessary, update that ``LICENSE`` value.
+The ``devtool add`` command also sets the
+```LIC_FILES_CHKSUM`` <&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM>`__
+value to point to all files that appear to be license-related. Realize
+that license statements often appear in comments at the top of source
+files or within the documentation. In such cases, the command does not
+recognize those license statements. Consequently, you might need to
+amend the ``LIC_FILES_CHKSUM`` variable to point to one or more of those
+comments if present. Setting ``LIC_FILES_CHKSUM`` is particularly
+important for third-party software. The mechanism attempts to ensure
+correct licensing should you upgrade the recipe to a newer upstream
+version in future. Any change in licensing is detected and you receive
+an error prompting you to check the license text again.
+If the ``devtool add`` command cannot determine licensing information,
+``devtool`` sets the ``LICENSE`` value to "CLOSED" and leaves the
+``LIC_FILES_CHKSUM`` value unset. This behavior allows you to continue
+with development even though the settings are unlikely to be correct in
+all cases. You should check the documentation or source files for the
+software you are building to determine the actual license.
+.. _sdk-adding-makefile-only-software:
+Adding Makefile-Only Software
+-----------------------------
+The use of Make by itself is very common in both proprietary and
+open-source software. Unfortunately, Makefiles are often not written
+with cross-compilation in mind. Thus, ``devtool add`` often cannot do
+very much to ensure that these Makefiles build correctly. It is very
+common, for example, to explicitly call ``gcc`` instead of using the
+```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__ variable. Usually, in a
+cross-compilation environment, ``gcc`` is the compiler for the build
+host and the cross-compiler is named something similar to
+``arm-poky-linux-gnueabi-gcc`` and might require arguments (e.g. to
+point to the associated sysroot for the target machine).
+When writing a recipe for Makefile-only software, keep the following in
+mind:
+-  You probably need to patch the Makefile to use variables instead of
+   hardcoding tools within the toolchain such as ``gcc`` and ``g++``.
+-  The environment in which Make runs is set up with various standard
+   variables for compilation (e.g. ``CC``, ``CXX``, and so forth) in a
+   similar manner to the environment set up by the SDK's environment
+   setup script. One easy way to see these variables is to run the
+   ``devtool build`` command on the recipe and then look in
+   ``oe-logs/run.do_compile``. Towards the top of this file, a list of
+   environment variables exists that are being set. You can take
+   advantage of these variables within the Makefile.
+-  If the Makefile sets a default for a variable using "=", that default
+   overrides the value set in the environment, which is usually not
+   desirable. For this case, you can either patch the Makefile so it
+   sets the default using the "?=" operator, or you can alternatively
+   force the value on the ``make`` command line. To force the value on
+   the command line, add the variable setting to
+   ```EXTRA_OEMAKE`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE>`__ or
+   ```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__
+   within the recipe. Here is an example using ``EXTRA_OEMAKE``:
+   EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" In the above example,
+   single quotes are used around the variable settings as the values are
+   likely to contain spaces because required default options are passed
+   to the compiler.
+-  Hardcoding paths inside Makefiles is often problematic in a
+   cross-compilation environment. This is particularly true because
+   those hardcoded paths often point to locations on the build host and
+   thus will either be read-only or will introduce contamination into
+   the cross-compilation because they are specific to the build host
+   rather than the target. Patching the Makefile to use prefix variables
+   or other path variables is usually the way to handle this situation.
+-  Sometimes a Makefile runs target-specific commands such as
+   ``ldconfig``. For such cases, you might be able to apply patches that
+   remove these commands from the Makefile.
+.. _sdk-adding-native-tools:
+Adding Native Tools
+-------------------
+Often, you need to build additional tools that run on the `build
+host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ as opposed to
+the target. You should indicate this requirement by using one of the
+following methods when you run ``devtool add``:
+-  Specify the name of the recipe such that it ends with "-native".
+   Specifying the name like this produces a recipe that only builds for
+   the build host.
+-  Specify the "DASHDASHalso-native" option with the ``devtool add``
+   command. Specifying this option creates a recipe file that still
+   builds for the target but also creates a variant with a "-native"
+   suffix that builds for the build host.
+.. note::
+   If you need to add a tool that is shipped as part of a source tree
+   that builds code for the target, you can typically accomplish this by
+   building the native and target parts separately rather than within
+   the same compilation process. Realize though that with the
+   "DASHDASHalso-native" option, you can add the tool using just one
+   recipe file.
+.. _sdk-adding-node-js-modules:
+Adding Node.js Modules
+----------------------
+You can use the ``devtool add`` command two different ways to add
+Node.js modules: 1) Through ``npm`` and, 2) from a repository or local
+source.
+Use the following form to add Node.js modules through ``npm``: $ devtool
+add "npm://registry.npmjs.org;name=forever;version=0.15.1" The name and
+version parameters are mandatory. Lockdown and shrinkwrap files are
+generated and pointed to by the recipe in order to freeze the version
+that is fetched for the dependencies according to the first time. This
+also saves checksums that are verified on future fetches. Together,
+these behaviors ensure the reproducibility and integrity of the build.
+.. note::
+   -  You must use quotes around the URL. The ``devtool add`` does not
+      require the quotes, but the shell considers ";" as a splitter
+      between multiple commands. Thus, without the quotes,
+      ``devtool add`` does not receive the other parts, which results in
+      several "command not found" errors.
+   -  In order to support adding Node.js modules, a ``nodejs`` recipe
+      must be part of your SDK.
+As mentioned earlier, you can also add Node.js modules directly from a
+repository or local source tree. To add modules this way, use
+``devtool add`` in the following form: $ devtool add
+https://github.com/diversario/node-ssdp In this example, ``devtool``
+fetches the specified Git repository, detects the code as Node.js code,
+fetches dependencies using ``npm``, and sets
+```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ accordingly.
+.. _sdk-working-with-recipes:
+Working With Recipes
+====================
+When building a recipe using the ``devtool build`` command, the typical
+build progresses as follows:
+1. Fetch the source
+2. Unpack the source
+3. Configure the source
+4. Compile the source
+5. Install the build output
+6. Package the installed output
+For recipes in the workspace, fetching and unpacking is disabled as the
+source tree has already been prepared and is persistent. Each of these
+build steps is defined as a function (task), usually with a "do_" prefix
+(e.g. ```do_fetch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-fetch>`__,
+```do_unpack`` <&YOCTO_DOCS_REF_URL;#ref-tasks-unpack>`__, and so
+forth). These functions are typically shell scripts but can instead be
+written in Python.
+If you look at the contents of a recipe, you will see that the recipe
+does not include complete instructions for building the software.
+Instead, common functionality is encapsulated in classes inherited with
+the ``inherit`` directive. This technique leaves the recipe to describe
+just the things that are specific to the software being built. A
+```base`` <&YOCTO_DOCS_REF_URL;#ref-classes-base>`__ class exists that
+is implicitly inherited by all recipes and provides the functionality
+that most recipes typically need.
+The remainder of this section presents information useful when working
+with recipes.
+.. _sdk-finding-logs-and-work-files:
+Finding Logs and Work Files
+---------------------------
+After the first run of the ``devtool build`` command, recipes that were
+previously created using the ``devtool add`` command or whose sources
+were modified using the ``devtool modify`` command contain symbolic
+links created within the source tree:
+-  ``oe-logs``: This link points to the directory in which log files and
+   run scripts for each build step are created.
+-  ``oe-workdir``: This link points to the temporary work area for the
+   recipe. The following locations under ``oe-workdir`` are particularly
+   useful:
+   -  ``image/``: Contains all of the files installed during the
+      ```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ stage.
+      Within a recipe, this directory is referred to by the expression
+      ``${``\ ```D`` <&YOCTO_DOCS_REF_URL;#var-D>`__\ ``}``.
+   -  ``sysroot-destdir/``: Contains a subset of files installed within
+      ``do_install`` that have been put into the shared sysroot. For
+      more information, see the "`Sharing Files Between
+      Recipes <#sdk-sharing-files-between-recipes>`__" section.
+   -  ``packages-split/``: Contains subdirectories for each package
+      produced by the recipe. For more information, see the
+      "`Packaging <#sdk-packaging>`__" section.
+You can use these links to get more information on what is happening at
+each build step.
+.. _sdk-setting-configure-arguments:
+Setting Configure Arguments
+---------------------------
+If the software your recipe is building uses GNU autoconf, then a fixed
+set of arguments is passed to it to enable cross-compilation plus any
+extras specified by
+```EXTRA_OECONF`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF>`__ or
+```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__
+set within the recipe. If you wish to pass additional options, add them
+to ``EXTRA_OECONF`` or ``PACKAGECONFIG_CONFARGS``. Other supported build
+tools have similar variables (e.g.
+```EXTRA_OECMAKE`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE>`__ for
+CMake, ```EXTRA_OESCONS`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS>`__
+for Scons, and so forth). If you need to pass anything on the ``make``
+command line, you can use ``EXTRA_OEMAKE`` or the
+```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__
+variables to do so.
+You can use the ``devtool configure-help`` command to help you set the
+arguments listed in the previous paragraph. The command determines the
+exact options being passed, and shows them to you along with any custom
+arguments specified through ``EXTRA_OECONF`` or
+``PACKAGECONFIG_CONFARGS``. If applicable, the command also shows you
+the output of the configure script's "DASHDASHhelp" option as a
+reference.
+.. _sdk-sharing-files-between-recipes:
+Sharing Files Between Recipes
+-----------------------------
+Recipes often need to use files provided by other recipes on the `build
+host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__. For example,
+an application linking to a common library needs access to the library
+itself and its associated headers. The way this access is accomplished
+within the extensible SDK is through the sysroot. One sysroot exists per
+"machine" for which the SDK is being built. In practical terms, this
+means a sysroot exists for the target machine, and a sysroot exists for
+the build host.
+Recipes should never write files directly into the sysroot. Instead,
+files should be installed into standard locations during the
+```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ task within
+the ``${``\ ```D`` <&YOCTO_DOCS_REF_URL;#var-D>`__\ ``}`` directory. A
+subset of these files automatically goes into the sysroot. The reason
+for this limitation is that almost all files that go into the sysroot
+are cataloged in manifests in order to ensure they can be removed later
+when a recipe is modified or removed. Thus, the sysroot is able to
+remain free from stale files.
+.. _sdk-packaging:
+Packaging
+---------
+Packaging is not always particularly relevant within the extensible SDK.
+However, if you examine how build output gets into the final image on
+the target device, it is important to understand packaging because the
+contents of the image are expressed in terms of packages and not
+recipes.
+During the ```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__
+task, files installed during the
+```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ task are
+split into one main package, which is almost always named the same as
+the recipe, and into several other packages. This separation exists
+because not all of those installed files are useful in every image. For
+example, you probably do not need any of the documentation installed in
+a production image. Consequently, for each recipe the documentation
+files are separated into a ``-doc`` package. Recipes that package
+software containing optional modules or plugins might undergo additional
+package splitting as well.
+After building a recipe, you can see where files have gone by looking in
+the ``oe-workdir/packages-split`` directory, which contains a
+subdirectory for each package. Apart from some advanced cases, the
+```PACKAGES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGES>`__ and
+```FILES`` <&YOCTO_DOCS_REF_URL;#var-FILES>`__ variables controls
+splitting. The ``PACKAGES`` variable lists all of the packages to be
+produced, while the ``FILES`` variable specifies which files to include
+in each package by using an override to specify the package. For
+example, ``FILES_${PN}`` specifies the files to go into the main package
+(i.e. the main package has the same name as the recipe and
+``${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}`` evaluates to the
+recipe name). The order of the ``PACKAGES`` value is significant. For
+each installed file, the first package whose ``FILES`` value matches the
+file is the package into which the file goes. Defaults exist for both
+the ``PACKAGES`` and ``FILES`` variables. Consequently, you might find
+you do not even need to set these variables in your recipe unless the
+software the recipe is building installs files into non-standard
+locations.
+.. _sdk-restoring-the-target-device-to-its-original-state:
+Restoring the Target Device to its Original State
+=================================================
+If you use the ``devtool deploy-target`` command to write a recipe's
+build output to the target, and you are working on an existing component
+of the system, then you might find yourself in a situation where you
+need to restore the original files that existed prior to running the
+``devtool deploy-target`` command. Because the ``devtool deploy-target``
+command backs up any files it overwrites, you can use the
+``devtool undeploy-target`` command to restore those files and remove
+any other files the recipe deployed. Consider the following example: $
+devtool undeploy-target lighttpd root@192.168.7.2 If you have deployed
+multiple applications, you can remove them all using the "-a" option
+thus restoring the target device to its original state: $ devtool
+undeploy-target -a root@192.168.7.2 Information about files deployed to
+the target as well as any backed up files are stored on the target
+itself. This storage, of course, requires some additional space on the
+target machine.
+.. note::
+   The
+   devtool deploy-target
+   and
+   devtool undeploy-target
+   commands do not currently interact with any package management system
+   on the target device (e.g. RPM or OPKG). Consequently, you should not
+   intermingle
+   devtool deploy-target
+   and package manager operations on the target device. Doing so could
+   result in a conflicting set of files.
+.. _sdk-installing-additional-items-into-the-extensible-sdk:
+Installing Additional Items Into the Extensible SDK
+===================================================
+Out of the box the extensible SDK typically only comes with a small
+number of tools and libraries. A minimal SDK starts mostly empty and is
+populated on-demand. Sometimes you must explicitly install extra items
+into the SDK. If you need these extra items, you can first search for
+the items using the ``devtool search`` command. For example, suppose you
+need to link to libGL but you are not sure which recipe provides libGL.
+You can use the following command to find out: $ devtool search libGL
+mesa A free implementation of the OpenGL API Once you know the recipe
+(i.e. ``mesa`` in this example), you can install it: $ devtool
+sdk-install mesa By default, the ``devtool sdk-install`` command assumes
+the item is available in pre-built form from your SDK provider. If the
+item is not available and it is acceptable to build the item from
+source, you can add the "-s" option as follows: $ devtool sdk-install -s
+mesa It is important to remember that building the item from source
+takes significantly longer than installing the pre-built artifact. Also,
+if no recipe exists for the item you want to add to the SDK, you must
+instead add the item using the ``devtool add`` command.
+.. _sdk-applying-updates-to-an-installed-extensible-sdk:
+Applying Updates to an Installed Extensible SDK
+===============================================
+If you are working with an installed extensible SDK that gets
+occasionally updated (e.g. a third-party SDK), then you will need to
+manually "pull down" the updates into the installed SDK.
+To update your installed SDK, use ``devtool`` as follows: $ devtool
+sdk-update The previous command assumes your SDK provider has set the
+default update URL for you through the
+```SDK_UPDATE_URL`` <&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL>`__
+variable as described in the "`Providing Updates to the Extensible SDK
+After
+Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__"
+section. If the SDK provider has not set that default URL, you need to
+specify it yourself in the command as follows: $ devtool sdk-update
+path_to_update_directory
+.. note::
+   The URL needs to point specifically to a published SDK and not to an
+   SDK installer that you would download and install.
+.. _sdk-creating-a-derivative-sdk-with-additional-components:
+Creating a Derivative SDK With Additional Components
+====================================================
+You might need to produce an SDK that contains your own custom
+libraries. A good example would be if you were a vendor with customers
+that use your SDK to build their own platform-specific software and
+those customers need an SDK that has custom libraries. In such a case,
+you can produce a derivative SDK based on the currently installed SDK
+fairly easily by following these steps:
+1. If necessary, install an extensible SDK that you want to use as a
+   base for your derivative SDK.
+2. Source the environment script for the SDK.
+3. Add the extra libraries or other components you want by using the
+   ``devtool add`` command.
+4. Run the ``devtool build-sdk`` command.
+The previous steps take the recipes added to the workspace and construct
+a new SDK installer that contains those recipes and the resulting binary
+artifacts. The recipes go into their own separate layer in the
+constructed derivative SDK, which leaves the workspace clean and ready
+for users to add their own recipes.
diff --git a/documentation/sdk-manual/sdk-intro.rst b/documentation/sdk-manual/sdk-intro.rst
new file mode 100644
index 0000000000..f2641b7ade
--- /dev/null
+++ b/documentation/sdk-manual/sdk-intro.rst
@@ -0,0 +1,223 @@
+************
+Introduction
+************
+.. _sdk-manual-intro:
+Introduction
+============
+Welcome to the Yocto Project Application Development and the Extensible
+Software Development Kit (eSDK) manual. This manual provides information
+that explains how to use both the Yocto Project extensible and standard
+SDKs to develop applications and images.
+.. note::
+   Prior to the 2.0 Release of the Yocto Project, application
+   development was primarily accomplished through the use of the
+   Application Development Toolkit (ADT) and the availability of
+   stand-alone cross-development toolchains and other tools. With the
+   2.1 Release of the Yocto Project, application development has
+   transitioned to within a tool-rich extensible SDK and the more
+   traditional standard SDK.
+All SDKs consist of the following:
+-  *Cross-Development Toolchain*: This toolchain contains a compiler,
+   debugger, and various miscellaneous tools.
+-  *Libraries, Headers, and Symbols*: The libraries, headers, and
+   symbols are specific to the image (i.e. they match the image).
+-  *Environment Setup Script*: This ``*.sh`` file, once run, 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 `OpenEmbedded build
+system <&YOCTO_DOCS_REF_URL;#build-system-term>`__.
+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 for 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
+```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__ and
+```LD`` <&YOCTO_DOCS_REF_URL;#var-LD>`__. This reduces the space needed
+for the tools. Understand, however, that every target still needs a
+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 `Metadata <&YOCTO_DOCS_REF_URL;#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. Following 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\*                 |
+-----------------------+-----------------------+-----------------------+
+| Debugger              | Yes                   | Yes\*                 |
+-----------------------+-----------------------+-----------------------+
+| Size                  | 100+ MBytes           | 1+ GBytes (or 300+    |
+|                       |                       | MBytes for minimal    |
+|                       |                       | w/toolchain)          |
+-----------------------+-----------------------+-----------------------+
+| ``devtool``           | No                    | Yes                   |
+-----------------------+-----------------------+-----------------------+
+| Build Images          | No                    | Yes                   |
+-----------------------+-----------------------+-----------------------+
+| Updateable            | No                    | Yes                   |
+-----------------------+-----------------------+-----------------------+
+| Managed Sysroot*\*    | No                    | Yes                   |
+-----------------------+-----------------------+-----------------------+
+| Installed Packages    | No**\*                | Yes***\*              |
+-----------------------+-----------------------+-----------------------+
+| Construction          | Packages              | Shared State          |
+-----------------------+-----------------------+-----------------------+
+\* Extensible SDK contains the toolchain and debugger if
+```SDK_EXT_TYPE`` <&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE>`__ is "full"
+or
+```SDK_INCLUDE_TOOLCHAIN`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN>`__
+is "1", which is the default. \*\* 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. \**\* You can add
+runtime package management to the standard SDK but it is not supported
+by default. \***\* 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 `Cross-Development
+Toolchain <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__ consists
+of a cross-compiler, cross-linker, and cross-debugger that are used to
+develop user-space applications for targeted hardware. Additionally, for
+an extensible SDK, the toolchain also has built-in ``devtool``
+functionality. This toolchain is created by running a SDK installer
+script or through a `Build
+Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ that is based on
+your metadata configuration or extension for your targeted device. The
+cross-toolchain works with a matching target sysroot.
+.. _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 made
+available a number of different ways:
+-  If you have cloned the ``poky`` Git repository to create a `Source
+   Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ and you have
+   sourced the environment setup script, QEMU is installed and
+   automatically available.
+-  If you have downloaded a Yocto Project release and unpacked it to
+   create a Source Directory and you have sourced the environment setup
+   script, QEMU is installed and automatically available.
+-  If you have installed the cross-toolchain tarball and you have
+   sourced the toolchain's setup environment script, QEMU is also
+   installed and automatically available.
+SDK Development Model
+=====================
+Fundamentally, the SDK fits into the development process as follows: 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:
+1. *Install the SDK for your target hardware:* For information on how to
+   install the SDK, see the "`Installing the
+   SDK <#sdk-installing-the-sdk>`__" section.
+2. *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
+   ```machines`` <&YOCTO_MACHINES_DL_URL;>`__ 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
+   ```machines/qemu`` <&YOCTO_QEMU_DL_URL;>`__ 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 "
+      Extracting the Root Filesystem
+      " section for information on how to extract the root filesystem.
+3. *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 <http://wiki.qemu.org/Main_Page>`__ to download and learn about
+   the emulator. See the "`Using the Quick EMUlator
+   (QEMU) <&YOCTO_DOCS_DEV_URL;#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. Information also exists in appendix form that describes
+how you can build, install, and modify an SDK.
diff --git a/documentation/sdk-manual/sdk-manual.rst b/documentation/sdk-manual/sdk-manual.rst
new file mode 100644
index 0000000000..2573b76d96
--- /dev/null
+++ b/documentation/sdk-manual/sdk-manual.rst
@@ -0,0 +1,15 @@
+========================================================================================
+Yocto Project Application Development and the Extensible Software Development Kit (eSDK)
+========================================================================================
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+   sdk-intro
+   sdk-extensible
+   sdk-using
+   sdk-working-projects
+   sdk-appendix-obtain
+   sdk-appendix-customizing
+   sdk-appendix-customizing-standard
diff --git a/documentation/sdk-manual/sdk-using.rst b/documentation/sdk-manual/sdk-using.rst
new file mode 100644
index 0000000000..afe72d2b61
--- /dev/null
+++ b/documentation/sdk-manual/sdk-using.rst
@@ -0,0 +1,136 @@
+**********************
+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 "
+   Introduction
+   " section.
+You can use a standard SDK to work on Makefile and Autotools-based
+projects. See the "`Using the SDK Toolchain
+Directly <#sdk-working-projects>`__" chapter for more information.
+.. _sdk-standard-sdk-intro:
+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 "`Installed Standard
+SDK Directory
+Structure <#sdk-installed-standard-sdk-directory-structure>`__" section.
+.. _sdk-installing-the-sdk:
+Installing the SDK
+==================
+The first thing you need to do is install the SDK on your `Build
+Host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ 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 `toolchain <&YOCTO_TOOLCHAIN_DL_URL;>`__ 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 that 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 "
+   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.
+.. 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.
+$ ./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
+Again, reference the "`Installed Standard SDK Directory
+Structure <#sdk-installed-standard-sdk-directory-structure>`__" section
+for more details on the resulting directory structure of the installed
+SDK.
+.. _sdk-running-the-sdk-environment-setup-script:
+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 "`Running the
+Extensible SDK Environment Setup
+Script <#sdk-running-the-extensible-sdk-environment-setup-script>`__"
+section for more information.
diff --git a/documentation/sdk-manual/sdk-working-projects.rst b/documentation/sdk-manual/sdk-working-projects.rst
new file mode 100644
index 0000000000..42f8bfeb46
--- /dev/null
+++ b/documentation/sdk-manual/sdk-working-projects.rst
@@ -0,0 +1,284 @@
+********************************
+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 `cross-development
+toolchain <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__
+installed, it is very easy to develop a project using the `GNU
+Autotools-based <https://en.wikipedia.org/wiki/GNU_Build_System>`__
+workflow, which is outside of the `OpenEmbedded build
+system <&YOCTO_DOCS_REF_URL;#build-system-term>`__.
+The following figure presents a simple Autotools workflow.
+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.
+1. *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
+2. *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
+3. *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.
+4. *Cross-Compile the Project:* This command compiles the project using
+   the cross-compiler. The
+   ```CONFIGURE_FLAGS`` <&YOCTO_DOCS_REF_URL;#var-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
+5. *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 when the Makefile, see the "
+      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
+6. *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.
+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.
+```CC`` <&YOCTO_DOCS_REF_URL;#var-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/2.5/sysroots/i586-poky-linux
+To illustrate variable use, work through this simple "Hello World!"
+example:
+1. *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"); }
+2. *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
+3. *Create the ``Makefile``:* For this example, the Makefile contains
+   two lines that can be used to set the ``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 ``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
+4. *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 ``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 ``CC``
+   variable defined in the setup script.
+   You can override the ``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 ``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.
+5. *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.