1CLANG(1)                             Clang                            CLANG(1)
2
3
4

NAME

6       clang - the Clang C, C++, and Objective-C compiler
7

SYNOPSIS

9       clang [options] filename ...
10

DESCRIPTION

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

OPTIONS

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
245none: allow no implicit conversions between vectors
246
247integer: allow implicit bitcasts between  integer  vectors  of
248                the same overall bit-width
249
250all:  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

ENVIRONMENT

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

BUGS

566       To  report  bugs,  please visit <https://bugs.llvm.org/>.  Most bug re‐
567       ports should include preprocessed source files (use the -E option)  and
568       the full output of the compiler, along with information to reproduce.
569

SEE ALSO

571       as(1), ld(1)
572

AUTHOR

574       Maintained by the Clang / LLVM Team (<http://clang.llvm.org>)
575
577       2007-2021, The Clang Team
578
579
580
581
58212                               May 18, 2021                         CLANG(1)
Impressum