This chapter explains how to invoke the CompCert C compiler and describes its command-line interface.
By default, every input file is processed in sequence to obtain a compiled object file; then, all compiled object files thus obtained, plus those given on the command line, are linked together to produce an executable program. The name of the generated executable is controlled with the -o option; it is a.out if no option is given. The -c, -S and -E options allow the user to stop this process at an intermediate stage. For example, the -c option stops compilation before invoking the linker, leaving the compiled object files (with extension .o) as the final result. Likewise, the -S option stops compilation before invoking the assembler, leaving assembly files with the .s extension as the final result.
Arguments ending in .c are taken to be source files written in C. Given the file x.c, the compiler preprocesses the file, then compiles it to assembly language, then invokes the assembler to produce an object file named x.o.
Arguments ending in .i or .p are taken to be source files written in C and already preprocessed, or not using any preprocessing directive. These files are not run through the preprocessor. Given the file x.i or x.p, the compiler compiles it to assembly language, then invokes the assembler to produce an object file named x.o.
Arguments ending in .s are taken to be source files written in assembly language. Given the file x.s, the compiler passes it to the assembler, producing an object file named x.o.
Arguments ending in .S are taken to be source files written in assembly language plus C-style macros and preprocessing directives. Given the file x.S, the compiler passes the file through the C preprocessor, then through the assembler, producing an object file named x.o.
Arguments ending in .o are taken to be object files obtained by a prior run of compilation. They are passed directly to the linker.
Arguments ending in .a are taken to be libraries. Like .o files, they are passed directly to the linker.
Arguments starting in -l are taken to be system libraries. They are passed directly to the linker.
CompCert can read command line arguments from response files passed via @filename, too. The options read from a response file replace the @filename option. If a response file does not exist or cannot be read, the option will be treated literally and is not removed.
Within a response file, the options are separated by whitespace, i.e. by space, tab, or newline characters. Options can be enclosed in either single or double quotes to allow whitespace as part of an option. Furthermore, any character can be escaped by prefixing it with a backslash character.
Including options via response files works recursively, i.e. it is possible to specify @otherfile from within a response file. Circular includes are detected and treated as error.
If specified, CompCert reads its configuration from <file>.
If present, the environment variable denotes the path to the configuration file to be used.
If specified, CompCert reads its target configuration from a file named <target-triple>.ini. CompCert searches the configuration file in the bin/, share/, or share/compcert/ subfolders of its installation directory.
As fallback CompCert looks for a default configuration file named compcert.ini in the same folders as described for the -target option. Such a default configuration is created when CompCert is built from sources.
The ccomp command recognizes the following options. All options start with a minus sign (-).
Compile or assemble the source files, but do not link. The final output is an object file x.o for every input file x.c or x.s or x.S. The name of the output can be controlled using the -o option.
Compile the source files all the way to assembly, but do not assemble nor link. The final output is an assembly file x.s for every input file x.c. The name of the output can be controlled using the -o option.
Stop after the preprocessing stage; do not compile nor link. The output is preprocessed C source code for every input file x.c. If no -o option is given, the preprocessed code is sent to the standard output. If a -o option is given, the preprocessed code is saved to the indicated file.
Generate the final output in file named file. If none of the -c, -S or -E options are given, the final output is the executable program produced during the linking phase. The -o file option causes this executable to be placed in file. Otherwise, it is placed in file a.out in the current directory.
If the -c option is given along with the -o option, the object file generated by the compilation of the source file given on the command line is saved in file. If no -o option is given, it is generated in the current directory with extension .o.
If the -S option is given along with the -o option, the assembly file generated by the compilation of the source file given on the command line is saved in file. If no -o option is given, it is generated in the current directory with extension .s.
If the -E option is given along with the -o option, the result of preprocessing the source file given on the command line is saved in file. If no -o option is given, the preprocessed result is sent to standard output.
When the -o option is given in conjunction with one of the -c, -S or -E options, there must be only one source file given on the command line.
In addition to the outputs normally produced by Compcert, generate a x.sdump file for every x.c input file. The .sdump file contains the abstract syntax tree for the generated assembly code, in JSON format. The .sdump files can be used by the Valex validation tool distributed by AbsInt.
Add directory dir to the list of directories searched for included .h files.
Define name as a macro that expands to "1". This is equivalent to adding a line "#define name 1" at the beginning of the source file.
Define name as a macro that expands to def. This is equivalent to adding a line "#define name def" at the beginning of the source file. A parenthesized list of parameters can occur between name and the = sign, to define a macro with parameters. For example, -DF(x,y)=x is equivalent to adding a line "#define F(x,y) x" at the beginning of the source file.
Erase any previous definition of the macro name, either built-in or performed via a previous -D option. This is equivalent to adding a line "#undef name" at the beginning of the source file.
Pass opt as an option to the preprocessor. If opt contains commas (,), it is split into multiple options at the commas.
Pass opt as an option to the preprocessor.
The macro __COMPCERT__ is always predefined, with expansion "1".
The preprocessing options above can either be concatenated with their arguments (as shown above) or separated from their arguments by spaces.
For GNU backends the options -C, -CC, -idirafter, -imacros, -iquote, -isystem, -M, -MF, -MG, -MM, -MP, -MQ, -MT, -nostdinc, and -P are recognized and propagated to the preprocessor.
Optimize the code with the objective of improving execution speed. This is the default.
Synonymous for -O (optimize for speed).
Optimize the code with the objective of reducing the size of the executable. CompCert's optimizations improve both execution speed and code size, but some of the code generation heuristics in -O mode favor speed over compactness. The -Os option biases these heuristics in the other direction, favoring compactness over speed.
Turn most optimizations off. This produces slower code but reduces compilation times. Equivalent to -fno-const-prop -fno-cse -fno-redundancy -fno-tailcalls. The only optimizations performed are 1- integer constant propagation within expressions, 2- register allocation, and 3- dead code elimination.
Turn on/off the constant propagation optimization.
Turn on/off the elimination of common subexpressions.
Turn on/off the inlining of functions.
Turn on/off inlining of functions only required by a single caller.
Turn on/off the elimination of redundant computations and useless memory stores.
Turn on/off the optimization of function calls in tail position.
This option controls whether and how floating-point constants are propagated at compile-time. The constant propagation optimization consists in evaluating, at compile-time, arithmetic and logical operations whose arguments are constants, and replace these operations by the constants just obtained. A constant, here, is either an integer or float literal, the initial value of a const variable, or, recursively, the result of an arithmetic or logical operation itself contracted by constant propagation. The -ffloat-const-prop controls how floating-point constants are propagated and translated.
Full propagation of floating-point constants. Float arithmetic is performed by the compiler in IEEE double precision format, with round-to-nearest mode. This propagation is correct only if the program does not change float rounding mode at run-time, leaving it in the default round-to-nearest mode.
No propagation of floating-point constants. This option should be given if the program changes the float rounding mode during its execution.
Propagate floating-point constants, assuming round-to-nearest mode, but only for arguments of integer-valued operations such as float comparisons and float-to-integer conversions. In other words, floating-point constants are propagated, but no new floating-point constants are inserted in the generated assembly code. This option is useful for some processor configurations where floating-point constants are stored in slow memory and therefore loading a floating-point constant from memory can be slower than recomputing it at run-time.
Force the entry point to any compiled function to be aligned on an N byte boundary. The default alignment for function entry points is 16 bytes for the IA32 target and 4 bytes for the ARM and PowerPC targets.
This option is specific to the PowerPC target. In the generated assembly code, align the targets of branch instructions to a multiple of N bytes. Only branch targets that cannot be reached by fall-through execution are thus aligned. If no -falign-branch-targets option is specified, N is assumed to be zero which deactivates alignment handling for branch targets.
This option is specific to the PowerPC target. It causes conditional branch instructions (bc) to be aligned to a multiple of N bytes in the generated assembly code. If no -falign-cond-branches option is specified, N is assumed to be zero which deactivates alignment handling for conditional branch instructions.
Turn on/off placement of global variables defined without an initializer (tentative definitions) in the common section. Disabling the use of the common section inhibits merging of tentative definitions by the linker and may lead to multiple-definition errors. By default the use of the common section is enabled.
Prevent the generation of floating-point or SSE2 instructions for assignments between composites (structures or unions) and for the __builtin_memcpy_aligned built-in function.
This option is specific to the PowerPC EABI target platform with Diab tools. It causes global variables of size less than or equal to N bytes and of non-const type to be placed in the small data area (SDA) of the generated executable, and to be addressed by 16-bit offsets relative to the SDA register. This is more efficient than the default absolute addressing used to access global variables. If no -fsmall-data option is given, N is taken to be 8 by default.
Similar to -fsmall-data N, but governs the placement of const global variables in the small data area.
Pass opt as an option to the assembler. If opt contains commas (,), it is split into multiple options at the commas.
Pass opt as an option to the assembler.
Select a specific target processor configuration for code generation instead of using the default described in compcert.ini. Refer to section 3.1.2 for detailed information about configuration files.
This option applies only to the ARM port of CompCert. It instructs CompCert to generate code using the Thumb2 instruction encoding. This is the default if CompCert was configured for the ARMv7R profile.
This option applies only to the ARM port of CompCert. It instructs CompCert to generate code using the classic ARM instruction encoding. This is the default if CompCert was configured for a profile other than ARMv7R.
This option is specific to the PowerPC EABI target platform with Diab toolchain. It selects the target architecture and execution envorinment and is forwarded to the preprocessor, assembler and linker of the Diab toolchain. It has no effect on the code generated by CompCert.
Generate full debugging information in DWARF format. Programs compiled and linked with the -g option can be debugged using a debugger such as GDB.
Control generation of debugging information (0: none, 1: only globals, 2: globals and locals without locations, 3: full debug information). The default level is 3 for full debug information.
Available for GNU backends to select between debug information in DWARF format version 2 or 3. The default format is DWARF v3.
Link with the system library -lx. The linker searches a standard list of directories for the file libx.a and links it.
Add directory dir to the list of directories searched for -llib libraries.
Pass opt as an option to the linker. If opt contains commas (,), it is split into multiple options at the commas.
Pass opt as an option to the driver program used for linking. If opt contains commas (,), it is split into multiple options at the commas.
Pass opt as an option to the linker.
For GNU backends the options -nodefaultlibs, -nostartfiles, and -nostdlib are recognized and propagated to the linker.
The formally-verified part of the CompCert compiler lacks several features of the C language. Some of these features can be simulated by prior source-to-source transformations, performed during the elaboration phase, before entering the formally-verified part of the compiler. The following language support options control which features are simulated this way. Note that these source-to-source transformations are not formally verified yet and cannot be absolutely trusted. For high-assurance software, it is recommended to deactivate them entirely (option -fnone) or to review the C source code after these transformations (option -dc).
Support bit-fields in structure declarations. Consecutive bit-fields are grouped into integer fields of appropriate sizes. Accesses to bit-fields are replaced by bit shifting and masking over the generated integer fields.
Reject bit-fields in structure declarations.
Accept the long double type and treat it as synonymous for the double type, that is, double-precision IEEE 754 floats. This implementation of long double is correct according to the C standards, but does not conform to the ABIs of the target platforms. In other terms, the code generated by CompCert in -flongdouble mode may not interoperate with code generated by an ABI-conformant compiler.
Reject all occurrences of the long double type.
Enable the programmer to control the alignment of struct types and of their individual fields, via the non-standard packed type attribute (section 6.2).
Ignore the packed type attribute, and always use the field alignment rules specified by the ABI of the target platform.
Support functions that take parameters and return results of composite types (struct or union types) by value.
Reject all functions that take arguments or return results of struct or union types.
Support the declaration and invocation of functions declared without function prototypes ("old-style" unprototyped functions).
Reject all functions that are not declared with a function prototype.
Support defining functions with a variable number of arguments, and calling such functions. A typical example is the printf function and its variants from the C standard library.
Reject all attempts to define or invoke a variable-argument function.
Activate support for inline assembly statements (see section 6.6). Indiscriminate use of this statement can ruin all the semantic preservation guarantees of CompCert.
Reject all uses of asm statements.
Activate all language support options above.
Turn off all language support options above.
As listed in the description above, the -fvararg-calls and -funprototyped language support options are turned on by default, and all other are turned off by default.
Enable the specific warning warning. See below for a list of possible warning names.
Disable the specific warning warning. See below for a list of possible warning names.
Treat all warnings of CompCert as errors.
Treat the specific warning warning as an error. See below for a list of possible warning names.
Prevent the specific warning warning from being treated as error even if -Werror is specified. See below for a list of possible warning names.
Treat all errors of CompCert as fatal errors, so that the compilation is aborted immediately.
Limits the maximum number of error messages to N, at which point CompCert stops processing the source-code. If N is 0 (default) the number of error messages is unlimited.
Set format for location information in diagnostic messages. Possible formats are ccomp (default), msvc or vi.
CompCert will print all diagnostic messages with color codes. Colorized output is enabled by default when CompCert is invoked with a TTY output device.
CompCert will print all diagnostic messages as standard ASCII text without colorization. This behavior is the default when CompCert is invoked with a non-TTY as output device.
Print option name with mappable diagnostics.
Disable printing option name with mappable diagnostics.
CompCert currently supports the following warning names. The names must be inserted instead of the <warning> placeholder in the diagnostic options described above. E.g. use the option -Werror=c11-extensions to turn warnings related to C11 specific features into errors.
Comparison of different pointer types.
Features that are not part of the CompCert C core language, e.g. K&R style functions.
Dangerous conversion of constants, e.g. literals that are too large for the given type.
Extern declarations after non-extern definitions.
Use of structs with flexible arrays nexted within structs or arrays.
GNU extension for empty structs.
Type of parameter or return type is implicitly assumed to be int.
Use of unsupported features in combination with dump of abstract syntax tree (via option -sdump).
Conversion between pointer and integer.
Functions declared as noreturn that actually contain a return statement.
Floating point literals with out-of-range magnitudes or values that convert to NaN.
Wrong return type for main.
Declations which do not declare anything.
Use of incompatible pointer types in conditional expressions.
Alignment specifications below natural alignment.
Void-return statement in non-void function.
Use of static variables in non-static inline functions.
Static tentative definition with incomplete type.
Use of unsupported or unknown attributes.
Use of unsupported or unknown pragmas.
Unused parameter for embedded program annotations.
Use of illegal parameter expressions for embedded program annotations.
GNU extension for zero length arrays.
Save the C file after parsing, elaboration, and source-to-source transformations as described in section "Language support options". If the source file is named x.c, the intermediate form is saved in file x.parsed.c, in C syntax. This intermediate form is useful to review the effect of the unverified source-to-source transformations.
Save the generated CompCert C code, just before entering the verified part of the compiler. If the source file is named x.c, the intermediate form is saved in file x.compcert.c, in C syntax. This intermediate form is useful in conjunction with the reference interpreter, because it represents the program exactly as it is interpreted.
Save the generated assembly code, just before calling the assembler. If the source file is named x.c, the assembly code is saved in file x.s. Unlike with option -S, compilation does not stop here and continues with assembling and linking.
The remaining tracing options are of interest mainly to the CompCert developers. In the description below, we assume that the source file is named x.c.
Save generated Clight intermediate code in file x.light.c, in C-like syntax.
Save generated Cminor intermediate code in file x.cm.
Save generated RTL form at successive stages of optimization in files x.rtl.0, x.rtl.1, etc.
Before every invocation of an external command (preprocessor, assembler, linker), print the command and its arguments.
Measure and display the time spent in various compilation passes.
Specify the directory dir containing the CompCert C specific library and header files. This option is useful in the rare case where the user needs to override the default location specified at CompCert installation time.
Read CompCert configuration from file. This takes precedence over any other specification. Refer to section 3.1.2 for detailed information about configuration files.