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 semantic analysis 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++20
161
162                     ISO C++ 2020 with amendments
163                 gnu++20
164
165                     ISO C++ 2020 with amendments and GNU extensions
166                 c++2b
167
168                     Working draft for ISO C++ 2023
169                 gnu++2b
170
171                     Working draft for ISO C++ 2023 with GNU extensions
172
173              The default C++ language standard is gnu++17.
174
175              Supported values for the OpenCL language are:
176                 cl1.0
177
178                     OpenCL 1.0
179                 cl1.1
180
181                     OpenCL 1.1
182                 cl1.2
183
184                     OpenCL 1.2
185                 cl2.0
186
187                     OpenCL 2.0
188
189              The default OpenCL language standard is cl1.0.
190
191              Supported values for the CUDA language are:
192                 cuda
193
194                     NVIDIA CUDA(tm)
195
196       -stdlib=<library>
197              Specify the C++ standard library to use; supported  options  are
198              libstdc++ and libc++. If not specified, platform default will be
199              used.
200
201       -rtlib=<library>
202              Specify the compiler runtime library to use;  supported  options
203              are  libgcc  and compiler-rt. If not specified, platform default
204              will be used.
205
206       -ansi  Same as -std=c89.
207
208       -ObjC, -ObjC++
209              Treat source input files as Objective-C  and  Object-C++  inputs
210              respectively.
211
212       -trigraphs
213              Enable trigraphs.
214
215       -ffreestanding
216              Indicate  that  the  file should be compiled for a freestanding,
217              not a hosted, environment. Note that it is assumed that a  free‐
218              standing  environment will additionally provide memcpy, memmove,
219              memset and memcmp implementations, as these are needed for effi‐
220              cient codegen for many programs.
221
222       -fno-builtin
223              Disable special handling and optimizations of well-known library
224              functions, like strlen() and malloc().
225
226       -fno-builtin-<function>
227              Disable special handling and optimizations for the specific  li‐
228              brary  function.   For  example, -fno-builtin-strlen removes any
229              special handling for the strlen() library function.
230
231       -fno-builtin-std-<function>
232              Disable special handling and optimizations for the specific  C++
233              standard   library  function  in  namespace  std.  For  example,
234              -fno-builtin-std-move_if_noexcept removes any  special  handling
235              for the std::move_if_noexcept() library function.
236
237              For  C  standard library functions that the C++ standard library
238              also provides in namespace std, use -fno-builtin-<function>  in‐
239              stead.
240
241       -fmath-errno
242              Indicate  that  math functions should be treated as updating er‐
243              rno.
244
245       -fpascal-strings
246              Enable support for Pascal-style strings with "\pfoo".
247
248       -fms-extensions
249              Enable support for Microsoft extensions.
250
251       -fmsc-version=
252              Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise.
253
254       -fborland-extensions
255              Enable support for Borland extensions.
256
257       -fwritable-strings
258              Make all string literals default  to  writable.   This  disables
259              uniquing of strings and other optimizations.
260
261       -flax-vector-conversions,              -flax-vector-conversions=<kind>,
262       -fno-lax-vector-conversions
263              Allow loose type checking rules for implicit vector conversions.
264              Possible values of <kind>:
265
266none: allow no implicit conversions between vectors
267
268integer:  allow  implicit  bitcasts between integer vectors of
269                the same overall bit-width
270
271all: allow implicit bitcasts between any vectors of  the  same
272                overall bit-width
273
274              <kind> defaults to integer if unspecified.
275
276       -fblocks
277              Enable the "Blocks" language feature.
278
279       -fobjc-abi-version=version
280              Select  the  Objective-C  ABI version to use. Available versions
281              are 1 (legacy "fragile" ABI),  2  (non-fragile  ABI  1),  and  3
282              (non-fragile ABI 2).
283
284       -fobjc-nonfragile-abi-version=<version>
285              Select  the  Objective-C  non-fragile  ABI version to use by de‐
286              fault. This will only be used as the Objective-C  ABI  when  the
287              non-fragile ABI is enabled (either via -fobjc-nonfragile-abi, or
288              because it is the platform default).
289
290       -fobjc-nonfragile-abi, -fno-objc-nonfragile-abi
291              Enable use of the Objective-C non-fragile ABI. On platforms  for
292              which  this  is  the  default  ABI,  it  can  be  disabled  with
293              -fno-objc-nonfragile-abi.
294
295   Target Selection Options
296       Clang fully supports cross compilation as an inherent part of  its  de‐
297       sign.   Depending  on  how  your version of Clang is configured, it may
298       have support for a number of cross compilers, or may only support a na‐
299       tive target.
300
301       -arch <architecture>
302              Specify the architecture to build for (Mac OS X specific).
303
304       -target <architecture>
305              Specify the architecture to build for (all platforms).
306
307       -mmacosx-version-min=<version>
308              When  building  for macOS, specify the minimum version supported
309              by your application.
310
311       -miphoneos-version-min
312              When building for iPhone OS, specify the  minimum  version  sup‐
313              ported by your application.
314
315       --print-supported-cpus
316              Print  out  a  list of supported processors for the given target
317              (specified through --target=<architecture> or  -arch  <architec‐
318              ture>).  If  no  target  is specified, the system default target
319              will be used.
320
321       -mcpu=?, -mtune=?
322              Acts as an alias for --print-supported-cpus.
323
324       -march=<cpu>
325              Specify that Clang should generate code for a specific processor
326              family   member   and   later.   For  example,  if  you  specify
327              -march=i486, the compiler is allowed  to  generate  instructions
328              that  are  valid on i486 and later processors, but which may not
329              exist on earlier ones.
330
331   Code Generation Options
332       -O0, -O1, -O2, -O3, -Ofast, -Os, -Oz, -Og, -O, -O4
333              Specify which optimization level to use:
334                 -O0 Means "no optimization": this level compiles the  fastest
335                 and generates the most debuggable code.
336
337                 -O1 Somewhere between -O0 and -O2.
338
339                 -O2  Moderate  level of optimization which enables most opti‐
340                 mizations.
341
342                 -O3 Like -O2, except that it enables optimizations that  take
343                 longer to perform or that may generate larger code (in an at‐
344                 tempt to make the program run faster).
345
346                 -Ofast Enables all the  optimizations  from  -O3  along  with
347                 other  aggressive  optimizations that may violate strict com‐
348                 pliance with language standards.
349
350                 -Os Like -O2 with extra optimizations to reduce code size.
351
352                 -Oz Like -Os (and thus -O2), but reduces code size further.
353
354                 -Og Like -O1. In future versions, this option  might  disable
355                 different optimizations in order to improve debuggability.
356
357                 -O Equivalent to -O1.
358
359                 -O4 and higher
360                     Currently equivalent to -O3
361
362       -g, -gline-tables-only, -gmodules
363              Control  debug information output.  Note that Clang debug infor‐
364              mation works best at -O0.  When more than  one  option  starting
365              with -g is specified, the last one wins:
366                 -g Generate debug information.
367
368                 -gline-tables-only  Generate  only  line table debug informa‐
369                 tion. This allows for symbolicated backtraces  with  inlining
370                 information, but does not include any information about vari‐
371                 ables, their locations or types.
372
373                 -gmodules Generate debug information that  contains  external
374                 references  to  types defined in Clang modules or precompiled
375                 headers instead of emitting redundant debug type  information
376                 into  every  object file.  This option transparently switches
377                 the Clang module format to object file containers  that  hold
378                 the  Clang  module together with the debug information.  When
379                 compiling a program that uses Clang  modules  or  precompiled
380                 headers, this option produces complete debug information with
381                 faster compile times and much smaller object files.
382
383                 This option should not be used when building static libraries
384                 for  distribution  to  other  machines because the debug info
385                 will contain references to the module cache  on  the  machine
386                 the object files in the library were built on.
387
388       -fstandalone-debug -fno-standalone-debug
389              Clang  supports  a number of optimizations to reduce the size of
390              debug information in the binary. They work based on the  assump‐
391              tion that the debug type information can be spread out over mul‐
392              tiple compilation units.  For instance, Clang will not emit type
393              definitions  for types that are not needed by a module and could
394              be replaced with a forward  declaration.   Further,  Clang  will
395              only  emit  type info for a dynamic C++ class in the module that
396              contains the vtable for the class.
397
398              The -fstandalone-debug option  turns  off  these  optimizations.
399              This  is useful when working with 3rd-party libraries that don't
400              come with debug information.  This is  the  default  on  Darwin.
401              Note  that Clang will never emit type information for types that
402              are not referenced at all by the program.
403
404       -feliminate-unused-debug-types
405              By default, Clang does not emit type information for types  that
406              are  defined but not used in a program. To retain the debug info
407              for these unused types, the  negation  -fno-eliminate-unused-de‐
408              bug-types can be used.
409
410       -fexceptions
411              Enable  generation of unwind information. This allows exceptions
412              to be thrown through Clang compiled stack frames.  This is on by
413              default in x86-64.
414
415       -ftrapv
416              Generate  code to catch integer overflow errors.  Signed integer
417              overflow is undefined in C. With this flag, extra code is gener‐
418              ated to detect this and abort when it happens.
419
420       -fvisibility
421              This flag sets the default visibility level.
422
423       -fcommon, -fno-common
424              This flag specifies that variables without initializers get com‐
425              mon linkage.  It can be disabled with -fno-common.
426
427       -ftls-model=<model>
428              Set the default thread-local storage  (TLS)  model  to  use  for
429              thread-local variables. Valid values are: "global-dynamic", "lo‐
430              cal-dynamic", "initial-exec" and "local-exec".  The  default  is
431              "global-dynamic".  The  default model can be overridden with the
432              tls_model attribute. The compiler will try to choose a more  ef‐
433              ficient model if possible.
434
435       -flto, -flto=full, -flto=thin, -emit-llvm
436              Generate  output  files  in LLVM formats, suitable for link time
437              optimization.  When used with -S this generates LLVM  intermedi‐
438              ate  language assembly files, otherwise this generates LLVM bit‐
439              code format object files (which may be passed to the linker  de‐
440              pending on the stage selection options).
441
442              The  default  for  -flto is "full", in which the LLVM bitcode is
443              suitable for monolithic Link Time Optimization (LTO), where  the
444              linker merges all such modules into a single combined module for
445              optimization. With "thin", ThinLTO compilation  is  invoked  in‐
446              stead.
447
448              NOTE:
449                 On  Darwin,  when using -flto along with -g and compiling and
450                 linking in separate steps, you also  need  to  pass  -Wl,-ob‐
451                 ject_path_lto,<lto-filename>.o  at  the  linking  step to in‐
452                 struct the ld64 linker not to  delete  the  temporary  object
453                 file  generated  during  Link Time Optimization (this flag is
454                 automatically passed to the linker by  Clang  if  compilation
455                 and linking are done in a single step). This allows debugging
456                 the executable as well as generating the .dSYM  bundle  using
457                 dsymutil(1).
458
459   Driver Options
460       -###   Print (but do not run) the commands to run for this compilation.
461
462       --help Display available options.
463
464       -Qunused-arguments
465              Do not emit any warnings for unused driver arguments.
466
467       -Wa,<args>
468              Pass the comma separated arguments in args to the assembler.
469
470       -Wl,<args>
471              Pass the comma separated arguments in args to the linker.
472
473       -Wp,<args>
474              Pass the comma separated arguments in args to the preprocessor.
475
476       -Xanalyzer <arg>
477              Pass arg to the static analyzer.
478
479       -Xassembler <arg>
480              Pass arg to the assembler.
481
482       -Xlinker <arg>
483              Pass arg to the linker.
484
485       -Xpreprocessor <arg>
486              Pass arg to the preprocessor.
487
488       -o <file>
489              Write output to file.
490
491       -print-file-name=<file>
492              Print the full library path of file.
493
494       -print-libgcc-file-name
495              Print  the  library path for the currently used compiler runtime
496              library ("libgcc.a" or "libclang_rt.builtins.*.a").
497
498       -print-prog-name=<name>
499              Print the full program path of name.
500
501       -print-search-dirs
502              Print the paths used for finding libraries and programs.
503
504       -save-temps
505              Save intermediate compilation results.
506
507       -save-stats, -save-stats=cwd, -save-stats=obj
508              Save internal code generation (LLVM) statistics to a file in the
509              current  directory (-save-stats/"-save-stats=cwd") or the direc‐
510              tory of the output file ("-save-state=obj").
511
512       -integrated-as, -no-integrated-as
513              Used to enable and disable, respectively, the use of  the  inte‐
514              grated  assembler. Whether the integrated assembler is on by de‐
515              fault is target dependent.
516
517       -time  Time individual commands.
518
519       -ftime-report
520              Print timing summary of each stage of compilation.
521
522       -v     Show commands to run and use verbose output.
523
524   Diagnostics Options
525       -fshow-column, -fshow-source-location, -fcaret-diagnostics,  -fdiagnos‐
526       tics-fixit-info,       -fdiagnostics-parseable-fixits,       -fdiagnos‐
527       tics-print-source-range-info,   -fprint-source-range-info,   -fdiagnos‐
528       tics-show-option, -fmessage-length
529              These options control how Clang prints out information about di‐
530              agnostics (errors and warnings). Please  see  the  Clang  User's
531              Manual for more information.
532
533   Preprocessor Options
534       -D<macroname>=<value>
535              Adds  an  implicit  #define  into the predefines buffer which is
536              read before the source file is preprocessed.
537
538       -U<macroname>
539              Adds an implicit #undef into the predefines buffer which is read
540              before the source file is preprocessed.
541
542       -include <filename>
543              Adds  an  implicit  #include into the predefines buffer which is
544              read before the source file is preprocessed.
545
546       -I<directory>
547              Add the specified directory  to  the  search  path  for  include
548              files.
549
550       -F<directory>
551              Add the specified directory to the search path for framework in‐
552              clude files.
553
554       -nostdinc
555              Do not  search  the  standard  system  directories  or  compiler
556              builtin directories for include files.
557
558       -nostdlibinc
559              Do not search the standard system directories for include files,
560              but do search compiler builtin include directories.
561
562       -nobuiltininc
563              Do not search clang's builtin directory for include files.
564

ENVIRONMENT

566       TMPDIR, TEMP, TMP
567              These environment variables are checked, in order, for the loca‐
568              tion  to  write  temporary  files  used  during  the compilation
569              process.
570
571       CPATH  If this environment variable is present, it is treated as a  de‐
572              limited  list of paths to be added to the default system include
573              path list. The delimiter is the platform dependent delimiter, as
574              used in the PATH environment variable.
575
576              Empty components in the environment variable are ignored.
577
578       C_INCLUDE_PATH,   OBJC_INCLUDE_PATH,  CPLUS_INCLUDE_PATH,  OBJCPLUS_IN‐
579       CLUDE_PATH
580              These environment variables specify  additional  paths,  as  for
581              CPATH,  which are only used when processing the appropriate lan‐
582              guage.
583
584       MACOSX_DEPLOYMENT_TARGET
585              If -mmacosx-version-min is unspecified, the  default  deployment
586              target  is read from this environment variable. This option only
587              affects Darwin targets.
588

BUGS

590       To         report         bugs,         please         visit         <‐
591       https://github.com/llvm/llvm-project/issues/>.  Most bug reports should
592       include preprocessed source files (use the -E option) and the full out‐
593       put of the compiler, along with information to reproduce.
594

SEE ALSO

596       as(1), ld(1)
597

AUTHOR

599       Maintained by the Clang / LLVM Team (<http://clang.llvm.org>)
600
602       2007-2023, The Clang Team
603
604
605
606
60716                               Aug 24, 2023                         CLANG(1)
Impressum