summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/sdk-using.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-01-26 14:57:15 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-03-23 21:56:07 +0000
commit62477889fd9f82b00003ce468cf8aad832f146e4 (patch)
tree38a8193fdcadc3964e98867c6548b14fab7c3efd /documentation/sdk-manual/sdk-using.xml
parent7ab8afa7a5ccf1f5588bd6d93f8e36e72d7d961f (diff)
downloadpoky-62477889fd9f82b00003ce468cf8aad832f146e4.tar.gz
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>
Diffstat (limited to 'documentation/sdk-manual/sdk-using.xml')
-rw-r--r--documentation/sdk-manual/sdk-using.xml230
1 files changed, 212 insertions, 18 deletions
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
index e3dc6e22a1..66f2c0ed9d 100644
--- a/documentation/sdk-manual/sdk-using.xml
+++ b/documentation/sdk-manual/sdk-using.xml
@@ -7,9 +7,9 @@
7<title>Using the Standard SDK</title> 7<title>Using the Standard SDK</title>
8 8
9<para> 9<para>
10 This chapter describes how to use a standard SDK. 10 This chapter describes the standard SDK and how to use it.
11 Information covers installing the SDK and task-based procedures common 11 Information covers the pieces of the SDK, how to install it, and presents
12 for developing with a standard SDK. 12 several task-based procedures common for developing with a standard SDK.
13 <note> 13 <note>
14 The tasks you can perform using a standard SDK are also applicable 14 The tasks you can perform using a standard SDK are also applicable
15 when you are using an extensible SDK. 15 when you are using an extensible SDK.
@@ -20,34 +20,50 @@
20 </note> 20 </note>
21</para> 21</para>
22 22
23<section id='sdk-setting-up-to-use-the-standard-sdk'> 23<section id='sdk-standard-sdk-intro'>
24 <title>Setting Up to Use the Standard SDK</title> 24 <title>Why use the Standard SDK and What is in It?</title>
25 25
26 <para> 26 <para role='writernotes'>
27 Here is a list of items I think need addressed in this section: 27 <emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
28 This paragraph describes why you use the Standard SDK.
29 Probably need to compare that against why you would not be interested
30 in the extensible SDK here as well.
31 According to Paul, the most interest lies in the extensible SDK.
32 So providing this comparison would be helpful.
33 Currently, my understanding boils down to this: The only reason to use
34 the Standard SDK is if you want to build and debug source code that
35 you have.
36 That pretty much sums it up.
37 If there is more detail, I need to know about it.
38 </para>
39
40 <para role='writernotes'>
41 <emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
42 Here is a list of items I think need addressed in these early
43 sections:
28 <itemizedlist> 44 <itemizedlist>
29 <listitem><para><emphasis>What is your situation?</emphasis></para> 45 <listitem><para role='writernotes'><emphasis>What is your situation?</emphasis></para>
30 <para>In other words, is the developer on a machine that 46 <para role='writernotes'>In other words, is the developer on a machine that
31 has YP on it? 47 has YP on it?
32 Are they on a machine that does not? 48 Are they on a machine that does not?
33 Is the image they are developing against available as a 49 Is the image they are developing against available as a
34 pre-built, down-loadable image and can they get it?</para> 50 pre-built, down-loadable image and can they get it?</para>
35 <para>Depending on the scenario, there are different ways 51 <para role='writernotes'>Depending on the scenario, there are different ways
36 to make sure the machine they are using is ready to use a 52 to make sure the machine they are using is ready to use a
37 standard SDK. 53 standard SDK.
38 I think we need to cover the various situations in this 54 I think we need to cover the various situations in this
39 section. 55 section.
40 </para></listitem> 56 </para></listitem>
41 <listitem><para><emphasis>What are the recommendations?</emphasis></para> 57 <listitem><para role='writernotes'><emphasis>What are the recommendations?</emphasis></para>
42 <para>What is the most common development scenario? 58 <para role='writernotes'>What is the most common development scenario?
43 Is there a recommended development flow we want to present 59 Is there a recommended development flow we want to present
44 when using a standard SDK? 60 when using a standard SDK?
45 What conditions in a development scenario warrant use of 61 What conditions in a development scenario warrant use of
46 just the standard SDK as compared to the extensible SDK? 62 just the standard SDK as compared to the extensible SDK?
47 </para></listitem> 63 </para></listitem>
48 <listitem><para><emphasis>What procedures do we want to cover to set up 64 <listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set up
49 the standard SDK?</emphasis></para> 65 the standard SDK?</emphasis></para>
50 <para>There is a ton of setup information in the 66 <para role='writernotes'>There is a ton of setup information in the
51 current ADT manual regarding getting, building, and installing 67 current ADT manual regarding getting, building, and installing
52 an SDK. 68 an SDK.
53 We would ignore the stuff about the ADT installer script 69 We would ignore the stuff about the ADT installer script
@@ -60,12 +76,190 @@
60 </para></listitem> 76 </para></listitem>
61 </itemizedlist> 77 </itemizedlist>
62 </para> 78 </para>
79
80 <para>
81 The installed Standard SDK consists of several files and directories.
82 Basically, it contains an SDK environment setup script, some
83 configuration files, and host and target root filesystems to support
84 usage.
85 You can see the directory structure in the
86 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
87 section.
88 <note>
89 You can also find information on how the Yocto Project
90 OpenEmbedded build system creates an SDK image by looking at the
91 "<ulink url='&YOCTO_DOCS_REF_URL;#sdk-generation-dev-environment'>SDK Generation</ulink>"
92 section in the Yocto Project Reference Manual.
93 </note>
94 </para>
95</section>
96
97<section id='sdk-installing-the-sdk'>
98 <title>Installing the SDK</title>
99
100 <para>
101 The first thing you need to do is install the SDK on your host
102 development machine by running the <filename>.sh</filename>
103 installation script.
104 </para>
105
106 <para>
107 You can download a tarball installer, which includes the
108 pre-built toolchain, the <filename>runqemu</filename>
109 script, and support files from the appropriate directory under
110 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
111 Toolchains are available for 32-bit and 64-bit x86 development
112 systems from the <filename>i686</filename> and
113 <filename>x86_64</filename> directories, respectively.
114 The toolchains the Yocto Project provides are based off the
115 <filename>core-image-sato</filename> image and contain
116 libraries appropriate for developing against that image.
117 Each type of development system supports five or more target
118 architectures.
119 </para>
120
121 <para>
122 The names of the tarball installer scripts are such that a
123 string representing the host system appears first in the
124 filename and then is immediately followed by a string
125 representing the target architecture.
126 <literallayout class='monospaced'>
127 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh
128
129 Where:
130 <replaceable>host_system</replaceable> is a string representing your development system:
131
132 i686 or x86_64.
133
134 <replaceable>image_type</replaceable> is a string representing the image you wish to
135 develop a SDK for use against. The Yocto Project builds
136 installers for standard SDKs using the following BitBake
137 command:
138
139 bitbake core-image-sato -c populate_sdk
140
141 <replaceable>arch</replaceable> is a string representing the tuned target architecture:
142
143 i586, x86_64, powerpc, mips, armv7a or armv5te
144
145 <replaceable>release_version</replaceable> is a string representing the release number of the
146 Yocto Project:
147
148 &DISTRO;, &DISTRO;+snapshot
149 </literallayout>
150 For example, the following toolchain installer is for a 64-bit
151 development host system and a i586-tuned target architecture
152 based off the SDK for <filename>core-image-sato</filename> and
153 using the current &DISTRO; snapshot:
154 <literallayout class='monospaced'>
155 poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
156 </literallayout>
157 </para>
158
159 <para>
160 The SDK and toolchains are self-contained and by default are installed
161 into <filename>/opt/poky</filename>.
162 However, when you run the SDK installer, you can choose an
163 installation directory.
164 </para>
165
166 <para>
167 The following command shows how to run the installer given a
168 toolchain tarball for a 64-bit x86 development host system and
169 a 32-bit x86 target architecture.
170 When you run the installer, the script prompts you for a
171 system password so that you permissions can change enabling
172 you to run the installer script.
173 The example assumes the toolchain installer is located in
174 <filename>~/Downloads/</filename>.
175 <note>
176 If you do not have write permissions for the directory
177 into which you are installing the SDK, the installer
178 notifies you and exits.
179 Be sure you have write permissions in the directory and
180 run the installer again.
181 </note>
182 <literallayout class='monospaced'>
183 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
184 Poky (Yocto Project Reference Distro) SDK installer version 2.1+snapshot
185 ========================================================================
186 Enter target directory for SDK (default: /opt/poky/2.1+snapshot):
187 You are about to install the SDK to "/opt/poky/2.1+snapshot". Proceed[Y/n]? Y
188 [sudo] password for scottrif:
189 Extracting SDK.......................done
190 Setting it up...done
191 SDK has been successfully set up and is ready to be used.
192 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
193 $ . /opt/poky/2.1+snapshot/environment-setup-i586-poky-linux
194 </literallayout>
195 </para>
196
197 <para>
198 Again, reference the
199 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
200 section for more details on the resulting directory structure of
201 the installed SDK.
202 </para>
203</section>
204
205<section id='sdk-running-the-sdk-environment-setup-script'>
206 <title>Running the SDK Environment Setup Script</title>
207
208 <para>
209 Once you have the SDK installed, you must run the SDK environment
210 setup script before you can actually use it.
211 This setup script resides in the directory you chose when you installed
212 the SDK.
213 For information on where this setup script can reside, see the
214 "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>"
215 Appendix.
216 </para>
217
218 <para>
219 Before running the script, be sure it is the one that matches the
220 architecture for which you are developing.
221 Environment setup scripts begin with the string
222 "<filename>environment-setup</filename>" and include as part of their
223 name the tuned target architecture.
224 For example, the setup script for an IA-based target machine using
225 i586 tuning and located in the default SDK installation
226 directory is as follows:
227 <literallayout class='monospaced'>
228 $ source /opt/poky/&DISTRO;+snapshot/environment-setup-i586-poky-linux
229 </literallayout>
230 When you run the setup script, many environment variables are
231 defined:
232 <literallayout class='monospaced'>
233 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
234 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
235 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
236 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
237 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
238 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
239 <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
240 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
241 <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
242 <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols
243 <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
244 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
245 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
246 <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
247 <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
248 <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
249 <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools
250 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
251 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
252 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
253 <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
254 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags
255 </literallayout>
256 </para>
63</section> 257</section>
64 258
65<section id='sdk-using-the-sdk-to-task-1'> 259<section id='sdk-using-the-sdk-to-task-1'>
66 <title>Using the SDK to <replaceable>item 1</replaceable></title> 260 <title>Using the SDK to <replaceable>item 1</replaceable></title>
67 261
68 <para> 262 <para role='writernotes'>
69 Describe the specific task you are going to accomplish with the SDK. 263 Describe the specific task you are going to accomplish with the SDK.
70 Provide a diagram showing the rough flow of the task. 264 Provide a diagram showing the rough flow of the task.
71 Provide specific steps using a real example that works through the 265 Provide specific steps using a real example that works through the
@@ -76,7 +270,7 @@
76<section id='sdk-using-the-sdk-to-task-2'> 270<section id='sdk-using-the-sdk-to-task-2'>
77 <title>Using the SDK to <replaceable>item-2</replaceable></title> 271 <title>Using the SDK to <replaceable>item-2</replaceable></title>
78 272
79 <para> 273 <para role='writernotes'>
80 Describe the specific task you are going to accomplish with the SDK. 274 Describe the specific task you are going to accomplish with the SDK.
81 Provide a diagram showing the rough flow of the task. 275 Provide a diagram showing the rough flow of the task.
82 Provide specific steps using a real example that works through the 276 Provide specific steps using a real example that works through the
@@ -87,7 +281,7 @@
87<section id='sdk-using-the-sdk-to-task-3'> 281<section id='sdk-using-the-sdk-to-task-3'>
88 <title>Using the SDK to <replaceable>item-3</replaceable></title> 282 <title>Using the SDK to <replaceable>item-3</replaceable></title>
89 283
90 <para> 284 <para role='writernotes'>
91 Describe the specific task you are going to accomplish with the SDK. 285 Describe the specific task you are going to accomplish with the SDK.
92 Provide a diagram showing the rough flow of the task. 286 Provide a diagram showing the rough flow of the task.
93 Provide specific steps using a real example that works through the 287 Provide specific steps using a real example that works through the
@@ -98,7 +292,7 @@
98<section id='sdk-using-the-sdk-to-task-x'> 292<section id='sdk-using-the-sdk-to-task-x'>
99 <title>Using the SDK to <replaceable>item-x</replaceable></title> 293 <title>Using the SDK to <replaceable>item-x</replaceable></title>
100 294
101 <para> 295 <para role='writernotes'>
102 Describe the specific task you are going to accomplish with the SDK. 296 Describe the specific task you are going to accomplish with the SDK.
103 Provide a diagram showing the rough flow of the task. 297 Provide a diagram showing the rough flow of the task.
104 Provide specific steps using a real example that works through the 298 Provide specific steps using a real example that works through the