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