1 .\" Man page generated from reStructuredText.
3 .TH "CLANG" "1" "March 20, 2016" "3.8" "Clang"
5 clang \- the Clang C, C++, and Objective-C compiler
7 .nr rst2man-indent-level 0
11 level \\n[rst2man-indent-level]
12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
19 .\" .rstReportMargin pre:
21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
22 . nr rst2man-indent-level +1
23 .\" .rstReportMargin post:
27 .\" indent \\n[an-margin]
28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .nr rst2man-indent-level -1
30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
35 \fBclang\fP [\fIoptions\fP] \fIfilename ...\fP
38 \fBclang\fP is a C, C++, and Objective\-C compiler which encompasses
39 preprocessing, parsing, optimization, code generation, assembly, and linking.
40 Depending on which high\-level mode setting is passed, Clang will stop before
41 doing a full link. While Clang is highly integrated, it is important to
42 understand the stages of compilation, to understand how to invoke it. These
47 The clang executable is actually a small driver which controls the overall
48 execution of other tools such as the compiler, assembler and linker.
49 Typically you do not need to interact with the driver, but you
50 transparently use it to run the other tools.
53 This stage handles tokenization of the input source file, macro expansion,
54 #include expansion and handling of other preprocessor directives. The
55 output of this stage is typically called a ".i" (for C), ".ii" (for C++),
56 ".mi" (for Objective\-C), or ".mii" (for Objective\-C++) file.
58 .B Parsing and Semantic Analysis
59 This stage parses the input file, translating preprocessor tokens into a
60 parse tree. Once in the form of a parse tree, it applies semantic
61 analysis to compute types for expressions as well and determine whether
62 the code is well formed. This stage is responsible for generating most of
63 the compiler warnings as well as parse errors. The output of this stage is
64 an "Abstract Syntax Tree" (AST).
66 .B Code Generation and Optimization
67 This stage translates an AST into low\-level intermediate code (known as
68 "LLVM IR") and ultimately to machine code. This phase is responsible for
69 optimizing the generated code and handling target\-specific code generation.
70 The output of this stage is typically called a ".s" file or "assembly" file.
72 Clang also supports the use of an integrated assembler, in which the code
73 generator produces object files directly. This avoids the overhead of
74 generating the ".s" file and of calling the target assembler.
77 This stage runs the target assembler to translate the output of the
78 compiler into a target object file. The output of this stage is typically
79 called a ".o" file or "object" file.
82 This stage runs the target linker to merge multiple object files into an
83 executable or dynamic library. The output of this stage is typically called
84 an "a.out", ".dylib" or ".so" file.
87 \fBClang Static Analyzer\fP
89 The Clang Static Analyzer is a tool that scans source code to try to find bugs
90 through code analysis. This tool uses many parts of Clang and is built into
91 the same driver. Please see <\fI\%http://clang\-analyzer.llvm.org\fP> for more details
92 on how to use the static analyzer.
94 .SS Stage Selection Options
98 Run the preprocessor stage.
103 Run the preprocessor, parser and type checking stages.
108 Run the previous stages as well as LLVM generation and optimization stages
109 and target\-specific code generation, producing an assembly file.
114 Run all of the above, plus the assembler, generating a target ".o" object file.
118 .B no stage selection option
119 If no stage selection option is specified, all stages above are run, and the
120 linker is run to combine the results into an executable or shared library.
122 .SS Language Selection and Mode Options
126 Treat subsequent input files as having type language.
131 Specify the language standard to compile for.
135 .B \-stdlib=<library>
136 Specify the C++ standard library to use; supported options are libstdc++ and
147 Treat source input files as Objective\-C and Object\-C++ inputs respectively.
157 Indicate that the file should be compiled for a freestanding, not a hosted,
163 Disable special handling and optimizations of builtin functions like
164 \fBstrlen()\fP and \fBmalloc()\fP\&.
169 Indicate that math functions should be treated as updating \fBerrno\fP\&.
173 .B \-fpascal\-strings
174 Enable support for Pascal\-style strings with "\epfoo".
179 Enable support for Microsoft extensions.
184 Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise.
188 .B \-fborland\-extensions
189 Enable support for Borland extensions.
193 .B \-fwritable\-strings
194 Make all string literals default to writable. This disables uniquing of
195 strings and other optimizations.
199 .B \-flax\-vector\-conversions
200 Allow loose type checking rules for implicit vector conversions.
205 Enable the "Blocks" language feature.
210 Indicate that Objective\-C code should be compiled in GC\-only mode, which only
211 works when Objective\-C Garbage Collection is enabled.
216 Indicate that Objective\-C code should be compiled in hybrid\-GC mode, which
217 works with both GC and non\-GC mode.
221 .B \-fobjc\-abi\-version=version
222 Select the Objective\-C ABI version to use. Available versions are 1 (legacy
223 "fragile" ABI), 2 (non\-fragile ABI 1), and 3 (non\-fragile ABI 2).
227 .B \-fobjc\-nonfragile\-abi\-version=<version>
228 Select the Objective\-C non\-fragile ABI version to use by default. This will
229 only be used as the Objective\-C ABI when the non\-fragile ABI is enabled
230 (either via \fI\%\-fobjc\-nonfragile\-abi\fP, or because it is the platform
235 .B \-fobjc\-nonfragile\-abi
236 Enable use of the Objective\-C non\-fragile ABI. On platforms for which this is
237 the default ABI, it can be disabled with \fB\-fno\-objc\-nonfragile\-abi\fP\&.
239 .SS Target Selection Options
241 Clang fully supports cross compilation as an inherent part of its design.
242 Depending on how your version of Clang is configured, it may have support for a
243 number of cross compilers, or may only support a native target.
246 .B \-arch <architecture>
247 Specify the architecture to build for.
251 .B \-mmacosx\-version\-min=<version>
252 When building for Mac OS X, specify the minimum version supported by your
257 .B \-miphoneos\-version\-min
258 When building for iPhone OS, specify the minimum version supported by your
264 Specify that Clang should generate code for a specific processor family
265 member and later. For example, if you specify \-march=i486, the compiler is
266 allowed to generate instructions that are valid on i486 and later processors,
267 but which may not exist on earlier ones.
269 .SS Code Generation Options
272 .B \-O0, \-O1, \-O2, \-O3, \-Ofast, \-Os, \-Oz, \-O, \-O4
273 Specify which optimization level to use:
276 \fI\%\-O0\fP Means "no optimization": this level compiles the fastest and
277 generates the most debuggable code.
279 \fI\%\-O1\fP Somewhere between \fI\%\-O0\fP and \fI\%\-O2\fP\&.
281 \fI\%\-O2\fP Moderate level of optimization which enables most
284 \fI\%\-O3\fP Like \fI\%\-O2\fP, except that it enables optimizations that
285 take longer to perform or that may generate larger code (in an attempt to
286 make the program run faster).
288 \fI\%\-Ofast\fP Enables all the optimizations from \fI\%\-O3\fP along
289 with other aggressive optimizations that may violate strict compliance with
292 \fI\%\-Os\fP Like \fI\%\-O2\fP with extra optimizations to reduce code
295 \fI\%\-Oz\fP Like \fI\%\-Os\fP (and thus \fI\%\-O2\fP), but reduces code
298 \fI\%\-O\fP Equivalent to \fI\%\-O2\fP\&.
300 \fI\%\-O4\fP and higher
303 Currently equivalent to \fI\%\-O3\fP
312 Generate debug information. Note that Clang debug information works best at \-O0.
317 Generate debug information that contains external references to
318 types defined in clang modules or precompiled headers instead of
319 emitting redundant debug type information into every object file.
320 This option implies \fB\-fmodule\-format=obj\fP\&.
322 This option should not be used when building static libraries for
323 distribution to other machines because the debug info will contain
324 references to the module cache on the machine the object files in
325 the library were built on.
329 .B \-fstandalone\-debug \-fno\-standalone\-debug
330 Clang supports a number of optimizations to reduce the size of debug
331 information in the binary. They work based on the assumption that the
332 debug type information can be spread out over multiple compilation units.
333 For instance, Clang will not emit type definitions for types that are not
334 needed by a module and could be replaced with a forward declaration.
335 Further, Clang will only emit type info for a dynamic C++ class in the
336 module that contains the vtable for the class.
338 The \fB\-fstandalone\-debug\fP option turns off these optimizations.
339 This is useful when working with 3rd\-party libraries that don\(aqt come with
340 debug information. This is the default on Darwin. Note that Clang will
341 never emit type information for types that are not referenced at all by the
347 Enable generation of unwind information. This allows exceptions to be thrown
348 through Clang compiled stack frames. This is on by default in x86\-64.
353 Generate code to catch integer overflow errors. Signed integer overflow is
354 undefined in C. With this flag, extra code is generated to detect this and
355 abort when it happens.
360 This flag sets the default visibility level.
365 This flag specifies that variables without initializers get common linkage.
366 It can be disabled with \fB\-fno\-common\fP\&.
370 .B \-ftls\-model=<model>
371 Set the default thread\-local storage (TLS) model to use for thread\-local
372 variables. Valid values are: "global\-dynamic", "local\-dynamic",
373 "initial\-exec" and "local\-exec". The default is "global\-dynamic". The default
374 model can be overridden with the tls_model attribute. The compiler will try
375 to choose a more efficient model if possible.
379 .B \-flto, \-emit\-llvm
380 Generate output files in LLVM formats, suitable for link time optimization.
381 When used with \fI\%\-S\fP this generates LLVM intermediate language
382 assembly files, otherwise this generates LLVM bitcode format object files
383 (which may be passed to the linker depending on the stage selection options).
389 Print (but do not run) the commands to run for this compilation.
394 Display available options.
398 .B \-Qunused\-arguments
399 Do not emit any warnings for unused driver arguments.
404 Pass the comma separated arguments in args to the assembler.
409 Pass the comma separated arguments in args to the linker.
414 Pass the comma separated arguments in args to the preprocessor.
419 Pass arg to the static analyzer.
423 .B \-Xassembler <arg>
424 Pass arg to the assembler.
429 Pass arg to the linker.
433 .B \-Xpreprocessor <arg>
434 Pass arg to the preprocessor.
439 Write output to file.
443 .B \-print\-file\-name=<file>
444 Print the full library path of file.
448 .B \-print\-libgcc\-file\-name
449 Print the library path for "libgcc.a".
453 .B \-print\-prog\-name=<name>
454 Print the full program path of name.
458 .B \-print\-search\-dirs
459 Print the paths used for finding libraries and programs.
464 Save intermediate compilation results.
468 .B \-integrated\-as, \-no\-integrated\-as
469 Used to enable and disable, respectively, the use of the integrated
470 assembler. Whether the integrated assembler is on by default is target
476 Time individual commands.
481 Print timing summary of each stage of compilation.
486 Show commands to run and use verbose output.
488 .SS Diagnostics Options
491 .B \-fshow\-column, \-fshow\-source\-location, \-fcaret\-diagnostics, \-fdiagnostics\-fixit\-info, \-fdiagnostics\-parseable\-fixits, \-fdiagnostics\-print\-source\-range\-info, \-fprint\-source\-range\-info, \-fdiagnostics\-show\-option, \-fmessage\-length
492 These options control how Clang prints out information about diagnostics
493 (errors and warnings). Please see the Clang User\(aqs Manual for more information.
495 .SS Preprocessor Options
498 .B \-D<macroname>=<value>
499 Adds an implicit #define into the predefines buffer which is read before the
500 source file is preprocessed.
505 Adds an implicit #undef into the predefines buffer which is read before the
506 source file is preprocessed.
510 .B \-include <filename>
511 Adds an implicit #include into the predefines buffer which is read before the
512 source file is preprocessed.
517 Add the specified directory to the search path for include files.
522 Add the specified directory to the search path for framework include files.
527 Do not search the standard system directories or compiler builtin directories
533 Do not search the standard system directories for include files, but do
534 search compiler builtin include directories.
539 Do not search clang\(aqs builtin directory for include files.
545 These environment variables are checked, in order, for the location to write
546 temporary files used during the compilation process.
551 If this environment variable is present, it is treated as a delimited list of
552 paths to be added to the default system include path list. The delimiter is
553 the platform dependent delimiter, as used in the PATH environment variable.
555 Empty components in the environment variable are ignored.
559 .B C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH
560 These environment variables specify additional paths, as for \fI\%CPATH\fP, which are
561 only used when processing the appropriate language.
565 .B MACOSX_DEPLOYMENT_TARGET
566 If \fI\%\-mmacosx\-version\-min\fP is unspecified, the default deployment
567 target is read from this environment variable. This option only affects
572 To report bugs, please visit <\fI\%http://llvm.org/bugs/\fP>. Most bug reports should
573 include preprocessed source files (use the \fI\%\-E\fP option) and the full
574 output of the compiler, along with information to reproduce.
577 \fIas(1)\fP, \fIld(1)\fP
579 Maintained by the Clang / LLVM Team (<http://clang.llvm.org>)
581 2007-2016, The Clang Team
582 .\" Generated by docutils manpage writer.