UsersManual.rst

Clang Compiler User's Manual

• Introduction
  • Terminology
  • Basic Usage
• Command Line Options
  • Options to Control Error and Warning Messages
    • Formatting of Diagnostics
    • Individual Warning Groups
  • Options to Control Clang Crash Diagnostics
  • Options to Emit Optimization Reports
    • Current limitations
• Language and Target-Independent Features
  • Controlling Errors and Warnings
    • Controlling How Clang Displays Diagnostics
    • Diagnostic Mappings
    • Diagnostic Categories
    • Controlling Diagnostics via Command Line Flags
    • Controlling Diagnostics via Pragmas
    • Controlling Diagnostics in System Headers
    • Enabling All Diagnostics
    • Controlling Static Analyzer Diagnostics
  • Precompiled Headers
    • Generating a PCH File
    • Using a PCH File
    • Relocatable PCH Files
  • Controlling Code Generation
  • Profile Guided Optimization
    • Using Sampling Profilers
      • Sample Profile Format
    • Profiling with Instrumentation
  • Controlling Size of Debug Information
  • Comment Parsing Options
• C Language Features
  • Extensions supported by clang
  • Differences between various standard modes
  • GCC extensions not implemented yet
  • Intentionally unsupported GCC extensions
  • Microsoft extensions
• C++ Language Features
  • Controlling implementation limits
• Objective-C Language Features
• Objective-C++ Language Features
• Target-Specific Features and Limitations
  • CPU Architectures Features and Limitations
    • X86
    • ARM
    • PowerPC
    • Other platforms
  • Operating System Features and Limitations
    • Darwin (Mac OS X)
    • Windows
      • Cygwin
      • MinGW32
      • MinGW-w64
• clang-cl
  • Command-Line Options
    • The /fallback Option

Introduction

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

This document describes important notes about using Clang as a compiler for an end-user, documenting the supported features, command line options, etc. If you are interested in using Clang to build a tool that processes code, please see :doc:`InternalsManual`. If you are interested in the Clang Static Analyzer, please see its web page.

Clang is designed to support the C family of programming languages, which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and :ref:`Objective-C++ <objcxx>` as well as many dialects of those. For language-specific information, please see the corresponding language specific section:

• :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO C99 (+TC1, TC2, TC3).
• :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus variants depending on base language.
• :ref:`C++ Language <cxx>`
• :ref:`Objective C++ Language <objcxx>`

In addition to these base languages and their dialects, Clang supports a broad variety of language extensions, which are documented in the corresponding language section. These extensions are provided to be compatible with the GCC, Microsoft, and other popular compilers as well as to improve functionality through Clang-specific features. The Clang driver and language features are intentionally designed to be as compatible with the GNU GCC compiler as reasonably possible, easing migration from GCC to Clang. In most cases, code "just works". Clang also provides an alternative driver, :ref:`clang-cl`, that is designed to be compatible with the Visual C++ compiler, cl.exe.

In addition to language specific features, Clang has a variety of features that depend on what CPU architecture or operating system is being compiled for. Please see the :ref:`Target-Specific Features and Limitations <target_features>` section for more details.

The rest of the introduction introduces some basic :ref:`compiler terminology <terminology>` that is used throughout this manual and contains a basic :ref:`introduction to using Clang <basicusage>` as a command line compiler.

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 optimizations picking a language to use, defaults to C99 by default. Autosenses based on extension. using a makefile

Command Line Options

This section is generally an index into other sections. It does not go into depth on the ones that are covered by other sections. However, the first part introduces the language selection and other high level options like :option:`-c`, :option:`-g`, etc.

Options to Control Error and Warning Messages

-Werror=foo

Turn warning "foo" into an error.

Formatting of Diagnostics

Clang aims to produce beautiful diagnostics by default, particularly for new users that first come to Clang. However, different people have different preferences, and sometimes Clang is driven by another program that wants to parse simple and consistent output, not a person. For these cases, Clang provides a wide range of options to control the exact output format of the diagnostics that it generates.

-f[no-]show-column

Print column number in diagnostic.

This option, which defaults to on, controls whether or not Clang prints the column number of a diagnostic. For example, when this is enabled, Clang will print something like:

test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
#endif bad
       ^
       //

When this is disabled, Clang will print "test.c:28: warning..." with no column number.

The printed column numbers count bytes from the beginning of the line; take care if your source contains multibyte characters.

-f[no-]show-source-location

Print source file/line/column information in diagnostic.

This option, which defaults to on, controls whether or not Clang prints the filename, line number and column number of a diagnostic. For example, when this is enabled, Clang will print something like:

test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
#endif bad
       ^
       //

When this is disabled, Clang will not print the "test.c:28:8: " part.

-f[no-]caret-diagnostics

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

test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
#endif bad
       ^
       //

-f[no-]color-diagnostics

This option, which defaults to on when a color-capable terminal is detected, controls whether or not Clang prints diagnostics in color.

When this option is enabled, Clang will use colors to highlight specific parts of the diagnostic, e.g.,

When this is disabled, Clang will just print:

test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
#endif bad
       ^
       //

-fansi-escape-codes

Controls whether ANSI escape codes are used instead of the Windows Console API to output colored diagnostics. This option is only used on Windows and defaults to off.

-f[no-]diagnostics-show-option

Enable [-Woption] information in diagnostic line.

This option, which defaults to on, controls whether or not Clang prints the associated :ref:`warning group <cl_diag_warning_groups>` option name when outputting a warning diagnostic. For example, in this output:

test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
#endif bad
       ^
       //

Passing -fno-diagnostics-show-option will prevent Clang from printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in the diagnostic. This information tells you the flag needed to enable or disable the diagnostic, either from the command line or through :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.

-f[no-]diagnostics-fixit-info

Enable "FixIt" information in the diagnostics output.

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. For example, in this output:

test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
#endif bad
       ^
       //

Passing -fno-diagnostics-fixit-info will prevent Clang from printing the "//" line at the end of the message. This information is useful for users who may not understand what is wrong, but can be confusing for machine parsing.

-fdiagnostics-print-source-range-info

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

exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
   P = (P-42) + Gamma*4;
       ~~~~~~ ^ ~~~~~~~

The {}'s are generated by -fdiagnostics-print-source-range-info.

The printed column numbers count bytes from the beginning of the line; take care if your source contains multibyte characters.

Individual Warning Groups

TODO: Generate this from tblgen. Define one anchor per warning group.

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 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.

Options to Emit Optimization Reports

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.

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

1. When the pass makes a transformation (:option:`-Rpass`).
2. When the pass fails to make a transformation (:option:`-Rpass-missed`).
3. When the pass determines whether or not to make a transformation (:option:`-Rpass-analysis`).

NOTE: Although the discussion below focuses on :option:`-Rpass`, the exact same options apply to :option:`-Rpass-missed` and :option:`-Rpass-analysis`.

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:

$ clang -O2 -Rpass=inline code.cc -o code
code.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 :option:`-Rpass=.*` (in fact, you can use any valid POSIX regular expression). 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.g., inlining, vectorization, loop optimizations) and not every optimization pass supports this feature.

Current limitations

1. Optimization remarks that refer to function names will display the mangled name of the function. Since these remarks are emitted by the back end of the compiler, it does not know anything about the input language, nor its mangling rules.
2. Some source locations are not displayed correctly. The front end has a more detailed source location tracking than the locations included in the debug info (e.g., the front end can locate code inside macro expansions). However, the locations used by :option:`-Rpass` are translated from debug annotations. That translation can be lossy, which results in some remarks having no location information.

Language and Target-Independent Features

Controlling Errors and Warnings

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.

Controlling How Clang Displays Diagnostics

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:

1. A file/line/column indicator that shows exactly where the diagnostic occurs in your code [:ref:`-fshow-column <opt_fshow-column>`, :ref:`-fshow-source-location <opt_fshow-source-location>`].
2. A categorization of the diagnostic as a note, warning, error, or fatal error.
3. A text string that describes what the problem is.
4. An option that indicates how to control the diagnostic (for diagnostics that support it) [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
5. A :ref:`high-level category <diagnostics_categories>` for the diagnostic for clients that want to group diagnostics by class (for diagnostics that support it) [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
6. The line of source code that the issue occurs on, along with a caret and ranges that indicate the important locations [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
7. "FixIt" information, which is a concise explanation of how to fix the problem (when Clang is certain it knows) [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
8. A machine-parsable representation of the ranges involved (off by default) [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].

For more information please see :ref:`Formatting of Diagnostics <cl_diag_formatting>`.

Diagnostic Mappings

All diagnostics are mapped into one of these 5 classes:

• Ignored
• Note
• Remark
• Warning
• Error
• Fatal

Diagnostic Categories