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 (assembler and 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.
- 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 details in Linker Options.

Note

For more information about using tiarmclang options to pass options directly to the assembler or linker, please see the Passing Options to Other Tools from tiarmclang section.

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.

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.
- GNU-syntax Arm assembly source files - by default, an input file with either a .s or .S file extension will be interpreted as a GNU-syntax Arm assembly source file. In the case of an input file with a .S extension, the input file will be run through the C pre-processor and pass the output of the C pre-processor 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.
- ELF object files - by default, an input file with a .o file extension is interpreted as an ELF object 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.1.1. 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 that will be specified 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:

#include <stdio.h>

extern int a_global;

int main() {
  printf("a_global: %d\n", a_global);
  return 0;
}

Contents of def_global.S:

#if defined(__ti_version__)
            .global  a_global
            .data
a_global:   .int     12345
#else
#error "a_global is not defined"
#endif

In addition, the linker command file lnkme.cmd is available 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 will compile and link 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 will subsequently be fed into the link step.
tiarmclang runs the C pre-processor over def_global.S, 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.2. tiarmclang Modes of Operation¶

1.2.2.1. Compile and Link (Default)¶

The default behavior of the tiarmclang compiler is to compile specified C, C++, or assembly 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 will compile file1.c into a temporary object file. That object file, along with file2.o and a linker command file, link_test.cmd, will be 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

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 will be 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.2.2. Preprocess Only¶

The -E option will cause the compiler to halt after running the C preprocessor and emitting the preprocessed output to stdout (the preprocessor output can also be piped to a file).

tiarmclang -E [options] [filenames]

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 to stdout:

tiarmclang -mcpu=cortex-m0 -E -dD file1.c

For more information about preprocessor options, see the Preprocessor Options section.

1.2.2.3. Syntax-Checking Only¶

The -fsyntax-only option will instruct 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.2.4. Compile to Assembly Output¶

Using the -S option will cause the compiler to generate assembly files from the C or C++ source files that are specified on the command-line. When -S is specified on the command-line, compilation will stop after the assembly files are emitted, preventing the compiler from generating an object file or invoking the linker.

tiarmclang -S [options] [filenames]

The following example will generate 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.2.5. Compile to Object File Output¶

You can avoid invoking the linker by specifying the -c option on the tiarmclang command-line.

tiarmclang -c [options] [filenames]

The following example will generate 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