diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-using.xml')
-rw-r--r-- | documentation/sdk-manual/sdk-using.xml | 1563 |
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 <stdio.h> | ||
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>&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 ‘<-m 256 -full-screen>’ | ||
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 | <!-- |
1483 | vim: expandtab tw=80 ts=4 | 204 | vim: expandtab tw=80 ts=4 |