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