Home | History | Annotate | Download | only in tools
      1 =pod
      2 
      3 =head1 NAME
      4 
      5 clang - the Clang C, C++, and Objective-C compiler
      6 
      7 =head1 SYNOPSIS
      8 
      9 B<clang> [B<-c>|B<-S>|B<-E>] B<-std=>I<standard> B<-g>
     10   [B<-O0>|B<-O1>|B<-O2>|B<-Os>|B<-Oz>|B<-O3>|B<-O4>]
     11   B<-W>I<warnings...> B<-pedantic>
     12   B<-I>I<dir...> B<-L>I<dir...>
     13   B<-D>I<macro[=defn]>
     14   B<-f>I<feature-option...>
     15   B<-m>I<machine-option...>
     16   B<-o> I<output-file>
     17   B<-stdlib=>I<library> 
     18   I<input-filenames>
     19 
     20 =head1 DESCRIPTION
     21 
     22 B<clang> is a C, C++, and Objective-C compiler which encompasses preprocessing,
     23 parsing, optimization, code generation, assembly, and linking.  Depending on
     24 which high-level mode setting is passed, Clang will stop before doing a full
     25 link.  While Clang is highly integrated, it is important to understand the
     26 stages of compilation, to understand how to invoke it.  These stages are:
     27 
     28 =over
     29 
     30 =item B<Driver>
     31 
     32 The B<clang> executable is actually a small driver which controls the overall
     33 execution of other tools such as the compiler, assembler and linker.  Typically
     34 you do not need to interact with the driver, but you transparently use it to run
     35 the other tools.
     36 
     37 =item B<Preprocessing>
     38 
     39 This stage handles tokenization of the input source file, macro expansion,
     40 #include expansion and handling of other preprocessor directives.  The output of
     41 this stage is typically called a ".i" (for C), ".ii" (for C++), ".mi" (for 
     42 Objective-C) , or ".mii" (for Objective-C++) file.
     43 
     44 =item B<Parsing and Semantic Analysis>
     45 
     46 This stage parses the input file, translating preprocessor tokens into a parse
     47 tree.  Once in the form of a parser tree, it applies semantic analysis to compute
     48 types for expressions as well and determine whether the code is well formed. This
     49 stage is responsible for generating most of the compiler warnings as well as
     50 parse errors.  The output of this stage is an "Abstract Syntax Tree" (AST).
     51 
     52 =item B<Code Generation and Optimization>
     53 
     54 This stage translates an AST into low-level intermediate code (known as "LLVM
     55 IR") and ultimately to machine code.  This phase is responsible for optimizing
     56 the generated code and handling target-specific code generation.  The output of
     57 this stage is typically called a ".s" file or "assembly" file.
     58 
     59 Clang also supports the use of an integrated assembler, in which the code
     60 generator produces object files directly. This avoids the overhead of generating
     61 the ".s" file and of calling the target assembler.
     62 
     63 =item B<Assembler>
     64 
     65 This stage runs the target assembler to translate the output of the compiler
     66 into a target object file.  The output of this stage is typically called a ".o"
     67 file or "object" file.
     68 
     69 =item B<Linker>
     70 
     71 This stage runs the target linker to merge multiple object files into an
     72 executable or dynamic library.  The output of this stage is typically called an
     73 "a.out", ".dylib" or ".so" file.
     74 
     75 =back
     76 
     77 The Clang compiler supports a large number of options to control each of these
     78 stages.  In addition to compilation of code, Clang also supports other tools:
     79 
     80 B<Clang Static Analyzer>
     81 
     82 The Clang Static Analyzer is a tool that scans source code to try to find bugs
     83 through code analysis.  This tool uses many parts of Clang and is built into the
     84 same driver.
     85 
     86 
     87 =head1 OPTIONS
     88 
     89 =head2 Stage Selection Options
     90 
     91 =over
     92 
     93 =item B<-E>
     94 
     95 Run the preprocessor stage.
     96 
     97 =item B<-fsyntax-only>
     98 
     99 Run the preprocessor, parser and type checking stages.
    100 
    101 =item B<-S>
    102 
    103 Run the previous stages as well as LLVM generation and optimization stages and
    104 target-specific code generation, producing an assembly file.
    105 
    106 =item B<-c>
    107 
    108 Run all of the above, plus the assembler, generating a target ".o" object file.
    109 
    110 =item B<no stage selection option>
    111 
    112 If no stage selection option is specified, all stages above are run, and the
    113 linker is run to combine the results into an executable or shared library.
    114 
    115 =item B<--analyze>
    116 
    117 Run the Clang Static Analyzer.
    118 
    119 =back
    120 
    121 
    122 
    123 =head2 Language Selection and Mode Options
    124 
    125 =over
    126 
    127 =item B<-x> I<language>
    128 
    129 Treat subsequent input files as having type I<language>.
    130 
    131 =item B<-std>=I<language>
    132 
    133 Specify the language standard to compile for.
    134 
    135 =item B<-stdlib>=I<language>
    136 
    137 Specify the C++ standard library to use; supported options are libstdc++ and
    138 libc++.
    139 
    140 =item B<-ansi>
    141 
    142 Same as B<-std=c89>.
    143 
    144 =item B<-ObjC++>
    145 
    146 Treat source input files as Objective-C++ inputs.
    147 
    148 =item B<-ObjC>
    149 
    150 Treat source input files as Objective-C inputs.
    151 
    152 =item B<-trigraphs>
    153 
    154 Enable trigraphs.
    155 
    156 =item B<-ffreestanding>
    157 
    158 Indicate that the file should be compiled for a freestanding, not a hosted,
    159 environment.
    160 
    161 =item B<-fno-builtin>
    162 
    163 Disable special handling and optimizations of builtin functions like strlen and
    164 malloc.
    165 
    166 =item B<-fmath-errno>
    167 
    168 Indicate that math functions should be treated as updating errno.
    169 
    170 =item B<-fpascal-strings>
    171 
    172 Enable support for Pascal-style strings with "\pfoo".
    173 
    174 =item B<-fms-extensions>
    175 
    176 Enable support for Microsoft extensions.
    177 
    178 =item B<-fmsc-version=>
    179 
    180 Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise.
    181 
    182 =item B<-fborland-extensions>
    183 
    184 Enable support for Borland extensions.
    185 
    186 =item B<-fwritable-strings>
    187 
    188 Make all string literals default to writable.  This disables uniquing of
    189 strings and other optimizations.
    190 
    191 =item B<-flax-vector-conversions>
    192 
    193 Allow loose type checking rules for implicit vector conversions.
    194 
    195 =item B<-fblocks>
    196 
    197 Enable the "Blocks" language feature.
    198 
    199 =item B<-fobjc-gc-only>
    200 
    201 Indicate that Objective-C code should be compiled in GC-only mode, which only
    202 works when Objective-C Garbage Collection is enabled.
    203 
    204 =item B<-fobjc-gc>
    205 
    206 Indicate that Objective-C code should be compiled in hybrid-GC mode, which works
    207 with both GC and non-GC mode.
    208 
    209 =item B<-fobjc-abi-version>=I<version>
    210 
    211 Select the Objective-C ABI version to use. Available versions are 1 (legacy
    212 "fragile" ABI), 2 (non-fragile ABI 1), and 3 (non-fragile ABI 2).
    213 
    214 =item B<-fobjc-nonfragile-abi-version>=I<version>
    215 
    216 Select the Objective-C non-fragile ABI version to use by default. This will only
    217 be used as the Objective-C ABI when the non-fragile ABI is enabled (either via
    218 -fobjc-nonfragile-abi, or because it is the platform default).
    219 
    220 =item B<-fobjc-nonfragile-abi>
    221 
    222 Enable use of the Objective-C non-fragile ABI. On platforms for which this is
    223 the default ABI, it can be disabled with B<-fno-objc-nonfragile-abi>.
    224 
    225 =back
    226 
    227 
    228 
    229 =head2 Target Selection Options
    230 
    231 Clang fully supports cross compilation as an inherent part of its design.
    232 Depending on how your version of Clang is configured, it may have support for
    233 a number of cross compilers, or may only support a native target.
    234 
    235 =over
    236 
    237 =item B<-arch> I<architecture>
    238 
    239 Specify the architecture to build for.
    240 
    241 =item B<-mmacosx-version-min>=I<version>
    242 
    243 When building for Mac OS/X, specify the minimum version supported by your
    244 application.
    245 
    246 =item B<-miphoneos-version-min>
    247 
    248 When building for iPhone OS, specify the minimum version supported by your
    249 application.
    250 
    251 
    252 =item B<-march>=I<cpu>
    253 
    254 Specify that Clang should generate code for a specific processor family member
    255 and later.  For example, if you specify -march=i486, the compiler is allowed to
    256 generate instructions that are valid on i486 and later processors, but which
    257 may not exist on earlier ones.
    258 
    259 =back
    260 
    261 
    262 =head2 Code Generation Options
    263 
    264 =over
    265 
    266 =item B<-O0> B<-O1> B<-O2> B<-Os> B<-Oz> B<-O3> B<-O4>
    267 
    268 Specify which optimization level to use.  B<-O0> means "no optimization": this
    269 level compiles the fastest and generates the most debuggable code.  B<-O2> is a
    270 moderate level of optimization which enables most optimizations.  B<-Os> is like
    271 B<-O2> with extra optimizations to reduce code size.  B<-Oz> is like B<-Os> 
    272 (and thus B<-O2>), but reduces code size further.  B<-O3> is like B<-O2>,
    273 except that it enables optimizations that take longer to perform or that may
    274 generate larger code (in an attempt to make the program run faster).  On
    275 supported platforms, B<-O4> enables link-time optimization; object files are
    276 stored in the LLVM bitcode file format and whole program optimization is done at
    277 link time. B<-O1> is somewhere between B<-O0> and B<-O2>.
    278 
    279 =item B<-g>
    280 
    281 Generate debug information.  Note that Clang debug information works best at
    282 B<-O0>.  At higher optimization levels, only line number information is
    283 currently available.
    284 
    285 =item B<-fexceptions>
    286 
    287 Enable generation of unwind information, this allows exceptions to be thrown
    288 through Clang compiled stack frames.  This is on by default in x86-64.
    289 
    290 =item B<-ftrapv>
    291 
    292 Generate code to catch integer overflow errors.  Signed integer overflow is
    293 undefined in C, with this flag, extra code is generated to detect this and abort
    294 when it happens.
    295 
    296 
    297 =item B<-fvisibility>
    298 
    299 This flag sets the default visibility level.
    300 
    301 =item B<-fcommon>
    302 
    303 This flag specifies that variables without initializers get common linkage.  It
    304 can be disabled with B<-fno-common>.
    305 
    306 =item B<-flto> B<-emit-llvm>
    307 
    308 Generate output files in LLVM formats, suitable for link time optimization. When
    309 used with B<-S> this generates LLVM intermediate language assembly files,
    310 otherwise this generates LLVM bitcode format object files (which may be passed
    311 to the linker depending on the stage selection options).
    312 
    313 =cut
    314 
    315 ##=item B<-fnext-runtime> B<-fobjc-nonfragile-abi> B<-fgnu-runtime>
    316 ##These options specify which Objective-C runtime the code generator should
    317 ##target.  FIXME: we don't want people poking these generally.
    318 
    319 =pod
    320 
    321 =back
    322 
    323 
    324 =head2 Driver Options
    325 
    326 =over
    327 
    328 =item B<-###>
    329 
    330 Print the commands to run for this compilation.
    331 
    332 =item B<--help>
    333 
    334 Display available options.
    335 
    336 =item B<-Qunused-arguments>
    337 
    338 Don't emit warning for unused driver arguments.
    339 
    340 =item B<-Wa,>I<args>
    341 
    342 Pass the comma separated arguments in I<args> to the assembler.
    343 
    344 =item B<-Wl,>I<args>
    345 
    346 Pass the comma separated arguments in I<args> to the linker.
    347 
    348 =item B<-Wp,>I<args>
    349 
    350 Pass the comma separated arguments in I<args> to the preprocessor.
    351 
    352 =item B<-Xanalyzer> I<arg>
    353 
    354 Pass I<arg> to the static analyzer.
    355 
    356 =item B<-Xassembler> I<arg>
    357 
    358 Pass I<arg> to the assembler.
    359 
    360 =item B<-Xlinker> I<arg>
    361 
    362 Pass I<arg> to the linker.
    363 
    364 =item B<-Xpreprocessor> I<arg>
    365 
    366 Pass I<arg> to the preprocessor.
    367 
    368 =item B<-o> I<file>
    369 
    370 Write output to I<file>.
    371 
    372 =item B<-print-file-name>=I<file>
    373 
    374 Print the full library path of I<file>.
    375 
    376 =item B<-print-libgcc-file-name>
    377 
    378 Print the library path for "libgcc.a".
    379 
    380 =item B<-print-prog-name>=I<name>
    381 
    382 Print the full program path of I<name>.
    383 
    384 =item B<-print-search-dirs>
    385 
    386 Print the paths used for finding libraries and programs.
    387 
    388 =item B<-save-temps>
    389 
    390 Save intermediate compilation results.
    391 
    392 =item B<-integrated-as> B<-no-integrated-as>
    393 
    394 Used to enable and disable, respectively, the use of the integrated
    395 assembler. Whether the integrated assembler is on by default is target
    396 dependent.
    397 
    398 =item B<-time>
    399 
    400 Time individual commands.
    401 
    402 =item B<-ftime-report>
    403 
    404 Print timing summary of each stage of compilation.
    405 
    406 =item B<-v>
    407 
    408 Show commands to run and use verbose output.
    409 
    410 =back
    411 
    412 
    413 =head2 Diagnostics Options
    414 
    415 =over
    416 
    417 =item B<-fshow-column>
    418 B<-fshow-source-location>
    419 B<-fcaret-diagnostics>
    420 B<-fdiagnostics-fixit-info>
    421 B<-fdiagnostics-parseable-fixits>
    422 B<-fdiagnostics-print-source-range-info>
    423 B<-fprint-source-range-info>
    424 B<-fdiagnostics-show-option>
    425 B<-fmessage-length>
    426 
    427 These options control how Clang prints out information about diagnostics (errors
    428 and warnings).  Please see the Clang User's Manual for more information.
    429 
    430 =back
    431 
    432 
    433 =head2 Preprocessor Options
    434 
    435 =over
    436 
    437 =item B<-D>I<macroname=value>
    438 
    439 Adds an implicit #define into the predefines buffer which is read before the
    440 source file is preprocessed.
    441 
    442 =item B<-U>I<macroname>
    443 
    444 Adds an implicit #undef into the predefines buffer which is read before the
    445 source file is preprocessed.
    446 
    447 =item B<-include> I<filename>
    448 
    449 Adds an implicit #include into the predefines buffer which is read before the
    450 source file is preprocessed.
    451 
    452 =item B<-I>I<directory>
    453 
    454 Add the specified directory to the search path for include files.
    455 
    456 =item B<-F>I<directory>
    457 
    458 Add the specified directory to the search path for framework include files.
    459 
    460 =item B<-nostdinc>
    461 
    462 Do not search the standard system directories or compiler builtin directories
    463 for include files.
    464 
    465 =item B<-nostdlibinc>
    466 
    467 Do not search the standard system directories for include files, but do search
    468 compiler builtin include directories.
    469 
    470 =item B<-nobuiltininc>
    471 
    472 Do not search clang's builtin directory for include files.
    473 
    474 =cut
    475 
    476 ## TODO, but do we really want people using this stuff?
    477 #=item B<-idirafter>I<directory>
    478 #=item B<-iquote>I<directory>
    479 #=item B<-isystem>I<directory>
    480 #=item B<-iprefix>I<directory>
    481 #=item B<-iwithprefix>I<directory>
    482 #=item B<-iwithprefixbefore>I<directory>
    483 #=item B<-isysroot>
    484 
    485 =pod
    486 
    487 
    488 =back
    489 
    490 
    491 
    492 =cut
    493 
    494 ### TODO someday.
    495 #=head2 Warning Control Options
    496 #=over
    497 #=back
    498 #=head2 Code Generation and Optimization Options
    499 #=over
    500 #=back
    501 #=head2 Assembler Options
    502 #=over
    503 #=back
    504 #=head2 Linker Options
    505 #=over
    506 #=back
    507 #=head2 Static Analyzer Options
    508 #=over
    509 #=back
    510 
    511 =pod
    512 
    513 
    514 =head1 ENVIRONMENT
    515 
    516 =over
    517 
    518 =item B<TMPDIR>, B<TEMP>, B<TMP>
    519 
    520 These environment variables are checked, in order, for the location to
    521 write temporary files used during the compilation process.
    522 
    523 =item B<CPATH>
    524 
    525 If this environment variable is present, it is treated as a delimited
    526 list of paths to be added to the default system include path list. The
    527 delimiter is the platform dependent delimitor, as used in the I<PATH>
    528 environment variable.
    529 
    530 Empty components in the environment variable are ignored.
    531 
    532 =item B<C_INCLUDE_PATH>, B<OBJC_INCLUDE_PATH>, B<CPLUS_INCLUDE_PATH>,
    533 B<OBJCPLUS_INCLUDE_PATH>
    534 
    535 These environment variables specify additional paths, as for CPATH,
    536 which are only used when processing the appropriate language.
    537 
    538 =item B<MACOSX_DEPLOYMENT_TARGET>
    539 
    540 If -mmacosx-version-min is unspecified, the default deployment target
    541 is read from this environment variable.  This option only affects darwin
    542 targets.
    543 
    544 =back
    545 
    546 =head1 BUGS
    547 
    548 To report bugs, please visit L<http://llvm.org/bugs/>.  Most bug reports should
    549 include preprocessed source files (use the B<-E> option) and the full output of 
    550 the compiler, along with information to reproduce.
    551 
    552 =head1 SEE ALSO
    553 
    554  as(1), ld(1)
    555 
    556 =head1 AUTHOR
    557 
    558 Maintained by the Clang / LLVM Team (L<http://clang.llvm.org>).
    559 
    560 =cut
    561