8 USING THE UTILITIES

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

8.1 Introduction

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.

8.2 Control Program

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.

8.2.1 Calling the Control Program

You can only call the control program from the command line. The invocation syntax is

For example:

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:

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.

Recognized input files

The control program recognizes the following input files:

Options of the control program

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:

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.

8.3 Make Utility

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.

Make process

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:

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.

Example

To build the target test.elf, call mktc with one of the following lines:

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:

This invocation has the same effect but now all files are recompiled (assembled, linked and located).

8.3.1 Calling the Make Utility

You can only call the make utility from the command line. The invocation syntax is

For example:

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.

Options of the make utility

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.

8.3.2 Writing a Makefile

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 (\):

If a line must end with a backslash, add an empty macro.

Targets and dependencies

The basis of the makefile is a set of targets, dependencies and rules. A target entry in the makefile has the following format:

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.:

You can now can specify the target you want to build to the make utility. The following three invocations all have the same effect:

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:

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.

Special Targets

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.

Rules

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.

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.

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:

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:

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

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.

Example

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

Files

makefile Description of dependencies and rules.
Makefile Alternative to makefile, for UNIX.
mktc.mk Default dependencies and rules.

Diagnostics

mktc returns an exit status of 1 when it halts as a result of an error. Otherwise it returns an exit status of 0.

Macro definitions

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:

Spaces around the equal sign are not significant. To use a macro, you must access it's contents:

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:

The macro FOOD is expanded as meat and/or vegetables and water at the moment it is used in the export line.

Predefined Macros

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.

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.

Functions

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:

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:

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.

exist The exist function expands to its second argument if the first argument is an existing file or directory.

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.

Conditional Processing

Lines containing ifdef, ifndef, else or endif are used for conditional processing of the makefile. They are used in the following way:

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.

Comment lines

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.

Include lines

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.

Export lines

An export line is used to export a macro definition to the environment of any command executed by the make utility.

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.

8.4 Archiver

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.

8.4.1 Calling the Archiver

You can only call the archiver from the command line. The invocation syntax is:

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.

Options of the archiver utility

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.

8.4.2 Examples

Create a new library

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:

Add a new module to an existing library

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.)

Print a list of object modules in the library

To inspect the contents of the library:

The library has the following contents:

Move an object module to another position

To move mod3.o to the beginning of the library, position it just before cstart.o:

Delete an object module from the library

To delete the object module cstart.eln from the library mylib.a:

Extract all modules from the library

Extract all modules from the library mylib.a:


Copyright © 2003 Altium BV