diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/sdk-manual')
16 files changed, 4880 insertions, 0 deletions
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png Binary files differnew file mode 100644 index 000000000..c09e60e35 --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png Binary files differnew file mode 100644 index 000000000..cd06c0181 --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-eclipse-dev-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-eclipse-dev-flow.png Binary files differnew file mode 100644 index 000000000..9f986e0d4 --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-eclipse-dev-flow.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-environment.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-environment.png Binary files differnew file mode 100644 index 000000000..78b8cad39 --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-environment.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-installed-extensible-sdk-directory.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-installed-extensible-sdk-directory.png Binary files differnew file mode 100644 index 000000000..99e07ce6f --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-installed-extensible-sdk-directory.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-installed-standard-sdk-directory.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-installed-standard-sdk-directory.png Binary files differnew file mode 100644 index 000000000..d4af85020 --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-installed-standard-sdk-directory.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-title.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-title.png Binary files differnew file mode 100644 index 000000000..e9d5b346b --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-title.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml new file mode 100644 index 000000000..79326077f --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml @@ -0,0 +1,388 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<appendix id='sdk-appendix-customizing'> + +<title>Customizing the SDK</title> + +<para> + This appendix presents customizations you can apply to both the standard + and extensible SDK. + Each subsection identifies the type of SDK to which the section applies. +</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 following filters, which the OpenEmbedded build system applies + against <filename>local.conf</filename> and + <filename>auto.conf</filename> if they are present: + <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 build host. + </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. + The default value blacklists + <ulink url='&YOCTO_DOCS_REF_URL;#var-CONF_VERSION'><filename>CONF_VERSION</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink>, + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>. + </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 above two conditions. + 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 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-system-setup'> + <title>Adjusting the Extensible SDK to Suit Your Build System Setup</title> + + <para> + In most cases, the extensible SDK defaults should work. + 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. + The default value of <filename>SDK_INHERIT_BLACKLIST</filename> + is set using the "?=" operator. + Consequently, you will need to either set the complete value + using "=" or append the value using "_append". + </para></listitem> + <listitem><para> + If you have classes or recipes that add additional tasks to + the standard build flow (i.e. that execute as part of building + the recipe as opposed to needing to be called explicitly), then + you need to do one of the following: + <itemizedlist> + <listitem><para> + Ensure the tasks are shared state tasks (i.e. their + output is saved to and can be restored from the shared + state cache), or that the tasks are able to be + produced quickly from a task that is a shared state + task and 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 + <filename>SDK_INHERIT_BLACKLIST</filename> as previously + described. + </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-after-installing-the-extensible-sdk'>Providing Updates After Installing the Extensible SDK</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> + or + <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</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-appearance-of-the-extensible-sdk'> + <title>Changing the Appearance of the Extensible SDK</title> + + <para> + You can change the title shown by the SDK installer by setting the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TITLE'><filename>SDK_TITLE</filename></ulink> + variable. + 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> +</section> + +<section id='sdk-providing-updates-after-installing-the-extensible-sdk'> + <title>Providing Updates After Installing the Extensible SDK</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 to make it possible for those that use + the SDK to update their installations with the + <filename>devtool sdk-update</filename> command: + <orderedlist> + <listitem><para> + Arrange to be created a directory that can be shared over + HTTP or HTTPS. + </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. + </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 SDKs to + simply run <filename>devtool sdk-update</filename> to retrieve the + latest updates. + See the + "<link linkend='sdk-updating-the-extensible-sdk'>Updating the Extensible SDK</link>" + section for further information. + </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 the extensible SDK you are building to be + able to add items to the SDK without needing 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 actually built. + You can ensure these items are built a number of different + ways: 1) Build them explicitly, perhaps using one or more + "meta" recipes that depend on lists of other recipes to keep + things tidy, or 2) 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> + <listitem><para> + Expose the <filename>sstate-cache</filename> directory + produced by the build. + Typically, you expose this directory over HTTP or HTTPS. + </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> either in + your + <ulink url='&YOCTO_DOCS_DEV_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 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 will need to also enable + bringing in the information on a wider range of packages produced by + the system. + This 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. + Also so that the <filename>devtool search</filename> command + is able to return useful results. + </para> + + <para> + To facilitate this wider range of information, you would additionally + 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> +</section> +</appendix> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml new file mode 100644 index 000000000..3d4e364bf --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml @@ -0,0 +1,252 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<appendix id='sdk-appendix-obtain'> + +<title>Obtaining the SDK</title> + +<section id='sdk-locating-pre-built-sdk-installers'> + <title>Locating Pre-Built SDK Installers</title> + + <para> + You can use existing, pre-built toolchains by locating and running + an SDK installer script that ships with the Yocto Project. + Using this method, you select and download an architecture-specific + toolchain installer and then run the script to hand-install the + toolchain. + </para> + + <para> + You can find SDK installers here: + <itemizedlist> + <listitem><para><emphasis>Standard SDK Installers</emphasis> + Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink> + and find the folder that matches your host development system + (i.e. <filename>i686</filename> for 32-bit machines or + <filename>x86_64</filename> for 64-bit machines).</para> + + <para>Go into that folder and download the toolchain installer + whose name includes the appropriate target architecture. + The toolchains provided by the Yocto Project are based off of + the <filename>core-image-sato</filename> image and contain + libraries appropriate for developing against that image. + For example, if your host development system is a 64-bit x86 + system and you are going to use your cross-toolchain for a + 32-bit x86 target, go into the <filename>x86_64</filename> + folder and download the following installer: + <literallayout class='monospaced'> + poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + </literallayout> + </para></listitem> + <listitem><para><emphasis>Extensible SDK Installers</emphasis> + Installers for the extensible SDK are in + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. + </para></listitem> + </itemizedlist> + </para> +</section> + +<section id='sdk-building-an-sdk-installer'> + <title>Building an SDK Installer</title> + + <para> + As an alternative to locating and downloading a toolchain installer, + you can build the toolchain installer assuming you have first sourced + the environment setup script. + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" + section in the Yocto Project Quick Start for steps that show you + how to set up the Yocto Project environment. + In particular, you need to be sure the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable matches the architecture for which you are building and that + the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink> + variable is correctly set if you are building a toolchain designed to + run on an architecture that differs from your current development host + machine (i.e. the build machine). + </para> + + <para> + To build the toolchain installer for a standard SDK and populate + the SDK image, use the following command: + <literallayout class='monospaced'> + $ bitbake <replaceable>image</replaceable> -c populate_sdk + </literallayout> + You can do the same for the extensible SDK using this command: + <literallayout class='monospaced'> + $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext + </literallayout> + These commands result in a toolchain installer that contains the sysroot + that matches your target root filesystem. + </para> + + <para> + When the <filename>bitbake</filename> command completes, the toolchain + installer will be in + <filename>tmp/deploy/sdk</filename> in the Build Directory. + <note> + By default, this toolchain does not build static binaries. + If you want to use the toolchain to build these types of libraries, + you need to be sure your image has the appropriate static + development libraries. + Use the + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink> + variable inside your <filename>local.conf</filename> file to + install the appropriate library packages. + Following is an example using <filename>glibc</filename> static + development libraries: + <literallayout class='monospaced'> + IMAGE_INSTALL_append = " glibc-staticdev" + </literallayout> + </note> + </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. + For example, the Eclipse IDE environment with the Eclipse + Yocto Plug-in installed allows you to use QEMU to boot + under NFS.</para></listitem> + <listitem><para>You want to develop your target application + using the root filesystem as the target sysroot. + </para></listitem> + </itemizedlist> + </para> + + <para> + To extract the root filesystem, first <filename>source</filename> + the cross-development environment setup script to establish + necessary environment variables. + If you built the toolchain in the Build Directory, you will find + the toolchain environment script in the + <filename>tmp</filename> directory. + If you installed the toolchain by hand, the environment setup + script is located in <filename>/opt/poky/&DISTRO;</filename>. + </para> + + <para> + After sourcing the environment script, use the + <filename>runqemu-extract-sdk</filename> command and provide the + filesystem image. + </para> + + <para> + Following is an example. + The second command sets up the environment. + In this case, the setup script is located in the + <filename>/opt/poky/&DISTRO;</filename> directory. + The third command extracts the root filesystem from a previously + built filesystem that is located in the + <filename>~/Downloads</filename> directory. + Furthermore, this command extracts the root filesystem into the + <filename>qemux86-sato</filename> directory: + <literallayout class='monospaced'> + $ cd ~ + $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + $ runqemu-extract-sdk \ + ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \ + $HOME/qemux86-sato + </literallayout> + You could now point to the target sysroot at + <filename>qemux86-sato</filename>. + </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="60" 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;+snapshot</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="60" 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 a log file for the OpenEmbedded build system + preparation script run by the installer. + </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. + <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>). + </para> +</section> + +</appendix> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml new file mode 100644 index 000000000..3e11fc97d --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml @@ -0,0 +1,1304 @@ +<!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; ] > + +<chapter id='sdk-extensible'> + +<title>Using the Extensible SDK</title> + +<para> + This chapter describes the extensible SDK and how to use it. + 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_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. +</para> + +<para> + Information in this chapter covers features that are not part of the + standard SDK. + In other words, the chapter presents information unique to the + extensible SDK only. + For information on how to use the standard SDK, see the + "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>" + chapter. +</para> + +<section id='sdk-setting-up-to-use-the-extensible-sdk'> + <title>Setting Up to Use the Extensible SDK</title> + + <para> + Getting set up to use the extensible SDK is identical to getting set + up to use the standard SDK. + You still need to locate and run the installer and then run the + environment setup script. + See the + "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" + and the + "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>" + sections for general information. + The following items highlight the only differences between getting + set up to use the extensible SDK as compared to the standard SDK: + <itemizedlist> + <listitem><para><emphasis>Default Installation Directory:</emphasis> + By default, the extensible SDK installs into the + <filename>poky_sdk</filename> folder of your home directory. + As with the standard SDK, you can choose to install the + extensible SDK in any location when you run the installer. + However, unlike the standard SDK, the location you choose needs + to be writable for whichever users need to use the SDK, + since files will need to be written under that directory during + the normal course of operation. + </para></listitem> + <listitem><para><emphasis>Build Tools and Build System:</emphasis> + The extensible SDK installer performs additional tasks as + compared to the standard SDK installer. + The extensible SDK installer extracts build tools specific + to the SDK and the installer also prepares the internal build + system within the SDK. + Here is example output for running the extensible SDK + installer: + <literallayout class='monospaced'> + $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.1+snapshot.sh + Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.1+snapshot + =================================================================================== + 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... + 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></listitem> + </itemizedlist> + </para> + + <para> + After installing the SDK, you need to run the SDK environment setup + script. + Here is the output: + <literallayout class='monospaced'> + $ 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> + Once you run the environment setup script, you have + <filename>devtool</filename> available. + </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. + </para> + + <para> + The <filename>devtool</filename> command line is organized similarly + to + <ulink url='&YOCTO_DOCS_DEV_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. + </para> + + <para> + Two <filename>devtool</filename> subcommands that provide + entry-points into development are: + <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> + </itemizedlist> + As with the OpenEmbedded 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, both 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> and + <filename>devtool modify</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_DEV_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 where other developers are responsible for + various areas of source code. + As a developer, you are probably interested in using + that source code as part of your development using + 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 represents a common situation + where the source code does not exist locally + and needs to be extracted. + In this situation, you just let it get + extracted to the default workspace - you do not + want it 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> + creates a recipe and an append file in the + workspace as well as extracts the upstream + source files into a local Git repository also + within the <filename>sources</filename> folder. + </para></listitem> + <listitem><para><emphasis>Middle</emphasis>: + The middle scenario 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. + As always, if required <filename>devtool</filename> creates + a Git repository locally during the extraction. + 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: + <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 both the recipe and an append file + for the recipe. + </para></listitem> + <listitem><para><emphasis>Right</emphasis>: + The right scenario represents a situation + where the source tree (srctree) has been + previously prepared outside of the + <filename>devtool</filename> workspace. + </para> + + <para>The following command names the recipe + and identifies where the existing source tree + is located: + <literallayout class='monospaced'> + $ devtool add <replaceable>recipe srctree</replaceable> + </literallayout> + The command examines the source code and creates + a recipe for it placing the recipe into the + workspace.</para> + + <para>Because the extracted source code already exists, + <filename>devtool</filename> does not try to + relocate it into the workspace - just the new + the recipe is placed in the workspace.</para> + + <para>Aside from a recipe folder, the command + also creates an append folder and places an initial + <filename>*.bbappend</filename> within. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Edit the Recipe</emphasis>: + At this point, 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>: + At this point in the flow, the next step you + take depends on what you are going to do with + the new code.</para> + <para>If you need to take the build output and eventually + move it to the target hardware, you would use + <filename>devtool build</filename>: + <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 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, 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>Optionally Update the Recipe With Patch Files</emphasis>: + Once you are satisfied with the recipe, if you have made + any changes to the source tree that you want to have + applied by the recipe, you need to generate patches + from those changes. + You do this before moving the recipe + to its final layer and cleaning up the workspace area + <filename>devtool</filename> uses. + This optional step is especially relevant if you are + using or adding third-party software.</para> + <para>To convert commits created using Git to patch files, + use the <filename>devtool update-recipe</filename> command. + <note> + Any changes you want to turn into patches must be + committed to the Git repository in the source tree. + </note> + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> + </literallayout> + </para></listitem> + <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>: + Before cleaning up the workspace, you need to move the + final recipe to its permanent layer. + You must do this before using the + <filename>devtool reset</filename> command if you want to + retain the recipe. + </para></listitem> + <listitem><para><emphasis>Reset the Recipe</emphasis>: + As a final step, you can restore the state such that + standard layers and the upstream source is used to build + the recipe rather than data in the workspace. + To reset the recipe, use the <filename>devtool reset</filename> + command: + <literallayout class='monospaced'> + $ devtool reset <replaceable>recipe</replaceable> + </literallayout> + </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 recipe in + place. + The command is flexible enough to allow you to extract code, + 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 + you would use with 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 in some layer external + to the <filename>devtool</filename> workspace. + </para></listitem> + <listitem><para>The source files exist 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 some 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 represents a common situation + where the source code does not exist locally + and needs to be extracted. + In this situation, the source is extracted + into the default 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, + it uses the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable to locate the source code and + any local patch files from other developers are + located. + <note> + You cannot provide an URL for + <replaceable>srctree</replaceable> when using the + <filename>devtool modify</filename> command. + </note> + With this scenario, however, since no + <replaceable>srctree</replaceable> argument exists, the + <filename>devtool modify</filename> command by default + extracts the source files to a Git structure. + Furthermore, the location for the extracted source is the + default area within the workspace. + The result is that the command sets up both the source + code and an append file within the workspace with the + recipe remaining in its original location. + </para></listitem> + <listitem><para><emphasis>Middle</emphasis>: + The middle scenario 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 in its own + layer outside the workspace.</para> + + <para>The following command tells + <filename>devtool</filename> what recipe with + which to work and, in this case, identifies a local + area for the extracted source files that is outside + of the default workspace: + <literallayout class='monospaced'> + $ devtool modify <replaceable>recipe srctree</replaceable> + </literallayout> + As with all extractions, the command uses + the recipe's <filename>SRC_URI</filename> to locate the + source files. + Once the files are located, the command by default + extracts them. + Providing the <replaceable>srctree</replaceable> + argument instructs <filename>devtool</filename> where + place the extracted source.</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 + provided with <replaceable>srctree</replaceable>. + </para></listitem> + <listitem><para><emphasis>Right</emphasis>: + The right scenario represents a situation + where the source tree + (<replaceable>srctree</replaceable>) exists as a + previously extracted Git structure outside of + the <filename>devtool</filename> workspace. + In this example, the recipe also exists + elsewhere 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>Once the command finishes, it creates only + an append file for the recipe in the 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</emphasis>: + Once you have updated the source files, you can build + the recipe. + </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, 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>Optionally Create Patch Files for Your Changes</emphasis>: + After you have debugged your changes, you can + use <filename>devtool update-recipe</filename> to + generate patch files for all the commits you have + made. + <note> + Patch files are generated only for changes + you have committed. + </note> + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> + </literallayout> + By default, the + <filename>devtool update-recipe</filename> command + creates the patch files in a folder named the same + as the recipe beneath the folder in which the recipe + resides, and updates the recipe's + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement to point to the generated patch files. + <note> + You can use the + "--append <replaceable>LAYERDIR</replaceable>" + option to cause the command to create append files + in a specific layer rather than the default + recipe layer. + </note> + </para></listitem> + <listitem><para><emphasis>Restore the Workspace</emphasis>: + The <filename>devtool reset</filename> restores the + state so that standard layers and upstream sources are + used to build the recipe rather than what is in the + workspace. + <literallayout class='monospaced'> + $ devtool reset <replaceable>recipe</replaceable> + </literallayout> + </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 with which you provide it. + 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 through + <filename>npm</filename> + </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 you can build the recipe. + Once the recipe can be built, 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> attempts to determine + the name and version of the software being built from + various metadata within the source tree. + Furthermore, the command sets the name of the created recipe + file accordingly. + If the name or version cannot be determined, the + <filename>devtool add</filename> command prints an error and + you must re-run the command with both the name and version + or just the name or version specified. + </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 in the + <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> + value within the recipe. + If a dependency cannot be mapped, then a comment is placed in + the recipe indicating such. + The inability to map a dependency might be caused because the + naming is not 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 to satisfy the dependency and then come + back to the first recipe and add its name to + <filename>DEPENDS</filename>. + </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} += "dependency1 dependency2 ..." + </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 for an option to disable 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 and sets the + <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> + value accordingly. + You should double-check this value against the documentation + or source files for the software you are building and update + that <filename>LICENSE</filename> value if necessary. + </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. + However, license statements often appear in comments at the top + of source files or within documentation. + 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, the + <filename>LICENSE</filename> value is set to "CLOSED" and the + <filename>LIC_FILES_CHKSUM</filename> vaule remains unset. + This behavior allows you to continue with development but is + unlikely to be correct in all cases. + Consequently, 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 <filename>make</filename> 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 + <filename>CC</filename> 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 some 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 <filename>make</filename> 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 you will see a list of + environment variables 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. + In this situation, 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> + within the recipe as follows: + <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 by virtue of + being 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. + </para></listitem> + <listitem><para> + Sometimes a Makefile runs target-specific commands such + as <filename>ldconfig</filename>. + For such cases, you might be able to simply 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 + build host system as opposed to the target. + You should indicate this 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 in the + following form to add Node.js modules: + <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 in order to provide Node.js + itself. + </para></listitem> + </itemizedlist> + </note> + </para> + </section> +</section> + +<section id='sdk-working-with-recipes'> + <title>Working With Recipes</title> + + <para> + When building a recipe with <filename>devtool build</filename> the + typical build progression is 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> + Compiling 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, usually with a + "do_" prefix. + 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, leaving the recipe + to describe just the things that are specific to the software to be + built. + A <ulink url='ref-classes-base'><filename>base</filename></ulink> + class exists that is implicitly inherited by all recipes and provides + the functionality that most typical recipes 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> + When you are debugging a recipe that you previously created using + <filename>devtool add</filename> or whose source you are modifying + by using the <filename>devtool modify</filename> command, after + the first run of <filename>devtool build</filename>, you will + find some symbolic links created within the source tree: + <filename>oe-logs</filename>, which points to the directory in + which log files and run scripts for each build step are created + and <filename>oe-workdir</filename>, which points to the temporary + work area for the recipe. + You can use these links to get more information on what is + happening at each build step. + </para> + + <para> + These locations under <filename>oe-workdir</filename> are + particularly useful: + <itemizedlist> + <listitem><para><filename>image/</filename>: + Contains all of the files installed at 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> + </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> + set within the recipe. + If you wish to pass additional options, add them to + <filename>EXTRA_OECONF</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> 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>. + 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 build host. + 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 go 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 several other packages. + This separation is done because not all of those installed files + are always 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 that has optional modules or + plugins might do 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, + 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 is named the + same 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> 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 at once thus restoring the target device back 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> command do not + currently interact with any package management system on the + target device (e.g. RPM or OPKG). + Consequently, you should not intermingle operations + <filename>devtool deploy-target</filename> and the 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> + The extensible SDK typically only comes with a small number of tools + and libraries out of the box. + If you have a minimal SDK, then it starts mostly empty and is + populated on-demand. + However, sometimes you will need to 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 it. + 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> 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 it using the <filename>devtool add</filename> command. + </para> +</section> + +<section id='sdk-updating-the-extensible-sdk'> + <title>Updating the Extensible SDK</title> + + <para> + If you are working with an extensible SDK that gets occasionally + updated (e.g. typically when that SDK has been provided to you by + another party), then you will need to manually pull down those + updates to your installed SDK. + </para> + + <para> + To update your installed SDK, run the following: + <literallayout class='monospaced'> + $ devtool sdk-update + </literallayout> + The previous command assumes your SDK provider has set the default + update URL for you. + If that URL has not been set, you need to specify it yourself 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 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 for sending to a third party (e.g., if you are a vendor with + customers needing to build their own software for the target platform). + If that is the case, then you can produce a derivative SDK based on + the currently installed SDK fairly easily. + Use 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 above procedure takes the recipes added to the workspace and + constructs a new SDK installer containing those recipes and the + resulting binary artifacts. + The recipes go into their own separate layer in the constructed + derivative SDK, leaving the workspace clean and ready for users + to add their own recipes. + </para> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml new file mode 100644 index 000000000..88ae77831 --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml @@ -0,0 +1,338 @@ +<!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; ] > + +<chapter id='sdk-intro'> +<title>Introduction</title> + +<section id='sdk-manual-intro'> + <title>Introduction</title> + + <para> + Welcome to the Yocto Project Software Development Kit (SDK) + Developer's Guide. + This manual provides information that lets you use both the standard + Yocto Project SDK and an extensible SDK to develop applications and + images using the Yocto Project. + Additionally, the manual also provides information on how to use + the popular <trademark class='trade'>Eclipse</trademark> IDE as part + of your application development workflow. + </para> + + <para> + 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 more traditional SDK and extensible + SDK. + </para> + + <para> + A standard SDK consists of a cross-development toolchain that contains + a compiler, debugger, and various miscellaneous tools; libraries, + headers, and symbols to match an image; and environment setup script. + You can use this SDK to independently develop and test code that is + destined to run on some target machine. + </para> + + <para> + An extensible SDK consists of everything that the standard SDK has plus + 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_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. + </para> + + <para> + 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-canadian + toolchain binaries are produced per 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 a sysroot is still needed for every target + since those binaries are target-specific. + </para> + + <para> + Going beyond the actual SDK, the SDK development environment consists + of the following: + <itemizedlist> + <listitem><para>An architecture-specific cross-toolchain and + matching sysroots (target and native) all built by the + OpenEmbedded build system. + The toolchain and sysroots are based on a + <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> + configuration and extensions, + which allows you to cross-develop on the host machine for the + target hardware. + </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 and SDK. + </para></listitem> + <listitem><para>The Eclipse IDE Yocto Plug-in. + This plug-in is also available for you if you are an Eclipse + user. + In the same manner as QEMU, the plug-in is not literally part + of the SDK but is rather available for use as part of the + development process. + </para></listitem> + <listitem><para>Various user-space tools that greatly enhance + your application development experience. + These tools are also separate from the actual SDK but can be + independently obtained and used in the development process. + </para></listitem> + </itemizedlist> + </para> + + <section id='the-cross-development-toolchain'> + <title>The Cross-Development Toolchain</title> + + <para> + The + <ulink url='&YOCTO_DOCS_DEV_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. + This toolchain is created by running a toolchain installer script + or through a + <ulink url='&YOCTO_DOCS_DEV_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 ways: + <itemizedlist> + <listitem><para> + If you have cloned the <filename>poky</filename> Git + repository to create a + <ulink url='&YOCTO_DOCS_DEV_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 + <ulink url='&YOCTO_DOCS_DEV_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 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 id='eclipse-overview'> + <title>Eclipse Yocto Plug-in</title> + + <para> + The Eclipse IDE is a popular development environment and it fully + supports development using the Yocto Project. + When you install and configure the Eclipse Yocto Project Plug-in + into the Eclipse IDE, you maximize your Yocto Project experience. + Installing and configuring the Plug-in results in an environment + that has extensions specifically designed to let you more easily + develop software. + These extensions allow for cross-compilation, deployment, and + execution of your output into a QEMU emulation session. + You can also perform cross-debugging and profiling. + The environment also supports a suite of tools that allows you to + perform remote profiling, tracing, collection of power data, + collection of latency data, and collection of performance data. + </para> + + <para> + For information about the application development workflow that + uses the Eclipse IDE and for a detailed example of how to install + and configure the Eclipse Yocto Project Plug-in, see the + "<link link='sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>" + section. + </para> + </section> + + <section id='user-space-tools'> + <title>User-Space Tools</title> + + <para> + User-space tools are available as part of the SDK development + process and can be helpful. + The tools include LatencyTOP, PowerTOP, Perf, SystemTap, + and Lttng-ust. + These tools are common development tools for the Linux platform. + <itemizedlist> + <listitem><para><emphasis>LatencyTOP:</emphasis> LatencyTOP + focuses on latency that causes skips in audio, stutters in + your desktop experience, or situations that overload your + server even when you have plenty of CPU power left. + </para></listitem> + <listitem><para><emphasis>PowerTOP:</emphasis> Helps you + determine what software is using the most power. + You can find out more about PowerTOP at + <ulink url='https://01.org/powertop/'></ulink>.</para></listitem> + <listitem><para><emphasis>Perf:</emphasis> Performance counters + for Linux used to keep track of certain types of hardware + and software events. + For more information on these types of counters see + <ulink url='https://perf.wiki.kernel.org/'></ulink>. + For examples on how to setup and use this tool, see the + "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>" + section in the Yocto Project Profiling and Tracing Manual. + </para></listitem> + <listitem><para><emphasis>SystemTap:</emphasis> A free software + infrastructure that simplifies information gathering about + a running Linux system. + This information helps you diagnose performance or + functional problems. + SystemTap is not available as a user-space tool through + the Eclipse IDE Yocto Plug-in. + See <ulink url='http://sourceware.org/systemtap'></ulink> + for more information on SystemTap. + For examples on how to setup and use this tool, see the + "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-systemtap'>SystemTap</ulink>" + section in the Yocto Project Profiling and Tracing Manual. + </para></listitem> + <listitem><para><emphasis>Lttng-ust:</emphasis> A User-space + Tracer designed to provide detailed information on + user-space activity. + See <ulink url='http://lttng.org/ust'></ulink> for more + information on Lttng-ust. + </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 + 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 url='sdk-installing-the-sdk'>Installing the SDK</link>" + section.</para></listitem> + <listitem><para><emphasis>Download 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 kernel, root filesystem, and any other files you + need for your process. + <note>In order to use the root filesystem in QEMU, you + need to extract it. + See the + "<link url='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. + You can see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" + chapter in the Yocto Project Development Manual + for information on using QEMU within the Yocto + Project.</para></listitem> + </orderedlist> + </para> + + <para> + The remainder of this manual describes how to use both the standard + SDK and the extensible SDK. + 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/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl new file mode 100644 index 000000000..dae992c07 --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl @@ -0,0 +1,27 @@ +<?xml version='1.0'?> +<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/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl new file mode 100644 index 000000000..03555d6ca --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl @@ -0,0 +1,37 @@ +<?xml version='1.0'?> +<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/eclipse/eclipse3.xsl" /> +--> + + <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" /> + +<!-- + + <xsl:import + href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" /> + +--> + + <xsl:param name="chunker.output.indent" select="'yes'"/> + <xsl:param name="chunk.quietly" select="1"/> + <xsl:param name="chunk.first.sections" select="1"/> + <xsl:param name="chunk.section.depth" select="10"/> + <xsl:param name="use.id.as.filename" select="1"/> + <xsl:param name="ulink.target" select="'_self'" /> + <xsl:param name="base.dir" select="'html/adt-manual/'"/> + <xsl:param name="html.stylesheet" select="'../book.css'"/> + <xsl:param name="eclipse.manifest" select="0"/> + <xsl:param name="create.plugin.xml" select="0"/> + <xsl:param name="suppress.navigation" select="1"/> + <xsl:param name="generate.index" select="0"/> + <xsl:param name="chapter.autolabel" select="1" /> + <xsl:param name="appendix.autolabel" select="1" /> + <xsl:param name="section.autolabel" select="1" /> + <xsl:param name="section.label.includes.component.label" select="1" /> +</xsl:stylesheet> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml new file mode 100644 index 000000000..c860782fb --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml @@ -0,0 +1,80 @@ +<!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; ] > + +<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 Software Development Kit (SDK) Developer's Guide + </title> + + <authorgroup> + <author> + <firstname>Scott</firstname> <surname>Rifenbark</surname> + <affiliation> + <orgname>Scotty's Documentation Services, LLC</orgname> + </affiliation> + <email>srifenbark@gmail.com</email> + </author> + </authorgroup> + + <revhistory> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.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> + For the latest version of this manual associated with this + Yocto Project release, see the + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink> + from the Yocto Project website. + </note> + + </legalnotice> + + </bookinfo> + + <xi:include href="sdk-intro.xml"/> + + <xi:include href="sdk-using.xml"/> + + <xi:include href="sdk-extensible.xml"/> + + <xi:include href="sdk-appendix-obtain.xml"/> + + <xi:include href="sdk-appendix-customizing.xml"/> + +<!-- <index id='index'> + <title>Index</title> + </index> +--> + +</book> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-style.css b/import-layers/yocto-poky/documentation/sdk-manual/sdk-style.css new file mode 100644 index 000000000..52518964c --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-style.css @@ -0,0 +1,988 @@ +/* + 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/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml new file mode 100644 index 000000000..1ea47d3bb --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml @@ -0,0 +1,1466 @@ +<!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; ] > + +<chapter id='sdk-using-the-standard-sdk'> + +<title>Using the Standard SDK</title> + +<para> + This chapter describes the standard SDK and how to use it. + Information covers the pieces of the SDK, how to install it, and presents + several task-based procedures common for developing with a standard SDK. + <note> + The tasks you can perform using a standard SDK are also applicable + when you are using an extensible SDK. + For information on the differences when using an extensible SDK as + compared to an extensible SDK, see the + "<link linkend='sdk-extensible'>Using the Extensible SDK</link>" + chapter. + </note> +</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. + </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 host + development machine 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 directory under + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. + Toolchains are available for 32-bit and 64-bit x86 development + systems from the <filename>i686</filename> and + <filename>x86_64</filename> directories, respectively. + The toolchains the Yocto Project provides are based off the + <filename>core-image-sato</filename> image and contain + libraries appropriate for developing against that image. + Each type of development system supports five or more target + architectures. + </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. + + <replaceable>arch</replaceable> is a string representing the tuned target architecture: + + i586, x86_64, powerpc, mips, armv7a or armv5te + + <replaceable>release_version</replaceable> is a string representing the release number of the + Yocto Project: + + &DISTRO;, &DISTRO;+snapshot + </literallayout> + For example, the following toolchain 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> + </para> + + <para> + The SDK and toolchains are self-contained and by default are installed + into <filename>/opt/poky</filename>. + However, when you run the SDK installer, you can choose an + installation directory. + <note> + You must change the permissions on the toolchain + installer script so that it is executable: + <literallayout class='monospaced'> + $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh + </literallayout> + </note> + </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 32-bit x86 target architecture. + The example assumes the toolchain installer is located in + <filename>~/Downloads/</filename>. + <note> + If you do not have write permissions for the directory + into which you are installing the SDK, the installer + notifies you and exits. + Be sure you have write permissions in the directory and + run the installer again. + </note> + <literallayout class='monospaced'> + $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh + Poky (Yocto Project Reference Distro) SDK installer version 2.0 + =============================================================== + Enter target directory for SDK (default: /opt/poky/2.1): + You are about to install the SDK to "/opt/poky/2.1". 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/2.1/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 it. + This setup script resides in the directory you chose when you installed + the SDK. + For information on where this setup script can reside, see the + "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>" + Appendix. + </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. + For example, the command to source a setup script for an IA-based + target machine using i586 tuning and located in the default SDK + installation directory is as follows: + <literallayout class='monospaced'> + $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + </literallayout> + When you run the setup script, many environment variables are + defined: + <literallayout class='monospaced'> + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation + <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files + <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler + <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler + <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor + <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler + <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker + <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger + <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols + <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib' + <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy' + <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump' + <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar' + <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm' + <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools + <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools + <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure + <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags + <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags + <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link + <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags + </literallayout> + </para> +</section> + +<section id='autotools-based-projects'> + <title>Autotools-Based Projects</title> + + <para> + Once you have a suitable cross-toolchain installed, it is very easy to + develop a project outside of the OpenEmbedded build system. + This section presents a simple "Helloworld" example that shows how + to set up, compile, and run the project. + </para> + + <section id='creating-and-running-a-project-based-on-gnu-autotools'> + <title>Creating and Running a Project Based on GNU Autotools</title> + + <para> + Follow these steps to create a simple Autotools-based project: + <orderedlist> + <listitem><para><emphasis>Create your directory:</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></para></listitem> + <listitem><para><emphasis>Populate the directory:</emphasis> + Create <filename>hello.c</filename>, <filename>Makefile.am</filename>, + and <filename>configure.in</filename> files as follows: + <itemizedlist> + <listitem><para>For <filename>hello.c</filename>, include + these lines: + <literallayout class='monospaced'> + #include <stdio.h> + + main() + { + printf("Hello World!\n"); + } + </literallayout></para></listitem> + <listitem><para>For <filename>Makefile.am</filename>, + include these lines: + <literallayout class='monospaced'> + bin_PROGRAMS = hello + hello_SOURCES = hello.c + </literallayout></para></listitem> + <listitem><para>For <filename>configure.in</filename>, + include these lines: + <literallayout class='monospaced'> + AC_INIT(hello.c) + AM_INIT_AUTOMAKE(hello,0.1) + AC_PROG_CC + AC_PROG_INSTALL + AC_OUTPUT(Makefile) + </literallayout></para></listitem> + </itemizedlist></para></listitem> + <listitem><para><emphasis>Source the cross-toolchain + environment setup file:</emphasis> + Installation of 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". + Here is an example that 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>Generate the local aclocal.m4 + files and create the configure script:</emphasis> + The following GNU Autotools generate the local + <filename>aclocal.m4</filename> files and create the + configure script: + <literallayout class='monospaced'> + $ aclocal + $ autoconf + </literallayout></para></listitem> + <listitem><para><emphasis>Generate files needed by GNU + coding standards:</emphasis> + GNU coding standards require certain files in order for the + project to be compliant. + This command creates those files: + <literallayout class='monospaced'> + $ touch NEWS README AUTHORS ChangeLog + </literallayout></para></listitem> + <listitem><para><emphasis>Generate the configure + file:</emphasis> + This command generates the <filename>configure</filename>: + <literallayout class='monospaced'> + $ automake -a + </literallayout></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></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></para></listitem> + <listitem><para><emphasis>Verify the installation:</emphasis> + This 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 in the shell, simply enter the name. + You could also copy the binary to the actual target hardware + and run the project there as well: + <literallayout class='monospaced'> + $ ./hello + </literallayout> + As expected, the project displays the "Hello World!" message. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='passing-host-options'> + <title>Passing Host Options</title> + + <para> + 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> + <note> + If the <filename>configure</filename> script results in problems recognizing the + <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option, + regenerate the script to enable the support by doing the following and then + run the script again: + <literallayout class='monospaced'> + $ libtoolize --automake + $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \ + [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>] + $ autoconf + $ autoheader + $ automake -a + </literallayout> + </note> + </para> + </section> +</section> + +<section id='makefile-based-projects'> + <title>Makefile-Based Projects</title> + + <para> + For Makefile-based projects, the cross-toolchain environment variables + established by running the cross-toolchain environment setup script + are subject to general <filename>make</filename> rules. + </para> + + <para> + To illustrate this, consider the following four cross-toolchain + environment variables: + <literallayout class='monospaced'> + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux + <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux + <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types + <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types + </literallayout> + Now, consider the following three cases: + <itemizedlist> + <listitem><para><emphasis>Case 1 - No Variables Set in the <filename>Makefile</filename>:</emphasis> + Because these variables are not specifically set in the + <filename>Makefile</filename>, the variables retain their + values based on the environment. + </para></listitem> + <listitem><para><emphasis>Case 2 - Variables Set in the <filename>Makefile</filename>:</emphasis> + Specifically setting variables in the + <filename>Makefile</filename> during the build results in the + environment settings of the variables being overwritten. + </para></listitem> + <listitem><para><emphasis>Case 3 - Variables Set when the <filename>Makefile</filename> is Executed from the Command Line:</emphasis> + Executing the <filename>Makefile</filename> from the command + line results in the variables being overwritten with + command-line content regardless of what is being set in the + <filename>Makefile</filename>. + In this case, environment variables are not considered unless + you use the "-e" flag during the build: + <literallayout class='monospaced'> + $ make -e <replaceable>file</replaceable> + </literallayout> + If you use this flag, then the environment values of the + variables override any variables specifically set in the + <filename>Makefile</filename>. + </para></listitem> + </itemizedlist> + <note> + For the list of variables set up by the cross-toolchain environment + setup script, see the + "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>" + section. + </note> + </para> +</section> + +<section id='sdk-developing-applications-using-eclipse'> + <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title> + + <para> + If you are familiar with the popular Eclipse IDE, you can use an + Eclipse Yocto Plug-in to allow you to develop, deploy, and test your + application all from within Eclipse. + This section describes general workflow using the SDK and Eclipse + and how to configure and set up Eclipse. + </para> + + <section id='workflow-using-eclipse'> + + <title>Workflow Using <trademark class='trade'>Eclipse</trademark></title> + + <para> + The following figure and supporting list summarize the application + development general workflow that employs both the SDK Eclipse. + </para> + + <para> + <imagedata fileref="figures/sdk-eclipse-dev-flow.png" + width="7in" depth="7in" align="center" scale="100" /> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>: + See + "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" + and + "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both + in the Yocto Project Reference Manual for requirements. + In particular, be sure your host system has the + <filename>xterm</filename> package installed. + </para></listitem> + <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>: + You must have a target kernel image that has been built using the OpenEmbedded + build system.</para> + <para>Depending on whether the Yocto Project has a pre-built image that matches your target + architecture and where you are going to run the image while you develop your application + (QEMU or real hardware), the area from which you get the image differs. + <itemizedlist> + <listitem><para>Download the image from + <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> + if your target architecture is supported and you are going to develop + and test your application on actual hardware.</para></listitem> + <listitem><para>Download the image from + <ulink url='&YOCTO_QEMU_DL_URL;'> + <filename>machines/qemu</filename></ulink> if your target architecture is supported + and you are going to develop and test your application using the QEMU + emulator.</para></listitem> + <listitem><para>Build your image if you cannot find a pre-built image that matches + your target architecture. + If your target architecture is similar to a supported architecture, you can + modify the kernel image before you build it. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>" + section in the Yocto Project Development + manual for an example.</para></listitem> + </itemizedlist></para> + <para>For information on pre-built kernel image naming schemes for images + that can run on the QEMU emulator, see the + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. + </para></listitem> + <listitem><para><emphasis>Install the SDK</emphasis>: + The SDK provides a target-specific cross-development toolchain, the root filesystem, + the QEMU emulator, and other tools that can help you develop your application. + 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>Secure the target root filesystem + and the Cross-development toolchain</emphasis>: + You need to find and download the appropriate root filesystem and + the cross-development toolchain.</para> + <para>You can find the tarballs for the root filesystem in the same area used + for the kernel image. + Depending on the type of image you are running, the root filesystem you need differs. + For example, if you are developing an application that runs on an image that + supports Sato, you need to get a root filesystem that supports Sato.</para> + <para>You can find the cross-development toolchains at + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>. + Be sure to get the correct toolchain for your development host and your + target architecture. + See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>" + section for information and the + "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" + section for installation information. + </para></listitem> + <listitem><para><emphasis>Create and build your application</emphasis>: + At this point, you need to have source files for your application. + Once you have the files, you can use the Eclipse IDE to import them and build the + project. + If you are not using Eclipse, you need to use the cross-development tools you have + installed to create the image.</para></listitem> + <listitem><para><emphasis>Deploy the image with the application</emphasis>: + If you are using the Eclipse IDE, you can deploy your image to the hardware or to + QEMU through the project's preferences. + If you are not using the Eclipse IDE, then you need to deploy the application + to the hardware using other methods. + Or, if you are using QEMU, you need to use that tool and + load your image in for testing. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" + chapter in the Yocto Project Development Manual + for information on using QEMU. + </para></listitem> + <listitem><para><emphasis>Test and debug the application</emphasis>: + Once your application is deployed, you need to test it. + Within the Eclipse IDE, you can use the debugging environment along with the + set of installed user-space tools to debug your application. + Of course, the same user-space tools are available separately if you choose + not to use the Eclipse IDE.</para></listitem> + </orderedlist> + </para> + </section> + + <section id='adt-eclipse'> + <title>Working Within Eclipse</title> + + <para> + The Eclipse IDE is a popular development environment and it fully + supports development using the Yocto Project. + <note> + This release of the Yocto Project supports both the Luna + and Kepler versions of the Eclipse IDE. + Thus, the following information provides setup information for + both versions. + </note> + </para> + + <para> + When you install and configure the Eclipse Yocto Project Plug-in + into the Eclipse IDE, you maximize your Yocto Project experience. + Installing and configuring the Plug-in results in an environment + that has extensions specifically designed to let you more easily + develop software. + These extensions allow for cross-compilation, deployment, and + execution of your output into a QEMU emulation session as well as + actual target hardware. + You can also perform cross-debugging and profiling. + The environment also supports a suite of tools that allows you + to perform remote profiling, tracing, collection of power data, + collection of latency data, and collection of performance data. + </para> + + <para> + This section describes how to install and configure the Eclipse IDE + Yocto Plug-in and how to use it to develop your application. + </para> + + <section id='setting-up-the-eclipse-ide'> + <title>Setting Up the Eclipse IDE</title> + + <para> + To develop within the Eclipse IDE, you need to do the following: + <orderedlist> + <listitem><para>Install the optimal version of the Eclipse + IDE.</para></listitem> + <listitem><para>Configure the Eclipse IDE. + </para></listitem> + <listitem><para>Install the Eclipse Yocto Plug-in. + </para></listitem> + <listitem><para>Configure the Eclipse Yocto Plug-in. + </para></listitem> + </orderedlist> + <note> + Do not install Eclipse from your distribution's package + repository. + Be sure to install Eclipse from the official Eclipse + download site as directed in the next section. + </note> + </para> + + <section id='installing-eclipse-ide'> + <title>Installing the Eclipse IDE</title> + + <para> + It is recommended that you have the Luna SR2 (4.4.2) + version of the Eclipse IDE installed on your development + system. + However, if you currently have the Kepler 4.3.2 version + installed and you do not want to upgrade the IDE, you can + configure Kepler to work with the Yocto Project. + </para> + + <para> + If you do not have the Luna SR2 (4.4.2) Eclipse IDE + installed, you can find the tarball at + <ulink url='&ECLIPSE_MAIN_URL;'></ulink>. + From that site, choose the appropriate download from the + "Eclipse IDE for C/C++ Developers". + This version contains the Eclipse Platform, the Java + Development Tools (JDT), and the Plug-in Development + Environment. + </para> + + <para> + Once you have downloaded the tarball, extract it into a + clean directory. + For example, the following commands unpack and install the + downloaded Eclipse IDE tarball into a clean directory + using the default name <filename>eclipse</filename>: + <literallayout class='monospaced'> + $ cd ~ + $ tar -xzvf ~/Downloads/eclipse-cpp-luna-SR2-linux-gtk-x86_64.tar.gz + </literallayout> + </para> + </section> + + <section id='configuring-the-eclipse-ide'> + <title>Configuring the Eclipse IDE</title> + + <para> + This section presents the steps needed to configure the + Eclipse IDE. + </para> + + <para> + Before installing and configuring the Eclipse Yocto Plug-in, + you need to configure the Eclipse IDE. + Follow these general steps: + <orderedlist> + <listitem><para>Start the Eclipse IDE.</para></listitem> + <listitem><para>Make sure you are in your Workbench and + select "Install New Software" from the "Help" + pull-down menu.</para></listitem> + <listitem><para>Select + <filename>Luna - &ECLIPSE_LUNA_URL;</filename> + from the "Work with:" pull-down menu. + <note> + For Kepler, select + <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename> + </note> + </para></listitem> + <listitem><para>Expand the box next to "Linux Tools" + and select the + <filename>Linux Tools LTTng Tracer Control</filename>, + <filename>Linux Tools LTTng Userspace Analysis</filename>, + and + <filename>LTTng Kernel Analysis</filename> boxes. + If these selections do not appear in the list, + that means the items are already installed. + <note> + For Kepler, select + <filename>LTTng - Linux Tracing Toolkit</filename> + box. + </note> + </para></listitem> + <listitem><para>Expand the box next to "Mobile and + Device Development" and select the following boxes. + Again, if any of the following items are not + available for selection, that means the items are + already installed: + <itemizedlist> + <listitem><para><filename>C/C++ Remote Launch (Requires RSE Remote System Explorer)</filename></para></listitem> + <listitem><para><filename>Remote System Explorer End-user Runtime</filename></para></listitem> + <listitem><para><filename>Remote System Explorer User Actions</filename></para></listitem> + <listitem><para><filename>Target Management Terminal (Core SDK)</filename></para></listitem> + <listitem><para><filename>TCF Remote System Explorer add-in</filename></para></listitem> + <listitem><para><filename>TCF Target Explorer</filename></para></listitem> + </itemizedlist></para></listitem> + <listitem><para>Expand the box next to "Programming + Languages" and select the + <filename>C/C++ Autotools Support</filename> + and <filename>C/C++ Development Tools</filename> + boxes. + For Luna, these items do not appear on the list + as they are already installed. + </para></listitem> + <listitem><para>Complete the installation and restart + the Eclipse IDE.</para></listitem> + </orderedlist> + </para> + </section> + + <section id='installing-the-eclipse-yocto-plug-in'> + <title>Installing or Accessing the Eclipse Yocto Plug-in</title> + + <para> + You can install the Eclipse Yocto Plug-in into the Eclipse + IDE one of two ways: use the Yocto Project's Eclipse + Update site to install the pre-built plug-in or build and + install the plug-in from the latest source code. + </para> + + <section id='new-software'> + <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> + + <para> + To install the Eclipse Yocto Plug-in from the update + site, follow these steps: + <orderedlist> + <listitem><para>Start up the Eclipse IDE. + </para></listitem> + <listitem><para>In Eclipse, select "Install New + Software" from the "Help" menu. + </para></listitem> + <listitem><para>Click "Add..." in the "Work with:" + area.</para></listitem> + <listitem><para>Enter + <filename>&ECLIPSE_DL_PLUGIN_URL;/luna</filename> + in the URL field and provide a meaningful name + in the "Name" field. + <note> + If you are using Kepler, use + <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename> + in the URL field. + </note></para></listitem> + <listitem><para>Click "OK" to have the entry added + to the "Work with:" drop-down list. + </para></listitem> + <listitem><para>Select the entry for the plug-in + from the "Work with:" drop-down list. + </para></listitem> + <listitem><para>Check the boxes next to + <filename>Yocto Project ADT Plug-in</filename>, + <filename>Yocto Project Bitbake Commander Plug-in</filename>, + and + <filename>Yocto Project Documentation plug-in</filename>. + </para></listitem> + <listitem><para>Complete the remaining software + installation steps and then restart the Eclipse + IDE to finish the installation of the plug-in. + <note> + You can click "OK" when prompted about + installing software that contains unsigned + content. + </note> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='zip-file-method'> + <title>Installing the Plug-in Using the Latest Source Code</title> + + <para> + To install the Eclipse Yocto Plug-in from the latest + source code, follow these steps: + <orderedlist> + <listitem><para>Be sure your development system + is not using OpenJDK to build the plug-in + by doing the following: + <orderedlist> + <listitem><para>Use the Oracle JDK. + If you don't have that, go to + <ulink url='http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html'></ulink> + and download the latest appropriate + Java SE Development Kit tarball for + your development system and + extract it into your home directory. + </para></listitem> + <listitem><para>In the shell you are going + to do your work, export the location of + the Oracle Java. + The previous step creates a new folder + for the extracted software. + You need to use the following + <filename>export</filename> command + and provide the specific location: + <literallayout class='monospaced'> + export PATH=~/<replaceable>extracted_jdk_location</replaceable>/bin:$PATH + </literallayout> + </para></listitem> + </orderedlist> + </para></listitem> + <listitem><para>In the same shell, create a Git + repository with: + <literallayout class='monospaced'> + $ cd ~ + $ git clone git://git.yoctoproject.org/eclipse-poky + </literallayout> + </para></listitem> + <listitem><para>Be sure to checkout the correct + tag. + For example, if you are using Luna, do the + following: + <literallayout class='monospaced'> + $ git checkout luna/yocto-&DISTRO; + </literallayout> + This puts you in a detached HEAD state, which + is fine since you are only going to be building + and not developing. + <note> + If you are building kepler, checkout the + <filename>kepler/yocto-&DISTRO;</filename> + branch. + </note> + </para></listitem> + <listitem><para>Change to the + <filename>scripts</filename> + directory within the Git repository: + <literallayout class='monospaced'> + $ cd scripts + </literallayout> + </para></listitem> + <listitem><para>Set up the local build environment + by running the setup script: + <literallayout class='monospaced'> + $ ./setup.sh + </literallayout> + </para></listitem> + <listitem><para>When the script finishes execution, + it prompts you with instructions on how to run + the <filename>build.sh</filename> script, which + is also in the <filename>scripts</filename> + directory of the Git repository created + earlier. + </para></listitem> + <listitem><para>Run the <filename>build.sh</filename> + script as directed. + Be sure to provide the tag name, documentation + branch, and a release name. + Here is an example that uses the + <filename>luna/yocto-&DISTRO;</filename> tag, the + <filename>master</filename> documentation + branch, and + <filename>&DISTRO_NAME_NO_CAP;</filename> for the + release name: + <literallayout class='monospaced'> + $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh luna/yocto-&DISTRO; master &DISTRO_NAME_NO_CAP; 2>&1 | tee -a build.log + </literallayout> + After running the script, the file + <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename> + is in the current directory. + </para></listitem> + <listitem><para>If necessary, start the Eclipse IDE + and be sure you are in the Workbench. + </para></listitem> + <listitem><para>Select "Install New Software" from + the "Help" pull-down menu. + </para></listitem> + <listitem><para>Click "Add".</para></listitem> + <listitem><para>Provide anything you want in the + "Name" field. + </para></listitem> + <listitem><para>Click "Archive" and browse to the + ZIP file you built in step eight. + This ZIP file should not be "unzipped", and must + be the <filename>*archive.zip</filename> file + created by running the + <filename>build.sh</filename> script. + </para></listitem> + <listitem><para>Click the "OK" button. + </para></listitem> + <listitem><para>Check the boxes that appear in + the installation window to install the + <filename>Yocto Project ADT Plug-in</filename>, + <filename>Yocto Project Bitbake Commander Plug-in</filename>, + and the + <filename>Yocto Project Documentation plug-in</filename>. + </para></listitem> + <listitem><para>Finish the installation by clicking + through the appropriate buttons. + You can click "OK" when prompted about + installing software that contains unsigned + content. + </para></listitem> + <listitem><para>Restart the Eclipse IDE if + necessary. + </para></listitem> + </orderedlist> + </para> + + <para> + At this point you should be able to configure the + Eclipse Yocto Plug-in as described in the + "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" + section.</para> + </section> + </section> + + <section id='configuring-the-eclipse-yocto-plug-in'> + <title>Configuring the Eclipse Yocto Plug-in</title> + + <para> + Configuring the Eclipse Yocto Plug-in involves setting the + Cross Compiler options and the Target options. + The configurations you choose become the default settings + for all projects. + You do have opportunities to change them later when + you configure the project (see the following section). + </para> + + <para> + To start, you need to do the following from within the + Eclipse IDE: + <itemizedlist> + <listitem><para>Choose "Preferences" from the + "Window" menu to display the Preferences Dialog. + </para></listitem> + <listitem><para>Click "Yocto Project ADT" to display + the configuration screen. + </para></listitem> + </itemizedlist> + </para> + + <section id='configuring-the-cross-compiler-options'> + <title>Configuring the Cross-Compiler Options</title> + + <para> + To configure the Cross Compiler Options, you must select + the type of toolchain, point to the toolchain, specify + the sysroot location, and select the target + architecture. + <itemizedlist> + <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis> + Choose between + <filename>Standalone pre-built toolchain</filename> + and + <filename>Build system derived toolchain</filename> + for Cross Compiler Options. + <itemizedlist> + <listitem><para><emphasis> + <filename>Standalone Pre-built Toolchain:</filename></emphasis> + Select this mode when you are using + a stand-alone cross-toolchain. + For example, suppose you are an + application developer and do not + need to build a target image. + Instead, you just want to use an + architecture-specific toolchain on + an existing kernel and target root + filesystem.</para></listitem> + <listitem><para><emphasis> + <filename>Build System Derived Toolchain:</filename></emphasis> + Select this mode if the + cross-toolchain has been installed + and built as part of the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + When you select + <filename>Build system derived toolchain</filename>, + you are using the toolchain bundled + inside the Build Directory. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Point to the Toolchain:</emphasis> + If you are using a stand-alone pre-built + toolchain, you should be pointing to where it is + installed. + See the + "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" + section for information about how the SDK is + installed.</para> + <para>If you are using a system-derived + toolchain, the path you provide for the + <filename>Toolchain Root Location</filename> + field is the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + See the + "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" + section.</para></listitem> + <listitem><para><emphasis>Specify the Sysroot Location:</emphasis> + This location is where the root filesystem for + the target hardware resides. + </para> + <para>The location of + the sysroot filesystem depends on where you + separately extracted and installed the + filesystem.</para> + <para>For information on how to install the + toolchain and on how to extract and install the + sysroot filesystem, see the + "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" + section. + </para></listitem> + <listitem><para><emphasis>Select the Target Architecture:</emphasis> + The target architecture is the type of hardware + you are going to use or emulate. + Use the pull-down + <filename>Target Architecture</filename> menu + to make your selection. + The pull-down menu should have the supported + architectures. + If the architecture you need is not listed in + the menu, you will need to build the image. + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" + section of the Yocto Project Quick Start for + more information.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='configuring-the-target-options'> + <title>Configuring the Target Options</title> + + <para> + You can choose to emulate hardware using the QEMU + emulator, or you can choose to run your image on actual + hardware. + <itemizedlist> + <listitem><para><emphasis>QEMU:</emphasis> + Select this option if you will be using the + QEMU emulator. + If you are using the emulator, you also need to + locate the kernel and specify any custom + options.</para> + <para>If you selected + <filename>Build system derived toolchain</filename>, + the target kernel you built will be located in + the Build Directory in + <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename> + directory. + If you selected + <filename>Standalone pre-built toolchain</filename>, + the pre-built image you downloaded is located + in the directory you specified when you + downloaded the image.</para> + <para>Most custom options are for advanced QEMU + users to further customize their QEMU instance. + These options are specified between paired + angled brackets. + Some options must be specified outside the + brackets. + In particular, the options + <filename>serial</filename>, + <filename>nographic</filename>, and + <filename>kvm</filename> must all be outside the + brackets. + Use the <filename>man qemu</filename> command + to get help on all the options and their use. + The following is an example: + <literallayout class='monospaced'> + serial ‘<-m 256 -full-screen>’ + </literallayout></para> + <para> + Regardless of the mode, Sysroot is already + defined as part of the Cross-Compiler Options + configuration in the + <filename>Sysroot Location:</filename> field. + </para></listitem> + <listitem><para><emphasis>External HW:</emphasis> + Select this option if you will be using actual + hardware.</para></listitem> + </itemizedlist> + </para> + + <para> + Click the "OK" to save your plug-in configurations. + </para> + </section> + </section> + </section> + + <section id='creating-the-project'> + <title>Creating the Project</title> + + <para> + You can create two types of projects: Autotools-based, or + Makefile-based. + This section describes how to create Autotools-based projects + from within the Eclipse IDE. + For information on creating Makefile-based projects in a + terminal window, see the + "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>" + section. + <note> + Do not use special characters in project names + (e.g. spaces, underscores, etc.). Doing so can + cause configuration to fail. + </note> + </para> + + <para> + To create a project based on a Yocto template and then display + the source code, follow these steps: + <orderedlist> + <listitem><para>Select "Project" from the "File -> New" menu. + </para></listitem> + <listitem><para>Double click <filename>CC++</filename>. + </para></listitem> + <listitem><para>Double click <filename>C Project</filename> + to create the project.</para></listitem> + <listitem><para>Expand <filename>Yocto Project ADT Autotools Project</filename>. + </para></listitem> + <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>. + This is an Autotools-based project based on a Yocto + template.</para></listitem> + <listitem><para>Put a name in the <filename>Project name:</filename> + field. + Do not use hyphens as part of the name. + </para></listitem> + <listitem><para>Click "Next".</para></listitem> + <listitem><para>Add information in the + <filename>Author</filename> and + <filename>Copyright notice</filename> fields. + </para></listitem> + <listitem><para>Be sure the <filename>License</filename> + field is correct.</para></listitem> + <listitem><para>Click "Finish".</para></listitem> + <listitem><para>If the "open perspective" prompt appears, + click "Yes" so that you in the C/C++ perspective. + </para></listitem> + <listitem><para>The left-hand navigation pane shows your + project. + You can display your source by double clicking the + project's source file.</para></listitem> + </orderedlist> + </para> + </section> + + <section id='configuring-the-cross-toolchains'> + <title>Configuring the Cross-Toolchains</title> + + <para> + The earlier section, + "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>", + sets up the default project configurations. + You can override these settings for a given project by following + these steps: + <orderedlist> + <listitem><para>Select "Change Yocto Project Settings" from + the "Project" menu. + This selection brings up the Yocto Project Settings + Dialog and allows you to make changes specific to an + individual project.</para> + <para>By default, the Cross Compiler Options and Target + Options for a project are inherited from settings you + provided using the Preferences Dialog as described + earlier in the + "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" section. + The Yocto Project Settings Dialog allows you to override + those default settings for a given project. + </para></listitem> + <listitem><para>Make your configurations for the project + and click "OK". + </para></listitem> + <listitem><para>Right-click in the navigation pane and + select "Reconfigure Project" from the pop-up menu. + This selection reconfigures the project by running + <filename>autogen.sh</filename> in the workspace for + your project. + The script also runs <filename>libtoolize</filename>, + <filename>aclocal</filename>, + <filename>autoconf</filename>, + <filename>autoheader</filename>, + <filename>automake --a</filename>, and + <filename>./configure</filename>. + Click on the "Console" tab beneath your source code to + see the results of reconfiguring your project. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='building-the-project'> + <title>Building the Project</title> + + <para> + To build the project select "Build Project" from the + "Project" menu. + The console should update and you can note the cross-compiler + you are using. + <note> + When building "Yocto Project ADT Autotools" projects, the Eclipse + IDE might display error messages for Functions/Symbols/Types + that cannot be "resolved", even when the related include file + is listed at the project navigator and when the project is + able to build. + For these cases only, it is recommended to add a new linked + folder to the appropriate sysroot. + Use these steps to add the linked folder: + <orderedlist> + <listitem><para> + Select the project. + </para></listitem> + <listitem><para> + Select "Folder" from the + <filename>File > New</filename> menu. + </para></listitem> + <listitem><para> + In the "New Folder" Dialog, select "Link to alternate + location (linked folder)". + </para></listitem> + <listitem><para> + Click "Browse" to navigate to the include folder inside + the same sysroot location selected in the Yocto Project + configuration preferences. + </para></listitem> + <listitem><para> + Click "OK". + </para></listitem> + <listitem><para> + Click "Finish" to save the linked folder. + </para></listitem> + </orderedlist> + </note> + </para> + </section> + + <section id='starting-qemu-in-user-space-nfs-mode'> + <title>Starting QEMU in User-Space NFS Mode</title> + + <para> + To start the QEMU emulator from within Eclipse, follow these + steps: + <note> + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" + chapter in the Yocto Project Development Manual + for more information on using QEMU. + </note> + <orderedlist> + <listitem><para>Expose and select "External Tools" from + the "Run" menu. + Your image should appear as a selectable menu item. + </para></listitem> + <listitem><para>Select your image from the menu to launch + the emulator in a new window. + </para></listitem> + <listitem><para>If needed, enter your host root password in + the shell window at the prompt. + This sets up a <filename>Tap 0</filename> connection + needed for running in user-space NFS mode. + </para></listitem> + <listitem><para>Wait for QEMU to launch.</para></listitem> + <listitem><para>Once QEMU launches, you can begin operating + within that environment. + One useful task at this point would be to determine the + IP Address for the user-space NFS by using the + <filename>ifconfig</filename> command. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='deploying-and-debugging-the-application'> + <title>Deploying and Debugging the Application</title> + + <para> + Once the QEMU emulator is running the image, you can deploy + your application using the Eclipse IDE and then use + the emulator to perform debugging. + Follow these steps to deploy the application. + <note> + Currently, Eclipse does not support SSH port forwarding. + Consequently, if you need to run or debug a remote + application using the host display, you must create a + tunneling connection from outside Eclipse and keep + that connection alive during your work. + For example, in a new terminal, run the following: + <literallayout class='monospaced'> + ssh -XY user_name@remote_host_ip + </literallayout> + After running the command, add the command to be executed + in Eclipse's run configuration before the application + as follows: + <literallayout class='monospaced'> + export DISPLAY=:10.0 + </literallayout> + </note> + <orderedlist> + <listitem><para>Select "Debug Configurations..." from the + "Run" menu.</para></listitem> + <listitem><para>In the left area, expand + <filename>C/C++Remote Application</filename>. + </para></listitem> + <listitem><para>Locate your project and select it to bring + up a new tabbed view in the Debug Configurations Dialog. + </para></listitem> + <listitem><para>Enter the absolute path into which you want + to deploy the application. + Use the "Remote Absolute File Path for + C/C++Application:" field. + For example, enter + <filename>/usr/bin/<replaceable>programname</replaceable></filename>. + </para></listitem> + <listitem><para>Click on the "Debugger" tab to see the + cross-tool debugger you are using.</para></listitem> + <listitem><para>Click on the "Main" tab.</para></listitem> + <listitem><para>Create a new connection to the QEMU instance + by clicking on "new".</para></listitem> + <listitem><para>Select <filename>TCF</filename>, which means + Target Communication Framework.</para></listitem> + <listitem><para>Click "Next".</para></listitem> + <listitem><para>Clear out the "host name" field and enter + the IP Address determined earlier.</para></listitem> + <listitem><para>Click "Finish" to close the + New Connections Dialog.</para></listitem> + <listitem><para>Use the drop-down menu now in the + "Connection" field and pick the IP Address you entered. + </para></listitem> + <listitem><para>Click "Debug" to bring up a login screen + and login.</para></listitem> + <listitem><para>Accept the debug perspective. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='running-user-space-tools'> + <title>Running User-Space Tools</title> + + <para> + As mentioned earlier in the manual, several tools exist that + enhance your development experience. + These tools are aids in developing and debugging applications + and images. + You can run these user-space tools from within the Eclipse + IDE through the "YoctoProjectTools" menu. + </para> + + <para> + Once you pick a tool, you need to configure it for the remote + target. + Every tool needs to have the connection configured. + You must select an existing TCF-based RSE connection to the + remote target. + If one does not exist, click "New" to create one. + </para> + + <para> + Here are some specifics about the remote tools: + <itemizedlist> + <listitem><para><emphasis><filename>Lttng2.0 trace import</filename>:</emphasis> + Selecting this tool transfers the remote target's + <filename>Lttng</filename> tracing data back to the + local host machine and uses the Lttng Eclipse plug-in + to graphically display the output. + For information on how to use Lttng to trace an + application, + see <ulink url='http://lttng.org/documentation'></ulink> + and the + "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>" + section, which is in the Yocto Project Profiling and + Tracing Manual. + <note>Do not use + <filename>Lttng-user space (legacy)</filename> tool. + This tool no longer has any upstream support.</note> + </para> + <para>Before you use the + <filename>Lttng2.0 trace import</filename> tool, + you need to setup the Lttng Eclipse plug-in and create a + Tracing project. + Do the following: + <orderedlist> + <listitem><para>Select "Open Perspective" from the + "Window" menu and then select "Other..." to + bring up a menu of other perspectives. + Choose "Tracing". + </para></listitem> + <listitem><para>Click "OK" to change the Eclipse + perspective into the Tracing perspective. + </para></listitem> + <listitem><para>Create a new Tracing project by + selecting "Project" from the "File -> New" menu. + </para></listitem> + <listitem><para>Choose "Tracing Project" from the + "Tracing" menu and click "Next". + </para></listitem> + <listitem><para>Provide a name for your tracing + project and click "Finish". + </para></listitem> + <listitem><para>Generate your tracing data on the + remote target.</para></listitem> + <listitem><para>Select "Lttng2.0 trace import" + from the "Yocto Project Tools" menu to + start the data import process.</para></listitem> + <listitem><para>Specify your remote connection name. + </para></listitem> + <listitem><para>For the Ust directory path, specify + the location of your remote tracing data. + Make sure the location ends with + <filename>ust</filename> (e.g. + <filename>/usr/mysession/ust</filename>). + </para></listitem> + <listitem><para>Click "OK" to complete the import + process. + The data is now in the local tracing project + you created.</para></listitem> + <listitem><para>Right click on the data and then use + the menu to Select "Generic CTF Trace" from the + "Trace Type... -> Common Trace Format" menu to + map the tracing type.</para></listitem> + <listitem><para>Right click the mouse and select + "Open" to bring up the Eclipse Lttng Trace + Viewer so you view the tracing data. + </para></listitem> + </orderedlist></para></listitem> + <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> + Selecting this tool runs PowerTOP on the remote target + machine and displays the results in a new view called + PowerTOP.</para> + <para>The "Time to gather data(sec):" field is the time + passed in seconds before data is gathered from the + remote target for analysis.</para> + <para>The "show pids in wakeups list:" field corresponds + to the <filename>-p</filename> argument passed to + <filename>PowerTOP</filename>.</para></listitem> + <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis> + LatencyTOP identifies system latency, while + Perf monitors the system's performance counter + registers. + Selecting either of these tools causes an RSE terminal + view to appear from which you can run the tools. + Both tools refresh the entire screen to display results + while they run. + For more information on setting up and using + <filename>perf</filename>, see the + "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>" + section in the Yocto Project Profiling and Tracing + Manual. + </para></listitem> + <listitem><para><emphasis><filename>SystemTap</filename>:</emphasis> + Systemtap is a tool that lets you create and reuse + scripts to examine the activities of a live Linux + system. + You can easily extract, filter, and summarize data + that helps you diagnose complex performance or + functional problems. + For more information on setting up and using + <filename>SystemTap</filename>, see the + <ulink url='https://sourceware.org/systemtap/documentation.html'>SystemTap Documentation</ulink>. + </para></listitem> + <listitem><para><emphasis><filename>yocto-bsp</filename>:</emphasis> + The <filename>yocto-bsp</filename> tool lets you + quickly set up a Board Support Package (BSP) layer. + The tool requires a Metadata location, build location, + BSP name, BSP output location, and a kernel + architecture. + For more information on the + <filename>yocto-bsp</filename> tool outside of Eclipse, + see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</ulink>" + section in the Yocto Project Board Support Package + (BSP) Developer's Guide. + </para></listitem> + </itemizedlist> + </para> + </section> + </section> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> |
