blob: 0eddee08e3d48bb4210b2b9f3c5bea08e938025e [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`
Patrick Williams7784c422022-11-17 07:29:11 -060014installed, it is very easy to develop a project using the :wikipedia:`GNU
15Autotools-based <GNU_Build_System>` workflow, which is outside of the
16:term:`OpenEmbedded Build System`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050017
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
Patrick Williams92b42cb2022-09-03 06:53:57 -050091 Another example is sourcing the environment setup directly in a Yocto
92 build::
93
94 $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux
95
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500963. *Create the configure Script:* Use the ``autoreconf`` command to
Patrick Williams92b42cb2022-09-03 06:53:57 -050097 generate the ``configure`` script::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050098
99 $ autoreconf
100
101 The ``autoreconf``
102 tool takes care of running the other Autotools such as ``aclocal``,
103 ``autoconf``, and ``automake``.
104
105 .. note::
106
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500107 If you get errors from ``configure.ac``, which ``autoreconf``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500108 runs, that indicate missing files, you can use the "-i" option,
109 which ensures missing auxiliary files are copied to the build
110 host.
111
1124. *Cross-Compile the Project:* This command compiles the project using
113 the cross-compiler. The
114 :term:`CONFIGURE_FLAGS`
115 environment variable provides the minimal arguments for GNU
Andrew Geisslerc926e172021-05-07 16:11:35 -0500116 configure::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500117
118 $ ./configure ${CONFIGURE_FLAGS}
119
120 For an Autotools-based
121 project, you can use the cross-toolchain by just passing the
122 appropriate host option to ``configure.sh``. The host option you use
123 is derived from the name of the environment setup script found in the
124 directory in which you installed the cross-toolchain. For example,
125 the host option for an ARM-based target that uses the GNU EABI is
126 ``armv5te-poky-linux-gnueabi``. You will notice that the name of the
127 script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the
128 following command works to update your project and rebuild it using
Andrew Geisslerc926e172021-05-07 16:11:35 -0500129 the appropriate cross-toolchain tools::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500130
131 $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
132
1335. *Make and Install the Project:* These two commands generate and
Andrew Geisslerc926e172021-05-07 16:11:35 -0500134 install the project into the destination directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500135
136 $ make
137 $ make install DESTDIR=./tmp
138
139 .. note::
140
141 To learn about environment variables established when you run the
142 cross-toolchain environment setup script and how they are used or
Andrew Geissler09036742021-06-25 14:25:14 -0500143 overridden by the Makefile, see the
144 :ref:`sdk-manual/working-projects:makefile-based projects` section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500145
146 This next command is a simple way to verify the installation of your
147 project. Running the command prints the architecture on which the
148 binary file can run. This architecture should be the same
149 architecture that the installed cross-toolchain supports.
150 ::
151
152 $ file ./tmp/usr/local/bin/hello
153
1546. *Execute Your Project:* To execute the project, you would need to run
155 it on your target hardware. If your target hardware happens to be
Andrew Geisslerc926e172021-05-07 16:11:35 -0500156 your build host, you could run the project as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500157
158 $ ./tmp/usr/local/bin/hello
159
160 As expected, the project displays the "Hello World!" message.
161
162Makefile-Based Projects
163=======================
164
165Simple Makefile-based projects use and interact with the cross-toolchain
166environment variables established when you run the cross-toolchain
167environment setup script. The environment variables are subject to
168general ``make`` rules.
169
170This section presents a simple Makefile development flow and provides an
171example that lets you see how you can use cross-toolchain environment
172variables and Makefile variables during development.
173
174.. image:: figures/sdk-makefile-flow.png
175 :align: center
Andrew Geisslerd5838332022-05-27 11:33:10 -0500176 :width: 70%
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500177
178The main point of this section is to explain the following three cases
179regarding variable behavior:
180
Andrew Geissler615f2f12022-07-15 14:00:58 -0500181- *Case 1 --- No Variables Set in the Makefile Map to Equivalent
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500182 Environment Variables Set in the SDK Setup Script:* Because matching
183 variables are not specifically set in the ``Makefile``, the variables
184 retain their values based on the environment setup script.
185
Andrew Geissler615f2f12022-07-15 14:00:58 -0500186- *Case 2 --- Variables Are Set in the Makefile that Map to Equivalent
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500187 Environment Variables from the SDK Setup Script:* Specifically
188 setting matching variables in the ``Makefile`` during the build
189 results in the environment settings of the variables being
190 overwritten. In this case, the variables you set in the ``Makefile``
191 are used.
192
Andrew Geissler615f2f12022-07-15 14:00:58 -0500193- *Case 3 --- Variables Are Set Using the Command Line that Map to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500194 Equivalent Environment Variables from the SDK Setup Script:*
195 Executing the ``Makefile`` from the command line results in the
196 environment variables being overwritten. In this case, the
197 command-line content is used.
198
199.. note::
200
201 Regardless of how you set your variables, if you use the "-e" option
Andrew Geisslerc926e172021-05-07 16:11:35 -0500202 with ``make``, the variables from the SDK setup script take precedence::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500203
204 $ make -e target
205
206
207The remainder of this section presents a simple Makefile example that
208demonstrates these variable behaviors.
209
210In a new shell environment variables are not established for the SDK
211until you run the setup script. For example, the following commands show
212a null value for the compiler variable (i.e.
213:term:`CC`).
214::
215
216 $ echo ${CC}
217
218 $
219
220Running the
221SDK setup script for a 64-bit build host and an i586-tuned target
Andrew Geissler09209ee2020-12-13 08:44:15 -0600222architecture for a ``core-image-sato`` image using the current &DISTRO;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500223Yocto Project release and then echoing that variable shows the value
Andrew Geisslerc926e172021-05-07 16:11:35 -0500224established through the script::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500225
Andrew Geissler09209ee2020-12-13 08:44:15 -0600226 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500227 $ echo ${CC}
Andrew Geissler09209ee2020-12-13 08:44:15 -0600228 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500229
230To illustrate variable use, work through this simple "Hello World!"
231example:
232
2331. *Create a Working Directory and Populate It:* Create a clean
234 directory for your project and then make that directory your working
235 location.
236 ::
237
238 $ mkdir $HOME/helloworld
239 $ cd $HOME/helloworld
240
241 After
242 setting up the directory, populate it with files needed for the flow.
243 You need a ``main.c`` file from which you call your function, a
244 ``module.h`` file to contain headers, and a ``module.c`` that defines
245 your function.
246
247 Create the three files as follows:
248
Andrew Geisslerc926e172021-05-07 16:11:35 -0500249 - ``main.c``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500250
251 #include "module.h"
252 void sample_func();
253 int main()
254 {
255 sample_func();
256 return 0;
257 }
258
Andrew Geisslerc926e172021-05-07 16:11:35 -0500259 - ``module.h``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500260
261 #include <stdio.h>
262 void sample_func();
263
Andrew Geisslerc926e172021-05-07 16:11:35 -0500264 - ``module.c``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500265
266 #include "module.h"
267 void sample_func()
268 {
269 printf("Hello World!");
270 printf("\n");
271 }
272
2732. *Source the Cross-Toolchain Environment Setup File:* As described
274 earlier in the manual, installing the cross-toolchain creates a
275 cross-toolchain environment setup script in the directory that the
276 SDK was installed. Before you can use the tools to develop your
277 project, you must source this setup script. The script begins with
278 the string "environment-setup" and contains the machine architecture,
279 which is followed by the string "poky-linux". For this example, the
280 command sources a script from the default SDK installation directory
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600281 that uses the 32-bit Intel x86 Architecture and the &DISTRO_NAME; Yocto
Andrew Geisslerc926e172021-05-07 16:11:35 -0500282 Project release::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500283
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600284 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500285
Patrick Williams92b42cb2022-09-03 06:53:57 -0500286 Another example is sourcing the environment setup directly in a Yocto
287 build::
288
289 $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux
290
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002913. *Create the Makefile:* For this example, the Makefile contains
Andrew Geissler09036742021-06-25 14:25:14 -0500292 two lines that can be used to set the :term:`CC` variable. One line is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500293 identical to the value that is set when you run the SDK environment
Andrew Geissler09036742021-06-25 14:25:14 -0500294 setup script, and the other line sets :term:`CC` to "gcc", the default
Andrew Geisslerc926e172021-05-07 16:11:35 -0500295 GNU compiler on the build host::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500296
297 # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
298 # CC="gcc"
299 all: main.o module.o
300 ${CC} main.o module.o -o target_bin
301 main.o: main.c module.h
302 ${CC} -I . -c main.c
303 module.o: module.c
304 module.h ${CC} -I . -c module.c
305 clean:
306 rm -rf *.o
307 rm target_bin
308
3094. *Make the Project:* Use the ``make`` command to create the binary
310 output file. Because variables are commented out in the Makefile, the
Andrew Geissler09036742021-06-25 14:25:14 -0500311 value used for :term:`CC` is the value set when the SDK environment setup
Andrew Geisslerc926e172021-05-07 16:11:35 -0500312 file was run::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500313
314 $ make
315 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
316 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
317 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
318
319 From the results of the previous command, you can see that
Andrew Geissler09036742021-06-25 14:25:14 -0500320 the compiler used was the compiler established through the :term:`CC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500321 variable defined in the setup script.
322
Andrew Geissler09036742021-06-25 14:25:14 -0500323 You can override the :term:`CC` environment variable with the same
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500324 variable as set from the Makefile by uncommenting the line in the
325 Makefile and running ``make`` again.
326 ::
327
328 $ make clean
329 rm -rf *.o
330 rm target_bin
331 #
332 # Edit the Makefile by uncommenting the line that sets CC to "gcc"
333 #
334 $ make
335 gcc -I . -c main.c
336 gcc -I . -c module.c
337 gcc main.o module.o -o target_bin
338
339 As shown in the previous example, the
340 cross-toolchain compiler is not used. Rather, the default compiler is
341 used.
342
343 This next case shows how to override a variable by providing the
344 variable as part of the command line. Go into the Makefile and
345 re-insert the comment character so that running ``make`` uses the
346 established SDK compiler. However, when you run ``make``, use a
Andrew Geissler09036742021-06-25 14:25:14 -0500347 command-line argument to set :term:`CC` to "gcc"::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500348
349 $ make clean
350 rm -rf *.o
351 rm target_bin
352 #
353 # Edit the Makefile to comment out the line setting CC to "gcc"
354 #
355 $ make
356 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
357 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
358 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
359 $ make clean
360 rm -rf *.o
361 rm target_bin
362 $ make CC="gcc"
363 gcc -I . -c main.c
364 gcc -I . -c module.c
365 gcc main.o module.o -o target_bin
366
367 In the previous case, the command-line argument overrides the SDK
368 environment variable.
369
370 In this last case, edit Makefile again to use the "gcc" compiler but
Andrew Geisslerc926e172021-05-07 16:11:35 -0500371 then use the "-e" option on the ``make`` command line::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500372
373 $ make clean
374 rm -rf *.o
375 rm target_bin
376 #
377 # Edit the Makefile to use "gcc"
378 #
379 $ make
380 gcc -I . -c main.c
381 gcc -I . -c module.c
382 gcc main.o module.o -o target_bin
383 $ make clean
384 rm -rf *.o
385 rm target_bin
386 $ make -e
387 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
388 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
389 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
390
391 In the previous case, the "-e" option forces ``make`` to
392 use the SDK environment variables regardless of the values in the
393 Makefile.
394
3955. *Execute Your Project:* To execute the project (i.e. ``target_bin``),
Andrew Geisslerc926e172021-05-07 16:11:35 -0500396 use the following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500397
398 $ ./target_bin
399 Hello World!
400
401 .. note::
402
403 If you used the cross-toolchain compiler to build
404 target_bin
405 and your build host differs in architecture from that of the
406 target machine, you need to run your project on the target device.
407
408 As expected, the project displays the "Hello World!" message.