This option, which defaults to on, controls whether or not Clang prints the information on how to fix a specific diagnostic underneath it when it knows.
This information is useful for users who may not understand what is wrong, but can be confusing for machine parsing. Print machine parsable information about source ranges.
This option makes Clang print available Fix-Its in a machine parseable format at the end of diagnostics. The following example illustrates the format:. The range printed is a half-open range, so in this example the characters at column 25 up to but not including column 29 on line 7 in t.
Either the range or the replacement string may be empty representing strict insertions and strict erasures, respectively. The default for template type printing is to elide as many template arguments as possible, removing those which are the same in both template types, leaving only the differences.
Adding this flag will print 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 to display the templates as an indented text tree, one argument per line, with differences marked inline.
This is compatible with -fno-elide-type. With -fdiagnostics-show-template-tree :. This option, which defaults to on, enables warnings about extra tokens at the end of preprocessor directives. These extra tokens are not strictly conforming, and are usually best handled by commenting them out.
Warn about unqualified uses of a member template whose name resolves to another template at the location of the use. As unbelievable as it may sound, Clang does crash from time to time. Generally, this only occurs to those living on the bleeding edge. Clang goes to great lengths to assist you in filing a bug report. Specifically, Clang generates preprocessed source file s and associated run script s upon a crash. These files should be attached to a bug report to ease reproducibility of the failure.
Below are the command line options to control the crash diagnostics. The -fno-crash-diagnostics flag can be helpful for speeding the process of generating a delta reduced test case.
Specify where to write the crash diagnostics files; defaults to the usual location for temporary files. Clang is also capable of generating preprocessed source file s and associated run script s even without a crash. This is specially useful when trying to generate a reproducer for warnings or errors while using modules.
Optimization reports trace, at a high-level, all the major decisions done by compiler transformations. For instance, when the inliner decides to inline function foo into bar , or the loop unroller decides to unroll a loop N times, or the vectorizer decides to vectorize a loop body.
Since there are dozens of passes inside the compiler, each of these flags take a regular expression that identifies the name of the pass which should emit the associated diagnostic. For example, to get a report from the inliner, compile the code with:. However, do not expect a report from every transformation made by the compiler. Optimization remarks do not really make sense outside of the major transformations e.
Note that when using profile-guided optimization information, profile hotness information can be included in the remarks see -fdiagnostics-show-hotness. These are options that report execution time and consumed memory of different compilations steps. This option requests driver to print used memory and execution time of each compilation step. The clang driver during execution calls different tools, like compiler, assembler, linker etc.
With this option the driver reports total execution time, the execution time spent in user mode and peak memory usage of each the called tool. Value of the option specifies where the report is sent to. If it specifies a regular file, the data are saved to this file in CSV format:. It is possible to specify this option without any value. In this case statistics are printed on standard output in human readable format:. The report file specified in the option is locked for write, so this option can be used to collect statistics in parallel builds.
The report file is not cleared, new data is appended to it, thus making posible to accumulate build statistics.
You can also use environment variables to control the process statistics reporting. Specifying a relative path will likely lead to multiple files with the same name created in different directories, since the path is relative to a changing working directory. These environment variables are handy when you need to request the statistics report without changing your build scripts or alter the existing set of compiler options.
This flag does not enable or disable any GCC extensions implemented in Clang. When emitting a dependency file, use formatting conventions appropriate for NMake or Jom. Ignored unless another option causes Clang to emit a dependency file.
When Clang emits a dependency file e. The -MV option tells Clang to put double-quotes around the entire filename, which is the convention used by NMake and Jom. Configuration files group command-line options and allow all of them to be specified just by referencing the configuration file. They may be used, for example, to collect options required to tune compilation for particular target, such as -L, -I, -l, —sysroot, codegen options, etc.
The command line option —config can be used to specify configuration file in a Clang invocation. If the provided argument contains a directory separator, it is considered as a file path, and options are read from that file. Otherwise the argument is treated as a file name and is searched for sequentially in the directories:.
The first file found is used. It is an error if the required file cannot be found. Another way to specify a configuration file is to encode it in executable name. For example, if the Clang executable is named armv7l-clang it may be a symbolic link to clang , then Clang will search for file armv7l. If a driver mode is specified in invocation, Clang tries to find a file specific for the specified mode.
If the command line contains options that effectively change target architecture these are -m32, -EL, and some others and the configuration file starts with an architecture name, Clang tries to load the configuration file for the effective architecture. For example, invocation:. The configuration file consists of command-line options specified on one or more lines.
Lines composed of whitespace characters only are ignored as well as lines in which the first non-blank character is. Long options may be split between several lines by a trailing backslash.
Here is example of a configuration file:. Files included by file directives in configuration files are resolved relative to the including file. This will expand to the absolute path of the directory containing the configuration file. 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:.
Clang provides a number of ways to control which code constructs cause it to emit errors and warning messages, and how they are displayed to the console. When Clang emits a diagnostic, it includes rich information in the output, and gives you fine-grain control over which information is printed. Clang has the ability to print this information, and these are the options that control it:. For more information please see Formatting of Diagnostics.
Though not shown by default, diagnostics may each be associated with a high-level category. This category is intended to make it possible to triage builds that produce a large number of errors or warnings in a grouped way. Categories are not shown by default, but they can be turned on with the -fdiagnostics-show-category option. Clang can also control what diagnostics are enabled through the use of pragmas in the source code. This is useful for turning off specific warnings in a section of source code.
The pragma may control any warning that can be used from the command line. Warnings may be set to ignored, warning, error, or fatal. In the below example -Wextra-tokens is ignored for only a single line of code, after which the diagnostics return to whatever state had previously existed.
The push and pop pragmas will save and restore the full diagnostic state of the compiler, regardless of how it was set.
That means that it is possible to use push and pop around GCC compatible diagnostics and Clang will push and pop them appropriately, while GCC will ignore the pushes and pops as unknown pragmas. It should be noted that while Clang supports the GCC pragma, Clang and GCC do not support the exact same set of warnings, so even when using GCC compatible pragmas there is no guarantee that they will have identical behaviour on both compilers.
In addition to controlling warnings and errors generated by the compiler, it is possible to generate custom warning and error messages through the following pragmas:. Warnings are suppressed when they occur in system headers. By default, an included file is treated as a system header if it is found in an include path specified by -isystem , but this can be overridden in several ways. No warnings will be produced from the location of the pragma onwards within the same file.
When the name in a include directive is found within a header search path and starts with a system prefix, the header is treated as a system header. The last prefix on the command-line which matches the specified header name takes precedence. For instance:. A include directive which finds a file relative to the current directory is treated as including a system header if the including file is treated as a system header.
In addition to the traditional -W flags, one can enable all diagnostics by passing -Weverything. This works as expected with -Werror , and also includes the warnings from -pedantic. If you do use -Weverything then we advise that you address all new compiler diagnostics as they get added to Clang, either by fixing everything they find or explicitly disabling that diagnostic with its corresponding Wno- option.
Note that when combined with -w which disables all warnings , disabling all warnings wins. Precompiled headers are a general approach employed by many compilers to reduce compilation time. The underlying motivation of the approach is that it is common for the same and often large header files to be included by multiple source files.
Consequently, compile times can often be greatly improved by caching some of the redundant work done by a compiler to process headers. Precompiled header files, which represent one of many ways to implement this optimization, are literally files that represent an on-disk cache that contains the vital information necessary to reduce some of the work needed to process a corresponding header file.
While details of precompiled headers vary between compilers, precompiled headers have been shown to be highly effective at speeding up program compilation on systems with very large system headers e.
A PCH file can then be used as a prefix header when a -include option is passed to clang :. The clang driver will first check if a PCH file for test.
Otherwise, Clang falls back to directly processing the content of test. This mirrors the behavior of GCC. Clang does not automatically use PCH files for headers that are directly included within a source file. In this example, clang will not automatically use the PCH file for test. It is sometimes necessary to build a precompiled header from headers that are not yet in their final, installed locations.
For example, one might build a precompiled header within the build tree that is then meant to be installed alongside the headers. To build a relocatable precompiled header, place your headers into a subdirectory whose structure mimics the installed location. For example, if you want to build a precompiled header for the header mylib.
If mylib. Building a relocatable precompiled header requires two additional arguments. First, pass the --relocatable-pch flag to indicate that the resulting PCH file should be relocatable.
When loading the relocatable PCH file, the various headers used in the PCH file are found from the system header root. For example, mylib. If the headers are installed in some other system root, the -isysroot option can be used provide a different system root from which the headers will be based. Relocatable precompiled headers are intended to be used in a limited number of cases where the compilation environment is tightly controlled and the precompiled header cannot be generated after headers have been installed.
Clang provides a number of ways to control floating point behavior, including with command line options and source pragmas. This section describes the various floating point semantic modes and the corresponding options.
This table describes the option settings that correspond to the three floating point semantic models: precise the default , strict, and fast. Enable fast-math mode. This option lets the compiler make aggressive, potentially-lossy assumptions about floating-point math. These include:. Some math libraries recognize this macro and change their behavior.
Require math functions to indicate errors by setting errno. The default varies by ToolChain. For example, on some systems, the math function sqrt is specified as setting errno to EDOM when the input is negative. On these systems, the compiler cannot normally optimize a call to sqrt to use inline code e. On some targets, math library functions never set errno , and so -fno-math-errno is the default. This includes most BSD-derived systems, including Darwin.
Specify when the compiler is permitted to form fused floating-point operations, such as fused multiply-add FMA. Fused operations are permitted to produce more precise results than performing the same operations separately. The C standard permits intermediate floating-point results within an expression to be computed with more precision than their type would normally allow.
This permits operation fusing, and Clang takes advantage of this by default. Please refer to the pragma documentation for a description of how the pragmas interact with this option. Defaults to -fno-unsafe-math-optimizations.
Also implies:. Defaults to -fno-finite-math-only. The result of a floating-point operation often cannot be exactly represented in the result type and therefore must be rounded. IEEE describes different rounding modes that control how to perform this rounding, not all of which are supported by all implementations.
C provides interfaces fesetround and fesetenv 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 local static variables. Specify floating point behavior. Valid values are: precise , strict , and fast.
Note: If your command line specifies multiple instances of the -ffp-model option, or if your command line option specifies -ffp-model and later on the command line selects a floating point option that has the effect of negating part of the ffp-model that has been selected, then the compiler will issue a diagnostic warning that the override has occurred. Valid values are: ignore , maytrap , and strict.
The default value is ignore. This option pertains to floating-point types, complex types with floating-point components, and vectors of these types.
Further, the optimizer may ignore parentheses when computing arithmetic expressions in circumstances where the parenthesized and unparenthesized expression express the same mathematical value. When enabled, this option forces the optimizer to honor the order of operations with respect to parentheses in all circumstances. In C, the only place floating point operations are guaranteed to be evaluated during translation is in the initializers of variables of static storage duration, which are all notionally initialized before the program begins executing and thus before a non-default floating point environment can be entered.
Consider this example when compiled with -frounding-math. This is in line with the C rules; C11 F. All computation for initialization of objects that have static or thread storage duration is done as if at translation time. This option controls whether Clang adds runtime checks for various forms of undefined or suspicious behavior, and is disabled by default. If a check fails, a diagnostic message is produced at runtime explaining the problem. The main checks are:. Requires instrumentation of all program code.
There are more fine-grained checks available: see the list of specific kinds of undefined behavior that can be detected and the list of control flow integrity schemes. If the check is fatal, program will halt after the first error of this kind is detected and error report is printed. Some sanitizers may not support recovery or not support it by default e. AddressSanitizer , and always crash the program after the issue is detected.
Note that the -fsanitize-trap flag has precedence over this flag. This option is intended for use in cases where the sanitizer runtime cannot be used for instance, when building libc or a kernel module , or where the binary size increase caused by the sanitizer runtime is a concern. This flag is only compatible with control flow integrity schemes and UndefinedBehaviorSanitizer checks other than vptr.
This flag is enabled by default for sanitizers in the cfi group. Disable or modify sanitizer checks for objects source files, functions, variables, types listed in the file. See Sanitizer special case list for file format description.
Controls how address sanitizer code is generated. If enabled will always use a function call instead of inlining the code. Turning this option on could reduce the binary size, but might result in a worse run-time performance. Enable cross-DSO control flow integrity checks. This flag modifies the behavior of sanitizers in the cfi group to allow checking of cross-DSO virtual and indirect calls.
Generalize pointers in return and argument types in function type signatures checked by Control Flow Integrity indirect call checking. See Control Flow Integrity for more details. This enables better devirtualization. Turned off by default, because it is still experimental. Enable whole-program vtable optimizations, such as single-implementation devirtualization and virtual constant propagation, for classes with hidden LTO visibility. Requires -flto.
It causes more inline virtual functions to be emitted. Otherwise, the builtin is translated into a call to abort. If this option is set, then the code generator will always lower the builtin to a call to the specified function regardless of whether the target ISA has a trap instruction. This option is useful for environments e.
Valid values are: global-dynamic , local-dynamic , initial-exec and local-exec. The default value is global-dynamic. The compiler may use a different model if the selected model is not supported by the target, or if a more efficient model can be used.
Valid values are: arm , thumb and arm,thumb. This option is used to indicate which mode arm or thumb supports hardware division instructions. This only applies to the ARM architecture. This option is used to indicate whether CRC instructions are to be generated. This option restricts the generated code to use general registers only.
This only applies to the AArch64 architecture. Valid values are: never , optimal and always. The default value is optimal which generates compact branches when a delay slot cannot be filled. Instruct the code generator to not enforce a higher alignment than the given number of bytes when accessing memory via an opaque pointer or reference. 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 instructions that take advantage of that alignment.
However, many system allocators do not promise to return memory that is more than 8-byte or byte-aligned. Use this option to limit the alignment that the compiler can assume for an arbitrary pointer, which may point onto the heap. This option does not affect the ABI alignment of types; the layout of structs and unions and the value returned by the alignof operator remain the same.
Controls whether Clang emits an address-significance table into the object file. Address-significance tables allow linkers to implement safe ICF without the false positives that can result from other implementation techniques such as relocation scanning. Address-significance tables are enabled by default on ELF targets when using the integrated assembler. This flag currently only has an effect on ELF targets.
Controls whether Clang emits a unique best-effort symbol name for internal linkage symbols. When this option is set, compiler hashes the main source file path from the command line and appends it to all internal symbols. If a program contains multiple objects compiled with the same command-line source file path, the symbols are not guaranteed to be unique. This option is particularly useful in attributing profile information to the correct function when multiple functions with the same private linkage name exist in the binary.
It should be noted that this option cannot guarantee uniqueness and the following is an example where it is not unique when two modules contain symbols with the same private linkage name:. Controls how Clang emits text sections for basic blocks. Expressions represent the operations being done on variables, including the assignments to variables.
All of the classes are documented in detail with javadoc. A TranslationUnit represents a single source file. It may only appear as the immediate child of the Program. Declarations appear in many places. As children of TranslationUnit, they represent global declarations of variables, functions, or classes. As parameters of a Procedure, they represent declarations of formal parameters. As children of ClassDeclaration, they representmethods and data members. Expressions are normally of most interest to optimization passes.
All assignments, function calls, and mathematical computations are Expressions. Statements serve two purposes: to provide control constructs, and to provide wrappers for Declarations and Expressions. Statements such as IfStatement provide a control construct, whereas DeclarationStatement and ExpressionStatement simply allow Declarations and Expressions to appear wherever a Statement may appear. Specifiers are most often found in lists. For example, a variable declaration may be prefixed with a list of specifiers such as const and float.
When designing any class hierarchy, some general principles are followed. The main principle is that a derived class satisfies an is a relationship with its parent, such that the data and methods of the parent make sense in the context of the child.
This principle is followed to some extent in Cetus, but it would be more accurate to say that a derived class can appear in the grammar wherever its parent can appear. There is a distinction between the class hierarchy and the syntax tree. For example, in the syntax tree, the parent of a TranslationUnit is a Program, however neither TranslationUnit nor Program have a parent in the class hierarchy.
One important aspect that makes an infrastructure useful is providing a good set of tools to help debug future compiler passes. Cetus provides basic debugging support through the Java language, which contains exceptions and assertions as built-in features. Cetus executes within a Java virtual machine, so a full stack trace including source line numbers is available whenever an exception is caught or the compiler terminates abnormally. Such error reporting is useless unless the IR is designed to prevent programmers from corrupting the program representation.
In other words, there must be a way of detecting the state of the IR is not as it should be, in order to report an error. To provide error checking and detect common errors by pass writers, the Cetus IR maintains several invariants. Violating one of the invariants below will probably result in an exception, to the extent that it is possible for Cetus to recognize what you have done.
You may not take an object that has a parent and add it as the child of another object. If you want to use the same object in more than one place in the syntax tree, you must clone the original object.
An iterator object can be created with P that can iterate over P 's children. In some cases, the iterator will not visit data that is actually part of P itself.
Nearly everything is kept in the list of children, and we may more move data into the list in the future. An object P controls the addition and removal of its children. An object C cannot become the child of an object P without P 's permission.
Before an object C can set its parent reference to an object P , P must already recognize C is a child. C must already be in the list of P 's children. The child reference and parent reference i. The addXYZ methods of many classes will take care of this for you.
There are also atomic swap methods that respect the ordering. Comments, pragmas and other annotations were initially parsed in as Annotations and enclosed inside DeclarationStatements in most cases. In the new implementation, parsed in annotations are converted to a new internal representation through the AnnotationParser. The AnnotationParser stores annotations under corresponding subclasses:. Annotations can be attached to existing IR where the semantics define so or can be inserted as stand-alone IR.
In the above mentioned subclasses, Cetus and Omp Annotations have specific semantics and hence if present in the input source, they are attached to corresponding source IR. However, this is not possible for Comments as it is difficult to determine their association with the IR except for in certain cases which are not handled currently. Hence, all Comments and other annotations are inserted as stand-alone. Annotations that need to be attached to existing IR are stored as member objects of this Annotatable IR Statements and Declarations , the new API for manipulating these is hence available through Annotatable.
Standalone annotations are enclosed in special IR such as AnnotationDeclaration or AnnotationStatement note that AnnotationStatement is different from previous release. Cetus does not contain a code generator. It is a source-to-source compiler, and so it relies on other compilers such as GCC, Intel or Microsoft compiler to compile the source code it outputs.
It is possible that in the future a back end could be added to Cetus, but for research purposes other compilers are more suited to back end optimization work. For passes accepted into the main Cetus distribution, provide a static void run method that accepts a Program object as its only parameter.
We will add a flag to Cetus, named similarly to your pass, that will cause the Cetus driver to call your pass. Derive a class from cetus. Driver and override the runPasses method. You must provide your own main method, which should contain a single line:.
You can optionally override the printUsage and printHelp methods if your pass has additional command-line options. The Driver class contains a protected Program object that your derived class will be able to access in its runPasses method. Note that the run method called in the example above is the run method of the Driver class.
It will process command-line arguments, run the parsers, and get everything ready for your code before calling runPasses. The FlatIterator simply iterates over an object's children, and does not perform a "deep" traversal within the children. An IRIterator can be made to skip objects such that it only returns objects of certain types.
It can also be made to prune parts of the traversal below objects of certain types. IRIterators provide several versions of next that are explained in the examples below. The first example shows how to use the standard next :. Note the exception handling.
The reason is the iterator would have to actually perform the iteration to determine if there was such a next element, and if true, would need to perform the iteration again to actually return the object. The standard hasNext does not have have this problem because it simply checks if it has reached the end of the list.
We think it would be very strange for users if we provided a hasNext method that modified the iterator, and it would be awkward for us to write a hasNext that would look ahead and then undo its changes. Other versions of next will find an element of a set of classes, or an element that is not of a set of classes. Instead of obtaining one iterator on the Program object to look for TranslationUnits, and then obtaining another iterator on each TranslationUnit to look for Procedures, it is easier to do a breadth first search on the entire Program.
However, it does not make much sense to look for Procedures inside other Procedures, since none of the languages supported by Cetus allow nested Procedures. Therefore, pruneOn tells the iterator to skip anything below a Procedure on the IR tree. The cetus. Some of these methods are used only internally, hence are not provided as public methods. DataFlowTools : Utility methods for detecting used or modified memory accesses.
PrintTools : Utility methods that enable pretty printing of collections and user-directed printing of verbose information. SymbolTools : Utility methods related to Cetus' symbol interface. Tools : Utility methods for general purpose. Expression simplifier supports normalization and simplification of expressions. It internally transforms a given expression to a normalized form so that each operand of a commutative and associative operation is located at the same height in the tree representation; in other words, it converts a binary tree to a n-ary tree.
This internal representation makes the simplification algorithm easier and the result of the simplification is converted back to the original internal representation of Cetus. Like its predecessor Polaris, a key feature of Cetus is the ability to reason about the represented program in symbolic terms. For example, compiler analyses and optimizations at the source level often require the expressions in the program to be in a simplified form. A specific example is data dependence analysis that collects the coefficients of affine subscript expressions, which are passed to the underlying data dependence test package.
Cetus has functionalities that ease the manipulation of expressions for pass writers. The following example shows how to invoke the simplifier. The simplifier returns a new copy of the original expression that was converted to a normalized form. It is also possible for users to invoke individual simplification technique for their own purposes.
The following examples show the functionality of the individual simplification technique. See the javadoc page or the source code to learn how to invoke each technique individually. The API provides complete abstraction to the pass writer, and construct specific API help in making the pass writer's job easier.
More details about modifying the IR will be added to this manual in the near future. Please get in touch with us for further support. A major complaint about early versions of Cetus was that the printing of IR was not flexible enough.
To solve this problem, we have made printing completely customizable by the pass writer. Nearly all classes implement a Printable interface, which means they provide a print method for printing themselves as source code.
By default, this print method calls a static method of the same class, called defaultPrint. The call is made by invoking a Java Method object, which is similar to a function pointer in C. The Method object can be changed by calling setPrintMethod and passing it a different printing routine.
If the pass writer notices that they are calling this method frequently for the same type of object, then it may be easier to call setClassPrintMethod , a static method which causes all newly created objects of a particular class to use the provided printing routine. The Cetus Compiler Manual. Table of Contents I. Overview 1. Introduction 2. License II.
Users Guide 4. Obtaining Cetus 5. Building Cetus 6. Developers Guide 8. Part I. Table of Contents 1. Chapter 1. Chapter 2. Chapter 3. Part II. Users Guide. Table of Contents 4. Chapter 4. Obtaining Cetus. The intermediate representation and compiler passes. These are written in Java. Chapter 5. Building Cetus. Chapter 6. Running Cetus. Quick Start. Driver [option] [files].
Command Line Options. Chapter 7. Some expression that will evaluate to a value. Array dimensions must be specified The [] notation is not permitted in the compiler. Arrays of Records are permitted but the record size is always rounded up to the next byte boundary. Attempt to create a pointer to a constant Constant tables are implemented as functions. Pointers cannot be created to functions.
Bad expression syntax This is a generic error message. It covers all incorrect syntax.
0コメント