1CLANG(1) Clang CLANG(1)
2
6 clang - the Clang C, C++, and Objective-C compiler
7
9 clang [options] filename ...
10
12 clang is a C, C++, and Objective-C compiler which encompasses prepro‐
13 cessing, parsing, optimization, code generation, assembly, and linking.
14 Depending on which high-level mode setting is passed, Clang will stop
15 before doing a full link. While Clang is highly integrated, it is
16 important to understand the stages of compilation, to understand how to
17 invoke it. These stages are:
18 Driver The clang executable is actually a small driver which controls
20 the overall execution of other tools such as the compiler,
21 assembler and linker. Typically you do not need to interact
22 with the driver, but you transparently use it to run the other
23 tools.
24 Preprocessing
26 This stage handles tokenization of the input source file, macro
27 expansion, #include expansion and handling of other preprocessor
28 directives. The output of this stage is typically called a ".i"
29 (for C), ".ii" (for C++), ".mi" (for Objective-C), or ".mii"
30 (for Objective-C++) file.
31 Parsing and Semantic Analysis
33 This stage parses the input file, translating preprocessor
34 tokens into a parse tree. Once in the form of a parse tree, it
35 applies semantic analysis to compute types for expressions as
36 well and determine whether the code is well formed. This stage
37 is responsible for generating most of the compiler warnings as
38 well as parse errors. The output of this stage is an "Abstract
39 Syntax Tree" (AST).
40 Code Generation and Optimization
42 This stage translates an AST into low-level intermediate code
43 (known as "LLVM IR") and ultimately to machine code. This phase
44 is responsible for optimizing the generated code and handling
45 target-specific code generation. The output of this stage is
46 typically called a ".s" file or "assembly" file.
47 Clang also supports the use of an integrated assembler, in which
49 the code generator produces object files directly. This avoids
50 the overhead of generating the ".s" file and of calling the tar‐
51 get assembler.
52 Assembler
54 This stage runs the target assembler to translate the output of
55 the compiler into a target object file. The output of this stage
56 is typically called a ".o" file or "object" file.
57 Linker This stage runs the target linker to merge multiple object files
59 into an executable or dynamic library. The output of this stage
60 is typically called an "a.out", ".dylib" or ".so" file.
61 Clang Static Analyzer
63 The Clang Static Analyzer is a tool that scans source code to try to
65 find bugs through code analysis. This tool uses many parts of Clang
66 and is built into the same driver. Please see <‐
67 https://clang-analyzer.llvm.org> for more details on how to use the
68 static analyzer.
69
71 Stage Selection Options
72 -E Run the preprocessor stage.
73 -fsyntax-only
75 Run the preprocessor, parser and type checking stages.
76 -S Run the previous stages as well as LLVM generation and optimiza‐
78 tion stages and target-specific code generation, producing an
79 assembly file.
80 -c Run all of the above, plus the assembler, generating a target
82 ".o" object file.
83 no stage selection option
85 If no stage selection option is specified, all stages above are
86 run, and the linker is run to combine the results into an exe‐
87 cutable or shared library.
88 Language Selection and Mode Options
90 -x <language>
91 Treat subsequent input files as having type language.
92 -std=<standard>
94 Specify the language standard to compile for.
95 Supported values for the C language are:
97 c89
98 c90
99 iso9899:1990
100 ISO C 1990
102 iso9899:199409
103 ISO C 1990 with amendment 1
105 gnu89
106 gnu90
107 ISO C 1990 with GNU extensions
109 c99
110 iso9899:1999
111 ISO C 1999
113 gnu99
114 ISO C 1999 with GNU extensions
116 c11
117 iso9899:2011
118 ISO C 2011
120 gnu11
121 ISO C 2011 with GNU extensions
123 c17
124 iso9899:2017
125 ISO C 2017
127 gnu17
128 ISO C 2017 with GNU extensions
130 The default C language standard is gnu17, except on PS4, where
132 it is gnu99.
133 Supported values for the C++ language are:
135 c++98
136 c++03
137 ISO C++ 1998 with amendments
139 gnu++98
140 gnu++03
141 ISO C++ 1998 with amendments and GNU extensions
143 c++11
144 ISO C++ 2011 with amendments
146 gnu++11
147 ISO C++ 2011 with amendments and GNU extensions
149 c++14
150 ISO C++ 2014 with amendments
152 gnu++14
153 ISO C++ 2014 with amendments and GNU extensions
155 c++17
156 ISO C++ 2017 with amendments
158 gnu++17
159 ISO C++ 2017 with amendments and GNU extensions
161 c++2a
162 Working draft for ISO C++ 2020
164 gnu++2a
165 Working draft for ISO C++ 2020 with GNU extensions
167 The default C++ language standard is gnu++14.
169 Supported values for the OpenCL language are:
171 cl1.0
172 OpenCL 1.0
174 cl1.1
175 OpenCL 1.1
177 cl1.2
178 OpenCL 1.2
180 cl2.0
181 OpenCL 2.0
183 The default OpenCL language standard is cl1.0.
185 Supported values for the CUDA language are:
187 cuda
188 NVIDIA CUDA(tm)
190 -stdlib=<library>
192 Specify the C++ standard library to use; supported options are
193 libstdc++ and libc++. If not specified, platform default will be
194 used.
195 -rtlib=<library>
197 Specify the compiler runtime library to use; supported options
198 are libgcc and compiler-rt. If not specified, platform default
199 will be used.
200 -ansi Same as -std=c89.
202 -ObjC, -ObjC++
204 Treat source input files as Objective-C and Object-C++ inputs
205 respectively.
206 -trigraphs
208 Enable trigraphs.
209 -ffreestanding
211 Indicate that the file should be compiled for a freestanding,
212 not a hosted, environment. Note that it is assumed that a free‐
213 standing environment will additionally provide memcpy, memmove,
214 memset and memcmp implementations, as these are needed for effi‐
215 cient codegen for many programs.
216 -fno-builtin
218 Disable special handling and optimizations of builtin functions
219 like strlen() and malloc().
220 -fmath-errno
222 Indicate that math functions should be treated as updating
223 errno.
224 -fpascal-strings
226 Enable support for Pascal-style strings with "\pfoo".
227 -fms-extensions
229 Enable support for Microsoft extensions.
230 -fmsc-version=
232 Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise.
233 -fborland-extensions
235 Enable support for Borland extensions.
236 -fwritable-strings
238 Make all string literals default to writable. This disables
239 uniquing of strings and other optimizations.
240 -flax-vector-conversions, -flax-vector-conversions=<kind>,
242 -fno-lax-vector-conversions
243 Allow loose type checking rules for implicit vector conversions.
244 Possible values of <kind>:
245 · none: allow no implicit conversions between vectors
247 · integer: allow implicit bitcasts between integer vectors of
249 the same overall bit-width
250 · all: allow implicit bitcasts between any vectors of the same
252 overall bit-width
253 <kind> defaults to integer if unspecified.
255 -fblocks
257 Enable the "Blocks" language feature.
258 -fobjc-abi-version=version
260 Select the Objective-C ABI version to use. Available versions
261 are 1 (legacy "fragile" ABI), 2 (non-fragile ABI 1), and 3
262 (non-fragile ABI 2).
263 -fobjc-nonfragile-abi-version=<version>
265 Select the Objective-C non-fragile ABI version to use by
266 default. This will only be used as the Objective-C ABI when the
267 non-fragile ABI is enabled (either via -fobjc-nonfragile-abi, or
268 because it is the platform default).
269 -fobjc-nonfragile-abi, -fno-objc-nonfragile-abi
271 Enable use of the Objective-C non-fragile ABI. On platforms for
272 which this is the default ABI, it can be disabled with
273 -fno-objc-nonfragile-abi.
274 Target Selection Options
276 Clang fully supports cross compilation as an inherent part of its
277 design. Depending on how your version of Clang is configured, it may
278 have support for a number of cross compilers, or may only support a
279 native target.
280 -arch <architecture>
282 Specify the architecture to build for.
283 -mmacosx-version-min=<version>
285 When building for macOS, specify the minimum version supported
286 by your application.
287 -miphoneos-version-min
289 When building for iPhone OS, specify the minimum version sup‐
290 ported by your application.
291 --print-supported-cpus
293 Print out a list of supported processors for the given target
294 (specified through --target=<architecture> or -arch <architec‐
295 ture>). If no target is specified, the system default target
296 will be used.
297 -mcpu=?, -mtune=?
299 Aliases of --print-supported-cpus
300 -march=<cpu>
302 Specify that Clang should generate code for a specific processor
303 family member and later. For example, if you specify
304 -march=i486, the compiler is allowed to generate instructions
305 that are valid on i486 and later processors, but which may not
306 exist on earlier ones.
307 Code Generation Options
309 -O0, -O1, -O2, -O3, -Ofast, -Os, -Oz, -Og, -O, -O4
310 Specify which optimization level to use:
311 -O0 Means "no optimization": this level compiles the fastest
312 and generates the most debuggable code.
313 -O1 Somewhere between -O0 and -O2.
315 -O2 Moderate level of optimization which enables most opti‐
317 mizations.
318 -O3 Like -O2, except that it enables optimizations that take
320 longer to perform or that may generate larger code (in an
321 attempt to make the program run faster).
322 -Ofast Enables all the optimizations from -O3 along with
324 other aggressive optimizations that may violate strict com‐
325 pliance with language standards.
326 -Os Like -O2 with extra optimizations to reduce code size.
328 -Oz Like -Os (and thus -O2), but reduces code size further.
330 -Og Like -O1. In future versions, this option might disable
332 different optimizations in order to improve debuggability.
333 -O Equivalent to -O1.
335 -O4 and higher
337 Currently equivalent to -O3
338 -g, -gline-tables-only, -gmodules
340 Control debug information output. Note that Clang debug infor‐
341 mation works best at -O0. When more than one option starting
342 with -g is specified, the last one wins:
343 -g Generate debug information.
344 -gline-tables-only Generate only line table debug informa‐
346 tion. This allows for symbolicated backtraces with inlining
347 information, but does not include any information about vari‐
348 ables, their locations or types.
349 -gmodules Generate debug information that contains external
351 references to types defined in Clang modules or precompiled
352 headers instead of emitting redundant debug type information
353 into every object file. This option transparently switches
354 the Clang module format to object file containers that hold
355 the Clang module together with the debug information. When
356 compiling a program that uses Clang modules or precompiled
357 headers, this option produces complete debug information with
358 faster compile times and much smaller object files.
359 This option should not be used when building static libraries
361 for distribution to other machines because the debug info
362 will contain references to the module cache on the machine
363 the object files in the library were built on.
364 -fstandalone-debug -fno-standalone-debug
366 Clang supports a number of optimizations to reduce the size of
367 debug information in the binary. They work based on the assump‐
368 tion that the debug type information can be spread out over mul‐
369 tiple compilation units. For instance, Clang will not emit type
370 definitions for types that are not needed by a module and could
371 be replaced with a forward declaration. Further, Clang will
372 only emit type info for a dynamic C++ class in the module that
373 contains the vtable for the class.
374 The -fstandalone-debug option turns off these optimizations.
376 This is useful when working with 3rd-party libraries that don't
377 come with debug information. This is the default on Darwin.
378 Note that Clang will never emit type information for types that
379 are not referenced at all by the program.
380 -fexceptions
382 Enable generation of unwind information. This allows exceptions
383 to be thrown through Clang compiled stack frames. This is on by
384 default in x86-64.
385 -ftrapv
387 Generate code to catch integer overflow errors. Signed integer
388 overflow is undefined in C. With this flag, extra code is gener‐
389 ated to detect this and abort when it happens.
390 -fvisibility
392 This flag sets the default visibility level.
393 -fcommon, -fno-common
395 This flag specifies that variables without initializers get com‐
396 mon linkage. It can be disabled with -fno-common.
397 -ftls-model=<model>
399 Set the default thread-local storage (TLS) model to use for
400 thread-local variables. Valid values are: "global-dynamic",
401 "local-dynamic", "initial-exec" and "local-exec". The default is
402 "global-dynamic". The default model can be overridden with the
403 tls_model attribute. The compiler will try to choose a more
404 efficient model if possible.
405 -flto, -flto=full, -flto=thin, -emit-llvm
407 Generate output files in LLVM formats, suitable for link time
408 optimization. When used with -S this generates LLVM intermedi‐
409 ate language assembly files, otherwise this generates LLVM bit‐
410 code format object files (which may be passed to the linker
411 depending on the stage selection options).
412 The default for -flto is "full", in which the LLVM bitcode is
414 suitable for monolithic Link Time Optimization (LTO), where the
415 linker merges all such modules into a single combined module for
416 optimization. With "thin", ThinLTO compilation is invoked
417 instead.
418 NOTE:
420 On Darwin, when using -flto along with -g and compiling and
421 linking in separate steps, you also need to pass
422 -Wl,-object_path_lto,<lto-filename>.o at the linking step to
423 instruct the ld64 linker not to delete the temporary object
424 file generated during Link Time Optimization (this flag is
425 automatically passed to the linker by Clang if compilation
426 and linking are done in a single step). This allows debugging
427 the executable as well as generating the .dSYM bundle using
428 dsymutil(1).
429 Driver Options
431 -### Print (but do not run) the commands to run for this compilation.
432 --help Display available options.
434 -Qunused-arguments
436 Do not emit any warnings for unused driver arguments.
437 -Wa,<args>
439 Pass the comma separated arguments in args to the assembler.
440 -Wl,<args>
442 Pass the comma separated arguments in args to the linker.
443 -Wp,<args>
445 Pass the comma separated arguments in args to the preprocessor.
446 -Xanalyzer <arg>
448 Pass arg to the static analyzer.
449 -Xassembler <arg>
451 Pass arg to the assembler.
452 -Xlinker <arg>
454 Pass arg to the linker.
455 -Xpreprocessor <arg>
457 Pass arg to the preprocessor.
458 -o <file>
460 Write output to file.
461 -print-file-name=<file>
463 Print the full library path of file.
464 -print-libgcc-file-name
466 Print the library path for the currently used compiler runtime
467 library ("libgcc.a" or "libclang_rt.builtins.*.a").
468 -print-prog-name=<name>
470 Print the full program path of name.
471 -print-search-dirs
473 Print the paths used for finding libraries and programs.
474 -save-temps
476 Save intermediate compilation results.
477 -save-stats, -save-stats=cwd, -save-stats=obj
479 Save internal code generation (LLVM) statistics to a file in the
480 current directory (-save-stats/"-save-stats=cwd") or the direc‐
481 tory of the output file ("-save-state=obj").
482 -integrated-as, -no-integrated-as
484 Used to enable and disable, respectively, the use of the inte‐
485 grated assembler. Whether the integrated assembler is on by
486 default is target dependent.
487 -time Time individual commands.
489 -ftime-report
491 Print timing summary of each stage of compilation.
492 -v Show commands to run and use verbose output.
494 Diagnostics Options
496 -fshow-column, -fshow-source-location, -fcaret-diagnostics, -fdiagnos‐
497 tics-fixit-info, -fdiagnostics-parseable-fixits, -fdiagnos‐
498 tics-print-source-range-info, -fprint-source-range-info, -fdiagnos‐
499 tics-show-option, -fmessage-length
500 These options control how Clang prints out information about
501 diagnostics (errors and warnings). Please see the Clang User's
502 Manual for more information.
503 Preprocessor Options
505 -D<macroname>=<value>
506 Adds an implicit #define into the predefines buffer which is
507 read before the source file is preprocessed.
508 -U<macroname>
510 Adds an implicit #undef into the predefines buffer which is read
511 before the source file is preprocessed.
512 -include <filename>
514 Adds an implicit #include into the predefines buffer which is
515 read before the source file is preprocessed.
516 -I<directory>
518 Add the specified directory to the search path for include
519 files.
520 -F<directory>
522 Add the specified directory to the search path for framework
523 include files.
524 -nostdinc
526 Do not search the standard system directories or compiler
527 builtin directories for include files.
528 -nostdlibinc
530 Do not search the standard system directories for include files,
531 but do search compiler builtin include directories.
532 -nobuiltininc
534 Do not search clang's builtin directory for include files.
535
537 TMPDIR, TEMP, TMP
538 These environment variables are checked, in order, for the loca‐
539 tion to write temporary files used during the compilation
540 process.
541 CPATH If this environment variable is present, it is treated as a
543 delimited list of paths to be added to the default system
544 include path list. The delimiter is the platform dependent
545 delimiter, as used in the PATH environment variable.
546 Empty components in the environment variable are ignored.
548 C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJC‐
550 PLUS_INCLUDE_PATH
551 These environment variables specify additional paths, as for
552 CPATH, which are only used when processing the appropriate lan‐
553 guage.
554 MACOSX_DEPLOYMENT_TARGET
556 If -mmacosx-version-min is unspecified, the default deployment
557 target is read from this environment variable. This option only
558 affects Darwin targets.
559
561 To report bugs, please visit <https://bugs.llvm.org/>. Most bug
562 reports should include preprocessed source files (use the -E option)
563 and the full output of the compiler, along with information to repro‐
564 duce.
565
567 as(1), ld(1)
568
570 Maintained by the Clang / LLVM Team (<http://clang.llvm.org>)
571
573 2007-2020, The Clang Team
57411 Oct 29, 2020 CLANG(1)