Terminology¶

Front end, parser, backend, preprocessor, undefined behavior,diagnostic, optimizer

Basic Usage¶

Intro to how to use a C compiler for newbies.

compile + link compile then link debug info enabling optimizationspicking a language to use, defaults to C17 by default. Autosenses basedon extension. using a makefile

Options to Control Error and Warning Messages¶

-Werror¶

Turn warnings into errors.

-Werror=foo

Turn warning “foo” into an error.

-Wno-error=foo¶

Turn warning “foo” into a warning even if-Werror is specified.

-Wfoo¶

Enable warning “foo”.See thediagnostics reference for a completelist of the warning flags that can be specified in this way.

-Wno-foo¶

Disable warning “foo”.

-w¶

Disable all diagnostics.

-Weverything¶

Enable all diagnostics.

-pedantic¶

Warn on language extensions.

-pedantic-errors¶

Error on language extensions.

-Wsystem-headers¶

Enable warnings from system headers.

-ferror-limit=123¶

Stop emitting diagnostics after 123 errors have been produced. The default is20, and the error limit can be disabled with-ferror-limit=0.

-ftemplate-backtrace-limit=123¶

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.

--warning-suppression-mappings=foo.txt¶

Suppress certain diagnostics for certain files.

Options to Control Clang Crash Diagnostics¶

As unbelievable as it may sound, Clang does crash from time to time.Generally, this only occurs to those living on thebleedingedge. 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.

-fcrash-diagnostics=<val>¶

Valid values are:

• off (Disable auto-generation of preprocessed source files during a clang crash.)

• compiler (Generate diagnostics for compiler crashes (default))

• all (Generate diagnostics for all tools which support it)

-fno-crash-diagnostics¶

Disable auto-generation of preprocessed source files during a clang crash.

The -fno-crash-diagnostics flag can be helpful for speeding the processof generating a delta reduced test case.

-fcrash-diagnostics-dir=<dir>¶

Specify where to write the crash diagnostics files; defaults to theusual location for temporary files.

CLANG_CRASH_DIAGNOSTICS_DIR=<dir>¶

Like-fcrash-diagnostics-dir=<dir>, specifies where to write thecrash diagnostics files, but with lower precedence than the option.

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.

-gen-reproducer¶

Generates preprocessed source files, a reproducer script and if relevant, acache containing: built module pcm’s and all headers needed to rebuild thesame modules.

Options to Emit Optimization Reports¶

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

Clang offers a family of flags which the optimizers can use to emita diagnostic in three cases:

1. When the pass makes a transformation (-Rpass).

2. When the pass fails to make a transformation (-Rpass-missed).

3. When the pass determines whether or not to make a transformation(-Rpass-analysis).

NOTE: Although the discussion below focuses on-Rpass, the exactsame options apply to-Rpass-missed and-Rpass-analysis.

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:

$clang-O2-Rpass=inlinecode.cc-ocodecode.cc:4:25: remark: foo inlined into bar [-Rpass=inline]int bar(int j) { return foo(j, j - 2); }                        ^

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.

Note that when using profile-guided optimization information, profile hotnessinformation can be included in the remarks (see-fdiagnostics-show-hotness).

Options to Emit Resource Consumption Reports¶

These are options that report execution time and consumed memory of differentcompilations steps.

-fproc-stat-report=¶

This option requests driver to print used memory and execution time of eachcompilation step. Theclang 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:

$clang-fproc-stat-report=abcfoo.c$catabcclang-11,"/tmp/foo-123456.o",92000,84000,87536ld,"a.out",900,8000,53568

The data on each row represent:

• file name of the tool executable,

• output file name in quotes,

• total execution time in microseconds,

• execution time in user mode in microseconds,

• peak memory usage in Kb.

It is possible to specify this option without any value. In this case statisticsare printed on standard output in human readable format:

$clang-fproc-stat-reportfoo.cclang-11: output=/tmp/foo-855a8e.o, total=68.000 ms, user=60.000 ms, mem=86920 Kbld: output=a.out, total=8.000 ms, user=4.000 ms, mem=52320 Kb

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.SettingCC_PRINT_PROC_STAT to1 enables the feature, the report goes tostdout in human readable format.SettingCC_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 overCC_PRINT_PROC_STATandCC_PRINT_PROC_STAT_FILE.

$exportCC_PRINT_PROC_STAT=1$exportCC_PRINT_PROC_STAT_FILE=~/project-build-proc-stat.csv$make

Other Options¶

Clang options that don’t fit neatly into other categories.

-fgnuc-version=¶

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.

-MV¶

When emitting a dependency file, use formatting conventions appropriatefor NMake or Jom. Ignored unless another option causes Clang to emit adependency file.

When Clang emits a dependency file (e.g., you supplied the -M option)most filenames can be written to the file without any special formatting.Different Make tools will treat different sets of characters as “special”and use different conventions for telling the Make tool that the characteris actually part of the filename. Normally Clang uses backslash to “escape”a special character, which is the convention used by GNU Make. The -MVoption tells Clang to put double-quotes around the entire filename, whichis the convention used by NMake and Jom.

-femit-dwarf-unwind=<value>¶

When to emit DWARF unwind (EH frame) info. This is a Mach-O-specific option.

Valid values are:

• no-compact-unwind - Only emit DWARF unwind when compact unwind encodingsaren’t available. This is the default for arm64.

• always - Always emit DWARF unwind regardless.

• default - Use the platform-specific default (always for allnon-arm64-platforms).

no-compact-unwind is a performance optimization – Clang will emit smallerobject files that are more quickly processed by the linker. This may causebinary compatibility issues on older x86_64 targets, however, so use it withcaution.

-fdisable-block-signature-string¶

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 possibility when using the flag.

Configuration files¶

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.

Configuration files can be either specified on the command line or loadedfrom default locations. If both variants are present, the default configurationfiles are loaded first.

The command line option--config= can be used to specify explicitconfiguration files in a Clang invocation. If the option is used multiple times,all specified files are loaded, in order. For example:

clang--config=/home/user/cfgs/testing.txtclang--config=debug.cfg--config=runtimes.cfg

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:

• user directory,

• system directory,

• the directory where Clang executable resides.

Both user and system directories for configuration files can be specifiedeither during build or during runtime. At build time, useCLANG_CONFIG_FILE_USER_DIR andCLANG_CONFIG_FILE_SYSTEM_DIR. At runtime use the--config-user-dir= and--config-system-dir= command lineoptions. Specifying config directories at runtime overrides the configdirectories set at build time The first file found is used. It is an error ifthe 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<triple>-<driver>.cfg wheretriple is the triple for the target beingbuilt for, anddriver 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.

The following canonical driver names are used:

• clang for thegcc driver (used to compile C programs)

• clang++ for thegxx driver (used to compile C++ programs)

• clang-cpp for thecpp driver (pure preprocessor)

• clang-cl for thecl driver

• flang for theflang driver

• clang-dxc for thedxc driver

For example, when callingx86_64-pc-linux-gnu-clang-g++,the driver will first attempt to use the configuration file named:

x86_64-pc-linux-gnu-clang++.cfg

If this file is not found, it will attempt to use the name foundin the executable instead:

x86_64-pc-linux-gnu-clang-g++.cfg

Note that options such as--driver-mode=,--target=,-m32 affectthe search algorithm. For example, the aforementioned executable called with-m32 argument will instead search for:

i386-pc-linux-gnu-clang++.cfg

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<driver>.cfg while the latter is named<triple>.cfg. Similarly to the previous variants, the canonical driver namewill be preferred, and the compiler will fall back to the actual name.

For example,x86_64-pc-linux-gnu-clang-g++ will attempt to load twoconfiguration files named respectively:

clang++.cfgx86_64-pc-linux-gnu.cfg

with fallback to trying:

clang-g++.cfgx86_64-pc-linux-gnu.cfg

It is not an error if either of these files is not found.

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:

# Several options on line-c--target=x86_64-unknown-linux-gnu# Long option split between lines-I/usr/lib/gcc/x86_64-linux-gnu/5.4.0/../../../../\include/c++/5.4.0# other config files may be included@linux.options

Files included by@file directives in configuration files are resolvedrelative to the including file. For example, if a configuration file~/.llvm/target.cfg contains the directive@os/linux.opts, the filelinux.opts is searched for in the directory~/.llvm/os. Another way toinclude a file content is using the command line option--config=. It workssimilarly but the included file is searched for using the rules for configurationfiles.

To generate paths relative to the configuration file, the<CFGDIR> token maybe used. This will expand to the absolute path of the directory containing theconfiguration file.

In cases where a configuration file is deployed alongside SDK contents, theSDK directory can remain fully portable by using<CFGDIR> prefixed paths.In this way, the user may only need to specify a root configuration file with--config= to establish every aspect of the SDK with the compiler:

--target=foo-isystem<CFGDIR>/include-L<CFGDIR>/lib-T<CFGDIR>/ldscripts/link.ld

Usually, config file options are placed before command-line options, regardlessof the actual operation to be performed. The exception is being made for theoptions prefixed with the$ character. These will be used only when linkeris being invoked, and added after all of the command-line specified linkerinputs. Here is some example of$-prefixed options:

$-Wl,-Bstatic $-lm$-Wl,-Bshared

Freestanding Builds¶

Passing the-ffreestanding flag causes Clang to build for a freestanding(rather than a hosted) environment. The flag has the following effects:

• the__STDC_HOSTED__ predefined macro will expand to0,

• builtin functions are disabled by default (-fno-builtins),

• unwind tables are disabled by default(fno-asynchronous-unwind-tables-fno-unwind-tables), and

• does not treat the globalmain function as a special function.

An implementation of the following runtime library functions must always beprovided with the usual semantics, as Clang will generate calls to them:

• memcpy,

• memmove, and

• memset.

Clang does not, by itself, provide a full “conforming freestandingimplementation”. If you wish to have a conforming freestanding implementation,you must provide a freestanding C library. While Clang provides some of therequired header files, it does not provide all of them, nor any libraryimplementations.

Conversely, when-ffreestanding is specified, Clang does not require you toprovide a conforming freestanding implementation library. Clang will not makeany assumptions as to the availability or semantics of standard-libraryfunctions other than those mentioned above.

Controlling Errors and Warnings¶

Clang provides a number of ways to control which code constructs causeit to emit errors and warning messages, and how they are displayed tothe console.

#pragma GCC diagnostic ignored "-Wall"

#if foo#endif foo// warning: extra tokens at end of #endif directive#pragma GCC diagnostic push#pragma GCC diagnostic ignored "-Wextra-tokens"#if foo#endif foo// no warning#pragma GCC diagnostic pop

// C only#pragma GCC diagnostic warning "-Wimplicit-function-declaration"intmain(void){puts("");}

// The following will produce warning messages#pragma message "some diagnostic message"#pragma GCC warning "TODO: replace deprecated feature"// The following will produce an error message#pragma GCC error "Not supported"

#define STR(X) #X#define DEFER(M,...) M(__VA_ARGS__)#define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))CUSTOM_ERROR("Feature not available");

#if foo#endif foo// warning: extra tokens at end of #endif directive#pragma clang system_header#if foo#endif foo// no warning

$clang-Ifoo-isystembar--system-header-prefix=x/\--no-system-header-prefix=x/y/

#define _CLANG_DISABLE_CRT_DEPRECATION_WARNINGS#include<stdint.h>    // Clang CRT deprecation warnings are disabled.#include<stdatomic.h> // Clang CRT deprecation warnings are disabled.

$catmappings.txt[unused]src:foo/*$clang--warning-suppression-mappings=mapping.txt-Wunusedfoo/bar.cc#Thiscompilationwon't emit any unused findings for sources under foo/#directory. But it'llstillcomplainforalltheothersources,e.g:$catfoo/bar.cc#include"dir/include.h"//Clangflagsunuseddeclarationshere.#include"foo/include.h"//butunusedwarningsunderthissourceisomitted.#include"next_to_bar_cc.h"//asareunusedwarningsfromthisheaderfile.// Further, unused warnings in the remainder of bar.cc are also omitted.

Precompiled Headers¶

Precompiled headersare a general approach employed by many compilers to reduce compilationtime. The underlying motivation of the approach is that it is common forthe same (and often large) header files to be included by multiplesource files. Consequently, compile times can often be greatly improvedby caching some of the (redundant) work done by a compiler to processheaders. Precompiled header files, which represent one of many ways toimplement this optimization, are literally files that represent anon-disk cache that contains the vital information necessary to reducesome of the work needed to process a corresponding header file. Whiledetails of precompiled headers vary between compilers, precompiledheaders have been shown to be highly effective at speeding up programcompilation on systems with very large system headers (e.g., macOS).

$gcc-xc-headertest.h-otest.h.gch$clang-xc-headertest.h-otest.h.pch

$clang-include-pchtest.h.pchtest.c-otest

$clang-xc-headertest.h-otest.h.pch$cattest.c#include"test.h"$clangtest.c-otest

$clang-xc-headertest.h-Xclang-ignore-pch-otest.h.pch$clang-include-pchtest.h.pch-Xclang-ignore-pchtest.c-otest

#clang-xc-header--relocatable-pch-isysroot/path/to/build/path/to/build/mylib.hmylib.h.pch

Controlling Floating Point Behavior¶

Clang provides a number of ways to control floating point behavior, includingwith command line options and source pragmas. This sectiondescribes the various floating point semantic modes and the corresponding options.

This table describes the option settings that correspond to the threefloating point semantic models: precise (the default), strict, and fast.

The-ffp-model option does not modify thefdenormal-fp-mathsetting, but it does have an impact on whethercrtfastmath.o islinked. Because linkingcrtfastmath.o has a global effect on theprogram, and because the global denormal handling can be changed inother ways, the state offdenormal-fp-math handling cannotbe assumed in any function based on fp-model. SeeA note about crtfastmath.ofor more details.

-ffast-math¶

Enable fast-math mode. This option lets thecompiler make aggressive, potentially-lossy assumptions aboutfloating-point math. These include:

• Floating-point math obeys regular algebraic rules for real numbers (e.g.+ and* are associative,x/y==x*(1/y), and(a+b)*c==a*c+b*c),

• NoNaN or infinite values will be operands or results offloating-point operations,

• +0 and-0 may be treated as interchangeable.

-ffast-math also defines the__FAST_MATH__ preprocessormacro. Some math libraries recognize this macro and change their behavior.With the exception of-ffp-contract=fast, using any of the optionsbelow to disable any of the individual optimizations in-ffast-mathwill cause__FAST_MATH__ to no longer be set.-ffast-math enables-fcx-limited-range.

This option implies:

• -fno-honor-infinities

• -fno-honor-nans

• -fapprox-func

• -fno-math-errno

• -ffinite-math-only

• -fassociative-math

• -freciprocal-math

• -fno-signed-zeros

• -fno-trapping-math

• -fno-rounding-math

• -ffp-contract=fast

Note:-ffast-math causescrtfastmath.o to be linked with code unless-shared or-mno-daz-ftz is present. SeeA note about crtfastmath.o for more details.

-fno-fast-math¶

Disable fast-math mode. This options disables unsafe floating-pointoptimizations by preventing the compiler from making any transformations thatcould affect the results.

This option implies:

• -fhonor-infinities

• -fhonor-nans

• -fno-approx-func

• -fno-finite-math-only

• -fno-associative-math

• -fno-reciprocal-math

• -fsigned-zeros

• -ffp-contract=on

Also, this option resets following options to their target-dependent defaults.

• -f[no-]math-errno

There is ambiguity about how-ffp-contract,-ffast-math,and-fno-fast-math behave when combined. To keep the value of-ffp-contract consistent, we define this set of rules:

• -ffast-math setsffp-contract tofast.

• -fno-fast-math sets-ffp-contract toon (fast for CUDA andHIP).

• If-ffast-math and-ffp-contract are both seen, but-ffast-math is not followed by-fno-fast-math,ffp-contractwill be given the value of whichever option was last seen.

• If-fno-fast-math is seen and-ffp-contract has been seen at leastonce, theffp-contract will get the value of the last seen value of-ffp-contract.

• If-fno-fast-math is seen and-ffp-contract has not been seen, the-ffp-contract setting is determined by the default value of-ffp-contract.

Note:-fno-fast-math causescrtfastmath.o to not be linked with codeunless-mdaz-ftz is present.

-fdenormal-fp-math=<value>¶

Select which denormal numbers the code is permitted to require.

Valid values are:

• ieee - IEEE 754 denormal numbers

• preserve-sign - the sign of a flushed-to-zero number is preserved in the sign of 0

• positive-zero - denormals are flushed to positive zero

The default value depends on the target. For most targets, defaults toieee.

-f[no-]strict-float-cast-overflow¶

When a floating-point value is not representable in a destination integertype, the code has undefined behavior according to the language standard.By default, Clang will not guarantee any particular result in that case.With the ‘no-strict’ option, Clang will saturate towards the smallest andlargest representable integer values instead. NaNs will be converted to zero.Defaults to-fstrict-float-cast-overflow.

-f[no-]math-errno¶

Require math functions to indicate errors by setting errno.The default varies by ToolChain.-fno-math-errno allows optimizationsthat might cause standard C math functions to not seterrno.For example, on some systems, the math functionsqrt is specifiedas settingerrno toEDOM when the input is negative. On thesesystems, the compiler cannot normally optimize a call tosqrt to useinline code (e.g. the x86sqrtsd instruction) without additionalchecking to ensure thaterrno is set appropriately.-fno-math-errno permits these transformations.

On some targets, math library functions never seterrno, and so-fno-math-errno is the default. This includes most BSD-derivedsystems, including Darwin.

-f[no-]trapping-math¶

Control floating point exception behavior.-fno-trapping-math allows optimizations that assume that floating point operations cannot generate traps such as divide-by-zero, overflow and underflow.

• The option-ftrapping-math behaves identically to-ffp-exception-behavior=strict.

• The option-fno-trapping-math behaves identically to-ffp-exception-behavior=ignore. This is the default.

-ffp-contract=<value>¶

Specify when the compiler is permitted to form fused floating-pointoperations, such as fused multiply-add (FMA). Fused operations arepermitted to produce more precise results than performing the sameoperations separately.

The C and C++ standards permit intermediate floating-point results within anexpression to be computed with more precision than their type wouldnormally allow. This permits operation fusing, and Clang takes advantageof this by default (on). Fusion across statements is not compliant withthe C and C++ standards but can be enabled using-ffp-contract=fast.

Fusion can be controlled with theFP_CONTRACT andclangfpcontractpragmas. Please note that pragmas will be ingored with-ffp-contract=fast, and refer to the pragma documentation for adescription of how the pragmas interact with the different-ffp-contractoption values.

Valid values are:

• fast: enable fusion across statements disregarding pragmas, breakingcompliance with the C and C++ standards (default for CUDA).

• on: enable C and C++ standard complaint fusion in the same statementunless dictated by pragmas (default for languages other than CUDA/HIP)

• off: disable fusion

• fast-honor-pragmas: fuse across statements unless dictated by pragmas(default for HIP)

-f[no-]honor-infinities¶

Allow floating-point optimizations that assume arguments and results arenot +-Inf.Defaults to-fhonor-infinities.

If both-fno-honor-infinities and-fno-honor-nans are used,has the same effect as specifying-ffinite-math-only.

-f[no-]honor-nans¶

Allow floating-point optimizations that assume arguments and results arenot NaNs.Defaults to-fhonor-nans.

If both-fno-honor-infinities and-fno-honor-nans are used,has the same effect as specifying-ffinite-math-only.

-f[no-]approx-func¶

Allow certain math function calls (such aslog,sqrt,pow, etc)to be replaced with an approximately equivalent set of instructionsor alternative math function calls. For example, apow(x,0.25)may be replaced withsqrt(sqrt(x)), despite being an inexact resultin cases wherex is-0.0 or-inf.Defaults to-fno-approx-func.

-f[no-]signed-zeros¶

Allow optimizations that ignore the sign of floating point zeros.Defaults to-fsigned-zeros.

-f[no-]associative-math¶

Allow floating point operations to be reassociated.Defaults to-fno-associative-math.

-f[no-]reciprocal-math¶

Allow division operations to be transformed into multiplication by areciprocal. This can be significantly faster than an ordinary divisionbut can also have significantly less precision. Defaults to-fno-reciprocal-math.

-f[no-]unsafe-math-optimizations¶

Allow unsafe floating-point optimizations.-funsafe-math-optimizations also implies:

• -fapprox-func

• -fassociative-math

• -freciprocal-math

• -fno-signed-zeros

• -fno-trapping-math

• -ffp-contract=fast

-fno-unsafe-math-optimizations implies:

• -fno-approx-func

• -fno-associative-math

• -fno-reciprocal-math

• -fsigned-zeros

• -ffp-contract=on

There is ambiguity about how-ffp-contract,-funsafe-math-optimizations, and-fno-unsafe-math-optimizationsbehave when combined. Explanation in-fno-fast-math also appliesto these options.

Defaults to-fno-unsafe-math-optimizations.

-f[no-]finite-math-only¶

Allow floating-point optimizations that assume arguments and results arenot NaNs or +-Inf.-ffinite-math-only defines the__FINITE_MATH_ONLY__ preprocessor macro.-ffinite-math-only implies:

• -fno-honor-infinities

• -fno-honor-nans

-ffno-inite-math-only implies:

• -fhonor-infinities

• -fhonor-nans

Defaults to-fno-finite-math-only.

-f[no-]rounding-math¶

Force floating-point operations to honor the dynamically-set rounding mode by default.

The result of a floating-point operation often cannot be exactly represented in the result type and therefore must be rounded. IEEE 754 describes different rounding modes that control how to perform this rounding, not all of which are supported by all implementations. C provides interfaces (fesetround andfesetenv) for dynamically controlling the rounding mode, and while it also recommends certain conventions for changing the rounding mode, these conventions are not typically enforced in the ABI. Since the rounding mode changes the numerical result of operations, the compiler must understand something about it in order to optimize floating point operations.

Note that floating-point operations performed as part of constant initialization are formally performed prior to the start of the program and are therefore not subject to the current rounding mode. This includes the initialization of global variables and localstatic variables. Floating-point operations in these contexts will be rounded usingFE_TONEAREST.

• The option-fno-rounding-math allows the compiler to assume that the rounding mode is set toFE_TONEAREST. This is the default.

• The option-frounding-math forces the compiler to honor the dynamically-set rounding mode. This prevents optimizations which might affect results if the rounding mode changes or is different from the default; for example, it prevents floating-point operations from being reordered across most calls and prevents constant-folding when the result is not exactly representable.

-ffp-model=<value>¶

Specify floating point behavior.-ffp-model is an umbrellaoption that encompasses functionality provided by other, singlepurpose, floating point options. Valid values are:precise,strict,fast, andaggressive.Details:

• precise Disables optimizations that are not value-safe onfloating-point data, although FP contraction (FMA) is enabled(-ffp-contract=on). This is the default behavior. This value resets-fmath-errno to its target-dependent default.

• strict Enables-frounding-math and-ffp-exception-behavior=strict, and disables contractions (FMA). Allof the-ffast-math enablements are disabled. EnablesSTDCFENV_ACCESS: by defaultFENV_ACCESS is disabled. This optionsetting behaves as though#pragmaSTDCFENV_ACCESSON appeared at thetop of the source file.

• fast Behaves identically to specifying-funsafe-math-optimizations,-fno-math-errno and-fcomplex-arithmetic=promotedffp-contract=fast

• aggressive Behaves identically to specifying both-ffast-math andffp-contract=fast

Note: If your command line specifies multiple instancesof the-ffp-model option, or if your command line option specifies-ffp-model and later on the command line selects a floating pointoption that has the effect of negating part of theffp-model thathas been selected, then the compiler will issue a diagnostic warningthat the override has occurred.

-ffp-exception-behavior=<value>¶

Specify the floating-point exception behavior.

Valid values are:ignore,maytrap, andstrict.The default value isignore. Details:

• ignore The compiler assumes that the exception status flags will not be read and that floating point exceptions will be masked.

• maytrap The compiler avoids transformations that may raise exceptions that would not have been raised by the original code. Constant folding performed by the compiler is exempt from this option.

• strict The compiler ensures that all transformations strictly preserve the floating point exception semantics of the original code.

-ffp-eval-method=<value>¶

Specify the floating-point evaluation method for intermediate results withina single expression of the code.

Valid values are:source,double, andextended.For 64-bit targets, the default value issource. For 32-bit x86 targetshowever, in the case of NETBSD 6.99.26 and under, the default value isdouble; in the case of NETBSD greater than 6.99.26, with NoSSE, thedefault value isextended, with SSE the default value issource.Details:

• source The compiler uses the floating-point type declared in the source program as the evaluation method.

• double The compiler usesdouble as the floating-point evaluation method for all float expressions of type that is narrower thandouble.

• extended The compiler useslongdouble as the floating-point evaluation method for all float expressions of type that is narrower thanlongdouble.

-f[no-]protect-parens¶

This option pertains to floating-point types, complex types withfloating-point components, and vectors of these types. Some arithmeticexpression transformations that are mathematically correct and permissibleaccording to the C and C++ language standards may be incorrect when dealingwith floating-point types, such as reassociation and distribution. Further,the optimizer may ignore parentheses when computing arithmetic expressionsin circumstances where the parenthesized and unparenthesized expressionexpress the same mathematical value. For example (a+b)+c is the samemathematical value as a+(b+c), but the optimizer is free to evaluate theadditions in any order regardless of the parentheses. When enabled, thisoption forces the optimizer to honor the order of operations with respectto parentheses in all circumstances.Defaults to-fno-protect-parens.

Note that floating-point contraction (option-ffp-contract=) is disabledwhen-fprotect-parens is enabled. Also note that in safe floating-pointmodes, such as-ffp-model=precise or-ffp-model=strict, this optionhas no effect because the optimizer is prohibited from making unsafetransformations.

-fexcess-precision:¶

The C and C++ standards allow floating-point expressions to be computed as ifintermediate results had more precision (and/or a wider range) than the typeof the expression strictly allows. This is called excess precisionarithmetic.Excess precision arithmetic can improve the accuracy of results (although notalways), and it can make computation significantly faster if the target lacksdirect hardware support for arithmetic in a particular type. However, it canalso undermine strict floating-point reproducibility.

Under the standards, assignments and explicit casts force the operand to beconverted to its formal type, discarding any excess precision. Because datacan only flow between statements via an assignment, this means that the useof excess precision arithmetic is a reliable local property of a singlestatement, and results do not change based on optimization. However, whenexcess precision arithmetic is in use, Clang does not guarantee strictreproducibility, and future compiler releases may recognize moreopportunities to use excess precision arithmetic, e.g. with floating-pointbuiltins.

Clang does not use excess precision arithmetic for most types or on mosttargets. For example, even on pre-SSE X86 targets wherefloat anddouble computations must be performed in the 80-bit X87 format, Clangrounds all intermediate results correctly for their type. Clang currentlyuses excess precision arithmetic by default only for the following types andtargets:

• _Float16 on X86 targets withoutAVX512-FP16.

The-fexcess-precision=<value> option can be used to control the use ofexcess precision arithmetic. Valid values are:

• standard - The default. Allow the use of excess precision arithmeticunder the constraints of the C and C++ standards. Has no effect except onthe types and targets listed above.

• fast - Accepted for GCC compatibility, but currently treated as analias forstandard.

• 16 - Forces_Float16 operations to be emitted without using excessprecision arithmetic.

-fcomplex-arithmetic=<value>:¶

This option specifies the implementation for complex multiplication and division.

Valid values are:basic,improved,full andpromoted.

• basic Implementation of complex division and multiplication usingalgebraic formulas at source precision. No special handling to avoidoverflow. NaN and infinite values are not handled.

• improved Implementation of complex division using the Smith algorithmat source precision. Smith’s algorithm for complex division.See SMITH, R. L. Algorithm 116: Complex division. Commun. ACM 5, 8 (1962).This value offers improved handling for overflow in intermediatecalculations, but overflow may occur. NaN and infinite values are nothandled in some cases.

• full Implementation of complex division and multiplication using acall to runtime library functions (generally the case, but the BE mightsometimes replace the library call if it knows enough about the potentialrange of the inputs). Overflow and non-finite values are handled by thelibrary implementation. For the case of multiplication overflow will occur inaccordance with normal floating-point rules. This is the default value.

• promoted Implementation of complex division using algebraic formulas athigher precision. Overflow is handled. Non-finite values are handled in somecases. If the target does not have native support for a higher precisiondata type, the implementation for the complex operation using the Smithalgorithm will be used. Overflow may still occur in some cases. NaN andinfinite values are not handled.

-fcx-limited-range:¶

This option is aliased to-fcomplex-arithmetic=basic. It enables thenaive mathematical formulas for complex division and multiplication with noNaN checking of results. The default is-fno-cx-limited-range aliased to-fcomplex-arithmetic=full. This option is enabled by the-ffast-mathoption.

-fcx-fortran-rules:¶

This option is aliased to-fcomplex-arithmetic=improved. It enables thenaive mathematical formulas for complex multiplication and enables applicationof Smith’s algorithm for complex division. See SMITH, R. L. Algorithm 116:Complex division. Commun. ACM 5, 8 (1962).The default is-fno-cx-fortran-rules aliased to-fcomplex-arithmetic=full.

Controlling Code Generation¶

Clang provides a number of ways to control code generation. The optionsare listed below.

-f[no-]sanitize=check1,check2,...¶

Turn on runtime checks for various forms of undefined or suspiciousbehavior.

This option controls whether Clang adds runtime checks for variousforms of undefined or suspicious behavior, and is disabled bydefault. If a check fails, a diagnostic message is produced atruntime explaining the problem. The main checks are:

• -fsanitize=address:AddressSanitizer, a memory errordetector.

• -fsanitize=thread:ThreadSanitizer, a data race detector.

• -fsanitize=memory:MemorySanitizer,a detector of uninitialized reads. Requires instrumentation of allprogram code.

• -fsanitize=undefined:UndefinedBehaviorSanitizer,a fast and compatible undefined behavior checker.

• -fsanitize=type:TypeSanitizer, a detector for strictaliasing violations.

• -fsanitize=dataflow:DataFlowSanitizer, a general dataflow analysis.

• -fsanitize=cfi:control flow integritychecks. Requires-flto.

• -fsanitize=kcfi: kernel indirect call forward-edge control flowintegrity.

• -fsanitize=safe-stack:safe stackprotection against stack-based memory corruption errors.

• -fsanitize=realtime:RealtimeSanitizer,a real-time safety checker.

There are more fine-grained checks available: seethelist of specific kinds ofundefined behavior that can be detected and thelistof control flow integrity schemes.

The-fsanitize= argument must also be provided when linking, inorder to link to the appropriate runtime library.

It is not possible to combine more than one of the-fsanitize=address,-fsanitize=thread, and-fsanitize=memory checkers in the sameprogram.

-f[no-]sanitize-recover=check1,check2,...¶

-f[no-]sanitize-recover[=all]¶

Controls which checks enabled by-fsanitize= flag are non-fatal.If the check is fatal, program will halt after the first errorof this kind is detected and error report is printed.

By default, non-fatal checks are those enabled byUndefinedBehaviorSanitizer,except for-fsanitize=return and-fsanitize=unreachable. Somesanitizers may not support recovery (or not support it by defaulte.g.AddressSanitizer), and always crash the program after the issueis detected.

Note that the-fsanitize-trap flag has precedence over this flag.This means that if a check has been configured to trap elsewhere on thecommand line, or if the check traps by default, this flag will not haveany effect unless that sanitizer’s trapping behavior is disabled with-fno-sanitize-trap.

For example, if a command line contains the flags-fsanitize=undefined-fsanitize-trap=undefined, the flag-fsanitize-recover=alignmentwill have no effect on its own; it will need to be accompanied by-fno-sanitize-trap=alignment.

-f[no-]sanitize-trap=check1,check2,...¶

-f[no-]sanitize-trap[=all]¶

Controls which checks enabled by the-fsanitize= flag trap. Thisoption is intended for use in cases where the sanitizer runtime cannotbe used (for instance, when building libc or a kernel module), or wherethe binary size increase caused by the sanitizer runtime is a concern.

This flag is only compatible withcontrol flow integrity schemes andUndefinedBehaviorSanitizerchecks other thanvptr.

This flag is enabled by default for sanitizers in thecfi group.

-fsanitize-ignorelist=/path/to/ignorelist/file¶

Disable or modify sanitizer checks for objects (source files, functions,variables, types) listed in the file. SeeSanitizer special case list for file format description.

-fno-sanitize-ignorelist¶

Don’t use ignorelist file, if it was specified earlier in the command line.

-f[no-]sanitize-coverage=[type,features,...]¶

Enable simple code coverage in addition to certain sanitizers.SeeSanitizerCoverage for more details.

-f[no-]sanitize-address-outline-instrumentation¶

Controls how address sanitizer code is generated. If enabled will always usea function call instead of inlining the code. Turning this option on couldreduce the binary size, but might result in a worse run-time performance.

See :doc:AddressSanitizer for more details.

-f[no-]sanitize-stats¶

Enable simple statistics gathering for the enabled sanitizers.SeeSanitizerStats for more details.

-fsanitize-undefined-trap-on-error¶

Deprecated alias for-fsanitize-trap=undefined.

-fsanitize-cfi-cross-dso¶

Enable cross-DSO control flow integrity checks. This flag modifiesthe behavior of sanitizers in thecfi group to allow checkingof cross-DSO virtual and indirect calls.

-fsanitize-cfi-icall-generalize-pointers¶

Generalize pointers in return and argument types in function type signatureschecked by Control Flow Integrity indirect call checking. SeeControl Flow Integrity for more details.

-fsanitize-cfi-icall-experimental-normalize-integers¶

Normalize integers in return and argument types in function type signatureschecked by Control Flow Integrity indirect call checking. SeeControl Flow Integrity for more details.

This option is currently experimental.

-fsanitize-kcfi-arity¶

Extends kernel indirect call forward-edge control flow integrity withadditional function arity information (for supported targets). SeeControl Flow Integrity for more details.

-fstrict-vtable-pointers¶

Enable optimizations based on the strict rules for overwriting polymorphicC++ objects, i.e. the vptr is invariant during an object’s lifetime.This enables better devirtualization. Turned off by default, because it isstill experimental.

-fwhole-program-vtables¶

Enable whole-program vtable optimizations, such as single-implementationdevirtualization and virtual constant propagation, for classes withhidden LTO visibility. Requires-flto.

-f[no]split-lto-unit¶

Controls splitting theLTO unit into regular LTO andThinLTO portions, when compiling with -flto=thin. Defaults to falseunless-fsanitize=cfi or-fwhole-program-vtables are specified, inwhich case it defaults to true. Splitting is required withfsanitize=cfi,and it is an error to disable via-fno-split-lto-unit. Splitting isoptional with-fwhole-program-vtables, however, it enables moreaggressive whole program vtable optimizations (specifically virtual constantpropagation).

When enabled, vtable definitions and select virtual functions are placedin the split regular LTO module, enabling more aggressive whole programvtable optimizations required for CFI and virtual constant propagation.However, this can increase the LTO link time and memory requirements overpure ThinLTO, as all split regular LTO modules are merged and LTO linkedwith regular LTO.

-f[no-]unique-source-file-names¶

When enabled, allows the compiler to assume that each object filepassed to the linker has a unique identifier. The identifier foran object file is either the source file path or the value of theargument-funique-source-file-identifier if specified. This isuseful for reducing link times when doing ThinLTO in combination withwhole-program devirtualization or CFI.

The full source path or identifier passed to the compiler must beunique. This means that, for example, the following is a usage error:

$cdfoo$clang-funique-source-file-names-cfoo.c$cd../bar$clang-funique-source-file-names-cfoo.c$cd..$clangfoo/foo.obar/foo.o

but this is not:

$clang-funique-source-file-names-cfoo/foo.c$clang-funique-source-file-names-cbar/foo.c$clangfoo/foo.obar/foo.o

A misuse of this flag may result in a duplicate symbol error atlink time.

-funique-source-file-identifier=IDENTIFIER¶

Used with-funique-source-file-names to specify a source fileidentifier.

-fforce-emit-vtables¶

In order to improve devirtualization, forces emitting of vtables even inmodules where it isn’t necessary. It causes more inline virtual functionsto be emitted.

-fno-assume-sane-operator-new¶

Don’t assume that the C++’s new operator is sane.

This option tells the compiler to do not assume that C++’s globalnew operator will always return a pointer that does not alias anyother pointer when the function returns.

-fassume-nothrow-exception-dtor¶

Assume that an exception object’ destructor will not throw, and generateless code for catch handlers. A throw expression of a type with apotentially-throwing destructor will lead to an error.

By default, Clang assumes that the exception object may have a throwingdestructor. For the Itanium C++ ABI, Clang generates a landing pad todestroy local variables and call_Unwind_Resume for the codecatch(...){...}. This option tells Clang that an exception object’sdestructor will not throw and code simplification is possible.

-ftrap-function=[name]¶

Instruct code generator to emit a function call to the specifiedfunction name for__builtin_trap().

LLVM code generator translates__builtin_trap() to a trapinstruction if it is supported by the target ISA. Otherwise, thebuiltin is translated into a call toabort. If this option isset, then the code generator will always lower the builtin to a callto the specified function regardless of whether the target ISA has atrap instruction. This option is useful for environments (e.g.deeply embedded) where a trap cannot be properly handled, or whensome custom behavior is desired.

-ftls-model=[model]¶

Select which TLS model to use.

Valid values are:global-dynamic,local-dynamic,initial-exec andlocal-exec. The default value isglobal-dynamic. The compiler may use a different model if theselected model is not supported by the target, or if a moreefficient model can be used. The TLS model can be overridden pervariable using thetls_model attribute.

-femulated-tls¶

Select emulated TLS model, which overrides all -ftls-model choices.

In emulated TLS mode, all access to TLS variables are converted tocalls to __emutls_get_address in the runtime library.

-mhwdiv=[values]¶

Select the ARM modes (arm or thumb) that support hardware divisioninstructions.

Valid values are:arm,thumb andarm,thumb.This option is used to indicate which mode (arm or thumb) supportshardware division instructions. This only applies to the ARMarchitecture.

-m[no-]crc¶

Enable or disable CRC instructions.

This option is used to indicate whether CRC instructions are tobe generated. This only applies to the ARM architecture.

CRC instructions are enabled by default on ARMv8.

-mgeneral-regs-only¶

Generate code which only uses the general purpose registers.

This option restricts the generated code to use general registersonly. This only applies to the AArch64 architecture.

-mcompact-branches=[values]¶

Control the usage of compact branches for MIPSR6.

Valid values are:never,optimal andalways.The default value isoptimal which generates compact brancheswhen a delay slot cannot be filled.never disables the usage ofcompact branches andalways generates compact branches wheneverpossible.

-f[no-]max-type-align=[number]¶

Instruct the code generator to not enforce a higher alignment than the givennumber (of bytes) when accessing memory via an opaque pointer or reference.This cap is ignored when directly accessing a variable or when the pointeetype has an explicit “aligned” attribute.

The value should usually be determined by the properties of the system allocator.Some builtin types, especially vector types, have very high natural alignments;when working with values of those types, Clang usually wants to use instructionsthat take advantage of that alignment. However, many system allocators donot promise to return memory that is more than 8-byte or 16-byte-aligned. Usethis option to limit the alignment that the compiler can assume for an arbitrarypointer, which may point onto the heap.

This option does not affect the ABI alignment of types; the layout of structs andunions and the value returned by the alignof operator remain the same.

This option can be overridden on a case-by-case basis by putting an explicit“aligned” alignment on a struct, union, or typedef. For example:

#include<immintrin.h>// Make an aligned typedef of the AVX-512 16-int vector type.typedef __v16si __aligned_v16si __attribute__((aligned(64)));void initialize_vector(__aligned_v16si *v) {  // The compiler may assume that ‘v’ is 64-byte aligned, regardless of the  // value of -fmax-type-align.}

-faddrsig,-fno-addrsig¶

Controls whether Clang emits an address-significance table into the objectfile. Address-significance tables allow linkers to implementsafe ICF without the falsepositives that can result from other implementation techniques such asrelocation scanning. Address-significance tables are enabled by defaulton ELF targets when using the integrated assembler. This flag currentlyonly has an effect on ELF targets.

-f[no]-unique-internal-linkage-names¶

Controls whether Clang emits a unique (best-effort) symbol name for internallinkage symbols. When this option is set, compiler hashes the main sourcefile path from the command line and appends it to all internal symbols. If aprogram contains multiple objects compiled with the same command-line sourcefile path, the symbols are not guaranteed to be unique. This option isparticularly useful in attributing profile information to the correctfunction when multiple functions with the same private linkage name existin the binary.

It should be noted that this option cannot guarantee uniqueness and thefollowing is an example where it is not unique when two modules containsymbols with the same private linkage name:

$cd$P/foo&&clang-c-funique-internal-linkage-namesname_conflict.c$cd$P/bar&&clang-c-funique-internal-linkage-namesname_conflict.c$cd$P&&clangfoo/name_conflict.o&&bar/name_conflict.o

-f[no]-basic-block-address-map:¶

Emitsa``SHT_LLVM_BB_ADDR_MAP``sectionwhichincludesaddressoffsetsforeach¶

basicblockintheprogram,relativetotheparentfunctionaddress.¶

-fbasic-block-sections=[all,list=<arg>,none]¶

Controls how Clang emits text sections for basic blocks. With valuesallandlist=<arg>, each basic block or a subset of basic blocks can be placedin its own unique section.

With thelist=<arg> option, a file containing the subset of basic blocksthat need to placed in unique sections can be specified. The format of thefile is as follows. For example,list=spec.txt wherespec.txt is thefollowing:

!foo!!2!_Z3barv

will place the machine basic block withid2 in functionfoo in aunique section. It will also place all basic blocks of functionsbarin unique sections.

Further, section clusters can also be specified using thelist=<arg>option. For example,list=spec.txt wherespec.txt contains:

!foo!!1 !!3 !!5!!2 !!4 !!6

will create two unique sections for functionfoo with the firstcontaining the odd numbered basic blocks and the second containing theeven numbered basic blocks.

Basic block sections allow the linker to reorder basic blocks and enableslink-time optimizations like whole program inter-procedural basic blockreordering.

-fcodegen-data-generate[=<path>]¶

Emit the raw codegen (CG) data into custom sections in the object file.Currently, this option also combines the raw CG data from the object filesinto an indexed CG data file specified by the <path>, for LLD MachO only.When the <path> is not specified,default.cgdata is created.The CG data file combines all the outlining instances that occurred locallyin each object file.

$clang-fuse-ld=lld-Oz-fcodegen-data-generatecode.cc

For linkers that do not yet support this feature,llvm-cgdata can be usedmanually to merge this CG data in object files.

$clang-c-fuse-ld=lld-Oz-fcodegen-data-generatecode.cc$llvm-cgdata--merge-odefault.cgdatacode.o

-fcodegen-data-use[=<path>]¶

Read the codegen data from the specified path to more effectively outlinefunctions across compilation units. When the <path> is not specified,default.cgdata is used. This option can create many identically outlinedfunctions that can be optimized by the conventional linker’s identical codefolding (ICF).

$clang-fuse-ld=lld-Oz-Wl,--icf=safe-fcodegen-data-usecode.cc

Strict Aliasing¶

The C and C++ standards require accesses to objects in memory to use l-values ofan appropriate type for the object. This is calledstrict aliasing ortype-based alias analysis. Strict aliasing enhances a variety of powerfulmemory optimizations, including reordering, combining, and eliminating memoryaccesses. These optimizations can lead to unexpected behavior in code thatviolates the strict aliasing rules. For example:

voidadvance(size_t*index,double*data){doublevalue=data[*index];/* Clang may assume that this store does not change the contents of `data`. */*index+=1;/* Clang may assume that this store does not change the contents of `index`. */data[*index]=value;/* Either of these facts may create significant optimization opportunities     if Clang is able to inline this function. */}

Strict aliasing can be explicitly enabled with-fstrict-aliasing anddisabled with-fno-strict-aliasing.clang-cl defaults to-fno-strict-aliasing; see . Otherwise, Clang defaults to-fstrict-aliasing.

C and C++ specify slightly different rules for strict aliasing. To improvelanguage interoperability, Clang allows two types to alias if either languagewould permit it. This includes applying the C++ similar types rule to C,allowingint** to aliasintconst*const*. Clang also relaxes thestandard aliasing rules in the following ways:

• All integer types of the same size are permitted to alias each other,including signed and unsigned types.

• void* is permitted to alias any pointer type,void** is permitted toalias any pointer to pointer type, and so on.

Code which violates strict aliasing has undefined behavior. A program thatworks in one version of Clang may not work in another because of changes to theoptimizer. Clang provides aTypeSanitizer to help detectviolations of the strict aliasing rules, but it is currently still experimental.Code that is known to violate strict aliasing should generally be built with-fno-strict-aliasing if the violation cannot be fixed.

Clang supports several ways to fix a violation of strict aliasing:

• L-values of the character typeschar andunsignedchar (as well asother types, depending on the standard) are permitted to access objects ofany type.

• Library functions such asmemcpy andmemset are specified as treatingmemory as characters and therefore are not limited by strict aliasing. If avalue of one type must be reinterpreted as another (e.g. to read the bits of afloating-point number), usememcpy to copy the representation to an objectof the destination type. This has no overhead over a direct l-value accessbecause Clang should reliably optimize calls to these functions to use simpleloads and stores when they are used with small constant sizes.

• The attributemay_alias can be added to atypedef to give l-values ofthat type the same aliasing power as the character types.

Clang makes a best effort to avoid obvious miscompilations from strict aliasingby only considering type information when it cannot prove that two accesses mustrefer to the same memory. However, it is not recommended that programmersintentionally rely on this instead of using one of the solutions above becauseit is too easy for the compiler’s analysis to be blocked in surprising ways.

In Clang 20, Clang strengthened its implementation of strict aliasing foraccesses of pointer type. Previously, all accesses of pointer type werepermitted to alias each other, but Clang now distinguishes different pointersby their pointee type, except as limited by the relaxations around qualifiersandvoid* described above. The previous behavior of treating all pointers asaliasing can be restored using-fno-pointer-tbaa.

Profile Guided Optimization¶

Profile information enables better optimization. For example, knowing that abranch is taken very frequently helps the compiler make better decisions whenordering basic blocks. Knowing that a functionfoo is called morefrequently than another functionbar helps the inliner. Optimizationlevels-O2 and above are recommended for use of profile guided optimization.

Clang supports profile guided optimization with two different kinds ofprofiling. A sampling profiler can generate a profile with very low runtimeoverhead, or you can build an instrumented version of the code that collectsmore detailed profile information. Both kinds of profiles can provide executioncounts for instructions in the code and information on branches taken andfunction invocation.

Regardless of which kind of profiling you use, be careful to collect profilesby running your code with inputs that are representative of the typicalbehavior. Code that is not exercised in the profile will be optimized as if itis unimportant, and the compiler may make poor optimization choices for codethat is disproportionately used while profiling.

function1:total_samples:total_head_samples offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ] offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ] ... offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ] offsetA[.discriminator]: fnA:num_of_total_samples  offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ]  offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ]  offsetB[.discriminator]: fnB:num_of_total_samples   offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ]

main:35504:01: _Z3foov:35504  2: _Z32bari:31977  1.1: 319772: 0

intmain(){initialize();// Reset all profile counters to 0 to omit profile collected during// initialize()'s execution.__llvm_profile_reset_counters();...hotregion1// Dump the profile for hot region 1.__llvm_profile_set_filename("region1.profraw");__llvm_profile_dump();// Reset counters before proceeding to hot region 2.__llvm_profile_reset_counters();...hotregion2// Dump the profile for hot region 2.__llvm_profile_set_filename("region2.profraw");__llvm_profile_dump();// Since the profile has been dumped, no further profile data// will be collected beyond the above __llvm_profile_dump().cleanup();return0;}

__attribute__((weak))int__llvm_profile_dump(void);// Then later in the same source fileif(__llvm_profile_dump)if(__llvm_profile_dump()!=0){...}// The first if condition tests if the symbol is actually defined.// Profile dumping only happens if the symbol is defined. Hence,// the user program works correctly during normal (not profile-generate)// executions.

#include"profile/instr_prof_interface.h"// Then later in the same source fileif(__llvm_profile_dump()!=0){...}

#if __LLVM_INSTR_PROFILE_GENERATEexpensive_logging_of_full_program_state();#endif

fragmentkind fragment1 fragment2

# absl::string_view is considered equivalent to std::string_viewtype N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE# std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++name 3std St3__1name 3std St7__cxx11

GCOV-based Profiling¶

GCOV is a test coverage program, it helps to know how often a line of codeis executed. When instrumenting the code with--coverage option, somecounters are added for each edge linking basic blocks.

At compile time, gcno files are generated containing information aboutblocks and edges between them. At runtime the counters are incremented and atexit the counters are dumped in gcda files.

The toolllvm-covgcov will parse gcno, gcda and source files to generatea report.c.gcov.

-fprofile-filter-files=[regexes]¶

Define a list of regexes separated by a semi-colon.If a file name matches any of the regexes then the file is instrumented.

$clang--coverage-fprofile-filter-files=".*\.c$"foo.c

For example, this will only instrument files finishing with.c, skipping.h files.

-fprofile-exclude-files=[regexes]¶

Define a list of regexes separated by a semi-colon.If a file name doesn’t match all the regexes then the file is instrumented.

$clang--coverage-fprofile-exclude-files="^/usr/include/.*$"foo.c

For example, this will instrument all the files except the ones in/usr/include.

If both options are used then a file is instrumented if its name matches anyof the regexes from-fprofile-filter-list and doesn’t match all the regexesfrom-fprofile-exclude-list.

$clang--coverage-fprofile-exclude-files="^/usr/include/.*$"\-fprofile-filter-files="^/usr/.*$"

In that case/usr/foo/oof.h is instrumented since it matches the filter regex anddoesn’t match the exclude regex, but/usr/include/foo.h doesn’t since it matchesthe exclude regex.

Controlling Debug Information¶

Controlling LLVM IR Output¶

Comment Parsing Options¶

Clang parses Doxygen and non-Doxygen style documentation comments and attachesthem to the appropriate declaration nodes. By default, it only parsesDoxygen-style comments and ignores ordinary comments starting with// and/*.

-Wdocumentation¶

Emit warnings about use of documentation comments. This warning group is offby default.

This includes checking that\param commands name parameters that actuallypresent in the function signature, checking that\returns is used only onfunctions that actually return a value etc.

-Wno-documentation-unknown-command¶

Don’t warn when encountering an unknown Doxygen command.

-fparse-all-comments¶

Parse all comments as documentation comments (including ordinary commentsstarting with// and/*).

-fcomment-block-commands=[commands]¶

Define custom documentation commands as block commands. This allows Clang toconstruct the correct AST for these custom commands, and silences warningsabout unknown commands. Several commands must be separated by a commawithout trailing space; e.g.-fcomment-block-commands=foo,bar definescustom commands\foo and\bar.

It is also possible to use-fcomment-block-commands several times; e.g.-fcomment-block-commands=foo-fcomment-block-commands=bar does the sameas above.

CCC_OVERRIDE_OPTIONS¶

The environment variableCCC_OVERRIDE_OPTIONS can be used to edit clang’scommand line arguments. The value of this variable is a space-separated list ofedits to perform. The edits are applied in the order in which they appear inCCC_OVERRIDE_OPTIONS. Each edit should be one of the following forms:

• #: Silence information about the changes to the command line arguments.

• ^FOO: AddFOO as a new argument at the beginning of the command lineright after the name of the compiler executable.

• +FOO: AddFOO as a new argument at the end of the command line.

• s/XXX/YYY/: Substitute the regular expressionXXX withYYY in thecommand line.

• xOPTION: Removes all instances of the literal argumentOPTION.

• XOPTION: Removes all instances of the literal argumentOPTION, and thefollowing argument.

• Ox: Removes all flags matchingO orO[sz0-9] and addsOx atthe end of the command line.

This environment variable does not affect the options added by the config files.

Extensions supported by clang¶

SeeClang Language Extensions.

Differences between various standard modes¶

clang supports the -std option, which changes what language mode clang uses.The supported modes for C are c89, gnu89, c94, c99, gnu99, c11, gnu11, c17,gnu17, c23, gnu23, c2y, gnu2y, and various aliases for those modes. If no -stdoption is specified, clang defaults to gnu17 mode. Many C99 and C11 featuresare supported in earlier modes as a conforming extension, with a warning. Use-pedantic-errors to request an error if a feature from a later standardrevision is used in an earlier mode.

Differences between allc* andgnu* modes:

• c* modes define “__STRICT_ANSI__”.

• Target-specific defines not prefixed by underscores, likelinux,are defined ingnu* modes.

• Trigraphs default to being off ingnu* modes; they can be enabledby the-trigraphs option.

• The parser recognizesasm andtypeof as keywords ingnu* modes;the variants__asm__ and__typeof__ are recognized in all modes.

• The parser recognizesinline as a keyword ingnu* mode, inaddition to recognizing it in the*99 and later modes for which it ispart of the ISO C standard. The variant__inline__ is recognized in allmodes.

• The Apple “blocks” extension is recognized by default ingnu* modeson some platforms; it can be enabled in any mode with the-fblocksoption.

Differences between*89 and*94 modes:

• Digraphs are not recognized in c89 mode.

Differences between*94 and*99 modes:

• The*99 modes default to implementinginline /__inline__as specified in C99, while the*89 modes implement the GNU version.This can be overridden for individual functions with the__gnu_inline__attribute.

• The scope of names defined inside afor,if,switch,while,ordo statement is different. (example:if((structx{intx;}*)0){}.)

• __STDC_VERSION__ is not defined in*89 modes.

• inline is not recognized as a keyword inc89 mode.

• restrict is not recognized as a keyword in*89 modes.

• Commas are allowed in integer constant expressions in*99 modes.

• Arrays which are not lvalues are not implicitly promoted to pointersin*89 modes.

• Some warnings are different.

Differences between*99 and*11 modes:

• Warnings for use of C11 features are disabled.

• __STDC_VERSION__ is defined to201112L rather than199901L.

Differences between*11 and*17 modes:

• __STDC_VERSION__ is defined to201710L rather than201112L.

Differences between*17 and*23 modes:

• __STDC_VERSION__ is defined to202311L rather than201710L.

• nullptr andnullptr_t are supported, only in*23 mode.

• ATOMIC_VAR_INIT is removed from*23 mode.

• bool,true,false,alignas,alignof,static_assert,andthread_local are now first-class keywords, only in*23 mode.

• typeof andtypeof_unqual are supported, only*23 mode.

• Bit-precise integers (_BitInt(N)) are supported by default in*23mode, and as an extension in*17 and earlier modes.

• [[]] attributes are supported by default in*23 mode, and as anextension in*17 and earlier modes.

Differences between*23 and*2y modes:

• __STDC_VERSION__ is defined to202400L rather than202311L.

GCC extensions not implemented yet¶

clang tries to be compatible with gcc as much as possible, but some gccextensions are not implemented yet:

• clang does not support decimal floating point types (_Decimal32 andfriends) yet.

• clang does not support nested functions; this is a complex featurewhich is infrequently used, so it is unlikely to be implementedanytime soon. In C++11 it can be emulated by assigning lambdafunctions to local variables, e.g:

  autoconstlocal_function=[&](intparameter){// Do something};...local_function(1);

• clang only supports global register variables when the register specifiedis non-allocatable (e.g. the stack pointer). Support for general globalregister variables is unlikely to be implemented soon because it requiresadditional LLVM backend support.

• clang does not support static initialization of flexible arraymembers. This appears to be a rarely used extension, but could beimplemented pending user demand.

• clang does not support__builtin_va_arg_pack/__builtin_va_arg_pack_len. This isused rarely, but in some potentially interesting places, like theglibc headers, so it may be implemented pending user demand. Notethat because clang pretends to be like GCC 4.2, and this extensionwas introduced in 4.3, the glibc headers will not try to use thisextension with clang at the moment.

• clang does not support the gcc extension for forward-declaringfunction parameters; this has not shown up in any real-world codeyet, though, so it might never be implemented.

This is not a complete list; if you find an unsupported extensionmissing from this list, please send an e-mail to cfe-dev. This listcurrently excludes C++; seeC++ Language Features. Also, thislist does not include bugs in mostly-implemented features; please seethebugtrackerfor known existing bugs (FIXME: Is there a section for bug-reportingguidelines somewhere?).

Intentionally unsupported GCC extensions¶

• clang does not support the gcc extension that allows variable-lengtharrays in structures. This is for a few reasons: one, it is tricky toimplement, two, the extension is completely undocumented, and three,the extension appears to be rarely used. Note that clangdoessupport flexible array members (arrays with a zero or unspecifiedsize at the end of a structure).

• GCC accepts many expression forms that are not valid integer constantexpressions in bit-field widths, enumerator constants, case labels,and in array bounds at global scope. Clang also accepts additionalexpression forms in these contexts, but constructs that GCC accepts due tosimplifications GCC performs while parsing, such asx-x (wherex is avariable) will likely never be accepted by Clang.

• clang does not support__builtin_apply and friends; this extensionis extremely obscure and difficult to implement reliably.

Microsoft extensions¶

clang has support for many extensions from Microsoft Visual C++. To enable theseextensions, use the-fms-extensions command-line option. This is the defaultfor Windows targets. Clang does not implement every pragma or declspec providedby MSVC, but the popular ones, such as__declspec(dllexport) and#pragmacomment(lib) are well supported.

clang has a-fms-compatibility flag that makes clang accept enoughinvalid C++ to be able to parse most Microsoft headers. For example, itallowsunqualified lookup of dependent base class members, which isa common compatibility issue with clang. This flag is enabled by defaultfor Windows targets.

-fdelayed-template-parsing lets clang delay parsing of function templatedefinitions until the end of a translation unit. This flag is enabled bydefault for Windows targets.

For compatibility with existing code that compiles with MSVC, clang defines the_MSC_VER and_MSC_FULL_VER macros. When on Windows, these default toeither the same value as the currently installed version of cl.exe, or1933and193300000 (respectively). The-fms-compatibility-version= flagoverrides these values. It accepts a dotted version tuple, such as 19.00.23506.Changing the MSVC compatibility version makes clang behave more like thatversion of MSVC. For example,-fms-compatibility-version=19 will enableC++14 features and definechar16_t andchar32_t as builtin types.

Controlling implementation limits¶

-fbracket-depth=N¶

Sets the limit for nested parentheses, brackets, and braces to N. Thedefault is 256.

-fconstexpr-depth=N¶

Sets the limit for constexpr function invocations to N. The default is 512.

-fconstexpr-steps=N¶

Sets the limit for the number of full-expressions evaluated in a singleconstant expression evaluation. This also controls the maximum sizeof array and dynamic array allocation that can be constant evaluated.The default is 1048576.

-ftemplate-depth=N¶

Sets the limit for recursively nested template instantiations to N. Thedefault is 1024.

-foperator-arrow-depth=N¶

Sets the limit for iterative calls to ‘operator->’ functions to N. Thedefault is 256.

Controlling implementation limits¶

-fopenmp-use-tls¶

Controls code generation for OpenMP threadprivate variables. In presence ofthis option all threadprivate variables are generated the same way as threadlocal variables, using TLS support. If-fno-openmp-use-tlsis provided or target does not support TLS, code generation for threadprivatevariables relies on OpenMP runtime library.

OpenCL Specific Options¶

Most of the OpenCL build options fromthe specification v2.0 section 5.8.4 are available.

Examples:

$clang-cl-std=CL2.0-cl-single-precision-constanttest.cl

Many flags used for the compilation for C sources can also be passed whilecompiling for OpenCL, examples:-c,-O<1-4|s>,-o,-emit-llvm, etc.

Some extra options are available to support special OpenCL features.

-cl-no-stdinc¶

Allows to disable all extra types and functions that are not native to the compiler.This might reduce the compilation speed marginally but many declarations from theOpenCL standard will not be accessible. For example, the following will fail tocompile.

$echo"bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}">test.cl$clang-cl-std=CL2.0-cl-no-stdinctest.clerror: use of undeclared identifier 'get_enqueued_local_size'error: use of undeclared identifier 'get_local_size'

More information about the standard types and functions is provided inthesection on the OpenCL Header.

-cl-ext¶

Enables/Disables support of OpenCL extensions and optional features. All OpenCLtargets set a list of extensions that they support. Clang allows to amend this usingthe-cl-ext flag with a comma-separated list of extensions prefixed with'+' or'-'. The syntax:-cl-ext=<(['-'|'+']<extension>[,])+>, whereextensions can be either one ofthe OpenCL published extensionsor any vendor extension. Alternatively,'all' can be used to enableor disable all known extensions.

Example disabling double support for the 64-bit SPIR-V target:

$clang-c--target=spirv64-cl-ext=-cl_khr_fp64test.cl

Enabling all extensions except double support in R600 AMD GPU can be done using:

$clang--target=r600-cl-ext=-all,+cl_khr_fp16test.cl

Note that some generic targets e.g. SPIR/SPIR-V enable all extensions/features inclang by default.

OpenCL Targets¶

OpenCL targets are derived from the regular Clang target classes. The OpenCLspecific parts of the target representation provide address space mapping aswell as a set of supported extensions.

OpenCL Header¶

By default Clang will include standard headers and therefore most of OpenCLbuiltin functions and types are available during compilation. Thedefault declarations of non-native compiler types and functions can be disabledby using flag-cl-no-stdinc.

The following example demonstrates that OpenCL kernel sources with variousstandard builtin functions can be compiled without the need for an explicitincludes or compiler flags.

$echo"bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}">test.cl$clang-cl-std=CL2.0test.cl

More information about the default headers is provided inOpenCL Support.

OpenCL Extensions¶

Most of thecl_khr_* extensions to OpenCL C fromthe official OpenCLregistry are available andconfigured per target depending on the support available in the specificarchitecture.

It is possible to alter the default extensions setting per target using-cl-ext flag. (Seeflags description for more details).

Vendor extensions can be added flexibly by declaring the list of types andfunctions associated with each extensions enclosed within the followingcompiler pragma directives:

#pragma OPENCL EXTENSION the_new_extension_name : begin// declare types and functions associated with the extension here#pragma OPENCL EXTENSION the_new_extension_name : end

For example, parsing the following code addsmy_t type andmy_funcfunction to the custommy_ext extension.

#pragma OPENCL EXTENSION my_ext : begintypedefstruct{inta;}my_t;voidmy_func(my_t);#pragma OPENCL EXTENSION my_ext : end

There is no conflict resolution for identifier clashes among extensions.It is therefore recommended that the identifiers are prefixed with adouble underscore to avoid clashing with user space identifiers. Vendorextension should use reserved identifier prefix e.g. amd, arm, intel.

Clang also supports language extensions documented inThe OpenCL C LanguageExtensions Documentation.

OpenCL-Specific Attributes¶

OpenCL support in Clang contains a set of attribute taken directly from thespecification as well as additional attributes.

See alsoAttributes in Clang.

C++ for OpenCL¶

Starting from clang 9 kernel code can contain C++17 features: classes, templates,function overloading, type deduction, etc. Please note that this is not animplementation ofOpenCL C++ andthere is no plan to support it in clang in any new releases in the near future.

Clang currently supports C++ for OpenCL 1.0 and 2021.For detailed information about this language refer to the C++ for OpenCLProgramming Language Documentation availableinthe latest buildor inthe official release.

To enable the C++ for OpenCL mode, pass one of following command line options whencompiling.clcpp file:

• C++ for OpenCL 1.0:-cl-std=clc++,-cl-std=CLC++,-cl-std=clc++1.0,-cl-std=CLC++1.0,-std=clc++,-std=CLC++,-std=clc++1.0 or-std=CLC++1.0.

• C++ for OpenCL 2021:-cl-std=clc++2021,-cl-std=CLC++2021,-std=clc++2021,-std=CLC++2021.

Example of use:

template<classT>Tadd(Tx,Ty){returnx+y;}__kernelvoidtest(__globalfloat*a,__globalfloat*b){autoindex=get_global_id(0);a[index]=add(b[index],b[index+1]);}

clang -cl-std=clc++1.0 test.clcppclang -cl-std=clc++ -c --target=spirv64 test.cl

By default, files with.clcpp extension are compiled with the C++ forOpenCL 1.0 mode.

clang test.clcpp

For backward compatibility files with.cl extensions can also be compiledin C++ for OpenCL mode but the desirable language mode must be activated witha flag.

clang -cl-std=clc++ test.cl

Support of C++ for OpenCL 2021 is currently in experimental phase, refer toOpenCL Support for more details.

C++ for OpenCL kernel sources can also be compiled online in drivers supportingcl_ext_cxx_for_openclextension.

CPU Architectures Features and Limitations¶

Operating System Features and Limitations¶