Dso-tc2 Manual

[Maricel Fergason]

The Clang Compiler is an open-source compiler for the C family ofprogramming languages, aiming to be the best in class implementation ofthese languages. Clang builds on the LLVM optimizer and code generator,allowing it to provide high-quality optimization and code generationsupport for many targets. For more general information, please see theClang Web Site or the LLVM WebSite.

In addition to language specific features, Clang has a variety offeatures that depend on what CPU architecture or operating system isbeing compiled for. Please see the Target-Specific Features andLimitations section for more details.

This section is generally an index into other sections. It does not gointo depth on the ones that are covered by other sections. However, thefirst part introduces the language selection and other high leveloptions like -c, -g, etc.

Only emit up to 123 template instantiation notes within the templateinstantiation backtrace for a single warning or error. The default is 10, andthe limit can be disabled with -ftemplate-backtrace-limit=0.

Clang aims to produce beautiful diagnostics by default, particularly fornew users that first come to Clang. However, different people havedifferent preferences, and sometimes Clang is driven not by a human,but by a program that wants consistent and easily parsable output. Forthese cases, Clang provides a wide range of options to control the exactoutput format of the diagnostics that it generates.

Print source line and ranges from source code in diagnostic.This option, which defaults to on, controls whether or not Clangprints the source line, source ranges, and caret when emitting adiagnostic. For example, when this is enabled, Clang will printsomething like:

If the NO_COLOR environment variable is defined and not empty(regardless of value), color diagnostics are disabled. If NO_COLOR isdefined and -fcolor-diagnostics is passed on the command line, Clangwill honor the command line argument.

Passing -fno-diagnostics-show-option will prevent Clang fromprinting the [-Wextra-tokens] information inthe diagnostic. This information tells you the flag needed to enableor disable the diagnostic, either from the command line or through#pragma GCC diagnostic.

Darwin-only: when used for generating a linked binary from a source file(through an intermediate object file), the driver will invoke cc1 togenerate a temporary object file. The temporary remark file will be emittednext to the object file, which will then be picked up by dsymutil andemitted in the .dSYM bundle. This is available for all formats except YAML.

This option controls whether Clang prints the profile hotness associatedwith diagnostics in the presence of profile-guided optimization information.This is currently supported with optimization remarks (seeOptions to Emit Optimization Reports). The hotness informationallows users to focus on the hot optimization remarks that are likely to bemore relevant for run-time performance.

This option, which defaults to zero, controls the minimum hotness anoptimization remark would need in order to be output by Clang. This iscurrently supported with optimization remarks (see Options to EmitOptimization Reports) when profile hotness information indiagnostics is enabled (see-fdiagnostics-show-hotness).

Print machine parsable information about source ranges.This option makes Clang print information about source ranges in a machineparsable format after the file/line/column number information. Theinformation is a simple sequence of brace enclosed ranges, where each rangelists the start and end line/column locations. For example, in this output:

The default for template type printing is to elide as many templatearguments as possible, removing those which are the same in bothtemplate types, leaving only the differences. Adding this flag willprint all the template arguments. If supported by the terminal,highlighting will still appear on differing arguments.

For diffing large templated types, this option will cause Clang todisplay the templates as an indented text tree, one argument perline, with differences marked inline. This is compatible with-fno-elide-type.

As unbelievable as it may sound, Clang does crash from time to time.Generally, this only occurs to those living on the bleedingedge. Clang goes to greatlengths to assist you in filing a bug report. Specifically, Clanggenerates preprocessed source file(s) and associated run script(s) upona crash. These files should be attached to a bug report to easereproducibility of the failure. Below are the command line options tocontrol the crash diagnostics.

Clang is also capable of generating preprocessed source file(s) and associatedrun script(s) even without a crash. This is specially useful when trying togenerate a reproducer for warnings or errors while using modules.

Optimization reports trace, at a high-level, all the major decisionsdone by compiler transformations. For instance, when the inlinerdecides to inline function foo() into bar(), or the loop unrollerdecides to unroll a loop N times, or the vectorizer decides tovectorize a loop body.

Since there are dozens of passes inside the compiler, each of these flagstake a regular expression that identifies the name of the pass which shouldemit the associated diagnostic. For example, to get a report from the inliner,compile the code with:

Note that remarks from the inliner are identified with [-Rpass=inline].To request a report from every optimization pass, you should use-Rpass=.* (in fact, you can use any valid POSIX regularexpression). However, do not expect a report from every transformationmade by the compiler. Optimization remarks do not really make senseoutside of the major transformations (e.g., inlining, vectorization,loop optimizations) and not every optimization pass supports thisfeature.

Optimization remarks that refer to function names will display themangled name of the function. Since these remarks are emitted by theback end of the compiler, it does not know anything about the inputlanguage, nor its mangling rules.

Some source locations are not displayed correctly. The front end hasa more detailed source location tracking than the locations includedin the debug info (e.g., the front end can locate code inside macroexpansions). However, the locations used by -Rpass aretranslated from debug annotations. That translation can be lossy,which results in some remarks having no location information.

This option requests driver to print used memory and execution time of eachcompilation step. The clang driver during execution calls different tools,like compiler, assembler, linker etc. With this option the driver reportstotal execution time, the execution time spent in user mode and peak memoryusage of each the called tool. Value of the option specifies where the reportis sent to. If it specifies a regular file, the data are saved to this file inCSV format:

The report file specified in the option is locked for write, so this optioncan be used to collect statistics in parallel builds. The report file is notcleared, new data is appended to it, thus making possible to accumulate buildstatistics.

You can also use environment variables to control the process statistics reporting.Setting CC_PRINT_PROC_STAT to 1 enables the feature, the report goes tostdout in human readable format.Setting CC_PRINT_PROC_STAT_FILE to a fully qualified file path makes it reportprocess statistics to the given file in the CSV format. Specifying a relativepath will likely lead to multiple files with the same name created in differentdirectories, since the path is relative to a changing working directory.

These environment variables are handy when you need to request the statisticsreport without changing your build scripts or alter the existing set of compileroptions. Note that -fproc-stat-report take precedence over CC_PRINT_PROC_STATand CC_PRINT_PROC_STAT_FILE.

This flag controls the value of __GNUC__ and related macros. This flagdoes not enable or disable any GCC extensions implemented in Clang. Settingthe version to zero causes Clang to leave __GNUC__ and otherGNU-namespaced macros, such as __GXX_WEAK__, undefined.

Instruct clang not to emit the signature string for blocks. Disabling thestring can potentially break existing code that relies on it. Users shouldcarefully consider this possibiilty when using the flag.

Configuration files group command-line options and allow all of them to bespecified just by referencing the configuration file. They may be used, forexample, to collect options required to tune compilation for particulartarget, such as -L, -I, -l, --sysroot, codegen options, etc.

If the provided argument contains a directory separator, it is considered asa file path, and options are read from that file. Otherwise the argument istreated as a file name and is searched for sequentially in the directories:

Both user and system directories for configuration files are specified duringclang build using CMake parameters, CLANG_CONFIG_FILE_USER_DIR andCLANG_CONFIG_FILE_SYSTEM_DIR respectively. The first file found is used.It is an error if the required file cannot be found.

The default configuration files are searched for in the same directoriesfollowing the rules described in the next paragraphs. Loading defaultconfiguration files can be disabled entirely via passingthe --no-default-config flag.

First, the algorithm searches for a configuration file named-.cfg where triple is the triple for the target beingbuilt for, and driver is the name of the currently used driver. The algorithmfirst attempts to use the canonical name for the driver used, then falls backto the one found in the executable name.

If none of the aforementioned files are found, the driver will instead searchfor separate driver and target configuration files and attempt to load both.The former is named .cfg while the latter is named.cfg. Similarly to the previous variants, the canonical driver namewill be preferred, and the compiler will fall back to the actual name.

The configuration file consists of command-line options specified on one ormore lines. Lines composed of whitespace characters only are ignored as well aslines in which the first non-blank character is #. Long options may be splitbetween several lines by a trailing backslash. Here is example of aconfiguration file:

c80f0f1006