This chapter contains the following sections:
Introduction
Control Program
Calling the Control Program
Make Utility
Calling the Make Utility
Writing a Makefile
Archiver
Calling the Archiver
Examples
The TASKING toolchain for the TriCore processor family comes with a number of utilities. The utilities are not actually part of the toolchain provide useful extra features. The utilities are only available as command line tools.
cctc A control program for the TriCore toolchain. The control program invokes all tools in the toolchain and lets you quickly generate an absolute object file from C source input files.
mktc A utility program to maintain, update, and reconstruct groups of programs. The make utility looks whether files are out of date, rebuilds them and determines which other files as a consequence also need to be rebuild.
artc An ELF archiver. With this utility you create and maintain object library files.
The control program cctc is a tool that invokes all tools in the toolchain for you. It provides a quick and easy way to generate the final absolute object file out of your C sources without the need to invoke the compiler, assembler and linker manually.
You can only call the control program from the command line. The invocation syntax is
cctc [ [option]... [file]... ]...
For example:
cctc -v test.c
The control program calls all tools in the toolchain and generates the absolute object file test.elf. With the control program option -v you can see how the control program calls the tools:
+ c:\ctc\bin\ctc -o cc7b40ab.src test.c + c:\ctc\bin\astc -o test.o cc7b40ab.src + c:\ctc\bin\ltc -r test.o -lc -lfp -lrt -Lc:\ctc\lib\tc1 -occ7b40af.out + c:\ctc\bin\ltc -FELF -M -dtc.lsl cc7b40af.out -otest.elf
The control program produces unique filenames for intermediate steps in the compilation process (such as cc7b40ab.src in the example above) which are removed afterwards. The control program prevents preprocessing of the compiler generated assembly file because the compiler does not generate any preprocessor symbols. Normally, (hand-written) assembly input files are preprocessed first.
The control program recognizes the following input files:
The following control program options are available:
Description | Option | ||||||||||||||||||||
Display options Display version header |
-? -V | ||||||||||||||||||||
Verbose option: show commands invoked Verbose option: show commands without executing |
-v -v0 | ||||||||||||||||||||
Input files | |||||||||||||||||||||
Force C files to C++ mode Force C++ files to C mode Read options from file |
-c++ -noc++ -f file
Process |
|
Stop after C++ files are compiled to intermediate C (.ic) | Stop after C++ files or C files are compiled to assembly (.src) Stop after the files are assembled to objects (.o) Stop after the files are linked to a linker object file (.out)
-cc | -cs -c -cl
Force invocation of the C++ muncher | Force invocation of the C++ linker
-cm | -cp
Libraries |
|
Do not link with the standard libraries | Use floating-point library with support for trapping
-nolib | -fptrap
Code generation |
|
Select CPU type | Generate symbolic debug information CPU functional problem bypasses
-Ccpu | -g --silicon- bug=bug,...
Output files |
|
Do not generate a linker map file | Specify name for the output file Keep temporary files Enable C and assembler warnings for C++ files
-nomap | -o file -tmp -wc++
Produce an ELF/DWARF object file | Produce an IEEE-695 object file Produce an Intel Hex object file Produce an Motorola S-record object file
-elf | -ieee -ihex -srec |
Table 8-1: Overview of control program options
For a complete list and description
of all control program options, see section 4.4,
Control Program Options, in Chapter Tool Options of the Reference Guide.
The options in table 8-1 are options that the control program interprets itself. The control program however can also pass an option directly to a tool. Such an option is not interpreted by the control program but by the tool itself. The next example illustrates how an option is passed directly to the linker to link a user defined library:
cctc -Wlk-lmylib test.c
Use the following options to pass arguments to the various tools:
Description | Option |
Pass argument directly to the C++ compiler Pass argument directly to the C++ pre-linker Pass argument directly to the C compiler Pass argument directly to the assembler Pass argument directly to the second assembler Pass argument directly to the linker Pass argument directly to the locating phase of the linker |
-Wcparg -Wplarg -Wcarg -Waarg -Wpcparg -Wlkarg -Wlcarg |
Table 8-2: Control program options to pass an option directly to a tool
If you specify an unknown option to the control program,
the control program looks if it is an option for a specific tool. If so,
it passes the option directly to the tool. However, it is recommended to use
the control program options to passing arguments directly to tools.
With the environment variable CCTCOPT you can define options and/or arguments that the control programs always processes before the command line arguments.
For example, if you use the control program always with the option -nomap (do not produce a linker map file), you can specify "-nomap" to the environment variable CCTCOPT.
See section 1.3.2
, Configuring the Command Line Environment, in Chapter Software Installation.
If you are working with large quantities of files, or if you need to build several targets, it is rather time-consuming to call the individual tools to compile, assemble, link and locate all your files.
You save already a lot of typing if you use the control program cctc and define an options file. You can even create a batch file or script that invokes the control program for each target you want to create. But with these methods all files are completely compiled, assembled, linked and located to obtain the target file, even if you changed just one C source. This may demand a lot of (CPU) time on your host.
The make utility mktc is a tool to maintain, update, and reconstruct groups of programs. The make utility looks which files are out-of-date and only recreates these files to obtain the updated target.
In order to build a target, the make utility needs the following input:
In addition, the make utility also reads the file
mktc.mk which contains predefined rules and macros. See section 8.3.2
, Wrtiting a Makefile.
The makefile contains the relationships among your files (called dependencies) and the commands that are necessary to create each of the files (called rules). Typically, the absolute object file (.elf) is updated by locating the .out file, which depends on .o files and libraries that must be linked together. The .o files on their turn depend on .src files that must be assembled and finally, .src files depend on the C source files (.c) that must be compiled. In the makefile makefile this looks like:
test.src : test.c # dependency ctc test.c # rule
test.o : test.src astc test.src
test.out : test.o ltc test.o -lc -lfp -lrt -otest.out
test.elf : test.out ltc test.out -otest.elf
You can use any command that is valid on the command line as a rule in the makefile. So, rules are not restricted to invocation of the toolchain.
To build the target test.elf, call mktc with one of the following lines:
mktc test.elf
mktc -f mymake.mak test.elf
Default the make utility reads makefile so you do not need to specify it on the command line. If you want to use another name for
the makefile, use the option -f my_makefile.
If you do not specify a target, mktc
uses the first target defined in the makefile. In this example it would build
test.src instead
of test.elf.
The make utility now tries to build test.elf based on the makefile and peforms the following steps:
1. From the makefile the make utility reads that test.elf depends on test.out.
2. If test.out does not exist or is out-of-date, the make utility first tries to build this file and reads from the makefile test.out depends on test.o.
3. If test.o does exist, the make utility now creates test.out by executing the rule for it: ltc test.o -lc -lfp -lrt -otest.out.
4. There are no other files necessary to create test.elf so the make utility now can use test.out to create test.elf by executing the rule ltc test.out -otest.elf.
The make utility has now build test.elf but it only used the linker to update test.out and the linker to create test.elf.
If you compare this to the control program:
cctc test.c
This invocation has the same effect but now all files are recompiled (assembled, linked and located).
You can only call the make utility from the command line. The invocation syntax is
mktc [ [options] [targets] [macro=def]... ]
For example:
mktc test.elf
target You can specify any target that is defined in the makefile. A target can also be one of the intermediate files specified in the makefile.
macro= def Macro definition. This definition remains fixed for the mktc invocation. It overrides any regular definitions for the specified macro within the makefiles and from the environment. It is inherited by subordinate mktc's but act as an environment variable for these. That is, depending on the -e setting, it may be overridden by a makefile definition.
The following make utility options are available:
Description | Option | ||||
Display options Display version header |
-? -V | ||||
Verbose | |||||
Print makefile lines while being read Display time comparisons which indicate a target is out of date Display current date and time Verbose option: show commands without executing (dry run) Do not show commands before execution Do not build, only indicate whether target is up-to-date |
-D/-DD -d/-dd -time -n -s -q | ||||
Input files | |||||
Use makefile instead of the standard makefile makefile Change to directory before reading the makefile Read options from file Do not read the mktc.mk file |
-f makefile -G path -m file -r | ||||
Process | |||||
Always rebuild target without checking whether it is out-of-date Run as a child process Environment variables override macro definitions Do not remove temporary files On error, only stop rebuilding current target Overrule the option -k (only stop rebuilding current target) Make all target files precious Touch the target files instead of rebuilding them Treat target as if it has just been reconstructed |
-a -c -e -K -k -S -p -t -W target
Error messages |
|
Redirect error messages and verbose messages to a file | Ignore error codes returned by commands Redirect messages to standard out instead of standard error Show extended error messages
-err file | -i -w -x |
Table 8-3: Overview of control program options
For a complete list and description
of all control program options, see section 4.5,
Make Utility Options, in Chapter Tool Options of the Reference Guide.
In addition to the standard makefile makefile, the make utility always reads the makefile mktc.mk before other inputs. This system makefile contains implicit rules and predefined macros that you can use in the makefile makefile.option -r (Do not read the mktc.mk file)
With the
option -r (Do not read the mktc.mk file) you can prevent the make utility from reading mktc.mk.
The default name of the makefile is makefile in the current directory. If on a UNIX system this file is not found, the file Makefile is used as the default. If you want to use other makefiles, use the option -f my_makefile.
The makefile can contain a mixture of:
To continue a line on the next line, terminate it with a backslash (\):
# this comment line is continued\ on the next line
If a line must end with a backslash, add an empty macro.
# this comment line ends with a backslash \$(EMPTY) # this is a new line
The basis of the makefile is a set of targets, dependencies and rules. A target entry in the makefile has the following format:
target ... : [dependency ...] [; rule] [rule] ...
Target lines must always start at the beginning of a line, leading white spaces (tabs or spaces) are not allowed. A target line consists of one or more targets, a semicolon and a set of files which are required to build the target (dependencies). The target itself can be one or more filenames or symbolic names.:
all: demo.elf final.elf
demo.elf final.elf: test.out demo.out final.out
You can now can specify the target you want to build to the make utility. The following three invocations all have the same effect:
mktc mktc all mktc demo.elf final.elf
If you do not specify a target, the first target in the makefile (in this example all) is build. The target all depends on demo.elf and final.elf so the second and third invocation have also the same effect and the files demo.elf and final.elf are built.
In MS-DOS you can normally use colons to denote drive
letters. The following works as intended: c:foo.o : a:foo.c
If a target is defined in more than one target line, the dependencies are added to form the target's complete dependency list:
all: demo.elf # These two lines are equivalent with: all: final.elf # all: demo.elf final.elf
For target lines, macros and functions are expanded at the moment they are read by the make utility. Normally macros are not expanded until the moment they are actually used.
There are a number of special targets. Their names begin with a period.
.DEFAULT: If you call the make utility with a target that has no definition in the make file, this target is build.
.DONE: When the make utility has finished building the specified targets, it continues with the rules following this target.
.IGNORE: Non-zero error codes returned from commands are ignored. Encountering this in a makefile is the same as specifying the option -i on the command line.
.INIT: The rules following this target are executed before any other targets are build.
.SILENT: Commands are not echoed before executing them. Encountering this in a makefile is the same as specifying the option -s on the command line.
.SUFFIXES: This target specifies a list of file extensions. Instead of building a completely specified target, you now can build a target that has a certain file extension. Implicit rules to build files with a number of extensions are included in the system makefile mktc.mk.
.PRECIOUS: Dependency files mentioned for this target are never removed. Normally, if a command in a rule returns an error or when the target construction is interrupted, the make utility removes that target file. You can use the -p command line option to make all target files precious.
A line with leading white space (tabs or spaces) is considered as a rule and associated with the most recently preceding dependency line. A rule is a line with commands that are executed to build the associated target. A target-dependency line can be followed by one or more rules.
final.src : final.c # target and dependency mv test.c final.c # rule1 ctc final.c # rule2
You can precede a rule with one or more of the following characters:
@ does not echo the command line, except if -n is used.
- the make utility ignores the exit code of the command (ERRORLEVEL in MS-DOS). Normally the make utility stops if a non-zero exit code is returned. This is the same as specifying the option -i on the command line or specifying the special .IGNORE target.
+ The make utility uses a shell or COMMAND.COM to execute the command. If the '+' is not followed by a shell line, but the command is a DOS command or if redirection is used (<, |, >), the shell line is passed to COMMAND.COM anyway. For UNIX, redirection, backquote (`) parentheses and variables force the use of a shell.
cd c:\ctc\bin ;\ cctc -V
The ';' must always directly be followed by the '\' token. Whitespace is not removed when it is at the end of the previous command line or when it is in front of the next command line. The use of the
';' as an operator for a command (like a semicolon ';' separated list with
each item on one line) and the '\' as a layout tool is not supported, unless
they are separated with whitespace.
The make utility can generate inline temporary files. If a line contains <<LABEL (no whitespaces!) then all subsequent lines are placed in a temporary file until the line LABEL is encountered. Next, <<LABEL is replaced by the name of the temporary file.
Example:
ltc -o $@ -f <<EOF $(separate "\n" $(match .o $!)) $(separate "\n" $(match .a $!)) $(LKFLAGS) EOF
The three lines between <<EOF and EOF are written to a temporary file (for example mkce4c0a.tmp), and the rule is rewritten as ltc -o $@ -f mkce4c0a.tmp.
Instead of specifying a specific target, you can also define a general target. A general target specifies the rules to generate a file with extension .ex1 to a file with extension .ex2. For example:
.SUFFIXES: .c .c.src : ltc $<
Read this as: to build a file with extension .src out of a file with extension .c, call the compiler with $<. $< is a predefined macro that is replaced with the basename of the specified file. The special target .SUFFIXES: is followed by a list of file extensions of the files that are required to build the target.
Implicit rules are stored in the system makefile mktc.mk and are intimately tied to the .SUFFIXES special target. Each dependency that follows the .SUFFIXES target, defines an extension to a filename which must be used to build another file. The implicit rules then define how to actually build one file from another. These files share a common basename, but have different extensions.
If the specified target on the command line is not defined in the makefile or has not rules in the makefile, the make utility looks if there is an implicit rule to build the target.
This makefile says that prog.out depends on two files prog.o and sub.o, and that they in turn depend on their corresponding source files (prog.c and sub.c) along with the common file inc.h.
LIB = -lc # macro prog.out: prog.o sub.o ltc prog.o sub.o $(LIB) -o prog.out prog.o: prog.c inc.h ctc prog.c astc prog.src sub.o: sub.c inc.h ctc sub.c astc sub.src
The following makefile uses implicit rules (from mktc.mk) to perform the same job.
LKFLAGS = -lc # macro used by implicit rules prog.out: prog.o sub.o # implicit rule used prog.o: prog.c inc.h # implicit rule used sub.o: sub.c inc.h # implicit rule used
makefile Description of dependencies and rules.
Makefile Alternative to makefile, for UNIX.
mktc.mk Default dependencies and rules.
mktc returns an exit status of 1 when it halts as a result of an error. Otherwise it returns an exit status of 0.
A macros is a symbol names that is replaced with it's definition before the makefile is executed. Although the macro name can consist of lower case or upper case characters, upper case is an accepted convention. The general form of a macro definition is:
MACRO = text and more text
Spaces around the equal sign are not significant. To use a macro, you must access it's contents:
$(MACRO) # you can read this as ${MACRO} # the contents of macro MACRO
If the macro name is a single character, the parentheses are optional. Note that the expansion is done recursively, so the body of a macro may contain other macros. These macros are expanded when the macro is actually used, not at the point of definition:
FOOD = $(EAT) and $(DRINK) EAT = meat and/or vegetables DRINK = water export FOOD
The macro FOOD is expanded as meat and/or vegetables and water at the moment it is used in the export line.
MAKE Holds the value mktc. Any line which uses MAKE, temporarily overrides the option -n (Show commands without executing), just for the duration of the one line. This way you can test nested calls to MAKE with the option -n.
MAKEFLAGS
Holds the set of options provided to mktc (except
for the options -f and -d). If this macro
is exported to set the environment variable MAKEFLAGS, the set of options is processed before any command line options. You can pass this macro explicitly to nested mktc's, but it is
also available to these invocations as an environment variable.
PRODDIR Holds the name of the directory where mktc is installed. You can use this macro to refer to files belonging to the product, for example a library source file.
DOPRINT = $(PRODDIR)/lib/src/_doprint.c
DOPRINT = /ctc/lib/src/_doprint.c
SHELLCMD Holds the default list of commands which are local to the SHELL. If a rule is an invocation of one of these commands, a SHELL is automatically spawned to handle it.
TMP_CCPROG
Holds the name of the control program: cctc. If this macro and the TMP_CCOPT macro are set and the command line argument list for the control program exceeds 127 characters, then mktc creates a temporary file with the command
line arguments. mktc calls the control program with the temporary file as command input file.
TMP_CCOPT
Holds -f, the control program option that tells it
to read options from a file. (This macro is only available for the Windows command prompt version of mktc.)
$ This macro translates to a dollar sign. Thus you can use "$$" in the makefile to represent a single "$".
There are several dynamically maintained macros that are useful as abbreviations within rules. It is best not to define them explicitly.
$* The basename of the current target.
$< The name of the current dependency file.
$@ The name of the current target.
$? The names of dependents which are younger than the target.
$! The names of all dependents.
The $< and $* macros are normally used for implicit rules. They may be unreliable when used within explicit target command lines. All macros may be suffixed with F to specify the Filename components (e.g. ${*F}, ${@F}). Likewise, the macros $*, $< and $@ may be suffixed by D to specify the directory component.
The result of the $* macro is always without double quotes
("), regardless of the original target having double quotes (") around
it or not.
The result of using the suffix F (Filename component) or D (Directory component) is also always without double quotes ("), regardless of
the original contents having double quotes (") around it or not.
A function not only expands but also performs a certain operation. Functions syntactically look like macros but have embedded spaces in the macro name, e.g. '$(match arg1 arg2 arg3 )'. All functions are built-in and currently there are five of them: match, separate, protect, exist and nexist.
match The match function yields all arguments which match a certain suffix:
$(match .o prog.o sub.o mylib.a)
prog.o sub.o
separate The separate function concatenates its arguments using the first argument as the separator. If the first argument is enclosed in double quotes then '\n' is interpreted as a newline character, '\t' is interpreted as a tab, '\ooo' is interpreted as an octal value (where, ooo is one to three octal digits), and spaces are taken literally. For example:
$(separate "\n" prog.o sub.o)
prog.o sub.o
$(separate "\n" $(match .o $!))
protect The protect function adds one level of quoting. This function has one argument which can contain white space. If the argument contains any white space, single quotes, double quotes, or backslashes, it is enclosed in double quotes. In addition, any double quote or backslash is escaped with a backslash.
echo $(protect I'll show you the "protect" function)
echo "I'll show you the \"protect\" function"
exist The exist function expands to its second argument if the first argument is an existing file or directory.
$(exist test.c cctc test.c)
cctc test.c
nexist The nexist function is the opposite of the exist function. It expands to its second argument if the first argument is not an existing file or directory.
$(nexist test.src cctc test.c)
Lines containing ifdef, ifndef, else or endif are used for conditional processing of the makefile. They are used in the following way:
ifdef macro-name if-lines else else-lines endif
The if-lines and else-lines may contain any number of lines or text of any kind, even other ifdef, ifndef, else and endif lines, or no lines at all. The else line may be omitted, along with the else-lines following it.
First the macro-name after the if command is checked for definition. If the macro is defined then the if-lines are interpreted and the else-lines are discarded (if present). Otherwise the if-lines are discarded; and if there is an else line, the else-lines are interpreted; but if there is no else line, then no lines are interpreted.
When using the ifndef line instead of ifdef, the macro is tested for not being defined. These conditional lines can be nested up to 6 levels deep.
See also Defining Macros
in section 4.5,
Make Utility Options, in Chapter Tools Options of the Reference Guide.
Anything after a "#" is considered as a comment, and is ignored. If the "#" is inside a quoted string, it is not treated as a comment. Completely blank lines are ignored.
test.src : test.c # this is comment and is ctc test.c # ignored by the make utility
An include line is used to include the text of another makefile (like including a .h file in a C source). Macros in the name of the included file are expanded before the file is included. Include files may be nested.
include makefile2
An export line is used to export a macro definition to the environment of any command executed by the make utility.
GREETING = Hello
export GREETING
This example creates the environment variable GREETING with the value Hello. The macros is exported at the moment the export line is read so the macro definition has to proceed the export line.
The archiver artc is a program to build and maintain your own library files. A library file is a file with extension .a and contains one or more object files (.o) that may be used by the linker.
The archiver has five main functionalities:
The archiver takes the following files for input and output:
Figure 8-1: artc ELF/DWARF archiver and library maintainer
The linker optionally includes object modules from a library if that module resolves an external symbol definition in one of the modules that are read before.
You can only call the archiver from the command line. The invocation syntax is:
artc key_option [sub_option...] library [object_file]
key_option With a key option you specify the main task which the archiver should perform. You must always specify a key option.
sub_option Sub-options specify into more detail how the archiver should perform the task that is specified with the key option. It is not obligatory to specify sub-options.
library The name of the library file on which the archiver performs the specified action. You must always specify a library name, except for the option -? and -V. When the library is not in the current directory, specify the complete path (either absolute or relative) to the library.
object_file The name of an object file. You must always specify an object file name when you add, extract, replace or remove an object file from the library.
The following archiver options are available:
Description | Option | Sub-option | ||||||||||||
Display options | -? | |||||||||||||
Display version header | -V | |||||||||||||
Print object module to standard output | -p | |||||||||||||
Main functions | ||||||||||||||
Delete object module from library | -d |
-v
Move object module to another position |
-m |
-a -b -v |
Replace or add an object module |
-r |
-a -b -c -u -v |
Print a table of contents of the library |
-t |
-s0 -s1 |
Extract an object module from the library |
-x |
-v | |
Table 8-4: Overview of archiver options and sub-options
For a complete list and description
of all archiver options, see section 4.6,
Archiver Options, in Chapter Tool Options of the Reference Guide.
If you add modules to a library that does not yet exist, the library is created. To create a new library with the name mylib.a and add the object modules cstart.o and calc.o to it:
artc -r mylib.a cstart.o calc.o
If you add a new module to an existing library, the module is added at the end of the module. (If the module already exists in the library, it is replaced.)
artc -r mylib.a mod3.o
To inspect the contents of the library:
artc -t mylib.a
The library has the following contents:
cstart.o calc.o mod3.o
To move mod3.o to the beginning of the library, position it just before cstart.o:
artc -mb cstart.o mylib.a mod3.o
To delete the object module cstart.eln from the library mylib.a:
artc -d mylib.a cstart.o
Extract all modules from the library mylib.a:
artc -x mylib.a