1.2. Invoking the Compiler¶
1.2.1. Usage¶
To invoke the c29clang compiler, enter:
c29clang [options] [filenames]
c29clang - 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:
c29clang options - affect the behavior of the C/C++ compiler. These are described in more detail in the Compiler Options 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 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 c29clang command line, but you can disable the link step by specifying the -c option on the c29clang command line. You can invoke the linker by itself using the c29lnk 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 c29clang 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 c29clang 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.
Note
For more information about the c29clang -x option and controlling how c29clang 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 c29clang command can be used to build an ELF format static executable file that can be loaded and run on a C29x processor.
Source Files There are two input files to specify on the c29clang command line.
The C file print_global.c references a global variable that is defined in a second C file def_global.c 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.c:
1#ifdef __ti_version__
2#define a_global 12345
3#else
4#error "a_global is not defined"
5#endif /* __ti_version__ */
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:
/****************************************************************************/
/* lnk.cmd - V1.00 Command file for linking C29 programs */
/****************************************************************************/
/* This linker command file assumes C/C++ model */
/****************************************************************************/
-c
-stack 0x8000 /* Software stack size */
-heap 0x2000 /* Heap area size */
/* Specify the system memory map */
MEMORY
{
ROM : org = 0x00000020 len = 0x2FFFE0 /* 1.25 GB */
FLASH : org = 0x10000000 len = 0x300000 /* 1.25 GB */
RAM : org = 0x18000000 len = 0x300000 /* 1.25 GB */
}
#define RO_CODE FLASH
#define RO_DATA FLASH
#define RW_DATA RAM
/* Specify the sections allocation into memory */
SECTIONS
{
.text : {} > RO_CODE /* Code */
.cinit : {} > RO_DATA /* Initialization tables */
.const : {} > RO_DATA /* Constant data */
.pinit : {} > RO_DATA /* C++ Constructor tables */
.data : {} > RW_DATA /* Initialized variables */
.bss : {} > RW_DATA /* Uninitialized variables */
.stack : {} > RW_DATA /* Software system stack */
.sysmem : {} > RW_DATA /* Dynamic memory allocation area */
}
Compile and Link Steps Explained The following c29clang command compiles and links the input files to create a static executable file called a.out:
%> c29clang -mcpu=c29.c0 print_global.c def_global.c -o a.out -Xlinker lnkme.cmd
The above c29clang command performs the following actions during the process of building the static executable file a.out:
1.2.3. Compile and Link (Default Operation)¶
The default behavior of the c29clang 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 c29clang 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 c29clang runtime libraries to create an executable output file named test.out:
c29clang -mcpu=c29.c0 file1.c file2.o -o test.out -Wl,link_test.cmd
1.2.3.1. More About Invoking the Linker With c29clang¶
Note that there is no mention of the c29clang runtime libraries on the c29clang command line or inside of the link_test.cmd linker command file. When the linker is invoked from the c29clang command line, the c29clang 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 c29clang 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 c29clang runtime libraries
--start_group/--end_group - specifies exactly which runtime libraries are incorporated into the link
In the above c29clang 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 emitting the preprocessed output to stdout. (The preprocessor output can also be piped to a file.)
c29clang -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:
c29clang -mcpu=c29.c0 -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 c29clang to run the C preprocessor, parse the C/C++ input file to check for syntax errors, and perform type checking before halting compilation.
c29clang -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¶
Note
Internally, the c29clang compiler normally generates assembly code and assembles the assembly code to create object modules. You do not need to be concerned with assembly code when using the C29x code generation tools. The assembly syntax for C29x is undocumented; it may change without notice in future versions.
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.
c29clang -S [options] [filenames]
The following example generates assembly files, file1.s and file2.s, each containing compiler-generated GNU-syntax C29x assembly language directives and instructions:
c29clang -S -mcpu=c29.c0 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 c29clang command line.
c29clang -c [options] [filenames]
The following example generates object files file1.o and file2.o from the C files file1.c and file2.c, respectively:
c29clang -c -mcpu=c29.c0 file1.c file2.c