From RTSC-Pedia
 | [printable version] | offline version generated on 04-Aug-2010 21:08 UTC |   |
Consuming Configurable Content/makefiles
RTSC configuration with makefiles
Contents |
Since the compile and link syntax you use to build a C/C++ application is toolchain-dependent, we show how to leverage the compiler.opt and linker.cmd files generated by configuro using the C/C++ compilers and linkers supplied with three very different toolchains: the toolchains from TI, GNU, and Microsoft. For details about the compiler options placed in compiler.opt for various targets supporting these toolchains, see Existing Targets.
The example make files in the following sections all use GNU make, which is delivered with the XDCtools product as XDCROOT/gmake. Each of these make files builds the "Hello World" application shown in Consuming Configurable Content and defines a build goal named "test". To build the application type "gmake all" and to build and run the application type "gmake test". When you run "gmake test", the last line displayed is the output of the application:
| | Hello World! |
When the configuro tool runs, you see messages similar to the following:
| | making package.mak (because of package.bld) ... generating interfaces for package hello (because ... configuring hello.x64 from package/cfg/hello_x64.cfg ... cl64 package/cfg/hello_x64.c ... |
Although the make files shown below are short and serve to illustrate the use of configuro in virtually any command line build environment, there are a number of subtleties that you should be aware of when integrating the configuro tool into a production GNU make based development environment. The Integrating with make section provides additional details about integration within make-based environments.
Integrating with TI Code Gen Tools
The following example makefile illustrates how to integrate RTSC configuration with the TI Code Gen Tools compiler and linker. The makefile runs configuro and uses the compiler.opt and linker.cmd files generated by configuro as part of the compile and link steps.
| > > | CGTOOLS = C:/CCStudio_v3.3/C6000/cgtools
CC = $(CGTOOLS)/bin/cl6x
LNK = $(CGTOOLS)/bin/lnk6x
RTS = $(CGTOOLS)/lib/rts6400.lib
CONFIG = hello
XDCTARGET = ti.targets.C64
XDCPLATFORM = ti.platforms.sim6xxx:TMS320C6416
.PRECIOUS: %/compiler.opt %/linker.cmd
%/linker.cmd %/compiler.opt : %.cfg
xs xdc.tools.configuro -c $(CGTOOLS) -t $(XDCTARGET) -p $(XDCPLATFORM) $<
%.obj : %.c $(CONFIG)/compiler.opt
$(CC) -@$(CONFIG)/compiler.opt -c $<
hello.out : hello.obj $(CONFIG)/linker.cmd
$(LNK) -o hello.out -c hello.obj $(CONFIG)/linker.cmd $(RTS)
test: hello.out
@$(CGTOOLS)/bin/load6x $< |
The lines marked with > above show how to run configuro and how to use its output with the compiler and linker to build an application. In this example, we could have omitted the platform specification because the default platform for the ti.targets.C64 target is already ti.platforms.sim6xxx:TMS320C6416. You can check this by looking at the C64.platform configuration parameter. While this would have simplified the makefile above, we explicitly set it here to illustrate how to build for a particular device.
Integrating with Microsoft C/C++ Tools
The following example makefile illustrates how to integrate RTSC configuration with the Microsoft Visual Studio compiler and linker. The makefile runs configuro and uses the compiler.opt and linker.cmd files generated by configuro as part of the compile and link steps.
| > > | CGTOOLS = "C:/Program Files/Microsoft Visual Studio 8"
CC = $(CGTOOLS)/vc/bin/cl
LNK = $(CGTOOLS)/vc/bin/link
RTS = -nodefaultlib -libpath:$(CGTOOLS)/vc/lib kernel32.lib msvcrt.lib
CONFIG = hello
XDCTARGET = microsoft.targets.Win32
.PRECIOUS: %/compiler.opt %/linker.cmd
%/linker.cmd %/compiler.opt : %.cfg
xs xdc.tools.configuro -c $(CGTOOLS) -t $(XDCTARGET) $<
%.obj : %.c $(CONFIG)/compiler.opt
$(CC) @$(CONFIG)/compiler.opt -c $<
hello.exe : hello.obj $(CONFIG)/linker.cmd
$(LNK) -out:$@ hello.obj @$(CONFIG)/linker.cmd $(RTS)
test: hello.exe
@$< |
The lines marked with > above show how to run configuro and how to use its output with the compiler and linker to build an application. No platform specification is needed because the default platform for each target in microsoft.targets is the one required for native execution on an x86 PC (host.platforms.PC).
Integrating with GNU gcc Tools
The following example illustrates how to integrate RTSC configuration with the GNU gcc compiler and linker. The makefile runs configuro and uses the compiler.opt and linker.cmd files generated by configuro as part of the compile and link steps.
| > > * | CGTOOLS = $(TOOLS)/gcc/3.2.1/Linux
CC = $(CGTOOLS)/bin/gcc
LNK = $(CGTOOLS)/bin/gcc
RTS = -lstdc++
CONFIG = hello
XDCTARGET = gnu.targets.Linux86
.PRECIOUS: %/compiler.opt %/linker.cmd
%.o : %.c # forget built-in rule to create .o files from .c sources
%/linker.cmd %/compiler.opt : %.cfg
xs xdc.tools.configuro -c $(CGTOOLS) -t $(XDCTARGET) $<
%.o : %.c $(CONFIG)/compiler.opt
$(CC) $(shell cat $(CONFIG)/compiler.opt) -c $<
hello.exe: hello.o $(CONFIG)/linker.cmd
$(LNK) -o $@ hello.o $(CONFIG)/linker.cmd $(RTS)
test: hello.exe
@$< |
The lines marked with > above highlight how to run configuro and how to use its output with the compiler and linker to build an application. No platform specification is needed because the default platform for the gnu.targets.Linux86 target is the one required for native execution on an x86 PC (host.platforms.PC).
Prior to version 4.2.4, the gcc compiler does not support an option to include other command line options from a file. However, this example accomplishes this by using GNU make's $(shell ...) function and the Linux cat command to copy the options to the compiler's command line before calling gcc; see the line marked by *.
Integrating with make
When integrating the configuration process into a make-based development environment there are a number of issues to be aware of. These issues fall into roughly three categories:
- make file syntax,
- rule definitions and proper dependency definitions, and
- GNU make specifics
Make file syntax. In GNU make files, you must always use a tab character to indent commands, not spaces. Much to the chagrin of every new makefile author, the tab character is how make determines the difference between commands to run and other makefile statements (variable definitions, goal dependencies, etc.) Also, you can split a command across two lines by terminating each line with the '\' character but you must be certain to not have any white space characters after the '\'.
Variable definitions that contain spaces (for example, product installation directories on Windows hosts) must be surrounded by quotes when passed to commands; otherwise, the command will see two arguments rather than a single argument with an embedded space. For more information about the syntax of makefiles and the operation of GNU make, see the online GNU make manual http://www.gnu.org/software/make/manual/make.html.
Rule definitions. When designing a make file, it's important to carefully specify when to run each command; otherwise, commands may be unnecessarily run or worse they may not run when they should be. In the case of configuro, you should re-run it whenever you do any of the following:
- Change the CFG file
- Change the target or platform
- Update a package used by your application
The configuro command uses specially generated make files to avoid running any unnecessary steps when you make the changes above. So, if you are not sure whether to run configuro, go ahead and run it; if nothing needs to be done, configuro quickly detects this and does nothing.
GNU make specifics. Over the years GNU make has evolved a number of capabilities that enable it to robustly manage even the most complex build requirements with minimal syntax. The short, seemly simple, makefile shown below belies several subtitles that can make the difference between a toy example and a robust integration with your build environment. In the remainder of this section, we review the subtitles embedded in this makefile.
| 1 2 3 4 | CGTOOLS = $(TOOLS)/gcc/3.2.1/Linux
CC = $(CGTOOLS)/bin/gcc
LNK = $(CGTOOLS)/bin/gcc
RTS = -lstdc++
CONFIG = hello
XDCTARGET = gnu.targets.Linux86
.PRECIOUS: %/compiler.opt %/linker.cmd
%.o : %.c # forget built-in rule to create .o files from .c sources
%/linker.cmd %/compiler.opt : %.cfg
xs xdc.tools.configuro -c $(CGTOOLS) -t $(XDCTARGET) $<
%.o : %.c $(CONFIG)/compiler.opt
$(CC) $(shell cat $(CONFIG)/compiler.opt) -c $<
hello.exe: hello.o $(CONFIG)/linker.cmd
$(LNK) -o $@ hello.o $(CONFIG)/linker.cmd $(RTS)
test: hello.exe
@$< |
Line 1 tells GNU make that, even though GNU make considers them to be intermediate files, compiler.opt and linker.cmd files should not be automatically deleted after they are no longer needed. When you start from a clean project, GNU make knows that to build hello.exe it must first build hello.o and, since no explicit rule is defined for hello.o, it infers that if it builds compiler.opt then it can apply the implicit rule on line 4. This "inference" causes GNU make to consider compiler.opt to be an intermediate file which it normally deletes when it is no longer needed; i.e., after hello.o is created. Without line 1, compiler.opt will not exist after hello.o is created and GNU make will re-run configuro every time you change hello.c!
Line 2 tells GNU make to ignore its built-in rules for converting C source (.c) files to object (.o) files. If you don't add this line GNU make will use its built-in rule in lieu of the rule defined on line 4 whenever compiler.opt does not exist. By removing the recipe for converting .c files into .o files without any prerequisites, GNU make is forced to ensure that $(CONFIG)/compiler.opt exists before any compilation of .c files to .o files.
Line 3 is a pattern rule that tells GNU make that configururo generates two output files from the one input .cfg file. This is critically important if you want to want to use GNU make's parallel build feature (e.g., --jobs=4). If, for example, you did not specify a pattern rule for configuro and you use parallel build, GNU make will spawn two separate configuro jobs to create both linker.cmd and compiler.opt. Not only will this waste valuable CPU cycles but the two jobs will overwrite each other's files and undoubtedly fail to produce valid output.
| [printable version] | offline version generated on 04-Aug-2010 21:08 UTC | |
