summaryrefslogtreecommitdiffstats
path: root/documentation/adt-manual/adt-command.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/adt-manual/adt-command.xml')
-rw-r--r--documentation/adt-manual/adt-command.xml266
1 files changed, 0 insertions, 266 deletions
diff --git a/documentation/adt-manual/adt-command.xml b/documentation/adt-manual/adt-command.xml
deleted file mode 100644
index b88c0ac682..0000000000
--- a/documentation/adt-manual/adt-command.xml
+++ /dev/null
@@ -1,266 +0,0 @@
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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='using-the-command-line'>
7<title>Using the Command Line</title>
8
9 <para>
10 Recall that earlier the manual discussed how to use an existing toolchain
11 tarball that had been installed into the default installation
12 directory, <filename>/opt/poky/&DISTRO;</filename>, which is outside of the
13 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
14 (see the section "<link linkend='using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball)</link>".
15 And, that sourcing your architecture-specific environment setup script
16 initializes a suitable cross-toolchain development environment.
17 </para>
18
19 <para>
20 During this setup, locations for the compiler, QEMU scripts, QEMU binary,
21 a special version of <filename>pkgconfig</filename> and other useful
22 utilities are added to the <filename>PATH</filename> variable.
23 Also, variables to assist
24 <filename>pkgconfig</filename> and <filename>autotools</filename>
25 are also defined so that, for example, <filename>configure.sh</filename>
26 can find pre-generated test results for tests that need target hardware
27 on which to run.
28 You can see the
29 "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>"
30 section for the list of cross-toolchain environment variables
31 established by the script.
32 </para>
33
34 <para>
35 Collectively, these conditions allow you to easily use the toolchain
36 outside of the OpenEmbedded build environment on both Autotools-based
37 projects and Makefile-based projects.
38 This chapter provides information for both these types of projects.
39 </para>
40
41
42<section id='autotools-based-projects'>
43<title>Autotools-Based Projects</title>
44
45 <para>
46 Once you have a suitable cross-toolchain installed, it is very easy to
47 develop a project outside of the OpenEmbedded build system.
48 This section presents a simple "Helloworld" example that shows how
49 to set up, compile, and run the project.
50 </para>
51
52 <section id='creating-and-running-a-project-based-on-gnu-autotools'>
53 <title>Creating and Running a Project Based on GNU Autotools</title>
54
55 <para>
56 Follow these steps to create a simple Autotools-based project:
57 <orderedlist>
58 <listitem><para><emphasis>Create your directory:</emphasis>
59 Create a clean directory for your project and then make
60 that directory your working location:
61 <literallayout class='monospaced'>
62 $ mkdir $HOME/helloworld
63 $ cd $HOME/helloworld
64 </literallayout></para></listitem>
65 <listitem><para><emphasis>Populate the directory:</emphasis>
66 Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
67 and <filename>configure.in</filename> files as follows:
68 <itemizedlist>
69 <listitem><para>For <filename>hello.c</filename>, include
70 these lines:
71 <literallayout class='monospaced'>
72 #include &lt;stdio.h&gt;
73
74 main()
75 {
76 printf("Hello World!\n");
77 }
78 </literallayout></para></listitem>
79 <listitem><para>For <filename>Makefile.am</filename>,
80 include these lines:
81 <literallayout class='monospaced'>
82 bin_PROGRAMS = hello
83 hello_SOURCES = hello.c
84 </literallayout></para></listitem>
85 <listitem><para>For <filename>configure.in</filename>,
86 include these lines:
87 <literallayout class='monospaced'>
88 AC_INIT(hello.c)
89 AM_INIT_AUTOMAKE(hello,0.1)
90 AC_PROG_CC
91 AC_PROG_INSTALL
92 AC_OUTPUT(Makefile)
93 </literallayout></para></listitem>
94 </itemizedlist></para></listitem>
95 <listitem><para><emphasis>Source the cross-toolchain
96 environment setup file:</emphasis>
97 Installation of the cross-toolchain creates a cross-toolchain
98 environment setup script in the directory that the ADT
99 was installed.
100 Before you can use the tools to develop your project, you must
101 source this setup script.
102 The script begins with the string "environment-setup" and contains
103 the machine architecture, which is followed by the string
104 "poky-linux".
105 Here is an example that sources a script from the
106 default ADT installation directory that uses the
107 32-bit Intel x86 Architecture and the
108 &DISTRO_NAME; Yocto Project release:
109 <literallayout class='monospaced'>
110 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
111 </literallayout></para></listitem>
112 <listitem><para><emphasis>Generate the local aclocal.m4
113 files and create the configure script:</emphasis>
114 The following GNU Autotools generate the local
115 <filename>aclocal.m4</filename> files and create the
116 configure script:
117 <literallayout class='monospaced'>
118 $ aclocal
119 $ autoconf
120 </literallayout></para></listitem>
121 <listitem><para><emphasis>Generate files needed by GNU
122 coding standards:</emphasis>
123 GNU coding standards require certain files in order for the
124 project to be compliant.
125 This command creates those files:
126 <literallayout class='monospaced'>
127 $ touch NEWS README AUTHORS ChangeLog
128 </literallayout></para></listitem>
129 <listitem><para><emphasis>Generate the configure
130 file:</emphasis>
131 This command generates the <filename>configure</filename>:
132 <literallayout class='monospaced'>
133 $ automake -a
134 </literallayout></para></listitem>
135 <listitem><para><emphasis>Cross-compile the project:</emphasis>
136 This command compiles the project using the cross-compiler.
137 The
138 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
139 environment variable provides the minimal arguments for
140 GNU configure:
141 <literallayout class='monospaced'>
142 $ ./configure ${CONFIGURE_FLAGS}
143 </literallayout></para></listitem>
144 <listitem><para><emphasis>Make and install the project:</emphasis>
145 These two commands generate and install the project into the
146 destination directory:
147 <literallayout class='monospaced'>
148 $ make
149 $ make install DESTDIR=./tmp
150 </literallayout></para></listitem>
151 <listitem><para><emphasis>Verify the installation:</emphasis>
152 This command is a simple way to verify the installation
153 of your project.
154 Running the command prints the architecture on which
155 the binary file can run.
156 This architecture should be the same architecture that
157 the installed cross-toolchain supports.
158 <literallayout class='monospaced'>
159 $ file ./tmp/usr/local/bin/hello
160 </literallayout></para></listitem>
161 <listitem><para><emphasis>Execute your project:</emphasis>
162 To execute the project in the shell, simply enter the name.
163 You could also copy the binary to the actual target hardware
164 and run the project there as well:
165 <literallayout class='monospaced'>
166 $ ./hello
167 </literallayout>
168 As expected, the project displays the "Hello World!" message.
169 </para></listitem>
170 </orderedlist>
171 </para>
172 </section>
173
174 <section id='passing-host-options'>
175 <title>Passing Host Options</title>
176
177 <para>
178 For an Autotools-based project, you can use the cross-toolchain by just
179 passing the appropriate host option to <filename>configure.sh</filename>.
180 The host option you use is derived from the name of the environment setup
181 script found in the directory in which you installed the cross-toolchain.
182 For example, the host option for an ARM-based target that uses the GNU EABI
183 is <filename>armv5te-poky-linux-gnueabi</filename>.
184 You will notice that the name of the script is
185 <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
186 Thus, the following command works to update your project and
187 rebuild it using the appropriate cross-toolchain tools:
188 <literallayout class='monospaced'>
189 $ ./configure --host=armv5te-poky-linux-gnueabi \
190 --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
191 </literallayout>
192 <note>
193 If the <filename>configure</filename> script results in problems recognizing the
194 <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option,
195 regenerate the script to enable the support by doing the following and then
196 run the script again:
197 <literallayout class='monospaced'>
198 $ libtoolize --automake
199 $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
200 [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
201 $ autoconf
202 $ autoheader
203 $ automake -a
204 </literallayout>
205 </note>
206 </para>
207 </section>
208</section>
209
210<section id='makefile-based-projects'>
211<title>Makefile-Based Projects</title>
212
213 <para>
214 For Makefile-based projects, the cross-toolchain environment variables
215 established by running the cross-toolchain environment setup script
216 are subject to general <filename>make</filename> rules.
217 </para>
218
219 <para>
220 To illustrate this, consider the following four cross-toolchain
221 environment variables:
222 <literallayout class='monospaced'>
223 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux
224 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux
225 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
226 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
227 </literallayout>
228 Now, consider the following three cases:
229 <itemizedlist>
230 <listitem><para><emphasis>Case 1 - No Variables Set in the <filename>Makefile</filename>:</emphasis>
231 Because these variables are not specifically set in the
232 <filename>Makefile</filename>, the variables retain their
233 values based on the environment.
234 </para></listitem>
235 <listitem><para><emphasis>Case 2 - Variables Set in the <filename>Makefile</filename>:</emphasis>
236 Specifically setting variables in the
237 <filename>Makefile</filename> during the build results in the
238 environment settings of the variables being overwritten.
239 </para></listitem>
240 <listitem><para><emphasis>Case 3 - Variables Set when the <filename>Makefile</filename> is Executed from the Command Line:</emphasis>
241 Executing the <filename>Makefile</filename> from the command
242 line results in the variables being overwritten with
243 command-line content regardless of what is being set in the
244 <filename>Makefile</filename>.
245 In this case, environment variables are not considered unless
246 you use the "-e" flag during the build:
247 <literallayout class='monospaced'>
248 $ make -e <replaceable>file</replaceable>
249 </literallayout>
250 If you use this flag, then the environment values of the
251 variables override any variables specifically set in the
252 <filename>Makefile</filename>.
253 </para></listitem>
254 </itemizedlist>
255 <note>
256 For the list of variables set up by the cross-toolchain environment
257 setup script, see the
258 "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>"
259 section.
260 </note>
261 </para>
262</section>
263</chapter>
264<!--
265vim: expandtab tw=80 ts=4
266-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-02-27 08:20:22 +0000