summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/sdk-using.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-09-19 16:45:26 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-09-28 15:02:32 +0100
commitfe8d57543313cd6ef79141ed374ac4f708f4e810 (patch)
treef75ba6bf5c207d2a6260dc6f45f76a4ce7903e6d /documentation/sdk-manual/sdk-using.xml
parented6a5495a19b7f2bc0f9ae35027b27f2bb973576 (diff)
downloadpoky-fe8d57543313cd6ef79141ed374ac4f708f4e810.tar.gz
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>
Diffstat (limited to 'documentation/sdk-manual/sdk-using.xml')
-rw-r--r--documentation/sdk-manual/sdk-using.xml1563
1 files changed, 142 insertions, 1421 deletions
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
index dd11304319..44cb49c0c8 100644
--- a/documentation/sdk-manual/sdk-using.xml
+++ b/documentation/sdk-manual/sdk-using.xml
@@ -3,74 +3,82 @@
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > 3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4 4
5<chapter id='sdk-using-the-standard-sdk'> 5<chapter id='sdk-using-the-standard-sdk'>
6 6 <title>Using the Standard SDK</title>
7<title>Using the Standard SDK</title>
8
9<para>
10 This chapter describes the standard SDK and how to use it.
11 Information covers the pieces of the SDK, how to install it, and presents
12 several task-based procedures common for developing with a standard SDK.
13 <note>
14 The tasks you can perform using a standard SDK are also applicable
15 when you are using an extensible SDK.
16 For information on the differences when using an extensible SDK as
17 compared to a standard SDK, see the
18 "<link linkend='sdk-extensible'>Using the Extensible SDK</link>"
19 chapter.
20 </note>
21</para>
22
23<section id='sdk-standard-sdk-intro'>
24 <title>Why use the Standard SDK and What is in It?</title>
25 7
26 <para> 8 <para>
27 The Standard SDK provides a cross-development toolchain and libraries 9 This chapter describes the standard SDK and how to install it.
28 tailored to the contents of a specific image. 10 Information includes unique installation and setup aspects for the
29 You would use the Standard SDK if you want a more traditional toolchain 11 standard SDK.
30 experience. 12 <note>
13 For a side-by-side comparison of main features supported for a
14 standard SDK as compared to an extensible SDK, see the
15 "<link linkend='sdk-manual-intro'>Introduction</link>"
16 section.
17 </note>
31 </para> 18 </para>
32 19
33 <para> 20 <para>
34 The installed Standard SDK consists of several files and directories. 21 You can use a standard SDK to work on Makefile, Autotools, and
35 Basically, it contains an SDK environment setup script, some 22 Eclipse-based projects.
36 configuration files, and host and target root filesystems to support 23 See the
37 usage. 24 "<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>"
38 You can see the directory structure in the 25 chapter for more information.
39 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
40 section.
41 </para> 26 </para>
42</section>
43 27
44<section id='sdk-installing-the-sdk'> 28 <section id='sdk-standard-sdk-intro'>
45 <title>Installing the SDK</title> 29 <title>Why use the Standard SDK and What is in It?</title>
46 30
47 <para> 31 <para>
48 The first thing you need to do is install the SDK on your host 32 The Standard SDK provides a cross-development toolchain and
49 development machine by running the <filename>*.sh</filename> 33 libraries tailored to the contents of a specific image.
50 installation script. 34 You would use the Standard SDK if you want a more traditional
51 </para> 35 toolchain experience as compared to the extensible SDK, which
36 provides an internal build system and the
37 <filename>devtool</filename> functionality.
38 </para>
52 39
53 <para> 40 <para>
54 You can download a tarball installer, which includes the 41 The installed Standard SDK consists of several files and
55 pre-built toolchain, the <filename>runqemu</filename> 42 directories.
56 script, and support files from the appropriate directory under 43 Basically, it contains an SDK environment setup script, some
57 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. 44 configuration files, and host and target root filesystems to
58 Toolchains are available for 32-bit and 64-bit x86 development 45 support usage.
59 systems from the <filename>i686</filename> and 46 You can see the directory structure in the
60 <filename>x86_64</filename> directories, respectively. 47 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
61 The toolchains the Yocto Project provides are based off the 48 section.
62 <filename>core-image-sato</filename> image and contain 49 </para>
63 libraries appropriate for developing against that image. 50 </section>
64 Each type of development system supports five or more target
65 architectures.
66 </para>
67 51
68 <para> 52 <section id='sdk-installing-the-sdk'>
69 The names of the tarball installer scripts are such that a 53 <title>Installing the SDK</title>
70 string representing the host system appears first in the 54
71 filename and then is immediately followed by a string 55 <para>
72 representing the target architecture. 56 The first thing you need to do is install the SDK on your host
73 <literallayout class='monospaced'> 57 development machine by running the <filename>*.sh</filename>
58 installation script.
59 </para>
60
61 <para>
62 You can download a tarball installer, which includes the
63 pre-built toolchain, the <filename>runqemu</filename>
64 script, and support files from the appropriate directory under
65 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
66 Toolchains are available for 32-bit and 64-bit x86 development
67 systems from the <filename>i686</filename> and
68 <filename>x86_64</filename> directories, respectively.
69 The toolchains the Yocto Project provides are based off the
70 <filename>core-image-sato</filename> image and contain
71 libraries appropriate for developing against that image.
72 Each type of development system supports five or more target
73 architectures.
74 </para>
75
76 <para>
77 The names of the tarball installer scripts are such that a
78 string representing the host system appears first in the
79 filename and then is immediately followed by a string
80 representing the target architecture.
81 <literallayout class='monospaced'>
74 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh 82 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh
75 83
76 Where: 84 Where:
@@ -88,57 +96,58 @@
88 Yocto Project: 96 Yocto Project:
89 97
90 &DISTRO;, &DISTRO;+snapshot 98 &DISTRO;, &DISTRO;+snapshot
91 </literallayout> 99 </literallayout>
92 For example, the following toolchain installer is for a 64-bit 100 For example, the following toolchain installer is for a 64-bit
93 development host system and a i586-tuned target architecture 101 development host system and a i586-tuned target architecture
94 based off the SDK for <filename>core-image-sato</filename> and 102 based off the SDK for <filename>core-image-sato</filename> and
95 using the current &DISTRO; snapshot: 103 using the current &DISTRO; snapshot:
96 <literallayout class='monospaced'> 104 <literallayout class='monospaced'>
97 poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh 105 poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
98 </literallayout> 106 </literallayout>
99 <note> 107 <note>
100 As an alternative to downloading an SDK, you can build the toolchain 108 As an alternative to downloading an SDK, you can build the
101 installer. 109 toolchain installer.
102 For information on building the installer, see the 110 For information on building the installer, see the
103 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" 111 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
104 section. 112 section.
105 Another helpful resource for building an installer is the 113 Another helpful resource for building an installer is the
106 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink> 114 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
107 wiki page. 115 wiki page.
108 This wiki page focuses on development when using the Eclipse IDE. 116 This wiki page focuses on development when using the Eclipse
109 </note> 117 IDE.
110 </para> 118 </note>
119 </para>
111 120
112 <para> 121 <para>
113 The SDK and toolchains are self-contained and by default are installed 122 The SDK and toolchains are self-contained and by default are
114 into <filename>/opt/poky</filename>. 123 installed into <filename>/opt/poky</filename>.
115 However, when you run the SDK installer, you can choose an 124 However, when you run the SDK installer, you can choose an
116 installation directory. 125 installation directory.
117 <note> 126 <note>
118 You must change the permissions on the toolchain 127 You must change the permissions on the toolchain
119 installer script so that it is executable: 128 installer script so that it is executable:
120 <literallayout class='monospaced'> 129 <literallayout class='monospaced'>
121 $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh 130 $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
122 </literallayout> 131 </literallayout>
123 </note> 132 </note>
124 </para> 133 </para>
125 134
126 <para> 135 <para>
127 The following command shows how to run the installer given a 136 The following command shows how to run the installer given a
128 toolchain tarball for a 64-bit x86 development host system and 137 toolchain tarball for a 64-bit x86 development host system and
129 a 32-bit x86 target architecture. 138 a 32-bit x86 target architecture.
130 The example assumes the toolchain installer is located in 139 The example assumes the toolchain installer is located in
131 <filename>~/Downloads/</filename>. 140 <filename>~/Downloads/</filename>.
132 <note> 141 <note>
133 If you do not have write permissions for the directory 142 If you do not have write permissions for the directory
134 into which you are installing the SDK, the installer 143 into which you are installing the SDK, the installer
135 notifies you and exits. 144 notifies you and exits.
136 Be sure you have write permissions in the directory and 145 Be sure you have write permissions in the directory and
137 run the installer again. 146 run the installer again.
138 </note> 147 </note>
139 <literallayout class='monospaced'> 148 <literallayout class='monospaced'>
140 $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh 149 $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
141 Poky (Yocto Project Reference Distro) SDK installer version 2.0 150 Poky (Yocto Project Reference Distro) SDK installer version &DISTRO;
142 =============================================================== 151 ===============================================================
143 Enter target directory for SDK (default: /opt/poky/&DISTRO;): 152 Enter target directory for SDK (default: /opt/poky/&DISTRO;):
144 You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed[Y/n]? Y 153 You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed[Y/n]? Y
@@ -147,1337 +156,49 @@
147 SDK has been successfully set up and is ready to be used. 156 SDK has been successfully set up and is ready to be used.
148 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. 157 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
149 $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux 158 $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
150 </literallayout>
151 </para>
152
153 <para>
154 Again, reference the
155 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
156 section for more details on the resulting directory structure of
157 the installed SDK.
158 </para>
159</section>
160
161<section id='sdk-running-the-sdk-environment-setup-script'>
162 <title>Running the SDK Environment Setup Script</title>
163
164 <para>
165 Once you have the SDK installed, you must run the SDK environment
166 setup script before you can actually use it.
167 This setup script resides in the directory you chose when you installed
168 the SDK.
169 For information on where this setup script can reside, see the
170 "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>"
171 Appendix.
172 </para>
173
174 <para>
175 Before running the script, be sure it is the one that matches the
176 architecture for which you are developing.
177 Environment setup scripts begin with the string
178 "<filename>environment-setup</filename>" and include as part of their
179 name the tuned target architecture.
180 For example, the command to source a setup script for an IA-based
181 target machine using i586 tuning and located in the default SDK
182 installation directory is as follows:
183 <literallayout class='monospaced'>
184 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
185 </literallayout>
186 When you run the setup script, many environment variables are
187 defined:
188 <literallayout class='monospaced'>
189 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
190 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
191 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
192 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
193 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
194 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
195 <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
196 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
197 <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
198 <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols
199 <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
200 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
201 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
202 <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
203 <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
204 <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
205 <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools
206 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
207 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
208 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
209 <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
210 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags
211 </literallayout>
212 </para>
213</section>
214
215<section id='autotools-based-projects'>
216 <title>Autotools-Based Projects</title>
217
218 <para>
219 Once you have a suitable cross-toolchain installed, it is very easy to
220 develop a project outside of the OpenEmbedded build system.
221 This section presents a simple "Helloworld" example that shows how
222 to set up, compile, and run the project.
223 </para>
224
225 <section id='creating-and-running-a-project-based-on-gnu-autotools'>
226 <title>Creating and Running a Project Based on GNU Autotools</title>
227
228 <para>
229 Follow these steps to create a simple Autotools-based project:
230 <orderedlist>
231 <listitem><para><emphasis>Create your directory:</emphasis>
232 Create a clean directory for your project and then make
233 that directory your working location:
234 <literallayout class='monospaced'>
235 $ mkdir $HOME/helloworld
236 $ cd $HOME/helloworld
237 </literallayout></para></listitem>
238 <listitem><para><emphasis>Populate the directory:</emphasis>
239 Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
240 and <filename>configure.ac</filename> files as follows:
241 <itemizedlist>
242 <listitem><para>For <filename>hello.c</filename>, include
243 these lines:
244 <literallayout class='monospaced'>
245 #include &lt;stdio.h&gt;
246
247 main()
248 {
249 printf("Hello World!\n");
250 }
251 </literallayout></para></listitem>
252 <listitem><para>For <filename>Makefile.am</filename>,
253 include these lines:
254 <literallayout class='monospaced'>
255 bin_PROGRAMS = hello
256 hello_SOURCES = hello.c
257 </literallayout></para></listitem>
258 <listitem><para>For <filename>configure.in</filename>,
259 include these lines:
260 <literallayout class='monospaced'>
261 AC_INIT(hello,0.1)
262 AM_INIT_AUTOMAKE([foreign])
263 AC_PROG_CC
264 AC_PROG_INSTALL
265 AC_OUTPUT(Makefile)
266 </literallayout></para></listitem>
267 </itemizedlist></para></listitem>
268 <listitem><para><emphasis>Source the cross-toolchain
269 environment setup file:</emphasis>
270 As described earlier in the manual, installing the
271 cross-toolchain creates a cross-toolchain
272 environment setup script in the directory that the SDK
273 was installed.
274 Before you can use the tools to develop your project,
275 you must source this setup script.
276 The script begins with the string "environment-setup" and
277 contains the machine architecture, which is followed by the
278 string "poky-linux".
279 Here is an example that sources a script from the
280 default SDK installation directory that uses the
281 32-bit Intel x86 Architecture and the
282 &DISTRO_NAME; Yocto Project release:
283 <literallayout class='monospaced'>
284 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
285 </literallayout></para></listitem>
286 <listitem><para><emphasis>Generate the local aclocal.m4
287 files and create the configure script:</emphasis>
288 The following GNU Autotools generate the local
289 <filename>aclocal.m4</filename> files and create the
290 configure script:
291 <literallayout class='monospaced'>
292 $ aclocal
293 $ autoconf
294 </literallayout></para></listitem>
295 <listitem><para><emphasis>Generate files needed by GNU
296 coding standards:</emphasis>
297 GNU coding standards require certain files in order for the
298 project to be compliant.
299 This command creates those files:
300 <literallayout class='monospaced'>
301 $ touch NEWS README AUTHORS ChangeLog
302 </literallayout></para></listitem>
303 <listitem><para><emphasis>Generate the configure
304 file:</emphasis>
305 This command generates the <filename>configure</filename>:
306 <literallayout class='monospaced'>
307 $ automake -a
308 </literallayout></para></listitem>
309 <listitem><para><emphasis>Cross-compile the project:</emphasis>
310 This command compiles the project using the cross-compiler.
311 The
312 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
313 environment variable provides the minimal arguments for
314 GNU configure:
315 <literallayout class='monospaced'>
316 $ ./configure ${CONFIGURE_FLAGS}
317 </literallayout></para></listitem>
318 <listitem><para><emphasis>Make and install the project:</emphasis>
319 These two commands generate and install the project into the
320 destination directory:
321 <literallayout class='monospaced'>
322 $ make
323 $ make install DESTDIR=./tmp
324 </literallayout></para></listitem>
325 <listitem><para><emphasis>Verify the installation:</emphasis>
326 This command is a simple way to verify the installation
327 of your project.
328 Running the command prints the architecture on which
329 the binary file can run.
330 This architecture should be the same architecture that
331 the installed cross-toolchain supports.
332 <literallayout class='monospaced'>
333 $ file ./tmp/usr/local/bin/hello
334 </literallayout></para></listitem>
335 <listitem><para><emphasis>Execute your project:</emphasis>
336 To execute the project in the shell, simply enter the name.
337 You could also copy the binary to the actual target hardware
338 and run the project there as well:
339 <literallayout class='monospaced'>
340 $ ./hello
341 </literallayout>
342 As expected, the project displays the "Hello World!" message.
343 </para></listitem>
344 </orderedlist>
345 </para>
346 </section>
347
348 <section id='passing-host-options'>
349 <title>Passing Host Options</title>
350
351 <para>
352 For an Autotools-based project, you can use the cross-toolchain by just
353 passing the appropriate host option to <filename>configure.sh</filename>.
354 The host option you use is derived from the name of the environment setup
355 script found in the directory in which you installed the cross-toolchain.
356 For example, the host option for an ARM-based target that uses the GNU EABI
357 is <filename>armv5te-poky-linux-gnueabi</filename>.
358 You will notice that the name of the script is
359 <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
360 Thus, the following command works to update your project and
361 rebuild it using the appropriate cross-toolchain tools:
362 <literallayout class='monospaced'>
363 $ ./configure --host=armv5te-poky-linux-gnueabi \
364 --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
365 </literallayout> 159 </literallayout>
366 <note>
367 If the <filename>configure</filename> script results in problems recognizing the
368 <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option,
369 regenerate the script to enable the support by doing the following and then
370 run the script again:
371 <literallayout class='monospaced'>
372 $ libtoolize --automake
373 $ aclocal -I ${OECORE_TARGET_SYSROOT}/usr/share/aclocal \
374 [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
375 $ autoconf
376 $ autoheader
377 $ automake -a
378 </literallayout>
379 </note>
380 </para> 160 </para>
381 </section>
382</section>
383
384<section id='makefile-based-projects'>
385 <title>Makefile-Based Projects</title>
386
387 <para>
388 For Makefile-based projects, the cross-toolchain environment variables
389 established by running the cross-toolchain environment setup script
390 are subject to general <filename>make</filename> rules.
391 </para>
392
393 <para>
394 To illustrate this, consider the following four cross-toolchain
395 environment variables:
396 <literallayout class='monospaced'>
397 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
398 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
399 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
400 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
401 </literallayout>
402 Now, consider the following three cases:
403 <itemizedlist>
404 <listitem><para><emphasis>Case 1 - No Variables Set in the <filename>Makefile</filename>:</emphasis>
405 Because these variables are not specifically set in the
406 <filename>Makefile</filename>, the variables retain their
407 values based on the environment.
408 </para></listitem>
409 <listitem><para><emphasis>Case 2 - Variables Set in the <filename>Makefile</filename>:</emphasis>
410 Specifically setting variables in the
411 <filename>Makefile</filename> during the build results in the
412 environment settings of the variables being overwritten.
413 </para></listitem>
414 <listitem><para><emphasis>Case 3 - Variables Set when the <filename>Makefile</filename> is Executed from the Command Line:</emphasis>
415 Executing the <filename>Makefile</filename> from the command
416 line results in the variables being overwritten with
417 command-line content regardless of what is being set in the
418 <filename>Makefile</filename>.
419 In this case, environment variables are not considered unless
420 you use the "-e" flag during the build:
421 <literallayout class='monospaced'>
422 $ make -e <replaceable>file</replaceable>
423 </literallayout>
424 If you use this flag, then the environment values of the
425 variables override any variables specifically set in the
426 <filename>Makefile</filename>.
427 </para></listitem>
428 </itemizedlist>
429 <note>
430 For the list of variables set up by the cross-toolchain environment
431 setup script, see the
432 "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
433 section.
434 </note>
435 </para>
436</section>
437
438<section id='sdk-developing-applications-using-eclipse'>
439 <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title>
440
441 <para>
442 If you are familiar with the popular Eclipse IDE, you can use an
443 Eclipse Yocto Plug-in to allow you to develop, deploy, and test your
444 application all from within Eclipse.
445 This section describes general workflow using the SDK and Eclipse
446 and how to configure and set up Eclipse.
447 </para>
448
449 <section id='workflow-using-eclipse'>
450
451 <title>Workflow Using <trademark class='trade'>Eclipse</trademark></title>
452 161
453 <para> 162 <para>
454 The following figure and supporting list summarize the application 163 Again, reference the
455 development general workflow that employs both the SDK Eclipse. 164 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
456 </para> 165 section for more details on the resulting directory structure of
457 166 the installed SDK.
458 <para>
459 <imagedata fileref="figures/sdk-eclipse-dev-flow.png"
460 width="7in" depth="7in" align="center" scale="100" />
461 </para>
462
463 <para>
464 <orderedlist>
465 <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>:
466 See
467 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
468 and
469 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both
470 in the Yocto Project Reference Manual for requirements.
471 In particular, be sure your host system has the
472 <filename>xterm</filename> package installed.
473 </para></listitem>
474 <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>:
475 You must have a target kernel image that has been built using the OpenEmbedded
476 build system.</para>
477 <para>Depending on whether the Yocto Project has a pre-built image that matches your target
478 architecture and where you are going to run the image while you develop your application
479 (QEMU or real hardware), the area from which you get the image differs.
480 <itemizedlist>
481 <listitem><para>Download the image from
482 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
483 if your target architecture is supported and you are going to develop
484 and test your application on actual hardware.</para></listitem>
485 <listitem><para>Download the image from
486 <ulink url='&YOCTO_QEMU_DL_URL;'>
487 <filename>machines/qemu</filename></ulink> if your target architecture is supported
488 and you are going to develop and test your application using the QEMU
489 emulator.</para></listitem>
490 <listitem><para>Build your image if you cannot find a pre-built image that matches
491 your target architecture.
492 If your target architecture is similar to a supported architecture, you can
493 modify the kernel image before you build it.
494 See the
495 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
496 section in the Yocto Project Development
497 manual for an example.
498 </para></listitem>
499 </itemizedlist>
500 </para></listitem>
501 <listitem><para><emphasis>Install the SDK</emphasis>:
502 The SDK provides a target-specific cross-development toolchain, the root filesystem,
503 the QEMU emulator, and other tools that can help you develop your application.
504 For information on how to install the SDK, see the
505 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
506 section.
507 </para></listitem>
508 <listitem><para><emphasis>
509 Secure the target root filesystem
510 and the Cross-development toolchain</emphasis>:
511 You need to find and download the appropriate root
512 filesystem and the cross-development toolchain.</para>
513 <para>You can find the tarballs for the root filesystem in
514 the same area used for the kernel image.
515 Depending on the type of image you are running, the root
516 filesystem you need differs.
517 For example, if you are developing an application that
518 runs on an image that supports Sato, you need to get a
519 root filesystem that supports Sato.</para>
520 <para>You can find the cross-development toolchains at
521 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
522 Be sure to get the correct toolchain for your development host and your
523 target architecture.
524 See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>"
525 section for information and the
526 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
527 section for installation information.
528 <note>
529 As an alternative to downloading an SDK, you can build
530 the toolchain installer.
531 For information on building the installer, see the
532 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
533 section.
534 Another helpful resource for building an installer is
535 the
536 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
537 wiki page.
538 </note>
539 </para></listitem>
540 <listitem><para><emphasis>Create and build your application</emphasis>:
541 At this point, you need to have source files for your application.
542 Once you have the files, you can use the Eclipse IDE to import them and build the
543 project.
544 If you are not using Eclipse, you need to use the cross-development tools you have
545 installed to create the image.</para></listitem>
546 <listitem><para>
547 <emphasis>Deploy the image with the application</emphasis>:
548 Using the Eclipse IDE, you can deploy your image to the
549 hardware or to QEMU through the project's preferences.
550 You can also use Eclipse to load and test your image under
551 QEMU.
552 See the
553 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
554 chapter in the Yocto Project Development Manual
555 for information on using QEMU.
556 </para></listitem>
557 <listitem><para><emphasis>Test and debug the application</emphasis>:
558 Once your application is deployed, you need to test it.
559 Within the Eclipse IDE, you can use the debugging
560 environment along with supported performance enhancing
561 <ulink url='http://www.eclipse.org/linuxtools/'>Linux Tools</ulink>.
562 </para></listitem>
563 </orderedlist>
564 </para> 167 </para>
565 </section> 168 </section>
566 169
567 <section id='adt-eclipse'> 170 <section id='sdk-running-the-sdk-environment-setup-script'>
568 <title>Working Within Eclipse</title> 171 <title>Running the SDK Environment Setup Script</title>
569 172
570 <para> 173 <para>
571 The Eclipse IDE is a popular development environment and it fully 174 Once you have the SDK installed, you must run the SDK environment
572 supports development using the Yocto Project. 175 setup script before you can actually use it.
176 This setup script resides in the directory you chose when you
177 installed the SDK.
178 For information on where this setup script can reside, see the
179 "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>"
180 Appendix.
573 </para> 181 </para>
574 182
575 <para> 183 <para>
576 When you install and configure the Eclipse Yocto Project Plug-in 184 Before running the script, be sure it is the one that matches the
577 into the Eclipse IDE, you maximize your Yocto Project experience. 185 architecture for which you are developing.
578 Installing and configuring the Plug-in results in an environment 186 Environment setup scripts begin with the string
579 that has extensions specifically designed to let you more easily 187 "<filename>environment-setup</filename>" and include as part of
580 develop software. 188 their name the tuned target architecture.
581 These extensions allow for cross-compilation, deployment, and 189 For example, the command to source a setup script for an IA-based
582 execution of your output into a QEMU emulation session as well as 190 target machine using i586 tuning and located in the default SDK
583 actual target hardware. 191 installation directory is as follows:
584 You can also perform cross-debugging and profiling. 192 <literallayout class='monospaced'>
585 The environment also supports performance enhancing 193 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
586 <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink> that 194 </literallayout>
587 allow you to perform remote profiling, tracing, collection of 195 When you run the setup script, the same environment variables are
588 power data, collection of latency data, and collection of 196 defined as are when you run the setup script for an extensible SDK.
589 performance data. 197 See the
590 <note> 198 "<link linkend='sdk-running-the-extensible-sdk-environment-setup-script'>Running the Extensible SDK Environment Setup Script</link>"
591 This release of the Yocto Project supports both the Neon 199 section for more information.
592 and Mars versions of the Eclipse IDE.
593 This section provides information on how to use the Neon
594 release with the Yocto Project.
595 For information on how to use the Mars version of Eclipse
596 with the Yocto Project, see
597 "<link linkend='sdk-appendix-mars'>Appendix C</link>.
598 </note>
599 </para> 200 </para>
600
601 <section id='neon-setting-up-the-eclipse-ide'>
602 <title>Setting Up the Neon Version of the Eclipse IDE</title>
603
604 <para>
605 To develop within the Eclipse IDE, you need to do the following:
606 <orderedlist>
607 <listitem><para>Install the Neon version of the Eclipse
608 IDE.</para></listitem>
609 <listitem><para>Configure the Eclipse IDE.
610 </para></listitem>
611 <listitem><para>Install the Eclipse Yocto Plug-in.
612 </para></listitem>
613 <listitem><para>Configure the Eclipse Yocto Plug-in.
614 </para></listitem>
615 </orderedlist>
616 <note>
617 Do not install Eclipse from your distribution's package
618 repository.
619 Be sure to install Eclipse from the official Eclipse
620 download site as directed in the next section.
621 </note>
622 </para>
623
624 <section id='neon-installing-eclipse-ide'>
625 <title>Installing the Neon Eclipse IDE</title>
626
627 <para>
628 Follow these steps to locate, install, and configure
629 Neon Eclipse:
630 <orderedlist>
631 <listitem><para>
632 <emphasis>Locate the Neon Download:</emphasis>
633 Open a browser and go to
634 <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/neon/</ulink>.
635 </para></listitem>
636 <listitem><para>
637 <emphasis>Download the Tarball:</emphasis>
638 Click through the "Download" buttons to
639 download the file.
640 </para></listitem>
641 <listitem><para>
642 <emphasis>Unpack the Tarball:</emphasis>
643 Move to a clean directory and unpack the tarball.
644 Here is an example:
645 <literallayout class='monospaced'>
646 $ cd ~
647 $ tar -xzvf ~/Downloads/eclipse-inst-linux64.tar.gz
648 </literallayout>
649 Everything unpacks into a folder named
650 "eclipse-installer".
651 </para></listitem>
652 <listitem><para>
653 <emphasis>Launch the Installer:</emphasis>
654 Use the following commands to launch the installer:
655 <literallayout class='monospaced'>
656 $ cd ~/eclipse-installer
657 $ ./eclipse-inst
658 </literallayout>
659 </para></listitem>
660 <listitem><para>
661 <emphasis>Select Your IDE:</emphasis>
662 From the list, select the "Eclipse IDE for
663 C/C++ Developers".
664 </para></listitem>
665 <listitem><para>
666 <emphasis>Install the Software:</emphasis>
667 Accept the default "cpp-neon" directory and click
668 "Install".
669 Accept any license agreements and approve any
670 certificates.
671 </para></listitem>
672 <listitem><para>
673 <emphasis>Launch Neon:</emphasis>
674 Click the "Launch" button and accept the default
675 "workspace".
676 </para></listitem>
677 </orderedlist>
678 </para>
679 </section>
680
681 <section id='neon-configuring-the-mars-eclipse-ide'>
682 <title>Configuring the Neon Eclipse IDE</title>
683
684 <para>
685 Follow these steps to configure the Neon Eclipse IDE.
686 <note>
687 Depending on how you installed Eclipse and what you have
688 already done, some of the options will not appear.
689 If you cannot find an option as directed by the manual,
690 it has already been installed.
691 </note>
692 <orderedlist>
693 <listitem><para>Be sure Eclipse is running and
694 you are in your workbench.
695 </para></listitem>
696 <listitem><para>Select "Install New Software" from
697 the "Help" pull-down menu.
698 </para></listitem>
699 <listitem><para>Select
700 "Neon - http://download.eclipse.org/releases/neon"
701 from the "Work with:" pull-down menu.
702 </para></listitem>
703 <listitem><para>Expand the box next to
704 "Linux Tools" and select the following:
705 <literallayout class='monospaced'>
706 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
707 TM Terminal
708 </literallayout>
709 </para></listitem>
710 <listitem><para>Expand the box next to "Mobile and
711 Device Development" and select the following
712 boxes:
713 <literallayout class='monospaced'>
714 C/C++ Remote (Over TCF/TE) Run/Debug Launcher
715 Remote System Explorer User Actions
716 TM Terminal
717 TCF Remote System Explorer add-in
718 TCF Target Explorer
719 </literallayout>
720 </para></listitem>
721 <listitem><para>Expand the box next to
722 "Programming Languages" and select the
723 following box:
724 <literallayout class='monospaced'>
725 C/C++ Development Tools SDK
726 </literallayout>
727 </para></listitem>
728 <listitem><para>
729 Complete the installation by clicking through
730 appropriate "Next" and "Finish" buttons.
731 </para></listitem>
732 </orderedlist>
733 </para>
734 </section>
735
736 <section id='neon-installing-the-eclipse-yocto-plug-in'>
737 <title>Installing or Accessing the Neon Eclipse Yocto Plug-in</title>
738
739 <para>
740 You can install the Eclipse Yocto Plug-in into the Eclipse
741 IDE one of two ways: use the Yocto Project's Eclipse
742 Update site to install the pre-built plug-in or build and
743 install the plug-in from the latest source code.
744 </para>
745
746 <section id='neon-new-software'>
747 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
748
749 <para>
750 To install the Neon Eclipse Yocto Plug-in from the
751 update site, follow these steps:
752 <orderedlist>
753 <listitem><para>Start up the Eclipse IDE.
754 </para></listitem>
755 <listitem><para>In Eclipse, select "Install New
756 Software" from the "Help" menu.
757 </para></listitem>
758 <listitem><para>Click "Add..." in the "Work with:"
759 area.
760 </para></listitem>
761 <listitem><para>Enter
762 <filename>&ECLIPSE_DL_PLUGIN_URL;/neon</filename>
763 in the URL field and provide a meaningful name
764 in the "Name" field.
765 </para></listitem>
766 <listitem><para>Click "OK" to have the entry added
767 to the "Work with:" drop-down list.
768 </para></listitem>
769 <listitem><para>Select the entry for the plug-in
770 from the "Work with:" drop-down list.
771 </para></listitem>
772 <listitem><para>Check the boxes next to the following:
773 <literallayout class='monospaced'>
774 Yocto Project SDK Plug-in
775 Yocto Project Documentation plug-in
776 </literallayout>
777 </para></listitem>
778 <listitem><para>Complete the remaining software
779 installation steps and then restart the Eclipse
780 IDE to finish the installation of the plug-in.
781 <note>
782 You can click "OK" when prompted about
783 installing software that contains unsigned
784 content.
785 </note>
786 </para></listitem>
787 </orderedlist>
788 </para>
789 </section>
790
791 <section id='neon-zip-file-method'>
792 <title>Installing the Plug-in Using the Latest Source Code</title>
793
794 <para>
795 To install the Neon Eclipse Yocto Plug-in from the
796 latest source code, follow these steps:
797 <orderedlist>
798 <listitem><para>Be sure your development system
799 has JDK 1.8+
800 </para></listitem>
801 <listitem><para>install X11-related packages:
802 <literallayout class='monospaced'>
803 $ sudo apt-get install xauth
804 </literallayout>
805 </para></listitem>
806 <listitem><para>In a new terminal shell, create a
807 Git repository with:
808 <literallayout class='monospaced'>
809 $ cd ~
810 $ git clone git://git.yoctoproject.org/eclipse-poky
811 </literallayout>
812 </para></listitem>
813 <listitem><para>Use Git to create the correct
814 tag:
815 <literallayout class='monospaced'>
816 $ cd ~/eclipse-poky
817 $ git checkout neon/yocto-&DISTRO;
818 </literallayout>
819 This creates a local tag named
820 <filename>neon/yocto-&DISTRO;</filename>
821 based on the branch
822 <filename>origin/neon-master</filename>.
823 You are put into a detached HEAD state, which
824 is fine since you are only going to be building
825 and not developing.
826 </para></listitem>
827 <listitem><para>Change to the
828 <filename>scripts</filename>
829 directory within the Git repository:
830 <literallayout class='monospaced'>
831 $ cd scripts
832 </literallayout>
833 </para></listitem>
834 <listitem><para>Set up the local build environment
835 by running the setup script:
836 <literallayout class='monospaced'>
837 $ ./setup.sh
838 </literallayout>
839 When the script finishes execution,
840 it prompts you with instructions on how to run
841 the <filename>build.sh</filename> script, which
842 is also in the <filename>scripts</filename>
843 directory of the Git repository created
844 earlier.
845 </para></listitem>
846 <listitem><para>
847 Run the <filename>build.sh</filename>
848 script as directed.
849 Be sure to provide the tag name, documentation
850 branch, and a release name.</para>
851 <para>
852 Following is an example:
853 <literallayout class='monospaced'>
854 $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l neon/yocto-&DISTRO; master yocto-&DISTRO; 2>&amp;1 | tee build.log
855 </literallayout>
856 The previous example command adds the tag you
857 need for
858 <filename>mars/yocto-&DISTRO;</filename>
859 to <filename>HEAD</filename>, then tells the
860 build script to use the local (-l) Git checkout
861 for the build.
862 After running the script, the file
863 <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>
864 is in the current directory.
865 </para></listitem>
866 <listitem><para>If necessary, start the Eclipse IDE
867 and be sure you are in the Workbench.
868 </para></listitem>
869 <listitem><para>Select "Install New Software" from
870 the "Help" pull-down menu.
871 </para></listitem>
872 <listitem><para>Click "Add".
873 </para></listitem>
874 <listitem><para>Provide anything you want in the
875 "Name" field.
876 </para></listitem>
877 <listitem><para>Click "Archive" and browse to the
878 ZIP file you built earlier.
879 This ZIP file should not be "unzipped", and must
880 be the <filename>*archive.zip</filename> file
881 created by running the
882 <filename>build.sh</filename> script.
883 </para></listitem>
884 <listitem><para>Click the "OK" button.
885 </para></listitem>
886 <listitem><para>Check the boxes that appear in
887 the installation window to install the
888 following:
889 <literallayout class='monospaced'>
890 Yocto Project SDK Plug-in
891 Yocto Project Documentation plug-in
892 </literallayout>
893 </para></listitem>
894 <listitem><para>Finish the installation by clicking
895 through the appropriate buttons.
896 You can click "OK" when prompted about
897 installing software that contains unsigned
898 content.
899 </para></listitem>
900 <listitem><para>Restart the Eclipse IDE if
901 necessary.
902 </para></listitem>
903 </orderedlist>
904 </para>
905
906 <para>
907 At this point you should be able to configure the
908 Eclipse Yocto Plug-in as described in the
909 "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"
910 section.
911 </para>
912 </section>
913 </section>
914
915 <section id='neon-configuring-the-eclipse-yocto-plug-in'>
916 <title>Configuring the Neon Eclipse Yocto Plug-in</title>
917
918 <para>
919 Configuring the Neon Eclipse Yocto Plug-in involves
920 setting the Cross Compiler options and the Target options.
921 The configurations you choose become the default settings
922 for all projects.
923 You do have opportunities to change them later when
924 you configure the project (see the following section).
925 </para>
926
927 <para>
928 To start, you need to do the following from within the
929 Eclipse IDE:
930 <itemizedlist>
931 <listitem><para>Choose "Preferences" from the
932 "Window" menu to display the Preferences Dialog.
933 </para></listitem>
934 <listitem><para>Click "Yocto Project SDK" to display
935 the configuration screen.
936 </para></listitem>
937 </itemizedlist>
938 The following sub-sections describe how to configure the
939 the plug-in.
940 <note>
941 Throughout the descriptions, a start-to-finish example for
942 preparing a QEMU image for use with Eclipse is referenced
943 as the "wiki" and is linked to the example on the
944 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
945 wiki page.
946 </note>
947 </para>
948
949 <section id='neon-configuring-the-cross-compiler-options'>
950 <title>Configuring the Cross-Compiler Options</title>
951
952 <para>
953 Cross Compiler options enable Eclipse to use your specific
954 cross compiler toolchain.
955 To configure these options, you must select
956 the type of toolchain, point to the toolchain, specify
957 the sysroot location, and select the target
958 architecture.
959 <itemizedlist>
960 <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
961 Choose between
962 <filename>Standalone pre-built toolchain</filename>
963 and
964 <filename>Build system derived toolchain</filename>
965 for Cross Compiler Options.
966 <itemizedlist>
967 <listitem><para><emphasis>
968 <filename>Standalone Pre-built Toolchain:</filename></emphasis>
969 Select this type when you are using
970 a stand-alone cross-toolchain.
971 For example, suppose you are an
972 application developer and do not
973 need to build a target image.
974 Instead, you just want to use an
975 architecture-specific toolchain on
976 an existing kernel and target root
977 filesystem.
978 In other words, you have downloaded
979 and installed a pre-built toolchain
980 for an existing image.
981 </para></listitem>
982 <listitem><para><emphasis>
983 <filename>Build System Derived Toolchain:</filename></emphasis>
984 Select this type if you built the
985 toolchain as part of the
986 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
987 When you select
988 <filename>Build system derived toolchain</filename>,
989 you are using the toolchain built and
990 bundled inside the Build Directory.
991 For example, suppose you created a
992 suitable image using the steps in the
993 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
994 In this situation, you would select the
995 <filename>Build system derived toolchain</filename>.
996 </para></listitem>
997 </itemizedlist>
998 </para></listitem>
999 <listitem><para><emphasis>Specify the Toolchain Root Location:</emphasis>
1000 If you are using a stand-alone pre-built
1001 toolchain, you should be pointing to where it is
1002 installed (e.g.
1003 <filename>/opt/poky/&DISTRO;</filename>).
1004 See the
1005 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
1006 section for information about how the SDK is
1007 installed.</para>
1008 <para>If you are using a build system derived
1009 toolchain, the path you provide for the
1010 <filename>Toolchain Root Location</filename>
1011 field is the
1012 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1013 from which you run the
1014 <filename>bitbake</filename> command (e.g
1015 <filename>/home/scottrif/poky/build</filename>).</para>
1016 <para>For more information, see the
1017 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
1018 section.
1019 </para></listitem>
1020 <listitem><para><emphasis>Specify Sysroot Location:</emphasis>
1021 This location is where the root filesystem for
1022 the target hardware resides.
1023 </para>
1024 <para>This location depends on where you
1025 separately extracted and installed the target
1026 filesystem.
1027 As an example, suppose you prepared an image
1028 using the steps in the
1029 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
1030 If so, the <filename>MY_QEMU_ROOTFS</filename>
1031 directory is found in the
1032 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1033 and you would browse to and select that directory
1034 (e.g. <filename>/home/scottrif/poky/build/MY_QEMU_ROOTFS</filename>).
1035 </para>
1036 <para>For more information on how to install the
1037 toolchain and on how to extract and install the
1038 sysroot filesystem, see the
1039 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
1040 section.
1041 </para></listitem>
1042 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
1043 The target architecture is the type of hardware
1044 you are going to use or emulate.
1045 Use the pull-down
1046 <filename>Target Architecture</filename> menu
1047 to make your selection.
1048 The pull-down menu should have the supported
1049 architectures.
1050 If the architecture you need is not listed in
1051 the menu, you will need to build the image.
1052 See the
1053 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
1054 section of the Yocto Project Quick Start for
1055 more information.
1056 You can also see the
1057 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
1058 </para></listitem>
1059 </itemizedlist>
1060 </para>
1061 </section>
1062
1063 <section id='neon-configuring-the-target-options'>
1064 <title>Configuring the Target Options</title>
1065
1066 <para>
1067 You can choose to emulate hardware using the QEMU
1068 emulator, or you can choose to run your image on actual
1069 hardware.
1070 <itemizedlist>
1071 <listitem><para><emphasis>QEMU:</emphasis>
1072 Select this option if you will be using the
1073 QEMU emulator.
1074 If you are using the emulator, you also need to
1075 locate the kernel and specify any custom
1076 options.</para>
1077 <para>If you selected the
1078 <filename>Build system derived toolchain</filename>,
1079 the target kernel you built will be located in
1080 the
1081 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1082 in
1083 <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
1084 directory.
1085 As an example, suppose you performed the steps in
1086 the
1087 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
1088 In this case, you specify your Build Directory path
1089 followed by the image (e.g.
1090 <filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).
1091 </para>
1092 <para>If you selected the standalone pre-built
1093 toolchain, the pre-built image you downloaded is
1094 located in the directory you specified when you
1095 downloaded the image.</para>
1096 <para>Most custom options are for advanced QEMU
1097 users to further customize their QEMU instance.
1098 These options are specified between paired
1099 angled brackets.
1100 Some options must be specified outside the
1101 brackets.
1102 In particular, the options
1103 <filename>serial</filename>,
1104 <filename>nographic</filename>, and
1105 <filename>kvm</filename> must all be outside the
1106 brackets.
1107 Use the <filename>man qemu</filename> command
1108 to get help on all the options and their use.
1109 The following is an example:
1110 <literallayout class='monospaced'>
1111 serial ‘&lt;-m 256 -full-screen&gt;’
1112 </literallayout></para>
1113 <para>
1114 Regardless of the mode, Sysroot is already
1115 defined as part of the Cross-Compiler Options
1116 configuration in the
1117 <filename>Sysroot Location:</filename> field.
1118 </para></listitem>
1119 <listitem><para><emphasis>External HW:</emphasis>
1120 Select this option if you will be using actual
1121 hardware.</para></listitem>
1122 </itemizedlist>
1123 </para>
1124
1125 <para>
1126 Click the "Apply" and "OK" to save your plug-in
1127 configurations.
1128 </para>
1129 </section>
1130 </section>
1131 </section>
1132
1133 <section id='neon-creating-the-project'>
1134 <title>Creating the Project</title>
1135
1136 <para>
1137 You can create two types of projects: Autotools-based, or
1138 Makefile-based.
1139 This section describes how to create Autotools-based projects
1140 from within the Eclipse IDE.
1141 For information on creating Makefile-based projects in a
1142 terminal window, see the
1143 "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
1144 section.
1145 <note>
1146 Do not use special characters in project names
1147 (e.g. spaces, underscores, etc.). Doing so can
1148 cause configuration to fail.
1149 </note>
1150 </para>
1151
1152 <para>
1153 To create a project based on a Yocto template and then display
1154 the source code, follow these steps:
1155 <orderedlist>
1156 <listitem><para>Select "C Project" from the "File -> New" menu.
1157 </para></listitem>
1158 <listitem><para>Expand <filename>Yocto Project SDK Autotools Project</filename>.
1159 </para></listitem>
1160 <listitem><para>Select <filename>Hello World ANSI C Autotools Projects</filename>.
1161 This is an Autotools-based project based on a Yocto
1162 template.
1163 </para></listitem>
1164 <listitem><para>Put a name in the <filename>Project name:</filename>
1165 field.
1166 Do not use hyphens as part of the name
1167 (e.g. <filename>hello</filename>).
1168 </para></listitem>
1169 <listitem><para>Click "Next".
1170 </para></listitem>
1171 <listitem><para>Add appropriate information in the various
1172 fields.
1173 </para></listitem>
1174 <listitem><para>Click "Finish".
1175 </para></listitem>
1176 <listitem><para>If the "open perspective" prompt appears,
1177 click "Yes" so that you in the C/C++ perspective.
1178 </para></listitem>
1179 <listitem><para>The left-hand navigation pane shows your
1180 project.
1181 You can display your source by double clicking the
1182 project's source file.
1183 </para></listitem>
1184 </orderedlist>
1185 </para>
1186 </section>
1187
1188 <section id='neon-configuring-the-cross-toolchains'>
1189 <title>Configuring the Cross-Toolchains</title>
1190
1191 <para>
1192 The earlier section,
1193 "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>",
1194 sets up the default project configurations.
1195 You can override these settings for a given project by following
1196 these steps:
1197 <orderedlist>
1198 <listitem><para>Select "Yocto Project Settings" from
1199 the "Project -> Properties" menu.
1200 This selection brings up the Yocto Project Settings
1201 Dialog and allows you to make changes specific to an
1202 individual project.</para>
1203 <para>By default, the Cross Compiler Options and Target
1204 Options for a project are inherited from settings you
1205 provided using the Preferences Dialog as described
1206 earlier in the
1207 "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" section.
1208 The Yocto Project Settings Dialog allows you to override
1209 those default settings for a given project.
1210 </para></listitem>
1211 <listitem><para>Make or verify your configurations for the
1212 project and click "OK".
1213 </para></listitem>
1214 <listitem><para>Right-click in the navigation pane and
1215 select "Reconfigure Project" from the pop-up menu.
1216 This selection reconfigures the project by running
1217 <filename>autogen.sh</filename> in the workspace for
1218 your project.
1219 The script also runs <filename>libtoolize</filename>,
1220 <filename>aclocal</filename>,
1221 <filename>autoconf</filename>,
1222 <filename>autoheader</filename>,
1223 <filename>automake --a</filename>, and
1224 <filename>./configure</filename>.
1225 Click on the "Console" tab beneath your source code to
1226 see the results of reconfiguring your project.
1227 </para></listitem>
1228 </orderedlist>
1229 </para>
1230 </section>
1231
1232 <section id='neon-building-the-project'>
1233 <title>Building the Project</title>
1234
1235 <para>
1236 To build the project select "Build All" from the
1237 "Project" menu.
1238 The console should update and you can note the cross-compiler
1239 you are using.
1240 <note>
1241 When building "Yocto Project SDK Autotools" projects, the
1242 Eclipse IDE might display error messages for
1243 Functions/Symbols/Types that cannot be "resolved", even when
1244 the related include file is listed at the project navigator and
1245 when the project is able to build.
1246 For these cases only, it is recommended to add a new linked
1247 folder to the appropriate sysroot.
1248 Use these steps to add the linked folder:
1249 <orderedlist>
1250 <listitem><para>
1251 Select the project.
1252 </para></listitem>
1253 <listitem><para>
1254 Select "Folder" from the
1255 <filename>File > New</filename> menu.
1256 </para></listitem>
1257 <listitem><para>
1258 In the "New Folder" Dialog, select "Link to alternate
1259 location (linked folder)".
1260 </para></listitem>
1261 <listitem><para>
1262 Click "Browse" to navigate to the include folder inside
1263 the same sysroot location selected in the Yocto Project
1264 configuration preferences.
1265 </para></listitem>
1266 <listitem><para>
1267 Click "OK".
1268 </para></listitem>
1269 <listitem><para>
1270 Click "Finish" to save the linked folder.
1271 </para></listitem>
1272 </orderedlist>
1273 </note>
1274 </para>
1275 </section>
1276
1277 <section id='neon-starting-qemu-in-user-space-nfs-mode'>
1278 <title>Starting QEMU in User-Space NFS Mode</title>
1279
1280 <para>
1281 To start the QEMU emulator from within Eclipse, follow these
1282 steps:
1283 <note>
1284 See the
1285 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
1286 chapter in the Yocto Project Development Manual
1287 for more information on using QEMU.
1288 </note>
1289 <orderedlist>
1290 <listitem><para>Expose and select "External Tools
1291 Configurations ..." from the "Run -> External Tools" menu.
1292 </para></listitem>
1293 <listitem><para>
1294 Locate and select your image in the navigation panel to
1295 the left (e.g. <filename>qemu_i586-poky-linux</filename>).
1296 </para></listitem>
1297 <listitem><para>
1298 Click "Run" to launch QEMU.
1299 <note>
1300 The host on which you are running QEMU must have
1301 the <filename>rpcbind</filename> utility running to be
1302 able to make RPC calls on a server on that machine.
1303 If QEMU does not invoke and you receive error messages
1304 involving <filename>rpcbind</filename>, follow the
1305 suggestions to get the service running.
1306 As an example, on a new Ubuntu 16.04 LTS installation,
1307 you must do the following in order to get QEMU to
1308 launch:
1309 <literallayout class='monospaced'>
1310 $ sudo apt-get install rpcbind
1311 </literallayout>
1312 After installing <filename>rpcbind</filename>, you
1313 need to edit the
1314 <filename>/etc/init.d/rpcbind</filename> file to
1315 include the following line:
1316 <literallayout class='monospaced'>
1317 OPTIONS="-i -w"
1318 </literallayout>
1319 After modifying the file, you need to start the
1320 service:
1321 <literallayout class='monospaced'>
1322 $ sudo service portmap restart
1323 </literallayout>
1324 </note>
1325 </para></listitem>
1326 <listitem><para>If needed, enter your host root password in
1327 the shell window at the prompt.
1328 This sets up a <filename>Tap 0</filename> connection
1329 needed for running in user-space NFS mode.
1330 </para></listitem>
1331 <listitem><para>Wait for QEMU to launch.
1332 </para></listitem>
1333 <listitem><para>Once QEMU launches, you can begin operating
1334 within that environment.
1335 One useful task at this point would be to determine the
1336 IP Address for the user-space NFS by using the
1337 <filename>ifconfig</filename> command.
1338 The IP address of the QEMU machine appears in the
1339 xterm window.
1340 You can use this address to help you see which particular
1341 IP address the instance of QEMU is using.
1342 </para></listitem>
1343 </orderedlist>
1344 </para>
1345 </section>
1346
1347 <section id='neon-deploying-and-debugging-the-application'>
1348 <title>Deploying and Debugging the Application</title>
1349
1350 <para>
1351 Once the QEMU emulator is running the image, you can deploy
1352 your application using the Eclipse IDE and then use
1353 the emulator to perform debugging.
1354 Follow these steps to deploy the application.
1355 <note>
1356 Currently, Eclipse does not support SSH port forwarding.
1357 Consequently, if you need to run or debug a remote
1358 application using the host display, you must create a
1359 tunneling connection from outside Eclipse and keep
1360 that connection alive during your work.
1361 For example, in a new terminal, run the following:
1362 <literallayout class='monospaced'>
1363 $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>
1364 </literallayout>
1365 Using the above form, here is an example:
1366 <literallayout class='monospaced'>
1367 $ ssh -XY root@192.168.7.2
1368 </literallayout>
1369 After running the command, add the command to be executed
1370 in Eclipse's run configuration before the application
1371 as follows:
1372 <literallayout class='monospaced'>
1373 export DISPLAY=:10.0
1374 </literallayout>
1375 Be sure to not destroy the connection during your QEMU
1376 session (i.e. do not
1377 exit out of or close that shell).
1378 </note>
1379 <orderedlist>
1380 <listitem><para>Select "Debug Configurations..." from the
1381 "Run" menu.</para></listitem>
1382 <listitem><para>In the left area, expand
1383 <filename>C/C++Remote Application</filename>.
1384 </para></listitem>
1385 <listitem><para>Locate your project and select it to bring
1386 up a new tabbed view in the Debug Configurations Dialog.
1387 </para></listitem>
1388 <listitem><para>Click on the "Debugger" tab to see the
1389 cross-tool debugger you are using.
1390 Be sure to change to the debugger perspective in Eclipse.
1391 </para></listitem>
1392 <listitem><para>Click on the "Main" tab.
1393 </para></listitem>
1394 <listitem><para>Create a new connection to the QEMU instance
1395 by clicking on "new".</para></listitem>
1396 <listitem><para>Select <filename>SSH</filename>, which means
1397 Secure Socket Shell and then click "OK".
1398 Optionally, you can select an TCF connection instead.
1399 </para></listitem>
1400 <listitem><para>Clear out the "Connection name" field and
1401 enter any name you want for the connection.
1402 </para></listitem>
1403 <listitem><para>Put the IP address for the connection in
1404 the "Host" field.
1405 For QEMU, the default is <filename>192.168.7.2</filename>.
1406 However, if a previous QEMU session did not exit
1407 cleanly, the IP address increments (e.g.
1408 <filename>192.168.7.3</filename>).
1409 <note>
1410 You can find the IP address for the current QEMU
1411 session by looking in the xterm that opens when
1412 you launch QEMU.
1413 </note>
1414 </para></listitem>
1415 <listitem><para>Enter <filename>root</filename>, which
1416 is the default for QEMU, for the "User" field.
1417 Be sure to leave the password field empty.
1418 </para></listitem>
1419 <listitem><para>Click "Finish" to close the
1420 New Connections Dialog.
1421 </para></listitem>
1422 <listitem><para>If necessary, use the drop-down menu now in the
1423 "Connection" field and pick the IP Address you entered.
1424 </para></listitem>
1425 <listitem><para>Assuming you are connecting as the root
1426 user, which is the default for QEMU x86-64 SDK images
1427 provided by the Yocto Project, in the "Remote Absolute
1428 File Path for C/C++ Application" field, browse to
1429 <filename>/home/root/</filename><replaceable>ProjectName</replaceable>
1430 (e.g. <filename>/home/root/hello</filename>).
1431 You could also browse to any other path you have write
1432 access to on the target such as
1433 <filename>/usr/bin</filename>.
1434 This location is where your application will be located
1435 on the QEMU system.
1436 If you fail to browse to and specify an appropriate
1437 location, QEMU will not understand what to remotely
1438 launch.
1439 Eclipse is helpful in that it auto fills your
1440 application name for you assuming you browsed to a
1441 directory.
1442 <note>
1443 If you are prompted to provide a username and to
1444 optionally set a password, be sure you provide
1445 "root" as the username and you leave the password
1446 field blank.
1447 </note>
1448 </para></listitem>
1449 <listitem><para>
1450 Be sure you change to the "Debug" perspective in
1451 Eclipse.
1452 </para></listitem>
1453 <listitem><para>Click "Debug"
1454 </para></listitem>
1455 <listitem><para>Accept the debug perspective.
1456 </para></listitem>
1457 </orderedlist>
1458 </para>
1459 </section>
1460
1461 <section id='neon-using-Linuxtools'>
1462 <title>Using Linuxtools</title>
1463
1464 <para>
1465 As mentioned earlier in the manual, performance tools exist
1466 (Linuxtools) that enhance your development experience.
1467 These tools are aids in developing and debugging applications and
1468 images.
1469 You can run these tools from within the Eclipse IDE through the
1470 "Linuxtools" menu.
1471 </para>
1472
1473 <para>
1474 For information on how to configure and use these tools, see
1475 <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
1476 </para>
1477 </section>
1478 </section> 201 </section>
1479</section>
1480
1481</chapter> 202</chapter>
1482<!-- 203<!--
1483vim: expandtab tw=80 ts=4 204vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-21 20:20:23 +0000