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