Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/documentation/sdk-manual/history.rst b/poky/documentation/sdk-manual/history.rst
index 8c10f6d..af027c9 100644
--- a/poky/documentation/sdk-manual/history.rst
+++ b/poky/documentation/sdk-manual/history.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-2.0-UK
***********************
Manual Revision History
diff --git a/poky/documentation/sdk-manual/sdk-appendix-customizing-standard.rst b/poky/documentation/sdk-manual/sdk-appendix-customizing-standard.rst
index 90b6345..f6f2b66 100644
--- a/poky/documentation/sdk-manual/sdk-appendix-customizing-standard.rst
+++ b/poky/documentation/sdk-manual/sdk-appendix-customizing-standard.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-2.0-UK
****************************
Customizing the Standard SDK
diff --git a/poky/documentation/sdk-manual/sdk-appendix-customizing-standard.xml b/poky/documentation/sdk-manual/sdk-appendix-customizing-standard.xml
new file mode 100644
index 0000000..3a6b4c8
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-appendix-customizing-standard.xml
@@ -0,0 +1,59 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<appendix id='sdk-appendix-customizing-standard'>
+
+<title>Customizing the Standard SDK</title>
+
+<para>
+ This appendix presents customizations you can apply to the standard SDK.
+</para>
+
+<section id='sdk-adding-individual-packages'>
+ <title>Adding Individual Packages to the Standard SDK</title>
+
+ <para>
+ When you build a standard SDK using the
+ <filename>bitbake -c populate_sdk</filename>, a default set of
+ packages is included in the resulting SDK.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>
+ variables control the set of packages adding to the SDK.
+ </para>
+
+ <para>
+ If you want to add individual packages to the toolchain that runs on
+ the host, simply add those packages to the
+ <filename>TOOLCHAIN_HOST_TASK</filename> 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
+ <filename>TOOLCHAIN_TARGET_TASK</filename> variable.
+ </para>
+</section>
+
+<section id='adding-api-documentation-to-the-standard-sdk'>
+ <title>Adding API Documentation to the Standard SDK</title>
+
+ <para>
+ You can include API documentation as well as any other
+ documentation provided by recipes with the standard SDK by
+ adding "api-documentation" to the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
+ variable:
+ <literallayout class='monospaced'>
+ DISTRO_FEATURES_append = " api-documentation"
+ </literallayout>
+ Setting this variable as shown here causes the OpenEmbedded build
+ system to build the documentation and then include it in the standard
+ SDK.
+ </para>
+</section>
+
+</appendix>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/poky/documentation/sdk-manual/sdk-appendix-customizing.rst b/poky/documentation/sdk-manual/sdk-appendix-customizing.rst
index 5a33f63..7743e3c 100644
--- a/poky/documentation/sdk-manual/sdk-appendix-customizing.rst
+++ b/poky/documentation/sdk-manual/sdk-appendix-customizing.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-2.0-UK
******************************
Customizing the Extensible SDK
diff --git a/poky/documentation/sdk-manual/sdk-appendix-customizing.xml b/poky/documentation/sdk-manual/sdk-appendix-customizing.xml
new file mode 100644
index 0000000..08054f8
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-appendix-customizing.xml
@@ -0,0 +1,515 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<appendix id='sdk-appendix-customizing'>
+
+<title>Customizing the Extensible SDK</title>
+
+<para>
+ This appendix describes customizations you can apply to the extensible SDK.
+</para>
+
+<section id='sdk-configuring-the-extensible-sdk'>
+ <title>Configuring the Extensible SDK</title>
+
+ <para>
+ 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 <filename>local.conf</filename> and
+ <filename>auto.conf</filename>:
+ <itemizedlist>
+ <listitem><para>
+ Variables whose values start with "/" are excluded since the
+ assumption is that those values are paths that are likely to
+ be specific to the
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>.
+ </para></listitem>
+ <listitem><para>
+ Variables listed in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>
+ 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.</para>
+
+ <para>For a list of the variables excluded by default, see the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>
+ in the glossary of the Yocto Project Reference Manual.
+ </para></listitem>
+ <listitem><para>
+ Variables listed in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>
+ are included.
+ Including a variable in the value of
+ <filename>SDK_LOCAL_CONF_WHITELIST</filename> overrides either
+ of the previous two filters.
+ The default value is blank.
+ </para></listitem>
+ <listitem><para>
+ Classes inherited globally with
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
+ that are listed in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>
+ are disabled.
+ Using <filename>SDK_INHERIT_BLACKLIST</filename> 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
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory'><filename>buildhistory</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-icecc'><filename>icecc</filename></ulink>
+ classes.
+ </para></listitem>
+ </itemizedlist>
+ Additionally, the contents of <filename>conf/sdk-extra.conf</filename>,
+ when present, are appended to the end of
+ <filename>conf/local.conf</filename> within the produced SDK, without
+ any filtering.
+ The <filename>sdk-extra.conf</filename> 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.
+ </para>
+</section>
+
+<section id='adjusting-the-extensible-sdk-to-suit-your-build-hosts-setup'>
+ <title>Adjusting the Extensible SDK to Suit Your Build Host's Setup</title>
+
+ <para>
+ In most cases, the extensible SDK defaults should work with your
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host's</ulink>
+ setup.
+ However, some cases exist for which you might consider making
+ adjustments:
+ <itemizedlist>
+ <listitem><para>
+ If your SDK configuration inherits additional classes
+ using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
+ variable and you do not need or want those classes enabled in
+ the SDK, you can blacklist them by adding them to the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>
+ variable as described in the fourth bullet of the previous
+ section.
+ <note>
+ The default value of
+ <filename>SDK_INHERIT_BLACKLIST</filename> 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
+ "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
+ section of the BitBake User Manual.
+ </note>.
+ </para></listitem>
+ <listitem><para>
+ 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:
+ <itemizedlist>
+ <listitem><para>
+ After ensuring the tasks are
+ <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink>
+ 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
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_RECRDEP_TASKS'><filename>SDK_RECRDEP_TASKS</filename></ulink>.
+ </para></listitem>
+ <listitem><para>
+ 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
+ <filename>SDK_INHERIT_BLACKLIST</filename> variable
+ as described in the previous section.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ 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
+ "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>"
+ section for information.
+ </para></listitem>
+ <listitem><para>
+ If you want users of the SDK to be able to easily update the
+ SDK, you need to set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
+ variable.
+ For more information, see the
+ "<link linkend='sdk-providing-updates-to-the-extensible-sdk-after-installation'>Providing Updates to the Extensible SDK After Installation</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ If you have adjusted the list of files and directories that
+ appear in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE'><filename>COREBASE</filename></ulink>
+ (other than layers that are enabled through
+ <filename>bblayers.conf</filename>), then you must list these
+ files in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES'><filename>COREBASE_FILES</filename></ulink>
+ so that the files are copied into the SDK.
+ </para></listitem>
+ <listitem><para>
+ If your OpenEmbedded build system setup uses a different
+ environment setup script other than
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>,
+ then you must set
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_INIT_ENV_SCRIPT'><filename>OE_INIT_ENV_SCRIPT</filename></ulink>
+ to point to the environment setup script you use.
+ <note>
+ You must also reflect this change in the value used for the
+ <filename>COREBASE_FILES</filename> variable as previously
+ described.
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='sdk-changing-the-sdk-installer-title'>
+ <title>Changing the Extensible SDK Installer Title</title>
+
+ <para>
+ You can change the displayed title for the SDK installer by setting
+ the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TITLE'><filename>SDK_TITLE</filename></ulink>
+ variable and then rebuilding the the SDK installer.
+ For information on how to build an SDK installer, see the
+ "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
+ section.
+ </para>
+
+ <para>
+ By default, this title is derived from
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink>
+ when it is set.
+ If the <filename>DISTRO_NAME</filename> variable is not set, the title
+ is derived from the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
+ variable.
+ </para>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink>
+ class defines the default value of the <filename>SDK_TITLE</filename>
+ variable as follows:
+ <literallayout class='monospaced'>
+ SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
+ </literallayout>
+ </para>
+
+ <para>
+ 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 <filename>SDK_TITLE</filename> variable
+ in the
+ <filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file
+ using the following form:
+ <literallayout class='monospaced'>
+ SDK_TITLE = "<replaceable>your_title</replaceable>"
+ </literallayout>
+ </para>
+</section>
+
+<section id='sdk-providing-updates-to-the-extensible-sdk-after-installation'>
+ <title>Providing Updates to the Extensible SDK After Installation</title>
+
+ <para>
+ 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
+ <filename>devtool sdk-update</filename> command:
+ <orderedlist>
+ <listitem><para>
+ Create a directory that can be shared over HTTP or HTTPS.
+ You can do this by setting up a web server such as an
+ <ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink>
+ or
+ <ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink>
+ server in the cloud to host the directory.
+ This directory must contain the published SDK.
+ </para></listitem>
+ <listitem><para>
+ Set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
+ 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
+ <filename>devtool sdk-update</filename> command as described
+ in the
+ "<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ Build the extensible SDK normally (i.e., use the
+ <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>
+ command).
+ </para></listitem>
+ <listitem><para>
+ Publish the SDK using the following command:
+ <literallayout class='monospaced'>
+ $ oe-publish-sdk <replaceable>some_path</replaceable>/sdk-installer.sh <replaceable>path_to_shared_http_directory</replaceable>
+ </literallayout>
+ You must repeat this step each time you rebuild the SDK
+ with changes that you want to make available through the
+ update mechanism.
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ Completing the above steps allows users of the existing installed
+ SDKs to simply run <filename>devtool sdk-update</filename> to
+ retrieve and apply the latest updates.
+ See the
+ "<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>"
+ section for further information.
+ </para>
+</section>
+
+<section id='sdk-changing-the-default-sdk-installation-directory'>
+ <title>Changing the Default SDK Installation Directory</title>
+
+ <para>
+ When you build the installer for the Extensible SDK, the default
+ installation directory for the SDK is based on the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKEXTPATH'><filename>SDKEXTPATH</filename></ulink>
+ variables from within the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink>
+ class as follows:
+ <literallayout class='monospaced'>
+ SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
+ </literallayout>
+ You can change this default installation directory by specifically
+ setting the <filename>SDKEXTPATH</filename> variable.
+ </para>
+
+ <para>
+ 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 <filename>SDKEXTPATH</filename> variable
+ in the
+ <filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file
+ using the following form:
+ <literallayout class='monospaced'>
+ SDKEXTPATH = "<replaceable>some_path_for_your_installed_sdk</replaceable>"
+ </literallayout>
+ </para>
+
+ <para>
+ After building your installer, running it prompts the user for
+ acceptance of the
+ <replaceable>some_path_for_your_installed_sdk</replaceable> directory
+ as the default location to install the Extensible SDK.
+ </para>
+</section>
+
+<section id='sdk-providing-additional-installable-extensible-sdk-content'>
+ <title>Providing Additional Installable Extensible SDK Content</title>
+
+ <para>
+ 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:
+ <orderedlist>
+ <listitem><para>
+ Ensure the additional items you want the user to be able to
+ install are already built:
+ <itemizedlist>
+ <listitem><para>
+ Build the items explicitly.
+ You could use one or more "meta" recipes that depend
+ on lists of other recipes.
+ </para></listitem>
+ <listitem><para>
+ Build the "world" target and set
+ <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable>
+ for the recipes you do not want built.
+ See the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXCLUDE_FROM_WORLD'><filename>EXCLUDE_FROM_WORLD</filename></ulink>
+ variable for additional information.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ Expose the <filename>sstate-cache</filename> directory
+ produced by the build.
+ Typically, you expose this directory by making it available
+ through an
+ <ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink>
+ or
+ <ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink>
+ server.
+ </para></listitem>
+ <listitem><para>
+ Set the appropriate configuration so that the produced SDK
+ knows how to find the configuration.
+ The variable you need to set is
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>:
+ <literallayout class='monospaced'>
+ SSTATE_MIRRORS = "file://.* http://<replaceable>example</replaceable>.com/<replaceable>some_path</replaceable>/sstate-cache/PATH"
+ </literallayout>
+ You can set the <filename>SSTATE_MIRRORS</filename> variable
+ in two different places:
+ <itemizedlist>
+ <listitem><para>
+ 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
+ <filename>local.conf</filename> or custom distro
+ configuration file.
+ You can then "whitelist" the variable through
+ to the SDK by adding the following:
+ <literallayout class='monospaced'>
+ SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Alternatively, if you just want to set the
+ <filename>SSTATE_MIRRORS</filename> variable's value
+ for the SDK alone, create a
+ <filename>conf/sdk-extra.conf</filename> file either in
+ your
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ or within any layer and put your
+ <filename>SSTATE_MIRRORS</filename> 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 <filename>SSTATE_MIRRORS</filename>.
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </orderedlist>
+ </para>
+</section>
+
+<section id='sdk-minimizing-the-size-of-the-extensible-sdk-installer-download'>
+ <title>Minimizing the Size of the Extensible SDK Installer Download</title>
+
+ <para>
+ 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
+ <filename>devtool command</filename> by setting the following in your
+ configuration:
+ <literallayout class='monospaced'>
+ SDK_EXT_TYPE = "minimal"
+ </literallayout>
+ Setting
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>
+ 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 <filename>devtool</filename> or
+ explicitly with the <filename>devtool sdk-install</filename> command.
+ </para>
+
+ <para>
+ 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 <filename>devtool add</filename> is able to effectively map
+ dependencies it discovers in a source tree to the appropriate recipes.
+ Additionally, the information enables the
+ <filename>devtool search</filename> command to return useful results.
+ </para>
+
+ <para>
+ To facilitate this wider range of information, you would need to
+ set the following:
+ <literallayout class='monospaced'>
+ SDK_INCLUDE_PKGDATA = "1"
+ </literallayout>
+ See the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink>
+ variable for additional information.
+ </para>
+
+ <para>
+ Setting the <filename>SDK_INCLUDE_PKGDATA</filename> 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.
+ </para>
+
+ <para>
+ You can use
+ <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable>
+ 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 <filename>SDK_EXT_TYPE</filename> to "minimal",
+ then providing a shared state mirror is mandatory so that items
+ can be installed as needed.
+ See the
+ "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>"
+ section for more information.
+ </note>
+ </para>
+
+ <para>
+ You can explicitly control whether or not to include the toolchain
+ when you build an SDK by setting the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink>
+ variable to "1".
+ In particular, it is useful to include the toolchain when you
+ have set <filename>SDK_EXT_TYPE</filename> 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.
+ </para>
+</section>
+</appendix>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/poky/documentation/sdk-manual/sdk-appendix-obtain.rst b/poky/documentation/sdk-manual/sdk-appendix-obtain.rst
index a51c22e..97ab916 100644
--- a/poky/documentation/sdk-manual/sdk-appendix-obtain.rst
+++ b/poky/documentation/sdk-manual/sdk-appendix-obtain.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-2.0-UK
*****************
Obtaining the SDK
diff --git a/poky/documentation/sdk-manual/sdk-appendix-obtain.xml b/poky/documentation/sdk-manual/sdk-appendix-obtain.xml
new file mode 100644
index 0000000..de7f75e
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-appendix-obtain.xml
@@ -0,0 +1,444 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<appendix id='sdk-appendix-obtain'>
+
+<title>Obtaining the SDK</title>
+
+<section id='sdk-locating-pre-built-sdk-installers'>
+ <title>Locating Pre-Built SDK Installers</title>
+
+ <para>
+ You can use existing, pre-built toolchains by locating and running
+ an SDK installer script that ships with the Yocto Project.
+ Using this method, you select and download an architecture-specific
+ SDK installer and then run the script to hand-install the
+ toolchain.
+ </para>
+
+ <para>
+ Follow these steps to locate and hand-install the toolchain:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Go to the Installers Directory:</emphasis>
+ Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Open the Folder for Your Build Host:</emphasis>
+ Open the folder that matches your
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>build host</ulink>
+ (i.e. <filename>i686</filename> for 32-bit machines or
+ <filename>x86_64</filename> for 64-bit machines).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Locate and Download the SDK Installer:</emphasis>
+ You need to find and download the installer appropriate for
+ your build host, target hardware, and image type.
+ </para>
+
+ <para>The installer files (<filename>*.sh</filename>) follow
+ this naming convention:
+ <literallayout class='monospaced'>
+ poky-glibc-<replaceable>host_system</replaceable>-core-image-<replaceable>type</replaceable>-<replaceable>arch</replaceable>-toolchain[-ext]-<replaceable>release</replaceable>.sh
+
+ Where:
+ <replaceable>host_system</replaceable> is a string representing your development system:
+ "i686" or "x86_64"
+
+ <replaceable>type</replaceable> is a string representing the image:
+ "sato" or "minimal"
+
+ <replaceable>arch</replaceable> is a string representing the target architecture:
+ "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2",
+ "mips64", or "ppc7400"
+
+ <replaceable>release</replaceable> is the version of Yocto Project.
+
+ NOTE:
+ The standard SDK installer does not have the "-ext" string as
+ part of the filename.
+
+ </literallayout>
+ The toolchains provided by the Yocto Project are based off of
+ the <filename>core-image-sato</filename> and
+ <filename>core-image-minimal</filename> images and contain
+ libraries appropriate for developing against those images.
+ </para>
+
+ <para>For example, if your build host is a 64-bit x86 system
+ and you need an extended SDK for a 64-bit core2 target, go
+ into the <filename>x86_64</filename> folder and download the
+ following installer:
+ <literallayout class='monospaced'>
+ poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Run the Installer:</emphasis>
+ Be sure you have execution privileges and run the installer.
+ Following is an example from the <filename>Downloads</filename>
+ directory:
+ <literallayout class='monospaced'>
+ $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
+ </literallayout>
+ During execution of the script, you choose the root location
+ for the toolchain.
+ See the
+ "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
+ section and the
+ "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>"
+ section for more information.
+ </para></listitem>
+ </orderedlist>
+ </para>
+</section>
+
+<section id='sdk-building-an-sdk-installer'>
+ <title>Building an SDK Installer</title>
+
+ <para>
+ As an alternative to locating and downloading an SDK installer,
+ you can build the SDK installer.
+ Follow these steps:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Set Up the Build Environment:</emphasis>
+ Be sure you are set up to use BitBake in a shell.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
+ section in the Yocto Project Development Tasks Manual for
+ information on how to get a build host ready that is either a
+ native Linux machine or a machine that uses CROPS.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
+ You need to have a local copy of the Yocto Project
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ (i.e. a local <filename>poky</filename> repository).
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
+ and possibly the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
+ and
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
+ sections all in the Yocto Project Development Tasks Manual for
+ information on how to clone the <filename>poky</filename>
+ repository and check out the appropriate branch for your work.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Initialize the Build Environment:</emphasis>
+ While in the root directory of the Source Directory (i.e.
+ <filename>poky</filename>), run the
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+ environment setup script to define the OpenEmbedded
+ build environment on your build host.
+ <literallayout class='monospaced'>
+ $ source &OE_INIT_FILE;
+ </literallayout>
+ Among other things, the script creates the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+ which is <filename>build</filename> in this case
+ and is located in the Source Directory.
+ After the script runs, your current working directory
+ is set to the <filename>build</filename> directory.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Sure You Are Building an Installer for the Correct Machine:</emphasis>
+ Check to be sure that your
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ variable in the <filename>local.conf</filename> file in your
+ Build Directory matches the architecture for which you are
+ building.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Sure Your SDK Machine is Correctly Set:</emphasis>
+ If you are building a toolchain designed to run on an
+ architecture that differs from your current development host
+ machine (i.e. the build host), be sure that the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
+ variable in the <filename>local.conf</filename> file in your
+ Build Directory is correctly set.
+ <note>
+ If you are building an SDK installer for the Extensible
+ SDK, the <filename>SDKMACHINE</filename> value must be
+ set for the architecture of the machine you are using to
+ build the installer.
+ If <filename>SDKMACHINE</filename> is not set appropriately,
+ the build fails and provides an error message similar to
+ the following:
+ <literallayout class='monospaced'>
+ The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is
+ set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64).
+ Unable to continue.
+ </literallayout>
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the SDK Installer:</emphasis>
+ To build the SDK installer for a standard SDK and populate
+ the SDK image, use the following command form.
+ Be sure to replace <replaceable>image</replaceable> with
+ an image (e.g. "core-image-sato"):
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>image</replaceable> -c populate_sdk
+ </literallayout>
+ You can do the same for the extensible SDK using this command
+ form:
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext
+ </literallayout>
+ These commands produce an SDK installer that contains the
+ sysroot that matches your target root filesystem.</para>
+
+ <para>When the <filename>bitbake</filename> command completes,
+ the SDK installer will be in
+ <filename>tmp/deploy/sdk</filename> in the Build Directory.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ By default, the previous BitBake command does not
+ build static binaries.
+ If you want to use the toolchain to build these
+ types of libraries, you need to be sure your SDK
+ has the appropriate static development libraries.
+ Use the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>
+ variable inside your <filename>local.conf</filename>
+ file before building the SDK installer.
+ Doing so ensures that the eventual SDK installation
+ process installs the appropriate library packages
+ as part of the SDK.
+ Following is an example using
+ <filename>libc</filename> static development
+ libraries:
+ <literallayout class='monospaced'>
+ TOOLCHAIN_TARGET_TASK_append = " libc-staticdev"
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Run the Installer:</emphasis>
+ You can now run the SDK installer from
+ <filename>tmp/deploy/sdk</filename> in the Build Directory.
+ Following is an example:
+ <literallayout class='monospaced'>
+ $ cd ~/poky/build/tmp/deploy/sdk
+ $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
+ </literallayout>
+ During execution of the script, you choose the root location
+ for the toolchain.
+ See the
+ "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
+ section and the
+ "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>"
+ section for more information.
+ </para></listitem>
+ </orderedlist>
+ </para>
+</section>
+
+<section id='sdk-extracting-the-root-filesystem'>
+ <title>Extracting the Root Filesystem</title>
+
+ <para>
+ After installing the toolchain, for some use cases you
+ might need to separately extract a root filesystem:
+ <itemizedlist>
+ <listitem><para>
+ You want to boot the image using NFS.
+ </para></listitem>
+ <listitem><para>
+ You want to use the root filesystem as the
+ target sysroot.
+ </para></listitem>
+ <listitem><para>
+ You want to develop your target application
+ using the root filesystem as the target sysroot.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Follow these steps to extract the root filesystem:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Locate and Download the Tarball for the Pre-Built
+ Root Filesystem Image File:</emphasis>
+ You need to find and download the root filesystem image
+ file that is appropriate for your target system.
+ These files are kept in machine-specific folders in the
+ <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/machines/'>Index of Releases</ulink>
+ in the "machines" directory.</para>
+
+ <para>The machine-specific folders of the "machines" directory
+ contain tarballs (<filename>*.tar.bz2</filename>) for supported
+ machines.
+ These directories also contain flattened root filesystem
+ image files (<filename>*.ext4</filename>), which you can use
+ with QEMU directly.</para>
+
+ <para>The pre-built root filesystem image files
+ follow these naming conventions:
+ <literallayout class='monospaced'>
+<!--
+ core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>-<replaceable>date_time</replaceable>.rootfs.tar.bz2
+-->
+ core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>.tar.bz2
+
+ Where:
+ <replaceable>profile</replaceable> is the filesystem image's profile:
+ lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs,
+ sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on
+ these types of image profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
+ the Yocto Project Reference Manual.
+
+ <replaceable>arch</replaceable> is a string representing the target architecture:
+ beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb,
+ genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*.
+
+<!-->
+ <replaceable>date_time</replaceable> is a date and time stamp.
+-->
+
+ </literallayout>
+ The root filesystems provided by the Yocto Project are based
+ off of the <filename>core-image-sato</filename> and
+ <filename>core-image-minimal</filename> images.
+ </para>
+
+ <para>For example, if you plan on using a BeagleBone device
+ as your target hardware and your image is a
+ <filename>core-image-sato-sdk</filename>
+ image, you can download the following file:
+ <literallayout class='monospaced'>
+ core-image-sato-sdk-beaglebone-yocto.tar.bz2
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Initialize the Cross-Development Environment:</emphasis>
+ You must <filename>source</filename> the cross-development
+ environment setup script to establish necessary environment
+ variables.</para>
+
+ <para>This script is located in the top-level directory in
+ which you installed the toolchain (e.g.
+ <filename>poky_sdk</filename>).</para>
+
+ <para>Following is an example based on the toolchain installed
+ in the
+ "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>"
+ section:
+ <literallayout class='monospaced'>
+ $ source ~/poky_sdk/environment-setup-core2-64-poky-linux
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Extract the Root Filesystem:</emphasis>
+ Use the <filename>runqemu-extract-sdk</filename> command
+ and provide the root filesystem image.</para>
+
+ <para>Following is an example command that extracts the root
+ filesystem from a previously built root filesystem image that
+ was downloaded from the
+ <ulink url='&YOCTO_DOCS_OM_URL;#index-downloads'>Index of Releases</ulink>.
+ This command extracts the root filesystem into the
+ <filename>core2-64-sato</filename> directory:
+ <literallayout class='monospaced'>
+ $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
+ </literallayout>
+ You could now point to the target sysroot at
+ <filename>beablebone-sato</filename>.
+ </para></listitem>
+ </orderedlist>
+ </para>
+</section>
+
+<section id='sdk-installed-standard-sdk-directory-structure'>
+ <title>Installed Standard SDK Directory Structure</title>
+
+ <para>
+ The following figure shows the resulting directory structure after
+ you install the Standard SDK by running the <filename>*.sh</filename>
+ SDK installation script:
+ </para>
+
+ <para>
+ <imagedata fileref="figures/sdk-installed-standard-sdk-directory.png" scale="80" align="center" />
+ </para>
+
+ <para>
+ The installed SDK consists of an environment setup script for the SDK,
+ a configuration file for the target, a version file for the target,
+ and the root filesystem (<filename>sysroots</filename>) needed to
+ develop objects for the target system.
+ </para>
+
+ <para>
+ Within the figure, italicized text is used to indicate replaceable
+ portions of the file or directory name.
+ For example,
+ <replaceable>install_dir</replaceable>/<replaceable>version</replaceable>
+ is the directory where the SDK is installed.
+ By default, this directory is <filename>/opt/poky/</filename>.
+ And, <replaceable>version</replaceable> represents the specific
+ snapshot of the SDK (e.g. <filename>&DISTRO;</filename>).
+ Furthermore, <replaceable>target</replaceable> represents the target
+ architecture (e.g. <filename>i586</filename>) and
+ <replaceable>host</replaceable> represents the development system's
+ architecture (e.g. <filename>x86_64</filename>).
+ Thus, the complete names of the two directories within the
+ <filename>sysroots</filename> could be
+ <filename>i586-poky-linux</filename> and
+ <filename>x86_64-pokysdk-linux</filename> for the target and host,
+ respectively.
+ </para>
+</section>
+
+<section id='sdk-installed-extensible-sdk-directory-structure'>
+ <title>Installed Extensible SDK Directory Structure</title>
+
+ <para>
+ The following figure shows the resulting directory structure after
+ you install the Extensible SDK by running the <filename>*.sh</filename>
+ SDK installation script:
+ </para>
+
+ <para>
+ <imagedata fileref="figures/sdk-installed-extensible-sdk-directory.png" scale="80" align="center" />
+ </para>
+
+ <para>
+ The installed directory structure for the extensible SDK is quite
+ different than the installed structure for the standard SDK.
+ The extensible SDK does not separate host and target parts in the
+ same manner as does the standard SDK.
+ The extensible SDK uses an embedded copy of the OpenEmbedded
+ build system, which has its own sysroots.
+ </para>
+
+ <para>
+ Of note in the directory structure are an environment setup script
+ for the SDK, a configuration file for the target, a version file for
+ the target, and log files for the OpenEmbedded build system
+ preparation script run by the installer and BitBake.
+ </para>
+
+ <para>
+ Within the figure, italicized text is used to indicate replaceable
+ portions of the file or directory name.
+ For example,
+ <replaceable>install_dir</replaceable> is the directory where the SDK
+ is installed, which is <filename>poky_sdk</filename> by default, and
+ <replaceable>target</replaceable> represents the target
+ architecture (e.g. <filename>i586</filename>).
+ </para>
+</section>
+
+</appendix>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/poky/documentation/sdk-manual/sdk-extensible.rst b/poky/documentation/sdk-manual/sdk-extensible.rst
index 5ff75ad..0f92ac9 100644
--- a/poky/documentation/sdk-manual/sdk-extensible.rst
+++ b/poky/documentation/sdk-manual/sdk-extensible.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-2.0-UK
************************
Using the Extensible SDK
diff --git a/poky/documentation/sdk-manual/sdk-extensible.xml b/poky/documentation/sdk-manual/sdk-extensible.xml
new file mode 100644
index 0000000..a73a07a
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-extensible.xml
@@ -0,0 +1,1847 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<chapter id='sdk-extensible'>
+
+ <title>Using the Extensible SDK</title>
+
+ <para>
+ 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 <filename>devtool</filename>
+ 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
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
+ <note>
+ For a side-by-side comparison of main features supported for an
+ extensible SDK as compared to a standard SDK, see the
+ "<link linkend='sdk-manual-intro'>Introduction</link>"
+ section.
+ </note>
+ </para>
+
+ <para>
+ In addition to the functionality available through
+ <filename>devtool</filename>, you can alternatively make use of the
+ toolchain directly, for example from Makefile and Autotools.
+ See the
+ "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>"
+ chapter for more information.
+ </para>
+
+ <section id='sdk-extensible-sdk-intro'>
+ <title>Why use the Extensible SDK and What is in It?</title>
+
+ <para>
+ 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 <filename>devtool</filename>
+ commands tailored for the Yocto Project environment.
+ </para>
+
+ <para>
+ 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
+ <filename>devtool</filename> functionality.
+ </para>
+ </section>
+
+ <section id='sdk-installing-the-extensible-sdk'>
+ <title>Installing the Extensible SDK</title>
+
+ <para>
+ The first thing you need to do is install the SDK on your
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink>
+ by running the <filename>*.sh</filename> installation script.
+ </para>
+
+ <para>
+ You can download a tarball installer, which includes the
+ pre-built toolchain, the <filename>runqemu</filename>
+ script, the internal build system, <filename>devtool</filename>,
+ and support files from the appropriate
+ <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink>
+ directory within the Index of Releases.
+ Toolchains are available for several 32-bit and 64-bit
+ architectures with the <filename>x86_64</filename> directories,
+ respectively.
+ The toolchains the Yocto Project provides are based off the
+ <filename>core-image-sato</filename> and
+ <filename>core-image-minimal</filename> images and contain
+ libraries appropriate for developing against that image.
+ </para>
+
+ <para>
+ 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:
+ <literallayout class='monospaced'>
+ poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh
+
+ Where:
+ <replaceable>host_system</replaceable> is a string representing your development system:
+
+ i686 or x86_64.
+
+ <replaceable>image_type</replaceable> is the image for which the SDK was built:
+
+ core-image-sato or core-image-minimal
+
+ <replaceable>arch</replaceable> is a string representing the tuned target architecture:
+
+ aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon
+
+ <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project:
+
+ &DISTRO;, &DISTRO;+snapshot
+ </literallayout>
+ 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 <filename>core-image-sato</filename> and
+ using the current &DISTRO; snapshot:
+ <literallayout class='monospaced'>
+ poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh
+ </literallayout>
+ <note>
+ As an alternative to downloading an SDK, you can build the
+ SDK installer.
+ For information on building the installer, see the
+ "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
+ section.
+ </note>
+ </para>
+
+ <para>
+ The SDK and toolchains are self-contained and by default are
+ installed into the <filename>poky_sdk</filename> 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.
+ </para>
+
+ <para>
+ 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
+ <filename>~/Downloads/</filename> 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.
+ </note>
+ <literallayout class='monospaced'>
+ $ ./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
+
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='sdk-running-the-extensible-sdk-environment-setup-script'>
+ <title>Running the Extensible SDK Environment Setup Script</title>
+
+ <para>
+ 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
+ <filename>poky_sdk</filename> directory or the directory you
+ chose during installation.
+ </para>
+
+ <para>
+ 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
+ "<filename>environment-setup</filename>" 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:
+ <literallayout class='monospaced'>
+ $ 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.
+ </literallayout>
+ Running the setup script defines many environment variables needed
+ in order to use the SDK (e.g. <filename>PATH</filename>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>,
+ and so forth).
+ If you want to see all the environment variables the script
+ exports, examine the installation file itself.
+ </para>
+ </section>
+
+ <section id='using-devtool-in-your-sdk-workflow'>
+ <title>Using <filename>devtool</filename> in Your SDK Workflow</title>
+
+ <para>
+ The cornerstone of the extensible SDK is a command-line tool
+ called <filename>devtool</filename>.
+ 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><title>Tip</title>
+ The use of <filename>devtool</filename> is not limited to
+ the extensible SDK.
+ You can use <filename>devtool</filename> to help you easily
+ develop any project whose build output must be part of an
+ image built using the build system.
+ </note>
+ </para>
+
+ <para>
+ The <filename>devtool</filename> command line is organized
+ similarly to
+ <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> in that it
+ has a number of sub-commands for each function.
+ You can run <filename>devtool --help</filename> to see all the
+ commands.
+ <note>
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename> Quick Reference</ulink>"
+ in the Yocto Project Reference Manual for a
+ <filename>devtool</filename> quick reference.
+ </note>
+ </para>
+
+ <para>
+ Three <filename>devtool</filename> subcommands exist that provide
+ entry-points into development:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>devtool add</filename></emphasis>:
+ Assists in adding new software to be built.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>devtool modify</filename></emphasis>:
+ Sets up an environment to enable you to modify the source of
+ an existing component.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>devtool upgrade</filename></emphasis>:
+ Updates an existing recipe so that you can build it for
+ an updated set of source files.
+ </para></listitem>
+ </itemizedlist>
+ As with the build system, "recipes" represent software packages
+ within <filename>devtool</filename>.
+ When you use <filename>devtool add</filename>, a recipe is
+ automatically created.
+ When you use <filename>devtool modify</filename>, 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.
+ </para>
+
+ <para>
+ The remainder of this section presents the
+ <filename>devtool add</filename>,
+ <filename>devtool modify</filename>, and
+ <filename>devtool upgrade</filename> workflows.
+ </para>
+
+ <section id='sdk-use-devtool-to-add-an-application'>
+ <title>Use <filename>devtool add</filename> to Add an Application</title>
+
+ <para>
+ The <filename>devtool add</filename> command generates
+ a new recipe based on existing source code.
+ This command takes advantage of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
+ layer that many <filename>devtool</filename> 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.
+ </para>
+
+ <para>
+ Depending on your particular scenario, the arguments and options
+ you use with <filename>devtool add</filename> form different
+ combinations.
+ The following diagram shows common development flows
+ you would use with the <filename>devtool add</filename>
+ command:
+ </para>
+
+ <para>
+ <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" />
+ </para>
+
+ <para>
+ <orderedlist>
+ <listitem><para><emphasis>Generating the New Recipe</emphasis>:
+ The top part of the flow shows three scenarios by which
+ you could use <filename>devtool add</filename> to
+ generate a recipe based on existing source code.</para>
+
+ <para>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.</para>
+
+ <para>Within the diagram, three possible scenarios
+ feed into the <filename>devtool add</filename> workflow:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Left</emphasis>:
+ 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:
+ <literallayout class='monospaced'>
+ $ devtool add <replaceable>recipe fetchuri</replaceable>
+ </literallayout>
+ With this command, <filename>devtool</filename>
+ extracts the upstream source files into a local
+ Git repository within the
+ <filename>sources</filename> folder.
+ The command then creates a recipe named
+ <replaceable>recipe</replaceable> and a
+ corresponding append file in the workspace.
+ If you do not provide
+ <replaceable>recipe</replaceable>, the command
+ makes an attempt to determine the recipe name.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Middle</emphasis>:
+ 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, <filename>devtool</filename>
+ always creates
+ a Git repository locally during the
+ extraction.
+ </note>
+ Furthermore, the first positional argument
+ <replaceable>srctree</replaceable> in this
+ case identifies where the
+ <filename>devtool add</filename> command
+ will locate the extracted code outside of the
+ workspace.
+ You need to specify an empty directory:
+ <literallayout class='monospaced'>
+ $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
+ </literallayout>
+ In summary, the source code is pulled from
+ <replaceable>fetchuri</replaceable> and
+ extracted into the location defined by
+ <replaceable>srctree</replaceable> as a local
+ Git repository.</para>
+
+ <para>Within workspace,
+ <filename>devtool</filename> creates a
+ recipe named <replaceable>recipe</replaceable>
+ along with an associated append file.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Right</emphasis>:
+ The right scenario in the figure represents a
+ situation where the
+ <replaceable>srctree</replaceable> has been
+ previously prepared outside of the
+ <filename>devtool</filename> workspace.</para>
+
+ <para>The following command provides a new
+ recipe name and identifies the existing source
+ tree location:
+ <literallayout class='monospaced'>
+ $ devtool add <replaceable>recipe srctree</replaceable>
+ </literallayout>
+ The command examines the source code and
+ creates a recipe named
+ <replaceable>recipe</replaceable> for the code
+ and places the recipe into the workspace.
+ </para>
+
+ <para>Because the extracted source code already
+ exists, <filename>devtool</filename> does not
+ try to relocate the source code into the
+ workspace - only the new recipe is placed
+ in the workspace.</para>
+
+ <para>Aside from a recipe folder, the command
+ also creates an associated append folder and
+ places an initial
+ <filename>*.bbappend</filename> file within.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Edit the Recipe</emphasis>:
+ You can use <filename>devtool edit-recipe</filename>
+ to open up the editor as defined by the
+ <filename>$EDITOR</filename> environment variable
+ and modify the file:
+ <literallayout class='monospaced'>
+ $ devtool edit-recipe <replaceable>recipe</replaceable>
+ </literallayout>
+ From within the editor, you can make modifications to
+ the recipe that take affect when you build it later.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
+ The next step you take depends on what you are going
+ to do with the new code.</para>
+
+ <para>If you need to eventually move the build output
+ to the target hardware, use the following
+ <filename>devtool</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool build <replaceable>recipe</replaceable>
+ </literallayout></para>
+
+ <para>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 <filename>devtool build-image</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool build-image <replaceable>image</replaceable>
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Deploy the Build Output</emphasis>:
+ When you use the <filename>devtool build</filename>
+ 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.
+ </note>
+ You can deploy your build output to that target
+ hardware by using the
+ <filename>devtool deploy-target</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool deploy-target <replaceable>recipe target</replaceable>
+ </literallayout>
+ The <replaceable>target</replaceable> is a live target
+ machine running as an SSH server.</para>
+
+ <para>You can, of course, also deploy the image you
+ build to actual hardware by using the
+ <filename>devtool build-image</filename> command.
+ However, <filename>devtool</filename> does not provide
+ a specific command that allows you to deploy the
+ image to actual hardware.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Finish Your Work With the Recipe</emphasis>:
+ The <filename>devtool finish</filename> 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.
+ <literallayout class='monospaced'>
+ $ devtool finish <replaceable>recipe layer</replaceable>
+ </literallayout>
+ <note>
+ Any changes you want to turn into patches must be
+ committed to the Git repository in the source tree.
+ </note></para>
+
+ <para>As mentioned, the
+ <filename>devtool finish</filename> command moves the
+ final recipe to its permanent layer.
+ </para>
+
+ <para>As a final process of the
+ <filename>devtool finish</filename> 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 <filename>devtool reset</filename>
+ 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.
+ </note>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>
+ <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title>
+
+ <para>
+ The <filename>devtool modify</filename> 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.
+ </para>
+
+ <para>
+ Depending on your particular scenario, the arguments and options
+ you use with <filename>devtool modify</filename> form different
+ combinations.
+ The following diagram shows common development flows for the
+ <filename>devtool modify</filename> command:
+ </para>
+
+ <para>
+ <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" />
+ </para>
+
+ <para>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Preparing to Modify the Code</emphasis>:
+ The top part of the flow shows three scenarios by which
+ you could use <filename>devtool modify</filename> to
+ prepare to work on source files.
+ Each scenario assumes the following:
+ <itemizedlist>
+ <listitem><para>
+ The recipe exists locally in a layer external
+ to the <filename>devtool</filename> workspace.
+ </para></listitem>
+ <listitem><para>
+ The source files exist either upstream in an
+ un-extracted state or locally in a previously
+ extracted state.
+ </para></listitem>
+ </itemizedlist>
+ 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.
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Left</emphasis>:
+ 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 <filename>devtool</filename>
+ workspace location.
+ The recipe, in this scenario, is in its own
+ layer outside the workspace
+ (i.e.
+ <filename>meta-</filename><replaceable>layername</replaceable>).
+ </para>
+
+ <para>The following command identifies the
+ recipe and, by default, extracts the source
+ files:
+ <literallayout class='monospaced'>
+ $ devtool modify <replaceable>recipe</replaceable>
+ </literallayout>
+ Once <filename>devtool</filename>locates the
+ recipe, <filename>devtool</filename> uses the
+ recipe's
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ statements to locate the source code and any
+ local patch files from other developers.</para>
+
+ <para>With this scenario, no
+ <replaceable>srctree</replaceable> argument
+ exists.
+ Consequently, the default behavior of the
+ <filename>devtool modify</filename> command is
+ to extract the source files pointed to by the
+ <filename>SRC_URI</filename> statements into a
+ local Git structure.
+ Furthermore, the location for the extracted
+ source is the default area within the
+ <filename>devtool</filename> 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.</para>
+
+ <para>Additionally, if you have any non-patch
+ local files (i.e. files referred to with
+ <filename>file://</filename> entries in
+ <filename>SRC_URI</filename> statement excluding
+ <filename>*.patch/</filename> or
+ <filename>*.diff</filename>), these files are
+ copied to an
+ <filename>oe-local-files</filename> 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.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Middle</emphasis>:
+ 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.
+ </para>
+
+ <para>The following command tells
+ <filename>devtool</filename> 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
+ <filename>devtool</filename> workspace:
+ <literallayout class='monospaced'>
+ $ devtool modify <replaceable>recipe srctree</replaceable>
+ </literallayout>
+ <note>
+ You cannot provide a URL for
+ <replaceable>srctree</replaceable> using
+ the <filename>devtool</filename> command.
+ </note>
+ As with all extractions, the command uses
+ the recipe's <filename>SRC_URI</filename>
+ statements to locate the source files and any
+ associated patch files.
+ Non-patch files are copied to an
+ <filename>oe-local-files</filename> folder
+ under the newly created source tree.</para>
+
+ <para>Once the files are located, the command
+ by default extracts them into
+ <replaceable>srctree</replaceable>.</para>
+
+ <para>Within workspace,
+ <filename>devtool</filename> 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
+ <replaceable>srctree</replaceable>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Right</emphasis>:
+ The right scenario in the figure represents a
+ situation where the source tree
+ (<replaceable>srctree</replaceable>) already
+ exists locally as a previously extracted Git
+ structure outside of the
+ <filename>devtool</filename> workspace.
+ In this example, the recipe also exists
+ elsewhere locally in its own layer.
+ </para>
+
+ <para>The following command tells
+ <filename>devtool</filename> the recipe
+ with which to work, uses the "-n" option to
+ indicate source does not need to be extracted,
+ and uses <replaceable>srctree</replaceable> to
+ point to the previously extracted source files:
+ <literallayout class='monospaced'>
+ $ devtool modify -n <replaceable>recipe srctree</replaceable>
+ </literallayout>
+ </para>
+
+ <para>If an <filename>oe-local-files</filename>
+ 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 <filename>devtool finish</filename>
+ command, any non-patch files that might exist
+ next to the recipe are removed because it
+ appears to <filename>devtool</filename> that
+ you have deleted those files.</para>
+
+ <para>Once the
+ <filename>devtool modify</filename> command
+ finishes, it creates only an append file for
+ the recipe in the <filename>devtool</filename>
+ workspace.
+ The recipe and the source code remain in their
+ original locations.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Edit the Source</emphasis>:
+ Once you have used the
+ <filename>devtool modify</filename> 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.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
+ The next step you take depends on what you are going
+ to do with the new code.</para>
+
+ <para>If you need to eventually move the build output
+ to the target hardware, use the following
+ <filename>devtool</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool build <replaceable>recipe</replaceable>
+ </literallayout></para>
+
+ <para>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 <filename>devtool build-image</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool build-image <replaceable>image</replaceable>
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Deploy the Build Output</emphasis>:
+ When you use the <filename>devtool build</filename>
+ 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.
+ </note>
+ You can deploy your build output to that target
+ hardware by using the
+ <filename>devtool deploy-target</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool deploy-target <replaceable>recipe target</replaceable>
+ </literallayout>
+ The <replaceable>target</replaceable> is a live target
+ machine running as an SSH server.</para>
+
+ <para>You can, of course, use other methods to deploy
+ the image you built using the
+ <filename>devtool build-image</filename> command to
+ actual hardware.
+ <filename>devtool</filename> does not provide
+ a specific command to deploy the image to actual
+ hardware.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Finish Your Work With the Recipe</emphasis>:
+ The <filename>devtool finish</filename> command creates
+ any patches corresponding to commits in the local
+ Git repository, updates the recipe to point to them
+ (or creates a <filename>.bbappend</filename> 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.
+ <literallayout class='monospaced'>
+ $ devtool finish <replaceable>recipe layer</replaceable>
+ </literallayout>
+ <note>
+ Any changes you want to turn into patches must be
+ staged and committed within the local Git
+ repository before you use the
+ <filename>devtool finish</filename> command.
+ </note></para>
+
+ <para>Because there is no need to move the recipe,
+ <filename>devtool finish</filename> either updates the
+ original recipe in the original layer or the command
+ creates a <filename>.bbappend</filename> file in a
+ different layer as provided by
+ <replaceable>layer</replaceable>.
+ Any work you did in the
+ <filename>oe-local-files</filename> directory is
+ preserved in the original files next to the recipe
+ during the <filename>devtool finish</filename>
+ command.</para>
+
+ <para>As a final process of the
+ <filename>devtool finish</filename> 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 <filename>devtool reset</filename>
+ 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.
+ </note>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
+ <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
+
+ <para>
+ The <filename>devtool upgrade</filename> 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 <filename>devtool upgrade</filename>
+ 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 -
+ <filename>devtool upgrade</filename> happens to be one.
+ You can read about all the methods by which you can
+ upgrade recipes in the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>"
+ section of the Yocto Project Development Tasks Manual.
+ </note>
+ </para>
+
+ <para>
+ The <filename>devtool upgrade</filename> command is flexible
+ enough to allow you to specify source code revision and
+ versioning schemes, extract code into or out of the
+ <filename>devtool</filename>
+ <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>,
+ and work with any source file forms that the
+ <ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>fetchers</ulink>
+ support.
+ </para>
+
+ <para>
+ The following diagram shows the common development flow
+ used with the <filename>devtool upgrade</filename> command:
+ </para>
+
+ <para>
+ <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" />
+ </para>
+
+ <para>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Initiate the Upgrade</emphasis>:
+ The top part of the flow shows the typical scenario by
+ which you use the <filename>devtool upgrade</filename>
+ command.
+ The following conditions exist:
+ <itemizedlist>
+ <listitem><para>
+ The recipe exists in a local layer external
+ to the <filename>devtool</filename> workspace.
+ </para></listitem>
+ <listitem><para>
+ The source files for the new release
+ exist in the same location pointed to by
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ 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).
+ </para></listitem>
+ </itemizedlist>
+ 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:
+ <literallayout class='monospaced'>
+ $ devtool upgrade -V <replaceable>version recipe</replaceable>
+ </literallayout>
+ By default, the <filename>devtool upgrade</filename>
+ command extracts source code into the
+ <filename>sources</filename> directory in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>.
+ If you want the code extracted to any other location,
+ you need to provide the
+ <replaceable>srctree</replaceable> positional argument
+ with the command as follows:
+ <literallayout class='monospaced'>
+ $ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
+ </literallayout>
+ <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.
+ </note>
+ If the source files pointed to by the
+ <filename>SRC_URI</filename> statement in the recipe
+ are in a Git repository, you must provide the "-S"
+ option and specify a revision for the software.</para>
+
+ <para>Once <filename>devtool</filename> locates the
+ recipe, it uses the <filename>SRC_URI</filename>
+ 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.</para>
+
+ <para>Additionally, if you have any non-patch
+ local files (i.e. files referred to with
+ <filename>file://</filename> entries in
+ <filename>SRC_URI</filename> statement excluding
+ <filename>*.patch/</filename> or
+ <filename>*.diff</filename>), these files are
+ copied to an
+ <filename>oe-local-files</filename> 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.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
+ Conflicts could exist due to the software being
+ upgraded to a new version.
+ Conflicts occur if your recipe specifies some patch
+ files in <filename>SRC_URI</filename> 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
+ <filename>git rebase</filename> conflict resolution
+ process.</para>
+
+ <para>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.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
+ The next step you take depends on what you are going
+ to do with the new code.</para>
+
+ <para>If you need to eventually move the build output
+ to the target hardware, use the following
+ <filename>devtool</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool build <replaceable>recipe</replaceable>
+ </literallayout></para>
+
+ <para>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 <filename>devtool build-image</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool build-image <replaceable>image</replaceable>
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Deploy the Build Output</emphasis>:
+ When you use the <filename>devtool build</filename>
+ command or <filename>bitbake</filename> 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.
+ </note>
+ You can deploy your build output to that target
+ hardware by using the
+ <filename>devtool deploy-target</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool deploy-target <replaceable>recipe target</replaceable>
+ </literallayout>
+ The <replaceable>target</replaceable> is a live target
+ machine running as an SSH server.</para>
+
+ <para>You can, of course, also deploy the image you
+ build using the
+ <filename>devtool build-image</filename> command
+ to actual hardware.
+ However, <filename>devtool</filename> does not provide
+ a specific command that allows you to do this.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Finish Your Work With the Recipe</emphasis>:
+ The <filename>devtool finish</filename> 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.</para>
+
+ <para>Any work you did in the
+ <filename>oe-local-files</filename> directory is
+ preserved in the original files next to the recipe
+ during the <filename>devtool finish</filename>
+ command.</para>
+
+ <para>
+ 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.
+ <literallayout class='monospaced'>
+ $ devtool finish <replaceable>recipe layer</replaceable>
+ </literallayout>
+ <note>
+ Any changes you want to turn into patches must be
+ committed to the Git repository in the source tree.
+ </note></para>
+
+ <para>As a final process of the
+ <filename>devtool finish</filename> 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 <filename>devtool reset</filename>
+ 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.
+ </note>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
+
+ <section id='sdk-a-closer-look-at-devtool-add'>
+ <title>A Closer Look at <filename>devtool add</filename></title>
+
+ <para>
+ The <filename>devtool add</filename> command automatically creates
+ a recipe based on the source tree you provide with the command.
+ Currently, the command has support for the following:
+ <itemizedlist>
+ <listitem><para>
+ Autotools (<filename>autoconf</filename> and
+ <filename>automake</filename>)
+ </para></listitem>
+ <listitem><para>
+ CMake
+ </para></listitem>
+ <listitem><para>
+ Scons
+ </para></listitem>
+ <listitem><para>
+ <filename>qmake</filename>
+ </para></listitem>
+ <listitem><para>
+ Plain <filename>Makefile</filename>
+ </para></listitem>
+ <listitem><para>
+ Out-of-tree kernel module
+ </para></listitem>
+ <listitem><para>
+ Binary package (i.e. "-b" option)
+ </para></listitem>
+ <listitem><para>
+ Node.js module
+ </para></listitem>
+ <listitem><para>
+ Python modules that use <filename>setuptools</filename>
+ or <filename>distutils</filename>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ 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 <filename>CMakeLists.txt</filename> 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.
+ </note>
+ </para>
+
+ <para>
+ The remainder of this section covers specifics regarding how parts
+ of the recipe are generated.
+ </para>
+
+ <section id='sdk-name-and-version'>
+ <title>Name and Version</title>
+
+ <para>
+ If you do not specify a name and version on the command
+ line, <filename>devtool add</filename> 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, <filename>devtool</filename>
+ sets the name of the created recipe file accordingly.
+ </para>
+
+ <para>
+ If <filename>devtool</filename> 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.
+ </para>
+
+ <para>
+ Sometimes the name or version determined from the source tree
+ might be incorrect.
+ For such a case, you must reset the recipe:
+ <literallayout class='monospaced'>
+ $ devtool reset -n <replaceable>recipename</replaceable>
+ </literallayout>
+ After running the <filename>devtool reset</filename> command,
+ you need to run <filename>devtool add</filename> again and
+ provide the name or the version.
+ </para>
+ </section>
+
+ <section id='sdk-dependency-detection-and-mapping'>
+ <title>Dependency Detection and Mapping</title>
+
+ <para>
+ The <filename>devtool add</filename> 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
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+ variable within the recipe.
+ If a dependency cannot be mapped, <filename>devtool</filename>
+ 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 <filename>devtool add</filename> command to add an
+ additional recipe that satisfies the dependency.
+ Once you add that recipe, you need to update the
+ <filename>DEPENDS</filename> variable in the original recipe
+ to include the new recipe.
+ </para>
+
+ <para>
+ If you need to add runtime dependencies, you can do so by
+ adding the following to your recipe:
+ <literallayout class='monospaced'>
+ RDEPENDS_${PN} += "<replaceable>dependency1 dependency2 ...</replaceable>"
+ </literallayout>
+ <note>
+ The <filename>devtool add</filename> 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.
+ </note>
+ </para>
+ </section>
+
+ <section id='sdk-license-detection'>
+ <title>License Detection</title>
+
+ <para>
+ The <filename>devtool add</filename> 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
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
+ 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
+ <filename>LICENSE</filename> value.
+ </para>
+
+ <para>
+ The <filename>devtool add</filename> command also sets the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
+ 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
+ <filename>LIC_FILES_CHKSUM</filename> variable to point to one
+ or more of those comments if present.
+ Setting <filename>LIC_FILES_CHKSUM</filename> 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.
+ </para>
+
+ <para>
+ If the <filename>devtool add</filename> command cannot
+ determine licensing information, <filename>devtool</filename>
+ sets the <filename>LICENSE</filename> value to "CLOSED" and
+ leaves the <filename>LIC_FILES_CHKSUM</filename> 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.
+ </para>
+ </section>
+
+ <section id='sdk-adding-makefile-only-software'>
+ <title>Adding Makefile-Only Software</title>
+
+ <para>
+ 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, <filename>devtool add</filename> often cannot do very
+ much to ensure that these Makefiles build correctly.
+ It is very common, for example, to explicitly call
+ <filename>gcc</filename> instead of using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
+ variable.
+ Usually, in a cross-compilation environment,
+ <filename>gcc</filename> is the compiler for the build host
+ and the cross-compiler is named something similar to
+ <filename>arm-poky-linux-gnueabi-gcc</filename> and might
+ require arguments (e.g. to point to the associated sysroot
+ for the target machine).
+ </para>
+
+ <para>
+ When writing a recipe for Makefile-only software, keep the
+ following in mind:
+ <itemizedlist>
+ <listitem><para>
+ You probably need to patch the Makefile to use
+ variables instead of hardcoding tools within the
+ toolchain such as <filename>gcc</filename> and
+ <filename>g++</filename>.
+ </para></listitem>
+ <listitem><para>
+ The environment in which Make runs is set up with
+ various standard variables for compilation (e.g.
+ <filename>CC</filename>, <filename>CXX</filename>, 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
+ <filename>devtool build</filename> command on the
+ recipe and then look in
+ <filename>oe-logs/run.do_compile</filename>.
+ 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.
+ </para></listitem>
+ <listitem><para>
+ 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
+ <filename>make</filename> command line.
+ To force the value on the command line, add the
+ variable setting to
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
+ within the recipe.
+ Here is an example using <filename>EXTRA_OEMAKE</filename>:
+ <literallayout class='monospaced'>
+ EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
+ </literallayout>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ Sometimes a Makefile runs target-specific commands such
+ as <filename>ldconfig</filename>.
+ For such cases, you might be able to apply patches that
+ remove these commands from the Makefile.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='sdk-adding-native-tools'>
+ <title>Adding Native Tools</title>
+
+ <para>
+ Often, you need to build additional tools that run on the
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
+ as opposed to the target.
+ You should indicate this requirement by using one of the
+ following methods when you run
+ <filename>devtool add</filename>:
+ <itemizedlist>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ Specify the "‐‐also-native" option with the
+ <filename>devtool add</filename> 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.
+ </para></listitem>
+ </itemizedlist>
+ <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 "‐‐also-native"
+ option, you can add the tool using just one recipe file.
+ </note>
+ </para>
+ </section>
+
+ <section id='sdk-adding-node-js-modules'>
+ <title>Adding Node.js Modules</title>
+
+ <para>
+ You can use the <filename>devtool add</filename> command two
+ different ways to add Node.js modules: 1) Through
+ <filename>npm</filename> and, 2) from a repository or local
+ source.
+ </para>
+
+ <para>
+ Use the following form to add Node.js modules through
+ <filename>npm</filename>:
+ <literallayout class='monospaced'>
+ $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
+ </literallayout>
+ 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><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ You must use quotes around the URL.
+ The <filename>devtool add</filename> does not require
+ the quotes, but the shell considers ";" as a splitter
+ between multiple commands.
+ Thus, without the quotes,
+ <filename>devtool add</filename> does not receive the
+ other parts, which results in several "command not
+ found" errors.
+ </para></listitem>
+ <listitem><para>
+ In order to support adding Node.js modules, a
+ <filename>nodejs</filename> recipe must be part
+ of your SDK.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ As mentioned earlier, you can also add Node.js modules
+ directly from a repository or local source tree.
+ To add modules this way, use <filename>devtool add</filename>
+ in the following form:
+ <literallayout class='monospaced'>
+ $ devtool add https://github.com/diversario/node-ssdp
+ </literallayout>
+ In this example, <filename>devtool</filename> fetches the
+ specified Git repository, detects the code as Node.js
+ code, fetches dependencies using <filename>npm</filename>, and
+ sets
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ accordingly.
+ </para>
+ </section>
+ </section>
+
+ <section id='sdk-working-with-recipes'>
+ <title>Working With Recipes</title>
+
+ <para>
+ When building a recipe using the
+ <filename>devtool build</filename> command, the typical build
+ progresses as follows:
+ <orderedlist>
+ <listitem><para>
+ Fetch the source
+ </para></listitem>
+ <listitem><para>
+ Unpack the source
+ </para></listitem>
+ <listitem><para>
+ Configure the source
+ </para></listitem>
+ <listitem><para>
+ Compile the source
+ </para></listitem>
+ <listitem><para>
+ Install the build output
+ </para></listitem>
+ <listitem><para>
+ Package the installed output
+ </para></listitem>
+ </orderedlist>
+ 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.
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>,
+ and so forth).
+ These functions are typically shell scripts but can instead be
+ written in Python.
+ </para>
+
+ <para>
+ 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 <filename>inherit</filename> directive.
+ This technique leaves the recipe to describe just the things that
+ are specific to the software being built.
+ A
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
+ class exists that is implicitly inherited by all recipes and
+ provides the functionality that most recipes typically need.
+ </para>
+
+ <para>
+ The remainder of this section presents information useful when
+ working with recipes.
+ </para>
+
+ <section id='sdk-finding-logs-and-work-files'>
+ <title>Finding Logs and Work Files</title>
+
+ <para>
+ After the first run of the <filename>devtool build</filename>
+ command, recipes that were previously created using the
+ <filename>devtool add</filename> command or whose sources were
+ modified using the <filename>devtool modify</filename>
+ command contain symbolic links created within the source tree:
+ <itemizedlist>
+ <listitem><para>
+ <filename>oe-logs</filename>:
+ This link points to the directory in which log files
+ and run scripts for each build step are created.
+ </para></listitem>
+ <listitem><para>
+ <filename>oe-workdir</filename>:
+ This link points to the temporary work area for the
+ recipe.
+ The following locations under
+ <filename>oe-workdir</filename> are particularly
+ useful:
+ <itemizedlist>
+ <listitem><para>
+ <filename>image/</filename>:
+ Contains all of the files installed during
+ the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ stage.
+ Within a recipe, this directory is referred
+ to by the expression
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>sysroot-destdir/</filename>:
+ Contains a subset of files installed within
+ <filename>do_install</filename> that have
+ been put into the shared sysroot.
+ For more information, see the
+ "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <filename>packages-split/</filename>:
+ Contains subdirectories for each package
+ produced by the recipe.
+ For more information, see the
+ "<link linkend='sdk-packaging'>Packaging</link>"
+ section.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+ You can use these links to get more information on what is
+ happening at each build step.
+ </para>
+ </section>
+
+ <section id='sdk-setting-configure-arguments'>
+ <title>Setting Configure Arguments</title>
+
+ <para>
+ 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
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
+ set within the recipe.
+ If you wish to pass additional options, add them to
+ <filename>EXTRA_OECONF</filename> or
+ <filename>PACKAGECONFIG_CONFARGS</filename>.
+ Other supported build tools have similar variables
+ (e.g.
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
+ for CMake,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink>
+ for Scons, and so forth).
+ If you need to pass anything on the <filename>make</filename>
+ command line, you can use <filename>EXTRA_OEMAKE</filename> or the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
+ variables to do so.
+ </para>
+
+ <para>
+ You can use the <filename>devtool configure-help</filename> 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
+ <filename>EXTRA_OECONF</filename> or
+ <filename>PACKAGECONFIG_CONFARGS</filename>.
+ If applicable, the command also shows you the output of the
+ configure script's "‐‐help" option as a reference.
+ </para>
+ </section>
+
+ <section id='sdk-sharing-files-between-recipes'>
+ <title>Sharing Files Between Recipes</title>
+
+ <para>
+ Recipes often need to use files provided by other recipes on
+ the
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>.
+ 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.
+ </para>
+
+ <para>
+ Recipes should never write files directly into the sysroot.
+ Instead, files should be installed into standard locations
+ during the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ task within the
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
+ 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.
+ </para>
+ </section>
+
+ <section id='sdk-packaging'>
+ <title>Packaging</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ During the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+ task, files installed during the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ 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 <filename>-doc</filename> package.
+ Recipes that package software containing optional modules or
+ plugins might undergo additional package splitting as well.
+ </para>
+
+ <para>
+ After building a recipe, you can see where files have gone by
+ looking in the <filename>oe-workdir/packages-split</filename>
+ directory, which contains a subdirectory for each package.
+ Apart from some advanced cases, the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
+ variables controls splitting.
+ The <filename>PACKAGES</filename> variable lists all of the
+ packages to be produced, while the <filename>FILES</filename>
+ variable specifies which files to include in each package by
+ using an override to specify the package.
+ For example, <filename>FILES_${PN}</filename> specifies the
+ files to go into the main package (i.e. the main package has
+ the same name as the recipe and
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
+ evaluates to the recipe name).
+ The order of the <filename>PACKAGES</filename> value is
+ significant.
+ For each installed file, the first package whose
+ <filename>FILES</filename> value matches the file is the
+ package into which the file goes.
+ Defaults exist for both the <filename>PACKAGES</filename> and
+ <filename>FILES</filename> 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.
+ </para>
+ </section>
+ </section>
+
+ <section id='sdk-restoring-the-target-device-to-its-original-state'>
+ <title>Restoring the Target Device to its Original State</title>
+
+ <para>
+ If you use the <filename>devtool deploy-target</filename>
+ 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
+ <filename>devtool deploy-target</filename> command.
+ Because the <filename>devtool deploy-target</filename> command
+ backs up any files it overwrites, you can use the
+ <filename>devtool undeploy-target</filename> command to restore
+ those files and remove any other files the recipe deployed.
+ Consider the following example:
+ <literallayout class='monospaced'>
+ $ devtool undeploy-target lighttpd root@192.168.7.2
+ </literallayout>
+ If you have deployed multiple applications, you can remove them
+ all using the "-a" option thus restoring the target device to its
+ original state:
+ <literallayout class='monospaced'>
+ $ devtool undeploy-target -a root@192.168.7.2
+ </literallayout>
+ 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 <filename>devtool deploy-target</filename> and
+ <filename>devtool undeploy-target</filename> commands do not
+ currently interact with any package management system on the
+ target device (e.g. RPM or OPKG).
+ Consequently, you should not intermingle
+ <filename>devtool deploy-target</filename> and package
+ manager operations on the target device.
+ Doing so could result in a conflicting set of files.
+ </note>
+ </para>
+ </section>
+
+ <section id='sdk-installing-additional-items-into-the-extensible-sdk'>
+ <title>Installing Additional Items Into the Extensible SDK</title>
+
+ <para>
+ 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 <filename>devtool search</filename> 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:
+ <literallayout class='monospaced'>
+ $ devtool search libGL
+ mesa A free implementation of the OpenGL API
+ </literallayout>
+ Once you know the recipe (i.e. <filename>mesa</filename> in this
+ example), you can install it:
+ <literallayout class='monospaced'>
+ $ devtool sdk-install mesa
+ </literallayout>
+ By default, the <filename>devtool sdk-install</filename> 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:
+ <literallayout class='monospaced'>
+ $ devtool sdk-install -s mesa
+ </literallayout>
+ 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
+ <filename>devtool add</filename> command.
+ </para>
+ </section>
+
+ <section id='sdk-applying-updates-to-an-installed-extensible-sdk'>
+ <title>Applying Updates to an Installed Extensible SDK</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ To update your installed SDK, use <filename>devtool</filename> as
+ follows:
+ <literallayout class='monospaced'>
+ $ devtool sdk-update
+ </literallayout>
+ The previous command assumes your SDK provider has set the default
+ update URL for you through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
+ variable as described in the
+ "<link linkend='sdk-providing-updates-to-the-extensible-sdk-after-installation'>Providing Updates to the Extensible SDK After Installation</link>"
+ section.
+ If the SDK provider has not set that default URL, you need to
+ specify it yourself in the command as follows:
+ <literallayout class='monospaced'>
+ $ devtool sdk-update <replaceable>path_to_update_directory</replaceable>
+ </literallayout>
+ <note>
+ The URL needs to point specifically to a published SDK and
+ not to an SDK installer that you would download and install.
+ </note>
+ </para>
+ </section>
+
+ <section id='sdk-creating-a-derivative-sdk-with-additional-components'>
+ <title>Creating a Derivative SDK With Additional Components</title>
+
+ <para>
+ 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:
+ <orderedlist>
+ <listitem><para>
+ If necessary, install an extensible SDK that
+ you want to use as a base for your derivative SDK.
+ </para></listitem>
+ <listitem><para>
+ Source the environment script for the SDK.
+ </para></listitem>
+ <listitem><para>
+ Add the extra libraries or other components you want by
+ using the <filename>devtool add</filename> command.
+ </para></listitem>
+ <listitem><para>
+ Run the <filename>devtool build-sdk</filename> command.
+ </para></listitem>
+ </orderedlist>
+ 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.
+ </para>
+ </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/poky/documentation/sdk-manual/sdk-intro.rst b/poky/documentation/sdk-manual/sdk-intro.rst
index 5a346fa..82b7bcf 100644
--- a/poky/documentation/sdk-manual/sdk-intro.rst
+++ b/poky/documentation/sdk-manual/sdk-intro.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-2.0-UK
************
Introduction
diff --git a/poky/documentation/sdk-manual/sdk-intro.xml b/poky/documentation/sdk-manual/sdk-intro.xml
new file mode 100644
index 0000000..f42670e
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-intro.xml
@@ -0,0 +1,353 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<chapter id='sdk-intro'>
+<title>Introduction</title>
+
+<section id='sdk-manual-intro'>
+ <title>Introduction</title>
+
+ <para>
+ 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.
+ </note>
+ </para>
+
+ <para>
+ All SDKs consist of the following:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Cross-Development Toolchain</emphasis>:
+ This toolchain contains a compiler, debugger, and various
+ miscellaneous tools.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Libraries, Headers, and Symbols</emphasis>:
+ The libraries, headers, and symbols are specific to the image
+ (i.e. they match the image).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Environment Setup Script</emphasis>:
+ This <filename>*.sh</filename> file, once run, sets up the
+ cross-development environment by defining variables and
+ preparing for SDK use.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ 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
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
+ </para>
+
+ <para>
+ 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
+ <filename>libc</filename>, 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
+ <filename>populate_sdk</filename> and
+ <filename>populate_sdk_ext</filename> archives.
+ </para>
+
+ <para>
+ 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 <filename>gcc</filename> as a set of compiler options.
+ Those options are set up by the environment script and contained in
+ variables such as
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>.
+ This reduces the space needed for the tools.
+ Understand, however, that every target still needs a sysroot because
+ those binaries are target-specific.
+ </para>
+
+ <para>
+ The SDK development environment consists of the following:
+ <itemizedlist>
+ <listitem><para>
+ 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
+ <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
+ configuration and extensions,
+ which allows you to cross-develop on the host machine for the
+ target hardware.
+ Additionally, the extensible SDK contains the
+ <filename>devtool</filename> functionality.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ 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:
+ <informaltable frame='none'>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth='1*'/>
+ <colspec colname='c2' colwidth='1*'/>
+ <colspec colname='c3' colwidth='1*'/>
+ <thead>
+ <row>
+ <entry align="left"><emphasis>Feature</emphasis></entry>
+ <entry align="left"><emphasis>Standard SDK</emphasis></entry>
+ <entry align="left"><emphasis>Extensible SDK</emphasis></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry align="left">Toolchain</entry>
+ <entry align="left">Yes</entry>
+ <entry align="left">Yes*</entry>
+ </row>
+ <row>
+ <entry align="left">Debugger</entry>
+ <entry align="left">Yes</entry>
+ <entry align="left">Yes*</entry>
+ </row>
+ <row>
+ <entry align="left">Size</entry>
+ <entry align="left">100+ MBytes</entry>
+ <entry align="left">1+ GBytes (or 300+ MBytes for minimal w/toolchain)</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>devtool</filename></entry>
+ <entry align="left">No</entry>
+ <entry align="left">Yes</entry>
+ </row>
+ <row>
+ <entry align="left">Build Images</entry>
+ <entry align="left">No</entry>
+ <entry align="left">Yes</entry>
+ </row>
+ <row>
+ <entry align="left">Updateable</entry>
+ <entry align="left">No</entry>
+ <entry align="left">Yes</entry>
+ </row>
+ <row>
+ <entry align="left">Managed Sysroot**</entry>
+ <entry align="left">No</entry>
+ <entry align="left">Yes</entry>
+ </row>
+ <row>
+ <entry align="left">Installed Packages</entry>
+ <entry align="left">No***</entry>
+ <entry align="left">Yes****</entry>
+ </row>
+ <row>
+ <entry align="left">Construction</entry>
+ <entry align="left">Packages</entry>
+ <entry align="left">Shared State</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <literallayout class='monospaced'>
+ * Extensible SDK contains the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default.
+
+ ** Sysroot is managed through the use of <filename>devtool</filename>. 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.
+ </literallayout>
+ </para>
+
+ <section id='the-cross-development-toolchain'>
+ <title>The Cross-Development Toolchain</title>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink>
+ 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 <filename>devtool</filename> functionality.
+ This toolchain is created by running a SDK installer script
+ or through a
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ that is based on your metadata configuration or extension for
+ your targeted device.
+ The cross-toolchain works with a matching target sysroot.
+ </para>
+ </section>
+
+ <section id='sysroot'>
+ <title>Sysroots</title>
+
+ <para>
+ 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.
+ </para>
+ </section>
+
+ <section id='the-qemu-emulator'>
+ <title>The QEMU Emulator</title>
+
+ <para>
+ 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:
+ <itemizedlist>
+ <listitem><para>
+ If you have cloned the <filename>poky</filename> Git
+ repository to create a
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ and you have sourced the environment setup script, QEMU is
+ installed and automatically available.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</section>
+
+<section id='sdk-development-model'>
+ <title>SDK Development Model</title>
+
+ <para>
+ Fundamentally, the SDK fits into the development process as follows:
+ <imagedata fileref="figures/sdk-environment.png" align="center" width="6in" depth="5in" scalefit="100" />
+ The SDK is installed on any machine and can be used to develop
+ applications, images, and kernels.
+ An SDK can even be used by a QA Engineer or Release Engineer.
+ The fundamental concept is that the machine that has the SDK installed
+ does not have to be associated with the machine that has the
+ Yocto Project installed.
+ A developer can independently compile and test an object on their
+ machine and then, when the object is ready for integration into an
+ image, they can simply make it available to the machine that has the
+ Yocto Project.
+ Once the object is available, the image can be rebuilt using the
+ Yocto Project to produce the modified image.
+ </para>
+
+ <para>
+ You just need to follow these general steps:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Install the SDK for your target hardware:</emphasis>
+ For information on how to install the SDK, see the
+ "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Download or Build the Target Image:</emphasis>
+ The Yocto Project supports several target architectures
+ and has many pre-built kernel images and root filesystem
+ images.</para>
+
+ <para>If you are going to develop your application on
+ hardware, go to the
+ <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
+ 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
+ <filename>.hddimg</filename> 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.</para>
+
+ <para>If you are going to develop your application and
+ then run and test it using the QEMU emulator, go to the
+ <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink>
+ download area.
+ From this area, go down into the directory for your
+ target architecture (e.g. <filename>qemux86_64</filename>
+ for an <trademark class='registered'>Intel</trademark>-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
+ "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
+ section for information on how to extract the root
+ filesystem.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Develop and Test your Application:</emphasis>
+ 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
+ <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink>
+ to download and learn about the emulator.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
+ chapter in the Yocto Project Development Tasks Manual
+ for information on using QEMU within the Yocto
+ Project.
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ 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.
+ </para>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/poky/documentation/sdk-manual/sdk-manual-customization.xsl b/poky/documentation/sdk-manual/sdk-manual-customization.xsl
new file mode 100644
index 0000000..4f8816f
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-manual-customization.xsl
@@ -0,0 +1,28 @@
+<?xml version='1.0'?>
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+
+ <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
+
+<!--
+ <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
+
+ <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
+
+-->
+
+ <xsl:include href="../template/permalinks.xsl"/>
+ <xsl:include href="../template/section.title.xsl"/>
+ <xsl:include href="../template/component.title.xsl"/>
+ <xsl:include href="../template/division.title.xsl"/>
+ <xsl:include href="../template/formal.object.heading.xsl"/>
+
+ <xsl:param name="html.stylesheet" select="'sdk-style.css'" />
+ <xsl:param name="chapter.autolabel" select="1" />
+ <xsl:param name="appendix.autolabel">A</xsl:param>
+ <xsl:param name="section.autolabel" select="1" />
+ <xsl:param name="section.label.includes.component.label" select="1" />
+ <xsl:param name="generate.id.attributes" select="1" />
+
+</xsl:stylesheet>
diff --git a/poky/documentation/sdk-manual/sdk-manual.rst b/poky/documentation/sdk-manual/sdk-manual.rst
index 177826e..d7776b7 100644
--- a/poky/documentation/sdk-manual/sdk-manual.rst
+++ b/poky/documentation/sdk-manual/sdk-manual.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-2.0-UK
========================================================================================
Yocto Project Application Development and the Extensible Software Development Kit (eSDK)
diff --git a/poky/documentation/sdk-manual/sdk-manual.xml b/poky/documentation/sdk-manual/sdk-manual.xml
new file mode 100755
index 0000000..6344478
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-manual.xml
@@ -0,0 +1,159 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<book id='sdk-manual' lang='en'
+ xmlns:xi="http://www.w3.org/2003/XInclude"
+ xmlns="http://docbook.org/ns/docbook"
+ >
+ <bookinfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref='figures/sdk-title.png'
+ format='SVG'
+ align='left' scalefit='1' width='100%'/>
+ </imageobject>
+ </mediaobject>
+
+ <title>
+ Yocto Project Application Development and the Extensible Software Development Kit (eSDK)
+ </title>
+
+ <authorgroup>
+ <author>
+ <affiliation>
+ <orgname>&ORGNAME;</orgname>
+ </affiliation>
+ <email>&ORGEMAIL;</email>
+ </author>
+ </authorgroup>
+
+ <revhistory>
+ <revision>
+ <revnumber>2.1</revnumber>
+ <date>April 2016</date>
+ <revremark>The initial document released with the Yocto Project 2.1 Release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>2.2</revnumber>
+ <date>October 2016</date>
+ <revremark>Released with the Yocto Project 2.2 Release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>2.3</revnumber>
+ <date>May 2017</date>
+ <revremark>Released with the Yocto Project 2.3 Release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>2.4</revnumber>
+ <date>October 2017</date>
+ <revremark>Released with the Yocto Project 2.4 Release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>2.5</revnumber>
+ <date>May 2018</date>
+ <revremark>Released with the Yocto Project 2.5 Release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>2.6</revnumber>
+ <date>November 2018</date>
+ <revremark>Released with the Yocto Project 2.6 Release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>2.7</revnumber>
+ <date>May 2019</date>
+ <revremark>Released with the Yocto Project 2.7 Release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>3.0</revnumber>
+ <date>October 2019</date>
+ <revremark>Released with the Yocto Project 3.0 Release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>3.1</revnumber>
+ <date>&REL_MONTH_YEAR;</date>
+ <revremark>Released with the Yocto Project 3.1 Release.</revremark>
+ </revision>
+ </revhistory>
+
+ <copyright>
+ <year>©RIGHT_YEAR;</year>
+ <holder>Linux Foundation</holder>
+ </copyright>
+
+ <legalnotice>
+ <para>
+ Permission is granted to copy, distribute and/or modify this document under
+ the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons.
+ </para>
+ <note><title>Manual Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ This version of the
+ <emphasis>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</emphasis>
+ manual is for the &YOCTO_DOC_VERSION; release of the
+ Yocto Project.
+ To be sure you have the latest version of the manual
+ for this release, go to the
+ <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
+ and select the manual from that site.
+ Manuals from the site are more up-to-date than manuals
+ derived from the Yocto Project released TAR files.
+ </para></listitem>
+ <listitem><para>
+ If you located this manual through a web search, the
+ version of the manual might not be the one you want
+ (e.g. the search might have returned a manual much
+ older than the Yocto Project version with which you
+ are working).
+ You can see all Yocto Project major releases by
+ visiting the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+ page.
+ If you need a version of this manual for a different
+ Yocto Project release, visit the
+ <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
+ and select the manual set by using the
+ "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+ pull-down menus.
+ </para></listitem>
+ <listitem>
+ <para>
+ To report any inaccuracies or problems with this
+ (or any other Yocto Project) manual, send an email to
+ the Yocto Project documentation mailing list at
+ <filename>docs@lists.yoctoproject.org</filename> or
+ log into the freenode <filename>#yocto</filename> channel.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </note>
+ </legalnotice>
+
+ </bookinfo>
+
+ <xi:include href="sdk-intro.xml"/>
+
+ <xi:include href="sdk-extensible.xml"/>
+
+ <xi:include href="sdk-using.xml"/>
+
+ <xi:include href="sdk-working-projects.xml"/>
+
+ <xi:include href="sdk-appendix-obtain.xml"/>
+
+ <xi:include href="sdk-appendix-customizing.xml"/>
+
+ <xi:include href="sdk-appendix-customizing-standard.xml"/>
+
+<!-- <index id='index'>
+ <title>Index</title>
+ </index>
+-->
+
+</book>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/poky/documentation/sdk-manual/sdk-style.css b/poky/documentation/sdk-manual/sdk-style.css
new file mode 100644
index 0000000..e0c4416
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-style.css
@@ -0,0 +1,991 @@
+/*
+
+ SPDX-License-Identifier: CC-BY-2.0-UK
+
+ Generic XHTML / DocBook XHTML CSS Stylesheet.
+
+ Browser wrangling and typographic design by
+ Oyvind Kolas / pippin@gimp.org
+
+ Customised for Poky by
+ Matthew Allum / mallum@o-hand.com
+
+ Thanks to:
+ Liam R. E. Quin
+ William Skaggs
+ Jakub Steiner
+
+ Structure
+ ---------
+
+ The stylesheet is divided into the following sections:
+
+ Positioning
+ Margins, paddings, width, font-size, clearing.
+ Decorations
+ Borders, style
+ Colors
+ Colors
+ Graphics
+ Graphical backgrounds
+ Nasty IE tweaks
+ Workarounds needed to make it work in internet explorer,
+ currently makes the stylesheet non validating, but up until
+ this point it is validating.
+ Mozilla extensions
+ Transparency for footer
+ Rounded corners on boxes
+
+*/
+
+
+ /*************** /
+ / Positioning /
+/ ***************/
+
+body {
+ font-family: Verdana, Sans, sans-serif;
+
+ min-width: 640px;
+ width: 80%;
+ margin: 0em auto;
+ padding: 2em 5em 5em 5em;
+ color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+ font-family: Arial, Sans;
+ color: #00557D;
+ clear: both;
+}
+
+h1 {
+ font-size: 2em;
+ text-align: left;
+ padding: 0em 0em 0em 0em;
+ margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+ margin: 0.10em 0em 3.0em 0em;
+ padding: 0em 0em 0em 0em;
+ font-size: 1.8em;
+ padding-left: 20%;
+ font-weight: normal;
+ font-style: italic;
+}
+
+h2 {
+ margin: 2em 0em 0.66em 0em;
+ padding: 0.5em 0em 0em 0em;
+ font-size: 1.5em;
+ font-weight: bold;
+}
+
+h3.subtitle {
+ margin: 0em 0em 1em 0em;
+ padding: 0em 0em 0em 0em;
+ font-size: 142.14%;
+ text-align: right;
+}
+
+h3 {
+ margin: 1em 0em 0.5em 0em;
+ padding: 1em 0em 0em 0em;
+ font-size: 140%;
+ font-weight: bold;
+}
+
+h4 {
+ margin: 1em 0em 0.5em 0em;
+ padding: 1em 0em 0em 0em;
+ font-size: 120%;
+ font-weight: bold;
+}
+
+h5 {
+ margin: 1em 0em 0.5em 0em;
+ padding: 1em 0em 0em 0em;
+ font-size: 110%;
+ font-weight: bold;
+}
+
+h6 {
+ margin: 1em 0em 0em 0em;
+ padding: 1em 0em 0em 0em;
+ font-size: 110%;
+ font-weight: bold;
+}
+
+.authorgroup {
+ background-color: transparent;
+ background-repeat: no-repeat;
+ padding-top: 256px;
+ background-image: url("figures/sdk-title.png");
+ background-position: left top;
+ margin-top: -256px;
+ padding-right: 50px;
+ margin-left: 0px;
+ text-align: right;
+ width: 740px;
+}
+
+h3.author {
+ margin: 0em 0me 0em 0em;
+ padding: 0em 0em 0em 0em;
+ font-weight: normal;
+ font-size: 100%;
+ color: #333;
+ clear: both;
+}
+
+.author tt.email {
+ font-size: 66%;
+}
+
+.titlepage hr {
+ width: 0em;
+ clear: both;
+}
+
+.revhistory {
+ padding-top: 2em;
+ clear: both;
+}
+
+.toc,
+.list-of-tables,
+.list-of-examples,
+.list-of-figures {
+ padding: 1.33em 0em 2.5em 0em;
+ color: #00557D;
+}
+
+.toc p,
+.list-of-tables p,
+.list-of-figures p,
+.list-of-examples p {
+ padding: 0em 0em 0em 0em;
+ padding: 0em 0em 0.3em;
+ margin: 1.5em 0em 0em 0em;
+}
+
+.toc p b,
+.list-of-tables p b,
+.list-of-figures p b,
+.list-of-examples p b{
+ font-size: 100.0%;
+ font-weight: bold;
+}
+
+.toc dl,
+.list-of-tables dl,
+.list-of-figures dl,
+.list-of-examples dl {
+ margin: 0em 0em 0.5em 0em;
+ padding: 0em 0em 0em 0em;
+}
+
+.toc dt {
+ margin: 0em 0em 0em 0em;
+ padding: 0em 0em 0em 0em;
+}
+
+.toc dd {
+ margin: 0em 0em 0em 2.6em;
+ padding: 0em 0em 0em 0em;
+}
+
+div.glossary dl,
+div.variablelist dl {
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+ font-weight: normal;
+ width: 20em;
+ text-align: right;
+}
+
+.variablelist dl dt {
+ margin-top: 0.5em;
+}
+
+.glossary dl dd,
+.variablelist dl dd {
+ margin-top: -1em;
+ margin-left: 25.5em;
+}
+
+.glossary dd p,
+.variablelist dd p {
+ margin-top: 0em;
+ margin-bottom: 1em;
+}
+
+
+div.calloutlist table td {
+ padding: 0em 0em 0em 0em;
+ margin: 0em 0em 0em 0em;
+}
+
+div.calloutlist table td p {
+ margin-top: 0em;
+ margin-bottom: 1em;
+}
+
+div p.copyright {
+ text-align: left;
+}
+
+div.legalnotice p.legalnotice-title {
+ margin-bottom: 0em;
+}
+
+p {
+ line-height: 1.5em;
+ margin-top: 0em;
+
+}
+
+dl {
+ padding-top: 0em;
+}
+
+hr {
+ border: solid 1px;
+}
+
+
+.mediaobject,
+.mediaobjectco {
+ text-align: center;
+}
+
+img {
+ border: none;
+}
+
+ul {
+ padding: 0em 0em 0em 1.5em;
+}
+
+ul li {
+ padding: 0em 0em 0em 0em;
+}
+
+ul li p {
+ text-align: left;
+}
+
+table {
+ width :100%;
+}
+
+th {
+ padding: 0.25em;
+ text-align: left;
+ font-weight: normal;
+ vertical-align: top;
+}
+
+td {
+ padding: 0.25em;
+ vertical-align: top;
+}
+
+p a[id] {
+ margin: 0px;
+ padding: 0px;
+ display: inline;
+ background-image: none;
+}
+
+a {
+ text-decoration: underline;
+ color: #444;
+}
+
+pre {
+ overflow: auto;
+}
+
+a:hover {
+ text-decoration: underline;
+ /*font-weight: bold;*/
+}
+
+/* This style defines how the permalink character
+ appears by itself and when hovered over with
+ the mouse. */
+
+[alt='Permalink'] { color: #eee; }
+[alt='Permalink']:hover { color: black; }
+
+
+div.informalfigure,
+div.informalexample,
+div.informaltable,
+div.figure,
+div.table,
+div.example {
+ margin: 1em 0em;
+ padding: 1em;
+ page-break-inside: avoid;
+}
+
+
+div.informalfigure p.title b,
+div.informalexample p.title b,
+div.informaltable p.title b,
+div.figure p.title b,
+div.example p.title b,
+div.table p.title b{
+ padding-top: 0em;
+ margin-top: 0em;
+ font-size: 100%;
+ font-weight: normal;
+}
+
+.mediaobject .caption,
+.mediaobject .caption p {
+ text-align: center;
+ font-size: 80%;
+ padding-top: 0.5em;
+ padding-bottom: 0.5em;
+}
+
+.epigraph {
+ padding-left: 55%;
+ margin-bottom: 1em;
+}
+
+.epigraph p {
+ text-align: left;
+}
+
+.epigraph .quote {
+ font-style: italic;
+}
+.epigraph .attribution {
+ font-style: normal;
+ text-align: right;
+}
+
+span.application {
+ font-style: italic;
+}
+
+.programlisting {
+ font-family: monospace;
+ font-size: 80%;
+ white-space: pre;
+ margin: 1.33em 0em;
+ padding: 1.33em;
+}
+
+.tip,
+.warning,
+.caution,
+.note {
+ margin-top: 1em;
+ margin-bottom: 1em;
+
+}
+
+/* force full width of table within div */
+.tip table,
+.warning table,
+.caution table,
+.note table {
+ border: none;
+ width: 100%;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+ padding: 0.8em 0.0em 0.0em 0.0em;
+ margin : 0em 0em 0em 0em;
+}
+
+.tip p,
+.warning p,
+.caution p,
+.note p {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+ padding-right: 1em;
+ text-align: left;
+}
+
+.acronym {
+ text-transform: uppercase;
+}
+
+b.keycap,
+.keycap {
+ padding: 0.09em 0.3em;
+ margin: 0em;
+}
+
+.itemizedlist li {
+ clear: none;
+}
+
+.filename {
+ font-size: medium;
+ font-family: Courier, monospace;
+}
+
+
+div.navheader, div.heading{
+ position: absolute;
+ left: 0em;
+ top: 0em;
+ width: 100%;
+ background-color: #cdf;
+ width: 100%;
+}
+
+div.navfooter, div.footing{
+ position: fixed;
+ left: 0em;
+ bottom: 0em;
+ background-color: #eee;
+ width: 100%;
+}
+
+
+div.navheader td,
+div.navfooter td {
+ font-size: 66%;
+}
+
+div.navheader table th {
+ /*font-family: Georgia, Times, serif;*/
+ /*font-size: x-large;*/
+ font-size: 80%;
+}
+
+div.navheader table {
+ border-left: 0em;
+ border-right: 0em;
+ border-top: 0em;
+ width: 100%;
+}
+
+div.navfooter table {
+ border-left: 0em;
+ border-right: 0em;
+ border-bottom: 0em;
+ width: 100%;
+}
+
+div.navheader table td a,
+div.navfooter table td a {
+ color: #777;
+ text-decoration: none;
+}
+
+/* normal text in the footer */
+div.navfooter table td {
+ color: black;
+}
+
+div.navheader table td a:visited,
+div.navfooter table td a:visited {
+ color: #444;
+}
+
+
+/* links in header and footer */
+div.navheader table td a:hover,
+div.navfooter table td a:hover {
+ text-decoration: underline;
+ background-color: transparent;
+ color: #33a;
+}
+
+div.navheader hr,
+div.navfooter hr {
+ display: none;
+}
+
+
+.qandaset tr.question td p {
+ margin: 0em 0em 1em 0em;
+ padding: 0em 0em 0em 0em;
+}
+
+.qandaset tr.answer td p {
+ margin: 0em 0em 1em 0em;
+ padding: 0em 0em 0em 0em;
+}
+.answer td {
+ padding-bottom: 1.5em;
+}
+
+.emphasis {
+ font-weight: bold;
+}
+
+
+ /************* /
+ / decorations /
+/ *************/
+
+.titlepage {
+}
+
+.part .title {
+}
+
+.subtitle {
+ border: none;
+}
+
+/*
+h1 {
+ border: none;
+}
+
+h2 {
+ border-top: solid 0.2em;
+ border-bottom: solid 0.06em;
+}
+
+h3 {
+ border-top: 0em;
+ border-bottom: solid 0.06em;
+}
+
+h4 {
+ border: 0em;
+ border-bottom: solid 0.06em;
+}
+
+h5 {
+ border: 0em;
+}
+*/
+
+.programlisting {
+ border: solid 1px;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example {
+ border: 1px solid;
+}
+
+
+
+.tip,
+.warning,
+.caution,
+.note {
+ border: 1px solid;
+}
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+ border-bottom: 1px solid;
+}
+
+.question td {
+ border-top: 1px solid black;
+}
+
+.answer {
+}
+
+
+b.keycap,
+.keycap {
+ border: 1px solid;
+}
+
+
+div.navheader, div.heading{
+ border-bottom: 1px solid;
+}
+
+
+div.navfooter, div.footing{
+ border-top: 1px solid;
+}
+
+ /********* /
+ / colors /
+/ *********/
+
+body {
+ color: #333;
+ background: white;
+}
+
+a {
+ background: transparent;
+}
+
+a:hover {
+ background-color: #dedede;
+}
+
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7,
+h8 {
+ background-color: transparent;
+}
+
+hr {
+ border-color: #aaa;
+}
+
+
+.tip, .warning, .caution, .note {
+ border-color: #fff;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+ border-bottom-color: #fff;
+}
+
+
+.warning {
+ background-color: #f0f0f2;
+}
+
+.caution {
+ background-color: #f0f0f2;
+}
+
+.tip {
+ background-color: #f0f0f2;
+}
+
+.note {
+ background-color: #f0f0f2;
+}
+
+.writernotes {
+ color: #ff0000;
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+ color: #044;
+}
+
+div.figure,
+div.table,
+div.example,
+div.informalfigure,
+div.informaltable,
+div.informalexample {
+ border-color: #aaa;
+}
+
+pre.programlisting {
+ color: black;
+ background-color: #fff;
+ border-color: #aaa;
+ border-width: 2px;
+}
+
+.guimenu,
+.guilabel,
+.guimenuitem {
+ background-color: #eee;
+}
+
+
+b.keycap,
+.keycap {
+ background-color: #eee;
+ border-color: #999;
+}
+
+
+div.navheader {
+ border-color: black;
+}
+
+
+div.navfooter {
+ border-color: black;
+}
+
+
+ /*********** /
+ / graphics /
+/ ***********/
+
+/*
+body {
+ background-image: url("images/body_bg.jpg");
+ background-attachment: fixed;
+}
+
+.navheader,
+.note,
+.tip {
+ background-image: url("images/note_bg.jpg");
+ background-attachment: fixed;
+}
+
+.warning,
+.caution {
+ background-image: url("images/warning_bg.jpg");
+ background-attachment: fixed;
+}
+
+.figure,
+.informalfigure,
+.example,
+.informalexample,
+.table,
+.informaltable {
+ background-image: url("images/figure_bg.jpg");
+ background-attachment: fixed;
+}
+
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7{
+}
+
+/*
+Example of how to stick an image as part of the title.
+
+div.article .titlepage .title
+{
+ background-image: url("figures/white-on-black.png");
+ background-position: center;
+ background-repeat: repeat-x;
+}
+*/
+
+div.preface .titlepage .title,
+div.colophon .title,
+div.chapter .titlepage .title,
+div.article .titlepage .title
+{
+}
+
+div.section div.section .titlepage .title,
+div.sect2 .titlepage .title {
+ background: none;
+}
+
+
+h1.title {
+ background-color: transparent;
+ background-repeat: no-repeat;
+ height: 256px;
+ text-indent: -9000px;
+ overflow:hidden;
+}
+
+h2.subtitle {
+ background-color: transparent;
+ text-indent: -9000px;
+ overflow:hidden;
+ width: 0px;
+ display: none;
+}
+
+ /*************************************** /
+ / pippin.gimp.org specific alterations /
+/ ***************************************/
+
+/*
+div.heading, div.navheader {
+ color: #777;
+ font-size: 80%;
+ padding: 0;
+ margin: 0;
+ text-align: left;
+ position: absolute;
+ top: 0px;
+ left: 0px;
+ width: 100%;
+ height: 50px;
+ background: url('/gfx/heading_bg.png') transparent;
+ background-repeat: repeat-x;
+ background-attachment: fixed;
+ border: none;
+}
+
+div.heading a {
+ color: #444;
+}
+
+div.footing, div.navfooter {
+ border: none;
+ color: #ddd;
+ font-size: 80%;
+ text-align:right;
+
+ width: 100%;
+ padding-top: 10px;
+ position: absolute;
+ bottom: 0px;
+ left: 0px;
+
+ background: url('/gfx/footing_bg.png') transparent;
+}
+*/
+
+
+
+ /****************** /
+ / nasty ie tweaks /
+/ ******************/
+
+/*
+div.heading, div.navheader {
+ width:expression(document.body.clientWidth + "px");
+}
+
+div.footing, div.navfooter {
+ width:expression(document.body.clientWidth + "px");
+ margin-left:expression("-5em");
+}
+body {
+ padding:expression("4em 5em 0em 5em");
+}
+*/
+
+ /**************************************** /
+ / mozilla vendor specific css extensions /
+/ ****************************************/
+/*
+div.navfooter, div.footing{
+ -moz-opacity: 0.8em;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example,
+.tip,
+.warning,
+.caution,
+.note {
+ -moz-border-radius: 0.5em;
+}
+
+b.keycap,
+.keycap {
+ -moz-border-radius: 0.3em;
+}
+*/
+
+table tr td table tr td {
+ display: none;
+}
+
+
+hr {
+ display: none;
+}
+
+table {
+ border: 0em;
+}
+
+ .photo {
+ float: right;
+ margin-left: 1.5em;
+ margin-bottom: 1.5em;
+ margin-top: 0em;
+ max-width: 17em;
+ border: 1px solid gray;
+ padding: 3px;
+ background: white;
+}
+ .seperator {
+ padding-top: 2em;
+ clear: both;
+ }
+
+ #validators {
+ margin-top: 5em;
+ text-align: right;
+ color: #777;
+ }
+ @media print {
+ body {
+ font-size: 8pt;
+ }
+ .noprint {
+ display: none;
+ }
+ }
+
+
+.tip,
+.note {
+ background: #f0f0f2;
+ color: #333;
+ padding: 20px;
+ margin: 20px;
+}
+
+.tip h3,
+.note h3 {
+ padding: 0em;
+ margin: 0em;
+ font-size: 2em;
+ font-weight: bold;
+ color: #333;
+}
+
+.tip a,
+.note a {
+ color: #333;
+ text-decoration: underline;
+}
+
+.footnote {
+ font-size: small;
+ color: #333;
+}
+
+/* Changes the announcement text */
+.tip h3,
+.warning h3,
+.caution h3,
+.note h3 {
+ font-size:large;
+ color: #00557D;
+}
diff --git a/poky/documentation/sdk-manual/sdk-using.rst b/poky/documentation/sdk-manual/sdk-using.rst
index 4b151e4..09a194c 100644
--- a/poky/documentation/sdk-manual/sdk-using.rst
+++ b/poky/documentation/sdk-manual/sdk-using.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-2.0-UK
**********************
Using the Standard SDK
diff --git a/poky/documentation/sdk-manual/sdk-using.xml b/poky/documentation/sdk-manual/sdk-using.xml
new file mode 100644
index 0000000..28ee50d
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-using.xml
@@ -0,0 +1,201 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<chapter id='sdk-using-the-standard-sdk'>
+ <title>Using the Standard SDK</title>
+
+ <para>
+ 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
+ "<link linkend='sdk-manual-intro'>Introduction</link>"
+ section.
+ </note>
+ </para>
+
+ <para>
+ You can use a standard SDK to work on Makefile and Autotools-based
+ projects.
+ See the
+ "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>"
+ chapter for more information.
+ </para>
+
+ <section id='sdk-standard-sdk-intro'>
+ <title>Why use the Standard SDK and What is in It?</title>
+
+ <para>
+ 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
+ <filename>devtool</filename> functionality.
+ </para>
+
+ <para>
+ 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
+ "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
+ section.
+ </para>
+ </section>
+
+ <section id='sdk-installing-the-sdk'>
+ <title>Installing the SDK</title>
+
+ <para>
+ The first thing you need to do is install the SDK on your
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink>
+ by running the <filename>*.sh</filename> installation script.
+ </para>
+
+ <para>
+ You can download a tarball installer, which includes the
+ pre-built toolchain, the <filename>runqemu</filename>
+ script, and support files from the appropriate
+ <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink>
+ directory within the Index of Releases.
+ Toolchains are available for several 32-bit and 64-bit
+ architectures with the <filename>x86_64</filename> directories,
+ respectively.
+ The toolchains the Yocto Project provides are based off the
+ <filename>core-image-sato</filename> and
+ <filename>core-image-minimal</filename> images and contain
+ libraries appropriate for developing against that image.
+ </para>
+
+ <para>
+ 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.
+ <literallayout class='monospaced'>
+ poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh
+
+ Where:
+ <replaceable>host_system</replaceable> is a string representing your development system:
+
+ i686 or x86_64.
+
+ <replaceable>image_type</replaceable> is the image for which the SDK was built:
+
+ core-image-minimal or core-image-sato.
+
+ <replaceable>arch</replaceable> is a string representing the tuned target architecture:
+
+ aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon.
+
+ <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project:
+
+ &DISTRO;, &DISTRO;+snapshot
+ </literallayout>
+ 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 <filename>core-image-sato</filename> and
+ using the current &DISTRO; snapshot:
+ <literallayout class='monospaced'>
+ poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+ </literallayout>
+ <note>
+ As an alternative to downloading an SDK, you can build the
+ SDK installer.
+ For information on building the installer, see the
+ "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
+ section.
+ </note>
+ </para>
+
+ <para>
+ The SDK and toolchains are self-contained and by default are
+ installed into the <filename>poky_sdk</filename> 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.
+ </para>
+
+ <para>
+ 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
+ <filename>~/Downloads/</filename> 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.
+ </note>
+ <literallayout class='monospaced'>
+ $ ./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
+ </literallayout>
+ </para>
+
+ <para>
+ Again, reference the
+ "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
+ section for more details on the resulting directory structure of
+ the installed SDK.
+ </para>
+ </section>
+
+ <section id='sdk-running-the-sdk-environment-setup-script'>
+ <title>Running the SDK Environment Setup Script</title>
+
+ <para>
+ 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
+ <filename>/opt/poky/&DISTRO;</filename> directory or the directory
+ you chose during installation.
+ </para>
+
+ <para>
+ 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
+ "<filename>environment-setup</filename>" 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:
+ <literallayout class='monospaced'>
+ $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+ </literallayout>
+ 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
+ "<link linkend='sdk-running-the-extensible-sdk-environment-setup-script'>Running the Extensible SDK Environment Setup Script</link>"
+ section for more information.
+ </para>
+ </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/poky/documentation/sdk-manual/sdk-working-projects.rst b/poky/documentation/sdk-manual/sdk-working-projects.rst
index 5c828fd..2c20a1e 100644
--- a/poky/documentation/sdk-manual/sdk-working-projects.rst
+++ b/poky/documentation/sdk-manual/sdk-working-projects.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-2.0-UK
********************************
Using the SDK Toolchain Directly
diff --git a/poky/documentation/sdk-manual/sdk-working-projects.xml b/poky/documentation/sdk-manual/sdk-working-projects.xml
new file mode 100644
index 0000000..070d903
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-working-projects.xml
@@ -0,0 +1,511 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<chapter id='sdk-working-projects'>
+
+ <title>Using the SDK Toolchain Directly</title>
+
+ <para>
+ You can use the SDK toolchain directly with Makefile and
+ Autotools-based projects.
+ </para>
+
+ <section id='autotools-based-projects'>
+ <title>Autotools-Based Projects</title>
+
+ <para>
+ Once you have a suitable
+ <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchain</ulink>
+ installed, it is very easy to develop a project using the
+ <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>GNU Autotools-based</ulink>
+ workflow, which is outside of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
+ </para>
+
+ <para>
+ The following figure presents a simple Autotools workflow.
+ <imagedata fileref="figures/sdk-autotools-flow.png" width="7in" height="8in" align="center" />
+ </para>
+
+ <para>
+ 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
+ <ulink url='https://developer.gnome.org/anjuta-build-tutorial/stable/create-autotools.html.en'>GNOME Developer</ulink>
+ site.
+ </note>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Create a Working Directory and Populate It:</emphasis>
+ Create a clean directory for your project and then make
+ that directory your working location.
+ <literallayout class='monospaced'>
+ $ mkdir $HOME/helloworld
+ $ cd $HOME/helloworld
+ </literallayout>
+ 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:
+ <filename>hello.c</filename>,
+ <filename>configure.ac</filename>,
+ <filename>Makefile.am</filename>, and
+ <filename>README</filename>, respectively.</para>
+
+ <para> Use the following command to create an empty README
+ file, which is required by GNU Coding Standards:
+ <literallayout class='monospaced'>
+ $ touch README
+ </literallayout>
+ Create the remaining three files as follows:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>hello.c</filename>:</emphasis>
+ <literallayout class='monospaced'>
+ #include <stdio.h>
+
+ main()
+ {
+ printf("Hello World!\n");
+ }
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>configure.ac</filename>:</emphasis>
+ <literallayout class='monospaced'>
+ AC_INIT(hello,0.1)
+ AM_INIT_AUTOMAKE([foreign])
+ AC_PROG_CC
+ AC_CONFIG_FILES(Makefile)
+ AC_OUTPUT
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>Makefile.am</filename>:</emphasis>
+ <literallayout class='monospaced'>
+ bin_PROGRAMS = hello
+ hello_SOURCES = hello.c
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Source the Cross-Toolchain
+ Environment Setup File:</emphasis>
+ 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:
+ <literallayout class='monospaced'>
+ $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create the <filename>configure</filename> Script:</emphasis>
+ Use the <filename>autoreconf</filename> command to
+ generate the <filename>configure</filename> script.
+ <literallayout class='monospaced'>
+ $ autoreconf
+ </literallayout>
+ The <filename>autoreconf</filename> tool takes care
+ of running the other Autotools such as
+ <filename>aclocal</filename>,
+ <filename>autoconf</filename>, and
+ <filename>automake</filename>.
+ <note>
+ If you get errors from
+ <filename>configure.ac</filename>, which
+ <filename>autoreconf</filename> runs, that indicate
+ missing files, you can use the "-i" option, which
+ ensures missing auxiliary files are copied to the build
+ host.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Cross-Compile the Project:</emphasis>
+ This command compiles the project using the
+ cross-compiler.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
+ environment variable provides the minimal arguments for
+ GNU configure:
+ <literallayout class='monospaced'>
+ $ ./configure ${CONFIGURE_FLAGS}
+ </literallayout>
+ For an Autotools-based project, you can use the
+ cross-toolchain by just passing the appropriate host
+ option to <filename>configure.sh</filename>.
+ 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
+ <filename>armv5te-poky-linux-gnueabi</filename>.
+ You will notice that the name of the script is
+ <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
+ Thus, the following command works to update your project
+ and rebuild it using the appropriate cross-toolchain tools:
+ <literallayout class='monospaced'>
+ $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make and Install the Project:</emphasis>
+ These two commands generate and install the project
+ into the destination directory:
+ <literallayout class='monospaced'>
+ $ make
+ $ make install DESTDIR=./tmp
+ </literallayout>
+ <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
+ "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
+ section.
+ </note>
+ 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.
+ <literallayout class='monospaced'>
+ $ file ./tmp/usr/local/bin/hello
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Execute Your Project:</emphasis>
+ 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:
+ <literallayout class='monospaced'>
+ $ ./tmp/usr/local/bin/hello
+ </literallayout>
+ As expected, the project displays the "Hello World!"
+ message.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='makefile-based-projects'>
+ <title>Makefile-Based Projects</title>
+
+ <para>
+ 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
+ <filename>make</filename> rules.
+ </para>
+
+ <para>
+ 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.
+ <imagedata fileref="figures/sdk-makefile-flow.png" width="6in" height="7in" align="center" />
+ </para>
+
+ <para>
+ The main point of this section is to explain the following three
+ cases regarding variable behavior:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Case 1 - No Variables Set in the
+ <filename>Makefile</filename> Map to Equivalent
+ Environment Variables Set in the SDK Setup Script:</emphasis>
+ Because matching variables are not specifically set in the
+ <filename>Makefile</filename>, the variables retain their
+ values based on the environment setup script.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Case 2 - Variables Are Set in the Makefile that
+ Map to Equivalent Environment Variables from the SDK
+ Setup Script:</emphasis>
+ Specifically setting matching variables in the
+ <filename>Makefile</filename> during the build results in
+ the environment settings of the variables being
+ overwritten.
+ In this case, the variables you set in the
+ <filename>Makefile</filename> are used.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Case 3 - Variables Are Set Using the Command Line
+ that Map to Equivalent Environment Variables from the
+ SDK Setup Script:</emphasis>
+ Executing the <filename>Makefile</filename> from the
+ command line results in the environment variables being
+ overwritten.
+ In this case, the command-line content is used.
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ Regardless of how you set your variables, if you use
+ the "-e" option with <filename>make</filename>, the
+ variables from the SDK setup script take precedence:
+ <literallayout class='monospaced'>
+ $ make -e <replaceable>target</replaceable>
+ </literallayout>
+ </note>
+ </para>
+
+ <para>
+ The remainder of this section presents a simple Makefile example
+ that demonstrates these variable behaviors.
+ </para>
+
+ <para>
+ 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.
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>).
+ <literallayout class='monospaced'>
+ $ echo ${CC}
+
+ $
+ </literallayout>
+ Running the SDK setup script for a 64-bit build host and an
+ i586-tuned target architecture for a
+ <filename>core-image-sato</filename> image using the current
+ &DISTRO; Yocto Project release and then echoing that variable
+ shows the value established through the script:
+ <literallayout class='monospaced'>
+ $ 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
+ </literallayout>
+ </para>
+
+ <para>
+ To illustrate variable use, work through this simple "Hello World!"
+ example:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Create a Working Directory and Populate It:</emphasis>
+ Create a clean directory for your project and then make
+ that directory your working location.
+ <literallayout class='monospaced'>
+ $ mkdir $HOME/helloworld
+ $ cd $HOME/helloworld
+ </literallayout>
+ After setting up the directory, populate it with files
+ needed for the flow.
+ You need a <filename>main.c</filename> file from which you
+ call your function, a <filename>module.h</filename> file
+ to contain headers, and a <filename>module.c</filename>
+ that defines your function.
+ </para>
+
+ <para>Create the three files as follows:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>main.c</filename>:</emphasis>
+ <literallayout class='monospaced'>
+ #include "module.h"
+ void sample_func();
+ int main()
+ {
+ sample_func();
+ return 0;
+ }
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>module.h</filename>:</emphasis>
+ <literallayout class='monospaced'>
+ #include <stdio.h>
+ void sample_func();
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>module.c</filename>:</emphasis>
+ <literallayout class='monospaced'>
+ #include "module.h"
+ void sample_func()
+ {
+ printf("Hello World!");
+ printf("\n");
+ }
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Source the Cross-Toolchain Environment Setup File:</emphasis>
+ 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:
+ <literallayout class='monospaced'>
+ $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create the <filename>Makefile</filename>:</emphasis>
+ For this example, the Makefile contains two lines that
+ can be used to set the <filename>CC</filename> variable.
+ One line is identical to the value that is set when you
+ run the SDK environment setup script, and the other line
+ sets <filename>CC</filename> to "gcc", the default GNU
+ compiler on the build host:
+ <literallayout class='monospaced'>
+ # 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
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make the Project:</emphasis>
+ Use the <filename>make</filename> command to create the
+ binary output file.
+ Because variables are commented out in the Makefile,
+ the value used for <filename>CC</filename> is the value
+ set when the SDK environment setup file was run:
+ <literallayout class='monospaced'>
+ $ 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
+ </literallayout>
+ From the results of the previous command, you can see that
+ the compiler used was the compiler established through
+ the <filename>CC</filename> variable defined in the
+ setup script.</para>
+
+ <para>You can override the <filename>CC</filename>
+ environment variable with the same variable as set from
+ the Makefile by uncommenting the line in the Makefile
+ and running <filename>make</filename> again.
+ <literallayout class='monospaced'>
+ $ 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
+ </literallayout>
+ As shown in the previous example, the cross-toolchain
+ compiler is not used.
+ Rather, the default compiler is used.</para>
+
+ <para>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 <filename>make</filename> uses
+ the established SDK compiler.
+ However, when you run <filename>make</filename>, use a
+ command-line argument to set <filename>CC</filename>
+ to "gcc":
+ <literallayout class='monospaced'>
+ $ 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
+ </literallayout>
+ In the previous case, the command-line argument overrides
+ the SDK environment variable.</para>
+
+ <para>In this last case, edit Makefile again to use the
+ "gcc" compiler but then use the "-e" option on the
+ <filename>make</filename> command line:
+ <literallayout class='monospaced'>
+ $ 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
+ </literallayout>
+ In the previous case, the "-e" option forces
+ <filename>make</filename> to use the SDK environment
+ variables regardless of the values in the Makefile.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Execute Your Project:</emphasis>
+ To execute the project (i.e.
+ <filename>target_bin</filename>), use the following
+ command:
+ <literallayout class='monospaced'>
+ $ ./target_bin
+ Hello World!
+ </literallayout>
+ <note>
+ If you used the cross-toolchain compiler to build
+ <filename>target_bin</filename> and your build host
+ differs in architecture from that of the target
+ machine, you need to run your project on the target
+ device.
+ </note>
+ As expected, the project displays the "Hello World!"
+ message.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->