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
16 important 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,
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
25 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
32 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
41 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
48 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
53 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
58 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
62 Clang Static Analyzer
63
64 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
74 -fsyntax-only
75 Run the preprocessor, parser and type checking stages.
76
77 -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
81 -c Run all of the above, plus the assembler, generating a target
82 ".o" object file.
83
84 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
89 Language Selection and Mode Options
90 -x <language>
91 Treat subsequent input files as having type language.
92
93 -std=<standard>
94 Specify the language standard to compile for.
95
96 Supported values for the C language are:
97 c89
98 c90
99 iso9899:1990
100
101 ISO C 1990
102 iso9899:199409
103
104 ISO C 1990 with amendment 1
105 gnu89
106 gnu90
107
108 ISO C 1990 with GNU extensions
109 c99
110 iso9899:1999
111
112 ISO C 1999
113 gnu99
114
115 ISO C 1999 with GNU extensions
116 c11
117 iso9899:2011
118
119 ISO C 2011
120 gnu11
121
122 ISO C 2011 with GNU extensions
123 c17
124 iso9899:2017
125
126 ISO C 2017
127 gnu17
128
129 ISO C 2017 with GNU extensions
130
131 The default C language standard is gnu11, except on PS4, where
132 it is gnu99.
133
134 Supported values for the C++ language are:
135 c++98
136 c++03
137
138 ISO C++ 1998 with amendments
139 gnu++98
140 gnu++03
141
142 ISO C++ 1998 with amendments and GNU extensions
143 c++11
144
145 ISO C++ 2011 with amendments
146 gnu++11
147
148 ISO C++ 2011 with amendments and GNU extensions
149 c++14
150
151 ISO C++ 2014 with amendments
152 gnu++14
153
154 ISO C++ 2014 with amendments and GNU extensions
155 c++17
156
157 ISO C++ 2017 with amendments
158 gnu++17
159
160 ISO C++ 2017 with amendments and GNU extensions
161 c++2a
162
163 Working draft for ISO C++ 2020
164 gnu++2a
165
166 Working draft for ISO C++ 2020 with GNU extensions
167
168 The default C++ language standard is gnu++14.
169
170 Supported values for the OpenCL language are:
171 cl1.0
172
173 OpenCL 1.0
174 cl1.1
175
176 OpenCL 1.1
177 cl1.2
178
179 OpenCL 1.2
180 cl2.0
181
182 OpenCL 2.0
183
184 The default OpenCL language standard is cl1.0.
185
186 Supported values for the CUDA language are:
187 cuda
188
189 NVIDIA CUDA(tm)
190
191 -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
196 -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
201 -ansi Same as -std=c89.
202
203 -ObjC, -ObjC++
204 Treat source input files as Objective-C and Object-C++ inputs
205 respectively.
206
207 -trigraphs
208 Enable trigraphs.
209
210 -ffreestanding
211 Indicate that the file should be compiled for a freestanding,
212 not a hosted, environment.
213
214 -fno-builtin
215 Disable special handling and optimizations of builtin functions
216 like strlen() and malloc().
217
218 -fmath-errno
219 Indicate that math functions should be treated as updating
220 errno.
221
222 -fpascal-strings
223 Enable support for Pascal-style strings with "\pfoo".
224
225 -fms-extensions
226 Enable support for Microsoft extensions.
227
228 -fmsc-version=
229 Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise.
230
231 -fborland-extensions
232 Enable support for Borland extensions.
233
234 -fwritable-strings
235 Make all string literals default to writable. This disables
236 uniquing of strings and other optimizations.
237
238 -flax-vector-conversions
239 Allow loose type checking rules for implicit vector conversions.
240
241 -fblocks
242 Enable the "Blocks" language feature.
243
244 -fobjc-abi-version=version
245 Select the Objective-C ABI version to use. Available versions
246 are 1 (legacy "fragile" ABI), 2 (non-fragile ABI 1), and 3
247 (non-fragile ABI 2).
248
249 -fobjc-nonfragile-abi-version=<version>
250 Select the Objective-C non-fragile ABI version to use by
251 default. This will only be used as the Objective-C ABI when the
252 non-fragile ABI is enabled (either via -fobjc-nonfragile-abi, or
253 because it is the platform default).
254
255 -fobjc-nonfragile-abi, -fno-objc-nonfragile-abi
256 Enable use of the Objective-C non-fragile ABI. On platforms for
257 which this is the default ABI, it can be disabled with
258 -fno-objc-nonfragile-abi.
259
260 Target Selection Options
261 Clang fully supports cross compilation as an inherent part of its
262 design. Depending on how your version of Clang is configured, it may
263 have support for a number of cross compilers, or may only support a
264 native target.
265
266 -arch <architecture>
267 Specify the architecture to build for.
268
269 -mmacosx-version-min=<version>
270 When building for Mac OS X, specify the minimum version sup‐
271 ported by your application.
272
273 -miphoneos-version-min
274 When building for iPhone OS, specify the minimum version sup‐
275 ported by your application.
276
277 -march=<cpu>
278 Specify that Clang should generate code for a specific processor
279 family member and later. For example, if you specify
280 -march=i486, the compiler is allowed to generate instructions
281 that are valid on i486 and later processors, but which may not
282 exist on earlier ones.
283
284 Code Generation Options
285 -O0, -O1, -O2, -O3, -Ofast, -Os, -Oz, -Og, -O, -O4
286 Specify which optimization level to use:
287 -O0 Means "no optimization": this level compiles the fastest
288 and generates the most debuggable code.
289
290 -O1 Somewhere between -O0 and -O2.
291
292 -O2 Moderate level of optimization which enables most opti‐
293 mizations.
294
295 -O3 Like -O2, except that it enables optimizations that take
296 longer to perform or that may generate larger code (in an
297 attempt to make the program run faster).
298
299 -Ofast Enables all the optimizations from -O3 along with
300 other aggressive optimizations that may violate strict com‐
301 pliance with language standards.
302
303 -Os Like -O2 with extra optimizations to reduce code size.
304
305 -Oz Like -Os (and thus -O2), but reduces code size further.
306
307 -Og Like -O1. In future versions, this option might disable
308 different optimizations in order to improve debuggability.
309
310 -O Equivalent to -O2.
311
312 -O4 and higher
313 Currently equivalent to -O3
314
315 -g, -gline-tables-only, -gmodules
316 Control debug information output. Note that Clang debug infor‐
317 mation works best at -O0. When more than one option starting
318 with -g is specified, the last one wins:
319 -g Generate debug information.
320
321 -gline-tables-only Generate only line table debug informa‐
322 tion. This allows for symbolicated backtraces with inlining
323 information, but does not include any information about vari‐
324 ables, their locations or types.
325
326 -gmodules Generate debug information that contains external
327 references to types defined in Clang modules or precompiled
328 headers instead of emitting redundant debug type information
329 into every object file. This option transparently switches
330 the Clang module format to object file containers that hold
331 the Clang module together with the debug information. When
332 compiling a program that uses Clang modules or precompiled
333 headers, this option produces complete debug information with
334 faster compile times and much smaller object files.
335
336 This option should not be used when building static libraries
337 for distribution to other machines because the debug info
338 will contain references to the module cache on the machine
339 the object files in the library were built on.
340
341 -fstandalone-debug -fno-standalone-debug
342 Clang supports a number of optimizations to reduce the size of
343 debug information in the binary. They work based on the assump‐
344 tion that the debug type information can be spread out over mul‐
345 tiple compilation units. For instance, Clang will not emit type
346 definitions for types that are not needed by a module and could
347 be replaced with a forward declaration. Further, Clang will
348 only emit type info for a dynamic C++ class in the module that
349 contains the vtable for the class.
350
351 The -fstandalone-debug option turns off these optimizations.
352 This is useful when working with 3rd-party libraries that don't
353 come with debug information. This is the default on Darwin.
354 Note that Clang will never emit type information for types that
355 are not referenced at all by the program.
356
357 -fexceptions
358 Enable generation of unwind information. This allows exceptions
359 to be thrown through Clang compiled stack frames. This is on by
360 default in x86-64.
361
362 -ftrapv
363 Generate code to catch integer overflow errors. Signed integer
364 overflow is undefined in C. With this flag, extra code is gener‐
365 ated to detect this and abort when it happens.
366
367 -fvisibility
368 This flag sets the default visibility level.
369
370 -fcommon, -fno-common
371 This flag specifies that variables without initializers get com‐
372 mon linkage. It can be disabled with -fno-common.
373
374 -ftls-model=<model>
375 Set the default thread-local storage (TLS) model to use for
376 thread-local variables. Valid values are: "global-dynamic",
377 "local-dynamic", "initial-exec" and "local-exec". The default is
378 "global-dynamic". The default model can be overridden with the
379 tls_model attribute. The compiler will try to choose a more
380 efficient model if possible.
381
382 -flto, -flto=full, -flto=thin, -emit-llvm
383 Generate output files in LLVM formats, suitable for link time
384 optimization. When used with -S this generates LLVM intermedi‐
385 ate language assembly files, otherwise this generates LLVM bit‐
386 code format object files (which may be passed to the linker
387 depending on the stage selection options).
388
389 The default for -flto is "full", in which the LLVM bitcode is
390 suitable for monolithic Link Time Optimization (LTO), where the
391 linker merges all such modules into a single combined module for
392 optimization. With "thin", ThinLTO compilation is invoked
393 instead.
394
395 Driver Options
396 -### Print (but do not run) the commands to run for this compilation.
397
398 --help Display available options.
399
400 -Qunused-arguments
401 Do not emit any warnings for unused driver arguments.
402
403 -Wa,<args>
404 Pass the comma separated arguments in args to the assembler.
405
406 -Wl,<args>
407 Pass the comma separated arguments in args to the linker.
408
409 -Wp,<args>
410 Pass the comma separated arguments in args to the preprocessor.
411
412 -Xanalyzer <arg>
413 Pass arg to the static analyzer.
414
415 -Xassembler <arg>
416 Pass arg to the assembler.
417
418 -Xlinker <arg>
419 Pass arg to the linker.
420
421 -Xpreprocessor <arg>
422 Pass arg to the preprocessor.
423
424 -o <file>
425 Write output to file.
426
427 -print-file-name=<file>
428 Print the full library path of file.
429
430 -print-libgcc-file-name
431 Print the library path for the currently used compiler runtime
432 library ("libgcc.a" or "libclang_rt.builtins.*.a").
433
434 -print-prog-name=<name>
435 Print the full program path of name.
436
437 -print-search-dirs
438 Print the paths used for finding libraries and programs.
439
440 -save-temps
441 Save intermediate compilation results.
442
443 -save-stats, -save-stats=cwd, -save-stats=obj
444 Save internal code generation (LLVM) statistics to a file in the
445 current directory (-save-stats/"-save-stats=cwd") or the direc‐
446 tory of the output file ("-save-state=obj").
447
448 -integrated-as, -no-integrated-as
449 Used to enable and disable, respectively, the use of the inte‐
450 grated assembler. Whether the integrated assembler is on by
451 default is target dependent.
452
453 -time Time individual commands.
454
455 -ftime-report
456 Print timing summary of each stage of compilation.
457
458 -v Show commands to run and use verbose output.
459
460 Diagnostics Options
461 -fshow-column, -fshow-source-location, -fcaret-diagnostics, -fdiagnos‐
462 tics-fixit-info, -fdiagnostics-parseable-fixits, -fdiagnos‐
463 tics-print-source-range-info, -fprint-source-range-info, -fdiagnos‐
464 tics-show-option, -fmessage-length
465 These options control how Clang prints out information about
466 diagnostics (errors and warnings). Please see the Clang User's
467 Manual for more information.
468
469 Preprocessor Options
470 -D<macroname>=<value>
471 Adds an implicit #define into the predefines buffer which is
472 read before the source file is preprocessed.
473
474 -U<macroname>
475 Adds an implicit #undef into the predefines buffer which is read
476 before the source file is preprocessed.
477
478 -include <filename>
479 Adds an implicit #include into the predefines buffer which is
480 read before the source file is preprocessed.
481
482 -I<directory>
483 Add the specified directory to the search path for include
484 files.
485
486 -F<directory>
487 Add the specified directory to the search path for framework
488 include files.
489
490 -nostdinc
491 Do not search the standard system directories or compiler
492 builtin directories for include files.
493
494 -nostdlibinc
495 Do not search the standard system directories for include files,
496 but do search compiler builtin include directories.
497
498 -nobuiltininc
499 Do not search clang's builtin directory for include files.
500
502 TMPDIR, TEMP, TMP
503 These environment variables are checked, in order, for the loca‐
504 tion to write temporary files used during the compilation
505 process.
506
507 CPATH If this environment variable is present, it is treated as a
508 delimited list of paths to be added to the default system
509 include path list. The delimiter is the platform dependent
510 delimiter, as used in the PATH environment variable.
511
512 Empty components in the environment variable are ignored.
513
514 C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJC‐
515 PLUS_INCLUDE_PATH
516 These environment variables specify additional paths, as for
517 CPATH, which are only used when processing the appropriate lan‐
518 guage.
519
520 MACOSX_DEPLOYMENT_TARGET
521 If -mmacosx-version-min is unspecified, the default deployment
522 target is read from this environment variable. This option only
523 affects Darwin targets.
524
526 To report bugs, please visit <https://bugs.llvm.org/>. Most bug
527 reports should include preprocessed source files (use the -E option)
528 and the full output of the compiler, along with information to repro‐
529 duce.
530
532 as(1), ld(1)
533
535 Maintained by the Clang / LLVM Team (<http://clang.llvm.org>)
536
538 2007-2019, The Clang Team
539
540
541
542
5438 Mar 26, 2019 CLANG(1)