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

sdk-manual: Applied some "red" text formatting to indicate notes 

I am using "red" text to indicate sections of the manual that
are my development notes.

(From yocto-docs rev: 95b432d852ac3248874a2a958d4a80e59187f062)

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-01-26 14:57:15 -08:00 committed by Richard Purdie
parent 7ab8afa7a5
commit 62477889fd
4 changed files with 229 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -6,14 +6,14 @@
<title>Customizing the SDK</title>
<para>
<para role='writernotes'>
This chapter is going to cover the details on extending the SDK through
user customizations.
I am not sure if this is possible for both the standard and extensible
SDK or what.
</para>
<para>
<para role='writernotes'>
I do not have a feel for what sub-topics need to be covered here.
I need to get this information from Paul.
</para>

6
documentation/sdk-manual/sdk-appendix-obtain.xml
View File

@ -9,18 +9,18 @@
<section id='sdk-appendix-obtain-manual-development-notes'>
<title>Manual Development Notes for Scott and Paul</title>
<para>
<para role='writernotes'>
This chapter is going to cover details about the installed SDK and perhaps
stuff on locating it (e.g. the naming scheme used to identify the
<filename>.sh</filename> installation script.
</para>
<para>
<para role='writernotes'>
The idea here is to gather all the current information in the regular
YP doc set that describes how to locate, download, or build out the SDK.
</para>
<para>
<para role='writernotes'>
One thing that needs discussed is any differences between getting the
standard SDK as compared to the extended SDK.
Do we have pre-build extensible SDKs laying around?

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

@ -6,7 +6,7 @@
<title>Using the Extensible SDK</title>
<para>
<para role='writernotes'>
This chapter describes what you need on your machine in order to use
an extensible SDK.
The chapter does not repeat information that also applies to using the
@ -26,30 +26,30 @@
<section id='sdk-setting-up-to-use-the-extensible-sdk'>
<title>Setting Up to Use the Extensible SDK</title>
<para>
<para role='writernotes'>
Here is a list of items I think need addressed in this section:
<itemizedlist>
<listitem><para><emphasis>Cover differences in the development
<listitem><para role='writernotes'><emphasis>Cover differences in the development
that might be impacted because they are using an extensible
SDK</emphasis></para>
<para>Presumably, the various development scenarios are
<para role='writernotes'>Presumably, the various development scenarios are
covered regarding setup in the previous chapter.
Are these impacted because the developer is going to now be
using an extensible SDK?
If so, what are the implications?
</para></listitem>
<listitem><para><emphasis>What new recommendations exist now that
<listitem><para role='writernotes'><emphasis>What new recommendations exist now that
the developer is going to be using an extensible SDK?</emphasis></para>
<para>We should cover the most common development scenarios
<para role='writernotes'>We should cover the most common development scenarios
that apply when using an extensible SDK.
Is there a recommended development flow we want to present
when using an extensible SDK?
What conditions in a development scenario warrant use of
the extensible SDK as compared to the standard SDK?
</para></listitem>
<listitem><para><emphasis>What procedures do we want to cover to set
<listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set
up the extensible SDK?</emphasis></para>
<para>Is it just a matter of building out the SDK using
<para role='writernotes'>Is it just a matter of building out the SDK using
<filename>bitbake -c populate_sdk_ext</filename>?
Is there a pre-built extensible SDK laying around they can
find and download if they are using a machine that does not
@ -63,7 +63,7 @@
<section id='sdk-using-the-extensible-sdk-to-task-1'>
<title>Using the Extensible SDK to <replaceable>item 1</replaceable></title>
<para>
<para role='writernotes'>
Describe the specific task you are going to accomplish with the
extensible SDK.
Provide a diagram showing the rough flow of the task.
@ -75,7 +75,7 @@
<section id='sdk-using-the-extensible-sdk-to-task-2'>
<title>Using the Extensible SDK to <replaceable>item-2</replaceable></title>
<para>
<para role='writernotes'>
Describe the specific task you are going to accomplish with the
extensible SDK.
Provide a diagram showing the rough flow of the task.
@ -87,7 +87,7 @@
<section id='sdk-using-the-extensible-sdk-to-task-3'>
<title>Using the Extensible SDK to <replaceable>item-3</replaceable></title>
<para>
<para role='writernotes'>
Describe the specific task you are going to accomplish with the
extensible SDK.
Provide a diagram showing the rough flow of the task.
@ -99,7 +99,7 @@
<section id='sdk-using-the-extensible-sdk-to-task-x'>
<title>Using the Extensible SDK to <replaceable>item-x</replaceable></title>
<para>
<para role='writernotes'>
Describe the specific task you are going to accomplish with the
extensible SDK.
Provide a diagram showing the rough flow of the task.

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

@ -7,9 +7,9 @@
<title>Using the Standard SDK</title>
<para>
This chapter describes how to use a standard SDK.
Information covers installing the SDK and task-based procedures common
for developing with a standard SDK.
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.
@ -20,34 +20,50 @@
</note>
</para>
<section id='sdk-setting-up-to-use-the-standard-sdk'>
<title>Setting Up to Use the Standard SDK</title>
<section id='sdk-standard-sdk-intro'>
<title>Why use the Standard SDK and What is in It?</title>
<para>
Here is a list of items I think need addressed in this section:
<para role='writernotes'>
<emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
This paragraph describes why you use the Standard SDK.
Probably need to compare that against why you would not be interested
in the extensible SDK here as well.
According to Paul, the most interest lies in the extensible SDK.
So providing this comparison would be helpful.
Currently, my understanding boils down to this: The only reason to use
the Standard SDK is if you want to build and debug source code that
you have.
That pretty much sums it up.
If there is more detail, I need to know about it.
</para>
<para role='writernotes'>
<emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
Here is a list of items I think need addressed in these early
sections:
<itemizedlist>
<listitem><para><emphasis>What is your situation?</emphasis></para>
<para>In other words, is the developer on a machine that
<listitem><para role='writernotes'><emphasis>What is your situation?</emphasis></para>
<para role='writernotes'>In other words, is the developer on a machine that
has YP on it?
Are they on a machine that does not?
Is the image they are developing against available as a
pre-built, down-loadable image and can they get it?</para>
<para>Depending on the scenario, there are different ways
<para role='writernotes'>Depending on the scenario, there are different ways
to make sure the machine they are using is ready to use a
standard SDK.
I think we need to cover the various situations in this
section.
</para></listitem>
<listitem><para><emphasis>What are the recommendations?</emphasis></para>
<para>What is the most common development scenario?
<listitem><para role='writernotes'><emphasis>What are the recommendations?</emphasis></para>
<para role='writernotes'>What is the most common development scenario?
Is there a recommended development flow we want to present
when using a standard SDK?
What conditions in a development scenario warrant use of
just the standard SDK as compared to the extensible SDK?
</para></listitem>
<listitem><para><emphasis>What procedures do we want to cover to set up
<listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set up
the standard SDK?</emphasis></para>
<para>There is a ton of setup information in the
<para role='writernotes'>There is a ton of setup information in the
current ADT manual regarding getting, building, and installing
an SDK.
We would ignore the stuff about the ADT installer script
@ -60,12 +76,190 @@
</para></listitem>
</itemizedlist>
</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.
<note>
You can also find information on how the Yocto Project
OpenEmbedded build system creates an SDK image by looking at the
"<ulink url='&YOCTO_DOCS_REF_URL;#sdk-generation-dev-environment'>SDK Generation</ulink>"
section in the Yocto Project Reference Manual.
</note>
</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 a string representing the image you wish to
develop a SDK for use against. The Yocto Project builds
installers for standard SDKs using the following BitBake
command:
bitbake core-image-sato -c populate_sdk
<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.
</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.
When you run the installer, the script prompts you for a
system password so that you permissions can change enabling
you to run the installer script.
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'>
$ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
Poky (Yocto Project Reference Distro) SDK installer version 2.1+snapshot
========================================================================
Enter target directory for SDK (default: /opt/poky/2.1+snapshot):
You are about to install the SDK to "/opt/poky/2.1+snapshot". Proceed[Y/n]? Y
[sudo] password for scottrif:
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+snapshot/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 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;+snapshot/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='sdk-using-the-sdk-to-task-1'>
<title>Using the SDK to <replaceable>item 1</replaceable></title>
<para>
<para role='writernotes'>
Describe the specific task you are going to accomplish with the SDK.
Provide a diagram showing the rough flow of the task.
Provide specific steps using a real example that works through the
@ -76,7 +270,7 @@
<section id='sdk-using-the-sdk-to-task-2'>
<title>Using the SDK to <replaceable>item-2</replaceable></title>
<para>
<para role='writernotes'>
Describe the specific task you are going to accomplish with the SDK.
Provide a diagram showing the rough flow of the task.
Provide specific steps using a real example that works through the
@ -87,7 +281,7 @@
<section id='sdk-using-the-sdk-to-task-3'>
<title>Using the SDK to <replaceable>item-3</replaceable></title>
<para>
<para role='writernotes'>
Describe the specific task you are going to accomplish with the SDK.
Provide a diagram showing the rough flow of the task.
Provide specific steps using a real example that works through the
@ -98,7 +292,7 @@
<section id='sdk-using-the-sdk-to-task-x'>
<title>Using the SDK to <replaceable>item-x</replaceable></title>
<para>
<para role='writernotes'>
Describe the specific task you are going to accomplish with the SDK.
Provide a diagram showing the rough flow of the task.
Provide specific steps using a real example that works through the