diff options
Diffstat (limited to 'poky/documentation/sdk-manual')
19 files changed, 5117 insertions, 9 deletions
diff --git a/poky/documentation/sdk-manual/history.rst b/poky/documentation/sdk-manual/history.rst index 8c10f6d2e..af027c97f 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 90b634529..f6f2b6640 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 000000000..3a6b4c8d8 --- /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 5a33f6385..7743e3c00 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 000000000..08054f8b7 --- /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 a51c22e39..97ab9169e 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 000000000..de7f75e2b --- /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 5ff75ada2..0f92ac9f0 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 000000000..a73a07a7b --- /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 5a346fa6e..82b7bcf3c 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 000000000..f42670ea6 --- /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 000000000..4f8816f95 --- /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 177826edf..d7776b7c4 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 000000000..6344478fb --- /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 000000000..e0c4416a1 --- /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 4b151e45c..09a194cab 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 000000000..28ee50d0b --- /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 5c828fd58..2c20a1ec5 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 000000000..070d903c7 --- /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 +--> |