diff options
Diffstat (limited to 'yocto-poky/documentation/sdk-manual')
16 files changed, 0 insertions, 4880 deletions
diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png b/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png Binary files differdeleted file mode 100644 index c09e60e35..000000000 --- a/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png +++ /dev/null diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png b/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png Binary files differdeleted file mode 100644 index cd06c0181..000000000 --- a/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png +++ /dev/null diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-eclipse-dev-flow.png b/yocto-poky/documentation/sdk-manual/figures/sdk-eclipse-dev-flow.png Binary files differdeleted file mode 100644 index 9f986e0d4..000000000 --- a/yocto-poky/documentation/sdk-manual/figures/sdk-eclipse-dev-flow.png +++ /dev/null diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-environment.png b/yocto-poky/documentation/sdk-manual/figures/sdk-environment.png Binary files differdeleted file mode 100644 index 78b8cad39..000000000 --- a/yocto-poky/documentation/sdk-manual/figures/sdk-environment.png +++ /dev/null diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-installed-extensible-sdk-directory.png b/yocto-poky/documentation/sdk-manual/figures/sdk-installed-extensible-sdk-directory.png Binary files differdeleted file mode 100644 index 99e07ce6f..000000000 --- a/yocto-poky/documentation/sdk-manual/figures/sdk-installed-extensible-sdk-directory.png +++ /dev/null diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-installed-standard-sdk-directory.png b/yocto-poky/documentation/sdk-manual/figures/sdk-installed-standard-sdk-directory.png Binary files differdeleted file mode 100644 index d4af85020..000000000 --- a/yocto-poky/documentation/sdk-manual/figures/sdk-installed-standard-sdk-directory.png +++ /dev/null diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-title.png b/yocto-poky/documentation/sdk-manual/figures/sdk-title.png Binary files differdeleted file mode 100644 index e9d5b346b..000000000 --- a/yocto-poky/documentation/sdk-manual/figures/sdk-title.png +++ /dev/null diff --git a/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml b/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml deleted file mode 100644 index 79326077f..000000000 --- a/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml +++ /dev/null @@ -1,388 +0,0 @@ -<!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/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml b/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml deleted file mode 100644 index 3d4e364bf..000000000 --- a/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml +++ /dev/null @@ -1,252 +0,0 @@ -<!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/yocto-poky/documentation/sdk-manual/sdk-extensible.xml b/yocto-poky/documentation/sdk-manual/sdk-extensible.xml deleted file mode 100644 index 3e11fc97d..000000000 --- a/yocto-poky/documentation/sdk-manual/sdk-extensible.xml +++ /dev/null @@ -1,1304 +0,0 @@ -<!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/yocto-poky/documentation/sdk-manual/sdk-intro.xml b/yocto-poky/documentation/sdk-manual/sdk-intro.xml deleted file mode 100644 index 88ae77831..000000000 --- a/yocto-poky/documentation/sdk-manual/sdk-intro.xml +++ /dev/null @@ -1,338 +0,0 @@ -<!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/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl b/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl deleted file mode 100644 index dae992c07..000000000 --- a/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl +++ /dev/null @@ -1,27 +0,0 @@ -<?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/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl b/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl deleted file mode 100644 index 03555d6ca..000000000 --- a/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl +++ /dev/null @@ -1,37 +0,0 @@ -<?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/yocto-poky/documentation/sdk-manual/sdk-manual.xml b/yocto-poky/documentation/sdk-manual/sdk-manual.xml deleted file mode 100644 index c860782fb..000000000 --- a/yocto-poky/documentation/sdk-manual/sdk-manual.xml +++ /dev/null @@ -1,80 +0,0 @@ -<!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/yocto-poky/documentation/sdk-manual/sdk-style.css b/yocto-poky/documentation/sdk-manual/sdk-style.css deleted file mode 100644 index 52518964c..000000000 --- a/yocto-poky/documentation/sdk-manual/sdk-style.css +++ /dev/null @@ -1,988 +0,0 @@ -/* - 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/yocto-poky/documentation/sdk-manual/sdk-using.xml b/yocto-poky/documentation/sdk-manual/sdk-using.xml deleted file mode 100644 index 1ea47d3bb..000000000 --- a/yocto-poky/documentation/sdk-manual/sdk-using.xml +++ /dev/null @@ -1,1466 +0,0 @@ -<!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 ---> |
