1.2. Invoking the Compiler¶
1.2.1. Usage¶
To invoke the tiarmclang compiler, enter:
tiarmclang [options] [filenames]
tiarmclang - Command that runs the compiler and other tools (the linker, for example).
options - Options that affect the way that the compiler tools process input files. These may include:
tiarmclang options - affect the behavior of the C/C++ compiler or the integrated GNU-syntax Arm assembler. These are described in more detail in the Compiler Options section. Additional information about the integrated GNU-syntax Arm assembler can be found in the Integrated GNU-Syntax Arm Assembler section.
Legacy TI-syntax Arm assembler options - are prefixed with either the -Wti-a, or -Xti-assembler option indicating that the option that follows should be passed directly to the legacy TI-syntax Arm assembler. Legacy TI-syntax Arm assembler options are described in more detail in the TI-Syntax Arm Assembler section. See Passing TI-Syntax Arm Assembler Options: -Wti-a, and -Xti-assembler for more about passing options to the assembler.
Linker options - are prefixed with either the -Wl, or -Xlinker option indicating that the option that follows should be passed directly to the linker. Linker options are described in more detail in Linker Options. See Passing Linker Options: -Wl, and -Xlinker for more about passing options to the linker.
Note
The linker is invoked by default from a tiarmclang command line, but you can disable the link step by specifying the -c option on the tiarmclang command line. You can invoke the linker by itself using the tiarmlnk command line.
filenames - One or more input files. These may include:
C source files - by default, an input file with a .c file extension is interpreted as a C source file. You may also use the -x c option to instruct tiarmclang to interpret subsequent input files as C source files.
C++ source files - by default, an input file with a .C or .cpp file extension is interpreted as a C++ source file. You may also use the -x c++ option to instruct tiarmclang to interpret subsequent input files as C++ source files.
ELF object files - by default, an input file with a .o file extension is interpreted as an ELF object file.
GNU-syntax Arm assembly source files - by default, an input file with either a .s or .S file extension is interpreted as a GNU-syntax Arm assembly source file. In the case of an input file with a .S extension, the input file is run through the C pre-processor and the output of the C pre-processor is passed to the integrated GNU-syntax Arm assembler. You may use the -x assembler option to instruct tiarmclang to interpret an input file as a GNU-syntax Arm assembly source file. Similarly, you may use the -x assembler-with-cpp option to instruct tiarmclang to run the input file through the C pre-processor before passing the output of the C pre-processor to the GNU-syntax Arm assembler.
TI-syntax Arm assembly source files - unlike other tiarmclang input file types, a -x ti-asm option must be used to instruct tiarmclang to interpret a subsequent input file as a TI-syntax Arm assembly source file.
Note
For more information about the tiarmclang -x option and controlling how tiarmclang interprets input files, see the Using -x Option to Control Input File Interpretation section.
1.2.2. Example¶
The following simple example shows how the tiarmclang command can be used to build an ELF format static executable file that can be loaded and run on a Cortex-M0 Arm processor.
Source Files There are two input files to specify on the tiarmclang command line.
The C file print_global.c references a global variable that is defined in a GNU-syntax Arm assembly source file def_global.S and prints out the value of that global variable.
Contents of print_global.c:
1#include <stdio.h>
2
3extern int a_global;
4
5int main() {
6 printf("a_global: %d\n", a_global);
7 return 0;
8}
Contents of def_global.S:
1#if defined(__ti_version__)
2 .global a_global
3 .data
4a_global: .int 12345
5#else
6#error "a_global is not defined"
7#endif
In addition, the linker command file lnkme.cmd is stored in the current working directory. This linker command file provides a specification of the available memory and how to place compiler/linker generated output sections in that memory.
Contents of lnkme.cmd:
/****************************************************************************/
/* Example Linker Command File */
/****************************************************************************/
-c /* LINK USING C CONVENTIONS */
-stack 0x8000 /* SOFTWARE STACK SIZE */
-heap 0x2000 /* HEAP AREA SIZE */
--args 0x1000
/* SPECIFY THE SYSTEM MEMORY MAP */
MEMORY
{
P_MEM : org = 0x00000020 len = 0x20000000 /* PROGRAM MEMORY (ROM) */
D_MEM : org = 0x20000020 len = 0x20000000 /* DATA MEMORY (RAM) */
}
/* SPECIFY THE SECTIONS ALLOCATION INTO MEMORY */
SECTIONS
{
.intvecs : {} > 0x0 /* INTERRUPT VECTORS */
.bss : {} > D_MEM /* GLOBAL & STATIC VARS */
.data : {} > D_MEM
.sysmem : {} > D_MEM /* DYNAMIC MEMORY ALLOCATION AREA */
.stack : {} > D_MEM /* SOFTWARE SYSTEM STACK */
.text : {} > P_MEM /* CODE */
.cinit : {} > P_MEM /* INITIALIZATION TABLES */
.const : {} > P_MEM /* CONSTANT DATA */
.rodata : {} > P_MEM
.ARM.exidx : {} > P_MEM
.init_array : {} > P_MEM /* C++ CONSTRUCTOR TABLES */
}
Compile and Link Steps Explained The following tiarmclang command compiles and links the input files to create a static executable file called a.out:
%> tiarmclang -mcpu=cortex-m0 print_global.c def_global.S -o a.out -Xlinker lnkme.cmd
The above tiarmclang command performs the following actions during the process of building the static executable file a.out:
tiarmclang compiles and generates a first input object file from print_global.c. This input object file is subsequently fed into the link step.
tiarmclang runs the C pre-processor over def_global.c, passing the result of the C pre-processor to the integrated GNU-syntax assembler that assembles the source file and produces a second input object file to be fed into the link step.
tiarmclang runs the linker:
the previously generated input object files are linked with the Cortex-M0 version of the runtime libraries that are provided with the tiarmclang compiler tools installation,
the linker resolves the call to printf with a definition of the printf function from the C runtime library,
the linker reads the linker command file lnkme.cmd to determine how code and data sections are to be placed in Cortex-M0 target memory, and
the linker writes out the resulting ELF executable file a.out.
1.2.3. Compile and Link (Default Operation)¶
The default behavior of the tiarmclang compiler is to compile the specified source files into temporary object files, and then pass those object files along with any explicitly specified object files and any specified linker options to the linker.
In the following example, assume that the C code in file1.c references a data object that is defined in an object file named file2.o. The specified tiarmclang command compiles file1.c into a temporary object file. That object file, along with file2.o and a linker command file, link_test.cmd, is input to the linker and linked with applicable object files from the tiarmclang runtime libraries to create an executable output file named test.out:
tiarmclang -mcpu=cortex-m0 file1.c file2.o -o test.out -Wl,link_test.cmd
1.2.3.1. More About Invoking the Linker With tiarmclang¶
Note that there is no mention of the tiarmclang runtime libraries on the tiarmclang command line or inside of the link_test.cmd linker command file. When the linker is invoked from the tiarmclang command line, the tiarmclang compiler implicitly tells the linker where to find applicable runtime libraries like the C runtime library (libc.a).
More specifically, the following options are implicitly passed from tiarmclang directly to the linker:
-I<install directory>/lib
--start-group -llibc++.a -llibc++abi.a -llibc.a -llibsys.a \
-llibsysbm.a -llibclang_rt.builtins.a \
-llibclang_rt.profile.a --end-group
-I <install directory>/lib - tells the linker where to find the tiarmclang runtime libraries
--start_group/--end_group - specifies exactly which runtime libraries are incorporated into the link
In the above tiarmclang command line, the -Wl, prefix in front of the specification of the link_test.cmd file name indicates to the compiler that the link_test.cmd file should be input directly into the linker (you can also use the -Xlinker prefix for this purpose).
1.2.4. Run Preprocesser Only¶
The -E option causes the compiler to halt after running the C preprocessor and send the preprocessed output to the output location.
tiarmclang -E [options] [filenames]
If no other options on the command line specify an output location, the preprocessed output is sent to stdout. If, for example, the -E option is used in combination with the -o option, the preprocessed output is sent to the file specified with the -o option. In this case, the file that would normally be a binary object file instead contains text.
The -E option is often combined with other preprocessor options like -dD, -dI, or -dM to further regulate the behavior of the C preprocessor. In the following example, the -E option is combined with -dD to print macro definitions in addition to normal preprocessor output:
tiarmclang -mcpu=cortex-m0 -E -dD file1.c
For more information about preprocessor options, see the Preprocessor Options section.
1.2.5. Run Preprocesser and Syntax-Checking Only¶
The -fsyntax-only option instructs tiarmclang to run the C preprocessor, parse the C/C++ input file to check for syntax errors, and perform type checking before halting compilation.
tiarmclang -fsyntax-only [options] [filenames]
The -fsyntax-only option can be useful for finding simple syntax and type usage errors in the C/C++ source without incurring additional compile time early on in the development of newly written code.
1.2.6. Stop Compiler After Assembly Output¶
Using the -S option causes the compiler to generate assembly files from C or C++ source files that are specified on the command line. When -S is specified on the command line, compilation stops after the assembly files are emitted, preventing the compiler from generating object files or invoking the linker.
tiarmclang -S [options] [filenames]
The following example generates assembly files, file1.s and file2.s, each containing compiler-generated GNU-syntax Arm assembly language directives and instructions:
tiarmclang -S -mcpu=cortex-m0 file1.c file2.c
1.2.7. Stop Compiler After Object File Output (Omit Linking)¶
You can avoid invoking the linker by specifying the -c option on the tiarmclang command line.
tiarmclang -c [options] [filenames]
The following example generates object files file1.o and file2.o from the C files file1.c and file2.c, respectively:
tiarmclang -c -mcpu=cortex-m0 file1.c file2.c