sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

sdk-manual: New Projet chapter added and other fixes 

I extracted the sections on Makefile, Autotools, and Eclipse into
their own new chapter.  Seemed to make sense as they are projet
types for both standard and extensible SDK types.  Also, swapped
the order of appearance from standard first to extensible first.
This swapping caused a bit of rewriting.

(From yocto-docs rev: 138a4d5576123da800a8fd8d99462a138ceeb743)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2016-09-19 16:45:26 -07:00 committed by Richard Purdie
parent ed6a5495a1
commit fe8d575433
5 changed files with 3236 additions and 2858 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

264
documentation/sdk-manual/sdk-extensible.xml
View File

@ -4,78 +4,149 @@
<chapter id='sdk-extensible'>
<title>Using the Extensible SDK</title>
<title>Using the Extensible SDK</title>
<para>
This chapter describes the extensible SDK and how to use it.
<para>
This chapter describes the extensible SDK and how to install it.
Information covers the pieces of the SDK, how to install it, and
presents a look at using the <filename>devtool</filename>
functionality.
The extensible SDK makes it easy to add new applications and libraries
to an image, modify the source for an existing component, test
changes on the target hardware, and ease integration into the rest of the
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>
<note>
For a side-by-side comparison of main features supported for an
extensible SDK as compared to a standard SDK, see the
"<link linkend='sdk-manual-intro'>Introduction</link>"
section.
</note>
</para>
<para>
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>
<para>
You can use an extensible SDK to work on Makefile, Autotools, and
Eclipse-based projects.
See the
"<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>"
chapter for more information.
</para>
<section id='sdk-setting-up-to-use-the-extensible-sdk'>
<section id='sdk-extensible-sdk-intro'>
<title>Why use the Extensible SDK and What is in It?</title>
<para>
The extensible SDK provides a cross-development toolchain and
libraries tailored to the contents of a specific image.
You would use the Extensible SDK if you want a toolchain experience
supplemented with the powerful set of <filename>devtool</filename>
commands tailored for the Yocto Project environment.
</para>
<para>
The installed extensible SDK consists of several files and
directories.
Basically, it contains an SDK environment setup script, some
configuration files, an internal build system, and the
<filename>devtool</filename> functionality.
</para>
</section>
<section id='sdk-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.
to the SDK and the installer also prepares the internal build
system within the SDK.
You can find pre-built extensible SDK installers in the same
<ulink url='http://downloads.yoctoproject.org/releases/yocto/yocto-&DISTRO;/toolchain/'>toolchain</ulink>
location as the pre-built standard SDK installers.
For extensible SDK installers, the
<filename>ext</filename> string is part of the name.
Here is an example:
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, the internal build system, <filename>devtool</filename>,
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.
An extensible SDK has the string "-ext" as part of the name.
<literallayout class='monospaced'>
poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh
Where:
<replaceable>host_system</replaceable> is a string representing your development system:
i686 or x86_64.
<replaceable>image_type</replaceable> is the image for which the SDK was built.
<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-ext-&DISTRO;.sh
</literallayout>
<note>
As an alternative to downloading an SDK, you can build the toolchain
installer.
As an alternative to downloading an SDK, you can build the
toolchain installer.
For information on building the installer, see the
"<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
section.
Another helpful resource for building an installer is the
<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
wiki page.
This wiki page focuses on development when using the Eclipse
IDE.
</note>
</para>
<para>
The SDK and toolchains are self-contained and by default are
installed into the <filename>poky_sdk</filename> folder in your
home directory.
You can choose to install the extensible SDK in any location when
you run the installer.
However, 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>
<para>
The following command shows how to run the installer given a
toolchain tarball for a 64-bit x86 development host system and
a 64-bit x86 target architecture.
The example assumes the 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>
Here is example output for running the extensible SDK
installer:
<literallayout class='monospaced'>
$ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-&DISTRO;.sh
Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
@ -91,26 +162,68 @@
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>
</section>
<section id='sdk-running-the-extensible-sdk-environment-setup-script'>
<title>Running the Extensible SDK Environment Setup Script</title>
<para>
Once you have the SDK installed, you must run the SDK environment
setup script before you can actually use it.
This setup script resides in the directory you chose when you
installed the SDK, which is either the default
<filename>poky_sdk</filename> directory or the directory you
chose during installation.
</para>
<para>
After installing the SDK, you need to run the SDK environment setup
script.
Here is the output from an example run:
Before running the script, be sure it is the one that matches the
architecture for which you are developing.
Environment setup scripts begin with the string
"<filename>environment-setup</filename>" and include as part of
their name the tuned target architecture.
As an example, the following commands set the working directory
to where the SDK was installed and then source the environment
setup script.
In this example, the setup script is for an IA-based
target machine using i586 tuning:
<literallayout class='monospaced'>
$ cd /home/scottrif/poky_sdk
$ source environment-setup-core2-64-poky-linux
SDK environment now set up; additionally you may now run devtool to perform development tasks.
Run devtool --help for further details.
</literallayout>
Once you run the environment setup script, you have
<filename>devtool</filename> available.
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>
<section id='using-devtool-in-your-sdk-workflow'>
<section id='using-devtool-in-your-sdk-workflow'>
<title>Using <filename>devtool</filename> in Your SDK Workflow</title>
<para>
@ -774,9 +887,9 @@
</orderedlist>
</para>
</section>
</section>
</section>
<section id='sdk-a-closer-look-at-devtool-add'>
<section id='sdk-a-closer-look-at-devtool-add'>
<title>A Closer Look at <filename>devtool add</filename></title>
<para>
@ -1143,9 +1256,9 @@
accordingly.
</para>
</section>
</section>
</section>
<section id='sdk-working-with-recipes'>
<section id='sdk-working-with-recipes'>
<title>Working With Recipes</title>
<para>
@ -1371,9 +1484,9 @@
building installs files into non-standard locations.
</para>
</section>
</section>
</section>
<section id='sdk-restoring-the-target-device-to-its-original-state'>
<section id='sdk-restoring-the-target-device-to-its-original-state'>
<title>Restoring the Target Device to its Original State</title>
<para>
@ -1412,9 +1525,9 @@
Doing so could result in a conflicting set of files.
</note>
</para>
</section>
</section>
<section id='sdk-installing-additional-items-into-the-extensible-sdk'>
<section id='sdk-installing-additional-items-into-the-extensible-sdk'>
<title>Installing Additional Items Into the Extensible SDK</title>
<para>
@ -1450,9 +1563,9 @@
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>
<section id='sdk-updating-the-extensible-sdk'>
<section id='sdk-updating-the-extensible-sdk'>
<title>Updating the Extensible SDK</title>
<para>
@ -1479,9 +1592,9 @@
SDK installer that you would download and install.
</note>
</para>
</section>
</section>
<section id='sdk-creating-a-derivative-sdk-with-additional-components'>
<section id='sdk-creating-a-derivative-sdk-with-additional-components'>
<title>Creating a Derivative SDK With Additional Components</title>
<para>
@ -1512,8 +1625,7 @@
derivative SDK, leaving the workspace clean and ready for users
to add their own recipes.
</para>
</section>
</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4

114
documentation/sdk-manual/sdk-intro.xml
View File

@ -12,25 +12,24 @@
Welcome to the Yocto Project Software Development Kit (SDK)
Developer's Guide.
This manual provides information that explains how to use both the
standard Yocto Project SDK and an extensible SDK to develop
applications and images using the Yocto Project.
Yocto Project extensible and standard SDKs to develop
applications and images.
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 within the SDK environment.
</para>
<para>
<note>
Prior to the 2.0 Release of the Yocto Project, application
development was primarily accomplished through the use of the
Application Development Toolkit (ADT) and the availability
of stand-alone cross-development toolchains and other tools.
With the 2.1 Release of the Yocto Project, application development
has transitioned to within a more traditional SDK and extensible
SDK.
has transitioned to within a tool-rich extensible SDK and the more
traditional standard SDK.
</note>
</para>
<para>
A standard SDK consists of the following:
All SDKs consist of the following:
<itemizedlist>
<listitem><para><emphasis>Cross-Development Toolchain</emphasis>:
This toolchain contains a compiler, debugger, and various
@ -46,19 +45,19 @@
preparing for SDK use.
</para></listitem>
</itemizedlist>
You can use the standard 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
Additionally an extensible SDK has tools that allow you to easily add
new applications and libraries to an image, modify the source of an
existing component, test changes on the target hardware, and easily
integrate an application into the
<ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
</para>
<para>
You can use an SDK to independently develop and test code
that is destined to run on some target machine.
SDKs are completely self-contained.
The binaries are linked against their own copy of
<filename>libc</filename>, which results in no dependencies
@ -73,7 +72,7 @@
<para>
Another feature for the SDKs is that only one set of cross-compiler
toolchain binaries are produced per architecture.
toolchain binaries are produced for any given architecture.
This feature takes advantage of the fact that the target hardware can
be passed to <filename>gcc</filename> as a set of compiler options.
Those options are set up by the environment script and contained in
@ -98,6 +97,8 @@
configuration and extensions,
which allows you to cross-develop on the host machine for the
target hardware.
Additionally, the extensible SDK contains the
<filename>devtool</filename> functionality.
</para></listitem>
<listitem><para>The Quick EMUlator (QEMU), which lets you simulate
target hardware.
@ -122,6 +123,85 @@
</itemizedlist>
</para>
<para>
In summary, the extensible and standard SDK share many features.
However, the extensible SDK has powerful development tools to help you
more quickly develop applications.
Following is a table that summarizes the primary differences between
the standard and extensible SDK types when considering which to
build:
<informaltable frame='none'>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
<colspec colname='c1' colwidth='1*'/>
<colspec colname='c2' colwidth='1*'/>
<colspec colname='c3' colwidth='1*'/>
<thead>
<row>
<entry align="left"><emphasis>Feature</emphasis></entry>
<entry align="left"><emphasis>Standard SDK</emphasis></entry>
<entry align="left"><emphasis>Extensible SDK</emphasis></entry>
</row>
</thead>
<tbody>
<row>
<entry align="left">Toolchain</entry>
<entry align="left">Yes</entry>
<entry align="left">Yes*</entry>
</row>
<row>
<entry align="left">Debugger</entry>
<entry align="left">Yes</entry>
<entry align="left">Yes*</entry>
</row>
<row>
<entry align="left">Size</entry>
<entry align="left">100+ MBytes</entry>
<entry align="left">1+ GBytes (or 300+ MBytes for minimal w/toolchain)</entry>
</row>
<row>
<entry align="left"><filename>devtool</filename></entry>
<entry align="left">No</entry>
<entry align="left">Yes</entry>
</row>
<row>
<entry align="left">Build Images</entry>
<entry align="left">No</entry>
<entry align="left">Yes</entry>
</row>
<row>
<entry align="left">Updateable</entry>
<entry align="left">No</entry>
<entry align="left">Yes</entry>
</row>
<row>
<entry align="left">Managed Sysroot**</entry>
<entry align="left">No</entry>
<entry align="left">Yes</entry>
</row>
<row>
<entry align="left">Installed Packages</entry>
<entry align="left">No***</entry>
<entry align="left">Yes****</entry>
</row>
<row>
<entry align="left">Construction</entry>
<entry align="left">Packages</entry>
<entry align="left">Shared State</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<literallayout class='monospaced'>
* Extensible SDK will contain the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default.
** Sysroot is managed through use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries.
*** Runtime package management can be added to the standard SDK but it is not supported by default.
**** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install.
</literallayout>
</para>
<section id='the-cross-development-toolchain'>
<title>The Cross-Development Toolchain</title>
@ -131,6 +211,8 @@
consists of a cross-compiler, cross-linker, and cross-debugger
that are used to develop user-space applications for targeted
hardware.
Additionally, for an extensible SDK, the toolchain also has
built-in <filename>devtool</filename> functionality.
This toolchain is created by running a toolchain installer script
or through a
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
@ -258,7 +340,7 @@
For information on how to install the SDK, see the
"<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
section.</para></listitem>
<listitem><para><emphasis>Download the Target Image:</emphasis>
<listitem><para><emphasis>Download or Build the Target Image:</emphasis>
The Yocto Project supports several target architectures
and has many pre-built kernel images and root filesystem
images.</para>

4
documentation/sdk-manual/sdk-manual.xml
View File

@ -66,9 +66,11 @@
<xi:include href="sdk-intro.xml"/>
<xi:include href="sdk-extensible.xml"/>
<xi:include href="sdk-using.xml"/>
<xi:include href="sdk-extensible.xml"/>
<xi:include href="sdk-working-projects.xml"/>
<xi:include href="sdk-appendix-obtain.xml"/>

1385
documentation/sdk-manual/sdk-using.xml
View File

File diff suppressed because it is too large Load Diff

1461
documentation/sdk-manual/sdk-working-projects.xml Normal file
View File

File diff suppressed because it is too large Load Diff