summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/working-projects.rst
blob: 3e40936ff6c52f359c9f1c9694afbab9210f80ef (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
.. SPDX-License-Identifier: CC-BY-SA-2.0-UK

********************************
Using the SDK Toolchain Directly
********************************

You can use the SDK toolchain directly with Makefile and Autotools-based
projects.

Autotools-Based Projects
========================

Once you have a suitable :ref:`sdk-manual/intro:the cross-development toolchain`
installed, it is very easy to develop a project using the `GNU
Autotools-based <https://en.wikipedia.org/wiki/GNU_Build_System>`__
workflow, which is outside of the :term:`OpenEmbedded Build System`.

The following figure presents a simple Autotools workflow.

.. image:: figures/sdk-autotools-flow.png
   :align: center

Follow these steps to create a simple Autotools-based "Hello World"
project:

.. note::

   For more information on the GNU Autotools workflow, see the same
   example on the
   GNOME Developer
   site.

1. *Create a Working Directory and Populate It:* Create a clean
   directory for your project and then make that directory your working
   location.
   ::

      $ mkdir $HOME/helloworld
      $ cd $HOME/helloworld

   After setting up the directory, populate it with files needed for the flow.
   You need a project source file, a file to help with configuration,
   and a file to help create the Makefile, and a README file:
   ``hello.c``, ``configure.ac``, ``Makefile.am``, and ``README``,
   respectively.

   Use the following command to create an empty README file, which is
   required by GNU Coding Standards:
   ::

      $ touch README

   Create the remaining
   three files as follows:

   -  ``hello.c``:
      ::

         #include <stdio.h>

         main()
             {
                 printf("Hello World!\n");
             }

   -  ``configure.ac``:
      ::

         AC_INIT(hello,0.1)
         AM_INIT_AUTOMAKE([foreign])
         AC_PROG_CC
         AC_CONFIG_FILES(Makefile)
         AC_OUTPUT

   -  ``Makefile.am``:
      ::

         bin_PROGRAMS = hello
         hello_SOURCES = hello.c

2. *Source the Cross-Toolchain Environment Setup File:* As described
   earlier in the manual, installing the cross-toolchain creates a
   cross-toolchain environment setup script in the directory that the
   SDK was installed. Before you can use the tools to develop your
   project, you must source this setup script. The script begins with
   the string "environment-setup" and contains the machine architecture,
   which is followed by the string "poky-linux". For this example, the
   command sources a script from the default SDK installation directory
   that uses the 32-bit Intel x86 Architecture and the &DISTRO; Yocto
   Project release:
   ::

      $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux

3. *Create the configure Script:* Use the ``autoreconf`` command to
   generate the ``configure`` script.
   ::

      $ autoreconf

   The ``autoreconf``
   tool takes care of running the other Autotools such as ``aclocal``,
   ``autoconf``, and ``automake``.

   .. note::

      If you get errors from
      configure.ac
      , which
      autoreconf
      runs, that indicate missing files, you can use the "-i" option,
      which ensures missing auxiliary files are copied to the build
      host.

4. *Cross-Compile the Project:* This command compiles the project using
   the cross-compiler. The
   :term:`CONFIGURE_FLAGS`
   environment variable provides the minimal arguments for GNU
   configure:
   ::

      $ ./configure ${CONFIGURE_FLAGS}

   For an Autotools-based
   project, you can use the cross-toolchain by just passing the
   appropriate host option to ``configure.sh``. The host option you use
   is derived from the name of the environment setup script found in the
   directory in which you installed the cross-toolchain. For example,
   the host option for an ARM-based target that uses the GNU EABI is
   ``armv5te-poky-linux-gnueabi``. You will notice that the name of the
   script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the
   following command works to update your project and rebuild it using
   the appropriate cross-toolchain tools:
   ::

     $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir

5. *Make and Install the Project:* These two commands generate and
   install the project into the destination directory:
   ::

      $ make
      $ make install DESTDIR=./tmp

   .. note::

      To learn about environment variables established when you run the
      cross-toolchain environment setup script and how they are used or
      overridden when the Makefile, see the "
      Makefile-Based Projects
      " section.

   This next command is a simple way to verify the installation of your
   project. Running the command prints the architecture on which the
   binary file can run. This architecture should be the same
   architecture that the installed cross-toolchain supports.
   ::

      $ file ./tmp/usr/local/bin/hello

6. *Execute Your Project:* To execute the project, you would need to run
   it on your target hardware. If your target hardware happens to be
   your build host, you could run the project as follows:
   ::

      $ ./tmp/usr/local/bin/hello

   As expected, the project displays the "Hello World!" message.

Makefile-Based Projects
=======================

Simple Makefile-based projects use and interact with the cross-toolchain
environment variables established when you run the cross-toolchain
environment setup script. The environment variables are subject to
general ``make`` rules.

This section presents a simple Makefile development flow and provides an
example that lets you see how you can use cross-toolchain environment
variables and Makefile variables during development.

.. image:: figures/sdk-makefile-flow.png
   :align: center

The main point of this section is to explain the following three cases
regarding variable behavior:

-  *Case 1 - No Variables Set in the Makefile Map to Equivalent
   Environment Variables Set in the SDK Setup Script:* Because matching
   variables are not specifically set in the ``Makefile``, the variables
   retain their values based on the environment setup script.

-  *Case 2 - Variables Are Set in the Makefile that Map to Equivalent
   Environment Variables from the SDK Setup Script:* Specifically
   setting matching variables in the ``Makefile`` during the build
   results in the environment settings of the variables being
   overwritten. In this case, the variables you set in the ``Makefile``
   are used.

-  *Case 3 - Variables Are Set Using the Command Line that Map to
   Equivalent Environment Variables from the SDK Setup Script:*
   Executing the ``Makefile`` from the command line results in the
   environment variables being overwritten. In this case, the
   command-line content is used.

.. note::

   Regardless of how you set your variables, if you use the "-e" option
   with
   make
   , the variables from the SDK setup script take precedence:
   ::

      $ make -e target


The remainder of this section presents a simple Makefile example that
demonstrates these variable behaviors.

In a new shell environment variables are not established for the SDK
until you run the setup script. For example, the following commands show
a null value for the compiler variable (i.e.
:term:`CC`).
::

   $ echo ${CC}

   $

Running the
SDK setup script for a 64-bit build host and an i586-tuned target
architecture for a ``core-image-sato`` image using the current &DISTRO;
Yocto Project release and then echoing that variable shows the value
established through the script:
::

   $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
   $ echo ${CC}
   i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux

To illustrate variable use, work through this simple "Hello World!"
example:

1. *Create a Working Directory and Populate It:* Create a clean
   directory for your project and then make that directory your working
   location.
   ::

      $ mkdir $HOME/helloworld
      $ cd $HOME/helloworld

   After
   setting up the directory, populate it with files needed for the flow.
   You need a ``main.c`` file from which you call your function, a
   ``module.h`` file to contain headers, and a ``module.c`` that defines
   your function.

   Create the three files as follows:

   -  ``main.c``:
      ::

         #include "module.h"
         void sample_func();
         int main()
         {
             sample_func();
             return 0;
         }

   -  ``module.h``:
      ::

         #include <stdio.h>
         void sample_func();

   -  ``module.c``:
      ::

         #include "module.h"
         void sample_func()
         {
             printf("Hello World!");
             printf("\n");
         }

2. *Source the Cross-Toolchain Environment Setup File:* As described
   earlier in the manual, installing the cross-toolchain creates a
   cross-toolchain environment setup script in the directory that the
   SDK was installed. Before you can use the tools to develop your
   project, you must source this setup script. The script begins with
   the string "environment-setup" and contains the machine architecture,
   which is followed by the string "poky-linux". For this example, the
   command sources a script from the default SDK installation directory
   that uses the 32-bit Intel x86 Architecture and the DISTRO_NAME Yocto
   Project release:
   ::

      $ source /opt/poky/DISTRO/environment-setup-i586-poky-linux

3. *Create the Makefile:* For this example, the Makefile contains
   two lines that can be used to set the ``CC`` variable. One line is
   identical to the value that is set when you run the SDK environment
   setup script, and the other line sets ``CC`` to "gcc", the default
   GNU compiler on the build host:
   ::

      # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
      # CC="gcc"
      all: main.o module.o
      	${CC} main.o module.o -o target_bin
      main.o: main.c module.h
      	${CC} -I . -c main.c
      module.o: module.c
      	module.h ${CC} -I . -c module.c
      clean:
      	rm -rf *.o
      	rm target_bin

4. *Make the Project:* Use the ``make`` command to create the binary
   output file. Because variables are commented out in the Makefile, the
   value used for ``CC`` is the value set when the SDK environment setup
   file was run:
   ::

      $ make
      i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
      i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
      i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin

   From the results of the previous command, you can see that
   the compiler used was the compiler established through the ``CC``
   variable defined in the setup script.

   You can override the ``CC`` environment variable with the same
   variable as set from the Makefile by uncommenting the line in the
   Makefile and running ``make`` again.
   ::

      $ make clean
      rm -rf *.o
      rm target_bin
      #
      # Edit the Makefile by uncommenting the line that sets CC to "gcc"
      #
      $ make
      gcc -I . -c main.c
      gcc -I . -c module.c
      gcc main.o module.o -o target_bin

   As shown in the previous example, the
   cross-toolchain compiler is not used. Rather, the default compiler is
   used.

   This next case shows how to override a variable by providing the
   variable as part of the command line. Go into the Makefile and
   re-insert the comment character so that running ``make`` uses the
   established SDK compiler. However, when you run ``make``, use a
   command-line argument to set ``CC`` to "gcc":
   ::

      $ make clean
      rm -rf *.o
      rm target_bin
      #
      # Edit the Makefile to comment out the line setting CC to "gcc"
      #
      $ make
      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
      $ make clean
      rm -rf *.o
      rm target_bin
      $ make CC="gcc"
      gcc -I . -c main.c
      gcc -I . -c module.c
      gcc main.o module.o -o target_bin

   In the previous case, the command-line argument overrides the SDK
   environment variable.

   In this last case, edit Makefile again to use the "gcc" compiler but
   then use the "-e" option on the ``make`` command line:
   ::

      $ make clean
      rm -rf *.o
      rm target_bin
      #
      # Edit the Makefile to use "gcc"
      #
      $ make
      gcc -I . -c main.c
      gcc -I . -c module.c
      gcc main.o module.o -o target_bin
      $ make clean
      rm -rf *.o
      rm target_bin
      $ make -e
      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin

   In the previous case, the "-e" option forces ``make`` to
   use the SDK environment variables regardless of the values in the
   Makefile.

5. *Execute Your Project:* To execute the project (i.e. ``target_bin``),
   use the following command:
   ::

      $ ./target_bin
      Hello World!

   .. note::

      If you used the cross-toolchain compiler to build
      target_bin
      and your build host differs in architecture from that of the
      target machine, you need to run your project on the target device.

   As expected, the project displays the "Hello World!" message.