UsersManual.rst source code [clang_source

1	============================
2	Clang Compiler User's Manual
3	============================
4
5	.. include:: <isonum.txt>
6
7	.. contents::
8	:local:
9
10	Introduction
11	============
12
13	The Clang Compiler is an open-source compiler for the C family of
14	programming languages, aiming to be the best in class implementation of
15	these languages. Clang builds on the LLVM optimizer and code generator,
16	allowing it to provide high-quality optimization and code generation
17	support for many targets. For more general information, please see the
18	`Clang Web Site <https://clang.llvm.org>`_ or the `LLVM Web
19	Site <https://llvm.org>`_.
20
21	This document describes important notes about using Clang as a compiler
22	for an end-user, documenting the supported features, command line
23	options, etc. If you are interested in using Clang to build a tool that
24	processes code, please see :doc:`InternalsManual`. If you are interested in the
25	`Clang Static Analyzer <https://clang-analyzer.llvm.org>`_, please see its web
26	page.
27
28	Clang is one component in a complete toolchain for C family languages.
29	A separate document describes the other pieces necessary to
30	:doc:`assemble a complete toolchain <Toolchain>`.
31
32	Clang is designed to support the C family of programming languages,
33	which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and
34	:ref:`Objective-C++ <objcxx>` as well as many dialects of those. For
35	language-specific information, please see the corresponding language
36	specific section:
37
38	- :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
39	C99 (+TC1, TC2, TC3).
40	- :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus
41	variants depending on base language.
42	- :ref:`C++ Language <cxx>`
43	- :ref:`Objective C++ Language <objcxx>`
44	- :ref:`OpenCL C Language <opencl>`: v1.0, v1.1, v1.2, v2.0.
45
46	In addition to these base languages and their dialects, Clang supports a
47	broad variety of language extensions, which are documented in the
48	corresponding language section. These extensions are provided to be
49	compatible with the GCC, Microsoft, and other popular compilers as well
50	as to improve functionality through Clang-specific features. The Clang
51	driver and language features are intentionally designed to be as
52	compatible with the GNU GCC compiler as reasonably possible, easing
53	migration from GCC to Clang. In most cases, code "just works".
54	Clang also provides an alternative driver, :ref:`clang-cl`, that is designed
55	to be compatible with the Visual C++ compiler, cl.exe.
56
57	In addition to language specific features, Clang has a variety of
58	features that depend on what CPU architecture or operating system is
59	being compiled for. Please see the :ref:`Target-Specific Features and
60	Limitations <target_features>` section for more details.
61
62	The rest of the introduction introduces some basic :ref:`compiler
63	terminology <terminology>` that is used throughout this manual and
64	contains a basic :ref:`introduction to using Clang <basicusage>` as a
65	command line compiler.
66
67	.. _terminology:
68
69	Terminology
70	-----------
71
72	Front end, parser, backend, preprocessor, undefined behavior,
73	diagnostic, optimizer
74
75	.. _basicusage:
76
77	Basic Usage
78	-----------
79
80	Intro to how to use a C compiler for newbies.
81
82	compile + link compile then link debug info enabling optimizations
83	picking a language to use, defaults to C11 by default. Autosenses based
84	on extension. using a makefile
85
86	Command Line Options
87	====================
88
89	This section is generally an index into other sections. It does not go
90	into depth on the ones that are covered by other sections. However, the
91	first part introduces the language selection and other high level
92	options like :option:`-c`, :option:`-g`, etc.
93
94	Options to Control Error and Warning Messages
95	---------------------------------------------
96
97	.. option:: -Werror
98
99	Turn warnings into errors.
100
101	.. This is in plain monospaced font because it generates the same label as
102	.. -Werror, and Sphinx complains.
103
104	``-Werror=foo``
105
106	Turn warning "foo" into an error.
107
108	.. option:: -Wno-error=foo
109
110	Turn warning "foo" into a warning even if :option:`-Werror` is specified.
111
112	.. option:: -Wfoo
113
114	Enable warning "foo".
115	See the :doc:`diagnostics reference <DiagnosticsReference>` for a complete
116	list of the warning flags that can be specified in this way.
117
118	.. option:: -Wno-foo
119
120	Disable warning "foo".
121
122	.. option:: -w
123
124	Disable all diagnostics.
125
126	.. option:: -Weverything
127
128	:ref:`Enable all diagnostics. <diagnostics_enable_everything>`
129
130	.. option:: -pedantic
131
132	Warn on language extensions.
133
134	.. option:: -pedantic-errors
135
136	Error on language extensions.
137
138	.. option:: -Wsystem-headers
139
140	Enable warnings from system headers.
141
142	.. option:: -ferror-limit=123
143
144	Stop emitting diagnostics after 123 errors have been produced. The default is
145	20, and the error limit can be disabled with `-ferror-limit=0`.
146
147	.. option:: -ftemplate-backtrace-limit=123
148
149	Only emit up to 123 template instantiation notes within the template
150	instantiation backtrace for a single warning or error. The default is 10, and
151	the limit can be disabled with `-ftemplate-backtrace-limit=0`.
152
153	.. _cl_diag_formatting:
154
155	Formatting of Diagnostics
156	^^^^^^^^^^^^^^^^^^^^^^^^^
157
158	Clang aims to produce beautiful diagnostics by default, particularly for
159	new users that first come to Clang. However, different people have
160	different preferences, and sometimes Clang is driven not by a human,
161	but by a program that wants consistent and easily parsable output. For
162	these cases, Clang provides a wide range of options to control the exact
163	output format of the diagnostics that it generates.
164
165	.. _opt_fshow-column:
166
167	-f[no-]show-column
168	Print column number in diagnostic.
169
170	This option, which defaults to on, controls whether or not Clang
171	prints the column number of a diagnostic. For example, when this is
172	enabled, Clang will print something like:
173
174	::
175
176	test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
177	#endif bad
178	^
179	//
180
181	When this is disabled, Clang will print "test.c:28: warning..." with
182	no column number.
183
184	The printed column numbers count bytes from the beginning of the
185	line; take care if your source contains multibyte characters.
186
187	.. _opt_fshow-source-location:
188
189	-f[no-]show-source-location
190	Print source file/line/column information in diagnostic.
191
192	This option, which defaults to on, controls whether or not Clang
193	prints the filename, line number and column number of a diagnostic.
194	For example, when this is enabled, Clang will print something like:
195
196	::
197
198	test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
199	#endif bad
200	^
201	//
202
203	When this is disabled, Clang will not print the "test.c:28:8: "
204	part.
205
206	.. _opt_fcaret-diagnostics:
207
208	-f[no-]caret-diagnostics
209	Print source line and ranges from source code in diagnostic.
210	This option, which defaults to on, controls whether or not Clang
211	prints the source line, source ranges, and caret when emitting a
212	diagnostic. For example, when this is enabled, Clang will print
213	something like:
214
215	::
216
217	test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
218	#endif bad
219	^
220	//
221
222	-f[no-]color-diagnostics
223	This option, which defaults to on when a color-capable terminal is
224	detected, controls whether or not Clang prints diagnostics in color.
225
226	When this option is enabled, Clang will use colors to highlight
227	specific parts of the diagnostic, e.g.,
228
229	.. nasty hack to not lose our dignity
230
231	.. raw:: html
232
233	<pre>
234	<b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b>
235	#endif bad
236	<span style="color:green">^</span>
237	<span style="color:green">//</span>
238	</pre>
239
240	When this is disabled, Clang will just print:
241
242	::
243
244	test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
245	#endif bad
246	^
247	//
248
249	-fansi-escape-codes
250	Controls whether ANSI escape codes are used instead of the Windows Console
251	API to output colored diagnostics. This option is only used on Windows and
252	defaults to off.
253
254	.. option:: -fdiagnostics-format=clang/msvc/vi
255
256	Changes diagnostic output format to better match IDEs and command line tools.
257
258	This option controls the output format of the filename, line number,
259	and column printed in diagnostic messages. The options, and their
260	affect on formatting a simple conversion diagnostic, follow:
261
262	clang (default)
263	::
264
265	t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
266
267	msvc
268	::
269
270	t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'
271
272	vi
273	::
274
275	t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
276
277	.. _opt_fdiagnostics-show-option:
278
279	-f[no-]diagnostics-show-option
280	Enable ``[-Woption]`` information in diagnostic line.
281
282	This option, which defaults to on, controls whether or not Clang
283	prints the associated :ref:`warning group <cl_diag_warning_groups>`
284	option name when outputting a warning diagnostic. For example, in
285	this output:
286
287	::
288
289	test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
290	#endif bad
291	^
292	//
293
294	Passing -fno-diagnostics-show-option will prevent Clang from
295	printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in
296	the diagnostic. This information tells you the flag needed to enable
297	or disable the diagnostic, either from the command line or through
298	:ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.
299
300	.. _opt_fdiagnostics-show-category:
301
302	.. option:: -fdiagnostics-show-category=none/id/name
303
304	Enable printing category information in diagnostic line.
305
306	This option, which defaults to "none", controls whether or not Clang
307	prints the category associated with a diagnostic when emitting it.
308	Each diagnostic may or many not have an associated category, if it
309	has one, it is listed in the diagnostic categorization field of the
310	diagnostic line (in the []'s).
311
312	For example, a format string warning will produce these three
313	renditions based on the setting of this option:
314
315	::
316
317	t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
318	t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
319	t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
320
321	This category can be used by clients that want to group diagnostics
322	by category, so it should be a high level category. We want dozens
323	of these, not hundreds or thousands of them.
324
325	.. _opt_fsave-optimization-record:
326
327	-fsave-optimization-record
328	Write optimization remarks to a YAML file.
329
330	This option, which defaults to off, controls whether Clang writes
331	optimization reports to a YAML file. By recording diagnostics in a file,
332	using a structured YAML format, users can parse or sort the remarks in a
333	convenient way.
334
335	.. _opt_foptimization-record-file:
336
337	-foptimization-record-file
338	Control the file to which optimization reports are written.
339
340	When optimization reports are being output (see
341	:ref:`-fsave-optimization-record <opt_fsave-optimization-record>`), this
342	option controls the file to which those reports are written.
343
344	If this option is not used, optimization records are output to a file named
345	after the primary file being compiled. If that's "foo.c", for example,
346	optimization records are output to "foo.opt.yaml".
347
348	.. _opt_fdiagnostics-show-hotness:
349
350	-f[no-]diagnostics-show-hotness
351	Enable profile hotness information in diagnostic line.
352
353	This option controls whether Clang prints the profile hotness associated
354	with diagnostics in the presence of profile-guided optimization information.
355	This is currently supported with optimization remarks (see
356	:ref:`Options to Emit Optimization Reports <rpass>`). The hotness information
357	allows users to focus on the hot optimization remarks that are likely to be
358	more relevant for run-time performance.
359
360	For example, in this output, the block containing the callsite of `foo` was
361	executed 3000 times according to the profile data:
362
363	::
364
365	s.c:7:10: remark: foo inlined into bar (hotness: 3000) [-Rpass-analysis=inline]
366	sum += foo(x, x - 2);
367	^
368
369	This option is implied when
370	:ref:`-fsave-optimization-record <opt_fsave-optimization-record>` is used.
371	Otherwise, it defaults to off.
372
373	.. _opt_fdiagnostics-hotness-threshold:
374
375	-fdiagnostics-hotness-threshold
376	Prevent optimization remarks from being output if they do not have at least
377	this hotness value.
378
379	This option, which defaults to zero, controls the minimum hotness an
380	optimization remark would need in order to be output by Clang. This is
381	currently supported with optimization remarks (see :ref:`Options to Emit
382	Optimization Reports <rpass>`) when profile hotness information in
383	diagnostics is enabled (see
384	:ref:`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`).
385
386	.. _opt_fdiagnostics-fixit-info:
387
388	-f[no-]diagnostics-fixit-info
389	Enable "FixIt" information in the diagnostics output.
390
391	This option, which defaults to on, controls whether or not Clang
392	prints the information on how to fix a specific diagnostic
393	underneath it when it knows. For example, in this output:
394
395	::
396
397	test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
398	#endif bad
399	^
400	//
401
402	Passing -fno-diagnostics-fixit-info will prevent Clang from
403	printing the "//" line at the end of the message. This information
404	is useful for users who may not understand what is wrong, but can be
405	confusing for machine parsing.
406
407	.. _opt_fdiagnostics-print-source-range-info:
408
409	-fdiagnostics-print-source-range-info
410	Print machine parsable information about source ranges.
411	This option makes Clang print information about source ranges in a machine
412	parsable format after the file/line/column number information. The
413	information is a simple sequence of brace enclosed ranges, where each range
414	lists the start and end line/column locations. For example, in this output:
415
416	::
417
418	exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
419	P = (P-42) + Gamma*4;
420	~~~~~~ ^ ~~~~~~~
421
422	The {}'s are generated by -fdiagnostics-print-source-range-info.
423
424	The printed column numbers count bytes from the beginning of the
425	line; take care if your source contains multibyte characters.
426
427	.. option:: -fdiagnostics-parseable-fixits
428
429	Print Fix-Its in a machine parseable form.
430
431	This option makes Clang print available Fix-Its in a machine
432	parseable format at the end of diagnostics. The following example
433	illustrates the format:
434
435	::
436
437	fix-it:"t.cpp":{7:25-7:29}:"Gamma"
438
439	The range printed is a half-open range, so in this example the
440	characters at column 25 up to but not including column 29 on line 7
441	in t.cpp should be replaced with the string "Gamma". Either the
442	range or the replacement string may be empty (representing strict
443	insertions and strict erasures, respectively). Both the file name
444	and the insertion string escape backslash (as "\\\\"), tabs (as
445	"\\t"), newlines (as "\\n"), double quotes(as "\\"") and
446	non-printable characters (as octal "\\xxx").
447
448	The printed column numbers count bytes from the beginning of the
449	line; take care if your source contains multibyte characters.
450
451	.. option:: -fno-elide-type
452
453	Turns off elision in template type printing.
454
455	The default for template type printing is to elide as many template
456	arguments as possible, removing those which are the same in both
457	template types, leaving only the differences. Adding this flag will
458	print all the template arguments. If supported by the terminal,
459	highlighting will still appear on differing arguments.
460
461	Default:
462
463	::
464
465	t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
466
467	-fno-elide-type:
468
469	::
470
471	t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, map<float, int>>>' to 'vector<map<int, map<double, int>>>' for 1st argument;
472
473	.. option:: -fdiagnostics-show-template-tree
474
475	Template type diffing prints a text tree.
476
477	For diffing large templated types, this option will cause Clang to
478	display the templates as an indented text tree, one argument per
479	line, with differences marked inline. This is compatible with
480	-fno-elide-type.
481
482	Default:
483
484	::
485
486	t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
487
488	With :option:`-fdiagnostics-show-template-tree`:
489
490	::
491
492	t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
493	vector<
494	map<
495	[...],
496	map<
497	[float != double],
498	[...]>>>
499
500	.. _cl_diag_warning_groups:
501
502	Individual Warning Groups
503	^^^^^^^^^^^^^^^^^^^^^^^^^
504
505	TODO: Generate this from tblgen. Define one anchor per warning group.
506
507	.. _opt_wextra-tokens:
508
509	.. option:: -Wextra-tokens
510
511	Warn about excess tokens at the end of a preprocessor directive.
512
513	This option, which defaults to on, enables warnings about extra
514	tokens at the end of preprocessor directives. For example:
515
516	::
517
518	test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
519	#endif bad
520	^
521
522	These extra tokens are not strictly conforming, and are usually best
523	handled by commenting them out.
524
525	.. option:: -Wambiguous-member-template
526
527	Warn about unqualified uses of a member template whose name resolves to
528	another template at the location of the use.
529
530	This option, which defaults to on, enables a warning in the
531	following code:
532
533	::
534
535	template<typename T> struct set{};
536	template<typename T> struct trait { typedef const T& type; };
537	struct Value {
538	template<typename T> void set(typename trait<T>::type value) {}
539	};
540	void foo() {
541	Value v;
542	v.set<double>(3.2);
543	}
544
545	C++ [basic.lookup.classref] requires this to be an error, but,
546	because it's hard to work around, Clang downgrades it to a warning
547	as an extension.
548
549	.. option:: -Wbind-to-temporary-copy
550
551	Warn about an unusable copy constructor when binding a reference to a
552	temporary.
553
554	This option enables warnings about binding a
555	reference to a temporary when the temporary doesn't have a usable
556	copy constructor. For example:
557
558	::
559
560	struct NonCopyable {
561	NonCopyable();
562	private:
563	NonCopyable(const NonCopyable&);
564	};
565	void foo(const NonCopyable&);
566	void bar() {
567	foo(NonCopyable()); // Disallowed in C++98; allowed in C++11.
568	}
569
570	::
571
572	struct NonCopyable2 {
573	NonCopyable2();
574	NonCopyable2(NonCopyable2&);
575	};
576	void foo(const NonCopyable2&);
577	void bar() {
578	foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11.
579	}
580
581	Note that if ``NonCopyable2::NonCopyable2()`` has a default argument
582	whose instantiation produces a compile error, that error will still
583	be a hard error in C++98 mode even if this warning is turned off.
584
585	Options to Control Clang Crash Diagnostics
586	------------------------------------------
587
588	As unbelievable as it may sound, Clang does crash from time to time.
589	Generally, this only occurs to those living on the `bleeding
590	edge <https://llvm.org/releases/download.html#svn>`_. Clang goes to great
591	lengths to assist you in filing a bug report. Specifically, Clang
592	generates preprocessed source file(s) and associated run script(s) upon
593	a crash. These files should be attached to a bug report to ease
594	reproducibility of the failure. Below are the command line options to
595	control the crash diagnostics.
596
597	.. option:: -fno-crash-diagnostics
598
599	Disable auto-generation of preprocessed source files during a clang crash.
600
601	The -fno-crash-diagnostics flag can be helpful for speeding the process
602	of generating a delta reduced test case.
603
604	Clang is also capable of generating preprocessed source file(s) and associated
605	run script(s) even without a crash. This is specially useful when trying to
606	generate a reproducer for warnings or errors while using modules.
607
608	.. option:: -gen-reproducer
609
610	Generates preprocessed source files, a reproducer script and if relevant, a
611	cache containing: built module pcm's and all headers needed to rebuilt the
612	same modules.
613
614	.. _rpass:
615
616	Options to Emit Optimization Reports
617	------------------------------------
618
619	Optimization reports trace, at a high-level, all the major decisions
620	done by compiler transformations. For instance, when the inliner
621	decides to inline function ``foo()`` into ``bar()``, or the loop unroller
622	decides to unroll a loop N times, or the vectorizer decides to
623	vectorize a loop body.
624
625	Clang offers a family of flags which the optimizers can use to emit
626	a diagnostic in three cases:
627
628	1. When the pass makes a transformation (`-Rpass`).
629
630	2. When the pass fails to make a transformation (`-Rpass-missed`).
631
632	3. When the pass determines whether or not to make a transformation
633	(`-Rpass-analysis`).
634
635	NOTE: Although the discussion below focuses on `-Rpass`, the exact
636	same options apply to `-Rpass-missed` and `-Rpass-analysis`.
637
638	Since there are dozens of passes inside the compiler, each of these flags
639	take a regular expression that identifies the name of the pass which should
640	emit the associated diagnostic. For example, to get a report from the inliner,
641	compile the code with:
642
643	.. code-block:: console
644
645	$ clang -O2 -Rpass=inline code.cc -o code
646	code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]
647	int bar(int j) { return foo(j, j - 2); }
648	^
649
650	Note that remarks from the inliner are identified with `[-Rpass=inline]`.
651	To request a report from every optimization pass, you should use
652	`-Rpass=.*` (in fact, you can use any valid POSIX regular
653	expression). However, do not expect a report from every transformation
654	made by the compiler. Optimization remarks do not really make sense
655	outside of the major transformations (e.g., inlining, vectorization,
656	loop optimizations) and not every optimization pass supports this
657	feature.
658
659	Note that when using profile-guided optimization information, profile hotness
660	information can be included in the remarks (see
661	:ref:`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`).
662
663	Current limitations
664	^^^^^^^^^^^^^^^^^^^
665
666	1. Optimization remarks that refer to function names will display the
667	mangled name of the function. Since these remarks are emitted by the
668	back end of the compiler, it does not know anything about the input
669	language, nor its mangling rules.
670
671	2. Some source locations are not displayed correctly. The front end has
672	a more detailed source location tracking than the locations included
673	in the debug info (e.g., the front end can locate code inside macro
674	expansions). However, the locations used by `-Rpass` are
675	translated from debug annotations. That translation can be lossy,
676	which results in some remarks having no location information.
677
678	Other Options
679	-------------
680	Clang options that don't fit neatly into other categories.
681
682	.. option:: -MV
683
684	When emitting a dependency file, use formatting conventions appropriate
685	for NMake or Jom. Ignored unless another option causes Clang to emit a
686	dependency file.
687
688	When Clang emits a dependency file (e.g., you supplied the -M option)
689	most filenames can be written to the file without any special formatting.
690	Different Make tools will treat different sets of characters as "special"
691	and use different conventions for telling the Make tool that the character
692	is actually part of the filename. Normally Clang uses backslash to "escape"
693	a special character, which is the convention used by GNU Make. The -MV
694	option tells Clang to put double-quotes around the entire filename, which
695	is the convention used by NMake and Jom.
696
697	Configuration files
698	-------------------
699
700	Configuration files group command-line options and allow all of them to be
701	specified just by referencing the configuration file. They may be used, for
702	example, to collect options required to tune compilation for particular
703	target, such as -L, -I, -l, --sysroot, codegen options, etc.
704
705	The command line option `--config` can be used to specify configuration
706	file in a Clang invocation. For example:
707
708	::
709
710	clang --config /home/user/cfgs/testing.txt
711	clang --config debug.cfg
712
713	If the provided argument contains a directory separator, it is considered as
714	a file path, and options are read from that file. Otherwise the argument is
715	treated as a file name and is searched for sequentially in the directories:
716
717	- user directory,
718	- system directory,
719	- the directory where Clang executable resides.
720
721	Both user and system directories for configuration files are specified during
722	clang build using CMake parameters, CLANG_CONFIG_FILE_USER_DIR and
723	CLANG_CONFIG_FILE_SYSTEM_DIR respectively. The first file found is used. It is
724	an error if the required file cannot be found.
725
726	Another way to specify a configuration file is to encode it in executable name.
727	For example, if the Clang executable is named `armv7l-clang` (it may be a
728	symbolic link to `clang`), then Clang will search for file `armv7l.cfg` in the
729	directory where Clang resides.
730
731	If a driver mode is specified in invocation, Clang tries to find a file specific
732	for the specified mode. For example, if the executable file is named
733	`x86_64-clang-cl`, Clang first looks for `x86_64-cl.cfg` and if it is not found,
734	looks for `x86_64.cfg`.
735
736	If the command line contains options that effectively change target architecture
737	(these are -m32, -EL, and some others) and the configuration file starts with an
738	architecture name, Clang tries to load the configuration file for the effective
739	architecture. For example, invocation:
740
741	::
742
743	x86_64-clang -m32 abc.c
744
745	causes Clang search for a file `i368.cfg` first, and if no such file is found,
746	Clang looks for the file `x86_64.cfg`.
747
748	The configuration file consists of command-line options specified on one or
749	more lines. Lines composed of whitespace characters only are ignored as well as
750	lines in which the first non-blank character is `#`. Long options may be split
751	between several lines by a trailing backslash. Here is example of a
752	configuration file:
753
754	::
755
756	# Several options on line
757	-c --target=x86_64-unknown-linux-gnu
758
759	# Long option split between lines
760	-I/usr/lib/gcc/x86_64-linux-gnu/5.4.0/../../../../\
761	include/c++/5.4.0
762
763	# other config files may be included
764	@linux.options
765
766	Files included by `@file` directives in configuration files are resolved
767	relative to the including file. For example, if a configuration file
768	`~/.llvm/target.cfg` contains the directive `@os/linux.opts`, the file
769	`linux.opts` is searched for in the directory `~/.llvm/os`.
770
771	Language and Target-Independent Features
772	========================================
773
774	Controlling Errors and Warnings
775	-------------------------------
776
777	Clang provides a number of ways to control which code constructs cause
778	it to emit errors and warning messages, and how they are displayed to
779	the console.
780
781	Controlling How Clang Displays Diagnostics
782	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
783
784	When Clang emits a diagnostic, it includes rich information in the
785	output, and gives you fine-grain control over which information is
786	printed. Clang has the ability to print this information, and these are
787	the options that control it:
788
789	#. A file/line/column indicator that shows exactly where the diagnostic
790	occurs in your code [:ref:`-fshow-column <opt_fshow-column>`,
791	:ref:`-fshow-source-location <opt_fshow-source-location>`].
792	#. A categorization of the diagnostic as a note, warning, error, or
793	fatal error.
794	#. A text string that describes what the problem is.
795	#. An option that indicates how to control the diagnostic (for
796	diagnostics that support it)
797	[:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
798	#. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
799	for clients that want to group diagnostics by class (for diagnostics
800	that support it)
801	[:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
802	#. The line of source code that the issue occurs on, along with a caret
803	and ranges that indicate the important locations
804	[:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
805	#. "FixIt" information, which is a concise explanation of how to fix the
806	problem (when Clang is certain it knows)
807	[:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
808	#. A machine-parsable representation of the ranges involved (off by
809	default)
810	[:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].
811
812	For more information please see :ref:`Formatting of
813	Diagnostics <cl_diag_formatting>`.
814
815	Diagnostic Mappings
816	^^^^^^^^^^^^^^^^^^^
817
818	All diagnostics are mapped into one of these 6 classes:
819
820	- Ignored
821	- Note
822	- Remark
823	- Warning
824	- Error
825	- Fatal
826
827	.. _diagnostics_categories:
828
829	Diagnostic Categories
830	^^^^^^^^^^^^^^^^^^^^^
831
832	Though not shown by default, diagnostics may each be associated with a
833	high-level category. This category is intended to make it possible to
834	triage builds that produce a large number of errors or warnings in a
835	grouped way.
836
837	Categories are not shown by default, but they can be turned on with the
838	:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
839	When set to "``name``", the category is printed textually in the
840	diagnostic output. When it is set to "``id``", a category number is
841	printed. The mapping of category names to category id's can be obtained
842	by running '``clang --print-diagnostic-categories``'.
843
844	Controlling Diagnostics via Command Line Flags
845	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
846
847	TODO: -W flags, -pedantic, etc
848
849	.. _pragma_gcc_diagnostic:
850
851	Controlling Diagnostics via Pragmas
852	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
853
854	Clang can also control what diagnostics are enabled through the use of
855	pragmas in the source code. This is useful for turning off specific
856	warnings in a section of source code. Clang supports GCC's pragma for
857	compatibility with existing source code, as well as several extensions.
858
859	The pragma may control any warning that can be used from the command
860	line. Warnings may be set to ignored, warning, error, or fatal. The
861	following example code will tell Clang or GCC to ignore the -Wall
862	warnings:
863
864	.. code-block:: c
865
866	#pragma GCC diagnostic ignored "-Wall"
867
868	In addition to all of the functionality provided by GCC's pragma, Clang
869	also allows you to push and pop the current warning state. This is
870	particularly useful when writing a header file that will be compiled by
871	other people, because you don't know what warning flags they build with.
872
873	In the below example :option:`-Wextra-tokens` is ignored for only a single line
874	of code, after which the diagnostics return to whatever state had previously
875	existed.
876
877	.. code-block:: c
878
879	#if foo
880	#endif foo // warning: extra tokens at end of #endif directive
881
882	#pragma clang diagnostic push
883	#pragma clang diagnostic ignored "-Wextra-tokens"
884
885	#if foo
886	#endif foo // no warning
887
888	#pragma clang diagnostic pop
889
890	The push and pop pragmas will save and restore the full diagnostic state
891	of the compiler, regardless of how it was set. That means that it is
892	possible to use push and pop around GCC compatible diagnostics and Clang
893	will push and pop them appropriately, while GCC will ignore the pushes
894	and pops as unknown pragmas. It should be noted that while Clang
895	supports the GCC pragma, Clang and GCC do not support the exact same set
896	of warnings, so even when using GCC compatible #pragmas there is no
897	guarantee that they will have identical behaviour on both compilers.
898
899	In addition to controlling warnings and errors generated by the compiler, it is
900	possible to generate custom warning and error messages through the following
901	pragmas:
902
903	.. code-block:: c
904
905	// The following will produce warning messages
906	#pragma message "some diagnostic message"
907	#pragma GCC warning "TODO: replace deprecated feature"
908
909	// The following will produce an error message
910	#pragma GCC error "Not supported"
911
912	These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
913	directives, except that they may also be embedded into preprocessor macros via
914	the C99 ``_Pragma`` operator, for example:
915
916	.. code-block:: c
917
918	#define STR(X) #X
919	#define DEFER(M,...) M(__VA_ARGS__)
920	#define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
921
922	CUSTOM_ERROR("Feature not available");
923
924	Controlling Diagnostics in System Headers
925	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
926
927	Warnings are suppressed when they occur in system headers. By default,
928	an included file is treated as a system header if it is found in an
929	include path specified by ``-isystem``, but this can be overridden in
930	several ways.
931
932	The ``system_header`` pragma can be used to mark the current file as
933	being a system header. No warnings will be produced from the location of
934	the pragma onwards within the same file.
935
936	.. code-block:: c
937
938	#if foo
939	#endif foo // warning: extra tokens at end of #endif directive
940
941	#pragma clang system_header
942
943	#if foo
944	#endif foo // no warning
945
946	The `--system-header-prefix=` and `--no-system-header-prefix=`
947	command-line arguments can be used to override whether subsets of an include
948	path are treated as system headers. When the name in a ``#include`` directive
949	is found within a header search path and starts with a system prefix, the
950	header is treated as a system header. The last prefix on the
951	command-line which matches the specified header name takes precedence.
952	For instance:
953
954	.. code-block:: console
955
956	$ clang -Ifoo -isystem bar --system-header-prefix=x/ \
957	--no-system-header-prefix=x/y/
958
959	Here, ``#include "x/a.h"`` is treated as including a system header, even
960	if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
961	as not including a system header, even if the header is found in
962	``bar``.
963
964	A ``#include`` directive which finds a file relative to the current
965	directory is treated as including a system header if the including file
966	is treated as a system header.
967
968	.. _diagnostics_enable_everything:
969
970	Enabling All Diagnostics
971	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
972
973	In addition to the traditional ``-W`` flags, one can enable all
974	diagnostics by passing :option:`-Weverything`. This works as expected
975	with
976	:option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
977
978	Note that when combined with :option:`-w` (which disables all warnings), that
979	flag wins.
980
981	Controlling Static Analyzer Diagnostics
982	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
983
984	While not strictly part of the compiler, the diagnostics from Clang's
985	`static analyzer <https://clang-analyzer.llvm.org>`_ can also be
986	influenced by the user via changes to the source code. See the available
987	`annotations <https://clang-analyzer.llvm.org/annotations.html>`_ and the
988	analyzer's `FAQ
989	page <https://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
990	information.
991
992	.. _usersmanual-precompiled-headers:
993
994	Precompiled Headers
995	-------------------
996
997	`Precompiled headers <https://en.wikipedia.org/wiki/Precompiled_header>`_
998	are a general approach employed by many compilers to reduce compilation
999	time. The underlying motivation of the approach is that it is common for
1000	the same (and often large) header files to be included by multiple
1001	source files. Consequently, compile times can often be greatly improved
1002	by caching some of the (redundant) work done by a compiler to process
1003	headers. Precompiled header files, which represent one of many ways to
1004	implement this optimization, are literally files that represent an
1005	on-disk cache that contains the vital information necessary to reduce
1006	some of the work needed to process a corresponding header file. While
1007	details of precompiled headers vary between compilers, precompiled
1008	headers have been shown to be highly effective at speeding up program
1009	compilation on systems with very large system headers (e.g., Mac OS X).
1010
1011	Generating a PCH File
1012	^^^^^^^^^^^^^^^^^^^^^
1013
1014	To generate a PCH file using Clang, one invokes Clang with the
1015	`-x <language>-header` option. This mirrors the interface in GCC
1016	for generating PCH files:
1017
1018	.. code-block:: console
1019
1020	$ gcc -x c-header test.h -o test.h.gch
1021	$ clang -x c-header test.h -o test.h.pch
1022
1023	Using a PCH File
1024	^^^^^^^^^^^^^^^^
1025
1026	A PCH file can then be used as a prefix header when a :option:`-include`
1027	option is passed to ``clang``:
1028
1029	.. code-block:: console
1030
1031	$ clang -include test.h test.c -o test
1032
1033	The ``clang`` driver will first check if a PCH file for ``test.h`` is
1034	available; if so, the contents of ``test.h`` (and the files it includes)
1035	will be processed from the PCH file. Otherwise, Clang falls back to
1036	directly processing the content of ``test.h``. This mirrors the behavior
1037	of GCC.
1038
1039	.. note::
1040
1041	Clang does not automatically use PCH files for headers that are directly
1042	included within a source file. For example:
1043
1044	.. code-block:: console
1045
1046	$ clang -x c-header test.h -o test.h.pch
1047	$ cat test.c
1048	#include "test.h"
1049	$ clang test.c -o test
1050
1051	In this example, ``clang`` will not automatically use the PCH file for
1052	``test.h`` since ``test.h`` was included directly in the source file and not
1053	specified on the command line using :option:`-include`.
1054
1055	Relocatable PCH Files
1056	^^^^^^^^^^^^^^^^^^^^^
1057
1058	It is sometimes necessary to build a precompiled header from headers
1059	that are not yet in their final, installed locations. For example, one
1060	might build a precompiled header within the build tree that is then
1061	meant to be installed alongside the headers. Clang permits the creation
1062	of "relocatable" precompiled headers, which are built with a given path
1063	(into the build directory) and can later be used from an installed
1064	location.
1065
1066	To build a relocatable precompiled header, place your headers into a
1067	subdirectory whose structure mimics the installed location. For example,
1068	if you want to build a precompiled header for the header ``mylib.h``
1069	that will be installed into ``/usr/include``, create a subdirectory
1070	``build/usr/include`` and place the header ``mylib.h`` into that
1071	subdirectory. If ``mylib.h`` depends on other headers, then they can be
1072	stored within ``build/usr/include`` in a way that mimics the installed
1073	location.
1074
1075	Building a relocatable precompiled header requires two additional
1076	arguments. First, pass the ``--relocatable-pch`` flag to indicate that
1077	the resulting PCH file should be relocatable. Second, pass
1078	``-isysroot /path/to/build``, which makes all includes for your library
1079	relative to the build directory. For example:
1080
1081	.. code-block:: console
1082
1083	# clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
1084
1085	When loading the relocatable PCH file, the various headers used in the
1086	PCH file are found from the system header root. For example, ``mylib.h``
1087	can be found in ``/usr/include/mylib.h``. If the headers are installed
1088	in some other system root, the ``-isysroot`` option can be used provide
1089	a different system root from which the headers will be based. For
1090	example, ``-isysroot /Developer/SDKs/MacOSX10.4u.sdk`` will look for
1091	``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
1092
1093	Relocatable precompiled headers are intended to be used in a limited
1094	number of cases where the compilation environment is tightly controlled
1095	and the precompiled header cannot be generated after headers have been
1096	installed.
1097
1098	.. _controlling-code-generation:
1099
1100	Controlling Code Generation
1101	---------------------------
1102
1103	Clang provides a number of ways to control code generation. The options
1104	are listed below.
1105
1106	-f[no-]sanitize=check1,check2,...
1107	Turn on runtime checks for various forms of undefined or suspicious
1108	behavior.
1109
1110	This option controls whether Clang adds runtime checks for various
1111	forms of undefined or suspicious behavior, and is disabled by
1112	default. If a check fails, a diagnostic message is produced at
1113	runtime explaining the problem. The main checks are:
1114
1115	- .. _opt_fsanitize_address:
1116
1117	``-fsanitize=address``:
1118	:doc:`AddressSanitizer`, a memory error
1119	detector.
1120	- .. _opt_fsanitize_thread:
1121
1122	``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector.
1123	- .. _opt_fsanitize_memory:
1124
1125	``-fsanitize=memory``: :doc:`MemorySanitizer`,
1126	a detector of uninitialized reads. Requires instrumentation of all
1127	program code.
1128	- .. _opt_fsanitize_undefined:
1129
1130	``-fsanitize=undefined``: :doc:`UndefinedBehaviorSanitizer`,
1131	a fast and compatible undefined behavior checker.
1132
1133	- ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data
1134	flow analysis.
1135	- ``-fsanitize=cfi``: :doc:`control flow integrity <ControlFlowIntegrity>`
1136	checks. Requires ``-flto``.
1137	- ``-fsanitize=safe-stack``: :doc:`safe stack <SafeStack>`
1138	protection against stack-based memory corruption errors.
1139
1140	There are more fine-grained checks available: see
1141	the :ref:`list <ubsan-checks>` of specific kinds of
1142	undefined behavior that can be detected and the :ref:`list <cfi-schemes>`
1143	of control flow integrity schemes.
1144
1145	The ``-fsanitize=`` argument must also be provided when linking, in
1146	order to link to the appropriate runtime library.
1147
1148	It is not possible to combine more than one of the ``-fsanitize=address``,
1149	``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
1150	program.
1151
1152	-f[no-]sanitize-recover=check1,check2,...
1153
1154	-f[no-]sanitize-recover=all
1155
1156	Controls which checks enabled by ``-fsanitize=`` flag are non-fatal.
1157	If the check is fatal, program will halt after the first error
1158	of this kind is detected and error report is printed.
1159
1160	By default, non-fatal checks are those enabled by
1161	:doc:`UndefinedBehaviorSanitizer`,
1162	except for ``-fsanitize=return`` and ``-fsanitize=unreachable``. Some
1163	sanitizers may not support recovery (or not support it by default
1164	e.g. :doc:`AddressSanitizer`), and always crash the program after the issue
1165	is detected.
1166
1167	Note that the ``-fsanitize-trap`` flag has precedence over this flag.
1168	This means that if a check has been configured to trap elsewhere on the
1169	command line, or if the check traps by default, this flag will not have
1170	any effect unless that sanitizer's trapping behavior is disabled with
1171	``-fno-sanitize-trap``.
1172
1173	For example, if a command line contains the flags ``-fsanitize=undefined
1174	-fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment``
1175	will have no effect on its own; it will need to be accompanied by
1176	``-fno-sanitize-trap=alignment``.
1177
1178	-f[no-]sanitize-trap=check1,check2,...
1179
1180	Controls which checks enabled by the ``-fsanitize=`` flag trap. This
1181	option is intended for use in cases where the sanitizer runtime cannot
1182	be used (for instance, when building libc or a kernel module), or where
1183	the binary size increase caused by the sanitizer runtime is a concern.
1184
1185	This flag is only compatible with :doc:`control flow integrity
1186	<ControlFlowIntegrity>` schemes and :doc:`UndefinedBehaviorSanitizer`
1187	checks other than ``vptr``. If this flag
1188	is supplied together with ``-fsanitize=undefined``, the ``vptr`` sanitizer
1189	will be implicitly disabled.
1190
1191	This flag is enabled by default for sanitizers in the ``cfi`` group.
1192
1193	.. option:: -fsanitize-blacklist=/path/to/blacklist/file
1194
1195	Disable or modify sanitizer checks for objects (source files, functions,
1196	variables, types) listed in the file. See
1197	:doc:`SanitizerSpecialCaseList` for file format description.
1198
1199	.. option:: -fno-sanitize-blacklist
1200
1201	Don't use blacklist file, if it was specified earlier in the command line.
1202
1203	-f[no-]sanitize-coverage=[type,features,...]
1204
1205	Enable simple code coverage in addition to certain sanitizers.
1206	See :doc:`SanitizerCoverage` for more details.
1207
1208	-f[no-]sanitize-stats
1209
1210	Enable simple statistics gathering for the enabled sanitizers.
1211	See :doc:`SanitizerStats` for more details.
1212
1213	.. option:: -fsanitize-undefined-trap-on-error
1214
1215	Deprecated alias for ``-fsanitize-trap=undefined``.
1216
1217	.. option:: -fsanitize-cfi-cross-dso
1218
1219	Enable cross-DSO control flow integrity checks. This flag modifies
1220	the behavior of sanitizers in the ``cfi`` group to allow checking
1221	of cross-DSO virtual and indirect calls.
1222
1223	.. option:: -fsanitize-cfi-icall-generalize-pointers
1224
1225	Generalize pointers in return and argument types in function type signatures
1226	checked by Control Flow Integrity indirect call checking. See
1227	:doc:`ControlFlowIntegrity` for more details.
1228
1229	.. option:: -fstrict-vtable-pointers
1230
1231	Enable optimizations based on the strict rules for overwriting polymorphic
1232	C++ objects, i.e. the vptr is invariant during an object's lifetime.
1233	This enables better devirtualization. Turned off by default, because it is
1234	still experimental.
1235
1236	.. option:: -ffast-math
1237
1238	Enable fast-math mode. This defines the ``__FAST_MATH__`` preprocessor
1239	macro, and lets the compiler make aggressive, potentially-lossy assumptions
1240	about floating-point math. These include:
1241
1242	* Floating-point math obeys regular algebraic rules for real numbers (e.g.
1243	``+`` and ```` are associative, ``x/y == x (1/y)``, and
1244	``(a + b) * c == a * c + b * c``),
1245	* operands to floating-point operations are not equal to ``NaN`` and
1246	``Inf``, and
1247	* ``+0`` and ``-0`` are interchangeable.
1248
1249	.. option:: -fdenormal-fp-math=[values]
1250
1251	Select which denormal numbers the code is permitted to require.
1252
1253	Valid values are: ``ieee``, ``preserve-sign``, and ``positive-zero``,
1254	which correspond to IEEE 754 denormal numbers, the sign of a
1255	flushed-to-zero number is preserved in the sign of 0, denormals are
1256	flushed to positive zero, respectively.
1257
1258	.. option:: -f[no-]strict-float-cast-overflow
1259
1260	When a floating-point value is not representable in a destination integer
1261	type, the code has undefined behavior according to the language standard.
1262	By default, Clang will not guarantee any particular result in that case.
1263	With the 'no-strict' option, Clang attempts to match the overflowing behavior
1264	of the target's native float-to-int conversion instructions.
1265
1266	.. option:: -fwhole-program-vtables
1267
1268	Enable whole-program vtable optimizations, such as single-implementation
1269	devirtualization and virtual constant propagation, for classes with
1270	:doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``.
1271
1272	.. option:: -fforce-emit-vtables
1273
1274	In order to improve devirtualization, forces emitting of vtables even in
1275	modules where it isn't necessary. It causes more inline virtual functions
1276	to be emitted.
1277
1278	.. option:: -fno-assume-sane-operator-new
1279
1280	Don't assume that the C++'s new operator is sane.
1281
1282	This option tells the compiler to do not assume that C++'s global
1283	new operator will always return a pointer that does not alias any
1284	other pointer when the function returns.
1285
1286	.. option:: -ftrap-function=[name]
1287
1288	Instruct code generator to emit a function call to the specified
1289	function name for ``__builtin_trap()``.
1290
1291	LLVM code generator translates ``__builtin_trap()`` to a trap
1292	instruction if it is supported by the target ISA. Otherwise, the
1293	builtin is translated into a call to ``abort``. If this option is
1294	set, then the code generator will always lower the builtin to a call
1295	to the specified function regardless of whether the target ISA has a
1296	trap instruction. This option is useful for environments (e.g.
1297	deeply embedded) where a trap cannot be properly handled, or when
1298	some custom behavior is desired.
1299
1300	.. option:: -ftls-model=[model]
1301
1302	Select which TLS model to use.
1303
1304	Valid values are: ``global-dynamic``, ``local-dynamic``,
1305	``initial-exec`` and ``local-exec``. The default value is
1306	``global-dynamic``. The compiler may use a different model if the
1307	selected model is not supported by the target, or if a more
1308	efficient model can be used. The TLS model can be overridden per
1309	variable using the ``tls_model`` attribute.
1310
1311	.. option:: -femulated-tls
1312
1313	Select emulated TLS model, which overrides all -ftls-model choices.
1314
1315	In emulated TLS mode, all access to TLS variables are converted to
1316	calls to __emutls_get_address in the runtime library.
1317
1318	.. option:: -mhwdiv=[values]
1319
1320	Select the ARM modes (arm or thumb) that support hardware division
1321	instructions.
1322
1323	Valid values are: ``arm``, ``thumb`` and ``arm,thumb``.
1324	This option is used to indicate which mode (arm or thumb) supports
1325	hardware division instructions. This only applies to the ARM
1326	architecture.
1327
1328	.. option:: -m[no-]crc
1329
1330	Enable or disable CRC instructions.
1331
1332	This option is used to indicate whether CRC instructions are to
1333	be generated. This only applies to the ARM architecture.
1334
1335	CRC instructions are enabled by default on ARMv8.
1336
1337	.. option:: -mgeneral-regs-only
1338
1339	Generate code which only uses the general purpose registers.
1340
1341	This option restricts the generated code to use general registers
1342	only. This only applies to the AArch64 architecture.
1343
1344	.. option:: -mcompact-branches=[values]
1345
1346	Control the usage of compact branches for MIPSR6.
1347
1348	Valid values are: ``never``, ``optimal`` and ``always``.
1349	The default value is ``optimal`` which generates compact branches
1350	when a delay slot cannot be filled. ``never`` disables the usage of
1351	compact branches and ``always`` generates compact branches whenever
1352	possible.
1353
1354	-f[no-]max-type-align=[number]
1355	Instruct the code generator to not enforce a higher alignment than the given
1356	number (of bytes) when accessing memory via an opaque pointer or reference.
1357	This cap is ignored when directly accessing a variable or when the pointee
1358	type has an explicit “aligned” attribute.
1359
1360	The value should usually be determined by the properties of the system allocator.
1361	Some builtin types, especially vector types, have very high natural alignments;
1362	when working with values of those types, Clang usually wants to use instructions
1363	that take advantage of that alignment. However, many system allocators do
1364	not promise to return memory that is more than 8-byte or 16-byte-aligned. Use
1365	this option to limit the alignment that the compiler can assume for an arbitrary
1366	pointer, which may point onto the heap.
1367
1368	This option does not affect the ABI alignment of types; the layout of structs and
1369	unions and the value returned by the alignof operator remain the same.
1370
1371	This option can be overridden on a case-by-case basis by putting an explicit
1372	“aligned” alignment on a struct, union, or typedef. For example:
1373
1374	.. code-block:: console
1375
1376	#include <immintrin.h>
1377	// Make an aligned typedef of the AVX-512 16-int vector type.
1378	typedef __v16si __aligned_v16si __attribute__((aligned(64)));
1379
1380	void initialize_vector(__aligned_v16si *v) {
1381	// The compiler may assume that ‘v’ is 64-byte aligned, regardless of the
1382	// value of -fmax-type-align.
1383	}
1384
1385	.. option:: -faddrsig, -fno-addrsig
1386
1387	Controls whether Clang emits an address-significance table into the object
1388	file. Address-significance tables allow linkers to implement `safe ICF
1389	<https://research.google.com/pubs/archive/36912.pdf>`_ without the false
1390	positives that can result from other implementation techniques such as
1391	relocation scanning. Address-significance tables are enabled by default
1392	on ELF targets when using the integrated assembler. This flag currently
1393	only has an effect on ELF targets.
1394
1395	Profile Guided Optimization
1396	---------------------------
1397
1398	Profile information enables better optimization. For example, knowing that a
1399	branch is taken very frequently helps the compiler make better decisions when
1400	ordering basic blocks. Knowing that a function ``foo`` is called more
1401	frequently than another function ``bar`` helps the inliner. Optimization
1402	levels ``-O2`` and above are recommended for use of profile guided optimization.
1403
1404	Clang supports profile guided optimization with two different kinds of
1405	profiling. A sampling profiler can generate a profile with very low runtime
1406	overhead, or you can build an instrumented version of the code that collects
1407	more detailed profile information. Both kinds of profiles can provide execution
1408	counts for instructions in the code and information on branches taken and
1409	function invocation.
1410
1411	Regardless of which kind of profiling you use, be careful to collect profiles
1412	by running your code with inputs that are representative of the typical
1413	behavior. Code that is not exercised in the profile will be optimized as if it
1414	is unimportant, and the compiler may make poor optimization choices for code
1415	that is disproportionately used while profiling.
1416
1417	Differences Between Sampling and Instrumentation
1418	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1419
1420	Although both techniques are used for similar purposes, there are important
1421	differences between the two:
1422
1423	1. Profile data generated with one cannot be used by the other, and there is no
1424	conversion tool that can convert one to the other. So, a profile generated
1425	via ``-fprofile-instr-generate`` must be used with ``-fprofile-instr-use``.
1426	Similarly, sampling profiles generated by external profilers must be
1427	converted and used with ``-fprofile-sample-use``.
1428
1429	2. Instrumentation profile data can be used for code coverage analysis and
1430	optimization.
1431
1432	3. Sampling profiles can only be used for optimization. They cannot be used for
1433	code coverage analysis. Although it would be technically possible to use
1434	sampling profiles for code coverage, sample-based profiles are too
1435	coarse-grained for code coverage purposes; it would yield poor results.
1436
1437	4. Sampling profiles must be generated by an external tool. The profile
1438	generated by that tool must then be converted into a format that can be read
1439	by LLVM. The section on sampling profilers describes one of the supported
1440	sampling profile formats.
1441
1442
1443	Using Sampling Profilers
1444	^^^^^^^^^^^^^^^^^^^^^^^^
1445
1446	Sampling profilers are used to collect runtime information, such as
1447	hardware counters, while your application executes. They are typically
1448	very efficient and do not incur a large runtime overhead. The
1449	sample data collected by the profiler can be used during compilation
1450	to determine what the most executed areas of the code are.
1451
1452	Using the data from a sample profiler requires some changes in the way
1453	a program is built. Before the compiler can use profiling information,
1454	the code needs to execute under the profiler. The following is the
1455	usual build cycle when using sample profilers for optimization:
1456
1457	1. Build the code with source line table information. You can use all the
1458	usual build flags that you always build your application with. The only
1459	requirement is that you add ``-gline-tables-only`` or ``-g`` to the
1460	command line. This is important for the profiler to be able to map
1461	instructions back to source line locations.
1462
1463	.. code-block:: console
1464
1465	$ clang++ -O2 -gline-tables-only code.cc -o code
1466
1467	2. Run the executable under a sampling profiler. The specific profiler
1468	you use does not really matter, as long as its output can be converted
1469	into the format that the LLVM optimizer understands. Currently, there
1470	exists a conversion tool for the Linux Perf profiler
1471	(https://perf.wiki.kernel.org/), so these examples assume that you
1472	are using Linux Perf to profile your code.
1473
1474	.. code-block:: console
1475
1476	$ perf record -b ./code
1477
1478	Note the use of the ``-b`` flag. This tells Perf to use the Last Branch
1479	Record (LBR) to record call chains. While this is not strictly required,
1480	it provides better call information, which improves the accuracy of
1481	the profile data.
1482
1483	3. Convert the collected profile data to LLVM's sample profile format.
1484	This is currently supported via the AutoFDO converter ``create_llvm_prof``.
1485	It is available at https://github.com/google/autofdo. Once built and
1486	installed, you can convert the ``perf.data`` file to LLVM using
1487	the command:
1488
1489	.. code-block:: console
1490
1491	$ create_llvm_prof --binary=./code --out=code.prof
1492
1493	This will read ``perf.data`` and the binary file ``./code`` and emit
1494	the profile data in ``code.prof``. Note that if you ran ``perf``
1495	without the ``-b`` flag, you need to use ``--use_lbr=false`` when
1496	calling ``create_llvm_prof``.
1497
1498	4. Build the code again using the collected profile. This step feeds
1499	the profile back to the optimizers. This should result in a binary
1500	that executes faster than the original one. Note that you are not
1501	required to build the code with the exact same arguments that you
1502	used in the first step. The only requirement is that you build the code
1503	with ``-gline-tables-only`` and ``-fprofile-sample-use``.
1504
1505	.. code-block:: console
1506
1507	$ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code
1508
1509
1510	Sample Profile Formats
1511	""""""""""""""""""""""
1512
1513	Since external profilers generate profile data in a variety of custom formats,
1514	the data generated by the profiler must be converted into a format that can be
1515	read by the backend. LLVM supports three different sample profile formats:
1516
1517	1. ASCII text. This is the easiest one to generate. The file is divided into
1518	sections, which correspond to each of the functions with profile
1519	information. The format is described below. It can also be generated from
1520	the binary or gcov formats using the ``llvm-profdata`` tool.
1521
1522	2. Binary encoding. This uses a more efficient encoding that yields smaller
1523	profile files. This is the format generated by the ``create_llvm_prof`` tool
1524	in https://github.com/google/autofdo.
1525
1526	3. GCC encoding. This is based on the gcov format, which is accepted by GCC. It
1527	is only interesting in environments where GCC and Clang co-exist. This
1528	encoding is only generated by the ``create_gcov`` tool in
1529	https://github.com/google/autofdo. It can be read by LLVM and
1530	``llvm-profdata``, but it cannot be generated by either.
1531
1532	If you are using Linux Perf to generate sampling profiles, you can use the
1533	conversion tool ``create_llvm_prof`` described in the previous section.
1534	Otherwise, you will need to write a conversion tool that converts your
1535	profiler's native format into one of these three.
1536
1537
1538	Sample Profile Text Format
1539	""""""""""""""""""""""""""
1540
1541	This section describes the ASCII text format for sampling profiles. It is,
1542	arguably, the easiest one to generate. If you are interested in generating any
1543	of the other two, consult the ``ProfileData`` library in LLVM's source tree
1544	(specifically, ``include/llvm/ProfileData/SampleProfReader.h``).
1545
1546	.. code-block:: console
1547
1548	function1:total_samples:total_head_samples
1549	offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
1550	offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
1551	...
1552	offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
1553	offsetA[.discriminator]: fnA:num_of_total_samples
1554	offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ]
1555	offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ]
1556	offsetB[.discriminator]: fnB:num_of_total_samples
1557	offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ]
1558
1559	This is a nested tree in which the indentation represents the nesting level
1560	of the inline stack. There are no blank lines in the file. And the spacing
1561	within a single line is fixed. Additional spaces will result in an error
1562	while reading the file.
1563
1564	Any line starting with the '#' character is completely ignored.
1565
1566	Inlined calls are represented with indentation. The Inline stack is a
1567	stack of source locations in which the top of the stack represents the
1568	leaf function, and the bottom of the stack represents the actual
1569	symbol to which the instruction belongs.
1570
1571	Function names must be mangled in order for the profile loader to
1572	match them in the current translation unit. The two numbers in the
1573	function header specify how many total samples were accumulated in the
1574	function (first number), and the total number of samples accumulated
1575	in the prologue of the function (second number). This head sample
1576	count provides an indicator of how frequently the function is invoked.
1577
1578	There are two types of lines in the function body.
1579
1580	- Sampled line represents the profile information of a source location.
1581	``offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]``
1582
1583	- Callsite line represents the profile information of an inlined callsite.
1584	``offsetA[.discriminator]: fnA:num_of_total_samples``
1585
1586	Each sampled line may contain several items. Some are optional (marked
1587	below):
1588
1589	a. Source line offset. This number represents the line number
1590	in the function where the sample was collected. The line number is
1591	always relative to the line where symbol of the function is
1592	defined. So, if the function has its header at line 280, the offset
1593	13 is at line 293 in the file.
1594
1595	Note that this offset should never be a negative number. This could
1596	happen in cases like macros. The debug machinery will register the
1597	line number at the point of macro expansion. So, if the macro was
1598	expanded in a line before the start of the function, the profile
1599	converter should emit a 0 as the offset (this means that the optimizers
1600	will not be able to associate a meaningful weight to the instructions
1601	in the macro).
1602
1603	b. [OPTIONAL] Discriminator. This is used if the sampled program
1604	was compiled with DWARF discriminator support
1605	(http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
1606	DWARF discriminators are unsigned integer values that allow the
1607	compiler to distinguish between multiple execution paths on the
1608	same source line location.
1609
1610	For example, consider the line of code ``if (cond) foo(); else bar();``.
1611	If the predicate ``cond`` is true 80% of the time, then the edge
1612	into function ``foo`` should be considered to be taken most of the
1613	time. But both calls to ``foo`` and ``bar`` are at the same source
1614	line, so a sample count at that line is not sufficient. The
1615	compiler needs to know which part of that line is taken more
1616	frequently.
1617
1618	This is what discriminators provide. In this case, the calls to
1619	``foo`` and ``bar`` will be at the same line, but will have
1620	different discriminator values. This allows the compiler to correctly
1621	set edge weights into ``foo`` and ``bar``.
1622
1623	c. Number of samples. This is an integer quantity representing the
1624	number of samples collected by the profiler at this source
1625	location.
1626
1627	d. [OPTIONAL] Potential call targets and samples. If present, this
1628	line contains a call instruction. This models both direct and
1629	number of samples. For example,
1630
1631	.. code-block:: console
1632
1633	130: 7 foo:3 bar:2 baz:7
1634
1635	The above means that at relative line offset 130 there is a call
1636	instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
1637	with ``baz()`` being the relatively more frequently called target.
1638
1639	As an example, consider a program with the call chain ``main -> foo -> bar``.
1640	When built with optimizations enabled, the compiler may inline the
1641	calls to ``bar`` and ``foo`` inside ``main``. The generated profile
1642	could then be something like this:
1643
1644	.. code-block:: console
1645
1646	main:35504:0
1647	1: _Z3foov:35504
1648	2: _Z32bari:31977
1649	1.1: 31977
1650	2: 0
1651
1652	This profile indicates that there were a total of 35,504 samples
1653	collected in main. All of those were at line 1 (the call to ``foo``).
1654	Of those, 31,977 were spent inside the body of ``bar``. The last line
1655	of the profile (``2: 0``) corresponds to line 2 inside ``main``. No
1656	samples were collected there.
1657
1658	Profiling with Instrumentation
1659	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1660
1661	Clang also supports profiling via instrumentation. This requires building a
1662	special instrumented version of the code and has some runtime
1663	overhead during the profiling, but it provides more detailed results than a
1664	sampling profiler. It also provides reproducible results, at least to the
1665	extent that the code behaves consistently across runs.
1666
1667	Here are the steps for using profile guided optimization with
1668	instrumentation:
1669
1670	1. Build an instrumented version of the code by compiling and linking with the
1671	``-fprofile-instr-generate`` option.
1672
1673	.. code-block:: console
1674
1675	$ clang++ -O2 -fprofile-instr-generate code.cc -o code
1676
1677	2. Run the instrumented executable with inputs that reflect the typical usage.
1678	By default, the profile data will be written to a ``default.profraw`` file
1679	in the current directory. You can override that default by using option
1680	``-fprofile-instr-generate=`` or by setting the ``LLVM_PROFILE_FILE``
1681	environment variable to specify an alternate file. If non-default file name
1682	is specified by both the environment variable and the command line option,
1683	the environment variable takes precedence. The file name pattern specified
1684	can include different modifiers: ``%p``, ``%h``, and ``%m``.
1685
1686	Any instance of ``%p`` in that file name will be replaced by the process
1687	ID, so that you can easily distinguish the profile output from multiple
1688	runs.
1689
1690	.. code-block:: console
1691
1692	$ LLVM_PROFILE_FILE="code-%p.profraw" ./code
1693
1694	The modifier ``%h`` can be used in scenarios where the same instrumented
1695	binary is run in multiple different host machines dumping profile data
1696	to a shared network based storage. The ``%h`` specifier will be substituted
1697	with the hostname so that profiles collected from different hosts do not
1698	clobber each other.
1699
1700	While the use of ``%p`` specifier can reduce the likelihood for the profiles
1701	dumped from different processes to clobber each other, such clobbering can still
1702	happen because of the ``pid`` re-use by the OS. Another side-effect of using
1703	``%p`` is that the storage requirement for raw profile data files is greatly
1704	increased. To avoid issues like this, the ``%m`` specifier can used in the profile
1705	name. When this specifier is used, the profiler runtime will substitute ``%m``
1706	with a unique integer identifier associated with the instrumented binary. Additionally,
1707	multiple raw profiles dumped from different processes that share a file system (can be
1708	on different hosts) will be automatically merged by the profiler runtime during the
1709	dumping. If the program links in multiple instrumented shared libraries, each library
1710	will dump the profile data into its own profile data file (with its unique integer
1711	id embedded in the profile name). Note that the merging enabled by ``%m`` is for raw
1712	profile data generated by profiler runtime. The resulting merged "raw" profile data
1713	file still needs to be converted to a different format expected by the compiler (
1714	see step 3 below).
1715
1716	.. code-block:: console
1717
1718	$ LLVM_PROFILE_FILE="code-%m.profraw" ./code
1719
1720
1721	3. Combine profiles from multiple runs and convert the "raw" profile format to
1722	the input expected by clang. Use the ``merge`` command of the
1723	``llvm-profdata`` tool to do this.
1724
1725	.. code-block:: console
1726
1727	$ llvm-profdata merge -output=code.profdata code-*.profraw
1728
1729	Note that this step is necessary even when there is only one "raw" profile,
1730	since the merge operation also changes the file format.
1731
1732	4. Build the code again using the ``-fprofile-instr-use`` option to specify the
1733	collected profile data.
1734
1735	.. code-block:: console
1736
1737	$ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code
1738
1739	You can repeat step 4 as often as you like without regenerating the
1740	profile. As you make changes to your code, clang may no longer be able to
1741	use the profile data. It will warn you when this happens.
1742
1743	Profile generation using an alternative instrumentation method can be
1744	controlled by the GCC-compatible flags ``-fprofile-generate`` and
1745	``-fprofile-use``. Although these flags are semantically equivalent to
1746	their GCC counterparts, they do not handle GCC-compatible profiles.
1747	They are only meant to implement GCC's semantics with respect to
1748	profile creation and use. Flag ``-fcs-profile-generate`` also instruments
1749	programs using the same instrumentation method as ``-fprofile-generate``.
1750
1751	.. option:: -fprofile-generate[=<dirname>]
1752
1753	The ``-fprofile-generate`` and ``-fprofile-generate=`` flags will use
1754	an alternative instrumentation method for profile generation. When
1755	given a directory name, it generates the profile file
1756	``default_%m.profraw`` in the directory named ``dirname`` if specified.
1757	If ``dirname`` does not exist, it will be created at runtime. ``%m`` specifier
1758	will be substituted with a unique id documented in step 2 above. In other words,
1759	with ``-fprofile-generate[=<dirname>]`` option, the "raw" profile data automatic
1760	merging is turned on by default, so there will no longer any risk of profile
1761	clobbering from different running processes. For example,
1762
1763	.. code-block:: console
1764
1765	$ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
1766
1767	When ``code`` is executed, the profile will be written to the file
1768	``yyy/zzz/default_xxxx.profraw``.
1769
1770	To generate the profile data file with the compiler readable format, the
1771	``llvm-profdata`` tool can be used with the profile directory as the input:
1772
1773	.. code-block:: console
1774
1775	$ llvm-profdata merge -output=code.profdata yyy/zzz/
1776
1777	If the user wants to turn off the auto-merging feature, or simply override the
1778	the profile dumping path specified at command line, the environment variable
1779	``LLVM_PROFILE_FILE`` can still be used to override
1780	the directory and filename for the profile file at runtime.
1781
1782	.. option:: -fcs-profile-generate[=<dirname>]
1783
1784	The ``-fcs-profile-generate`` and ``-fcs-profile-generate=`` flags will use
1785	the same instrumentation method, and generate the same profile as in the
1786	``-fprofile-generate`` and ``-fprofile-generate=`` flags. The difference is
1787	that the instrumentation is performed after inlining so that the resulted
1788	profile has a better context sensitive information. They cannot be used
1789	together with ``-fprofile-generate`` and ``-fprofile-generate=`` flags.
1790	They are typically used in conjunction with ``-fprofile-use`` flag.
1791	The profile generated by ``-fcs-profile-generate`` and ``-fprofile-generate``
1792	can be merged by llvm-profdata. A use example:
1793
1794	.. code-block:: console
1795
1796	$ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
1797	$ ./code
1798	$ llvm-profdata merge -output=code.profdata yyy/zzz/
1799
1800	The first few steps are the same as that in ``-fprofile-generate``
1801	compilation. Then perform a second round of instrumentation.
1802
1803	.. code-block:: console
1804
1805	$ clang++ -O2 -fprofile-use=code.profdata -fcs-profile-generate=sss/ttt \
1806	-o cs_code
1807	$ ./cs_code
1808	$ llvm-profdata merge -output=cs_code.profdata sss/ttt code.profdata
1809
1810	The resulted ``cs_code.prodata`` combines ``code.profdata`` and the profile
1811	generated from binary ``cs_code``. Profile ``cs_code.profata`` can be used by
1812	``-fprofile-use`` compilaton.
1813
1814	.. code-block:: console
1815
1816	$ clang++ -O2 -fprofile-use=cs_code.profdata
1817
1818	The above command will read both profiles to the compiler at the identical
1819	point of instrumenations.
1820
1821	.. option:: -fprofile-use[=<pathname>]
1822
1823	Without any other arguments, ``-fprofile-use`` behaves identically to
1824	``-fprofile-instr-use``. Otherwise, if ``pathname`` is the full path to a
1825	profile file, it reads from that file. If ``pathname`` is a directory name,
1826	it reads from ``pathname/default.profdata``.
1827
1828	Disabling Instrumentation
1829	^^^^^^^^^^^^^^^^^^^^^^^^^
1830
1831	In certain situations, it may be useful to disable profile generation or use
1832	for specific files in a build, without affecting the main compilation flags
1833	used for the other files in the project.
1834
1835	In these cases, you can use the flag ``-fno-profile-instr-generate`` (or
1836	``-fno-profile-generate``) to disable profile generation, and
1837	``-fno-profile-instr-use`` (or ``-fno-profile-use``) to disable profile use.
1838
1839	Note that these flags should appear after the corresponding profile
1840	flags to have an effect.
1841
1842	Profile remapping
1843	^^^^^^^^^^^^^^^^^
1844
1845	When the program is compiled after a change that affects many symbol names,
1846	pre-existing profile data may no longer match the program. For example:
1847
1848	* switching from libstdc++ to libc++ will result in the mangled names of all
1849	functions taking standard library types to change
1850	* renaming a widely-used type in C++ will result in the mangled names of all
1851	functions that have parameters involving that type to change
1852	* moving from a 32-bit compilation to a 64-bit compilation may change the
1853	underlying type of ``size_t`` and similar types, resulting in changes to
1854	manglings
1855
1856	Clang allows use of a profile remapping file to specify that such differences
1857	in mangled names should be ignored when matching the profile data against the
1858	program.
1859
1860	.. option:: -fprofile-remapping-file=<file>
1861
1862	Specifies a file containing profile remapping information, that will be
1863	used to match mangled names in the profile data to mangled names in the
1864	program.
1865
1866	The profile remapping file is a text file containing lines of the form
1867
1868	.. code-block:: text
1869
1870	fragmentkind fragment1 fragment2
1871
1872	where ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``,
1873	indicating whether the following mangled name fragments are
1874	<`name <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name>`_>s,
1875	<`type <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type>`_>s, or
1876	<`encoding <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding>`_>s,
1877	respectively.
1878	Blank lines and lines starting with ``#`` are ignored.
1879
1880	For convenience, built-in <substitution>s such as ``St`` and ``Ss``
1881	are accepted as <name>s (even though they technically are not <name>s).
1882
1883	For example, to specify that ``absl::string_view`` and ``std::string_view``
1884	should be treated as equivalent when matching profile data, the following
1885	remapping file could be used:
1886
1887	.. code-block:: text
1888
1889	# absl::string_view is considered equivalent to std::string_view
1890	type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE
1891
1892	# std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++
1893	name 3std St3__1
1894	name 3std St7__cxx11
1895
1896	Matching profile data using a profile remapping file is supported on a
1897	best-effort basis. For example, information regarding indirect call targets is
1898	currently not remapped. For best results, you are encouraged to generate new
1899	profile data matching the updated program, or to remap the profile data
1900	using the ``llvm-cxxmap`` and ``llvm-profdata merge`` tools.
1901
1902	.. note::
1903
1904	Profile data remapping support is currently only implemented for LLVM's
1905	new pass manager, which can be enabled with
1906	``-fexperimental-new-pass-manager``.
1907
1908	.. note::
1909
1910	Profile data remapping is currently only supported for C++ mangled names
1911	following the Itanium C++ ABI mangling scheme. This covers all C++ targets
1912	supported by Clang other than Windows.
1913
1914	GCOV-based Profiling
1915	--------------------
1916
1917	GCOV is a test coverage program, it helps to know how often a line of code
1918	is executed. When instrumenting the code with ``--coverage`` option, some
1919	counters are added for each edge linking basic blocks.
1920
1921	At compile time, gcno files are generated containing information about
1922	blocks and edges between them. At runtime the counters are incremented and at
1923	exit the counters are dumped in gcda files.
1924
1925	The tool ``llvm-cov gcov`` will parse gcno, gcda and source files to generate
1926	a report ``.c.gcov``.
1927
1928	.. option:: -fprofile-filter-files=[regexes]
1929
1930	Define a list of regexes separated by a semi-colon.
1931	If a file name matches any of the regexes then the file is instrumented.
1932
1933	.. code-block:: console
1934
1935	$ clang --coverage -fprofile-filter-files=".*\.c$" foo.c
1936
1937	For example, this will only instrument files finishing with ``.c``, skipping ``.h`` files.
1938
1939	.. option:: -fprofile-exclude-files=[regexes]
1940
1941	Define a list of regexes separated by a semi-colon.
1942	If a file name doesn't match all the regexes then the file is instrumented.
1943
1944	.. code-block:: console
1945
1946	$ clang --coverage -fprofile-exclude-files="^/usr/include/.*$" foo.c
1947
1948	For example, this will instrument all the files except the ones in ``/usr/include``.
1949
1950	If both options are used then a file is instrumented if its name matches any
1951	of the regexes from ``-fprofile-filter-list`` and doesn't match all the regexes
1952	from ``-fprofile-exclude-list``.
1953
1954	.. code-block:: console
1955
1956	$ clang --coverage -fprofile-exclude-files="^/usr/include/.*$" \
1957	-fprofile-filter-files="^/usr/.*$"
1958
1959	In that case ``/usr/foo/oof.h`` is instrumented since it matches the filter regex and
1960	doesn't match the exclude regex, but ``/usr/include/foo.h`` doesn't since it matches
1961	the exclude regex.
1962
1963	Controlling Debug Information
1964	-----------------------------
1965
1966	Controlling Size of Debug Information
1967	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1968
1969	Debug info kind generated by Clang can be set by one of the flags listed
1970	below. If multiple flags are present, the last one is used.
1971
1972	.. option:: -g0
1973
1974	Don't generate any debug info (default).
1975
1976	.. option:: -gline-tables-only
1977
1978	Generate line number tables only.
1979
1980	This kind of debug info allows to obtain stack traces with function names,
1981	file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It
1982	doesn't contain any other data (e.g. description of local variables or
1983	function parameters).
1984
1985	.. option:: -fstandalone-debug
1986
1987	Clang supports a number of optimizations to reduce the size of debug
1988	information in the binary. They work based on the assumption that
1989	the debug type information can be spread out over multiple
1990	compilation units. For instance, Clang will not emit type
1991	definitions for types that are not needed by a module and could be
1992	replaced with a forward declaration. Further, Clang will only emit
1993	type info for a dynamic C++ class in the module that contains the
1994	vtable for the class.
1995
1996	The -fstandalone-debug option turns off these optimizations.
1997	This is useful when working with 3rd-party libraries that don't come
1998	with debug information. Note that Clang will never emit type
1999	information for types that are not referenced at all by the program.
2000
2001	.. option:: -fno-standalone-debug
2002
2003	On Darwin -fstandalone-debug is enabled by default. The
2004	-fno-standalone-debug option can be used to get to turn on the
2005	vtable-based optimization described above.
2006
2007	.. option:: -g
2008
2009	Generate complete debug info.
2010
2011	Controlling Macro Debug Info Generation
2012	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2013
2014	Debug info for C preprocessor macros increases the size of debug information in
2015	the binary. Macro debug info generated by Clang can be controlled by the flags
2016	listed below.
2017
2018	.. option:: -fdebug-macro
2019
2020	Generate debug info for preprocessor macros. This flag is discarded when
2021	-g0 is enabled.
2022
2023	.. option:: -fno-debug-macro
2024
2025	Do not generate debug info for preprocessor macros (default).
2026
2027	Controlling Debugger "Tuning"
2028	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2029
2030	While Clang generally emits standard DWARF debug info (http://dwarfstd.org),
2031	different debuggers may know how to take advantage of different specific DWARF
2032	features. You can "tune" the debug info for one of several different debuggers.
2033
2034	.. option:: -ggdb, -glldb, -gsce
2035
2036	Tune the debug info for the ``gdb``, ``lldb``, or Sony PlayStation\ \|reg\|
2037	debugger, respectively. Each of these options implies -g. (Therefore, if
2038	you want both -gline-tables-only and debugger tuning, the tuning option
2039	must come first.)
2040
2041
2042	Controlling LLVM IR Output
2043	--------------------------
2044
2045	Controlling Value Names in LLVM IR
2046	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2047
2048	Emitting value names in LLVM IR increases the size and verbosity of the IR.
2049	By default, value names are only emitted in assertion-enabled builds of Clang.
2050	However, when reading IR it can be useful to re-enable the emission of value
2051	names to improve readability.
2052
2053	.. option:: -fdiscard-value-names
2054
2055	Discard value names when generating LLVM IR.
2056
2057	.. option:: -fno-discard-value-names
2058
2059	Do not discard value names when generating LLVM IR. This option can be used
2060	to re-enable names for release builds of Clang.
2061
2062
2063	Comment Parsing Options
2064	-----------------------
2065
2066	Clang parses Doxygen and non-Doxygen style documentation comments and attaches
2067	them to the appropriate declaration nodes. By default, it only parses
2068	Doxygen-style comments and ignores ordinary comments starting with ``//`` and
2069	``/*``.
2070
2071	.. option:: -Wdocumentation
2072
2073	Emit warnings about use of documentation comments. This warning group is off
2074	by default.
2075
2076	This includes checking that ``\param`` commands name parameters that actually
2077	present in the function signature, checking that ``\returns`` is used only on
2078	functions that actually return a value etc.
2079
2080	.. option:: -Wno-documentation-unknown-command
2081
2082	Don't warn when encountering an unknown Doxygen command.
2083
2084	.. option:: -fparse-all-comments
2085
2086	Parse all comments as documentation comments (including ordinary comments
2087	starting with ``//`` and ``/*``).
2088
2089	.. option:: -fcomment-block-commands=[commands]
2090
2091	Define custom documentation commands as block commands. This allows Clang to
2092	construct the correct AST for these custom commands, and silences warnings
2093	about unknown commands. Several commands must be separated by a comma
2094	without trailing space; e.g. ``-fcomment-block-commands=foo,bar`` defines
2095	custom commands ``\foo`` and ``\bar``.
2096
2097	It is also possible to use ``-fcomment-block-commands`` several times; e.g.
2098	``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same
2099	as above.
2100
2101	.. _c:
2102
2103	C Language Features
2104	===================
2105
2106	The support for standard C in clang is feature-complete except for the
2107	C99 floating-point pragmas.
2108
2109	Extensions supported by clang
2110	-----------------------------
2111
2112	See :doc:`LanguageExtensions`.
2113
2114	Differences between various standard modes
2115	------------------------------------------
2116
2117	clang supports the -std option, which changes what language mode clang
2118	uses. The supported modes for C are c89, gnu89, c99, gnu99, c11, gnu11,
2119	c17, gnu17, and various aliases for those modes. If no -std option is
2120	specified, clang defaults to gnu11 mode. Many C99 and C11 features are
2121	supported in earlier modes as a conforming extension, with a warning. Use
2122	``-pedantic-errors`` to request an error if a feature from a later standard
2123	revision is used in an earlier mode.
2124
2125	Differences between all ``c`` and ``gnu`` modes:
2126
2127	- ``c*`` modes define "``__STRICT_ANSI__``".
2128	- Target-specific defines not prefixed by underscores, like "linux",
2129	are defined in ``gnu*`` modes.
2130	- Trigraphs default to being off in ``gnu*`` modes; they can be enabled by
2131	the -trigraphs option.
2132	- The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes;
2133	the variants "``__asm__``" and "``__typeof__``" are recognized in all
2134	modes.
2135	- The Apple "blocks" extension is recognized by default in ``gnu*`` modes
2136	on some platforms; it can be enabled in any mode with the "-fblocks"
2137	option.
2138	- Arrays that are VLA's according to the standard, but which can be
2139	constant folded by the frontend are treated as fixed size arrays.
2140	This occurs for things like "int X[(1, 2)];", which is technically a
2141	VLA. ``c*`` modes are strictly compliant and treat these as VLAs.
2142
2143	Differences between ``89`` and ``99`` modes:
2144
2145	- The ``*99`` modes default to implementing "inline" as specified in C99,
2146	while the ``*89`` modes implement the GNU version. This can be
2147	overridden for individual functions with the ``__gnu_inline__``
2148	attribute.
2149	- Digraphs are not recognized in c89 mode.
2150	- The scope of names defined inside a "for", "if", "switch", "while",
2151	or "do" statement is different. (example: "``if ((struct x {int
2152	x;}*)0) {}``".)
2153	- ``__STDC_VERSION__`` is not defined in ``*89`` modes.
2154	- "inline" is not recognized as a keyword in c89 mode.
2155	- "restrict" is not recognized as a keyword in ``*89`` modes.
2156	- Commas are allowed in integer constant expressions in ``*99`` modes.
2157	- Arrays which are not lvalues are not implicitly promoted to pointers
2158	in ``*89`` modes.
2159	- Some warnings are different.
2160
2161	Differences between ``99`` and ``11`` modes:
2162
2163	- Warnings for use of C11 features are disabled.
2164	- ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``.
2165
2166	Differences between ``11`` and ``17`` modes:
2167
2168	- ``__STDC_VERSION__`` is defined to ``201710L`` rather than ``201112L``.
2169
2170	GCC extensions not implemented yet
2171	----------------------------------
2172
2173	clang tries to be compatible with gcc as much as possible, but some gcc
2174	extensions are not implemented yet:
2175
2176	- clang does not support decimal floating point types (``_Decimal32`` and
2177	friends) or fixed-point types (``_Fract`` and friends); nobody has
2178	expressed interest in these features yet, so it's hard to say when
2179	they will be implemented.
2180	- clang does not support nested functions; this is a complex feature
2181	which is infrequently used, so it is unlikely to be implemented
2182	anytime soon. In C++11 it can be emulated by assigning lambda
2183	functions to local variables, e.g:
2184
2185	.. code-block:: cpp
2186
2187	auto const local_function = [&](int parameter) {
2188	// Do something
2189	};
2190	...
2191	local_function(1);
2192
2193	- clang only supports global register variables when the register specified
2194	is non-allocatable (e.g. the stack pointer). Support for general global
2195	register variables is unlikely to be implemented soon because it requires
2196	additional LLVM backend support.
2197	- clang does not support static initialization of flexible array
2198	members. This appears to be a rarely used extension, but could be
2199	implemented pending user demand.
2200	- clang does not support
2201	``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
2202	used rarely, but in some potentially interesting places, like the
2203	glibc headers, so it may be implemented pending user demand. Note
2204	that because clang pretends to be like GCC 4.2, and this extension
2205	was introduced in 4.3, the glibc headers will not try to use this
2206	extension with clang at the moment.
2207	- clang does not support the gcc extension for forward-declaring
2208	function parameters; this has not shown up in any real-world code
2209	yet, though, so it might never be implemented.
2210
2211	This is not a complete list; if you find an unsupported extension
2212	missing from this list, please send an e-mail to cfe-dev. This list
2213	currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this
2214	list does not include bugs in mostly-implemented features; please see
2215	the `bug
2216	tracker <https://bugs.llvm.org/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_
2217	for known existing bugs (FIXME: Is there a section for bug-reporting
2218	guidelines somewhere?).
2219
2220	Intentionally unsupported GCC extensions
2221	----------------------------------------
2222
2223	- clang does not support the gcc extension that allows variable-length
2224	arrays in structures. This is for a few reasons: one, it is tricky to
2225	implement, two, the extension is completely undocumented, and three,
2226	the extension appears to be rarely used. Note that clang does
2227	support flexible array members (arrays with a zero or unspecified
2228	size at the end of a structure).
2229	- clang does not have an equivalent to gcc's "fold"; this means that
2230	clang doesn't accept some constructs gcc might accept in contexts
2231	where a constant expression is required, like "x-x" where x is a
2232	variable.
2233	- clang does not support ``__builtin_apply`` and friends; this extension
2234	is extremely obscure and difficult to implement reliably.
2235
2236	.. _c_ms:
2237
2238	Microsoft extensions
2239	--------------------
2240
2241	clang has support for many extensions from Microsoft Visual C++. To enable these
2242	extensions, use the ``-fms-extensions`` command-line option. This is the default
2243	for Windows targets. Clang does not implement every pragma or declspec provided
2244	by MSVC, but the popular ones, such as ``__declspec(dllexport)`` and ``#pragma
2245	comment(lib)`` are well supported.
2246
2247	clang has a ``-fms-compatibility`` flag that makes clang accept enough
2248	invalid C++ to be able to parse most Microsoft headers. For example, it
2249	allows `unqualified lookup of dependent base class members
2250	<https://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
2251	a common compatibility issue with clang. This flag is enabled by default
2252	for Windows targets.
2253
2254	``-fdelayed-template-parsing`` lets clang delay parsing of function template
2255	definitions until the end of a translation unit. This flag is enabled by
2256	default for Windows targets.
2257
2258	For compatibility with existing code that compiles with MSVC, clang defines the
2259	``_MSC_VER`` and ``_MSC_FULL_VER`` macros. These default to the values of 1800
2260	and 180000000 respectively, making clang look like an early release of Visual
2261	C++ 2013. The ``-fms-compatibility-version=`` flag overrides these values. It
2262	accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC
2263	compatibility version makes clang behave more like that version of MSVC. For
2264	example, ``-fms-compatibility-version=19`` will enable C++14 features and define
2265	``char16_t`` and ``char32_t`` as builtin types.
2266
2267	.. _cxx:
2268
2269	C++ Language Features
2270	=====================
2271
2272	clang fully implements all of standard C++98 except for exported
2273	templates (which were removed in C++11), and all of standard C++11
2274	and the current draft standard for C++1y.
2275
2276	Controlling implementation limits
2277	---------------------------------
2278
2279	.. option:: -fbracket-depth=N
2280
2281	Sets the limit for nested parentheses, brackets, and braces to N. The
2282	default is 256.
2283
2284	.. option:: -fconstexpr-depth=N
2285
2286	Sets the limit for recursive constexpr function invocations to N. The
2287	default is 512.
2288
2289	.. option:: -fconstexpr-steps=N
2290
2291	Sets the limit for the number of full-expressions evaluated in a single
2292	constant expression evaluation. The default is 1048576.
2293
2294	.. option:: -ftemplate-depth=N
2295
2296	Sets the limit for recursively nested template instantiations to N. The
2297	default is 1024.
2298
2299	.. option:: -foperator-arrow-depth=N
2300
2301	Sets the limit for iterative calls to 'operator->' functions to N. The
2302	default is 256.
2303
2304	.. _objc:
2305
2306	Objective-C Language Features
2307	=============================
2308
2309	.. _objcxx:
2310
2311	Objective-C++ Language Features
2312	===============================
2313
2314	.. _openmp:
2315
2316	OpenMP Features
2317	===============
2318
2319	Clang supports all OpenMP 4.5 directives and clauses. See :doc:`OpenMPSupport`
2320	for additional details.
2321
2322	Use `-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with
2323	`-fno-openmp`.
2324
2325	Use `-fopenmp-simd` to enable OpenMP simd features only, without linking
2326	the runtime library; for combined constructs
2327	(e.g. ``#pragma omp parallel for simd``) the non-simd directives and clauses
2328	will be ignored. This can be disabled with `-fno-openmp-simd`.
2329
2330	Controlling implementation limits
2331	---------------------------------
2332
2333	.. option:: -fopenmp-use-tls
2334
2335	Controls code generation for OpenMP threadprivate variables. In presence of
2336	this option all threadprivate variables are generated the same way as thread
2337	local variables, using TLS support. If `-fno-openmp-use-tls`
2338	is provided or target does not support TLS, code generation for threadprivate
2339	variables relies on OpenMP runtime library.
2340
2341	.. _opencl:
2342
2343	OpenCL Features
2344	===============
2345
2346	Clang can be used to compile OpenCL kernels for execution on a device
2347	(e.g. GPU). It is possible to compile the kernel into a binary (e.g. for AMD or
2348	Nvidia targets) that can be uploaded to run directly on a device (e.g. using
2349	`clCreateProgramWithBinary
2350	<https://www.khronos.org/registry/OpenCL/specs/opencl-1.1.pdf#111>`_) or
2351	into generic bitcode files loadable into other toolchains.
2352
2353	Compiling to a binary using the default target from the installation can be done
2354	as follows:
2355
2356	.. code-block:: console
2357
2358	$ echo "kernel void k(){}" > test.cl
2359	$ clang test.cl
2360
2361	Compiling for a specific target can be done by specifying the triple corresponding
2362	to the target, for example:
2363
2364	.. code-block:: console
2365
2366	$ clang -target nvptx64-unknown-unknown test.cl
2367	$ clang -target amdgcn-amd-amdhsa -mcpu=gfx900 test.cl
2368
2369	Compiling to bitcode can be done as follows:
2370
2371	.. code-block:: console
2372
2373	$ clang -c -emit-llvm test.cl
2374
2375	This will produce a generic test.bc file that can be used in vendor toolchains
2376	to perform machine code generation.
2377
2378	Clang currently supports OpenCL C language standards up to v2.0.
2379
2380	OpenCL Specific Options
2381	-----------------------
2382
2383	Most of the OpenCL build options from `the specification v2.0 section 5.8.4
2384	<https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf#200>`_ are available.
2385
2386	Examples:
2387
2388	.. code-block:: console
2389
2390	$ clang -cl-std=CL2.0 -cl-single-precision-constant test.cl
2391
2392	Some extra options are available to support special OpenCL features.
2393
2394	.. option:: -finclude-default-header
2395
2396	Loads standard includes during compilations. By default OpenCL headers are not
2397	loaded and therefore standard library includes are not available. To load them
2398	automatically a flag has been added to the frontend (see also :ref:`the section
2399	on the OpenCL Header <opencl_header>`):
2400
2401	.. code-block:: console
2402
2403	$ clang -Xclang -finclude-default-header test.cl
2404
2405	Alternatively ``-include`` or ``-I`` followed by the path to the header location
2406	can be given manually.
2407
2408	.. code-block:: console
2409
2410	$ clang -I<path to clang>/lib/Headers/opencl-c.h test.cl
2411
2412	In this case the kernel code should contain ``#include <opencl-c.h>`` just as a
2413	regular C include.
2414
2415	.. _opencl_cl_ext:
2416
2417	.. option:: -cl-ext
2418
2419	Disables support of OpenCL extensions. All OpenCL targets provide a list
2420	of extensions that they support. Clang allows to amend this using the ``-cl-ext``
2421	flag with a comma-separated list of extensions prefixed with ``'+'`` or ``'-'``.
2422	The syntax: ``-cl-ext=<(['-'\|'+']<extension>[,])+>``, where extensions
2423	can be either one of `the OpenCL specification extensions
2424	<https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/EXTENSION.html>`_
2425	or any known vendor extension. Alternatively, ``'all'`` can be used to enable
2426	or disable all known extensions.
2427	Example disabling double support for the 64-bit SPIR target:
2428
2429	.. code-block:: console
2430
2431	$ clang -cc1 -triple spir64-unknown-unknown -cl-ext=-cl_khr_fp64 test.cl
2432
2433	Enabling all extensions except double support in R600 AMD GPU can be done using:
2434
2435	.. code-block:: console
2436
2437	$ clang -cc1 -triple r600-unknown-unknown -cl-ext=-all,+cl_khr_fp16 test.cl
2438
2439	.. _opencl_fake_address_space_map:
2440
2441	.. option:: -ffake-address-space-map
2442
2443	Overrides the target address space map with a fake map.
2444	This allows adding explicit address space IDs to the bitcode for non-segmented
2445	memory architectures that don't have separate IDs for each of the OpenCL
2446	logical address spaces by default. Passing ``-ffake-address-space-map`` will
2447	add/override address spaces of the target compiled for with the following values:
2448	``1-global``, ``2-constant``, ``3-local``, ``4-generic``. The private address
2449	space is represented by the absence of an address space attribute in the IR (see
2450	also :ref:`the section on the address space attribute <opencl_addrsp>`).
2451
2452	.. code-block:: console
2453
2454	$ clang -ffake-address-space-map test.cl
2455
2456	Some other flags used for the compilation for C can also be passed while
2457	compiling for OpenCL, examples: ``-c``, ``-O<1-4\|s>``, ``-o``, ``-emit-llvm``, etc.
2458
2459	OpenCL Targets
2460	--------------
2461
2462	OpenCL targets are derived from the regular Clang target classes. The OpenCL
2463	specific parts of the target representation provide address space mapping as
2464	well as a set of supported extensions.
2465
2466	Specific Targets
2467	^^^^^^^^^^^^^^^^
2468
2469	There is a set of concrete HW architectures that OpenCL can be compiled for.
2470
2471	- For AMD target:
2472
2473	.. code-block:: console
2474
2475	$ clang -target amdgcn-amd-amdhsa -mcpu=gfx900 test.cl
2476
2477	- For Nvidia architectures:
2478
2479	.. code-block:: console
2480
2481	$ clang -target nvptx64-unknown-unknown test.cl
2482
2483
2484	Generic Targets
2485	^^^^^^^^^^^^^^^
2486
2487	- SPIR is available as a generic target to allow portable bitcode to be produced
2488	that can be used across GPU toolchains. The implementation follows `the SPIR
2489	specification <https://www.khronos.org/spir>`_. There are two flavors
2490	available for 32 and 64 bits.
2491
2492	.. code-block:: console
2493
2494	$ clang -target spir-unknown-unknown test.cl
2495	$ clang -target spir64-unknown-unknown test.cl
2496
2497	All known OpenCL extensions are supported in the SPIR targets. Clang will
2498	generate SPIR v1.2 compatible IR for OpenCL versions up to 2.0 and SPIR v2.0
2499	for OpenCL v2.0.
2500
2501	- x86 is used by some implementations that are x86 compatible and currently
2502	remains for backwards compatibility (with older implementations prior to
2503	SPIR target support). For "non-SPMD" targets which cannot spawn multiple
2504	work-items on the fly using hardware, which covers practically all non-GPU
2505	devices such as CPUs and DSPs, additional processing is needed for the kernels
2506	to support multiple work-item execution. For this, a 3rd party toolchain,
2507	such as for example `POCL <http://portablecl.org/>`_, can be used.
2508
2509	This target does not support multiple memory segments and, therefore, the fake
2510	address space map can be added using the :ref:`-ffake-address-space-map
2511	<opencl_fake_address_space_map>` flag.
2512
2513	.. _opencl_header:
2514
2515	OpenCL Header
2516	-------------
2517
2518	By default Clang will not include standard headers and therefore OpenCL builtin
2519	functions and some types (i.e. vectors) are unknown. The default CL header is,
2520	however, provided in the Clang installation and can be enabled by passing the
2521	``-finclude-default-header`` flag to the Clang frontend.
2522
2523	.. code-block:: console
2524
2525	$ echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl
2526	$ clang -Xclang -finclude-default-header -cl-std=CL2.0 test.cl
2527
2528	Because the header is very large and long to parse, PCH (:doc:`PCHInternals`)
2529	and modules (:doc:`Modules`) are used internally to improve the compilation
2530	speed.
2531
2532	To enable modules for OpenCL:
2533
2534	.. code-block:: console
2535
2536	$ clang -target spir-unknown-unknown -c -emit-llvm -Xclang -finclude-default-header -fmodules -fimplicit-module-maps -fmodules-cache-path=<path to the generated module> test.cl
2537
2538	OpenCL Extensions
2539	-----------------
2540
2541	All of the ``cl_khr_*`` extensions from `the official OpenCL specification
2542	<https://www.khronos.org/registry/OpenCL/sdk/2.0/docs/man/xhtml/EXTENSION.html>`_
2543	up to and including version 2.0 are available and set per target depending on the
2544	support available in the specific architecture.
2545
2546	It is possible to alter the default extensions setting per target using
2547	``-cl-ext`` flag. (See :ref:`flags description <opencl_cl_ext>` for more details).
2548
2549	Vendor extensions can be added flexibly by declaring the list of types and
2550	functions associated with each extensions enclosed within the following
2551	compiler pragma directives:
2552
2553	.. code-block:: c
2554
2555	#pragma OPENCL EXTENSION the_new_extension_name : begin
2556	// declare types and functions associated with the extension here
2557	#pragma OPENCL EXTENSION the_new_extension_name : end
2558
2559	For example, parsing the following code adds ``my_t`` type and ``my_func``
2560	function to the custom ``my_ext`` extension.
2561
2562	.. code-block:: c
2563
2564	#pragma OPENCL EXTENSION my_ext : begin
2565	typedef struct{
2566	int a;
2567	}my_t;
2568	void my_func(my_t);
2569	#pragma OPENCL EXTENSION my_ext : end
2570
2571	Declaring the same types in different vendor extensions is disallowed.
2572
2573	OpenCL Metadata
2574	---------------
2575
2576	Clang uses metadata to provide additional OpenCL semantics in IR needed for
2577	backends and OpenCL runtime.
2578
2579	Each kernel will have function metadata attached to it, specifying the arguments.
2580	Kernel argument metadata is used to provide source level information for querying
2581	at runtime, for example using the `clGetKernelArgInfo
2582	<https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167>`_
2583	call.
2584
2585	Note that ``-cl-kernel-arg-info`` enables more information about the original CL
2586	code to be added e.g. kernel parameter names will appear in the OpenCL metadata
2587	along with other information.
2588
2589	The IDs used to encode the OpenCL's logical address spaces in the argument info
2590	metadata follows the SPIR address space mapping as defined in the SPIR
2591	specification `section 2.2
2592	<https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18>`_
2593
2594	OpenCL-Specific Attributes
2595	--------------------------
2596
2597	OpenCL support in Clang contains a set of attribute taken directly from the
2598	specification as well as additional attributes.
2599
2600	See also :doc:`AttributeReference`.
2601
2602	nosvm
2603	^^^^^
2604
2605	Clang supports this attribute to comply to OpenCL v2.0 conformance, but it
2606	does not have any effect on the IR. For more details reffer to the specification
2607	`section 6.7.2
2608	<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#49>`_
2609
2610
2611	opencl_unroll_hint
2612	^^^^^^^^^^^^^^^^^^
2613
2614	The implementation of this feature mirrors the unroll hint for C.
2615	More details on the syntax can be found in the specification
2616	`section 6.11.5
2617	<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#61>`_
2618
2619	convergent
2620	^^^^^^^^^^
2621
2622	To make sure no invalid optimizations occur for single program multiple data
2623	(SPMD) / single instruction multiple thread (SIMT) Clang provides attributes that
2624	can be used for special functions that have cross work item semantics.
2625	An example is the subgroup operations such as `intel_sub_group_shuffle
2626	<https://www.khronos.org/registry/cl/extensions/intel/cl_intel_subgroups.txt>`_
2627
2628	.. code-block:: c
2629
2630	// Define custom my_sub_group_shuffle(data, c)
2631	// that makes use of intel_sub_group_shuffle
2632	r1 = ...
2633	if (r0) r1 = computeA();
2634	// Shuffle data from r1 into r3
2635	// of threads id r2.
2636	r3 = my_sub_group_shuffle(r1, r2);
2637	if (r0) r3 = computeB();
2638
2639	with non-SPMD semantics this is optimized to the following equivalent code:
2640
2641	.. code-block:: c
2642
2643	r1 = ...
2644	if (!r0)
2645	// Incorrect functionality! The data in r1
2646	// have not been computed by all threads yet.
2647	r3 = my_sub_group_shuffle(r1, r2);
2648	else {
2649	r1 = computeA();
2650	r3 = my_sub_group_shuffle(r1, r2);
2651	r3 = computeB();
2652	}
2653
2654	Declaring the function ``my_sub_group_shuffle`` with the convergent attribute
2655	would prevent this:
2656
2657	.. code-block:: c
2658
2659	my_sub_group_shuffle() __attribute__((convergent));
2660
2661	Using ``convergent`` guarantees correct execution by keeping CFG equivalence
2662	wrt operations marked as ``convergent``. CFG ``G´`` is equivalent to ``G`` wrt
2663	node ``Ni`` : ``iff ∀ Nj (i≠j)`` domination and post-domination relations with
2664	respect to ``Ni`` remain the same in both ``G`` and ``G´``.
2665
2666	noduplicate
2667	^^^^^^^^^^^
2668
2669	``noduplicate`` is more restrictive with respect to optimizations than
2670	``convergent`` because a convergent function only preserves CFG equivalence.
2671	This allows some optimizations to happen as long as the control flow remains
2672	unmodified.
2673
2674	.. code-block:: c
2675
2676	for (int i=0; i<4; i++)
2677	my_sub_group_shuffle()
2678
2679	can be modified to:
2680
2681	.. code-block:: c
2682
2683	my_sub_group_shuffle();
2684	my_sub_group_shuffle();
2685	my_sub_group_shuffle();
2686	my_sub_group_shuffle();
2687
2688	while using ``noduplicate`` would disallow this. Also ``noduplicate`` doesn't
2689	have the same safe semantics of CFG as ``convergent`` and can cause changes in
2690	CFG that modify semantics of the original program.
2691
2692	``noduplicate`` is kept for backwards compatibility only and it considered to be
2693	deprecated for future uses.
2694
2695	.. _opencl_addrsp:
2696
2697	address_space
2698	^^^^^^^^^^^^^
2699
2700	Clang has arbitrary address space support using the ``address_space(N)``
2701	attribute, where ``N`` is an integer number in the range ``0`` to ``16777215``
2702	(``0xffffffu``).
2703
2704	An OpenCL implementation provides a list of standard address spaces using
2705	keywords: ``private``, ``local``, ``global``, and ``generic``. In the AST and
2706	in the IR local, global, or generic will be represented by the address space
2707	attribute with the corresponding unique number. Note that private does not have
2708	any corresponding attribute added and, therefore, is represented by the absence
2709	of an address space number. The specific IDs for an address space do not have to
2710	match between the AST and the IR. Typically in the AST address space numbers
2711	represent logical segments while in the IR they represent physical segments.
2712	Therefore, machines with flat memory segments can map all AST address space
2713	numbers to the same physical segment ID or skip address space attribute
2714	completely while generating the IR. However, if the address space information
2715	is needed by the IR passes e.g. to improve alias analysis, it is recommended
2716	to keep it and only lower to reflect physical memory segments in the late
2717	machine passes.
2718
2719	OpenCL builtins
2720	---------------
2721
2722	There are some standard OpenCL functions that are implemented as Clang builtins:
2723
2724	- All pipe functions from `section 6.13.16.2/6.13.16.3
2725	<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#160>`_ of
2726	the OpenCL v2.0 kernel language specification. `
2727
2728	- Address space qualifier conversion functions ``to_global``/``to_local``/``to_private``
2729	from `section 6.13.9
2730	<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#101>`_.
2731
2732	- All the ``enqueue_kernel`` functions from `section 6.13.17.1
2733	<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#164>`_ and
2734	enqueue query functions from `section 6.13.17.5
2735	<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171>`_.
2736
2737	.. _target_features:
2738
2739	Target-Specific Features and Limitations
2740	========================================
2741
2742	CPU Architectures Features and Limitations
2743	------------------------------------------
2744
2745	X86
2746	^^^
2747
2748	The support for X86 (both 32-bit and 64-bit) is considered stable on
2749	Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
2750	to correctly compile many large C, C++, Objective-C, and Objective-C++
2751	codebases.
2752
2753	On ``x86_64-mingw32``, passing i128(by value) is incompatible with the
2754	Microsoft x64 calling convention. You might need to tweak
2755	``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
2756
2757	For the X86 target, clang supports the `-m16` command line
2758	argument which enables 16-bit code output. This is broadly similar to
2759	using ``asm(".code16gcc")`` with the GNU toolchain. The generated code
2760	and the ABI remains 32-bit but the assembler emits instructions
2761	appropriate for a CPU running in 16-bit mode, with address-size and
2762	operand-size prefixes to enable 32-bit addressing and operations.
2763
2764	ARM
2765	^^^
2766
2767	The support for ARM (specifically ARMv6 and ARMv7) is considered stable
2768	on Darwin (iOS): it has been tested to correctly compile many large C,
2769	C++, Objective-C, and Objective-C++ codebases. Clang only supports a
2770	limited number of ARM architectures. It does not yet fully support
2771	ARMv5, for example.
2772
2773	PowerPC
2774	^^^^^^^
2775
2776	The support for PowerPC (especially PowerPC64) is considered stable
2777	on Linux and FreeBSD: it has been tested to correctly compile many
2778	large C and C++ codebases. PowerPC (32bit) is still missing certain
2779	features (e.g. PIC code on ELF platforms).
2780
2781	Other platforms
2782	^^^^^^^^^^^^^^^
2783
2784	clang currently contains some support for other architectures (e.g. Sparc);
2785	however, significant pieces of code generation are still missing, and they
2786	haven't undergone significant testing.
2787
2788	clang contains limited support for the MSP430 embedded processor, but
2789	both the clang support and the LLVM backend support are highly
2790	experimental.
2791
2792	Other platforms are completely unsupported at the moment. Adding the
2793	minimal support needed for parsing and semantic analysis on a new
2794	platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source
2795	tree. This level of support is also sufficient for conversion to LLVM IR
2796	for simple programs. Proper support for conversion to LLVM IR requires
2797	adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
2798	change soon, though. Generating assembly requires a suitable LLVM
2799	backend.
2800
2801	Operating System Features and Limitations
2802	-----------------------------------------
2803
2804	Darwin (Mac OS X)
2805	^^^^^^^^^^^^^^^^^
2806
2807	Thread Sanitizer is not supported.
2808
2809	Windows
2810	^^^^^^^
2811
2812	Clang has experimental support for targeting "Cygming" (Cygwin / MinGW)
2813	platforms.
2814
2815	See also :ref:`Microsoft Extensions <c_ms>`.
2816
2817	Cygwin
2818	""""""
2819
2820	Clang works on Cygwin-1.7.
2821
2822	MinGW32
2823	"""""""
2824
2825	Clang works on some mingw32 distributions. Clang assumes directories as
2826	below;
2827
2828	- ``C:/mingw/include``
2829	- ``C:/mingw/lib``
2830	- ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
2831
2832	On MSYS, a few tests might fail.
2833
2834	MinGW-w64
2835	"""""""""
2836
2837	For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
2838	assumes as below;
2839
2840	- ``GCC versions 4.5.0 to 4.5.3, 4.6.0 to 4.6.2, or 4.7.0 (for the C++ header search path)``
2841	- ``some_directory/bin/gcc.exe``
2842	- ``some_directory/bin/clang.exe``
2843	- ``some_directory/bin/clang++.exe``
2844	- ``some_directory/bin/../include/c++/GCC_version``
2845	- ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
2846	- ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
2847	- ``some_directory/bin/../include/c++/GCC_version/backward``
2848	- ``some_directory/bin/../x86_64-w64-mingw32/include``
2849	- ``some_directory/bin/../i686-w64-mingw32/include``
2850	- ``some_directory/bin/../include``
2851
2852	This directory layout is standard for any toolchain you will find on the
2853	official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
2854
2855	Clang expects the GCC executable "gcc.exe" compiled for
2856	``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
2857
2858	`Some tests might fail <https://bugs.llvm.org/show_bug.cgi?id=9072>`_ on
2859	``x86_64-w64-mingw32``.
2860
2861	.. _clang-cl:
2862
2863	clang-cl
2864	========
2865
2866	clang-cl is an alternative command-line interface to Clang, designed for
2867	compatibility with the Visual C++ compiler, cl.exe.
2868
2869	To enable clang-cl to find system headers, libraries, and the linker when run
2870	from the command-line, it should be executed inside a Visual Studio Native Tools
2871	Command Prompt or a regular Command Prompt where the environment has been set
2872	up using e.g. `vcvarsall.bat <https://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
2873
2874	clang-cl can also be used from inside Visual Studio by selecting the LLVM
2875	Platform Toolset. The toolset is not part of the installer, but may be installed
2876	separately from the
2877	`Visual Studio Marketplace <https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.llvm-toolchain>`_.
2878	To use the toolset, select a project in Solution Explorer, open its Property
2879	Page (Alt+F7), and in the "General" section of "Configuration Properties"
2880	change "Platform Toolset" to LLVM. Doing so enables an additional Property
2881	Page for selecting the clang-cl executable to use for builds.
2882
2883	To use the toolset with MSBuild directly, invoke it with e.g.
2884	``/p:PlatformToolset=LLVM``. This allows trying out the clang-cl toolchain
2885	without modifying your project files.
2886
2887	It's also possible to point MSBuild at clang-cl without changing toolset by
2888	passing ``/p:CLToolPath=c:\llvm\bin /p:CLToolExe=clang-cl.exe``.
2889
2890	When using CMake and the Visual Studio generators, the toolset can be set with the ``-T`` flag:
2891
2892	::
2893
2894	cmake -G"Visual Studio 15 2017" -T LLVM ..
2895
2896	When using CMake with the Ninja generator, set the ``CMAKE_C_COMPILER`` and
2897	``CMAKE_CXX_COMPILER`` variables to clang-cl:
2898
2899	::
2900
2901	cmake -GNinja -DCMAKE_C_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe"
2902	-DCMAKE_CXX_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe" ..
2903
2904
2905	Command-Line Options
2906	--------------------
2907
2908	To be compatible with cl.exe, clang-cl supports most of the same command-line
2909	options. Those options can start with either ``/`` or ``-``. It also supports
2910	some of Clang's core options, such as the ``-W`` options.
2911
2912	Options that are known to clang-cl, but not currently supported, are ignored
2913	with a warning. For example:
2914
2915	::
2916
2917	clang-cl.exe: warning: argument unused during compilation: '/AI'
2918
2919	To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option.
2920
2921	Options that are not known to clang-cl will be ignored by default. Use the
2922	``-Werror=unknown-argument`` option in order to treat them as errors. If these
2923	options are spelled with a leading ``/``, they will be mistaken for a filename:
2924
2925	::
2926
2927	clang-cl.exe: error: no such file or directory: '/foobar'
2928
2929	Please `file a bug <https://bugs.llvm.org/enter_bug.cgi?product=clang&component=Driver>`_
2930	for any valid cl.exe flags that clang-cl does not understand.
2931
2932	Execute ``clang-cl /?`` to see a list of supported options:
2933
2934	::
2935
2936	CL.EXE COMPATIBILITY OPTIONS:
2937	/? Display available options
2938	/arch:<value> Set architecture for code generation
2939	/Brepro- Emit an object file which cannot be reproduced over time
2940	/Brepro Emit an object file which can be reproduced over time
2941	/clang:<arg> Pass <arg> to the clang driver
2942	/C Don't discard comments when preprocessing
2943	/c Compile only
2944	/d1PP Retain macro definitions in /E mode
2945	/d1reportAllClassLayout Dump record layout information
2946	/diagnostics:caret Enable caret and column diagnostics (on by default)
2947	/diagnostics:classic Disable column and caret diagnostics
2948	/diagnostics:column Disable caret diagnostics but keep column info
2949	/D <macro[=value]> Define macro
2950	/EH<value> Exception handling model
2951	/EP Disable linemarker output and preprocess to stdout
2952	/execution-charset:<value>
2953	Runtime encoding, supports only UTF-8
2954	/E Preprocess to stdout
2955	/fallback Fall back to cl.exe if clang-cl fails to compile
2956	/FA Output assembly code file during compilation
2957	/Fa<file or directory> Output assembly code to this file during compilation (with /FA)
2958	/Fe<file or directory> Set output executable file or directory (ends in / or \)
2959	/FI <value> Include file before parsing
2960	/Fi<file> Set preprocess output file name (with /P)
2961	/Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c)
2962	/fp:except-
2963	/fp:except
2964	/fp:fast
2965	/fp:precise
2966	/fp:strict
2967	/Fp<filename> Set pch filename (with /Yc and /Yu)
2968	/GA Assume thread-local variables are defined in the executable
2969	/Gd Set __cdecl as a default calling convention
2970	/GF- Disable string pooling
2971	/GF Enable string pooling (default)
2972	/GR- Disable emission of RTTI data
2973	/Gregcall Set __regcall as a default calling convention
2974	/GR Enable emission of RTTI data
2975	/Gr Set __fastcall as a default calling convention
2976	/GS- Disable buffer security check
2977	/GS Enable buffer security check (default)
2978	/Gs Use stack probes (default)
2979	/Gs<value> Set stack probe size (default 4096)
2980	/guard:<value> Enable Control Flow Guard with /guard:cf,
2981	or only the table with /guard:cf,nochecks
2982	/Gv Set __vectorcall as a default calling convention
2983	/Gw- Don't put each data item in its own section
2984	/Gw Put each data item in its own section
2985	/GX- Disable exception handling
2986	/GX Enable exception handling
2987	/Gy- Don't put each function in its own section (default)
2988	/Gy Put each function in its own section
2989	/Gz Set __stdcall as a default calling convention
2990	/help Display available options
2991	/imsvc <dir> Add directory to system include search path, as if part of %INCLUDE%
2992	/I <dir> Add directory to include search path
2993	/J Make char type unsigned
2994	/LDd Create debug DLL
2995	/LD Create DLL
2996	/link <options> Forward options to the linker
2997	/MDd Use DLL debug run-time
2998	/MD Use DLL run-time
2999	/MTd Use static debug run-time
3000	/MT Use static run-time
3001	/O0 Disable optimization
3002	/O1 Optimize for size (same as /Og /Os /Oy /Ob2 /GF /Gy)
3003	/O2 Optimize for speed (same as /Og /Oi /Ot /Oy /Ob2 /GF /Gy)
3004	/Ob0 Disable function inlining
3005	/Ob1 Only inline functions which are (explicitly or implicitly) marked inline
3006	/Ob2 Inline functions as deemed beneficial by the compiler
3007	/Od Disable optimization
3008	/Og No effect
3009	/Oi- Disable use of builtin functions
3010	/Oi Enable use of builtin functions
3011	/Os Optimize for size
3012	/Ot Optimize for speed
3013	/Ox Deprecated (same as /Og /Oi /Ot /Oy /Ob2); use /O2 instead
3014	/Oy- Disable frame pointer omission (x86 only, default)
3015	/Oy Enable frame pointer omission (x86 only)
3016	/O<flags> Set multiple /O flags at once; e.g. '/O2y-' for '/O2 /Oy-'
3017	/o <file or directory> Set output file or directory (ends in / or \)
3018	/P Preprocess to file
3019	/Qvec- Disable the loop vectorization passes
3020	/Qvec Enable the loop vectorization passes
3021	/showFilenames- Don't print the name of each compiled file (default)
3022	/showFilenames Print the name of each compiled file
3023	/showIncludes Print info about included files to stderr
3024	/source-charset:<value> Source encoding, supports only UTF-8
3025	/std:<value> Language standard to compile for
3026	/TC Treat all source files as C
3027	/Tc <filename> Specify a C source file
3028	/TP Treat all source files as C++
3029	/Tp <filename> Specify a C++ source file
3030	/utf-8 Set source and runtime encoding to UTF-8 (default)
3031	/U <macro> Undefine macro
3032	/vd<value> Control vtordisp placement
3033	/vmb Use a best-case representation method for member pointers
3034	/vmg Use a most-general representation for member pointers
3035	/vmm Set the default most-general representation to multiple inheritance
3036	/vms Set the default most-general representation to single inheritance
3037	/vmv Set the default most-general representation to virtual inheritance
3038	/volatile:iso Volatile loads and stores have standard semantics
3039	/volatile:ms Volatile loads and stores have acquire and release semantics
3040	/W0 Disable all warnings
3041	/W1 Enable -Wall
3042	/W2 Enable -Wall
3043	/W3 Enable -Wall
3044	/W4 Enable -Wall and -Wextra
3045	/Wall Enable -Weverything
3046	/WX- Do not treat warnings as errors
3047	/WX Treat warnings as errors
3048	/w Disable all warnings
3049	/X Don't add %INCLUDE% to the include search path
3050	/Y- Disable precompiled headers, overrides /Yc and /Yu
3051	/Yc<filename> Generate a pch file for all code up to and including <filename>
3052	/Yu<filename> Load a pch file and use it instead of all code up to and including <filename>
3053	/Z7 Enable CodeView debug information in object files
3054	/Zc:dllexportInlines- Don't dllexport/dllimport inline member functions of dllexport/import classes
3055	/Zc:dllexportInlines dllexport/dllimport inline member functions of dllexport/import classes (default)
3056	/Zc:sizedDealloc- Disable C++14 sized global deallocation functions
3057	/Zc:sizedDealloc Enable C++14 sized global deallocation functions
3058	/Zc:strictStrings Treat string literals as const
3059	/Zc:threadSafeInit- Disable thread-safe initialization of static variables
3060	/Zc:threadSafeInit Enable thread-safe initialization of static variables
3061	/Zc:trigraphs- Disable trigraphs (default)
3062	/Zc:trigraphs Enable trigraphs
3063	/Zc:twoPhase- Disable two-phase name lookup in templates
3064	/Zc:twoPhase Enable two-phase name lookup in templates
3065	/Zd Emit debug line number tables only
3066	/Zi Alias for /Z7. Does not produce PDBs.
3067	/Zl Don't mention any default libraries in the object file
3068	/Zp Set the default maximum struct packing alignment to 1
3069	/Zp<value> Specify the default maximum struct packing alignment
3070	/Zs Syntax-check only
3071
3072	OPTIONS:
3073	-### Print (but do not run) the commands to run for this compilation
3074	--analyze Run the static analyzer
3075	-faddrsig Emit an address-significance table
3076	-fansi-escape-codes Use ANSI escape codes for diagnostics
3077	-fblocks Enable the 'blocks' language feature
3078	-fcf-protection=<value> Instrument control-flow architecture protection. Options: return, branch, full, none.
3079	-fcf-protection Enable cf-protection in 'full' mode
3080	-fcolor-diagnostics Use colors in diagnostics
3081	-fcomplete-member-pointers
3082	Require member pointer base types to be complete if they would be significant under the Microsoft ABI
3083	-fcoverage-mapping Generate coverage mapping to enable code coverage analysis
3084	-fdebug-macro Emit macro debug information
3085	-fdelayed-template-parsing
3086	Parse templated function definitions at the end of the translation unit
3087	-fdiagnostics-absolute-paths
3088	Print absolute paths in diagnostics
3089	-fdiagnostics-parseable-fixits
3090	Print fix-its in machine parseable form
3091	-flto=<value> Set LTO mode to either 'full' or 'thin'
3092	-flto Enable LTO in 'full' mode
3093	-fmerge-all-constants Allow merging of constants
3094	-fms-compatibility-version=<value>
3095	Dot-separated value representing the Microsoft compiler version
3096	number to report in _MSC_VER (0 = don't define it (default))
3097	-fms-compatibility Enable full Microsoft Visual C++ compatibility
3098	-fms-extensions Accept some non-standard constructs supported by the Microsoft compiler
3099	-fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER
3100	(0 = don't define it (default))
3101	-fno-addrsig Don't emit an address-significance table
3102	-fno-builtin-<value> Disable implicit builtin knowledge of a specific function
3103	-fno-builtin Disable implicit builtin knowledge of functions
3104	-fno-complete-member-pointers
3105	Do not require member pointer base types to be complete if they would be significant under the Microsoft ABI
3106	-fno-coverage-mapping Disable code coverage analysis
3107	-fno-crash-diagnostics Disable auto-generation of preprocessed source files and a script for reproduction during a clang crash
3108	-fno-debug-macro Do not emit macro debug information
3109	-fno-delayed-template-parsing
3110	Disable delayed template parsing
3111	-fno-sanitize-address-poison-custom-array-cookie
3112	Disable poisoning array cookies when using custom operator new[] in AddressSanitizer
3113	-fno-sanitize-address-use-after-scope
3114	Disable use-after-scope detection in AddressSanitizer
3115	-fno-sanitize-address-use-odr-indicator
3116	Disable ODR indicator globals
3117	-fno-sanitize-blacklist Don't use blacklist file for sanitizers
3118	-fno-sanitize-cfi-cross-dso
3119	Disable control flow integrity (CFI) checks for cross-DSO calls.
3120	-fno-sanitize-coverage=<value>
3121	Disable specified features of coverage instrumentation for Sanitizers
3122	-fno-sanitize-memory-track-origins
3123	Disable origins tracking in MemorySanitizer
3124	-fno-sanitize-memory-use-after-dtor
3125	Disable use-after-destroy detection in MemorySanitizer
3126	-fno-sanitize-recover=<value>
3127	Disable recovery for specified sanitizers
3128	-fno-sanitize-stats Disable sanitizer statistics gathering.
3129	-fno-sanitize-thread-atomics
3130	Disable atomic operations instrumentation in ThreadSanitizer
3131	-fno-sanitize-thread-func-entry-exit
3132	Disable function entry/exit instrumentation in ThreadSanitizer
3133	-fno-sanitize-thread-memory-access
3134	Disable memory access instrumentation in ThreadSanitizer
3135	-fno-sanitize-trap=<value>
3136	Disable trapping for specified sanitizers
3137	-fno-standalone-debug Limit debug information produced to reduce size of debug binary
3138	-fobjc-runtime=<value> Specify the target Objective-C runtime kind and version
3139	-fprofile-exclude-files=<value>
3140	Instrument only functions from files where names don't match all the regexes separated by a semi-colon
3141	-fprofile-filter-files=<value>
3142	Instrument only functions from files where names match any regex separated by a semi-colon
3143	-fprofile-instr-generate=<file>
3144	Generate instrumented code to collect execution counts into <file>
3145	(overridden by LLVM_PROFILE_FILE env var)
3146	-fprofile-instr-generate
3147	Generate instrumented code to collect execution counts into default.profraw file
3148	(overridden by '=' form of option or LLVM_PROFILE_FILE env var)
3149	-fprofile-instr-use=<value>
3150	Use instrumentation data for profile-guided optimization
3151	-fprofile-remapping-file=<file>
3152	Use the remappings described in <file> to match the profile data against names in the program
3153	-fsanitize-address-field-padding=<value>
3154	Level of field padding for AddressSanitizer
3155	-fsanitize-address-globals-dead-stripping
3156	Enable linker dead stripping of globals in AddressSanitizer
3157	-fsanitize-address-poison-custom-array-cookie
3158	Enable poisoning array cookies when using custom operator new[] in AddressSanitizer
3159	-fsanitize-address-use-after-scope
3160	Enable use-after-scope detection in AddressSanitizer
3161	-fsanitize-address-use-odr-indicator
3162	Enable ODR indicator globals to avoid false ODR violation reports in partially sanitized programs at the cost of an increase in binary size
3163	-fsanitize-blacklist=<value>
3164	Path to blacklist file for sanitizers
3165	-fsanitize-cfi-cross-dso
3166	Enable control flow integrity (CFI) checks for cross-DSO calls.
3167	-fsanitize-cfi-icall-generalize-pointers
3168	Generalize pointers in CFI indirect call type signature checks
3169	-fsanitize-coverage=<value>
3170	Specify the type of coverage instrumentation for Sanitizers
3171	-fsanitize-hwaddress-abi=<value>
3172	Select the HWAddressSanitizer ABI to target (interceptor or platform, default interceptor)
3173	-fsanitize-memory-track-origins=<value>
3174	Enable origins tracking in MemorySanitizer
3175	-fsanitize-memory-track-origins
3176	Enable origins tracking in MemorySanitizer
3177	-fsanitize-memory-use-after-dtor
3178	Enable use-after-destroy detection in MemorySanitizer
3179	-fsanitize-recover=<value>
3180	Enable recovery for specified sanitizers
3181	-fsanitize-stats Enable sanitizer statistics gathering.
3182	-fsanitize-thread-atomics
3183	Enable atomic operations instrumentation in ThreadSanitizer (default)
3184	-fsanitize-thread-func-entry-exit
3185	Enable function entry/exit instrumentation in ThreadSanitizer (default)
3186	-fsanitize-thread-memory-access
3187	Enable memory access instrumentation in ThreadSanitizer (default)
3188	-fsanitize-trap=<value> Enable trapping for specified sanitizers
3189	-fsanitize-undefined-strip-path-components=<number>
3190	Strip (or keep only, if negative) a given number of path components when emitting check metadata.
3191	-fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious
3192	behavior. See user manual for available checks
3193	-fsplit-lto-unit Enables splitting of the LTO unit.
3194	-fstandalone-debug Emit full debug info for all types used by the program
3195	-fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto
3196	-gcodeview-ghash Emit type record hashes in a .debug$H section
3197	-gcodeview Generate CodeView debug information
3198	-gline-directives-only Emit debug line info directives only
3199	-gline-tables-only Emit debug line number tables only
3200	-miamcu Use Intel MCU ABI
3201	-mllvm <value> Additional arguments to forward to LLVM's option processing
3202	-nobuiltininc Disable builtin #include directories
3203	-Qunused-arguments Don't emit warning for unused driver arguments
3204	-R<remark> Enable the specified remark
3205	--target=<value> Generate code for the given target
3206	--version Print version information
3207	-v Show commands to run and use verbose output
3208	-W<warning> Enable the specified warning
3209	-Xclang <arg> Pass <arg> to the clang compiler
3210
3211	The /clang: Option
3212	^^^^^^^^^^^^^^^^^^
3213
3214	When clang-cl is run with a set of ``/clang:<arg>`` options, it will gather all
3215	of the ``<arg>`` arguments and process them as if they were passed to the clang
3216	driver. This mechanism allows you to pass flags that are not exposed in the
3217	clang-cl options or flags that have a different meaning when passed to the clang
3218	driver. Regardless of where they appear in the command line, the ``/clang:``
3219	arguments are treated as if they were passed at the end of the clang-cl command
3220	line.
3221
3222	The /Zc:dllexportInlines- Option
3223	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3224
3225	This causes the class-level `dllexport` and `dllimport` attributes to not apply
3226	to inline member functions, as they otherwise would. For example, in the code
3227	below `S::foo()` would normally be defined and exported by the DLL, but when
3228	using the ``/Zc:dllexportInlines-`` flag it is not:
3229
3230	.. code-block:: c
3231
3232	struct __declspec(dllexport) S {
3233	void foo() {}
3234	}
3235
3236	This has the benefit that the compiler doesn't need to emit a definition of
3237	`S::foo()` in every translation unit where the declaration is included, as it
3238	would otherwise do to ensure there's a definition in the DLL even if it's not
3239	used there. If the declaration occurs in a header file that's widely used, this
3240	can save significant compilation time and output size. It also reduces the
3241	number of functions exported by the DLL similarly to what
3242	``-fvisibility-inlines-hidden`` does for shared objects on ELF and Mach-O.
3243	Since the function declaration comes with an inline definition, users of the
3244	library can use that definition directly instead of importing it from the DLL.
3245
3246	Note that the Microsoft Visual C++ compiler does not support this option, and
3247	if code in a DLL is compiled with ``/Zc:dllexportInlines-``, the code using the
3248	DLL must be compiled in the same way so that it doesn't attempt to dllimport
3249	the inline member functions. The reverse scenario should generally work though:
3250	a DLL compiled without this flag (such as a system library compiled with Visual
3251	C++) can be referenced from code compiled using the flag, meaning that the
3252	referencing code will use the inline definitions instead of importing them from
3253	the DLL.
3254
3255	Also note that like when using ``-fvisibility-inlines-hidden``, the address of
3256	`S::foo()` will be different inside and outside the DLL, breaking the C/C++
3257	standard requirement that functions have a unique address.
3258
3259	The flag does not apply to explicit class template instantiation definitions or
3260	declarations, as those are typically used to explicitly provide a single
3261	definition in a DLL, (dllexported instantiation definition) or to signal that
3262	the definition is available elsewhere (dllimport instantiation declaration). It
3263	also doesn't apply to inline members with static local variables, to ensure
3264	that the same instance of the variable is used inside and outside the DLL.
3265
3266	Using this flag can cause problems when inline functions that would otherwise
3267	be dllexported refer to internal symbols of a DLL. For example:
3268
3269	.. code-block:: c
3270
3271	void internal();
3272
3273	struct __declspec(dllimport) S {
3274	void foo() { internal(); }
3275	}
3276
3277	Normally, references to `S::foo()` would use the definition in the DLL from
3278	which it was exported, and which presumably also has the definition of
3279	`internal()`. However, when using ``/Zc:dllexportInlines-``, the inline
3280	definition of `S::foo()` is used directly, resulting in a link error since
3281	`internal()` is not available. Even worse, if there is an inline definition of
3282	`internal()` containing a static local variable, we will now refer to a
3283	different instance of that variable than in the DLL:
3284
3285	.. code-block:: c
3286
3287	inline int internal() { static int x; return x++; }
3288
3289	struct __declspec(dllimport) S {
3290	int foo() { return internal(); }
3291	}
3292
3293	This could lead to very subtle bugs. Using ``-fvisibility-inlines-hidden`` can
3294	lead to the same issue. To avoid it in this case, make `S::foo()` or
3295	`internal()` non-inline, or mark them `dllimport/dllexport` explicitly.
3296
3297	The /fallback Option
3298	^^^^^^^^^^^^^^^^^^^^
3299
3300	When clang-cl is run with the ``/fallback`` option, it will first try to
3301	compile files itself. For any file that it fails to compile, it will fall back
3302	and try to compile the file by invoking cl.exe.
3303
3304	This option is intended to be used as a temporary means to build projects where
3305	clang-cl cannot successfully compile all the files. clang-cl may fail to compile
3306	a file either because it cannot generate code for some C++ feature, or because
3307	it cannot parse some Microsoft language extension.
3308

Clang Project