blob: 7f8d9b84910d5340ccdb1c80d9736c0bc33532e8 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3********************************
4Using the SDK Toolchain Directly
5********************************
6
7You can use the SDK toolchain directly with Makefile and Autotools-based
8projects.
9
10Autotools-Based Projects
11========================
12
Andrew Geissler09209ee2020-12-13 08:44:15 -060013Once you have a suitable :ref:`sdk-manual/intro:the cross-development toolchain`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050014installed, it is very easy to develop a project using the `GNU
15Autotools-based <https://en.wikipedia.org/wiki/GNU_Build_System>`__
16workflow, which is outside of the :term:`OpenEmbedded Build System`.
17
18The following figure presents a simple Autotools workflow.
19
20.. image:: figures/sdk-autotools-flow.png
21 :align: center
Andrew Geisslerd5838332022-05-27 11:33:10 -050022 :width: 70%
Andrew Geisslerc9f78652020-09-18 14:11:35 -050023
24Follow these steps to create a simple Autotools-based "Hello World"
25project:
26
27.. note::
28
29 For more information on the GNU Autotools workflow, see the same
30 example on the
31 GNOME Developer
32 site.
33
341. *Create a Working Directory and Populate It:* Create a clean
35 directory for your project and then make that directory your working
36 location.
37 ::
38
39 $ mkdir $HOME/helloworld
40 $ cd $HOME/helloworld
41
42 After setting up the directory, populate it with files needed for the flow.
43 You need a project source file, a file to help with configuration,
44 and a file to help create the Makefile, and a README file:
45 ``hello.c``, ``configure.ac``, ``Makefile.am``, and ``README``,
46 respectively.
47
48 Use the following command to create an empty README file, which is
Andrew Geisslerc926e172021-05-07 16:11:35 -050049 required by GNU Coding Standards::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050050
51 $ touch README
52
53 Create the remaining
54 three files as follows:
55
Andrew Geisslerc926e172021-05-07 16:11:35 -050056 - ``hello.c``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050057
58 #include <stdio.h>
59
60 main()
61 {
62 printf("Hello World!\n");
63 }
64
Andrew Geisslerc926e172021-05-07 16:11:35 -050065 - ``configure.ac``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050066
67 AC_INIT(hello,0.1)
68 AM_INIT_AUTOMAKE([foreign])
69 AC_PROG_CC
70 AC_CONFIG_FILES(Makefile)
71 AC_OUTPUT
72
Andrew Geisslerc926e172021-05-07 16:11:35 -050073 - ``Makefile.am``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050074
75 bin_PROGRAMS = hello
76 hello_SOURCES = hello.c
77
782. *Source the Cross-Toolchain Environment Setup File:* As described
79 earlier in the manual, installing the cross-toolchain creates a
80 cross-toolchain environment setup script in the directory that the
81 SDK was installed. Before you can use the tools to develop your
82 project, you must source this setup script. The script begins with
83 the string "environment-setup" and contains the machine architecture,
84 which is followed by the string "poky-linux". For this example, the
85 command sources a script from the default SDK installation directory
Andrew Geissler09209ee2020-12-13 08:44:15 -060086 that uses the 32-bit Intel x86 Architecture and the &DISTRO; Yocto
Andrew Geisslerc926e172021-05-07 16:11:35 -050087 Project release::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050088
Andrew Geissler09209ee2020-12-13 08:44:15 -060089 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -050090
913. *Create the configure Script:* Use the ``autoreconf`` command to
92 generate the ``configure`` script.
93 ::
94
95 $ autoreconf
96
97 The ``autoreconf``
98 tool takes care of running the other Autotools such as ``aclocal``,
99 ``autoconf``, and ``automake``.
100
101 .. note::
102
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500103 If you get errors from ``configure.ac``, which ``autoreconf``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500104 runs, that indicate missing files, you can use the "-i" option,
105 which ensures missing auxiliary files are copied to the build
106 host.
107
1084. *Cross-Compile the Project:* This command compiles the project using
109 the cross-compiler. The
110 :term:`CONFIGURE_FLAGS`
111 environment variable provides the minimal arguments for GNU
Andrew Geisslerc926e172021-05-07 16:11:35 -0500112 configure::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500113
114 $ ./configure ${CONFIGURE_FLAGS}
115
116 For an Autotools-based
117 project, you can use the cross-toolchain by just passing the
118 appropriate host option to ``configure.sh``. The host option you use
119 is derived from the name of the environment setup script found in the
120 directory in which you installed the cross-toolchain. For example,
121 the host option for an ARM-based target that uses the GNU EABI is
122 ``armv5te-poky-linux-gnueabi``. You will notice that the name of the
123 script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the
124 following command works to update your project and rebuild it using
Andrew Geisslerc926e172021-05-07 16:11:35 -0500125 the appropriate cross-toolchain tools::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500126
127 $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
128
1295. *Make and Install the Project:* These two commands generate and
Andrew Geisslerc926e172021-05-07 16:11:35 -0500130 install the project into the destination directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500131
132 $ make
133 $ make install DESTDIR=./tmp
134
135 .. note::
136
137 To learn about environment variables established when you run the
138 cross-toolchain environment setup script and how they are used or
Andrew Geissler09036742021-06-25 14:25:14 -0500139 overridden by the Makefile, see the
140 :ref:`sdk-manual/working-projects:makefile-based projects` section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500141
142 This next command is a simple way to verify the installation of your
143 project. Running the command prints the architecture on which the
144 binary file can run. This architecture should be the same
145 architecture that the installed cross-toolchain supports.
146 ::
147
148 $ file ./tmp/usr/local/bin/hello
149
1506. *Execute Your Project:* To execute the project, you would need to run
151 it on your target hardware. If your target hardware happens to be
Andrew Geisslerc926e172021-05-07 16:11:35 -0500152 your build host, you could run the project as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500153
154 $ ./tmp/usr/local/bin/hello
155
156 As expected, the project displays the "Hello World!" message.
157
158Makefile-Based Projects
159=======================
160
161Simple Makefile-based projects use and interact with the cross-toolchain
162environment variables established when you run the cross-toolchain
163environment setup script. The environment variables are subject to
164general ``make`` rules.
165
166This section presents a simple Makefile development flow and provides an
167example that lets you see how you can use cross-toolchain environment
168variables and Makefile variables during development.
169
170.. image:: figures/sdk-makefile-flow.png
171 :align: center
Andrew Geisslerd5838332022-05-27 11:33:10 -0500172 :width: 70%
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500173
174The main point of this section is to explain the following three cases
175regarding variable behavior:
176
Andrew Geissler615f2f12022-07-15 14:00:58 -0500177- *Case 1 --- No Variables Set in the Makefile Map to Equivalent
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500178 Environment Variables Set in the SDK Setup Script:* Because matching
179 variables are not specifically set in the ``Makefile``, the variables
180 retain their values based on the environment setup script.
181
Andrew Geissler615f2f12022-07-15 14:00:58 -0500182- *Case 2 --- Variables Are Set in the Makefile that Map to Equivalent
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500183 Environment Variables from the SDK Setup Script:* Specifically
184 setting matching variables in the ``Makefile`` during the build
185 results in the environment settings of the variables being
186 overwritten. In this case, the variables you set in the ``Makefile``
187 are used.
188
Andrew Geissler615f2f12022-07-15 14:00:58 -0500189- *Case 3 --- Variables Are Set Using the Command Line that Map to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500190 Equivalent Environment Variables from the SDK Setup Script:*
191 Executing the ``Makefile`` from the command line results in the
192 environment variables being overwritten. In this case, the
193 command-line content is used.
194
195.. note::
196
197 Regardless of how you set your variables, if you use the "-e" option
Andrew Geisslerc926e172021-05-07 16:11:35 -0500198 with ``make``, the variables from the SDK setup script take precedence::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500199
200 $ make -e target
201
202
203The remainder of this section presents a simple Makefile example that
204demonstrates these variable behaviors.
205
206In a new shell environment variables are not established for the SDK
207until you run the setup script. For example, the following commands show
208a null value for the compiler variable (i.e.
209:term:`CC`).
210::
211
212 $ echo ${CC}
213
214 $
215
216Running the
217SDK setup script for a 64-bit build host and an i586-tuned target
Andrew Geissler09209ee2020-12-13 08:44:15 -0600218architecture for a ``core-image-sato`` image using the current &DISTRO;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500219Yocto Project release and then echoing that variable shows the value
Andrew Geisslerc926e172021-05-07 16:11:35 -0500220established through the script::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500221
Andrew Geissler09209ee2020-12-13 08:44:15 -0600222 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500223 $ echo ${CC}
Andrew Geissler09209ee2020-12-13 08:44:15 -0600224 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500225
226To illustrate variable use, work through this simple "Hello World!"
227example:
228
2291. *Create a Working Directory and Populate It:* Create a clean
230 directory for your project and then make that directory your working
231 location.
232 ::
233
234 $ mkdir $HOME/helloworld
235 $ cd $HOME/helloworld
236
237 After
238 setting up the directory, populate it with files needed for the flow.
239 You need a ``main.c`` file from which you call your function, a
240 ``module.h`` file to contain headers, and a ``module.c`` that defines
241 your function.
242
243 Create the three files as follows:
244
Andrew Geisslerc926e172021-05-07 16:11:35 -0500245 - ``main.c``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500246
247 #include "module.h"
248 void sample_func();
249 int main()
250 {
251 sample_func();
252 return 0;
253 }
254
Andrew Geisslerc926e172021-05-07 16:11:35 -0500255 - ``module.h``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500256
257 #include <stdio.h>
258 void sample_func();
259
Andrew Geisslerc926e172021-05-07 16:11:35 -0500260 - ``module.c``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500261
262 #include "module.h"
263 void sample_func()
264 {
265 printf("Hello World!");
266 printf("\n");
267 }
268
2692. *Source the Cross-Toolchain Environment Setup File:* As described
270 earlier in the manual, installing the cross-toolchain creates a
271 cross-toolchain environment setup script in the directory that the
272 SDK was installed. Before you can use the tools to develop your
273 project, you must source this setup script. The script begins with
274 the string "environment-setup" and contains the machine architecture,
275 which is followed by the string "poky-linux". For this example, the
276 command sources a script from the default SDK installation directory
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600277 that uses the 32-bit Intel x86 Architecture and the &DISTRO_NAME; Yocto
Andrew Geisslerc926e172021-05-07 16:11:35 -0500278 Project release::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500279
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600280 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500281
2823. *Create the Makefile:* For this example, the Makefile contains
Andrew Geissler09036742021-06-25 14:25:14 -0500283 two lines that can be used to set the :term:`CC` variable. One line is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500284 identical to the value that is set when you run the SDK environment
Andrew Geissler09036742021-06-25 14:25:14 -0500285 setup script, and the other line sets :term:`CC` to "gcc", the default
Andrew Geisslerc926e172021-05-07 16:11:35 -0500286 GNU compiler on the build host::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500287
288 # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
289 # CC="gcc"
290 all: main.o module.o
291 ${CC} main.o module.o -o target_bin
292 main.o: main.c module.h
293 ${CC} -I . -c main.c
294 module.o: module.c
295 module.h ${CC} -I . -c module.c
296 clean:
297 rm -rf *.o
298 rm target_bin
299
3004. *Make the Project:* Use the ``make`` command to create the binary
301 output file. Because variables are commented out in the Makefile, the
Andrew Geissler09036742021-06-25 14:25:14 -0500302 value used for :term:`CC` is the value set when the SDK environment setup
Andrew Geisslerc926e172021-05-07 16:11:35 -0500303 file was run::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500304
305 $ make
306 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
307 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
308 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
309
310 From the results of the previous command, you can see that
Andrew Geissler09036742021-06-25 14:25:14 -0500311 the compiler used was the compiler established through the :term:`CC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500312 variable defined in the setup script.
313
Andrew Geissler09036742021-06-25 14:25:14 -0500314 You can override the :term:`CC` environment variable with the same
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500315 variable as set from the Makefile by uncommenting the line in the
316 Makefile and running ``make`` again.
317 ::
318
319 $ make clean
320 rm -rf *.o
321 rm target_bin
322 #
323 # Edit the Makefile by uncommenting the line that sets CC to "gcc"
324 #
325 $ make
326 gcc -I . -c main.c
327 gcc -I . -c module.c
328 gcc main.o module.o -o target_bin
329
330 As shown in the previous example, the
331 cross-toolchain compiler is not used. Rather, the default compiler is
332 used.
333
334 This next case shows how to override a variable by providing the
335 variable as part of the command line. Go into the Makefile and
336 re-insert the comment character so that running ``make`` uses the
337 established SDK compiler. However, when you run ``make``, use a
Andrew Geissler09036742021-06-25 14:25:14 -0500338 command-line argument to set :term:`CC` to "gcc"::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500339
340 $ make clean
341 rm -rf *.o
342 rm target_bin
343 #
344 # Edit the Makefile to comment out the line setting CC to "gcc"
345 #
346 $ make
347 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
348 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
349 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
350 $ make clean
351 rm -rf *.o
352 rm target_bin
353 $ make CC="gcc"
354 gcc -I . -c main.c
355 gcc -I . -c module.c
356 gcc main.o module.o -o target_bin
357
358 In the previous case, the command-line argument overrides the SDK
359 environment variable.
360
361 In this last case, edit Makefile again to use the "gcc" compiler but
Andrew Geisslerc926e172021-05-07 16:11:35 -0500362 then use the "-e" option on the ``make`` command line::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500363
364 $ make clean
365 rm -rf *.o
366 rm target_bin
367 #
368 # Edit the Makefile to use "gcc"
369 #
370 $ make
371 gcc -I . -c main.c
372 gcc -I . -c module.c
373 gcc main.o module.o -o target_bin
374 $ make clean
375 rm -rf *.o
376 rm target_bin
377 $ make -e
378 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
379 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
380 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
381
382 In the previous case, the "-e" option forces ``make`` to
383 use the SDK environment variables regardless of the values in the
384 Makefile.
385
3865. *Execute Your Project:* To execute the project (i.e. ``target_bin``),
Andrew Geisslerc926e172021-05-07 16:11:35 -0500387 use the following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500388
389 $ ./target_bin
390 Hello World!
391
392 .. note::
393
394 If you used the cross-toolchain compiler to build
395 target_bin
396 and your build host differs in architecture from that of the
397 target machine, you need to run your project on the target device.
398
399 As expected, the project displays the "Hello World!" message.