Command-Line Compiler

This section describes the switches accepted by the compiler driver, cc. The compiler driver is capable of controlling compilation by all supported language compilers and the final link by the linker. It can also construct libraries automatically.

File naming conventions

The compiler driver uses file extensions to distinguish the language the source file is written in. The compiler driver recognizes the extension .c as C source files, .s and .asm as assembly code files.

The compiler driver recognizes the extension .hzo as object files, .hza as library files and .xml as special-purpose XML files.

We strongly recommend that you adopt these extensions for your source files and object files because you'll find that using the tools is much easier if you do.

C language files

When the compiler driver finds a file with a .c extension, it runs the C compiler to convert it to object code. Alternatively you can specify that it is a C file using

cc -x c cfile.notc ...

Assembly language files

When the compiler driver finds a file with a .s or .asm extension, it runs the C preprocessor and then the assembler to convert it to object code. Alternatively you can specify that it is an assembly language file using

cc -x asm asmfile.nots ...

Object code files

When the compiler driver finds a file with a .hzo or .hza extension, it passes it to the linker to include it in the final application.

Compilation

To compile or assemble a file you should supply the -c option together with the source file and provide a name for the output file using the -o option

cc -c file.c -o file.o

if you don't supply an output name then the output file will be use the basename of the source file.

You can supply the file to be compiled from the standard input using the

cc -c - -o main.o
int main() 
{
  return 3;
}
<EOF>

You can preprocess the source file rather than compile it using the -E option

cc -E main.c

This will send the output to the standard output or you can use -o to send it to a named file.

You can show the preprocessor defines that are defined for the compilation using the -dM option

cc -E -dM main.c

You can supply preprocessor defines and include directories using -D and -I options

cc -c file.c -Dmydefine -Imyincludedir

You can include a file before compilation using -include

cc -c file.c -include file.h

There is also a variant that will just use the #defines that are declared in the included file

cc -c file.c -imacros file.h

If you wish to not use the default C/C++ library you can use -I- and then supply your own system library directory using -isystem

cc -c file.c -I- -isystemmysystemincludedir

You can using the -g option to include debugging information in the output file

cc -c file.c -g

You can use the -O option to set the desired optimization level

cc -c file.c -O0

Linking

You can compile/link a number of files with the standard libraries

cc Cortex_M_Startup.s thumb_crt0.s main.o -o main.elf

You'll also need to supply linker control details. There are a number of ways of doing this

cc .. -placement ram_placement.xml -placementsegments "SRAM RW 0x0 0x1000" -ereset_handler

cc .. -memorymap map.xml -placementsegments "SRAM RW 0x0 0x1000" -ereset_handler

cc .. -Tlinker.icf -ereset_handler

Target Selection

Advanced

You can create a precompile header using the -pch option

cc -c -xc -pch main.h -o main.h.pch

Note that the output file must be in the same directory as the input file. You can use this precompiled header file

cc -c main.c -include-pch main.h.pch

You can create a C++ 20 module using

cc++ -c -xc++ main.cxx -std=c++20 -fmodules-ts -fmodule-file=main=main.o -o main.o

The module file will be named either .gcm or .pcm and can be used by another file using

cc++ -c -xc++ another.cxx -std=c++20 -fmodules-ts -fmodule-file=main=main.o -o another.o

Options:

Option	Description
`-`	input is taken from standard input
`-###`	show commands but don't execute them
`-allow-multiple-definition`	allow multiple symbol definition when linking
`-ansi`	enforce ANSI checking
`-ar`	create library from input files
`-arch=val`	set cpu architecture to 'val', use list to display supported
`-arm`	generate ARM code
`-arm64`	generate ARM64 code
`-be`	big endian target
`-be8`	big endian target
`-builtins`	use builtin compiler functions
`-c`	compile the files, no link/library
`-cmselib=l`	create cmse output library in 'l'
`-codec=c`	set file codec to 'c', use list to display supported
`-common`	allocate global variables in the common section
`-cpu=val`	set cpu core to 'val', use list to display supported
`-depend` file	generate dependency file in 'file'
`-dependu` file	generate dependency file in 'file' with user header files only
`-dM`	show #defines
`-Dname`	define the preprocessor macro 'name'
`-Dname=val`	define the preprocessor macro 'name' as 'val'
`-dname=val`	define the linker symbol 'name' as 'val'
`-E`	preprocess file and write to standard output
`-emit-relocs`	emit relocations into executable
`-ename`	set program entry symbol to 'name'
`-exceptions`	enable C++ exceptions
`-Fbin`	create an additional binary output file
`-fbuiltin`	enable compiler builtin functions
`-fcommon`	place global variables in COMMON section
`-fcoroutines`	enable C++ coroutine support
`-fdebug-types-section`	generate .debug_types section
`-fdiagnostics-color=always`	color diagnostic output of the compiler
`-fdiagnostics-color=never`	do not color diagnostic output of the compiler
`-fdiagnostics-show-caret`	show caret in diagostic output of the compiler
`-fexceptions`	enable C++ exception support
`-Fhex`	create an additional hex output file
`-fill=b`	fill gaps in the additional output file with byte 'b'
`-flto`	generate code suitable for link time optimization
`-fmath-errno`	set errno after calling math functions
`-fmodule-file='name'`	get module dependencies from the file 'name'
`-fmodules-ts`	enable c++20 modules
`-fno-builtin`	disable compiler builtin functions
`-fno-common`	place global variables in bss section
`-fno-diagnostics-show-caret`	do not show caret in diagostic output of the compiler
`-fno-exceptions`	disable C++ exception support
`-fno-math-errno`	set errno after calling math functions
`-fno-omit-frame-pointer`	disable framepointer generation
`-fno-rtti`	disable C++ RTTI support
`-fno-short-enums`	enumerations are int sized
`-fno-short-wchar`	wide characters are 32-bit
`-fno-signed-char`	char is considered to be unsigned char
`-fomit-frame-pointer`	disable framepointer generation
`-fpabi=hard`	generate FPU instructions passing fp arguments in FPU registers
`-fpabi=soft`	do not generate FPU instructions
`-fpabi=softfp`	generate FPU instructions passing fp arguments in CPU registers
`-fpu=val`	set fpu to 'val', use list to display supported
`-framepointer`	generate code to maintain a frame pointer register
`-frtti`	enable C++ RTTI support
`-fshort-enums`	enumerations are minimal container sized
`-fshort-wchar`	wide characters are 16-bit
`-fsigned-char`	char is considered to be signed char
`-Fsrec`	create an additional srec output file
`-ftree-vectorize`	perform vectorization on trees
`-funwind-tables`	generate unwind tables
`-g1`	generate only backtrace and line number debugging information
`-g2`	generate level 1 and variable display debugging information
`-g3`	generate level 2 and macro display debugging information
`-gcc`	use gcc assembler/compiler/lto
`-gcc-target=name`	select gcc 'name' tools to use
`-gdwarf-2`	generate dwarf-2 debugging information
`-gdwarf-3`	generate dwarf-3 debugging information
`-gdwarf-4`	generate dwarf-4 debugging information
`-gdwarf-5`	generate dwarf-5 debugging information
`-gnu-ld`	use gnu linker
`-gpubnames`	generate .debug_pubnames and .debug_pubtypes sections
`-hascmse`	v8m architecture has cmse instructions
`-hascrc`	v8a architecuture has crc instructions
`-hascrypto`	v8a architecture has crypto instructions
`-hasdsp`	v8m architecture has dsp instructions
`-hasidiv`	v7ar architecture has integer divide instructions
`-hassmallmultiplier`	cortex-m0/m0+/m1 architecture has small multiplier
`-heap=basic`	use basic heap implementation
`-heap=minimal`	use minimal heap implementation
`-heap=rt`	use real-time heap implementation
`-help`	show this text
`-I-`	do not search any standard directories for include files
`-Idir`	add 'dir' to the end of the user include search list
`-imacros` file	same as -include but only keep #defines
`-include` file	#include 'file' before the source file
`-include-pch` file	#include precompiled header 'file' before the source file
`-inputfiles` file	list of files in 'file' to link or archive
`-instrument`	instrument functions
`-io=none`	use user supplied implementation for library io
`-io=rtt`	use RTT implementation for library io
`-io=semihost`	use semihosted implementation for library io
`-io=semihostf`	use host formatted semihosted implementation for library io
`-io=swo`	use SWO implementation for library io
`-io=swoi`	use SWO with interrupts disabled implementation for library io
`-isystem` dir	add 'dir' to the end of the system include search list
`-Jdir`	add 'dir' to the end of the system include search list
`-kasm`	keep assembly code output
`-kind`	keep indirect files
`-kldscript`	keep generated linker script
`-klto`	keep lto generated files
`-Kname`	keep symbol 'name' in the linked output
`-kpp`	keep preprocessor output
`-l-`	disable linking of standard libraries
`-Ldir`	search directory 'dir' to find libraries
`-le`	little endian target
`-libdir` dir	specify system library directory 'dir'
`-lname`	search library 'name' to resolve symbols
`-locales=minimal`	locales implementation
`-longcalls`	generate long calling instruction sequences
`-lunwind`	generate stack unwind tables
`-M`	generate linkage map file
`-march=val`	set cpu architecture to 'val', use list to display supported
`-marm`	generate arm code
`-mbe8`	big endian target
`-mbig-endian`	big endian target
`-mcmse`	v8m architecture has cmse instructions
`-mcpu=val`	set cpu core to 'val', use list to display supported
`-memorymap` file	supply memory map file in 'file'
`-memorymapmacros` macros	define macros for memory map file in 'macros'
`-mfloat-abi=val`	specify the floating-point abi to use, val can be 'soft', 'softfp', 'hard'
`-mfp16-format=ieee`	specify the format of the __fp16 half-precision floating-point type
`-mfpu=val`	set fpu to 'val', use list to display supported
`-mlittle-endian`	little endian target
`-mno-thumb-interwork`	do not generate interworking code for v4t architecture
`-mno-unaligned-access`	disable unaligned word and half-word load/store instructions
`-mthumb`	generate thumb code, default is to generate ARM code for processors that support it
`-mtp=soft`	specify the thread local storage model
`-munaligned-access`	enable unaligned word and half-word load/store instructions
`-n`	show commands but don't execute them
`-nodefaultlibs`	disable linking of standard libraries
`-noshortenums`	enumerations are int sized
`-noshortwchar`	wide characters are 32-bit
`-nostderr`	redirect output from stderr to stdout
`-nostdinc`	do not search any standard directories for include files
`-nostdlib`	disable linking of standard libraries
`-nowarn-enumsize`	no linker warning on mismatched enum sized input files
`-nowarn-mismatch`	no linker warning on mismatched architecture input files
`-nowarn-rwx-segments`	no linker warning on load segments with RWX permissions
`-nowarn-wcharsize`	no linker warning on mismatched wchar sized input files
`-o` file	leave output in 'file'
`-O0`	set optimization level to level 0
`-O1`	set optimization level to level 1
`-O2`	set optimization level to level 2
`-O3`	set optimization level to level 3
`-Os`	set optimization level to optimize for size
`-Oz`	set optimization level to optimize for more size
`-patch` cmd	run 'cmd' after link but before the creation of the additional output file
`-pch`	generate a precompiled header file
`-pedantic`	warning on non-standard language usage
`-pedantic-errors`	error on non-standard language usage
`-placement` file	supply placement file in 'file'
`-placementmacros` macros	define macros for placement file in 'macros'
`-placementsegments` segments	memory segments for placement in 'segments'
`-printf=d[ll][w]`	double, optional long long, optional wchar
`-printf=f[ll][w]`	float, optional long long, optional wchar
`-printf=i[p][w]`	integer, optional width and precision, optional wchar
`-printf=ll[p][w]`	long long integer, optional width and precision, optional wchar
`-Rc,name`	name the default code section to 'name'
`-Rd,name`	name the default data section to 'name'
`-Rk,name`	name the default const section to 'name'
`-rtti`	enable C++ rtti
`-Rz,name`	name the default bss section to 'name'
`-scanf=d[ll][c]`	double, optional long long, optional %[...] and %[^...] character class
`-scanf=ll[c]`	long long integer, optional %[...] and %[^...] character class
`-segger`	use SEGGER assembler/compiler/lto
`-segger-ld`	use SEGGER linker
`-shortenums`	enumerations are minimal container sized
`-shortwchar`	wide characters are 16-bit
`-simd=neon`	generate simd vector processing code
`-stack-sizes`	generate stack-sizes section
`-std=s`	set language standard to 's', use list to display supported
`-stop`	generate stack overflow protection code
`-stripdebug`	strip debug information from linked executable
`-stripsymbols`	strip symbols from linked executable
`-symbols=s`	link symbols file 's' into executable
`-Tfile`	use 'file' as linker script
`-thumb`	generate thumb code, default is to generate ARM code for processors that support it
`-unwindtables`	generate stack unwind tables
`-v`	show command lines as they are executed
`-vectorize`	enable auto vectorization code generation
`-W`	supply option to the compiler
`-w`	suppress warnings
`-Wa,x`	pass 'x' to the assembler
`-Wc,x`	pass 'x' to the compiler
`-we`	treat warnings as errors
`-Werror`	treat warnings as errors
`-Wl,x`	pass 'x' to the linker
`-x` t	subsequent files are considered to be of file type 't'
`-xa`	subsequent files are considered to be library files
`-xasm`	subsequent files are considered to be assembly code
`-xassembler-with-cpp`	subsequent files are considered to be assembly code
`-xc`	subsequent files are considered to be C code
`-xc++`	subsequent files are considered to be C++ code
`-Xlinker` x	pass 'x' to the linker
`-xo`	subsequent files are considered to be object code