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
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

OPTIONS

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

ENVIRONMENT

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

BUGS

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

SEE ALSO

532       as(1), ld(1)
533

AUTHOR

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)
Impressum