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 im‐
16 portant 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, 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 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 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 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 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 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 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 Clang Static Analyzer
62 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 -fsyntax-only
74 Run the preprocessor, parser and semantic analysis stages.
75 -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 -c Run all of the above, plus the assembler, generating a target
81 ".o" object file.
82 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 Language Selection and Mode Options
89 -x <language>
90 Treat subsequent input files as having type language.
91 -std=<standard>
93 Specify the language standard to compile for.
94 Supported values for the C language are:
96 c89
97 c90
98 iso9899:1990
99 ISO C 1990
101 iso9899:199409
102 ISO C 1990 with amendment 1
104 gnu89
105 gnu90
106 ISO C 1990 with GNU extensions
108 c99
109 iso9899:1999
110 ISO C 1999
112 gnu99
113 ISO C 1999 with GNU extensions
115 c11
116 iso9899:2011
117 ISO C 2011
119 gnu11
120 ISO C 2011 with GNU extensions
122 c17
123 iso9899:2017
124 ISO C 2017
126 gnu17
127 ISO C 2017 with GNU extensions
129 The default C language standard is gnu17, except on PS4, where
131 it is gnu99.
132 Supported values for the C++ language are:
134 c++98
135 c++03
136 ISO C++ 1998 with amendments
138 gnu++98
139 gnu++03
140 ISO C++ 1998 with amendments and GNU extensions
142 c++11
143 ISO C++ 2011 with amendments
145 gnu++11
146 ISO C++ 2011 with amendments and GNU extensions
148 c++14
149 ISO C++ 2014 with amendments
151 gnu++14
152 ISO C++ 2014 with amendments and GNU extensions
154 c++17
155 ISO C++ 2017 with amendments
157 gnu++17
158 ISO C++ 2017 with amendments and GNU extensions
160 c++20
161 ISO C++ 2020 with amendments
163 gnu++20
164 ISO C++ 2020 with amendments and GNU extensions
166 c++23
167 ISO C++ 2023 with amendments
169 gnu++23
170 ISO C++ 2023 with amendments and GNU extensions
172 c++2c
173 Working draft for C++2c
175 gnu++2c
176 Working draft for C++2c with GNU extensions
178 The default C++ language standard is gnu++17.
180 Supported values for the OpenCL language are:
182 cl1.0
183 OpenCL 1.0
185 cl1.1
186 OpenCL 1.1
188 cl1.2
189 OpenCL 1.2
191 cl2.0
192 OpenCL 2.0
194 The default OpenCL language standard is cl1.0.
196 Supported values for the CUDA language are:
198 cuda
199 NVIDIA CUDA(tm)
201 -stdlib=<library>
203 Specify the C++ standard library to use; supported options are
204 libstdc++ and libc++. If not specified, platform default will be
205 used.
206 -rtlib=<library>
208 Specify the compiler runtime library to use; supported options
209 are libgcc and compiler-rt. If not specified, platform default
210 will be used.
211 -ansi Same as -std=c89.
213 -ObjC, -ObjC++
215 Treat source input files as Objective-C and Object-C++ inputs
216 respectively.
217 -trigraphs
219 Enable trigraphs.
220 -ffreestanding
222 Indicate that the file should be compiled for a freestanding,
223 not a hosted, environment. Note that it is assumed that a free‐
224 standing environment will additionally provide memcpy, memmove,
225 memset and memcmp implementations, as these are needed for effi‐
226 cient codegen for many programs.
227 -fno-builtin
229 Disable special handling and optimizations of well-known library
230 functions, like strlen() and malloc().
231 -fno-builtin-<function>
233 Disable special handling and optimizations for the specific li‐
234 brary function. For example, -fno-builtin-strlen removes any
235 special handling for the strlen() library function.
236 -fno-builtin-std-<function>
238 Disable special handling and optimizations for the specific C++
239 standard library function in namespace std. For example,
240 -fno-builtin-std-move_if_noexcept removes any special handling
241 for the std::move_if_noexcept() library function.
242 For C standard library functions that the C++ standard library
244 also provides in namespace std, use -fno-builtin-<function> in‐
245 stead.
246 -fmath-errno
248 Indicate that math functions should be treated as updating er‐
249 rno.
250 -fpascal-strings
252 Enable support for Pascal-style strings with "\pfoo".
253 -fms-extensions
255 Enable support for Microsoft extensions.
256 -fmsc-version=
258 Set _MSC_VER. When on Windows, this defaults to either the same
259 value as the currently installed version of cl.exe, or 1920. Not
260 set otherwise.
261 -fborland-extensions
263 Enable support for Borland extensions.
264 -fwritable-strings
266 Make all string literals default to writable. This disables
267 uniquing of strings and other optimizations.
268 -flax-vector-conversions, -flax-vector-conversions=<kind>,
270 -fno-lax-vector-conversions
271 Allow loose type checking rules for implicit vector conversions.
272 Possible values of <kind>:
273 • none: allow no implicit conversions between vectors
275 • integer: allow implicit bitcasts between integer vectors of
277 the same overall bit-width
278 • all: allow implicit bitcasts between any vectors of the same
280 overall bit-width
281 <kind> defaults to integer if unspecified.
283 -fblocks
285 Enable the "Blocks" language feature.
286 -fobjc-abi-version=version
288 Select the Objective-C ABI version to use. Available versions
289 are 1 (legacy "fragile" ABI), 2 (non-fragile ABI 1), and 3
290 (non-fragile ABI 2).
291 -fobjc-nonfragile-abi-version=<version>
293 Select the Objective-C non-fragile ABI version to use by de‐
294 fault. This will only be used as the Objective-C ABI when the
295 non-fragile ABI is enabled (either via -fobjc-nonfragile-abi, or
296 because it is the platform default).
297 -fobjc-nonfragile-abi, -fno-objc-nonfragile-abi
299 Enable use of the Objective-C non-fragile ABI. On platforms for
300 which this is the default ABI, it can be disabled with
301 -fno-objc-nonfragile-abi.
302 Target Selection Options
304 Clang fully supports cross compilation as an inherent part of its de‐
305 sign. Depending on how your version of Clang is configured, it may
306 have support for a number of cross compilers, or may only support a na‐
307 tive target.
308 -arch <architecture>
310 Specify the architecture to build for (Mac OS X specific).
311 -target <architecture>
313 Specify the architecture to build for (all platforms).
314 -mmacosx-version-min=<version>
316 When building for macOS, specify the minimum version supported
317 by your application.
318 -miphoneos-version-min
320 When building for iPhone OS, specify the minimum version sup‐
321 ported by your application.
322 --print-supported-cpus
324 Print out a list of supported processors for the given target
325 (specified through --target=<architecture> or -arch <architec‐
326 ture>). If no target is specified, the system default target
327 will be used.
328 -mcpu=?, -mtune=?
330 Acts as an alias for --print-supported-cpus.
331 -mcpu=help, -mtune=help
333 Acts as an alias for --print-supported-cpus.
334 -march=<cpu>
336 Specify that Clang should generate code for a specific processor
337 family member and later. For example, if you specify
338 -march=i486, the compiler is allowed to generate instructions
339 that are valid on i486 and later processors, but which may not
340 exist on earlier ones.
341 Code Generation Options
343 -O0, -O1, -O2, -O3, -Ofast, -Os, -Oz, -Og, -O, -O4
344 Specify which optimization level to use:
345 -O0 Means "no optimization": this level compiles the fastest
346 and generates the most debuggable code.
347 -O1 Somewhere between -O0 and -O2.
349 -O2 Moderate level of optimization which enables most opti‐
351 mizations.
352 -O3 Like -O2, except that it enables optimizations that take
354 longer to perform or that may generate larger code (in an at‐
355 tempt to make the program run faster).
356 -Ofast Enables all the optimizations from -O3 along with
358 other aggressive optimizations that may violate strict com‐
359 pliance with language standards.
360 -Os Like -O2 with extra optimizations to reduce code size.
362 -Oz Like -Os (and thus -O2), but reduces code size further.
364 -Og Like -O1. In future versions, this option might disable
366 different optimizations in order to improve debuggability.
367 -O Equivalent to -O1.
369 -O4 and higher
371 Currently equivalent to -O3
372 -g, -gline-tables-only, -gmodules
374 Control debug information output. Note that Clang debug infor‐
375 mation works best at -O0. When more than one option starting
376 with -g is specified, the last one wins:
377 -g Generate debug information.
378 -gline-tables-only Generate only line table debug informa‐
380 tion. This allows for symbolicated backtraces with inlining
381 information, but does not include any information about vari‐
382 ables, their locations or types.
383 -gmodules Generate debug information that contains external
385 references to types defined in Clang modules or precompiled
386 headers instead of emitting redundant debug type information
387 into every object file. This option transparently switches
388 the Clang module format to object file containers that hold
389 the Clang module together with the debug information. When
390 compiling a program that uses Clang modules or precompiled
391 headers, this option produces complete debug information with
392 faster compile times and much smaller object files.
393 This option should not be used when building static libraries
395 for distribution to other machines because the debug info
396 will contain references to the module cache on the machine
397 the object files in the library were built on.
398 -fstandalone-debug -fno-standalone-debug
400 Clang supports a number of optimizations to reduce the size of
401 debug information in the binary. They work based on the assump‐
402 tion that the debug type information can be spread out over mul‐
403 tiple compilation units. For instance, Clang will not emit type
404 definitions for types that are not needed by a module and could
405 be replaced with a forward declaration. Further, Clang will
406 only emit type info for a dynamic C++ class in the module that
407 contains the vtable for the class.
408 The -fstandalone-debug option turns off these optimizations.
410 This is useful when working with 3rd-party libraries that don't
411 come with debug information. This is the default on Darwin.
412 Note that Clang will never emit type information for types that
413 are not referenced at all by the program.
414 -feliminate-unused-debug-types
416 By default, Clang does not emit type information for types that
417 are defined but not used in a program. To retain the debug info
418 for these unused types, the negation -fno-eliminate-unused-de‐
419 bug-types can be used.
420 -fexceptions
422 Allow exceptions to be thrown through Clang compiled stack
423 frames (on many targets, this will enable unwind information for
424 functions that might have an exception thrown through them). For
425 most targets, this is enabled by default for C++.
426 -ftrapv
428 Generate code to catch integer overflow errors. Signed integer
429 overflow is undefined in C. With this flag, extra code is gener‐
430 ated to detect this and abort when it happens.
431 -fvisibility
433 This flag sets the default visibility level.
434 -fcommon, -fno-common
436 This flag specifies that variables without initializers get com‐
437 mon linkage. It can be disabled with -fno-common.
438 -ftls-model=<model>
440 Set the default thread-local storage (TLS) model to use for
441 thread-local variables. Valid values are: "global-dynamic", "lo‐
442 cal-dynamic", "initial-exec" and "local-exec". The default is
443 "global-dynamic". The default model can be overridden with the
444 tls_model attribute. The compiler will try to choose a more ef‐
445 ficient model if possible.
446 -flto, -flto=full, -flto=thin, -emit-llvm
448 Generate output files in LLVM formats, suitable for link time
449 optimization. When used with -S this generates LLVM intermedi‐
450 ate language assembly files, otherwise this generates LLVM bit‐
451 code format object files (which may be passed to the linker de‐
452 pending on the stage selection options).
453 The default for -flto is "full", in which the LLVM bitcode is
455 suitable for monolithic Link Time Optimization (LTO), where the
456 linker merges all such modules into a single combined module for
457 optimization. With "thin", ThinLTO compilation is invoked in‐
458 stead.
459 NOTE:
461 On Darwin, when using -flto along with -g and compiling and
462 linking in separate steps, you also need to pass -Wl,-ob‐
463 ject_path_lto,<lto-filename>.o at the linking step to in‐
464 struct the ld64 linker not to delete the temporary object
465 file generated during Link Time Optimization (this flag is
466 automatically passed to the linker by Clang if compilation
467 and linking are done in a single step). This allows debugging
468 the executable as well as generating the .dSYM bundle using
469 dsymutil(1).
470 Driver Options
472 -### Print (but do not run) the commands to run for this compilation.
473 --help Display available options.
475 -Qunused-arguments
477 Do not emit any warnings for unused driver arguments.
478 -Wa,<args>
480 Pass the comma separated arguments in args to the assembler.
481 -Wl,<args>
483 Pass the comma separated arguments in args to the linker.
484 -Wp,<args>
486 Pass the comma separated arguments in args to the preprocessor.
487 -Xanalyzer <arg>
489 Pass arg to the static analyzer.
490 -Xassembler <arg>
492 Pass arg to the assembler.
493 -Xlinker <arg>
495 Pass arg to the linker.
496 -Xpreprocessor <arg>
498 Pass arg to the preprocessor.
499 -o <file>
501 Write output to file.
502 -print-file-name=<file>
504 Print the full library path of file.
505 -print-libgcc-file-name
507 Print the library path for the currently used compiler runtime
508 library ("libgcc.a" or "libclang_rt.builtins.*.a").
509 -print-prog-name=<name>
511 Print the full program path of name.
512 -print-search-dirs
514 Print the paths used for finding libraries and programs.
515 -save-temps
517 Save intermediate compilation results.
518 -save-stats, -save-stats=cwd, -save-stats=obj
520 Save internal code generation (LLVM) statistics to a file in the
521 current directory (-save-stats/"-save-stats=cwd") or the direc‐
522 tory of the output file ("-save-state=obj").
523 You can also use environment variables to control the statistics
525 reporting. Setting CC_PRINT_INTERNAL_STAT to 1 enables the fea‐
526 ture, the report goes to stdout in JSON format.
527 Setting CC_PRINT_INTERNAL_STAT_FILE to a file path makes it re‐
529 port statistics to the given file in the JSON format.
530 Note that -save-stats take precedence over CC_PRINT_INTER‐
532 NAL_STAT and CC_PRINT_INTERNAL_STAT_FILE.
533 -integrated-as, -no-integrated-as
535 Used to enable and disable, respectively, the use of the inte‐
536 grated assembler. Whether the integrated assembler is on by de‐
537 fault is target dependent.
538 -time Time individual commands.
540 -ftime-report
542 Print timing summary of each stage of compilation.
543 -v Show commands to run and use verbose output.
545 Diagnostics Options
547 -fshow-column, -fshow-source-location, -fcaret-diagnostics, -fdiagnos‐
548 tics-fixit-info, -fdiagnostics-parseable-fixits, -fdiagnos‐
549 tics-print-source-range-info, -fprint-source-range-info, -fdiagnos‐
550 tics-show-option, -fmessage-length
551 These options control how Clang prints out information about di‐
552 agnostics (errors and warnings). Please see the Clang User's
553 Manual for more information.
554 Preprocessor Options
556 -D<macroname>=<value>
557 Adds an implicit #define into the predefines buffer which is
558 read before the source file is preprocessed.
559 -U<macroname>
561 Adds an implicit #undef into the predefines buffer which is read
562 before the source file is preprocessed.
563 -include <filename>
565 Adds an implicit #include into the predefines buffer which is
566 read before the source file is preprocessed.
567 -I<directory>
569 Add the specified directory to the search path for include
570 files.
571 -F<directory>
573 Add the specified directory to the search path for framework in‐
574 clude files.
575 -nostdinc
577 Do not search the standard system directories or compiler
578 builtin directories for include files.
579 -nostdlibinc
581 Do not search the standard system directories for include files,
582 but do search compiler builtin include directories.
583 -nobuiltininc
585 Do not search clang's builtin directory for include files.
586
588 TMPDIR, TEMP, TMP
589 These environment variables are checked, in order, for the loca‐
590 tion to write temporary files used during the compilation
591 process.
592 CPATH If this environment variable is present, it is treated as a de‐
594 limited list of paths to be added to the default system include
595 path list. The delimiter is the platform dependent delimiter, as
596 used in the PATH environment variable.
597 Empty components in the environment variable are ignored.
599 C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_IN‐
601 CLUDE_PATH
602 These environment variables specify additional paths, as for
603 CPATH, which are only used when processing the appropriate lan‐
604 guage.
605 MACOSX_DEPLOYMENT_TARGET
607 If -mmacosx-version-min is unspecified, the default deployment
608 target is read from this environment variable. This option only
609 affects Darwin targets.
610
612 To report bugs, please visit <‐
613 https://github.com/llvm/llvm-project/issues/>. Most bug reports should
614 include preprocessed source files (use the -E option) and the full out‐
615 put of the compiler, along with information to reproduce.
616
618 as(1), ld(1)
619
621 Maintained by the Clang / LLVM Team (<http://clang.llvm.org>)
622
624 2007-2023, The Clang Team
62517 Nov 28, 2023 CLANG(1)