2 .\" Man page generated from reStructuredText.
4 .TH "CLANG" "1" "March 04, 2016" "3.8" "Clang"
6 clang \- the Clang C, C++, and Objective-C compiler
8 .nr rst2man-indent-level 0
12 level \\n[rst2man-indent-level]
13 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
20 .\" .rstReportMargin pre:
22 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
23 . nr rst2man-indent-level +1
24 .\" .rstReportMargin post:
28 .\" indent \\n[an-margin]
29 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
30 .nr rst2man-indent-level -1
31 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
32 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
36 \fBclang\fP [\fIoptions\fP] \fIfilename ...\fP
39 \fBclang\fP is a C, C++, and Objective\-C compiler which encompasses
40 preprocessing, parsing, optimization, code generation, assembly, and linking.
41 Depending on which high\-level mode setting is passed, Clang will stop before
42 doing a full link. While Clang is highly integrated, it is important to
43 understand the stages of compilation, to understand how to invoke it. These
48 The clang executable is actually a small driver which controls the overall
49 execution of other tools such as the compiler, assembler and linker.
50 Typically you do not need to interact with the driver, but you
51 transparently use it to run the other tools.
54 This stage handles tokenization of the input source file, macro expansion,
55 #include expansion and handling of other preprocessor directives. The
56 output of this stage is typically called a ".i" (for C), ".ii" (for C++),
57 ".mi" (for Objective\-C), or ".mii" (for Objective\-C++) file.
59 .B Parsing and Semantic Analysis
60 This stage parses the input file, translating preprocessor tokens into a
61 parse tree. Once in the form of a parse tree, it applies semantic
62 analysis to compute types for expressions as well and determine whether
63 the code is well formed. This stage is responsible for generating most of
64 the compiler warnings as well as parse errors. The output of this stage is
65 an "Abstract Syntax Tree" (AST).
67 .B Code Generation and Optimization
68 This stage translates an AST into low\-level intermediate code (known as
69 "LLVM IR") and ultimately to machine code. This phase is responsible for
70 optimizing the generated code and handling target\-specific code generation.
71 The output of this stage is typically called a ".s" file or "assembly" file.
73 Clang also supports the use of an integrated assembler, in which the code
74 generator produces object files directly. This avoids the overhead of
75 generating the ".s" file and of calling the target assembler.
78 This stage runs the target assembler to translate the output of the
79 compiler into a target object file. The output of this stage is typically
80 called a ".o" file or "object" file.
83 This stage runs the target linker to merge multiple object files into an
84 executable or dynamic library. The output of this stage is typically called
85 an "a.out", ".dylib" or ".so" file.
88 \fBClang Static Analyzer\fP
90 The Clang Static Analyzer is a tool that scans source code to try to find bugs
91 through code analysis. This tool uses many parts of Clang and is built into
92 the same driver. Please see <\fI\%http://clang\-analyzer.llvm.org\fP> for more details
93 on how to use the static analyzer.
95 .SS Stage Selection Options
99 Run the preprocessor stage.
104 Run the preprocessor, parser and type checking stages.
109 Run the previous stages as well as LLVM generation and optimization stages
110 and target\-specific code generation, producing an assembly file.
115 Run all of the above, plus the assembler, generating a target ".o" object file.
119 .B no stage selection option
120 If no stage selection option is specified, all stages above are run, and the
121 linker is run to combine the results into an executable or shared library.
123 .SS Language Selection and Mode Options
127 Treat subsequent input files as having type language.
132 Specify the language standard to compile for.
136 .B \-stdlib=<library>
137 Specify the C++ standard library to use; supported options are libstdc++ and
148 Treat source input files as Objective\-C and Object\-C++ inputs respectively.
158 Indicate that the file should be compiled for a freestanding, not a hosted,
164 Disable special handling and optimizations of builtin functions like
165 \fBstrlen()\fP and \fBmalloc()\fP\&.
170 Indicate that math functions should be treated as updating \fBerrno\fP\&.
174 .B \-fpascal\-strings
175 Enable support for Pascal\-style strings with "\epfoo".
180 Enable support for Microsoft extensions.
185 Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise.
189 .B \-fborland\-extensions
190 Enable support for Borland extensions.
194 .B \-fwritable\-strings
195 Make all string literals default to writable. This disables uniquing of
196 strings and other optimizations.
200 .B \-flax\-vector\-conversions
201 Allow loose type checking rules for implicit vector conversions.
206 Enable the "Blocks" language feature.
211 Indicate that Objective\-C code should be compiled in GC\-only mode, which only
212 works when Objective\-C Garbage Collection is enabled.
217 Indicate that Objective\-C code should be compiled in hybrid\-GC mode, which
218 works with both GC and non\-GC mode.
222 .B \-fobjc\-abi\-version=version
223 Select the Objective\-C ABI version to use. Available versions are 1 (legacy
224 "fragile" ABI), 2 (non\-fragile ABI 1), and 3 (non\-fragile ABI 2).
228 .B \-fobjc\-nonfragile\-abi\-version=<version>
229 Select the Objective\-C non\-fragile ABI version to use by default. This will
230 only be used as the Objective\-C ABI when the non\-fragile ABI is enabled
231 (either via \fI\%\-fobjc\-nonfragile\-abi\fP, or because it is the platform
236 .B \-fobjc\-nonfragile\-abi
237 Enable use of the Objective\-C non\-fragile ABI. On platforms for which this is
238 the default ABI, it can be disabled with \fB\-fno\-objc\-nonfragile\-abi\fP\&.
240 .SS Target Selection Options
242 Clang fully supports cross compilation as an inherent part of its design.
243 Depending on how your version of Clang is configured, it may have support for a
244 number of cross compilers, or may only support a native target.
247 .B \-arch <architecture>
248 Specify the architecture to build for.
252 .B \-mmacosx\-version\-min=<version>
253 When building for Mac OS X, specify the minimum version supported by your
258 .B \-miphoneos\-version\-min
259 When building for iPhone OS, specify the minimum version supported by your
265 Specify that Clang should generate code for a specific processor family
266 member and later. For example, if you specify \-march=i486, the compiler is
267 allowed to generate instructions that are valid on i486 and later processors,
268 but which may not exist on earlier ones.
270 .SS Code Generation Options
273 .B \-O0, \-O1, \-O2, \-O3, \-Ofast, \-Os, \-Oz, \-O, \-O4
274 Specify which optimization level to use:
277 \fI\%\-O0\fP Means "no optimization": this level compiles the fastest and
278 generates the most debuggable code.
280 \fI\%\-O1\fP Somewhere between \fI\%\-O0\fP and \fI\%\-O2\fP\&.
282 \fI\%\-O2\fP Moderate level of optimization which enables most
285 \fI\%\-O3\fP Like \fI\%\-O2\fP, except that it enables optimizations that
286 take longer to perform or that may generate larger code (in an attempt to
287 make the program run faster).
289 \fI\%\-Ofast\fP Enables all the optimizations from \fI\%\-O3\fP along
290 with other aggressive optimizations that may violate strict compliance with
293 \fI\%\-Os\fP Like \fI\%\-O2\fP with extra optimizations to reduce code
296 \fI\%\-Oz\fP Like \fI\%\-Os\fP (and thus \fI\%\-O2\fP), but reduces code
299 \fI\%\-O\fP Equivalent to \fI\%\-O2\fP\&.
301 \fI\%\-O4\fP and higher
304 Currently equivalent to \fI\%\-O3\fP
313 Generate debug information. Note that Clang debug information works best at \-O0.
318 Generate debug information that contains external references to
319 types defined in clang modules or precompiled headers instead of
320 emitting redundant debug type information into every object file.
321 This option implies \fB\-fmodule\-format=obj\fP\&.
323 This option should not be used when building static libraries for
324 distribution to other machines because the debug info will contain
325 references to the module cache on the machine the object files in
326 the library were built on.
330 .B \-fstandalone\-debug \-fno\-standalone\-debug
331 Clang supports a number of optimizations to reduce the size of debug
332 information in the binary. They work based on the assumption that the
333 debug type information can be spread out over multiple compilation units.
334 For instance, Clang will not emit type definitions for types that are not
335 needed by a module and could be replaced with a forward declaration.
336 Further, Clang will only emit type info for a dynamic C++ class in the
337 module that contains the vtable for the class.
339 The \fB\-fstandalone\-debug\fP option turns off these optimizations.
340 This is useful when working with 3rd\-party libraries that don\(aqt come with
341 debug information. This is the default on Darwin. Note that Clang will
342 never emit type information for types that are not referenced at all by the
348 Enable generation of unwind information. This allows exceptions to be thrown
349 through Clang compiled stack frames. This is on by default in x86\-64.
354 Generate code to catch integer overflow errors. Signed integer overflow is
355 undefined in C. With this flag, extra code is generated to detect this and
356 abort when it happens.
361 This flag sets the default visibility level.
366 This flag specifies that variables without initializers get common linkage.
367 It can be disabled with \fB\-fno\-common\fP\&.
371 .B \-ftls\-model=<model>
372 Set the default thread\-local storage (TLS) model to use for thread\-local
373 variables. Valid values are: "global\-dynamic", "local\-dynamic",
374 "initial\-exec" and "local\-exec". The default is "global\-dynamic". The default
375 model can be overridden with the tls_model attribute. The compiler will try
376 to choose a more efficient model if possible.
380 .B \-flto, \-emit\-llvm
381 Generate output files in LLVM formats, suitable for link time optimization.
382 When used with \fI\%\-S\fP this generates LLVM intermediate language
383 assembly files, otherwise this generates LLVM bitcode format object files
384 (which may be passed to the linker depending on the stage selection options).
390 Print (but do not run) the commands to run for this compilation.
395 Display available options.
399 .B \-Qunused\-arguments
400 Do not emit any warnings for unused driver arguments.
405 Pass the comma separated arguments in args to the assembler.
410 Pass the comma separated arguments in args to the linker.
415 Pass the comma separated arguments in args to the preprocessor.
420 Pass arg to the static analyzer.
424 .B \-Xassembler <arg>
425 Pass arg to the assembler.
430 Pass arg to the linker.
434 .B \-Xpreprocessor <arg>
435 Pass arg to the preprocessor.
440 Write output to file.
444 .B \-print\-file\-name=<file>
445 Print the full library path of file.
449 .B \-print\-libgcc\-file\-name
450 Print the library path for "libgcc.a".
454 .B \-print\-prog\-name=<name>
455 Print the full program path of name.
459 .B \-print\-search\-dirs
460 Print the paths used for finding libraries and programs.
465 Save intermediate compilation results.
469 .B \-integrated\-as, \-no\-integrated\-as
470 Used to enable and disable, respectively, the use of the integrated
471 assembler. Whether the integrated assembler is on by default is target
477 Time individual commands.
482 Print timing summary of each stage of compilation.
487 Show commands to run and use verbose output.
489 .SS Diagnostics Options
492 .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
493 These options control how Clang prints out information about diagnostics
494 (errors and warnings). Please see the Clang User\(aqs Manual for more information.
496 .SS Preprocessor Options
499 .B \-D<macroname>=<value>
500 Adds an implicit #define into the predefines buffer which is read before the
501 source file is preprocessed.
506 Adds an implicit #undef into the predefines buffer which is read before the
507 source file is preprocessed.
511 .B \-include <filename>
512 Adds an implicit #include into the predefines buffer which is read before the
513 source file is preprocessed.
518 Add the specified directory to the search path for include files.
523 Add the specified directory to the search path for framework include files.
528 Do not search the standard system directories or compiler builtin directories
534 Do not search the standard system directories for include files, but do
535 search compiler builtin include directories.
540 Do not search clang\(aqs builtin directory for include files.
546 These environment variables are checked, in order, for the location to write
547 temporary files used during the compilation process.
552 If this environment variable is present, it is treated as a delimited list of
553 paths to be added to the default system include path list. The delimiter is
554 the platform dependent delimiter, as used in the PATH environment variable.
556 Empty components in the environment variable are ignored.
560 .B C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH
561 These environment variables specify additional paths, as for \fI\%CPATH\fP, which are
562 only used when processing the appropriate language.
566 .B MACOSX_DEPLOYMENT_TARGET
567 If \fI\%\-mmacosx\-version\-min\fP is unspecified, the default deployment
568 target is read from this environment variable. This option only affects
573 To report bugs, please visit <\fI\%http://llvm.org/bugs/\fP>. Most bug reports should
574 include preprocessed source files (use the \fI\%\-E\fP option) and the full
575 output of the compiler, along with information to reproduce.
578 \fIas(1)\fP, \fIld(1)\fP
580 Maintained by the Clang / LLVM Team (<http://clang.llvm.org>)
582 2007-2016, The Clang Team
583 .\" Generated by docutils manpage writer.