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 |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 76 | picking a language to use, defaults to C11 by default. Autosenses based |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 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 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 115 | Disable all diagnostics. |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 116 | |
| 117 | .. option:: -Weverything |
| 118 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 119 | :ref:`Enable all diagnostics. <diagnostics_enable_everything>` |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 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 |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 136 | 20, and the error limit can be disabled with `-ferror-limit=0`. |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 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 |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 142 | the limit can be disabled with `-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 |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 151 | different preferences, and sometimes Clang is driven not by a human, |
| 152 | but by a program that wants consistent and easily parsable output. For |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 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 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 268 | .. _opt_fdiagnostics-show-option: |
| 269 | |
| 270 | **-f[no-]diagnostics-show-option** |
| 271 | Enable ``[-Woption]`` information in diagnostic line. |
| 272 | |
| 273 | This option, which defaults to on, controls whether or not Clang |
| 274 | prints the associated :ref:`warning group <cl_diag_warning_groups>` |
| 275 | option name when outputting a warning diagnostic. For example, in |
| 276 | this output: |
| 277 | |
| 278 | :: |
| 279 | |
| 280 | test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] |
| 281 | #endif bad |
| 282 | ^ |
| 283 | // |
| 284 | |
| 285 | Passing **-fno-diagnostics-show-option** will prevent Clang from |
| 286 | printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in |
| 287 | the diagnostic. This information tells you the flag needed to enable |
| 288 | or disable the diagnostic, either from the command line or through |
| 289 | :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`. |
| 290 | |
| 291 | .. _opt_fdiagnostics-show-category: |
| 292 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 293 | .. option:: -fdiagnostics-show-category=none/id/name |
| 294 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 295 | Enable printing category information in diagnostic line. |
| 296 | |
| 297 | This option, which defaults to "none", controls whether or not Clang |
| 298 | prints the category associated with a diagnostic when emitting it. |
| 299 | Each diagnostic may or many not have an associated category, if it |
| 300 | has one, it is listed in the diagnostic categorization field of the |
| 301 | diagnostic line (in the []'s). |
| 302 | |
| 303 | For example, a format string warning will produce these three |
| 304 | renditions based on the setting of this option: |
| 305 | |
| 306 | :: |
| 307 | |
| 308 | t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat] |
| 309 | t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1] |
| 310 | t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String] |
| 311 | |
| 312 | This category can be used by clients that want to group diagnostics |
| 313 | by category, so it should be a high level category. We want dozens |
| 314 | of these, not hundreds or thousands of them. |
| 315 | |
| 316 | .. _opt_fdiagnostics-fixit-info: |
| 317 | |
| 318 | **-f[no-]diagnostics-fixit-info** |
| 319 | Enable "FixIt" information in the diagnostics output. |
| 320 | |
| 321 | This option, which defaults to on, controls whether or not Clang |
| 322 | prints the information on how to fix a specific diagnostic |
| 323 | underneath it when it knows. For example, in this output: |
| 324 | |
| 325 | :: |
| 326 | |
| 327 | test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] |
| 328 | #endif bad |
| 329 | ^ |
| 330 | // |
| 331 | |
| 332 | Passing **-fno-diagnostics-fixit-info** will prevent Clang from |
| 333 | printing the "//" line at the end of the message. This information |
| 334 | is useful for users who may not understand what is wrong, but can be |
| 335 | confusing for machine parsing. |
| 336 | |
| 337 | .. _opt_fdiagnostics-print-source-range-info: |
| 338 | |
Nico Weber | 727d0d0 | 2013-01-09 05:06:41 +0000 | [diff] [blame] | 339 | **-fdiagnostics-print-source-range-info** |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 340 | Print machine parsable information about source ranges. |
Nico Weber | 727d0d0 | 2013-01-09 05:06:41 +0000 | [diff] [blame] | 341 | This option makes Clang print information about source ranges in a machine |
| 342 | parsable format after the file/line/column number information. The |
| 343 | information is a simple sequence of brace enclosed ranges, where each range |
| 344 | 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] | 345 | |
| 346 | :: |
| 347 | |
| 348 | exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float') |
| 349 | P = (P-42) + Gamma*4; |
| 350 | ~~~~~~ ^ ~~~~~~~ |
| 351 | |
| 352 | The {}'s are generated by -fdiagnostics-print-source-range-info. |
| 353 | |
| 354 | The printed column numbers count bytes from the beginning of the |
| 355 | line; take care if your source contains multibyte characters. |
| 356 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 357 | .. option:: -fdiagnostics-parseable-fixits |
| 358 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 359 | Print Fix-Its in a machine parseable form. |
| 360 | |
| 361 | This option makes Clang print available Fix-Its in a machine |
| 362 | parseable format at the end of diagnostics. The following example |
| 363 | illustrates the format: |
| 364 | |
| 365 | :: |
| 366 | |
| 367 | fix-it:"t.cpp":{7:25-7:29}:"Gamma" |
| 368 | |
| 369 | The range printed is a half-open range, so in this example the |
| 370 | characters at column 25 up to but not including column 29 on line 7 |
| 371 | in t.cpp should be replaced with the string "Gamma". Either the |
| 372 | range or the replacement string may be empty (representing strict |
| 373 | insertions and strict erasures, respectively). Both the file name |
| 374 | and the insertion string escape backslash (as "\\\\"), tabs (as |
| 375 | "\\t"), newlines (as "\\n"), double quotes(as "\\"") and |
| 376 | non-printable characters (as octal "\\xxx"). |
| 377 | |
| 378 | The printed column numbers count bytes from the beginning of the |
| 379 | line; take care if your source contains multibyte characters. |
| 380 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 381 | .. option:: -fno-elide-type |
| 382 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 383 | Turns off elision in template type printing. |
| 384 | |
| 385 | The default for template type printing is to elide as many template |
| 386 | arguments as possible, removing those which are the same in both |
| 387 | template types, leaving only the differences. Adding this flag will |
| 388 | print all the template arguments. If supported by the terminal, |
| 389 | highlighting will still appear on differing arguments. |
| 390 | |
| 391 | Default: |
| 392 | |
| 393 | :: |
| 394 | |
| 395 | 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; |
| 396 | |
| 397 | -fno-elide-type: |
| 398 | |
| 399 | :: |
| 400 | |
| 401 | 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; |
| 402 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 403 | .. option:: -fdiagnostics-show-template-tree |
| 404 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 405 | Template type diffing prints a text tree. |
| 406 | |
| 407 | For diffing large templated types, this option will cause Clang to |
| 408 | display the templates as an indented text tree, one argument per |
| 409 | line, with differences marked inline. This is compatible with |
| 410 | -fno-elide-type. |
| 411 | |
| 412 | Default: |
| 413 | |
| 414 | :: |
| 415 | |
| 416 | 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; |
| 417 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 418 | With :option:`-fdiagnostics-show-template-tree`: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 419 | |
| 420 | :: |
| 421 | |
| 422 | t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument; |
| 423 | vector< |
| 424 | map< |
| 425 | [...], |
| 426 | map< |
Richard Trieu | 1ab7778 | 2013-08-09 22:52:48 +0000 | [diff] [blame] | 427 | [float != double], |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 428 | [...]>>> |
| 429 | |
| 430 | .. _cl_diag_warning_groups: |
| 431 | |
| 432 | Individual Warning Groups |
| 433 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 434 | |
| 435 | TODO: Generate this from tblgen. Define one anchor per warning group. |
| 436 | |
| 437 | .. _opt_wextra-tokens: |
| 438 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 439 | .. option:: -Wextra-tokens |
| 440 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 441 | Warn about excess tokens at the end of a preprocessor directive. |
| 442 | |
| 443 | This option, which defaults to on, enables warnings about extra |
| 444 | tokens at the end of preprocessor directives. For example: |
| 445 | |
| 446 | :: |
| 447 | |
| 448 | test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] |
| 449 | #endif bad |
| 450 | ^ |
| 451 | |
| 452 | These extra tokens are not strictly conforming, and are usually best |
| 453 | handled by commenting them out. |
| 454 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 455 | .. option:: -Wambiguous-member-template |
| 456 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 457 | Warn about unqualified uses of a member template whose name resolves to |
| 458 | another template at the location of the use. |
| 459 | |
| 460 | This option, which defaults to on, enables a warning in the |
| 461 | following code: |
| 462 | |
| 463 | :: |
| 464 | |
| 465 | template<typename T> struct set{}; |
| 466 | template<typename T> struct trait { typedef const T& type; }; |
| 467 | struct Value { |
| 468 | template<typename T> void set(typename trait<T>::type value) {} |
| 469 | }; |
| 470 | void foo() { |
| 471 | Value v; |
| 472 | v.set<double>(3.2); |
| 473 | } |
| 474 | |
| 475 | C++ [basic.lookup.classref] requires this to be an error, but, |
| 476 | because it's hard to work around, Clang downgrades it to a warning |
| 477 | as an extension. |
| 478 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 479 | .. option:: -Wbind-to-temporary-copy |
| 480 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 481 | Warn about an unusable copy constructor when binding a reference to a |
| 482 | temporary. |
| 483 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 484 | This option enables warnings about binding a |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 485 | reference to a temporary when the temporary doesn't have a usable |
| 486 | copy constructor. For example: |
| 487 | |
| 488 | :: |
| 489 | |
| 490 | struct NonCopyable { |
| 491 | NonCopyable(); |
| 492 | private: |
| 493 | NonCopyable(const NonCopyable&); |
| 494 | }; |
| 495 | void foo(const NonCopyable&); |
| 496 | void bar() { |
| 497 | foo(NonCopyable()); // Disallowed in C++98; allowed in C++11. |
| 498 | } |
| 499 | |
| 500 | :: |
| 501 | |
| 502 | struct NonCopyable2 { |
| 503 | NonCopyable2(); |
| 504 | NonCopyable2(NonCopyable2&); |
| 505 | }; |
| 506 | void foo(const NonCopyable2&); |
| 507 | void bar() { |
| 508 | foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11. |
| 509 | } |
| 510 | |
| 511 | Note that if ``NonCopyable2::NonCopyable2()`` has a default argument |
| 512 | whose instantiation produces a compile error, that error will still |
| 513 | be a hard error in C++98 mode even if this warning is turned off. |
| 514 | |
| 515 | Options to Control Clang Crash Diagnostics |
| 516 | ------------------------------------------ |
| 517 | |
| 518 | As unbelievable as it may sound, Clang does crash from time to time. |
| 519 | Generally, this only occurs to those living on the `bleeding |
| 520 | edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great |
| 521 | lengths to assist you in filing a bug report. Specifically, Clang |
| 522 | generates preprocessed source file(s) and associated run script(s) upon |
| 523 | a crash. These files should be attached to a bug report to ease |
| 524 | reproducibility of the failure. Below are the command line options to |
| 525 | control the crash diagnostics. |
| 526 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 527 | .. option:: -fno-crash-diagnostics |
| 528 | |
| 529 | Disable auto-generation of preprocessed source files during a clang crash. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 530 | |
| 531 | The -fno-crash-diagnostics flag can be helpful for speeding the process |
| 532 | of generating a delta reduced test case. |
| 533 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 534 | Options to Emit Optimization Reports |
| 535 | ------------------------------------ |
| 536 | |
| 537 | Optimization reports trace, at a high-level, all the major decisions |
| 538 | done by compiler transformations. For instance, when the inliner |
| 539 | decides to inline function ``foo()`` into ``bar()``, or the loop unroller |
| 540 | decides to unroll a loop N times, or the vectorizer decides to |
| 541 | vectorize a loop body. |
| 542 | |
| 543 | Clang offers a family of flags which the optimizers can use to emit |
| 544 | a diagnostic in three cases: |
| 545 | |
| 546 | 1. When the pass makes a transformation (:option:`-Rpass`). |
| 547 | |
| 548 | 2. When the pass fails to make a transformation (:option:`-Rpass-missed`). |
| 549 | |
| 550 | 3. When the pass determines whether or not to make a transformation |
| 551 | (:option:`-Rpass-analysis`). |
| 552 | |
| 553 | NOTE: Although the discussion below focuses on :option:`-Rpass`, the exact |
| 554 | same options apply to :option:`-Rpass-missed` and :option:`-Rpass-analysis`. |
| 555 | |
| 556 | Since there are dozens of passes inside the compiler, each of these flags |
| 557 | take a regular expression that identifies the name of the pass which should |
| 558 | emit the associated diagnostic. For example, to get a report from the inliner, |
| 559 | compile the code with: |
| 560 | |
| 561 | .. code-block:: console |
| 562 | |
| 563 | $ clang -O2 -Rpass=inline code.cc -o code |
| 564 | code.cc:4:25: remark: foo inlined into bar [-Rpass=inline] |
| 565 | int bar(int j) { return foo(j, j - 2); } |
| 566 | ^ |
| 567 | |
| 568 | Note that remarks from the inliner are identified with `[-Rpass=inline]`. |
| 569 | To request a report from every optimization pass, you should use |
| 570 | :option:`-Rpass=.*` (in fact, you can use any valid POSIX regular |
| 571 | expression). However, do not expect a report from every transformation |
| 572 | made by the compiler. Optimization remarks do not really make sense |
| 573 | outside of the major transformations (e.g., inlining, vectorization, |
| 574 | loop optimizations) and not every optimization pass supports this |
| 575 | feature. |
| 576 | |
| 577 | Current limitations |
| 578 | ^^^^^^^^^^^^^^^^^^^ |
| 579 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 580 | 1. Optimization remarks that refer to function names will display the |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 581 | mangled name of the function. Since these remarks are emitted by the |
| 582 | back end of the compiler, it does not know anything about the input |
| 583 | language, nor its mangling rules. |
| 584 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 585 | 2. Some source locations are not displayed correctly. The front end has |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 586 | a more detailed source location tracking than the locations included |
| 587 | in the debug info (e.g., the front end can locate code inside macro |
| 588 | expansions). However, the locations used by :option:`-Rpass` are |
| 589 | translated from debug annotations. That translation can be lossy, |
| 590 | which results in some remarks having no location information. |
| 591 | |
Pirama Arumuga Nainar | b6d6993 | 2015-07-01 12:25:36 -0700 | [diff] [blame] | 592 | Other Options |
| 593 | ------------- |
| 594 | Clang options that that don't fit neatly into other categories. |
| 595 | |
| 596 | .. option:: -MV |
| 597 | |
| 598 | When emitting a dependency file, use formatting conventions appropriate |
| 599 | for NMake or Jom. Ignored unless another option causes Clang to emit a |
| 600 | dependency file. |
| 601 | |
| 602 | When Clang emits a dependency file (e.g., you supplied the -M option) |
| 603 | most filenames can be written to the file without any special formatting. |
| 604 | Different Make tools will treat different sets of characters as "special" |
| 605 | and use different conventions for telling the Make tool that the character |
| 606 | is actually part of the filename. Normally Clang uses backslash to "escape" |
| 607 | a special character, which is the convention used by GNU Make. The -MV |
| 608 | option tells Clang to put double-quotes around the entire filename, which |
| 609 | is the convention used by NMake and Jom. |
| 610 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 611 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 612 | Language and Target-Independent Features |
| 613 | ======================================== |
| 614 | |
| 615 | Controlling Errors and Warnings |
| 616 | ------------------------------- |
| 617 | |
| 618 | Clang provides a number of ways to control which code constructs cause |
| 619 | it to emit errors and warning messages, and how they are displayed to |
| 620 | the console. |
| 621 | |
| 622 | Controlling How Clang Displays Diagnostics |
| 623 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 624 | |
| 625 | When Clang emits a diagnostic, it includes rich information in the |
| 626 | output, and gives you fine-grain control over which information is |
| 627 | printed. Clang has the ability to print this information, and these are |
| 628 | the options that control it: |
| 629 | |
| 630 | #. A file/line/column indicator that shows exactly where the diagnostic |
| 631 | occurs in your code [:ref:`-fshow-column <opt_fshow-column>`, |
| 632 | :ref:`-fshow-source-location <opt_fshow-source-location>`]. |
| 633 | #. A categorization of the diagnostic as a note, warning, error, or |
| 634 | fatal error. |
| 635 | #. A text string that describes what the problem is. |
| 636 | #. An option that indicates how to control the diagnostic (for |
| 637 | diagnostics that support it) |
| 638 | [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`]. |
| 639 | #. A :ref:`high-level category <diagnostics_categories>` for the diagnostic |
| 640 | for clients that want to group diagnostics by class (for diagnostics |
| 641 | that support it) |
| 642 | [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`]. |
| 643 | #. The line of source code that the issue occurs on, along with a caret |
| 644 | and ranges that indicate the important locations |
| 645 | [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`]. |
| 646 | #. "FixIt" information, which is a concise explanation of how to fix the |
| 647 | problem (when Clang is certain it knows) |
| 648 | [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`]. |
| 649 | #. A machine-parsable representation of the ranges involved (off by |
| 650 | default) |
| 651 | [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`]. |
| 652 | |
| 653 | For more information please see :ref:`Formatting of |
| 654 | Diagnostics <cl_diag_formatting>`. |
| 655 | |
| 656 | Diagnostic Mappings |
| 657 | ^^^^^^^^^^^^^^^^^^^ |
| 658 | |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 659 | All diagnostics are mapped into one of these 6 classes: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 660 | |
| 661 | - Ignored |
| 662 | - Note |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 663 | - Remark |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 664 | - Warning |
| 665 | - Error |
| 666 | - Fatal |
| 667 | |
| 668 | .. _diagnostics_categories: |
| 669 | |
| 670 | Diagnostic Categories |
| 671 | ^^^^^^^^^^^^^^^^^^^^^ |
| 672 | |
| 673 | Though not shown by default, diagnostics may each be associated with a |
| 674 | high-level category. This category is intended to make it possible to |
| 675 | triage builds that produce a large number of errors or warnings in a |
| 676 | grouped way. |
| 677 | |
| 678 | Categories are not shown by default, but they can be turned on with the |
| 679 | :ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option. |
| 680 | When set to "``name``", the category is printed textually in the |
| 681 | diagnostic output. When it is set to "``id``", a category number is |
| 682 | printed. The mapping of category names to category id's can be obtained |
| 683 | by running '``clang --print-diagnostic-categories``'. |
| 684 | |
| 685 | Controlling Diagnostics via Command Line Flags |
| 686 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 687 | |
| 688 | TODO: -W flags, -pedantic, etc |
| 689 | |
| 690 | .. _pragma_gcc_diagnostic: |
| 691 | |
| 692 | Controlling Diagnostics via Pragmas |
| 693 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 694 | |
| 695 | Clang can also control what diagnostics are enabled through the use of |
| 696 | pragmas in the source code. This is useful for turning off specific |
| 697 | warnings in a section of source code. Clang supports GCC's pragma for |
| 698 | compatibility with existing source code, as well as several extensions. |
| 699 | |
| 700 | The pragma may control any warning that can be used from the command |
| 701 | line. Warnings may be set to ignored, warning, error, or fatal. The |
| 702 | following example code will tell Clang or GCC to ignore the -Wall |
| 703 | warnings: |
| 704 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 705 | .. code-block:: c |
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 | #pragma GCC diagnostic ignored "-Wall" |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 708 | |
| 709 | In addition to all of the functionality provided by GCC's pragma, Clang |
| 710 | also allows you to push and pop the current warning state. This is |
| 711 | particularly useful when writing a header file that will be compiled by |
| 712 | other people, because you don't know what warning flags they build with. |
| 713 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 714 | In the below example :option:`-Wextra-tokens` is ignored for only a single line |
| 715 | of code, after which the diagnostics return to whatever state had previously |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 716 | existed. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 717 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 718 | .. code-block:: c |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 719 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 720 | #if foo |
| 721 | #endif foo // warning: extra tokens at end of #endif directive |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 722 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 723 | #pragma clang diagnostic ignored "-Wextra-tokens" |
| 724 | |
| 725 | #if foo |
| 726 | #endif foo // no warning |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 727 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 728 | #pragma clang diagnostic pop |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 729 | |
| 730 | The push and pop pragmas will save and restore the full diagnostic state |
| 731 | of the compiler, regardless of how it was set. That means that it is |
| 732 | possible to use push and pop around GCC compatible diagnostics and Clang |
| 733 | will push and pop them appropriately, while GCC will ignore the pushes |
| 734 | and pops as unknown pragmas. It should be noted that while Clang |
| 735 | supports the GCC pragma, Clang and GCC do not support the exact same set |
| 736 | of warnings, so even when using GCC compatible #pragmas there is no |
| 737 | guarantee that they will have identical behaviour on both compilers. |
| 738 | |
Andy Gibbs | 076eea2 | 2013-04-17 16:16:16 +0000 | [diff] [blame] | 739 | In addition to controlling warnings and errors generated by the compiler, it is |
| 740 | possible to generate custom warning and error messages through the following |
| 741 | pragmas: |
| 742 | |
| 743 | .. code-block:: c |
| 744 | |
| 745 | // The following will produce warning messages |
| 746 | #pragma message "some diagnostic message" |
| 747 | #pragma GCC warning "TODO: replace deprecated feature" |
| 748 | |
| 749 | // The following will produce an error message |
| 750 | #pragma GCC error "Not supported" |
| 751 | |
| 752 | These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor |
| 753 | directives, except that they may also be embedded into preprocessor macros via |
| 754 | the C99 ``_Pragma`` operator, for example: |
| 755 | |
| 756 | .. code-block:: c |
| 757 | |
| 758 | #define STR(X) #X |
| 759 | #define DEFER(M,...) M(__VA_ARGS__) |
| 760 | #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__)))) |
| 761 | |
| 762 | CUSTOM_ERROR("Feature not available"); |
| 763 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 764 | Controlling Diagnostics in System Headers |
| 765 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 766 | |
| 767 | Warnings are suppressed when they occur in system headers. By default, |
| 768 | an included file is treated as a system header if it is found in an |
| 769 | include path specified by ``-isystem``, but this can be overridden in |
| 770 | several ways. |
| 771 | |
| 772 | The ``system_header`` pragma can be used to mark the current file as |
| 773 | being a system header. No warnings will be produced from the location of |
| 774 | the pragma onwards within the same file. |
| 775 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 776 | .. code-block:: c |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 777 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 778 | #if foo |
| 779 | #endif foo // warning: extra tokens at end of #endif directive |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 780 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 781 | #pragma clang system_header |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 782 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 783 | #if foo |
| 784 | #endif foo // no warning |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 785 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 786 | The :option:`--system-header-prefix=` and :option:`--no-system-header-prefix=` |
| 787 | command-line arguments can be used to override whether subsets of an include |
| 788 | path are treated as system headers. When the name in a ``#include`` directive |
| 789 | is found within a header search path and starts with a system prefix, the |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 790 | header is treated as a system header. The last prefix on the |
| 791 | command-line which matches the specified header name takes precedence. |
| 792 | For instance: |
| 793 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 794 | .. code-block:: console |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 795 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 796 | $ clang -Ifoo -isystem bar --system-header-prefix=x/ \ |
| 797 | --no-system-header-prefix=x/y/ |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 798 | |
| 799 | Here, ``#include "x/a.h"`` is treated as including a system header, even |
| 800 | if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated |
| 801 | as not including a system header, even if the header is found in |
| 802 | ``bar``. |
| 803 | |
| 804 | A ``#include`` directive which finds a file relative to the current |
| 805 | directory is treated as including a system header if the including file |
| 806 | is treated as a system header. |
| 807 | |
| 808 | .. _diagnostics_enable_everything: |
| 809 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 810 | Enabling All Diagnostics |
| 811 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 812 | |
| 813 | In addition to the traditional ``-W`` flags, one can enable **all** |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 814 | diagnostics by passing :option:`-Weverything`. This works as expected |
| 815 | with |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 816 | :option:`-Werror`, and also includes the warnings from :option:`-pedantic`. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 817 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 818 | Note that when combined with :option:`-w` (which disables all warnings), that |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 819 | flag wins. |
| 820 | |
| 821 | Controlling Static Analyzer Diagnostics |
| 822 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 823 | |
| 824 | While not strictly part of the compiler, the diagnostics from Clang's |
| 825 | `static analyzer <http://clang-analyzer.llvm.org>`_ can also be |
| 826 | influenced by the user via changes to the source code. See the available |
| 827 | `annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the |
| 828 | analyzer's `FAQ |
| 829 | page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more |
| 830 | information. |
| 831 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 832 | .. _usersmanual-precompiled-headers: |
| 833 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 834 | Precompiled Headers |
| 835 | ------------------- |
| 836 | |
| 837 | `Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__ |
| 838 | are a general approach employed by many compilers to reduce compilation |
| 839 | time. The underlying motivation of the approach is that it is common for |
| 840 | the same (and often large) header files to be included by multiple |
| 841 | source files. Consequently, compile times can often be greatly improved |
| 842 | by caching some of the (redundant) work done by a compiler to process |
| 843 | headers. Precompiled header files, which represent one of many ways to |
| 844 | implement this optimization, are literally files that represent an |
| 845 | on-disk cache that contains the vital information necessary to reduce |
| 846 | some of the work needed to process a corresponding header file. While |
| 847 | details of precompiled headers vary between compilers, precompiled |
| 848 | headers have been shown to be highly effective at speeding up program |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 849 | compilation on systems with very large system headers (e.g., Mac OS X). |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 850 | |
| 851 | Generating a PCH File |
| 852 | ^^^^^^^^^^^^^^^^^^^^^ |
| 853 | |
| 854 | To generate a PCH file using Clang, one invokes Clang with the |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 855 | :option:`-x <language>-header` option. This mirrors the interface in GCC |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 856 | for generating PCH files: |
| 857 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 858 | .. code-block:: console |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 859 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 860 | $ gcc -x c-header test.h -o test.h.gch |
| 861 | $ clang -x c-header test.h -o test.h.pch |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 862 | |
| 863 | Using a PCH File |
| 864 | ^^^^^^^^^^^^^^^^ |
| 865 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 866 | 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] | 867 | option is passed to ``clang``: |
| 868 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 869 | .. code-block:: console |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 870 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 871 | $ clang -include test.h test.c -o test |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 872 | |
| 873 | The ``clang`` driver will first check if a PCH file for ``test.h`` is |
| 874 | available; if so, the contents of ``test.h`` (and the files it includes) |
| 875 | will be processed from the PCH file. Otherwise, Clang falls back to |
| 876 | directly processing the content of ``test.h``. This mirrors the behavior |
| 877 | of GCC. |
| 878 | |
| 879 | .. note:: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 880 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 881 | Clang does *not* automatically use PCH files for headers that are directly |
| 882 | included within a source file. For example: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 883 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 884 | .. code-block:: console |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 885 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 886 | $ clang -x c-header test.h -o test.h.pch |
| 887 | $ cat test.c |
| 888 | #include "test.h" |
| 889 | $ clang test.c -o test |
| 890 | |
| 891 | In this example, ``clang`` will not automatically use the PCH file for |
| 892 | ``test.h`` since ``test.h`` was included directly in the source file and not |
| 893 | specified on the command line using :option:`-include`. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 894 | |
| 895 | Relocatable PCH Files |
| 896 | ^^^^^^^^^^^^^^^^^^^^^ |
| 897 | |
| 898 | It is sometimes necessary to build a precompiled header from headers |
| 899 | that are not yet in their final, installed locations. For example, one |
| 900 | might build a precompiled header within the build tree that is then |
| 901 | meant to be installed alongside the headers. Clang permits the creation |
| 902 | of "relocatable" precompiled headers, which are built with a given path |
| 903 | (into the build directory) and can later be used from an installed |
| 904 | location. |
| 905 | |
| 906 | To build a relocatable precompiled header, place your headers into a |
| 907 | subdirectory whose structure mimics the installed location. For example, |
| 908 | if you want to build a precompiled header for the header ``mylib.h`` |
| 909 | that will be installed into ``/usr/include``, create a subdirectory |
| 910 | ``build/usr/include`` and place the header ``mylib.h`` into that |
| 911 | subdirectory. If ``mylib.h`` depends on other headers, then they can be |
| 912 | stored within ``build/usr/include`` in a way that mimics the installed |
| 913 | location. |
| 914 | |
| 915 | Building a relocatable precompiled header requires two additional |
| 916 | arguments. First, pass the ``--relocatable-pch`` flag to indicate that |
| 917 | the resulting PCH file should be relocatable. Second, pass |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 918 | :option:`-isysroot /path/to/build`, which makes all includes for your library |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 919 | relative to the build directory. For example: |
| 920 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 921 | .. code-block:: console |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 922 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 923 | # 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] | 924 | |
| 925 | When loading the relocatable PCH file, the various headers used in the |
| 926 | PCH file are found from the system header root. For example, ``mylib.h`` |
| 927 | 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] | 928 | 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] | 929 | a different system root from which the headers will be based. For |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 930 | example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 931 | ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``. |
| 932 | |
| 933 | Relocatable precompiled headers are intended to be used in a limited |
| 934 | number of cases where the compilation environment is tightly controlled |
| 935 | and the precompiled header cannot be generated after headers have been |
Argyrios Kyrtzidis | 8c42a67 | 2013-02-14 00:12:44 +0000 | [diff] [blame] | 936 | installed. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 937 | |
Pirama Arumuga Nainar | b6d6993 | 2015-07-01 12:25:36 -0700 | [diff] [blame] | 938 | .. _controlling-code-generation: |
| 939 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 940 | Controlling Code Generation |
| 941 | --------------------------- |
| 942 | |
| 943 | Clang provides a number of ways to control code generation. The options |
| 944 | are listed below. |
| 945 | |
Sean Silva | fb1ff86 | 2013-06-21 23:50:58 +0000 | [diff] [blame] | 946 | **-f[no-]sanitize=check1,check2,...** |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 947 | Turn on runtime checks for various forms of undefined or suspicious |
| 948 | behavior. |
| 949 | |
| 950 | This option controls whether Clang adds runtime checks for various |
| 951 | forms of undefined or suspicious behavior, and is disabled by |
| 952 | default. If a check fails, a diagnostic message is produced at |
| 953 | runtime explaining the problem. The main checks are: |
| 954 | |
Richard Smith | 2dce7be | 2012-12-13 07:29:23 +0000 | [diff] [blame] | 955 | - .. _opt_fsanitize_address: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 956 | |
Richard Smith | 2dce7be | 2012-12-13 07:29:23 +0000 | [diff] [blame] | 957 | ``-fsanitize=address``: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 958 | :doc:`AddressSanitizer`, a memory error |
| 959 | detector. |
Richard Smith | 2dce7be | 2012-12-13 07:29:23 +0000 | [diff] [blame] | 960 | - .. _opt_fsanitize_thread: |
| 961 | |
Dmitry Vyukov | 7f5e76b | 2012-12-21 08:21:25 +0000 | [diff] [blame] | 962 | ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector. |
Evgeniy Stepanov | cc603e9 | 2012-12-21 10:50:00 +0000 | [diff] [blame] | 963 | - .. _opt_fsanitize_memory: |
| 964 | |
| 965 | ``-fsanitize=memory``: :doc:`MemorySanitizer`, |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 966 | a detector of uninitialized reads. Requires instrumentation of all |
| 967 | program code. |
Richard Smith | 2dce7be | 2012-12-13 07:29:23 +0000 | [diff] [blame] | 968 | - .. _opt_fsanitize_undefined: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 969 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 970 | ``-fsanitize=undefined``: :doc:`UndefinedBehaviorSanitizer`, |
| 971 | a fast and compatible undefined behavior checker. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 972 | |
Peter Collingbourne | 2eeed71 | 2013-08-07 22:47:34 +0000 | [diff] [blame] | 973 | - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data |
| 974 | flow analysis. |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 975 | - ``-fsanitize=cfi``: :doc:`control flow integrity <ControlFlowIntegrity>` |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 976 | checks. Requires ``-flto``. |
Pirama Arumuga Nainar | b6d6993 | 2015-07-01 12:25:36 -0700 | [diff] [blame] | 977 | - ``-fsanitize=safe-stack``: :doc:`safe stack <SafeStack>` |
| 978 | protection against stack-based memory corruption errors. |
Chad Rosier | 78d85b1 | 2013-01-29 23:31:22 +0000 | [diff] [blame] | 979 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 980 | There are more fine-grained checks available: see |
| 981 | the :ref:`list <ubsan-checks>` of specific kinds of |
| 982 | undefined behavior that can be detected and the :ref:`list <cfi-schemes>` |
| 983 | of control flow integrity schemes. |
Richard Smith | a0ed171 | 2013-05-29 22:57:31 +0000 | [diff] [blame] | 984 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 985 | The ``-fsanitize=`` argument must also be provided when linking, in |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 986 | order to link to the appropriate runtime library. |
Richard Smith | 635c1dc | 2013-07-19 19:06:48 +0000 | [diff] [blame] | 987 | |
| 988 | It is not possible to combine more than one of the ``-fsanitize=address``, |
| 989 | ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 990 | program. |
Richard Smith | 635c1dc | 2013-07-19 19:06:48 +0000 | [diff] [blame] | 991 | |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 992 | **-f[no-]sanitize-recover=check1,check2,...** |
| 993 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 994 | **-f[no-]sanitize-recover=all** |
| 995 | |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 996 | Controls which checks enabled by ``-fsanitize=`` flag are non-fatal. |
| 997 | If the check is fatal, program will halt after the first error |
| 998 | of this kind is detected and error report is printed. |
| 999 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1000 | By default, non-fatal checks are those enabled by |
| 1001 | :doc:`UndefinedBehaviorSanitizer`, |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 1002 | except for ``-fsanitize=return`` and ``-fsanitize=unreachable``. Some |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1003 | sanitizers may not support recovery (or not support it by default |
| 1004 | e.g. :doc:`AddressSanitizer`), and always crash the program after the issue |
| 1005 | is detected. |
| 1006 | |
| 1007 | Note that the ``-fsanitize-trap`` flag has precedence over this flag. |
| 1008 | This means that if a check has been configured to trap elsewhere on the |
| 1009 | command line, or if the check traps by default, this flag will not have |
| 1010 | any effect unless that sanitizer's trapping behavior is disabled with |
| 1011 | ``-fno-sanitize-trap``. |
| 1012 | |
| 1013 | For example, if a command line contains the flags ``-fsanitize=undefined |
| 1014 | -fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment`` |
| 1015 | will have no effect on its own; it will need to be accompanied by |
| 1016 | ``-fno-sanitize-trap=alignment``. |
| 1017 | |
| 1018 | **-f[no-]sanitize-trap=check1,check2,...** |
| 1019 | |
| 1020 | Controls which checks enabled by the ``-fsanitize=`` flag trap. This |
| 1021 | option is intended for use in cases where the sanitizer runtime cannot |
| 1022 | be used (for instance, when building libc or a kernel module), or where |
| 1023 | the binary size increase caused by the sanitizer runtime is a concern. |
| 1024 | |
| 1025 | This flag is only compatible with :doc:`control flow integrity |
| 1026 | <ControlFlowIntegrity>` schemes and :doc:`UndefinedBehaviorSanitizer` |
| 1027 | checks other than ``vptr``. If this flag |
| 1028 | is supplied together with ``-fsanitize=undefined``, the ``vptr`` sanitizer |
| 1029 | will be implicitly disabled. |
| 1030 | |
| 1031 | This flag is enabled by default for sanitizers in the ``cfi`` group. |
| 1032 | |
| 1033 | .. option:: -fsanitize-blacklist=/path/to/blacklist/file |
| 1034 | |
| 1035 | Disable or modify sanitizer checks for objects (source files, functions, |
| 1036 | variables, types) listed in the file. See |
| 1037 | :doc:`SanitizerSpecialCaseList` for file format description. |
| 1038 | |
| 1039 | .. option:: -fno-sanitize-blacklist |
| 1040 | |
| 1041 | Don't use blacklist file, if it was specified earlier in the command line. |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 1042 | |
Pirama Arumuga Nainar | b6d6993 | 2015-07-01 12:25:36 -0700 | [diff] [blame] | 1043 | **-f[no-]sanitize-coverage=[type,features,...]** |
| 1044 | |
| 1045 | Enable simple code coverage in addition to certain sanitizers. |
| 1046 | See :doc:`SanitizerCoverage` for more details. |
| 1047 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 1048 | **-f[no-]sanitize-stats** |
| 1049 | |
| 1050 | Enable simple statistics gathering for the enabled sanitizers. |
| 1051 | See :doc:`SanitizerStats` for more details. |
| 1052 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1053 | .. option:: -fsanitize-undefined-trap-on-error |
| 1054 | |
| 1055 | Deprecated alias for ``-fsanitize-trap=undefined``. |
| 1056 | |
| 1057 | .. option:: -fsanitize-cfi-cross-dso |
| 1058 | |
| 1059 | Enable cross-DSO control flow integrity checks. This flag modifies |
| 1060 | the behavior of sanitizers in the ``cfi`` group to allow checking |
| 1061 | of cross-DSO virtual and indirect calls. |
| 1062 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 1063 | .. option:: -ffast-math |
| 1064 | |
| 1065 | Enable fast-math mode. This defines the ``__FAST_MATH__`` preprocessor |
| 1066 | macro, and lets the compiler make aggressive, potentially-lossy assumptions |
| 1067 | about floating-point math. These include: |
| 1068 | |
| 1069 | * Floating-point math obeys regular algebraic rules for real numbers (e.g. |
| 1070 | ``+`` and ``*`` are associative, ``x/y == x * (1/y)``, and |
| 1071 | ``(a + b) * c == a * c + b * c``), |
| 1072 | * operands to floating-point operations are not equal to ``NaN`` and |
| 1073 | ``Inf``, and |
| 1074 | * ``+0`` and ``-0`` are interchangeable. |
| 1075 | |
| 1076 | .. option:: -fwhole-program-vtables |
| 1077 | |
| 1078 | Enable whole-program vtable optimizations, such as single-implementation |
| 1079 | devirtualization and virtual constant propagation, for classes with |
| 1080 | :doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``. |
| 1081 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1082 | .. option:: -fno-assume-sane-operator-new |
| 1083 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1084 | Don't assume that the C++'s new operator is sane. |
| 1085 | |
| 1086 | This option tells the compiler to do not assume that C++'s global |
| 1087 | new operator will always return a pointer that does not alias any |
| 1088 | other pointer when the function returns. |
| 1089 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1090 | .. option:: -ftrap-function=[name] |
| 1091 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1092 | Instruct code generator to emit a function call to the specified |
| 1093 | function name for ``__builtin_trap()``. |
| 1094 | |
| 1095 | LLVM code generator translates ``__builtin_trap()`` to a trap |
| 1096 | instruction if it is supported by the target ISA. Otherwise, the |
| 1097 | builtin is translated into a call to ``abort``. If this option is |
| 1098 | set, then the code generator will always lower the builtin to a call |
| 1099 | to the specified function regardless of whether the target ISA has a |
| 1100 | trap instruction. This option is useful for environments (e.g. |
| 1101 | deeply embedded) where a trap cannot be properly handled, or when |
| 1102 | some custom behavior is desired. |
| 1103 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1104 | .. option:: -ftls-model=[model] |
| 1105 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1106 | Select which TLS model to use. |
| 1107 | |
| 1108 | Valid values are: ``global-dynamic``, ``local-dynamic``, |
| 1109 | ``initial-exec`` and ``local-exec``. The default value is |
| 1110 | ``global-dynamic``. The compiler may use a different model if the |
| 1111 | selected model is not supported by the target, or if a more |
| 1112 | efficient model can be used. The TLS model can be overridden per |
| 1113 | variable using the ``tls_model`` attribute. |
| 1114 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1115 | .. option:: -femulated-tls |
| 1116 | |
| 1117 | Select emulated TLS model, which overrides all -ftls-model choices. |
| 1118 | |
| 1119 | In emulated TLS mode, all access to TLS variables are converted to |
| 1120 | calls to __emutls_get_address in the runtime library. |
| 1121 | |
Silviu Baranga | 1db2e27 | 2013-10-21 10:54:53 +0000 | [diff] [blame] | 1122 | .. option:: -mhwdiv=[values] |
| 1123 | |
| 1124 | Select the ARM modes (arm or thumb) that support hardware division |
| 1125 | instructions. |
| 1126 | |
| 1127 | Valid values are: ``arm``, ``thumb`` and ``arm,thumb``. |
| 1128 | This option is used to indicate which mode (arm or thumb) supports |
| 1129 | hardware division instructions. This only applies to the ARM |
| 1130 | architecture. |
| 1131 | |
Bernard Ogden | 909f35a | 2013-10-29 09:47:51 +0000 | [diff] [blame] | 1132 | .. option:: -m[no-]crc |
| 1133 | |
| 1134 | Enable or disable CRC instructions. |
| 1135 | |
| 1136 | This option is used to indicate whether CRC instructions are to |
| 1137 | be generated. This only applies to the ARM architecture. |
| 1138 | |
| 1139 | CRC instructions are enabled by default on ARMv8. |
| 1140 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 1141 | .. option:: -mgeneral-regs-only |
| 1142 | |
| 1143 | Generate code which only uses the general purpose registers. |
| 1144 | |
| 1145 | This option restricts the generated code to use general registers |
| 1146 | only. This only applies to the AArch64 architecture. |
| 1147 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 1148 | .. option:: -mcompact-branches=[values] |
| 1149 | |
| 1150 | Control the usage of compact branches for MIPSR6. |
| 1151 | |
| 1152 | Valid values are: ``never``, ``optimal`` and ``always``. |
| 1153 | The default value is ``optimal`` which generates compact branches |
| 1154 | when a delay slot cannot be filled. ``never`` disables the usage of |
| 1155 | compact branches and ``always`` generates compact branches whenever |
| 1156 | possible. |
| 1157 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1158 | **-f[no-]max-type-align=[number]** |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 1159 | Instruct the code generator to not enforce a higher alignment than the given |
| 1160 | number (of bytes) when accessing memory via an opaque pointer or reference. |
| 1161 | This cap is ignored when directly accessing a variable or when the pointee |
| 1162 | type has an explicit “aligned” attribute. |
| 1163 | |
| 1164 | The value should usually be determined by the properties of the system allocator. |
| 1165 | Some builtin types, especially vector types, have very high natural alignments; |
| 1166 | when working with values of those types, Clang usually wants to use instructions |
| 1167 | that take advantage of that alignment. However, many system allocators do |
| 1168 | not promise to return memory that is more than 8-byte or 16-byte-aligned. Use |
| 1169 | this option to limit the alignment that the compiler can assume for an arbitrary |
| 1170 | pointer, which may point onto the heap. |
| 1171 | |
| 1172 | This option does not affect the ABI alignment of types; the layout of structs and |
| 1173 | unions and the value returned by the alignof operator remain the same. |
| 1174 | |
| 1175 | This option can be overridden on a case-by-case basis by putting an explicit |
| 1176 | “aligned” alignment on a struct, union, or typedef. For example: |
| 1177 | |
| 1178 | .. code-block:: console |
| 1179 | |
| 1180 | #include <immintrin.h> |
| 1181 | // Make an aligned typedef of the AVX-512 16-int vector type. |
| 1182 | typedef __v16si __aligned_v16si __attribute__((aligned(64))); |
| 1183 | |
| 1184 | void initialize_vector(__aligned_v16si *v) { |
| 1185 | // The compiler may assume that ‘v’ is 64-byte aligned, regardless of the |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1186 | // value of -fmax-type-align. |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 1187 | } |
| 1188 | |
Silviu Baranga | 1db2e27 | 2013-10-21 10:54:53 +0000 | [diff] [blame] | 1189 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 1190 | Profile Guided Optimization |
| 1191 | --------------------------- |
| 1192 | |
| 1193 | Profile information enables better optimization. For example, knowing that a |
| 1194 | branch is taken very frequently helps the compiler make better decisions when |
| 1195 | ordering basic blocks. Knowing that a function ``foo`` is called more |
| 1196 | frequently than another function ``bar`` helps the inliner. |
| 1197 | |
| 1198 | Clang supports profile guided optimization with two different kinds of |
| 1199 | profiling. A sampling profiler can generate a profile with very low runtime |
| 1200 | overhead, or you can build an instrumented version of the code that collects |
| 1201 | more detailed profile information. Both kinds of profiles can provide execution |
| 1202 | counts for instructions in the code and information on branches taken and |
| 1203 | function invocation. |
| 1204 | |
| 1205 | Regardless of which kind of profiling you use, be careful to collect profiles |
| 1206 | by running your code with inputs that are representative of the typical |
| 1207 | behavior. Code that is not exercised in the profile will be optimized as if it |
| 1208 | is unimportant, and the compiler may make poor optimization choices for code |
| 1209 | that is disproportionately used while profiling. |
| 1210 | |
Pirama Arumuga Nainar | b6d6993 | 2015-07-01 12:25:36 -0700 | [diff] [blame] | 1211 | Differences Between Sampling and Instrumentation |
| 1212 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1213 | |
| 1214 | Although both techniques are used for similar purposes, there are important |
| 1215 | differences between the two: |
| 1216 | |
| 1217 | 1. Profile data generated with one cannot be used by the other, and there is no |
| 1218 | conversion tool that can convert one to the other. So, a profile generated |
| 1219 | via ``-fprofile-instr-generate`` must be used with ``-fprofile-instr-use``. |
| 1220 | Similarly, sampling profiles generated by external profilers must be |
| 1221 | converted and used with ``-fprofile-sample-use``. |
| 1222 | |
| 1223 | 2. Instrumentation profile data can be used for code coverage analysis and |
| 1224 | optimization. |
| 1225 | |
| 1226 | 3. Sampling profiles can only be used for optimization. They cannot be used for |
| 1227 | code coverage analysis. Although it would be technically possible to use |
| 1228 | sampling profiles for code coverage, sample-based profiles are too |
| 1229 | coarse-grained for code coverage purposes; it would yield poor results. |
| 1230 | |
| 1231 | 4. Sampling profiles must be generated by an external tool. The profile |
| 1232 | generated by that tool must then be converted into a format that can be read |
| 1233 | by LLVM. The section on sampling profilers describes one of the supported |
| 1234 | sampling profile formats. |
| 1235 | |
| 1236 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 1237 | Using Sampling Profilers |
| 1238 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 1239 | |
| 1240 | Sampling profilers are used to collect runtime information, such as |
| 1241 | hardware counters, while your application executes. They are typically |
| 1242 | very efficient and do not incur a large runtime overhead. The |
| 1243 | sample data collected by the profiler can be used during compilation |
| 1244 | to determine what the most executed areas of the code are. |
| 1245 | |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 1246 | Using the data from a sample profiler requires some changes in the way |
| 1247 | a program is built. Before the compiler can use profiling information, |
| 1248 | the code needs to execute under the profiler. The following is the |
| 1249 | usual build cycle when using sample profilers for optimization: |
| 1250 | |
| 1251 | 1. Build the code with source line table information. You can use all the |
| 1252 | usual build flags that you always build your application with. The only |
| 1253 | requirement is that you add ``-gline-tables-only`` or ``-g`` to the |
| 1254 | command line. This is important for the profiler to be able to map |
| 1255 | instructions back to source line locations. |
| 1256 | |
| 1257 | .. code-block:: console |
| 1258 | |
| 1259 | $ clang++ -O2 -gline-tables-only code.cc -o code |
| 1260 | |
| 1261 | 2. Run the executable under a sampling profiler. The specific profiler |
| 1262 | you use does not really matter, as long as its output can be converted |
| 1263 | into the format that the LLVM optimizer understands. Currently, there |
| 1264 | exists a conversion tool for the Linux Perf profiler |
| 1265 | (https://perf.wiki.kernel.org/), so these examples assume that you |
| 1266 | are using Linux Perf to profile your code. |
| 1267 | |
| 1268 | .. code-block:: console |
| 1269 | |
| 1270 | $ perf record -b ./code |
| 1271 | |
| 1272 | Note the use of the ``-b`` flag. This tells Perf to use the Last Branch |
| 1273 | Record (LBR) to record call chains. While this is not strictly required, |
| 1274 | it provides better call information, which improves the accuracy of |
| 1275 | the profile data. |
| 1276 | |
| 1277 | 3. Convert the collected profile data to LLVM's sample profile format. |
| 1278 | This is currently supported via the AutoFDO converter ``create_llvm_prof``. |
| 1279 | It is available at http://github.com/google/autofdo. Once built and |
| 1280 | installed, you can convert the ``perf.data`` file to LLVM using |
| 1281 | the command: |
| 1282 | |
| 1283 | .. code-block:: console |
| 1284 | |
| 1285 | $ create_llvm_prof --binary=./code --out=code.prof |
| 1286 | |
| 1287 | This will read ``perf.data`` and the binary file ``./code`` and emit |
| 1288 | the profile data in ``code.prof``. Note that if you ran ``perf`` |
| 1289 | without the ``-b`` flag, you need to use ``--use_lbr=false`` when |
| 1290 | calling ``create_llvm_prof``. |
| 1291 | |
| 1292 | 4. Build the code again using the collected profile. This step feeds |
| 1293 | the profile back to the optimizers. This should result in a binary |
| 1294 | that executes faster than the original one. Note that you are not |
| 1295 | required to build the code with the exact same arguments that you |
| 1296 | used in the first step. The only requirement is that you build the code |
| 1297 | with ``-gline-tables-only`` and ``-fprofile-sample-use``. |
| 1298 | |
| 1299 | .. code-block:: console |
| 1300 | |
| 1301 | $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code |
| 1302 | |
| 1303 | |
Pirama Arumuga Nainar | b6d6993 | 2015-07-01 12:25:36 -0700 | [diff] [blame] | 1304 | Sample Profile Formats |
| 1305 | """""""""""""""""""""" |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 1306 | |
Pirama Arumuga Nainar | b6d6993 | 2015-07-01 12:25:36 -0700 | [diff] [blame] | 1307 | Since external profilers generate profile data in a variety of custom formats, |
| 1308 | the data generated by the profiler must be converted into a format that can be |
| 1309 | read by the backend. LLVM supports three different sample profile formats: |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 1310 | |
Pirama Arumuga Nainar | b6d6993 | 2015-07-01 12:25:36 -0700 | [diff] [blame] | 1311 | 1. ASCII text. This is the easiest one to generate. The file is divided into |
| 1312 | sections, which correspond to each of the functions with profile |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1313 | information. The format is described below. It can also be generated from |
| 1314 | the binary or gcov formats using the ``llvm-profdata`` tool. |
Pirama Arumuga Nainar | b6d6993 | 2015-07-01 12:25:36 -0700 | [diff] [blame] | 1315 | |
| 1316 | 2. Binary encoding. This uses a more efficient encoding that yields smaller |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1317 | profile files. This is the format generated by the ``create_llvm_prof`` tool |
| 1318 | in http://github.com/google/autofdo. |
Pirama Arumuga Nainar | b6d6993 | 2015-07-01 12:25:36 -0700 | [diff] [blame] | 1319 | |
| 1320 | 3. GCC encoding. This is based on the gcov format, which is accepted by GCC. It |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1321 | is only interesting in environments where GCC and Clang co-exist. This |
| 1322 | encoding is only generated by the ``create_gcov`` tool in |
| 1323 | http://github.com/google/autofdo. It can be read by LLVM and |
| 1324 | ``llvm-profdata``, but it cannot be generated by either. |
Pirama Arumuga Nainar | b6d6993 | 2015-07-01 12:25:36 -0700 | [diff] [blame] | 1325 | |
| 1326 | If you are using Linux Perf to generate sampling profiles, you can use the |
| 1327 | conversion tool ``create_llvm_prof`` described in the previous section. |
| 1328 | Otherwise, you will need to write a conversion tool that converts your |
| 1329 | profiler's native format into one of these three. |
| 1330 | |
| 1331 | |
| 1332 | Sample Profile Text Format |
| 1333 | """""""""""""""""""""""""" |
| 1334 | |
| 1335 | This section describes the ASCII text format for sampling profiles. It is, |
| 1336 | arguably, the easiest one to generate. If you are interested in generating any |
| 1337 | of the other two, consult the ``ProfileData`` library in in LLVM's source tree |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1338 | (specifically, ``include/llvm/ProfileData/SampleProfReader.h``). |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 1339 | |
| 1340 | .. code-block:: console |
| 1341 | |
| 1342 | function1:total_samples:total_head_samples |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1343 | offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ] |
| 1344 | offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ] |
| 1345 | ... |
| 1346 | offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ] |
| 1347 | offsetA[.discriminator]: fnA:num_of_total_samples |
| 1348 | offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ] |
| 1349 | offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ] |
| 1350 | offsetB[.discriminator]: fnB:num_of_total_samples |
| 1351 | offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ] |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 1352 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1353 | This is a nested tree in which the identation represents the nesting level |
| 1354 | of the inline stack. There are no blank lines in the file. And the spacing |
| 1355 | within a single line is fixed. Additional spaces will result in an error |
| 1356 | while reading the file. |
| 1357 | |
| 1358 | Any line starting with the '#' character is completely ignored. |
| 1359 | |
| 1360 | Inlined calls are represented with indentation. The Inline stack is a |
| 1361 | stack of source locations in which the top of the stack represents the |
| 1362 | leaf function, and the bottom of the stack represents the actual |
| 1363 | symbol to which the instruction belongs. |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 1364 | |
| 1365 | Function names must be mangled in order for the profile loader to |
| 1366 | match them in the current translation unit. The two numbers in the |
| 1367 | function header specify how many total samples were accumulated in the |
| 1368 | function (first number), and the total number of samples accumulated |
| 1369 | in the prologue of the function (second number). This head sample |
| 1370 | count provides an indicator of how frequently the function is invoked. |
| 1371 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1372 | There are two types of lines in the function body. |
| 1373 | |
| 1374 | - Sampled line represents the profile information of a source location. |
| 1375 | ``offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]`` |
| 1376 | |
| 1377 | - Callsite line represents the profile information of an inlined callsite. |
| 1378 | ``offsetA[.discriminator]: fnA:num_of_total_samples`` |
| 1379 | |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 1380 | Each sampled line may contain several items. Some are optional (marked |
| 1381 | below): |
| 1382 | |
| 1383 | a. Source line offset. This number represents the line number |
| 1384 | in the function where the sample was collected. The line number is |
| 1385 | always relative to the line where symbol of the function is |
| 1386 | defined. So, if the function has its header at line 280, the offset |
| 1387 | 13 is at line 293 in the file. |
| 1388 | |
| 1389 | Note that this offset should never be a negative number. This could |
| 1390 | happen in cases like macros. The debug machinery will register the |
| 1391 | line number at the point of macro expansion. So, if the macro was |
| 1392 | expanded in a line before the start of the function, the profile |
| 1393 | converter should emit a 0 as the offset (this means that the optimizers |
| 1394 | will not be able to associate a meaningful weight to the instructions |
| 1395 | in the macro). |
| 1396 | |
| 1397 | b. [OPTIONAL] Discriminator. This is used if the sampled program |
| 1398 | was compiled with DWARF discriminator support |
| 1399 | (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators). |
| 1400 | DWARF discriminators are unsigned integer values that allow the |
| 1401 | compiler to distinguish between multiple execution paths on the |
| 1402 | same source line location. |
| 1403 | |
| 1404 | For example, consider the line of code ``if (cond) foo(); else bar();``. |
| 1405 | If the predicate ``cond`` is true 80% of the time, then the edge |
| 1406 | into function ``foo`` should be considered to be taken most of the |
| 1407 | time. But both calls to ``foo`` and ``bar`` are at the same source |
| 1408 | line, so a sample count at that line is not sufficient. The |
| 1409 | compiler needs to know which part of that line is taken more |
| 1410 | frequently. |
| 1411 | |
| 1412 | This is what discriminators provide. In this case, the calls to |
| 1413 | ``foo`` and ``bar`` will be at the same line, but will have |
| 1414 | different discriminator values. This allows the compiler to correctly |
| 1415 | set edge weights into ``foo`` and ``bar``. |
| 1416 | |
| 1417 | c. Number of samples. This is an integer quantity representing the |
| 1418 | number of samples collected by the profiler at this source |
| 1419 | location. |
| 1420 | |
| 1421 | d. [OPTIONAL] Potential call targets and samples. If present, this |
| 1422 | line contains a call instruction. This models both direct and |
| 1423 | number of samples. For example, |
| 1424 | |
| 1425 | .. code-block:: console |
| 1426 | |
| 1427 | 130: 7 foo:3 bar:2 baz:7 |
| 1428 | |
| 1429 | The above means that at relative line offset 130 there is a call |
| 1430 | instruction that calls one of ``foo()``, ``bar()`` and ``baz()``, |
| 1431 | with ``baz()`` being the relatively more frequently called target. |
| 1432 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1433 | As an example, consider a program with the call chain ``main -> foo -> bar``. |
| 1434 | When built with optimizations enabled, the compiler may inline the |
| 1435 | calls to ``bar`` and ``foo`` inside ``main``. The generated profile |
| 1436 | could then be something like this: |
| 1437 | |
| 1438 | .. code-block:: console |
| 1439 | |
| 1440 | main:35504:0 |
| 1441 | 1: _Z3foov:35504 |
| 1442 | 2: _Z32bari:31977 |
| 1443 | 1.1: 31977 |
| 1444 | 2: 0 |
| 1445 | |
| 1446 | This profile indicates that there were a total of 35,504 samples |
| 1447 | collected in main. All of those were at line 1 (the call to ``foo``). |
| 1448 | Of those, 31,977 were spent inside the body of ``bar``. The last line |
| 1449 | of the profile (``2: 0``) corresponds to line 2 inside ``main``. No |
| 1450 | samples were collected there. |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 1451 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 1452 | Profiling with Instrumentation |
| 1453 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1454 | |
| 1455 | Clang also supports profiling via instrumentation. This requires building a |
| 1456 | special instrumented version of the code and has some runtime |
| 1457 | overhead during the profiling, but it provides more detailed results than a |
| 1458 | sampling profiler. It also provides reproducible results, at least to the |
| 1459 | extent that the code behaves consistently across runs. |
| 1460 | |
| 1461 | Here are the steps for using profile guided optimization with |
| 1462 | instrumentation: |
| 1463 | |
| 1464 | 1. Build an instrumented version of the code by compiling and linking with the |
| 1465 | ``-fprofile-instr-generate`` option. |
| 1466 | |
| 1467 | .. code-block:: console |
| 1468 | |
| 1469 | $ clang++ -O2 -fprofile-instr-generate code.cc -o code |
| 1470 | |
| 1471 | 2. Run the instrumented executable with inputs that reflect the typical usage. |
| 1472 | By default, the profile data will be written to a ``default.profraw`` file |
| 1473 | in the current directory. You can override that default by setting the |
| 1474 | ``LLVM_PROFILE_FILE`` environment variable to specify an alternate file. |
| 1475 | Any instance of ``%p`` in that file name will be replaced by the process |
| 1476 | ID, so that you can easily distinguish the profile output from multiple |
| 1477 | runs. |
| 1478 | |
| 1479 | .. code-block:: console |
| 1480 | |
| 1481 | $ LLVM_PROFILE_FILE="code-%p.profraw" ./code |
| 1482 | |
| 1483 | 3. Combine profiles from multiple runs and convert the "raw" profile format to |
Pirama Arumuga Nainar | b6d6993 | 2015-07-01 12:25:36 -0700 | [diff] [blame] | 1484 | the input expected by clang. Use the ``merge`` command of the |
| 1485 | ``llvm-profdata`` tool to do this. |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 1486 | |
| 1487 | .. code-block:: console |
| 1488 | |
| 1489 | $ llvm-profdata merge -output=code.profdata code-*.profraw |
| 1490 | |
| 1491 | Note that this step is necessary even when there is only one "raw" profile, |
| 1492 | since the merge operation also changes the file format. |
| 1493 | |
| 1494 | 4. Build the code again using the ``-fprofile-instr-use`` option to specify the |
| 1495 | collected profile data. |
| 1496 | |
| 1497 | .. code-block:: console |
| 1498 | |
| 1499 | $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code |
| 1500 | |
| 1501 | You can repeat step 4 as often as you like without regenerating the |
| 1502 | profile. As you make changes to your code, clang may no longer be able to |
| 1503 | use the profile data. It will warn you when this happens. |
| 1504 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1505 | Profile generation and use can also be controlled by the GCC-compatible flags |
| 1506 | ``-fprofile-generate`` and ``-fprofile-use``. Although these flags are |
| 1507 | semantically equivalent to their GCC counterparts, they *do not* handle |
| 1508 | GCC-compatible profiles. They are only meant to implement GCC's semantics |
| 1509 | with respect to profile creation and use. |
| 1510 | |
| 1511 | .. option:: -fprofile-generate[=<dirname>] |
| 1512 | |
| 1513 | Without any other arguments, ``-fprofile-generate`` behaves identically to |
| 1514 | ``-fprofile-instr-generate``. When given a directory name, it generates the |
| 1515 | profile file ``default.profraw`` in the directory named ``dirname``. If |
| 1516 | ``dirname`` does not exist, it will be created at runtime. The environment |
| 1517 | variable ``LLVM_PROFILE_FILE`` can be used to override the directory and |
| 1518 | filename for the profile file at runtime. For example, |
| 1519 | |
| 1520 | .. code-block:: console |
| 1521 | |
| 1522 | $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code |
| 1523 | |
| 1524 | When ``code`` is executed, the profile will be written to the file |
| 1525 | ``yyy/zzz/default.profraw``. This can be altered at runtime via the |
| 1526 | ``LLVM_PROFILE_FILE`` environment variable: |
| 1527 | |
| 1528 | .. code-block:: console |
| 1529 | |
| 1530 | $ LLVM_PROFILE_FILE=/tmp/myprofile/code.profraw ./code |
| 1531 | |
| 1532 | The above invocation will produce the profile file |
| 1533 | ``/tmp/myprofile/code.profraw`` instead of ``yyy/zzz/default.profraw``. |
| 1534 | Notice that ``LLVM_PROFILE_FILE`` overrides the directory *and* the file |
| 1535 | name for the profile file. |
| 1536 | |
| 1537 | .. option:: -fprofile-use[=<pathname>] |
| 1538 | |
| 1539 | Without any other arguments, ``-fprofile-use`` behaves identically to |
| 1540 | ``-fprofile-instr-use``. Otherwise, if ``pathname`` is the full path to a |
| 1541 | profile file, it reads from that file. If ``pathname`` is a directory name, |
| 1542 | it reads from ``pathname/default.profdata``. |
| 1543 | |
| 1544 | Disabling Instrumentation |
| 1545 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1546 | |
| 1547 | In certain situations, it may be useful to disable profile generation or use |
| 1548 | for specific files in a build, without affecting the main compilation flags |
| 1549 | used for the other files in the project. |
| 1550 | |
| 1551 | In these cases, you can use the flag ``-fno-profile-instr-generate`` (or |
| 1552 | ``-fno-profile-generate``) to disable profile generation, and |
| 1553 | ``-fno-profile-instr-use`` (or ``-fno-profile-use``) to disable profile use. |
| 1554 | |
| 1555 | Note that these flags should appear after the corresponding profile |
| 1556 | flags to have an effect. |
| 1557 | |
| 1558 | Controlling Debug Information |
| 1559 | ----------------------------- |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 1560 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1561 | Controlling Size of Debug Information |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1562 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1563 | |
| 1564 | Debug info kind generated by Clang can be set by one of the flags listed |
| 1565 | below. If multiple flags are present, the last one is used. |
| 1566 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1567 | .. option:: -g0 |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1568 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1569 | Don't generate any debug info (default). |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1570 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1571 | .. option:: -gline-tables-only |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1572 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1573 | Generate line number tables only. |
| 1574 | |
| 1575 | This kind of debug info allows to obtain stack traces with function names, |
| 1576 | file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It |
| 1577 | doesn't contain any other data (e.g. description of local variables or |
| 1578 | function parameters). |
| 1579 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 1580 | .. option:: -fstandalone-debug |
| 1581 | |
| 1582 | Clang supports a number of optimizations to reduce the size of debug |
| 1583 | information in the binary. They work based on the assumption that |
| 1584 | the debug type information can be spread out over multiple |
| 1585 | compilation units. For instance, Clang will not emit type |
| 1586 | definitions for types that are not needed by a module and could be |
| 1587 | replaced with a forward declaration. Further, Clang will only emit |
| 1588 | type info for a dynamic C++ class in the module that contains the |
| 1589 | vtable for the class. |
| 1590 | |
| 1591 | The **-fstandalone-debug** option turns off these optimizations. |
| 1592 | This is useful when working with 3rd-party libraries that don't come |
| 1593 | with debug information. Note that Clang will never emit type |
| 1594 | information for types that are not referenced at all by the program. |
| 1595 | |
| 1596 | .. option:: -fno-standalone-debug |
| 1597 | |
| 1598 | On Darwin **-fstandalone-debug** is enabled by default. The |
| 1599 | **-fno-standalone-debug** option can be used to get to turn on the |
| 1600 | vtable-based optimization described above. |
| 1601 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1602 | .. option:: -g |
| 1603 | |
| 1604 | Generate complete debug info. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1605 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1606 | Controlling Debugger "Tuning" |
| 1607 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1608 | |
| 1609 | While Clang generally emits standard DWARF debug info (http://dwarfstd.org), |
| 1610 | different debuggers may know how to take advantage of different specific DWARF |
| 1611 | features. You can "tune" the debug info for one of several different debuggers. |
| 1612 | |
| 1613 | .. option:: -ggdb, -glldb, -gsce |
| 1614 | |
| 1615 | Tune the debug info for the ``gdb``, ``lldb``, or Sony Computer Entertainment |
| 1616 | debugger, respectively. Each of these options implies **-g**. (Therefore, if |
| 1617 | you want both **-gline-tables-only** and debugger tuning, the tuning option |
| 1618 | must come first.) |
| 1619 | |
| 1620 | |
Dmitri Gribenko | 6fd7d30 | 2013-04-10 15:35:17 +0000 | [diff] [blame] | 1621 | Comment Parsing Options |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 1622 | ----------------------- |
Dmitri Gribenko | 6fd7d30 | 2013-04-10 15:35:17 +0000 | [diff] [blame] | 1623 | |
| 1624 | Clang parses Doxygen and non-Doxygen style documentation comments and attaches |
| 1625 | them to the appropriate declaration nodes. By default, it only parses |
| 1626 | Doxygen-style comments and ignores ordinary comments starting with ``//`` and |
| 1627 | ``/*``. |
| 1628 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 1629 | .. option:: -Wdocumentation |
| 1630 | |
| 1631 | Emit warnings about use of documentation comments. This warning group is off |
| 1632 | by default. |
| 1633 | |
| 1634 | This includes checking that ``\param`` commands name parameters that actually |
| 1635 | present in the function signature, checking that ``\returns`` is used only on |
| 1636 | functions that actually return a value etc. |
| 1637 | |
| 1638 | .. option:: -Wno-documentation-unknown-command |
| 1639 | |
| 1640 | Don't warn when encountering an unknown Doxygen command. |
| 1641 | |
Dmitri Gribenko | 6fd7d30 | 2013-04-10 15:35:17 +0000 | [diff] [blame] | 1642 | .. option:: -fparse-all-comments |
| 1643 | |
| 1644 | Parse all comments as documentation comments (including ordinary comments |
| 1645 | starting with ``//`` and ``/*``). |
| 1646 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 1647 | .. option:: -fcomment-block-commands=[commands] |
| 1648 | |
| 1649 | Define custom documentation commands as block commands. This allows Clang to |
| 1650 | construct the correct AST for these custom commands, and silences warnings |
| 1651 | about unknown commands. Several commands must be separated by a comma |
| 1652 | *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines |
| 1653 | custom commands ``\foo`` and ``\bar``. |
| 1654 | |
| 1655 | It is also possible to use ``-fcomment-block-commands`` several times; e.g. |
| 1656 | ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same |
| 1657 | as above. |
| 1658 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1659 | .. _c: |
| 1660 | |
| 1661 | C Language Features |
| 1662 | =================== |
| 1663 | |
| 1664 | The support for standard C in clang is feature-complete except for the |
| 1665 | C99 floating-point pragmas. |
| 1666 | |
| 1667 | Extensions supported by clang |
| 1668 | ----------------------------- |
| 1669 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1670 | See :doc:`LanguageExtensions`. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1671 | |
| 1672 | Differences between various standard modes |
| 1673 | ------------------------------------------ |
| 1674 | |
| 1675 | clang supports the -std option, which changes what language mode clang |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 1676 | uses. The supported modes for C are c89, gnu89, c94, c99, gnu99, c11, |
| 1677 | gnu11, and various aliases for those modes. If no -std option is |
| 1678 | specified, clang defaults to gnu11 mode. Many C99 and C11 features are |
| 1679 | supported in earlier modes as a conforming extension, with a warning. Use |
| 1680 | ``-pedantic-errors`` to request an error if a feature from a later standard |
| 1681 | revision is used in an earlier mode. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1682 | |
| 1683 | Differences between all ``c*`` and ``gnu*`` modes: |
| 1684 | |
| 1685 | - ``c*`` modes define "``__STRICT_ANSI__``". |
| 1686 | - Target-specific defines not prefixed by underscores, like "linux", |
| 1687 | are defined in ``gnu*`` modes. |
| 1688 | - Trigraphs default to being off in ``gnu*`` modes; they can be enabled by |
| 1689 | the -trigraphs option. |
| 1690 | - The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes; |
| 1691 | the variants "``__asm__``" and "``__typeof__``" are recognized in all |
| 1692 | modes. |
| 1693 | - The Apple "blocks" extension is recognized by default in ``gnu*`` modes |
| 1694 | on some platforms; it can be enabled in any mode with the "-fblocks" |
| 1695 | option. |
| 1696 | - Arrays that are VLA's according to the standard, but which can be |
| 1697 | constant folded by the frontend are treated as fixed size arrays. |
| 1698 | This occurs for things like "int X[(1, 2)];", which is technically a |
| 1699 | VLA. ``c*`` modes are strictly compliant and treat these as VLAs. |
| 1700 | |
| 1701 | Differences between ``*89`` and ``*99`` modes: |
| 1702 | |
| 1703 | - The ``*99`` modes default to implementing "inline" as specified in C99, |
| 1704 | while the ``*89`` modes implement the GNU version. This can be |
| 1705 | overridden for individual functions with the ``__gnu_inline__`` |
| 1706 | attribute. |
| 1707 | - Digraphs are not recognized in c89 mode. |
| 1708 | - The scope of names defined inside a "for", "if", "switch", "while", |
| 1709 | or "do" statement is different. (example: "``if ((struct x {int |
| 1710 | x;}*)0) {}``".) |
| 1711 | - ``__STDC_VERSION__`` is not defined in ``*89`` modes. |
| 1712 | - "inline" is not recognized as a keyword in c89 mode. |
| 1713 | - "restrict" is not recognized as a keyword in ``*89`` modes. |
| 1714 | - Commas are allowed in integer constant expressions in ``*99`` modes. |
| 1715 | - Arrays which are not lvalues are not implicitly promoted to pointers |
| 1716 | in ``*89`` modes. |
| 1717 | - Some warnings are different. |
| 1718 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 1719 | Differences between ``*99`` and ``*11`` modes: |
| 1720 | |
| 1721 | - Warnings for use of C11 features are disabled. |
| 1722 | - ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``. |
| 1723 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1724 | c94 mode is identical to c89 mode except that digraphs are enabled in |
| 1725 | c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!). |
| 1726 | |
| 1727 | GCC extensions not implemented yet |
| 1728 | ---------------------------------- |
| 1729 | |
| 1730 | clang tries to be compatible with gcc as much as possible, but some gcc |
| 1731 | extensions are not implemented yet: |
| 1732 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1733 | - clang does not support decimal floating point types (``_Decimal32`` and |
| 1734 | friends) or fixed-point types (``_Fract`` and friends); nobody has |
| 1735 | expressed interest in these features yet, so it's hard to say when |
| 1736 | they will be implemented. |
| 1737 | - clang does not support nested functions; this is a complex feature |
| 1738 | which is infrequently used, so it is unlikely to be implemented |
| 1739 | anytime soon. In C++11 it can be emulated by assigning lambda |
| 1740 | functions to local variables, e.g: |
| 1741 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1742 | .. code-block:: cpp |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1743 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1744 | auto const local_function = [&](int parameter) { |
| 1745 | // Do something |
| 1746 | }; |
| 1747 | ... |
| 1748 | local_function(1); |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1749 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1750 | - clang does not support static initialization of flexible array |
| 1751 | members. This appears to be a rarely used extension, but could be |
| 1752 | implemented pending user demand. |
| 1753 | - clang does not support |
| 1754 | ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is |
| 1755 | used rarely, but in some potentially interesting places, like the |
| 1756 | glibc headers, so it may be implemented pending user demand. Note |
| 1757 | that because clang pretends to be like GCC 4.2, and this extension |
| 1758 | was introduced in 4.3, the glibc headers will not try to use this |
| 1759 | extension with clang at the moment. |
| 1760 | - clang does not support the gcc extension for forward-declaring |
| 1761 | function parameters; this has not shown up in any real-world code |
| 1762 | yet, though, so it might never be implemented. |
| 1763 | |
| 1764 | This is not a complete list; if you find an unsupported extension |
| 1765 | missing from this list, please send an e-mail to cfe-dev. This list |
| 1766 | currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this |
| 1767 | list does not include bugs in mostly-implemented features; please see |
| 1768 | the `bug |
| 1769 | tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_ |
| 1770 | for known existing bugs (FIXME: Is there a section for bug-reporting |
| 1771 | guidelines somewhere?). |
| 1772 | |
| 1773 | Intentionally unsupported GCC extensions |
| 1774 | ---------------------------------------- |
| 1775 | |
| 1776 | - clang does not support the gcc extension that allows variable-length |
| 1777 | arrays in structures. This is for a few reasons: one, it is tricky to |
| 1778 | implement, two, the extension is completely undocumented, and three, |
| 1779 | the extension appears to be rarely used. Note that clang *does* |
| 1780 | support flexible array members (arrays with a zero or unspecified |
| 1781 | size at the end of a structure). |
| 1782 | - clang does not have an equivalent to gcc's "fold"; this means that |
| 1783 | clang doesn't accept some constructs gcc might accept in contexts |
| 1784 | where a constant expression is required, like "x-x" where x is a |
| 1785 | variable. |
| 1786 | - clang does not support ``__builtin_apply`` and friends; this extension |
| 1787 | is extremely obscure and difficult to implement reliably. |
| 1788 | |
| 1789 | .. _c_ms: |
| 1790 | |
| 1791 | Microsoft extensions |
| 1792 | -------------------- |
| 1793 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 1794 | clang has support for many extensions from Microsoft Visual C++. To enable these |
| 1795 | extensions, use the ``-fms-extensions`` command-line option. This is the default |
| 1796 | for Windows targets. Clang does not implement every pragma or declspec provided |
| 1797 | by MSVC, but the popular ones, such as ``__declspec(dllexport)`` and ``#pragma |
| 1798 | comment(lib)`` are well supported. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1799 | |
Bill Wendling | c27813a | 2013-12-12 04:30:51 +0000 | [diff] [blame] | 1800 | clang has a ``-fms-compatibility`` flag that makes clang accept enough |
Reid Kleckner | 09ab088 | 2013-09-20 17:04:25 +0000 | [diff] [blame] | 1801 | invalid C++ to be able to parse most Microsoft headers. For example, it |
| 1802 | allows `unqualified lookup of dependent base class members |
Reid Kleckner | dec5f28 | 2013-09-20 17:54:39 +0000 | [diff] [blame] | 1803 | <http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is |
| 1804 | a common compatibility issue with clang. This flag is enabled by default |
Reid Kleckner | 09ab088 | 2013-09-20 17:04:25 +0000 | [diff] [blame] | 1805 | for Windows targets. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1806 | |
Bill Wendling | c27813a | 2013-12-12 04:30:51 +0000 | [diff] [blame] | 1807 | ``-fdelayed-template-parsing`` lets clang delay parsing of function template |
| 1808 | definitions until the end of a translation unit. This flag is enabled by |
| 1809 | default for Windows targets. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1810 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 1811 | For compatibility with existing code that compiles with MSVC, clang defines the |
| 1812 | ``_MSC_VER`` and ``_MSC_FULL_VER`` macros. These default to the values of 1800 |
| 1813 | and 180000000 respectively, making clang look like an early release of Visual |
| 1814 | C++ 2013. The ``-fms-compatibility-version=`` flag overrides these values. It |
| 1815 | accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC |
| 1816 | compatibility version makes clang behave more like that version of MSVC. For |
| 1817 | example, ``-fms-compatibility-version=19`` will enable C++14 features and define |
| 1818 | ``char16_t`` and ``char32_t`` as builtin types. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1819 | |
| 1820 | .. _cxx: |
| 1821 | |
| 1822 | C++ Language Features |
| 1823 | ===================== |
| 1824 | |
| 1825 | clang fully implements all of standard C++98 except for exported |
Bill Wendling | c27813a | 2013-12-12 04:30:51 +0000 | [diff] [blame] | 1826 | templates (which were removed in C++11), and all of standard C++11 |
| 1827 | and the current draft standard for C++1y. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1828 | |
| 1829 | Controlling implementation limits |
| 1830 | --------------------------------- |
| 1831 | |
Richard Smith | 9e738cc | 2013-02-22 01:59:51 +0000 | [diff] [blame] | 1832 | .. option:: -fbracket-depth=N |
| 1833 | |
| 1834 | Sets the limit for nested parentheses, brackets, and braces to N. The |
| 1835 | default is 256. |
| 1836 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1837 | .. option:: -fconstexpr-depth=N |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1838 | |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1839 | Sets the limit for recursive constexpr function invocations to N. The |
| 1840 | default is 512. |
| 1841 | |
| 1842 | .. option:: -ftemplate-depth=N |
| 1843 | |
| 1844 | Sets the limit for recursively nested template instantiations to N. The |
Richard Smith | 195dd7c | 2013-11-06 19:31:51 +0000 | [diff] [blame] | 1845 | default is 256. |
| 1846 | |
| 1847 | .. option:: -foperator-arrow-depth=N |
| 1848 | |
| 1849 | Sets the limit for iterative calls to 'operator->' functions to N. The |
| 1850 | default is 256. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1851 | |
| 1852 | .. _objc: |
| 1853 | |
| 1854 | Objective-C Language Features |
| 1855 | ============================= |
| 1856 | |
| 1857 | .. _objcxx: |
| 1858 | |
| 1859 | Objective-C++ Language Features |
| 1860 | =============================== |
| 1861 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 1862 | .. _openmp: |
| 1863 | |
| 1864 | OpenMP Features |
| 1865 | =============== |
| 1866 | |
| 1867 | Clang supports all OpenMP 3.1 directives and clauses. In addition, some |
| 1868 | features of OpenMP 4.0 are supported. For example, ``#pragma omp simd``, |
| 1869 | ``#pragma omp for simd``, ``#pragma omp parallel for simd`` directives, extended |
| 1870 | set of atomic constructs, ``proc_bind`` clause for all parallel-based |
| 1871 | directives, ``depend`` clause for ``#pragma omp task`` directive (except for |
| 1872 | array sections), ``#pragma omp cancel`` and ``#pragma omp cancellation point`` |
| 1873 | directives, and ``#pragma omp taskgroup`` directive. |
| 1874 | |
| 1875 | Use :option:`-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with |
| 1876 | :option:`-fno-openmp`. |
| 1877 | |
| 1878 | Controlling implementation limits |
| 1879 | --------------------------------- |
| 1880 | |
| 1881 | .. option:: -fopenmp-use-tls |
| 1882 | |
| 1883 | Controls code generation for OpenMP threadprivate variables. In presence of |
| 1884 | this option all threadprivate variables are generated the same way as thread |
| 1885 | local variables, using TLS support. If :option:`-fno-openmp-use-tls` |
| 1886 | is provided or target does not support TLS, code generation for threadprivate |
| 1887 | variables relies on OpenMP runtime library. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1888 | |
| 1889 | .. _target_features: |
| 1890 | |
| 1891 | Target-Specific Features and Limitations |
| 1892 | ======================================== |
| 1893 | |
| 1894 | CPU Architectures Features and Limitations |
| 1895 | ------------------------------------------ |
| 1896 | |
| 1897 | X86 |
| 1898 | ^^^ |
| 1899 | |
| 1900 | The support for X86 (both 32-bit and 64-bit) is considered stable on |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 1901 | Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1902 | to correctly compile many large C, C++, Objective-C, and Objective-C++ |
| 1903 | codebases. |
| 1904 | |
Bill Wendling | c27813a | 2013-12-12 04:30:51 +0000 | [diff] [blame] | 1905 | On ``x86_64-mingw32``, passing i128(by value) is incompatible with the |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 1906 | Microsoft x64 calling convention. You might need to tweak |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1907 | ``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp. |
| 1908 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 1909 | For the X86 target, clang supports the :option:`-m16` command line |
| 1910 | argument which enables 16-bit code output. This is broadly similar to |
| 1911 | using ``asm(".code16gcc")`` with the GNU toolchain. The generated code |
| 1912 | and the ABI remains 32-bit but the assembler emits instructions |
| 1913 | appropriate for a CPU running in 16-bit mode, with address-size and |
| 1914 | operand-size prefixes to enable 32-bit addressing and operations. |
| 1915 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1916 | ARM |
| 1917 | ^^^ |
| 1918 | |
| 1919 | The support for ARM (specifically ARMv6 and ARMv7) is considered stable |
| 1920 | on Darwin (iOS): it has been tested to correctly compile many large C, |
| 1921 | C++, Objective-C, and Objective-C++ codebases. Clang only supports a |
| 1922 | limited number of ARM architectures. It does not yet fully support |
| 1923 | ARMv5, for example. |
| 1924 | |
Roman Divacky | cd7b0f0 | 2013-09-11 17:12:49 +0000 | [diff] [blame] | 1925 | PowerPC |
| 1926 | ^^^^^^^ |
| 1927 | |
| 1928 | The support for PowerPC (especially PowerPC64) is considered stable |
| 1929 | on Linux and FreeBSD: it has been tested to correctly compile many |
| 1930 | large C and C++ codebases. PowerPC (32bit) is still missing certain |
| 1931 | features (e.g. PIC code on ELF platforms). |
| 1932 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1933 | Other platforms |
| 1934 | ^^^^^^^^^^^^^^^ |
| 1935 | |
Roman Divacky | cd7b0f0 | 2013-09-11 17:12:49 +0000 | [diff] [blame] | 1936 | clang currently contains some support for other architectures (e.g. Sparc); |
| 1937 | however, significant pieces of code generation are still missing, and they |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1938 | haven't undergone significant testing. |
| 1939 | |
| 1940 | clang contains limited support for the MSP430 embedded processor, but |
| 1941 | both the clang support and the LLVM backend support are highly |
| 1942 | experimental. |
| 1943 | |
| 1944 | Other platforms are completely unsupported at the moment. Adding the |
| 1945 | minimal support needed for parsing and semantic analysis on a new |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1946 | 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] | 1947 | tree. This level of support is also sufficient for conversion to LLVM IR |
| 1948 | for simple programs. Proper support for conversion to LLVM IR requires |
Dmitri Gribenko | 0bd9e72 | 2012-12-19 22:06:59 +0000 | [diff] [blame] | 1949 | 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] | 1950 | change soon, though. Generating assembly requires a suitable LLVM |
| 1951 | backend. |
| 1952 | |
| 1953 | Operating System Features and Limitations |
| 1954 | ----------------------------------------- |
| 1955 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 1956 | Darwin (Mac OS X) |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1957 | ^^^^^^^^^^^^^^^^^ |
| 1958 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 1959 | Thread Sanitizer is not supported. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1960 | |
| 1961 | Windows |
| 1962 | ^^^^^^^ |
| 1963 | |
Bill Wendling | c27813a | 2013-12-12 04:30:51 +0000 | [diff] [blame] | 1964 | Clang has experimental support for targeting "Cygming" (Cygwin / MinGW) |
| 1965 | platforms. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1966 | |
Reid Kleckner | af6f8cc | 2013-09-05 21:29:35 +0000 | [diff] [blame] | 1967 | See also :ref:`Microsoft Extensions <c_ms>`. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1968 | |
| 1969 | Cygwin |
| 1970 | """""" |
| 1971 | |
| 1972 | Clang works on Cygwin-1.7. |
| 1973 | |
| 1974 | MinGW32 |
| 1975 | """"""" |
| 1976 | |
| 1977 | Clang works on some mingw32 distributions. Clang assumes directories as |
| 1978 | below; |
| 1979 | |
| 1980 | - ``C:/mingw/include`` |
| 1981 | - ``C:/mingw/lib`` |
| 1982 | - ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++`` |
| 1983 | |
| 1984 | On MSYS, a few tests might fail. |
| 1985 | |
| 1986 | MinGW-w64 |
| 1987 | """"""""" |
| 1988 | |
| 1989 | For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang |
| 1990 | assumes as below; |
| 1991 | |
| 1992 | - ``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)`` |
| 1993 | - ``some_directory/bin/gcc.exe`` |
| 1994 | - ``some_directory/bin/clang.exe`` |
| 1995 | - ``some_directory/bin/clang++.exe`` |
| 1996 | - ``some_directory/bin/../include/c++/GCC_version`` |
| 1997 | - ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32`` |
| 1998 | - ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32`` |
| 1999 | - ``some_directory/bin/../include/c++/GCC_version/backward`` |
| 2000 | - ``some_directory/bin/../x86_64-w64-mingw32/include`` |
| 2001 | - ``some_directory/bin/../i686-w64-mingw32/include`` |
| 2002 | - ``some_directory/bin/../include`` |
| 2003 | |
| 2004 | This directory layout is standard for any toolchain you will find on the |
| 2005 | official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_. |
| 2006 | |
| 2007 | Clang expects the GCC executable "gcc.exe" compiled for |
| 2008 | ``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH. |
| 2009 | |
| 2010 | `Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on |
| 2011 | ``x86_64-w64-mingw32``. |
Hans Wennborg | 0a6cf66 | 2013-10-10 01:15:16 +0000 | [diff] [blame] | 2012 | |
| 2013 | .. _clang-cl: |
| 2014 | |
| 2015 | clang-cl |
| 2016 | ======== |
| 2017 | |
| 2018 | clang-cl is an alternative command-line interface to Clang driver, designed for |
| 2019 | compatibility with the Visual C++ compiler, cl.exe. |
| 2020 | |
| 2021 | To enable clang-cl to find system headers, libraries, and the linker when run |
| 2022 | from the command-line, it should be executed inside a Visual Studio Native Tools |
| 2023 | Command Prompt or a regular Command Prompt where the environment has been set |
| 2024 | up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_. |
| 2025 | |
| 2026 | clang-cl can also be used from inside Visual Studio by using an LLVM Platform |
| 2027 | Toolset. |
| 2028 | |
| 2029 | Command-Line Options |
| 2030 | -------------------- |
| 2031 | |
| 2032 | To be compatible with cl.exe, clang-cl supports most of the same command-line |
| 2033 | options. Those options can start with either ``/`` or ``-``. It also supports |
| 2034 | some of Clang's core options, such as the ``-W`` options. |
| 2035 | |
| 2036 | Options that are known to clang-cl, but not currently supported, are ignored |
| 2037 | with a warning. For example: |
| 2038 | |
| 2039 | :: |
| 2040 | |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2041 | clang-cl.exe: warning: argument unused during compilation: '/AI' |
Hans Wennborg | 0a6cf66 | 2013-10-10 01:15:16 +0000 | [diff] [blame] | 2042 | |
| 2043 | To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option. |
| 2044 | |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 2045 | Options that are not known to clang-cl will be ignored by default. Use the |
| 2046 | ``-Werror=unknown-argument`` option in order to treat them as errors. If these |
| 2047 | options are spelled with a leading ``/``, they will be mistaken for a filename: |
Hans Wennborg | 0a6cf66 | 2013-10-10 01:15:16 +0000 | [diff] [blame] | 2048 | |
| 2049 | :: |
| 2050 | |
| 2051 | clang-cl.exe: error: no such file or directory: '/foobar' |
| 2052 | |
| 2053 | Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_ |
| 2054 | for any valid cl.exe flags that clang-cl does not understand. |
| 2055 | |
| 2056 | Execute ``clang-cl /?`` to see a list of supported options: |
| 2057 | |
| 2058 | :: |
| 2059 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 2060 | CL.EXE COMPATIBILITY OPTIONS: |
| 2061 | /? Display available options |
| 2062 | /arch:<value> Set architecture for code generation |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 2063 | /Brepro- Emit an object file which cannot be reproduced over time |
| 2064 | /Brepro Emit an object file which can be reproduced over time |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 2065 | /C Don't discard comments when preprocessing |
| 2066 | /c Compile only |
| 2067 | /D <macro[=value]> Define macro |
| 2068 | /EH<value> Exception handling model |
| 2069 | /EP Disable linemarker output and preprocess to stdout |
| 2070 | /E Preprocess to stdout |
| 2071 | /fallback Fall back to cl.exe if clang-cl fails to compile |
| 2072 | /FA Output assembly code file during compilation |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2073 | /Fa<file or directory> Output assembly code to this file during compilation (with /FA) |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 2074 | /Fe<file or directory> Set output executable file or directory (ends in / or \) |
| 2075 | /FI <value> Include file before parsing |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2076 | /Fi<file> Set preprocess output file name (with /P) |
| 2077 | /Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c) |
| 2078 | /fp:except- |
| 2079 | /fp:except |
| 2080 | /fp:fast |
| 2081 | /fp:precise |
| 2082 | /fp:strict |
| 2083 | /GA Assume thread-local variables are defined in the executable |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 2084 | /GF- Disable string pooling |
| 2085 | /GR- Disable emission of RTTI data |
| 2086 | /GR Enable emission of RTTI data |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2087 | /Gs<value> Set stack probe size |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 2088 | /Gw- Don't put each data item in its own section |
| 2089 | /Gw Put each data item in its own section |
| 2090 | /Gy- Don't put each function in its own section |
| 2091 | /Gy Put each function in its own section |
| 2092 | /help Display available options |
| 2093 | /I <dir> Add directory to include search path |
| 2094 | /J Make char type unsigned |
| 2095 | /LDd Create debug DLL |
| 2096 | /LD Create DLL |
| 2097 | /link <options> Forward options to the linker |
| 2098 | /MDd Use DLL debug run-time |
| 2099 | /MD Use DLL run-time |
| 2100 | /MTd Use static debug run-time |
| 2101 | /MT Use static run-time |
| 2102 | /Ob0 Disable inlining |
| 2103 | /Od Disable optimization |
| 2104 | /Oi- Disable use of builtin functions |
| 2105 | /Oi Enable use of builtin functions |
| 2106 | /Os Optimize for size |
| 2107 | /Ot Optimize for speed |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2108 | /O<value> Optimization level |
| 2109 | /o <file or directory> Set output file or directory (ends in / or \) |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 2110 | /P Preprocess to file |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2111 | /Qvec- Disable the loop vectorization passes |
| 2112 | /Qvec Enable the loop vectorization passes |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 2113 | /showIncludes Print info about included files to stderr |
| 2114 | /TC Treat all source files as C |
| 2115 | /Tc <filename> Specify a C source file |
| 2116 | /TP Treat all source files as C++ |
| 2117 | /Tp <filename> Specify a C++ source file |
| 2118 | /U <macro> Undefine macro |
| 2119 | /vd<value> Control vtordisp placement |
| 2120 | /vmb Use a best-case representation method for member pointers |
| 2121 | /vmg Use a most-general representation for member pointers |
| 2122 | /vmm Set the default most-general representation to multiple inheritance |
| 2123 | /vms Set the default most-general representation to single inheritance |
| 2124 | /vmv Set the default most-general representation to virtual inheritance |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2125 | /volatile:iso Volatile loads and stores have standard semantics |
| 2126 | /volatile:ms Volatile loads and stores have acquire and release semantics |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 2127 | /W0 Disable all warnings |
| 2128 | /W1 Enable -Wall |
| 2129 | /W2 Enable -Wall |
| 2130 | /W3 Enable -Wall |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2131 | /W4 Enable -Wall and -Wextra |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 2132 | /Wall Enable -Wall and -Wextra |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 2133 | /WX- Do not treat warnings as errors |
| 2134 | /WX Treat warnings as errors |
| 2135 | /w Disable all warnings |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2136 | /Z7 Enable CodeView debug information in object files |
| 2137 | /Zc:sizedDealloc- Disable C++14 sized global deallocation functions |
| 2138 | /Zc:sizedDealloc Enable C++14 sized global deallocation functions |
| 2139 | /Zc:strictStrings Treat string literals as const |
| 2140 | /Zc:threadSafeInit- Disable thread-safe initialization of static variables |
| 2141 | /Zc:threadSafeInit Enable thread-safe initialization of static variables |
| 2142 | /Zc:trigraphs- Disable trigraphs (default) |
| 2143 | /Zc:trigraphs Enable trigraphs |
| 2144 | /Zi Alias for /Z7. Does not produce PDBs. |
| 2145 | /Zl Don't mention any default libraries in the object file |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 2146 | /Zp Set the default maximum struct packing alignment to 1 |
| 2147 | /Zp<value> Specify the default maximum struct packing alignment |
| 2148 | /Zs Syntax-check only |
| 2149 | |
| 2150 | OPTIONS: |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2151 | -### Print (but do not run) the commands to run for this compilation |
| 2152 | --analyze Run the static analyzer |
| 2153 | -fansi-escape-codes Use ANSI escape codes for diagnostics |
| 2154 | -fcolor-diagnostics Use colors in diagnostics |
| 2155 | -fdiagnostics-parseable-fixits |
| 2156 | Print fix-its in machine parseable form |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 2157 | -fms-compatibility-version=<value> |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2158 | Dot-separated value representing the Microsoft compiler version |
| 2159 | number to report in _MSC_VER (0 = don't define it (default)) |
Pirama Arumuga Nainar | 4967a71 | 2016-09-19 22:19:55 -0700 | [diff] [blame] | 2160 | -fms-compatibility Enable full Microsoft Visual C++ compatibility |
| 2161 | -fms-extensions Accept some non-standard constructs supported by the Microsoft compiler |
| 2162 | -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER |
| 2163 | (0 = don't define it (default)) |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2164 | -fno-sanitize-coverage=<value> |
| 2165 | Disable specified features of coverage instrumentation for Sanitizers |
| 2166 | -fno-sanitize-recover=<value> |
| 2167 | Disable recovery for specified sanitizers |
| 2168 | -fno-sanitize-trap=<value> |
| 2169 | Disable trapping for specified sanitizers |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 2170 | -fsanitize-blacklist=<value> |
Pirama Arumuga Nainar | 87d948e | 2016-03-03 15:49:35 -0800 | [diff] [blame] | 2171 | Path to blacklist file for sanitizers |
| 2172 | -fsanitize-coverage=<value> |
| 2173 | Specify the type of coverage instrumentation for Sanitizers |
| 2174 | -fsanitize-recover=<value> |
| 2175 | Enable recovery for specified sanitizers |
| 2176 | -fsanitize-trap=<value> Enable trapping for specified sanitizers |
| 2177 | -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious |
| 2178 | behavior. See user manual for available checks |
| 2179 | -gcodeview Generate CodeView debug information |
| 2180 | -mllvm <value> Additional arguments to forward to LLVM's option processing |
| 2181 | -Qunused-arguments Don't emit warning for unused driver arguments |
| 2182 | -R<remark> Enable the specified remark |
| 2183 | --target=<value> Generate code for the given target |
| 2184 | -v Show commands to run and use verbose output |
| 2185 | -W<warning> Enable the specified warning |
| 2186 | -Xclang <arg> Pass <arg> to the clang compiler |
Hans Wennborg | 0a6cf66 | 2013-10-10 01:15:16 +0000 | [diff] [blame] | 2187 | |
| 2188 | The /fallback Option |
| 2189 | ^^^^^^^^^^^^^^^^^^^^ |
| 2190 | |
| 2191 | When clang-cl is run with the ``/fallback`` option, it will first try to |
| 2192 | compile files itself. For any file that it fails to compile, it will fall back |
| 2193 | and try to compile the file by invoking cl.exe. |
| 2194 | |
| 2195 | This option is intended to be used as a temporary means to build projects where |
| 2196 | clang-cl cannot successfully compile all the files. clang-cl may fail to compile |
| 2197 | a file either because it cannot generate code for some C++ feature, or because |
| 2198 | it cannot parse some Microsoft language extension. |