summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-06-07 15:02:37 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-06-15 11:26:47 +0100
commit402b7ce9df5522b08b9d3d547407f137938a3ffe (patch)
tree8c504defb58b8beccd20d795079dbdf60a4c35bf /documentation
parent0f3aece52d31a82065d4ee1f3d7be0dac73d4411 (diff)
downloadpoky-402b7ce9df5522b08b9d3d547407f137938a3ffe.tar.gz
sdk-manual: Updated the "Makefile-Based Projects" section.
Expanded this section to contain a figure of the flow and an example that showcases the ways to override and use SDK environment and Makefile variables. (From yocto-docs rev: 834c059c1df4e8328248ea86fa23ca9a397351fa) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/sdk-manual/sdk-working-projects.xml285
1 files changed, 230 insertions, 55 deletions
diff --git a/documentation/sdk-manual/sdk-working-projects.xml b/documentation/sdk-manual/sdk-working-projects.xml
index f8be5c1528..d8cc4229dc 100644
--- a/documentation/sdk-manual/sdk-working-projects.xml
+++ b/documentation/sdk-manual/sdk-working-projects.xml
@@ -222,8 +222,8 @@
222 <para> 222 <para>
223 This section presents a simple Makefile development flow and 223 This section presents a simple Makefile development flow and
224 provides an example that lets you see how you can use 224 provides an example that lets you see how you can use
225 cross-toolchain environment variables to replace or override 225 cross-toolchain environment variables and Makefile variables
226 variables used in your Makefile. 226 during development.
227 <imagedata fileref="figures/sdk-makefile-flow.png" width="6in" height="7in" align="center" /> 227 <imagedata fileref="figures/sdk-makefile-flow.png" width="6in" height="7in" align="center" />
228 </para> 228 </para>
229 229
@@ -233,7 +233,7 @@
233 <itemizedlist> 233 <itemizedlist>
234 <listitem><para> 234 <listitem><para>
235 <emphasis>Case 1 - No Variables Set in the 235 <emphasis>Case 1 - No Variables Set in the
236 <filename>Makefile</filename> that Map to Equivalent 236 <filename>Makefile</filename> Map to Equivalent
237 Environment Variables Set in the SDK Setup Script:</emphasis> 237 Environment Variables Set in the SDK Setup Script:</emphasis>
238 Because matching variables are not specifically set in the 238 Because matching variables are not specifically set in the
239 <filename>Makefile</filename>, the variables retain their 239 <filename>Makefile</filename>, the variables retain their
@@ -255,21 +255,19 @@
255 that Map to Equivalent Environment Variables from the 255 that Map to Equivalent Environment Variables from the
256 SDK Setup Script:</emphasis> 256 SDK Setup Script:</emphasis>
257 Executing the <filename>Makefile</filename> from the 257 Executing the <filename>Makefile</filename> from the
258 command line results in the environment settings of the 258 command line results in the environment variables being
259 variables being overwritten. 259 overwritten.
260 In this case, the command-line content is used. 260 In this case, the command-line content is used.
261 <note>
262 The one exception to this is if you use the following
263 command-line option:
264 <literallayout class='monospaced'>
265 $ make -e <replaceable>target</replaceable>
266 </literallayout>
267 Using the "-e" option with <filename>make</filename>
268 causes the environment variables to be used during
269 the build.
270 </note>
271 </para></listitem> 261 </para></listitem>
272 </itemizedlist> 262 </itemizedlist>
263 <note>
264 Regardless of how you set your variables, if you use
265 the "-e" option with <filename>make</filename>, the
266 variables from the SDK setup script take precedence:
267 <literallayout class='monospaced'>
268 $ make -e <replaceable>target</replaceable>
269 </literallayout>
270 </note>
273 </para> 271 </para>
274 272
275 <para> 273 <para>
@@ -280,58 +278,235 @@
280 <para> 278 <para>
281 In a new shell environment variables are not established for the 279 In a new shell environment variables are not established for the
282 SDK until you run the setup script. 280 SDK until you run the setup script.
283 For example, the following commands show null values for four 281 For example, the following commands show a null value for the
284 variables that are set when you run the SDK environment setup 282 compiler variable (i.e.
285 script for a 64-bit build host and an i586-tuned target 283 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>).
286 architecture for a <filename>core-image-sato</filename> image
287 using the current &DISTRO; Yocto Project release:
288 <literallayout class='monospaced'> 284 <literallayout class='monospaced'>
289 $ echo ${CC} 285 $ echo ${CC}
290 286
291 $ echo ${LD} 287 $
292
293 $ echo ${CFLAGS}
294
295 $ echo ${CXXFLAGS}
296 </literallayout> 288 </literallayout>
297 Running the setup script and then echoing the variables shows the 289 Running the SDK setup script for a 64-bit build host and an
298 values established for the SDK: 290 i586-tuned target architecture for a
291 <filename>core-image-sato</filename> image using the current
292 &DISTRO; Yocto Project release and then echoing that variable
293 shows the value established through the script:
299 <literallayout class='monospaced'> 294 <literallayout class='monospaced'>
300 $ source /opt/poky/2.5/environment-setup-i586-poky-linux 295 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
301 $ echo ${CC} 296 $ echo ${CC}
302 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux 297 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
303 $ echo ${LD}
304 i586-poky-linux-ld --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
305 $ echo ${CFLAGS}
306 -O2 -pipe -g -feliminate-unused-debug-types
307 $ echo ${CXXFLAGS}
308 -O2 -pipe -g -feliminate-unused-debug-types
309 </literallayout> 298 </literallayout>
310 </para> 299 </para>
311 300
312 <para role='writernotes'> 301 <para>
313 NEED REST OF THE EXAMPLE. 302 To illustrate variable use, work through this simple "Hello World!"
314 WORKING ON GETTING IT TO WORK PROPERLY. 303 example:
315 </para> 304 <orderedlist>
305 <listitem><para>
306 <emphasis>Create a Working Directory and Populate It:</emphasis>
307 Create a clean directory for your project and then make
308 that directory your working location.
309 <literallayout class='monospaced'>
310 $ mkdir $HOME/helloworld
311 $ cd $HOME/helloworld
312 </literallayout>
313 After setting up the directory, populate it with files
314 needed for the flow.
315 You need a <filename>main.c</filename> file from which you
316 call your function, a <filename>module.h</filename> file
317 to contain headers, and a <filename>module.c</filename>
318 that defines your function.
319 </para>
316 320
317<!-- 321 <para>Create the three files as follows:
318To illustrate this, consider the following four cross-toolchain 322 <itemizedlist>
319 environment variables: 323 <listitem><para>
320 <literallayout class='monospaced'> 324 <emphasis><filename>main.c</filename>:</emphasis>
321 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>="i586-poky-linux-gcc -m32 -march=i586 &DASH;&DASH;sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux" 325 <literallayout class='monospaced'>
322 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>="i586-poky-linux-ld &DASH;&DASH;sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux" 326 #include "module.h"
323 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>="-O2 -pipe -g -feliminate-unused-debug-types" 327 void sample_func();
324 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>="-O2 -pipe -g -feliminate-unused-debug-types" 328 int main()
325 </literallayout> 329 {
326 Now, consider the following three cases: 330 sample_func();
327 <note> 331 return 0;
328 For information on the variables set up by the cross-toolchain 332 }
329 environment setup script, see the 333 </literallayout>
330 "<link linkend='sdk-running-the-extensible-sdk-environment-setup-script'>Running the Extensible SDK Environment Setup Script</link>" 334 </para></listitem>
331 section. 335 <listitem><para>
332 </note> 336 <emphasis><filename>module.h</filename>:</emphasis>
337 <literallayout class='monospaced'>
338 #include &lt;stdio.h&gt;
339 void sample_func();
340 </literallayout>
341 </para></listitem>
342 <listitem><para>
343 <emphasis><filename>module.c</filename>:</emphasis>
344 <literallayout class='monospaced'>
345 #include "module.h"
346 void sample_func()
347 {
348 printf("Hello World!");
349 printf("\n");
350 }
351 </literallayout>
352 </para></listitem>
353 </itemizedlist>
354 </para></listitem>
355 <listitem><para>
356 <emphasis>Source the Cross-Toolchain Environment Setup File:</emphasis>
357 As described earlier in the manual, installing the
358 cross-toolchain creates a cross-toolchain environment setup
359 script in the directory that the SDK was installed.
360 Before you can use the tools to develop your project,
361 you must source this setup script.
362 The script begins with the string "environment-setup"
363 and contains the machine architecture, which is
364 followed by the string "poky-linux".
365 For this example, the command sources a script from the
366 default SDK installation directory that uses the
367 32-bit Intel x86 Architecture and the
368 &DISTRO_NAME; Yocto Project release:
369 <literallayout class='monospaced'>
370 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
371 </literallayout>
372 </para></listitem>
373 <listitem><para>
374 <emphasis>Create the <filename>Makefile</filename>:</emphasis>
375 For this example, the Makefile contains two lines that
376 can be used to set the <filename>CC</filename> variable.
377 One line is identical to the value that is set when you
378 run the SDK environment setup script, and the other line
379 sets <filename>CC</filename> to "gcc", the default GNU
380 compiler on the build host:
381 <literallayout class='monospaced'>
382 # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
383 # CC="gcc"
384 all: main.o module.o
385 ${CC} main.o module.o -o target_bin
386 main.o: main.c module.h
387 ${CC} -I . -c main.c
388 module.o: module.c module.h
389 ${CC} -I . -c module.c
390 clean:
391 rm -rf *.o
392 rm target_bin
393 </literallayout>
394 </para></listitem>
395 <listitem><para>
396 <emphasis>Make the Project:</emphasis>
397 Use the <filename>make</filename> command to create the
398 binary output file.
399 Because variables are commented out in the Makefile,
400 the value used for <filename>CC</filename> is the value
401 set when the SDK environment setup file was run:
402 <literallayout class='monospaced'>
403 $ make
404 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
405 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
406 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
407 </literallayout>
408 From the results of the previous command, you can see that
409 the compiler used was the compiler established through
410 the <filename>CC</filename> variable defined in the
411 setup script.</para>
412
413 <para>You can override the <filename>CC</filename>
414 environment variable with the same variable as set from
415 the Makefile by uncommenting the line in the Makefile
416 and running <filename>make</filename> again.
417 <literallayout class='monospaced'>
418 $ make clean
419 rm -rf *.o
420 rm target_bin
421 #
422 # Edit the Makefile by uncommenting the line that sets CC to "gcc"
423 #
424 $ make
425 gcc -I . -c main.c
426 gcc -I . -c module.c
427 gcc main.o module.o -o target_bin
428 </literallayout>
429 As shown in the previous example, the cross-toolchain
430 compiler is not used.
431 Rather, the default compiler is used.</para>
432
433 <para>This next case shows how to override a variable
434 by providing the variable as part of the command line.
435 Go into the Makefile and re-insert the comment character
436 so that running <filename>make</filename> uses
437 the established SDK compiler.
438 However, when you run <filename>make</filename>, use a
439 command-line argument to set <filename>CC</filename>
440 to "gcc":
441 <literallayout class='monospaced'>
442 $ make clean
443 rm -rf *.o
444 rm target_bin
445 #
446 # Edit the Makefile to comment out the line setting CC to "gcc"
447 #
448 $ make
449 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
450 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
451 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
452 $ make clean
453 rm -rf *.o
454 rm target_bin
455 $ make CC="gcc"
456 gcc -I . -c main.c
457 gcc -I . -c module.c
458 gcc main.o module.o -o target_bin
459 </literallayout>
460 In the previous case, the command-line argument overrides
461 the SDK environment variable.</para>
462
463 <para>In this last case, edit Makefile again to use the
464 "gcc" compiler but then use the "-e" option on the
465 <filename>make</filename> command line:
466 <literallayout class='monospaced'>
467 $ make clean
468 rm -rf *.o
469 rm target_bin
470 #
471 # Edit the Makefile to use "gcc"
472 #
473 $ make
474 gcc -I . -c main.c
475 gcc -I . -c module.c
476 gcc main.o module.o -o target_bin
477 $ make clean
478 rm -rf *.o
479 rm target_bin
480 $ make -e
481 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
482 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
483 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
484 </literallayout>
485 In the previous case, the "-e" option forces
486 <filename>make</filename> to use the SDK environment
487 variables regardless of the values in the Makefile.
488 </para></listitem>
489 <listitem><para>
490 <emphasis>Execute Your Project:</emphasis>
491 To execute the project (i.e.
492 <filename>target_bin</filename>), use the following
493 command:
494 <literallayout class='monospaced'>
495 $ ./target_bin
496 Hello World!
497 </literallayout>
498 <note>
499 If you used the cross-toolchain compiler to build
500 <filename>target_bin</filename> and your build host
501 differs in architecture from that of the target
502 machine, you need to run your project on the target
503 device.
504 </note>
505 As expected, the project displays the "Hello World!"
506 message.
507 </para></listitem>
508 </orderedlist>
333 </para> 509 </para>
334-->
335 </section> 510 </section>
336</chapter> 511</chapter>
337<!-- 512<!--