summaryrefslogtreecommitdiffstats
path: root/documentation/adt-manual/adt-command.xml
diff options
context:
space:
mode:
authorAdrian Dudau <adrian.dudau@enea.com>2013-12-12 13:46:05 +0100
committerAdrian Dudau <adrian.dudau@enea.com>2013-12-12 13:47:32 +0100
commit14b00ff23a912494edc7f146e668c40ca82b8508 (patch)
treef7f4e592ccb935bc312cfa0cfc3c0cbbe444970d /documentation/adt-manual/adt-command.xml
downloadyocto-docs-master.tar.gz
initial commit of Enea Linux 3.1HEADmaster
Migrated from the internal git server on the dora-enea branch Signed-off-by: Adrian Dudau <adrian.dudau@enea.com>
Diffstat (limited to 'documentation/adt-manual/adt-command.xml')
-rw-r--r--documentation/adt-manual/adt-command.xml224
1 files changed, 224 insertions, 0 deletions
diff --git a/documentation/adt-manual/adt-command.xml b/documentation/adt-manual/adt-command.xml
new file mode 100644
index 0000000..0ed3396
--- /dev/null
+++ b/documentation/adt-manual/adt-command.xml
@@ -0,0 +1,224 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='using-the-command-line'>
6<title>Using the Command Line</title>
7
8 <para>
9 Recall that earlier the manual discussed how to use an existing toolchain
10 tarball that had been installed into the default installation
11 directory, <filename>/opt/poky/&DISTRO;</filename>, which is outside of the
12 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
13 (see the section "<link linkend='using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball)</link>".
14 And, that sourcing your architecture-specific environment setup script
15 initializes a suitable cross-toolchain development environment.
16 </para>
17
18 <para>
19 During this setup, locations for the compiler, QEMU scripts, QEMU binary,
20 a special version of <filename>pkgconfig</filename> and other useful
21 utilities are added to the <filename>PATH</filename> variable.
22 Also, variables to assist
23 <filename>pkgconfig</filename> and <filename>autotools</filename>
24 are also defined so that, for example, <filename>configure.sh</filename>
25 can find pre-generated test results for tests that need target hardware
26 on which to run.
27 </para>
28
29 <para>
30 Collectively, these conditions allow you to easily use the toolchain
31 outside of the OpenEmbedded build environment on both autotools-based
32 projects and Makefile-based projects.
33 This chapter provides information for both these types of projects.
34 </para>
35
36
37<section id='autotools-based-projects'>
38<title>Autotools-Based Projects</title>
39
40 <para>
41 Once you have a suitable cross-toolchain installed, it is very easy to
42 develop a project outside of the OpenEmbedded build system.
43 This section presents a simple "Helloworld" example that shows how
44 to set up, compile, and run the project.
45 </para>
46
47 <section id='creating-and-running-a-project-based-on-gnu-autotools'>
48 <title>Creating and Running a Project Based on GNU Autotools</title>
49
50 <para>
51 Follow these steps to create a simple autotools-based project:
52 <orderedlist>
53 <listitem><para><emphasis>Create your directory:</emphasis>
54 Create a clean directory for your project and then make
55 that directory your working location:
56 <literallayout class='monospaced'>
57 $ mkdir $HOME/helloworld
58 $ cd $HOME/helloworld
59 </literallayout></para></listitem>
60 <listitem><para><emphasis>Populate the directory:</emphasis>
61 Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
62 and <filename>configure.in</filename> files as follows:
63 <itemizedlist>
64 <listitem><para>For <filename>hello.c</filename>, include
65 these lines:
66 <literallayout class='monospaced'>
67 #include &lt;stdio.h&gt;
68
69 main()
70 {
71 printf("Hello World!\n");
72 }
73 </literallayout></para></listitem>
74 <listitem><para>For <filename>Makefile.am</filename>,
75 include these lines:
76 <literallayout class='monospaced'>
77 bin_PROGRAMS = hello
78 hello_SOURCES = hello.c
79 </literallayout></para></listitem>
80 <listitem><para>For <filename>configure.in</filename>,
81 include these lines:
82 <literallayout class='monospaced'>
83 AC_INIT(hello.c)
84 AM_INIT_AUTOMAKE(hello,0.1)
85 AC_PROG_CC
86 AC_PROG_INSTALL
87 AC_OUTPUT(Makefile)
88 </literallayout></para></listitem>
89 </itemizedlist></para></listitem>
90 <listitem><para><emphasis>Source the cross-toolchain
91 environment setup file:</emphasis>
92 Installation of the cross-toolchain creates a cross-toolchain
93 environment setup script in the directory that the ADT
94 was installed.
95 Before you can use the tools to develop your project, you must
96 source this setup script.
97 The script begins with the string "environment-setup" and contains
98 the machine architecture, which is followed by the string
99 "poky-linux".
100 Here is an example that sources a script from the
101 default ADT installation directory that uses the
102 32-bit Intel x86 Architecture and using the
103 &DISTRO_NAME; Yocto Project release:
104 <literallayout class='monospaced'>
105 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
106 </literallayout></para></listitem>
107 <listitem><para><emphasis>Generate the local aclocal.m4
108 files and create the configure script:</emphasis>
109 The following GNU Autotools generate the local
110 <filename>aclocal.m4</filename> files and create the
111 configure script:
112 <literallayout class='monospaced'>
113 $ aclocal
114 $ autoconf
115 </literallayout></para></listitem>
116 <listitem><para><emphasis>Generate files needed by GNU
117 coding standards:</emphasis>
118 GNU coding standards require certain files in order for the
119 project to be compliant.
120 This command creates those files:
121 <literallayout class='monospaced'>
122 $ touch NEWS README AUTHORS ChangeLog
123 </literallayout></para></listitem>
124 <listitem><para><emphasis>Generate the configure
125 file:</emphasis>
126 This command generates the <filename>configure</filename>:
127 <literallayout class='monospaced'>
128 $ automake -a
129 </literallayout></para></listitem>
130 <listitem><para><emphasis>Cross-compile the project:</emphasis>
131 This command compiles the project using the cross-compiler:
132 <literallayout class='monospaced'>
133 $ ./configure ${CONFIGURE_FLAGS}
134 </literallayout></para></listitem>
135 <listitem><para><emphasis>Make and install the project:</emphasis>
136 These two commands generate and install the project into the
137 destination directory:
138 <literallayout class='monospaced'>
139 $ make
140 $ make install DESTDIR=./tmp
141 </literallayout></para></listitem>
142 <listitem><para><emphasis>Verify the installation:</emphasis>
143 This command is a simple way to verify the installation
144 of your project.
145 Running the command prints the architecture on which
146 the binary file can run.
147 This architecture should be the same architecture that
148 the installed cross-toolchain supports.
149 <literallayout class='monospaced'>
150 $ file ./tmp/usr/local/bin/hello
151 </literallayout></para></listitem>
152 <listitem><para><emphasis>Execute your project:</emphasis>
153 To execute the project in the shell, simply enter the name.
154 You could also copy the binary to the actual target hardware
155 and run the project there as well:
156 <literallayout class='monospaced'>
157 $ ./hello
158 </literallayout>
159 As expected, the project displays the "Hello World!" message.
160 </para></listitem>
161 </orderedlist>
162 </para>
163 </section>
164
165 <section id='passing-host-options'>
166 <title>Passing Host Options</title>
167
168 <para>
169 For an Autotools-based project, you can use the cross-toolchain by just
170 passing the appropriate host option to <filename>configure.sh</filename>.
171 The host option you use is derived from the name of the environment setup
172 script found in the directory in which you installed the cross-toolchain.
173 For example, the host option for an ARM-based target that uses the GNU EABI
174 is <filename>armv5te-poky-linux-gnueabi</filename>.
175 You will notice that the name of the script is
176 <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
177 Thus, the following command works:
178 <literallayout class='monospaced'>
179 $ ./configure --host=armv5te-poky-linux-gnueabi \
180 --with-libtool-sysroot=&lt;sysroot-dir&gt;
181 </literallayout>
182 </para>
183
184 <para>
185 This single command updates your project and rebuilds it using the appropriate
186 cross-toolchain tools.
187 <note>
188 If <filename>configure</filename> script results in problems recognizing the
189 <filename>--with-libtool-sysroot=&lt;sysroot-dir&gt;</filename> option,
190 regenerate the script to enable the support by doing the following and then
191 run the script again:
192 <literallayout class='monospaced'>
193 $ libtoolize --automake
194 $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
195 [-I &lt;dir_containing_your_project-specific_m4_macros&gt;]
196 $ autoconf
197 $ autoheader
198 $ automake -a
199 </literallayout>
200 </note>
201 </para>
202 </section>
203</section>
204
205<section id='makefile-based-projects'>
206<title>Makefile-Based Projects</title>
207
208 <para>
209 For a Makefile-based project, you use the cross-toolchain by making sure
210 the tools are used.
211 You can do this as follows:
212 <literallayout class='monospaced'>
213 CC=arm-poky-linux-gnueabi-gcc
214 LD=arm-poky-linux-gnueabi-ld
215 CFLAGS=”${CFLAGS} --sysroot=&lt;sysroot-dir&gt;”
216 CXXFLAGS=”${CXXFLAGS} --sysroot=&lt;sysroot-dir&gt;”
217 </literallayout>
218 </para>
219</section>
220
221</chapter>
222<!--
223vim: expandtab tw=80 ts=4
224-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-11-19 13:07:35 +0000