Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1 | ============================ |
| 2 | Clang Compiler User's Manual |
| 3 | ============================ |
| 4 | |
| 5 | .. contents:: |
| 6 | :local: |
| 7 | |
| 8 | Introduction |
| 9 | ============ |
| 10 | |
| 11 | The Clang Compiler is an open-source compiler for the C family of |
| 12 | programming languages, aiming to be the best in class implementation of |
| 13 | these languages. Clang builds on the LLVM optimizer and code generator, |
| 14 | allowing it to provide high-quality optimization and code generation |
| 15 | support for many targets. For more general information, please see the |
| 16 | `Clang Web Site <http://clang.llvm.org>`_ or the `LLVM Web |
| 17 | Site <http://llvm.org>`_. |
| 18 | |
| 19 | This document describes important notes about using Clang as a compiler |
| 20 | for an end-user, documenting the supported features, command line |
| 21 | options, etc. If you are interested in using Clang to build a tool that |
Dmitri Gribenko | 5cc0580 | 2012-12-15 20:41:17 +0000 | [diff] [blame] | 22 | processes code, please see :doc:`InternalsManual`. If you are interested in the |
| 23 | `Clang Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 24 | page. |
| 25 | |
| 26 | Clang is designed to support the C family of programming languages, |
| 27 | which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and |
| 28 | :ref:`Objective-C++ <objcxx>` as well as many dialects of those. For |
| 29 | language-specific information, please see the corresponding language |
| 30 | specific section: |
| 31 | |
| 32 | - :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO |
| 33 | C99 (+TC1, TC2, TC3). |
| 34 | - :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus |
| 35 | variants depending on base language. |
| 36 | - :ref:`C++ Language <cxx>` |
| 37 | - :ref:`Objective C++ Language <objcxx>` |
| 38 | |
| 39 | In addition to these base languages and their dialects, Clang supports a |
| 40 | broad variety of language extensions, which are documented in the |
| 41 | corresponding language section. These extensions are provided to be |
| 42 | compatible with the GCC, Microsoft, and other popular compilers as well |
| 43 | as to improve functionality through Clang-specific features. The Clang |
| 44 | driver and language features are intentionally designed to be as |
| 45 | compatible with the GNU GCC compiler as reasonably possible, easing |
| 46 | migration from GCC to Clang. In most cases, code "just works". |
Hans Wennborg | 0a6cf66 | 2013-10-10 01:15:16 +0000 | [diff] [blame] | 47 | Clang also provides an alternative driver, :ref:`clang-cl`, that is designed |
| 48 | to be compatible with the Visual C++ compiler, cl.exe. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 49 | |
| 50 | In addition to language specific features, Clang has a variety of |
| 51 | features that depend on what CPU architecture or operating system is |
| 52 | being compiled for. Please see the :ref:`Target-Specific Features and |
| 53 | Limitations <target_features>` section for more details. |
| 54 | |
| 55 | The rest of the introduction introduces some basic :ref:`compiler |
| 56 | terminology <terminology>` that is used throughout this manual and |
| 57 | contains a basic :ref:`introduction to using Clang <basicusage>` as a |
| 58 | command line compiler. |
| 59 | |
| 60 | .. _terminology: |
| 61 | |
| 62 | Terminology |
| 63 | ----------- |
| 64 | |
| 65 | Front end, parser, backend, preprocessor, undefined behavior, |
| 66 | diagnostic, optimizer |
| 67 | |
| 68 | .. _basicusage: |
| 69 | |
| 70 | Basic Usage |
| 71 | ----------- |
| 72 | |
| 73 | Intro to how to use a C compiler for newbies. |
| 74 | |
| 75 | compile + link compile then link debug info enabling optimizations |
| 76 | picking a language to use, defaults to C99 by default. Autosenses based |
| 77 | on extension. using a makefile |
| 78 | |
| 79 | Command Line Options |
| 80 | ==================== |
| 81 | |
| 82 | This section is generally an index into other sections. It does not go |
| 83 | into depth on the ones that are covered by other sections. However, the |
| 84 | first part introduces the language selection and other high level |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 85 | options like :option:`-c`, :option:`-g`, etc. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 86 | |
| 87 | Options to Control Error and Warning Messages |
| 88 | --------------------------------------------- |
| 89 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 90 | .. option:: -Werror |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 91 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 92 | Turn warnings into errors. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 93 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 94 | .. This is in plain monospaced font because it generates the same label as |
| 95 | .. -Werror, and Sphinx complains. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 96 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 97 | ``-Werror=foo`` |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 98 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 99 | Turn warning "foo" into an error. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 100 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 101 | .. option:: -Wno-error=foo |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 102 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 103 | Turn warning "foo" into an warning even if :option:`-Werror` is specified. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 104 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 105 | .. option:: -Wfoo |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 106 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 107 | Enable warning "foo". |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 108 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 109 | .. option:: -Wno-foo |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 110 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 111 | Disable warning "foo". |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 112 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 113 | .. option:: -w |
| 114 | |
| 115 | Disable all warnings. |
| 116 | |
| 117 | .. option:: -Weverything |
| 118 | |
| 119 | :ref:`Enable all warnings. <diagnostics_enable_everything>` |
| 120 | |
| 121 | .. option:: -pedantic |
| 122 | |
| 123 | Warn on language extensions. |
| 124 | |
| 125 | .. option:: -pedantic-errors |
| 126 | |
| 127 | Error on language extensions. |
| 128 | |
| 129 | .. option:: -Wsystem-headers |
| 130 | |
| 131 | Enable warnings from system headers. |
| 132 | |
| 133 | .. option:: -ferror-limit=123 |
| 134 | |
| 135 | Stop emitting diagnostics after 123 errors have been produced. The default is |
| 136 | 20, and the error limit can be disabled with :option:`-ferror-limit=0`. |
| 137 | |
| 138 | .. option:: -ftemplate-backtrace-limit=123 |
| 139 | |
| 140 | Only emit up to 123 template instantiation notes within the template |
| 141 | instantiation backtrace for a single warning or error. The default is 10, and |
| 142 | the limit can be disabled with :option:`-ftemplate-backtrace-limit=0`. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 143 | |
| 144 | .. _cl_diag_formatting: |
| 145 | |
| 146 | Formatting of Diagnostics |
| 147 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 148 | |
| 149 | Clang aims to produce beautiful diagnostics by default, particularly for |
| 150 | new users that first come to Clang. However, different people have |
| 151 | different preferences, and sometimes Clang is driven by another program |
| 152 | that wants to parse simple and consistent output, not a person. For |
| 153 | these cases, Clang provides a wide range of options to control the exact |
| 154 | output format of the diagnostics that it generates. |
| 155 | |
| 156 | .. _opt_fshow-column: |
| 157 | |
| 158 | **-f[no-]show-column** |
| 159 | Print column number in diagnostic. |
| 160 | |
| 161 | This option, which defaults to on, controls whether or not Clang |
| 162 | prints the column number of a diagnostic. For example, when this is |
| 163 | enabled, Clang will print something like: |
| 164 | |
| 165 | :: |
| 166 | |
| 167 | test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] |
| 168 | #endif bad |
| 169 | ^ |
| 170 | // |
| 171 | |
| 172 | When this is disabled, Clang will print "test.c:28: warning..." with |
| 173 | no column number. |
| 174 | |
| 175 | The printed column numbers count bytes from the beginning of the |
| 176 | line; take care if your source contains multibyte characters. |
| 177 | |
| 178 | .. _opt_fshow-source-location: |
| 179 | |
| 180 | **-f[no-]show-source-location** |
| 181 | Print source file/line/column information in diagnostic. |
| 182 | |
| 183 | This option, which defaults to on, controls whether or not Clang |
| 184 | prints the filename, line number and column number of a diagnostic. |
| 185 | For example, when this is enabled, Clang will print something like: |
| 186 | |
| 187 | :: |
| 188 | |
| 189 | test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] |
| 190 | #endif bad |
| 191 | ^ |
| 192 | // |
| 193 | |
| 194 | When this is disabled, Clang will not print the "test.c:28:8: " |
| 195 | part. |
| 196 | |
| 197 | .. _opt_fcaret-diagnostics: |
| 198 | |
| 199 | **-f[no-]caret-diagnostics** |
| 200 | Print source line and ranges from source code in diagnostic. |
| 201 | This option, which defaults to on, controls whether or not Clang |
| 202 | prints the source line, source ranges, and caret when emitting a |
| 203 | diagnostic. For example, when this is enabled, Clang will print |
| 204 | something like: |
| 205 | |
| 206 | :: |
| 207 | |
| 208 | test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] |
| 209 | #endif bad |
| 210 | ^ |
| 211 | // |
| 212 | |
| 213 | **-f[no-]color-diagnostics** |
| 214 | This option, which defaults to on when a color-capable terminal is |
| 215 | detected, controls whether or not Clang prints diagnostics in color. |
| 216 | |
| 217 | When this option is enabled, Clang will use colors to highlight |
| 218 | specific parts of the diagnostic, e.g., |
| 219 | |
| 220 | .. nasty hack to not lose our dignity |
| 221 | |
| 222 | .. raw:: html |
| 223 | |
| 224 | <pre> |
| 225 | <b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b> |
| 226 | #endif bad |
| 227 | <span style="color:green">^</span> |
| 228 | <span style="color:green">//</span> |
| 229 | </pre> |
| 230 | |
| 231 | When this is disabled, Clang will just print: |
| 232 | |
| 233 | :: |
| 234 | |
| 235 | test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] |
| 236 | #endif bad |
| 237 | ^ |
| 238 | // |
| 239 | |
Nico Rieck | 2956ef4 | 2013-09-11 00:38:02 +0000 | [diff] [blame] | 240 | **-fansi-escape-codes** |
| 241 | Controls whether ANSI escape codes are used instead of the Windows Console |
| 242 | API to output colored diagnostics. This option is only used on Windows and |
| 243 | defaults to off. |
| 244 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 245 | .. option:: -fdiagnostics-format=clang/msvc/vi |
| 246 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 247 | Changes diagnostic output format to better match IDEs and command line tools. |
| 248 | |
| 249 | This option controls the output format of the filename, line number, |
| 250 | and column printed in diagnostic messages. The options, and their |
| 251 | affect on formatting a simple conversion diagnostic, follow: |
| 252 | |
| 253 | **clang** (default) |
| 254 | :: |
| 255 | |
| 256 | t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' |
| 257 | |
| 258 | **msvc** |
| 259 | :: |
| 260 | |
| 261 | t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int' |
| 262 | |
| 263 | **vi** |
| 264 | :: |
| 265 | |
| 266 | t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int' |
| 267 | |
| 268 | **-f[no-]diagnostics-show-name** |
| 269 | Enable the display of the diagnostic name. |
| 270 | This option, which defaults to off, controls whether or not Clang |
| 271 | prints the associated name. |
| 272 | |
| 273 | .. _opt_fdiagnostics-show-option: |
| 274 | |
| 275 | **-f[no-]diagnostics-show-option** |
| 276 | Enable ``[-Woption]`` information in diagnostic line. |
| 277 | |
| 278 | This option, which defaults to on, controls whether or not Clang |
| 279 | prints the associated :ref:`warning group <cl_diag_warning_groups>` |
| 280 | option name when outputting a warning diagnostic. For example, in |
| 281 | this output: |
| 282 | |
| 283 | :: |
| 284 | |
| 285 | test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] |
| 286 | #endif bad |
| 287 | ^ |
| 288 | // |
| 289 | |
| 290 | Passing **-fno-diagnostics-show-option** will prevent Clang from |
| 291 | printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in |
| 292 | the diagnostic. This information tells you the flag needed to enable |
| 293 | or disable the diagnostic, either from the command line or through |
| 294 | :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`. |
| 295 | |
| 296 | .. _opt_fdiagnostics-show-category: |
| 297 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 298 | .. option:: -fdiagnostics-show-category=none/id/name |
| 299 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 300 | Enable printing category information in diagnostic line. |
| 301 | |
| 302 | This option, which defaults to "none", controls whether or not Clang |
| 303 | prints the category associated with a diagnostic when emitting it. |
| 304 | Each diagnostic may or many not have an associated category, if it |
| 305 | has one, it is listed in the diagnostic categorization field of the |
| 306 | diagnostic line (in the []'s). |
| 307 | |
| 308 | For example, a format string warning will produce these three |
| 309 | renditions based on the setting of this option: |
| 310 | |
| 311 | :: |
| 312 | |
| 313 | t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat] |
| 314 | t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1] |
| 315 | t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String] |
| 316 | |
| 317 | This category can be used by clients that want to group diagnostics |
| 318 | by category, so it should be a high level category. We want dozens |
| 319 | of these, not hundreds or thousands of them. |
| 320 | |
| 321 | .. _opt_fdiagnostics-fixit-info: |
| 322 | |
| 323 | **-f[no-]diagnostics-fixit-info** |
| 324 | Enable "FixIt" information in the diagnostics output. |
| 325 | |
| 326 | This option, which defaults to on, controls whether or not Clang |
| 327 | prints the information on how to fix a specific diagnostic |
| 328 | underneath it when it knows. For example, in this output: |
| 329 | |
| 330 | :: |
| 331 | |
| 332 | test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] |
| 333 | #endif bad |
| 334 | ^ |
| 335 | // |
| 336 | |
| 337 | Passing **-fno-diagnostics-fixit-info** will prevent Clang from |
| 338 | printing the "//" line at the end of the message. This information |
| 339 | is useful for users who may not understand what is wrong, but can be |
| 340 | confusing for machine parsing. |
| 341 | |
| 342 | .. _opt_fdiagnostics-print-source-range-info: |
| 343 | |
Nico Weber | 727d0d0 | 2013-01-09 05:06:41 +0000 | [diff] [blame] | 344 | **-fdiagnostics-print-source-range-info** |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 345 | Print machine parsable information about source ranges. |
Nico Weber | 727d0d0 | 2013-01-09 05:06:41 +0000 | [diff] [blame] | 346 | This option makes Clang print information about source ranges in a machine |
| 347 | parsable format after the file/line/column number information. The |
| 348 | information is a simple sequence of brace enclosed ranges, where each range |
| 349 | lists the start and end line/column locations. For example, in this output: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 350 | |
| 351 | :: |
| 352 | |
| 353 | exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float') |
| 354 | P = (P-42) + Gamma*4; |
| 355 | ~~~~~~ ^ ~~~~~~~ |
| 356 | |
| 357 | The {}'s are generated by -fdiagnostics-print-source-range-info. |
| 358 | |
| 359 | The printed column numbers count bytes from the beginning of the |
| 360 | line; take care if your source contains multibyte characters. |
| 361 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 362 | .. option:: -fdiagnostics-parseable-fixits |
| 363 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 364 | Print Fix-Its in a machine parseable form. |
| 365 | |
| 366 | This option makes Clang print available Fix-Its in a machine |
| 367 | parseable format at the end of diagnostics. The following example |
| 368 | illustrates the format: |
| 369 | |
| 370 | :: |
| 371 | |
| 372 | fix-it:"t.cpp":{7:25-7:29}:"Gamma" |
| 373 | |
| 374 | The range printed is a half-open range, so in this example the |
| 375 | characters at column 25 up to but not including column 29 on line 7 |
| 376 | in t.cpp should be replaced with the string "Gamma". Either the |
| 377 | range or the replacement string may be empty (representing strict |
| 378 | insertions and strict erasures, respectively). Both the file name |
| 379 | and the insertion string escape backslash (as "\\\\"), tabs (as |
| 380 | "\\t"), newlines (as "\\n"), double quotes(as "\\"") and |
| 381 | non-printable characters (as octal "\\xxx"). |
| 382 | |
| 383 | The printed column numbers count bytes from the beginning of the |
| 384 | line; take care if your source contains multibyte characters. |
| 385 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 386 | .. option:: -fno-elide-type |
| 387 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 388 | Turns off elision in template type printing. |
| 389 | |
| 390 | The default for template type printing is to elide as many template |
| 391 | arguments as possible, removing those which are the same in both |
| 392 | template types, leaving only the differences. Adding this flag will |
| 393 | print all the template arguments. If supported by the terminal, |
| 394 | highlighting will still appear on differing arguments. |
| 395 | |
| 396 | Default: |
| 397 | |
| 398 | :: |
| 399 | |
| 400 | t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument; |
| 401 | |
| 402 | -fno-elide-type: |
| 403 | |
| 404 | :: |
| 405 | |
| 406 | t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, map<float, int>>>' to 'vector<map<int, map<double, int>>>' for 1st argument; |
| 407 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 408 | .. option:: -fdiagnostics-show-template-tree |
| 409 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 410 | Template type diffing prints a text tree. |
| 411 | |
| 412 | For diffing large templated types, this option will cause Clang to |
| 413 | display the templates as an indented text tree, one argument per |
| 414 | line, with differences marked inline. This is compatible with |
| 415 | -fno-elide-type. |
| 416 | |
| 417 | Default: |
| 418 | |
| 419 | :: |
| 420 | |
| 421 | t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument; |
| 422 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 423 | With :option:`-fdiagnostics-show-template-tree`: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 424 | |
| 425 | :: |
| 426 | |
| 427 | t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument; |
| 428 | vector< |
| 429 | map< |
| 430 | [...], |
| 431 | map< |
Richard Trieu | 1ab7778 | 2013-08-09 22:52:48 +0000 | [diff] [blame] | 432 | [float != double], |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 433 | [...]>>> |
| 434 | |
| 435 | .. _cl_diag_warning_groups: |
| 436 | |
| 437 | Individual Warning Groups |
| 438 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 439 | |
| 440 | TODO: Generate this from tblgen. Define one anchor per warning group. |
| 441 | |
| 442 | .. _opt_wextra-tokens: |
| 443 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 444 | .. option:: -Wextra-tokens |
| 445 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 446 | Warn about excess tokens at the end of a preprocessor directive. |
| 447 | |
| 448 | This option, which defaults to on, enables warnings about extra |
| 449 | tokens at the end of preprocessor directives. For example: |
| 450 | |
| 451 | :: |
| 452 | |
| 453 | test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] |
| 454 | #endif bad |
| 455 | ^ |
| 456 | |
| 457 | These extra tokens are not strictly conforming, and are usually best |
| 458 | handled by commenting them out. |
| 459 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 460 | .. option:: -Wambiguous-member-template |
| 461 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 462 | Warn about unqualified uses of a member template whose name resolves to |
| 463 | another template at the location of the use. |
| 464 | |
| 465 | This option, which defaults to on, enables a warning in the |
| 466 | following code: |
| 467 | |
| 468 | :: |
| 469 | |
| 470 | template<typename T> struct set{}; |
| 471 | template<typename T> struct trait { typedef const T& type; }; |
| 472 | struct Value { |
| 473 | template<typename T> void set(typename trait<T>::type value) {} |
| 474 | }; |
| 475 | void foo() { |
| 476 | Value v; |
| 477 | v.set<double>(3.2); |
| 478 | } |
| 479 | |
| 480 | C++ [basic.lookup.classref] requires this to be an error, but, |
| 481 | because it's hard to work around, Clang downgrades it to a warning |
| 482 | as an extension. |
| 483 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 484 | .. option:: -Wbind-to-temporary-copy |
| 485 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 486 | Warn about an unusable copy constructor when binding a reference to a |
| 487 | temporary. |
| 488 | |
| 489 | This option, which defaults to on, enables warnings about binding a |
| 490 | reference to a temporary when the temporary doesn't have a usable |
| 491 | copy constructor. For example: |
| 492 | |
| 493 | :: |
| 494 | |
| 495 | struct NonCopyable { |
| 496 | NonCopyable(); |
| 497 | private: |
| 498 | NonCopyable(const NonCopyable&); |
| 499 | }; |
| 500 | void foo(const NonCopyable&); |
| 501 | void bar() { |
| 502 | foo(NonCopyable()); // Disallowed in C++98; allowed in C++11. |
| 503 | } |
| 504 | |
| 505 | :: |
| 506 | |
| 507 | struct NonCopyable2 { |
| 508 | NonCopyable2(); |
| 509 | NonCopyable2(NonCopyable2&); |
| 510 | }; |
| 511 | void foo(const NonCopyable2&); |
| 512 | void bar() { |
| 513 | foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11. |
| 514 | } |
| 515 | |
| 516 | Note that if ``NonCopyable2::NonCopyable2()`` has a default argument |
| 517 | whose instantiation produces a compile error, that error will still |
| 518 | be a hard error in C++98 mode even if this warning is turned off. |
| 519 | |
| 520 | Options to Control Clang Crash Diagnostics |
| 521 | ------------------------------------------ |
| 522 | |
| 523 | As unbelievable as it may sound, Clang does crash from time to time. |
| 524 | Generally, this only occurs to those living on the `bleeding |
| 525 | edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great |
| 526 | lengths to assist you in filing a bug report. Specifically, Clang |
| 527 | generates preprocessed source file(s) and associated run script(s) upon |
| 528 | a crash. These files should be attached to a bug report to ease |
| 529 | reproducibility of the failure. Below are the command line options to |
| 530 | control the crash diagnostics. |
| 531 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 532 | .. option:: -fno-crash-diagnostics |
| 533 | |
| 534 | Disable auto-generation of preprocessed source files during a clang crash. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 535 | |
| 536 | The -fno-crash-diagnostics flag can be helpful for speeding the process |
| 537 | of generating a delta reduced test case. |
| 538 | |
| 539 | Language and Target-Independent Features |
| 540 | ======================================== |
| 541 | |
| 542 | Controlling Errors and Warnings |
| 543 | ------------------------------- |
| 544 | |
| 545 | Clang provides a number of ways to control which code constructs cause |
| 546 | it to emit errors and warning messages, and how they are displayed to |
| 547 | the console. |
| 548 | |
| 549 | Controlling How Clang Displays Diagnostics |
| 550 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 551 | |
| 552 | When Clang emits a diagnostic, it includes rich information in the |
| 553 | output, and gives you fine-grain control over which information is |
| 554 | printed. Clang has the ability to print this information, and these are |
| 555 | the options that control it: |
| 556 | |
| 557 | #. A file/line/column indicator that shows exactly where the diagnostic |
| 558 | occurs in your code [:ref:`-fshow-column <opt_fshow-column>`, |
| 559 | :ref:`-fshow-source-location <opt_fshow-source-location>`]. |
| 560 | #. A categorization of the diagnostic as a note, warning, error, or |
| 561 | fatal error. |
| 562 | #. A text string that describes what the problem is. |
| 563 | #. An option that indicates how to control the diagnostic (for |
| 564 | diagnostics that support it) |
| 565 | [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`]. |
| 566 | #. A :ref:`high-level category <diagnostics_categories>` for the diagnostic |
| 567 | for clients that want to group diagnostics by class (for diagnostics |
| 568 | that support it) |
| 569 | [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`]. |
| 570 | #. The line of source code that the issue occurs on, along with a caret |
| 571 | and ranges that indicate the important locations |
| 572 | [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`]. |
| 573 | #. "FixIt" information, which is a concise explanation of how to fix the |
| 574 | problem (when Clang is certain it knows) |
| 575 | [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`]. |
| 576 | #. A machine-parsable representation of the ranges involved (off by |
| 577 | default) |
| 578 | [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`]. |
| 579 | |
| 580 | For more information please see :ref:`Formatting of |
| 581 | Diagnostics <cl_diag_formatting>`. |
| 582 | |
| 583 | Diagnostic Mappings |
| 584 | ^^^^^^^^^^^^^^^^^^^ |
| 585 | |
| 586 | All diagnostics are mapped into one of these 5 classes: |
| 587 | |
| 588 | - Ignored |
| 589 | - Note |
| 590 | - Warning |
| 591 | - Error |
| 592 | - Fatal |
| 593 | |
| 594 | .. _diagnostics_categories: |
| 595 | |
| 596 | Diagnostic Categories |
| 597 | ^^^^^^^^^^^^^^^^^^^^^ |
| 598 | |
| 599 | Though not shown by default, diagnostics may each be associated with a |
| 600 | high-level category. This category is intended to make it possible to |
| 601 | triage builds that produce a large number of errors or warnings in a |
| 602 | grouped way. |
| 603 | |
| 604 | Categories are not shown by default, but they can be turned on with the |
| 605 | :ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option. |
| 606 | When set to "``name``", the category is printed textually in the |
| 607 | diagnostic output. When it is set to "``id``", a category number is |
| 608 | printed. The mapping of category names to category id's can be obtained |
| 609 | by running '``clang --print-diagnostic-categories``'. |
| 610 | |
| 611 | Controlling Diagnostics via Command Line Flags |
| 612 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 613 | |
| 614 | TODO: -W flags, -pedantic, etc |
| 615 | |
| 616 | .. _pragma_gcc_diagnostic: |
| 617 | |
| 618 | Controlling Diagnostics via Pragmas |
| 619 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 620 | |
| 621 | Clang can also control what diagnostics are enabled through the use of |
| 622 | pragmas in the source code. This is useful for turning off specific |
| 623 | warnings in a section of source code. Clang supports GCC's pragma for |
| 624 | compatibility with existing source code, as well as several extensions. |
| 625 | |
| 626 | The pragma may control any warning that can be used from the command |
| 627 | line. Warnings may be set to ignored, warning, error, or fatal. The |
| 628 | following example code will tell Clang or GCC to ignore the -Wall |
| 629 | warnings: |
| 630 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 631 | .. code-block:: c |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 632 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 633 | #pragma GCC diagnostic ignored "-Wall" |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 634 | |
| 635 | In addition to all of the functionality provided by GCC's pragma, Clang |
| 636 | also allows you to push and pop the current warning state. This is |
| 637 | particularly useful when writing a header file that will be compiled by |
| 638 | other people, because you don't know what warning flags they build with. |
| 639 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 640 | In the below example :option:`-Wmultichar` is ignored for only a single line of |
| 641 | code, after which the diagnostics return to whatever state had previously |
| 642 | existed. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 643 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 644 | .. code-block:: c |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 645 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 646 | #pragma clang diagnostic push |
| 647 | #pragma clang diagnostic ignored "-Wmultichar" |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 648 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 649 | char b = 'df'; // no warning. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 650 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 651 | #pragma clang diagnostic pop |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 652 | |
| 653 | The push and pop pragmas will save and restore the full diagnostic state |
| 654 | of the compiler, regardless of how it was set. That means that it is |
| 655 | possible to use push and pop around GCC compatible diagnostics and Clang |
| 656 | will push and pop them appropriately, while GCC will ignore the pushes |
| 657 | and pops as unknown pragmas. It should be noted that while Clang |
| 658 | supports the GCC pragma, Clang and GCC do not support the exact same set |
| 659 | of warnings, so even when using GCC compatible #pragmas there is no |
| 660 | guarantee that they will have identical behaviour on both compilers. |
| 661 | |
Andy Gibbs | 076eea2 | 2013-04-17 16:16:16 +0000 | [diff] [blame] | 662 | In addition to controlling warnings and errors generated by the compiler, it is |
| 663 | possible to generate custom warning and error messages through the following |
| 664 | pragmas: |
| 665 | |
| 666 | .. code-block:: c |
| 667 | |
| 668 | // The following will produce warning messages |
| 669 | #pragma message "some diagnostic message" |
| 670 | #pragma GCC warning "TODO: replace deprecated feature" |
| 671 | |
| 672 | // The following will produce an error message |
| 673 | #pragma GCC error "Not supported" |
| 674 | |
| 675 | These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor |
| 676 | directives, except that they may also be embedded into preprocessor macros via |
| 677 | the C99 ``_Pragma`` operator, for example: |
| 678 | |
| 679 | .. code-block:: c |
| 680 | |
| 681 | #define STR(X) #X |
| 682 | #define DEFER(M,...) M(__VA_ARGS__) |
| 683 | #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__)))) |
| 684 | |
| 685 | CUSTOM_ERROR("Feature not available"); |
| 686 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 687 | Controlling Diagnostics in System Headers |
| 688 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 689 | |
| 690 | Warnings are suppressed when they occur in system headers. By default, |
| 691 | an included file is treated as a system header if it is found in an |
| 692 | include path specified by ``-isystem``, but this can be overridden in |
| 693 | several ways. |
| 694 | |
| 695 | The ``system_header`` pragma can be used to mark the current file as |
| 696 | being a system header. No warnings will be produced from the location of |
| 697 | the pragma onwards within the same file. |
| 698 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 699 | .. code-block:: c |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 700 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 701 | char a = 'xy'; // warning |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 702 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 703 | #pragma clang system_header |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 704 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 705 | char b = 'ab'; // no warning |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 706 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 707 | The :option:`-isystem-prefix` and :option:`-ino-system-prefix` command-line |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 708 | arguments can be used to override whether subsets of an include path are |
| 709 | treated as system headers. When the name in a ``#include`` directive is |
| 710 | found within a header search path and starts with a system prefix, the |
| 711 | header is treated as a system header. The last prefix on the |
| 712 | command-line which matches the specified header name takes precedence. |
| 713 | For instance: |
| 714 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 715 | .. code-block:: console |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 716 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 717 | $ clang -Ifoo -isystem bar -isystem-prefix x/ -ino-system-prefix x/y/ |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 718 | |
| 719 | Here, ``#include "x/a.h"`` is treated as including a system header, even |
| 720 | if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated |
| 721 | as not including a system header, even if the header is found in |
| 722 | ``bar``. |
| 723 | |
| 724 | A ``#include`` directive which finds a file relative to the current |
| 725 | directory is treated as including a system header if the including file |
| 726 | is treated as a system header. |
| 727 | |
| 728 | .. _diagnostics_enable_everything: |
| 729 | |
| 730 | Enabling All Warnings |
| 731 | ^^^^^^^^^^^^^^^^^^^^^ |
| 732 | |
| 733 | In addition to the traditional ``-W`` flags, one can enable **all** |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 734 | warnings by passing :option:`-Weverything`. This works as expected with |
| 735 | :option:`-Werror`, and also includes the warnings from :option:`-pedantic`. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 736 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 737 | Note that when combined with :option:`-w` (which disables all warnings), that |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 738 | flag wins. |
| 739 | |
| 740 | Controlling Static Analyzer Diagnostics |
| 741 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 742 | |
| 743 | While not strictly part of the compiler, the diagnostics from Clang's |
| 744 | `static analyzer <http://clang-analyzer.llvm.org>`_ can also be |
| 745 | influenced by the user via changes to the source code. See the available |
| 746 | `annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the |
| 747 | analyzer's `FAQ |
| 748 | page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more |
| 749 | information. |
| 750 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 751 | .. _usersmanual-precompiled-headers: |
| 752 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 753 | Precompiled Headers |
| 754 | ------------------- |
| 755 | |
| 756 | `Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__ |
| 757 | are a general approach employed by many compilers to reduce compilation |
| 758 | time. The underlying motivation of the approach is that it is common for |
| 759 | the same (and often large) header files to be included by multiple |
| 760 | source files. Consequently, compile times can often be greatly improved |
| 761 | by caching some of the (redundant) work done by a compiler to process |
| 762 | headers. Precompiled header files, which represent one of many ways to |
| 763 | implement this optimization, are literally files that represent an |
| 764 | on-disk cache that contains the vital information necessary to reduce |
| 765 | some of the work needed to process a corresponding header file. While |
| 766 | details of precompiled headers vary between compilers, precompiled |
| 767 | headers have been shown to be highly effective at speeding up program |
| 768 | compilation on systems with very large system headers (e.g., Mac OS/X). |
| 769 | |
| 770 | Generating a PCH File |
| 771 | ^^^^^^^^^^^^^^^^^^^^^ |
| 772 | |
| 773 | To generate a PCH file using Clang, one invokes Clang with the |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 774 | :option:`-x <language>-header` option. This mirrors the interface in GCC |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 775 | for generating PCH files: |
| 776 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 777 | .. code-block:: console |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 778 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 779 | $ gcc -x c-header test.h -o test.h.gch |
| 780 | $ clang -x c-header test.h -o test.h.pch |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 781 | |
| 782 | Using a PCH File |
| 783 | ^^^^^^^^^^^^^^^^ |
| 784 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 785 | A PCH file can then be used as a prefix header when a :option:`-include` |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 786 | option is passed to ``clang``: |
| 787 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 788 | .. code-block:: console |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 789 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 790 | $ clang -include test.h test.c -o test |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 791 | |
| 792 | The ``clang`` driver will first check if a PCH file for ``test.h`` is |
| 793 | available; if so, the contents of ``test.h`` (and the files it includes) |
| 794 | will be processed from the PCH file. Otherwise, Clang falls back to |
| 795 | directly processing the content of ``test.h``. This mirrors the behavior |
| 796 | of GCC. |
| 797 | |
| 798 | .. note:: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 799 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 800 | Clang does *not* automatically use PCH files for headers that are directly |
| 801 | included within a source file. For example: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 802 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 803 | .. code-block:: console |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 804 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 805 | $ clang -x c-header test.h -o test.h.pch |
| 806 | $ cat test.c |
| 807 | #include "test.h" |
| 808 | $ clang test.c -o test |
| 809 | |
| 810 | In this example, ``clang`` will not automatically use the PCH file for |
| 811 | ``test.h`` since ``test.h`` was included directly in the source file and not |
| 812 | specified on the command line using :option:`-include`. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 813 | |
| 814 | Relocatable PCH Files |
| 815 | ^^^^^^^^^^^^^^^^^^^^^ |
| 816 | |
| 817 | It is sometimes necessary to build a precompiled header from headers |
| 818 | that are not yet in their final, installed locations. For example, one |
| 819 | might build a precompiled header within the build tree that is then |
| 820 | meant to be installed alongside the headers. Clang permits the creation |
| 821 | of "relocatable" precompiled headers, which are built with a given path |
| 822 | (into the build directory) and can later be used from an installed |
| 823 | location. |
| 824 | |
| 825 | To build a relocatable precompiled header, place your headers into a |
| 826 | subdirectory whose structure mimics the installed location. For example, |
| 827 | if you want to build a precompiled header for the header ``mylib.h`` |
| 828 | that will be installed into ``/usr/include``, create a subdirectory |
| 829 | ``build/usr/include`` and place the header ``mylib.h`` into that |
| 830 | subdirectory. If ``mylib.h`` depends on other headers, then they can be |
| 831 | stored within ``build/usr/include`` in a way that mimics the installed |
| 832 | location. |
| 833 | |
| 834 | Building a relocatable precompiled header requires two additional |
| 835 | arguments. First, pass the ``--relocatable-pch`` flag to indicate that |
| 836 | the resulting PCH file should be relocatable. Second, pass |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 837 | :option:`-isysroot /path/to/build`, which makes all includes for your library |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 838 | relative to the build directory. For example: |
| 839 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 840 | .. code-block:: console |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 841 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 842 | # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 843 | |
| 844 | When loading the relocatable PCH file, the various headers used in the |
| 845 | PCH file are found from the system header root. For example, ``mylib.h`` |
| 846 | can be found in ``/usr/include/mylib.h``. If the headers are installed |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 847 | in some other system root, the :option:`-isysroot` option can be used provide |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 848 | a different system root from which the headers will be based. For |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 849 | example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 850 | ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``. |
| 851 | |
| 852 | Relocatable precompiled headers are intended to be used in a limited |
| 853 | number of cases where the compilation environment is tightly controlled |
| 854 | and the precompiled header cannot be generated after headers have been |
Argyrios Kyrtzidis | 8c42a67 | 2013-02-14 00:12:44 +0000 | [diff] [blame] | 855 | installed. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 856 | |
| 857 | Controlling Code Generation |
| 858 | --------------------------- |
| 859 | |
| 860 | Clang provides a number of ways to control code generation. The options |
| 861 | are listed below. |
| 862 | |
Sean Silva | fb1ff86 | 2013-06-21 23:50:58 +0000 | [diff] [blame] | 863 | **-f[no-]sanitize=check1,check2,...** |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 864 | Turn on runtime checks for various forms of undefined or suspicious |
| 865 | behavior. |
| 866 | |
| 867 | This option controls whether Clang adds runtime checks for various |
| 868 | forms of undefined or suspicious behavior, and is disabled by |
| 869 | default. If a check fails, a diagnostic message is produced at |
| 870 | runtime explaining the problem. The main checks are: |
| 871 | |
Richard Smith | 2dce7be | 2012-12-13 07:29:23 +0000 | [diff] [blame] | 872 | - .. _opt_fsanitize_address: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 873 | |
Richard Smith | 2dce7be | 2012-12-13 07:29:23 +0000 | [diff] [blame] | 874 | ``-fsanitize=address``: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 875 | :doc:`AddressSanitizer`, a memory error |
| 876 | detector. |
Alexey Samsonov | f37b1e2 | 2013-03-14 12:26:21 +0000 | [diff] [blame] | 877 | - ``-fsanitize=init-order``: Make AddressSanitizer check for |
| 878 | dynamic initialization order problems. Implied by ``-fsanitize=address``. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 879 | - ``-fsanitize=address-full``: AddressSanitizer with all the |
| 880 | experimental features listed below. |
| 881 | - ``-fsanitize=integer``: Enables checks for undefined or |
| 882 | suspicious integer behavior. |
Richard Smith | 2dce7be | 2012-12-13 07:29:23 +0000 | [diff] [blame] | 883 | - .. _opt_fsanitize_thread: |
| 884 | |
Dmitry Vyukov | 7f5e76b | 2012-12-21 08:21:25 +0000 | [diff] [blame] | 885 | ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector. |
Evgeniy Stepanov | cc603e9 | 2012-12-21 10:50:00 +0000 | [diff] [blame] | 886 | - .. _opt_fsanitize_memory: |
| 887 | |
| 888 | ``-fsanitize=memory``: :doc:`MemorySanitizer`, |
| 889 | an *experimental* detector of uninitialized reads. Not ready for |
| 890 | widespread use. |
Richard Smith | 2dce7be | 2012-12-13 07:29:23 +0000 | [diff] [blame] | 891 | - .. _opt_fsanitize_undefined: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 892 | |
Richard Smith | 2dce7be | 2012-12-13 07:29:23 +0000 | [diff] [blame] | 893 | ``-fsanitize=undefined``: Fast and compatible undefined behavior |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 894 | checker. Enables the undefined behavior checks that have small |
| 895 | runtime cost and no impact on address space layout or ABI. This |
| 896 | includes all of the checks listed below other than |
| 897 | ``unsigned-integer-overflow``. |
| 898 | |
Richard Smith | a0ed171 | 2013-05-29 22:57:31 +0000 | [diff] [blame] | 899 | - ``-fsanitize=undefined-trap``: This includes all sanitizers |
Chad Rosier | 78d85b1 | 2013-01-29 23:31:22 +0000 | [diff] [blame] | 900 | included by ``-fsanitize=undefined``, except those that require |
Richard Smith | a0ed171 | 2013-05-29 22:57:31 +0000 | [diff] [blame] | 901 | runtime support. This group of sanitizers is intended to be |
| 902 | used in conjunction with the ``-fsanitize-undefined-trap-on-error`` |
| 903 | flag. This includes all of the checks listed below other than |
| 904 | ``unsigned-integer-overflow`` and ``vptr``. |
Peter Collingbourne | 2eeed71 | 2013-08-07 22:47:34 +0000 | [diff] [blame] | 905 | - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data |
| 906 | flow analysis. |
Chad Rosier | 78d85b1 | 2013-01-29 23:31:22 +0000 | [diff] [blame] | 907 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 908 | The following more fine-grained checks are also available: |
| 909 | |
| 910 | - ``-fsanitize=alignment``: Use of a misaligned pointer or creation |
| 911 | of a misaligned reference. |
Richard Smith | 463b48b | 2012-12-13 07:11:50 +0000 | [diff] [blame] | 912 | - ``-fsanitize=bool``: Load of a ``bool`` value which is neither |
| 913 | ``true`` nor ``false``. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 914 | - ``-fsanitize=bounds``: Out of bounds array indexing, in cases |
| 915 | where the array bound can be statically determined. |
Richard Smith | 463b48b | 2012-12-13 07:11:50 +0000 | [diff] [blame] | 916 | - ``-fsanitize=enum``: Load of a value of an enumerated type which |
| 917 | is not in the range of representable values for that enumerated |
| 918 | type. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 919 | - ``-fsanitize=float-cast-overflow``: Conversion to, from, or |
| 920 | between floating-point types which would overflow the |
| 921 | destination. |
| 922 | - ``-fsanitize=float-divide-by-zero``: Floating point division by |
| 923 | zero. |
Peter Collingbourne | b914e87 | 2013-10-20 21:29:19 +0000 | [diff] [blame] | 924 | - ``-fsanitize=function``: Indirect call of a function through a |
Peter Collingbourne | 23782ec | 2013-10-26 00:21:57 +0000 | [diff] [blame] | 925 | function pointer of the wrong type (Linux, C++ and x86/x86_64 only). |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 926 | - ``-fsanitize=integer-divide-by-zero``: Integer division by zero. |
| 927 | - ``-fsanitize=null``: Use of a null pointer or creation of a null |
| 928 | reference. |
| 929 | - ``-fsanitize=object-size``: An attempt to use bytes which the |
| 930 | optimizer can determine are not part of the object being |
| 931 | accessed. The sizes of objects are determined using |
| 932 | ``__builtin_object_size``, and consequently may be able to detect |
| 933 | more problems at higher optimization levels. |
| 934 | - ``-fsanitize=return``: In C++, reaching the end of a |
| 935 | value-returning function without returning a value. |
| 936 | - ``-fsanitize=shift``: Shift operators where the amount shifted is |
| 937 | greater or equal to the promoted bit-width of the left hand side |
| 938 | or less than zero, or where the left hand side is negative. For a |
| 939 | signed left shift, also checks for signed overflow in C, and for |
| 940 | unsigned overflow in C++. |
| 941 | - ``-fsanitize=signed-integer-overflow``: Signed integer overflow, |
| 942 | including all the checks added by ``-ftrapv``, and checking for |
| 943 | overflow in signed division (``INT_MIN / -1``). |
| 944 | - ``-fsanitize=unreachable``: If control flow reaches |
| 945 | ``__builtin_unreachable``. |
| 946 | - ``-fsanitize=unsigned-integer-overflow``: Unsigned integer |
| 947 | overflows. |
| 948 | - ``-fsanitize=vla-bound``: A variable-length array whose bound |
| 949 | does not evaluate to a positive value. |
| 950 | - ``-fsanitize=vptr``: Use of an object whose vptr indicates that |
| 951 | it is of the wrong dynamic type, or that its lifetime has not |
| 952 | begun or has ended. Incompatible with ``-fno-rtti``. |
| 953 | |
Alexey Samsonov | 05654ff | 2013-08-07 08:23:32 +0000 | [diff] [blame] | 954 | You can turn off or modify checks for certain source files, functions |
| 955 | or even variables by providing a special file: |
| 956 | |
| 957 | - ``-fsanitize-blacklist=/path/to/blacklist/file``: disable or modify |
| 958 | sanitizer checks for objects listed in the file. See |
| 959 | :doc:`SanitizerSpecialCaseList` for file format description. |
| 960 | - ``-fno-sanitize-blacklist``: don't use blacklist file, if it was |
| 961 | specified earlier in the command line. |
| 962 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 963 | Experimental features of AddressSanitizer (not ready for widespread |
| 964 | use, require explicit ``-fsanitize=address``): |
| 965 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 966 | - ``-fsanitize=use-after-return``: Check for use-after-return |
| 967 | errors (accessing local variable after the function exit). |
| 968 | - ``-fsanitize=use-after-scope``: Check for use-after-scope errors |
| 969 | (accesing local variable after it went out of scope). |
| 970 | |
Evgeniy Stepanov | cc603e9 | 2012-12-21 10:50:00 +0000 | [diff] [blame] | 971 | Extra features of MemorySanitizer (require explicit |
| 972 | ``-fsanitize=memory``): |
| 973 | |
| 974 | - ``-fsanitize-memory-track-origins``: Enables origin tracking in |
Evgeniy Stepanov | 583acae | 2012-12-21 10:53:20 +0000 | [diff] [blame] | 975 | MemorySanitizer. Adds a second section to MemorySanitizer |
| 976 | reports pointing to the heap or stack allocation the |
| 977 | uninitialized bits came from. Slows down execution by additional |
| 978 | 1.5x-2x. |
Evgeniy Stepanov | cc603e9 | 2012-12-21 10:50:00 +0000 | [diff] [blame] | 979 | |
Richard Smith | a0ed171 | 2013-05-29 22:57:31 +0000 | [diff] [blame] | 980 | Extra features of UndefinedBehaviorSanitizer: |
| 981 | |
| 982 | - ``-fno-sanitize-recover``: By default, after a sanitizer diagnoses |
| 983 | an issue, it will attempt to continue executing the program if there |
| 984 | is a reasonable behavior it can give to the faulting operation. This |
| 985 | option causes the program to abort instead. |
| 986 | - ``-fsanitize-undefined-trap-on-error``: Causes traps to be emitted |
| 987 | rather than calls to runtime libraries when a problem is detected. |
| 988 | This option is intended for use in cases where the sanitizer runtime |
| 989 | cannot be used (for instance, when building libc or a kernel module). |
| 990 | This is only compatible with the sanitizers in the ``undefined-trap`` |
| 991 | group. |
| 992 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 993 | The ``-fsanitize=`` argument must also be provided when linking, in |
Richard Smith | 635c1dc | 2013-07-19 19:06:48 +0000 | [diff] [blame] | 994 | order to link to the appropriate runtime library. When using |
| 995 | ``-fsanitize=vptr`` (or a group that includes it, such as |
| 996 | ``-fsanitize=undefined``) with a C++ program, the link must be |
| 997 | performed by ``clang++``, not ``clang``, in order to link against the |
| 998 | C++-specific parts of the runtime library. |
| 999 | |
| 1000 | It is not possible to combine more than one of the ``-fsanitize=address``, |
| 1001 | ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same |
| 1002 | program. The ``-fsanitize=undefined`` checks can be combined with other |
| 1003 | sanitizers. |
| 1004 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1005 | **-f[no-]address-sanitizer** |
| 1006 | Deprecated synonym for :ref:`-f[no-]sanitize=address |
| 1007 | <opt_fsanitize_address>`. |
| 1008 | **-f[no-]thread-sanitizer** |
| 1009 | Deprecated synonym for :ref:`-f[no-]sanitize=thread |
Richard Smith | 2dce7be | 2012-12-13 07:29:23 +0000 | [diff] [blame] | 1010 | <opt_fsanitize_thread>`. |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1011 | |
| 1012 | .. option:: -fcatch-undefined-behavior |
| 1013 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1014 | Deprecated synonym for :ref:`-fsanitize=undefined |
| 1015 | <opt_fsanitize_undefined>`. |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1016 | |
| 1017 | .. option:: -fno-assume-sane-operator-new |
| 1018 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1019 | Don't assume that the C++'s new operator is sane. |
| 1020 | |
| 1021 | This option tells the compiler to do not assume that C++'s global |
| 1022 | new operator will always return a pointer that does not alias any |
| 1023 | other pointer when the function returns. |
| 1024 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1025 | .. option:: -ftrap-function=[name] |
| 1026 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1027 | Instruct code generator to emit a function call to the specified |
| 1028 | function name for ``__builtin_trap()``. |
| 1029 | |
| 1030 | LLVM code generator translates ``__builtin_trap()`` to a trap |
| 1031 | instruction if it is supported by the target ISA. Otherwise, the |
| 1032 | builtin is translated into a call to ``abort``. If this option is |
| 1033 | set, then the code generator will always lower the builtin to a call |
| 1034 | to the specified function regardless of whether the target ISA has a |
| 1035 | trap instruction. This option is useful for environments (e.g. |
| 1036 | deeply embedded) where a trap cannot be properly handled, or when |
| 1037 | some custom behavior is desired. |
| 1038 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1039 | .. option:: -ftls-model=[model] |
| 1040 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1041 | Select which TLS model to use. |
| 1042 | |
| 1043 | Valid values are: ``global-dynamic``, ``local-dynamic``, |
| 1044 | ``initial-exec`` and ``local-exec``. The default value is |
| 1045 | ``global-dynamic``. The compiler may use a different model if the |
| 1046 | selected model is not supported by the target, or if a more |
| 1047 | efficient model can be used. The TLS model can be overridden per |
| 1048 | variable using the ``tls_model`` attribute. |
| 1049 | |
Silviu Baranga | 1db2e27 | 2013-10-21 10:54:53 +0000 | [diff] [blame] | 1050 | .. option:: -mhwdiv=[values] |
| 1051 | |
| 1052 | Select the ARM modes (arm or thumb) that support hardware division |
| 1053 | instructions. |
| 1054 | |
| 1055 | Valid values are: ``arm``, ``thumb`` and ``arm,thumb``. |
| 1056 | This option is used to indicate which mode (arm or thumb) supports |
| 1057 | hardware division instructions. This only applies to the ARM |
| 1058 | architecture. |
| 1059 | |
Bernard Ogden | 909f35a | 2013-10-29 09:47:51 +0000 | [diff] [blame] | 1060 | .. option:: -m[no-]crc |
| 1061 | |
| 1062 | Enable or disable CRC instructions. |
| 1063 | |
| 1064 | This option is used to indicate whether CRC instructions are to |
| 1065 | be generated. This only applies to the ARM architecture. |
| 1066 | |
| 1067 | CRC instructions are enabled by default on ARMv8. |
| 1068 | |
Silviu Baranga | 1db2e27 | 2013-10-21 10:54:53 +0000 | [diff] [blame] | 1069 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1070 | Controlling Size of Debug Information |
| 1071 | ------------------------------------- |
| 1072 | |
| 1073 | Debug info kind generated by Clang can be set by one of the flags listed |
| 1074 | below. If multiple flags are present, the last one is used. |
| 1075 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1076 | .. option:: -g0 |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1077 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1078 | Don't generate any debug info (default). |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1079 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1080 | .. option:: -gline-tables-only |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1081 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1082 | Generate line number tables only. |
| 1083 | |
| 1084 | This kind of debug info allows to obtain stack traces with function names, |
| 1085 | file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It |
| 1086 | doesn't contain any other data (e.g. description of local variables or |
| 1087 | function parameters). |
| 1088 | |
| 1089 | .. option:: -g |
| 1090 | |
| 1091 | Generate complete debug info. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1092 | |
Dmitri Gribenko | 6fd7d30 | 2013-04-10 15:35:17 +0000 | [diff] [blame] | 1093 | Comment Parsing Options |
| 1094 | -------------------------- |
| 1095 | |
| 1096 | Clang parses Doxygen and non-Doxygen style documentation comments and attaches |
| 1097 | them to the appropriate declaration nodes. By default, it only parses |
| 1098 | Doxygen-style comments and ignores ordinary comments starting with ``//`` and |
| 1099 | ``/*``. |
| 1100 | |
| 1101 | .. option:: -fparse-all-comments |
| 1102 | |
| 1103 | Parse all comments as documentation comments (including ordinary comments |
| 1104 | starting with ``//`` and ``/*``). |
| 1105 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1106 | .. _c: |
| 1107 | |
| 1108 | C Language Features |
| 1109 | =================== |
| 1110 | |
| 1111 | The support for standard C in clang is feature-complete except for the |
| 1112 | C99 floating-point pragmas. |
| 1113 | |
| 1114 | Extensions supported by clang |
| 1115 | ----------------------------- |
| 1116 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1117 | See :doc:`LanguageExtensions`. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1118 | |
| 1119 | Differences between various standard modes |
| 1120 | ------------------------------------------ |
| 1121 | |
| 1122 | clang supports the -std option, which changes what language mode clang |
| 1123 | uses. The supported modes for C are c89, gnu89, c94, c99, gnu99 and |
| 1124 | various aliases for those modes. If no -std option is specified, clang |
| 1125 | defaults to gnu99 mode. |
| 1126 | |
| 1127 | Differences between all ``c*`` and ``gnu*`` modes: |
| 1128 | |
| 1129 | - ``c*`` modes define "``__STRICT_ANSI__``". |
| 1130 | - Target-specific defines not prefixed by underscores, like "linux", |
| 1131 | are defined in ``gnu*`` modes. |
| 1132 | - Trigraphs default to being off in ``gnu*`` modes; they can be enabled by |
| 1133 | the -trigraphs option. |
| 1134 | - The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes; |
| 1135 | the variants "``__asm__``" and "``__typeof__``" are recognized in all |
| 1136 | modes. |
| 1137 | - The Apple "blocks" extension is recognized by default in ``gnu*`` modes |
| 1138 | on some platforms; it can be enabled in any mode with the "-fblocks" |
| 1139 | option. |
| 1140 | - Arrays that are VLA's according to the standard, but which can be |
| 1141 | constant folded by the frontend are treated as fixed size arrays. |
| 1142 | This occurs for things like "int X[(1, 2)];", which is technically a |
| 1143 | VLA. ``c*`` modes are strictly compliant and treat these as VLAs. |
| 1144 | |
| 1145 | Differences between ``*89`` and ``*99`` modes: |
| 1146 | |
| 1147 | - The ``*99`` modes default to implementing "inline" as specified in C99, |
| 1148 | while the ``*89`` modes implement the GNU version. This can be |
| 1149 | overridden for individual functions with the ``__gnu_inline__`` |
| 1150 | attribute. |
| 1151 | - Digraphs are not recognized in c89 mode. |
| 1152 | - The scope of names defined inside a "for", "if", "switch", "while", |
| 1153 | or "do" statement is different. (example: "``if ((struct x {int |
| 1154 | x;}*)0) {}``".) |
| 1155 | - ``__STDC_VERSION__`` is not defined in ``*89`` modes. |
| 1156 | - "inline" is not recognized as a keyword in c89 mode. |
| 1157 | - "restrict" is not recognized as a keyword in ``*89`` modes. |
| 1158 | - Commas are allowed in integer constant expressions in ``*99`` modes. |
| 1159 | - Arrays which are not lvalues are not implicitly promoted to pointers |
| 1160 | in ``*89`` modes. |
| 1161 | - Some warnings are different. |
| 1162 | |
| 1163 | c94 mode is identical to c89 mode except that digraphs are enabled in |
| 1164 | c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!). |
| 1165 | |
| 1166 | GCC extensions not implemented yet |
| 1167 | ---------------------------------- |
| 1168 | |
| 1169 | clang tries to be compatible with gcc as much as possible, but some gcc |
| 1170 | extensions are not implemented yet: |
| 1171 | |
| 1172 | - clang does not support #pragma weak (`bug |
| 1173 | 3679 <http://llvm.org/bugs/show_bug.cgi?id=3679>`_). Due to the uses |
| 1174 | described in the bug, this is likely to be implemented at some point, |
| 1175 | at least partially. |
| 1176 | - clang does not support decimal floating point types (``_Decimal32`` and |
| 1177 | friends) or fixed-point types (``_Fract`` and friends); nobody has |
| 1178 | expressed interest in these features yet, so it's hard to say when |
| 1179 | they will be implemented. |
| 1180 | - clang does not support nested functions; this is a complex feature |
| 1181 | which is infrequently used, so it is unlikely to be implemented |
| 1182 | anytime soon. In C++11 it can be emulated by assigning lambda |
| 1183 | functions to local variables, e.g: |
| 1184 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1185 | .. code-block:: cpp |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1186 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1187 | auto const local_function = [&](int parameter) { |
| 1188 | // Do something |
| 1189 | }; |
| 1190 | ... |
| 1191 | local_function(1); |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1192 | |
| 1193 | - clang does not support global register variables; this is unlikely to |
| 1194 | be implemented soon because it requires additional LLVM backend |
| 1195 | support. |
| 1196 | - clang does not support static initialization of flexible array |
| 1197 | members. This appears to be a rarely used extension, but could be |
| 1198 | implemented pending user demand. |
| 1199 | - clang does not support |
| 1200 | ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is |
| 1201 | used rarely, but in some potentially interesting places, like the |
| 1202 | glibc headers, so it may be implemented pending user demand. Note |
| 1203 | that because clang pretends to be like GCC 4.2, and this extension |
| 1204 | was introduced in 4.3, the glibc headers will not try to use this |
| 1205 | extension with clang at the moment. |
| 1206 | - clang does not support the gcc extension for forward-declaring |
| 1207 | function parameters; this has not shown up in any real-world code |
| 1208 | yet, though, so it might never be implemented. |
| 1209 | |
| 1210 | This is not a complete list; if you find an unsupported extension |
| 1211 | missing from this list, please send an e-mail to cfe-dev. This list |
| 1212 | currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this |
| 1213 | list does not include bugs in mostly-implemented features; please see |
| 1214 | the `bug |
| 1215 | tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_ |
| 1216 | for known existing bugs (FIXME: Is there a section for bug-reporting |
| 1217 | guidelines somewhere?). |
| 1218 | |
| 1219 | Intentionally unsupported GCC extensions |
| 1220 | ---------------------------------------- |
| 1221 | |
| 1222 | - clang does not support the gcc extension that allows variable-length |
| 1223 | arrays in structures. This is for a few reasons: one, it is tricky to |
| 1224 | implement, two, the extension is completely undocumented, and three, |
| 1225 | the extension appears to be rarely used. Note that clang *does* |
| 1226 | support flexible array members (arrays with a zero or unspecified |
| 1227 | size at the end of a structure). |
| 1228 | - clang does not have an equivalent to gcc's "fold"; this means that |
| 1229 | clang doesn't accept some constructs gcc might accept in contexts |
| 1230 | where a constant expression is required, like "x-x" where x is a |
| 1231 | variable. |
| 1232 | - clang does not support ``__builtin_apply`` and friends; this extension |
| 1233 | is extremely obscure and difficult to implement reliably. |
| 1234 | |
| 1235 | .. _c_ms: |
| 1236 | |
| 1237 | Microsoft extensions |
| 1238 | -------------------- |
| 1239 | |
| 1240 | clang has some experimental support for extensions from Microsoft Visual |
Bill Wendling | c27813a | 2013-12-12 04:30:51 +0000 | [diff] [blame^] | 1241 | C++; to enable it, use the ``-fms-extensions`` command-line option. This is |
Reid Kleckner | cc6fab9 | 2013-09-20 17:51:00 +0000 | [diff] [blame] | 1242 | the default for Windows targets. Note that the support is incomplete. |
Bill Wendling | c27813a | 2013-12-12 04:30:51 +0000 | [diff] [blame^] | 1243 | Some constructs such as ``dllexport`` on classes are ignored with a warning, |
Reid Kleckner | cc6fab9 | 2013-09-20 17:51:00 +0000 | [diff] [blame] | 1244 | and others such as `Microsoft IDL annotations |
Reid Kleckner | dec5f28 | 2013-09-20 17:54:39 +0000 | [diff] [blame] | 1245 | <http://msdn.microsoft.com/en-us/library/8tesw2eh.aspx>`_ are silently |
Reid Kleckner | cc6fab9 | 2013-09-20 17:51:00 +0000 | [diff] [blame] | 1246 | ignored. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1247 | |
Bill Wendling | c27813a | 2013-12-12 04:30:51 +0000 | [diff] [blame^] | 1248 | clang has a ``-fms-compatibility`` flag that makes clang accept enough |
Reid Kleckner | 09ab088 | 2013-09-20 17:04:25 +0000 | [diff] [blame] | 1249 | invalid C++ to be able to parse most Microsoft headers. For example, it |
| 1250 | allows `unqualified lookup of dependent base class members |
Reid Kleckner | dec5f28 | 2013-09-20 17:54:39 +0000 | [diff] [blame] | 1251 | <http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is |
| 1252 | a common compatibility issue with clang. This flag is enabled by default |
Reid Kleckner | 09ab088 | 2013-09-20 17:04:25 +0000 | [diff] [blame] | 1253 | for Windows targets. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1254 | |
Bill Wendling | c27813a | 2013-12-12 04:30:51 +0000 | [diff] [blame^] | 1255 | ``-fdelayed-template-parsing`` lets clang delay parsing of function template |
| 1256 | definitions until the end of a translation unit. This flag is enabled by |
| 1257 | default for Windows targets. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1258 | |
| 1259 | - clang allows setting ``_MSC_VER`` with ``-fmsc-version=``. It defaults to |
Reid Kleckner | 4cfebf2 | 2013-09-20 18:01:52 +0000 | [diff] [blame] | 1260 | 1700 which is the same as Visual C/C++ 2012. Any number is supported |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1261 | and can greatly affect what Windows SDK and c++stdlib headers clang |
Reid Kleckner | 4cfebf2 | 2013-09-20 18:01:52 +0000 | [diff] [blame] | 1262 | can compile. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1263 | - clang does not support the Microsoft extension where anonymous record |
| 1264 | members can be declared using user defined typedefs. |
Reid Kleckner | 4cfebf2 | 2013-09-20 18:01:52 +0000 | [diff] [blame] | 1265 | - clang supports the Microsoft ``#pragma pack`` feature for controlling |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1266 | record layout. GCC also contains support for this feature, however |
| 1267 | where MSVC and GCC are incompatible clang follows the MSVC |
| 1268 | definition. |
Reid Kleckner | a518896 | 2013-05-08 14:40:51 +0000 | [diff] [blame] | 1269 | - clang supports the Microsoft ``#pragma comment(lib, "foo.lib")`` feature for |
| 1270 | automatically linking against the specified library. Currently this feature |
| 1271 | only works with the Visual C++ linker. |
| 1272 | - clang supports the Microsoft ``#pragma comment(linker, "/flag:foo")`` feature |
| 1273 | for adding linker flags to COFF object files. The user is responsible for |
| 1274 | ensuring that the linker understands the flags. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1275 | - clang defaults to C++11 for Windows targets. |
| 1276 | |
| 1277 | .. _cxx: |
| 1278 | |
| 1279 | C++ Language Features |
| 1280 | ===================== |
| 1281 | |
| 1282 | clang fully implements all of standard C++98 except for exported |
Bill Wendling | c27813a | 2013-12-12 04:30:51 +0000 | [diff] [blame^] | 1283 | templates (which were removed in C++11), and all of standard C++11 |
| 1284 | and the current draft standard for C++1y. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1285 | |
| 1286 | Controlling implementation limits |
| 1287 | --------------------------------- |
| 1288 | |
Richard Smith | 9e738cc | 2013-02-22 01:59:51 +0000 | [diff] [blame] | 1289 | .. option:: -fbracket-depth=N |
| 1290 | |
| 1291 | Sets the limit for nested parentheses, brackets, and braces to N. The |
| 1292 | default is 256. |
| 1293 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1294 | .. option:: -fconstexpr-depth=N |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1295 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1296 | Sets the limit for recursive constexpr function invocations to N. The |
| 1297 | default is 512. |
| 1298 | |
| 1299 | .. option:: -ftemplate-depth=N |
| 1300 | |
| 1301 | Sets the limit for recursively nested template instantiations to N. The |
Richard Smith | 195dd7c | 2013-11-06 19:31:51 +0000 | [diff] [blame] | 1302 | default is 256. |
| 1303 | |
| 1304 | .. option:: -foperator-arrow-depth=N |
| 1305 | |
| 1306 | Sets the limit for iterative calls to 'operator->' functions to N. The |
| 1307 | default is 256. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1308 | |
| 1309 | .. _objc: |
| 1310 | |
| 1311 | Objective-C Language Features |
| 1312 | ============================= |
| 1313 | |
| 1314 | .. _objcxx: |
| 1315 | |
| 1316 | Objective-C++ Language Features |
| 1317 | =============================== |
| 1318 | |
| 1319 | |
| 1320 | .. _target_features: |
| 1321 | |
| 1322 | Target-Specific Features and Limitations |
| 1323 | ======================================== |
| 1324 | |
| 1325 | CPU Architectures Features and Limitations |
| 1326 | ------------------------------------------ |
| 1327 | |
| 1328 | X86 |
| 1329 | ^^^ |
| 1330 | |
| 1331 | The support for X86 (both 32-bit and 64-bit) is considered stable on |
| 1332 | Darwin (Mac OS/X), Linux, FreeBSD, and Dragonfly BSD: it has been tested |
| 1333 | to correctly compile many large C, C++, Objective-C, and Objective-C++ |
| 1334 | codebases. |
| 1335 | |
Bill Wendling | c27813a | 2013-12-12 04:30:51 +0000 | [diff] [blame^] | 1336 | On ``x86_64-mingw32``, passing i128(by value) is incompatible with the |
| 1337 | Microsoft x64 calling conversion. You might need to tweak |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1338 | ``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp. |
| 1339 | |
| 1340 | ARM |
| 1341 | ^^^ |
| 1342 | |
| 1343 | The support for ARM (specifically ARMv6 and ARMv7) is considered stable |
| 1344 | on Darwin (iOS): it has been tested to correctly compile many large C, |
| 1345 | C++, Objective-C, and Objective-C++ codebases. Clang only supports a |
| 1346 | limited number of ARM architectures. It does not yet fully support |
| 1347 | ARMv5, for example. |
| 1348 | |
Roman Divacky | cd7b0f0 | 2013-09-11 17:12:49 +0000 | [diff] [blame] | 1349 | PowerPC |
| 1350 | ^^^^^^^ |
| 1351 | |
| 1352 | The support for PowerPC (especially PowerPC64) is considered stable |
| 1353 | on Linux and FreeBSD: it has been tested to correctly compile many |
| 1354 | large C and C++ codebases. PowerPC (32bit) is still missing certain |
| 1355 | features (e.g. PIC code on ELF platforms). |
| 1356 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1357 | Other platforms |
| 1358 | ^^^^^^^^^^^^^^^ |
| 1359 | |
Roman Divacky | cd7b0f0 | 2013-09-11 17:12:49 +0000 | [diff] [blame] | 1360 | clang currently contains some support for other architectures (e.g. Sparc); |
| 1361 | however, significant pieces of code generation are still missing, and they |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1362 | haven't undergone significant testing. |
| 1363 | |
| 1364 | clang contains limited support for the MSP430 embedded processor, but |
| 1365 | both the clang support and the LLVM backend support are highly |
| 1366 | experimental. |
| 1367 | |
| 1368 | Other platforms are completely unsupported at the moment. Adding the |
| 1369 | minimal support needed for parsing and semantic analysis on a new |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1370 | platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1371 | tree. This level of support is also sufficient for conversion to LLVM IR |
| 1372 | for simple programs. Proper support for conversion to LLVM IR requires |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1373 | adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1374 | change soon, though. Generating assembly requires a suitable LLVM |
| 1375 | backend. |
| 1376 | |
| 1377 | Operating System Features and Limitations |
| 1378 | ----------------------------------------- |
| 1379 | |
| 1380 | Darwin (Mac OS/X) |
| 1381 | ^^^^^^^^^^^^^^^^^ |
| 1382 | |
| 1383 | None |
| 1384 | |
| 1385 | Windows |
| 1386 | ^^^^^^^ |
| 1387 | |
Bill Wendling | c27813a | 2013-12-12 04:30:51 +0000 | [diff] [blame^] | 1388 | Clang has experimental support for targeting "Cygming" (Cygwin / MinGW) |
| 1389 | platforms. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1390 | |
Reid Kleckner | af6f8cc | 2013-09-05 21:29:35 +0000 | [diff] [blame] | 1391 | See also :ref:`Microsoft Extensions <c_ms>`. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1392 | |
| 1393 | Cygwin |
| 1394 | """""" |
| 1395 | |
| 1396 | Clang works on Cygwin-1.7. |
| 1397 | |
| 1398 | MinGW32 |
| 1399 | """"""" |
| 1400 | |
| 1401 | Clang works on some mingw32 distributions. Clang assumes directories as |
| 1402 | below; |
| 1403 | |
| 1404 | - ``C:/mingw/include`` |
| 1405 | - ``C:/mingw/lib`` |
| 1406 | - ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++`` |
| 1407 | |
| 1408 | On MSYS, a few tests might fail. |
| 1409 | |
| 1410 | MinGW-w64 |
| 1411 | """"""""" |
| 1412 | |
| 1413 | For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang |
| 1414 | assumes as below; |
| 1415 | |
| 1416 | - ``GCC versions 4.5.0 to 4.5.3, 4.6.0 to 4.6.2, or 4.7.0 (for the C++ header search path)`` |
| 1417 | - ``some_directory/bin/gcc.exe`` |
| 1418 | - ``some_directory/bin/clang.exe`` |
| 1419 | - ``some_directory/bin/clang++.exe`` |
| 1420 | - ``some_directory/bin/../include/c++/GCC_version`` |
| 1421 | - ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32`` |
| 1422 | - ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32`` |
| 1423 | - ``some_directory/bin/../include/c++/GCC_version/backward`` |
| 1424 | - ``some_directory/bin/../x86_64-w64-mingw32/include`` |
| 1425 | - ``some_directory/bin/../i686-w64-mingw32/include`` |
| 1426 | - ``some_directory/bin/../include`` |
| 1427 | |
| 1428 | This directory layout is standard for any toolchain you will find on the |
| 1429 | official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_. |
| 1430 | |
| 1431 | Clang expects the GCC executable "gcc.exe" compiled for |
| 1432 | ``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH. |
| 1433 | |
| 1434 | `Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on |
| 1435 | ``x86_64-w64-mingw32``. |
Hans Wennborg | 0a6cf66 | 2013-10-10 01:15:16 +0000 | [diff] [blame] | 1436 | |
| 1437 | .. _clang-cl: |
| 1438 | |
| 1439 | clang-cl |
| 1440 | ======== |
| 1441 | |
| 1442 | clang-cl is an alternative command-line interface to Clang driver, designed for |
| 1443 | compatibility with the Visual C++ compiler, cl.exe. |
| 1444 | |
| 1445 | To enable clang-cl to find system headers, libraries, and the linker when run |
| 1446 | from the command-line, it should be executed inside a Visual Studio Native Tools |
| 1447 | Command Prompt or a regular Command Prompt where the environment has been set |
| 1448 | up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_. |
| 1449 | |
| 1450 | clang-cl can also be used from inside Visual Studio by using an LLVM Platform |
| 1451 | Toolset. |
| 1452 | |
| 1453 | Command-Line Options |
| 1454 | -------------------- |
| 1455 | |
| 1456 | To be compatible with cl.exe, clang-cl supports most of the same command-line |
| 1457 | options. Those options can start with either ``/`` or ``-``. It also supports |
| 1458 | some of Clang's core options, such as the ``-W`` options. |
| 1459 | |
| 1460 | Options that are known to clang-cl, but not currently supported, are ignored |
| 1461 | with a warning. For example: |
| 1462 | |
| 1463 | :: |
| 1464 | |
| 1465 | clang-cl.exe: warning: argument unused during compilation: '/Zi' |
| 1466 | |
| 1467 | To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option. |
| 1468 | |
| 1469 | Options that are not known to clang-cl will cause errors. If they are spelled with a |
| 1470 | leading ``/``, they will be mistaken for a filename: |
| 1471 | |
| 1472 | :: |
| 1473 | |
| 1474 | clang-cl.exe: error: no such file or directory: '/foobar' |
| 1475 | |
| 1476 | Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_ |
| 1477 | for any valid cl.exe flags that clang-cl does not understand. |
| 1478 | |
| 1479 | Execute ``clang-cl /?`` to see a list of supported options: |
| 1480 | |
| 1481 | :: |
| 1482 | |
| 1483 | /? Display available options |
| 1484 | /c Compile only |
| 1485 | /D <macro[=value]> Define macro |
| 1486 | /fallback Fall back to cl.exe if clang-cl fails to compile |
Hans Wennborg | 82a2911 | 2013-10-17 16:16:23 +0000 | [diff] [blame] | 1487 | /FA Output assembly code file during compilation |
| 1488 | /Fa<file or directory> Output assembly code to this file during compilation |
Hans Wennborg | 0a6cf66 | 2013-10-10 01:15:16 +0000 | [diff] [blame] | 1489 | /Fe<file or directory> Set output executable file or directory (ends in / or \) |
| 1490 | /FI<value> Include file before parsing |
| 1491 | /Fo<file or directory> Set output object file, or directory (ends in / or \) |
| 1492 | /GF- Disable string pooling |
| 1493 | /GR- Disable RTTI |
| 1494 | /GR Enable RTTI |
| 1495 | /help Display available options |
| 1496 | /I <dir> Add directory to include search path |
| 1497 | /J Make char type unsigned |
| 1498 | /LDd Create debug DLL |
| 1499 | /LD Create DLL |
| 1500 | /link <options> Forward options to the linker |
| 1501 | /MDd Use DLL debug run-time |
| 1502 | /MD Use DLL run-time |
| 1503 | /MTd Use static debug run-time |
| 1504 | /MT Use static run-time |
| 1505 | /Ob0 Disable inlining |
| 1506 | /Od Disable optimization |
| 1507 | /Oi- Disable use of builtin functions |
| 1508 | /Oi Enable use of builtin functions |
| 1509 | /Os Optimize for size |
| 1510 | /Ot Optimize for speed |
| 1511 | /Ox Maximum optimization |
| 1512 | /Oy- Disable frame pointer omission |
| 1513 | /Oy Enable frame pointer omission |
| 1514 | /O<n> Optimization level |
| 1515 | /P Only run the preprocessor |
| 1516 | /showIncludes Print info about included files to stderr |
| 1517 | /TC Treat all source files as C |
| 1518 | /Tc <filename> Specify a C source file |
| 1519 | /TP Treat all source files as C++ |
| 1520 | /Tp <filename> Specify a C++ source file |
| 1521 | /U <macro> Undefine macro |
| 1522 | /W0 Disable all warnings |
| 1523 | /W1 Enable -Wall |
| 1524 | /W2 Enable -Wall |
| 1525 | /W3 Enable -Wall |
| 1526 | /W4 Enable -Wall |
| 1527 | /Wall Enable -Wall |
| 1528 | /WX- Do not treat warnings as errors |
| 1529 | /WX Treat warnings as errors |
| 1530 | /w Disable all warnings |
| 1531 | /Zs Syntax-check only |
| 1532 | |
| 1533 | The /fallback Option |
| 1534 | ^^^^^^^^^^^^^^^^^^^^ |
| 1535 | |
| 1536 | When clang-cl is run with the ``/fallback`` option, it will first try to |
| 1537 | compile files itself. For any file that it fails to compile, it will fall back |
| 1538 | and try to compile the file by invoking cl.exe. |
| 1539 | |
| 1540 | This option is intended to be used as a temporary means to build projects where |
| 1541 | clang-cl cannot successfully compile all the files. clang-cl may fail to compile |
| 1542 | a file either because it cannot generate code for some C++ feature, or because |
| 1543 | it cannot parse some Microsoft language extension. |