[cfe-commits] Updated and expanded Clang manual page (docs/tools/clang.pod)

[Jonathan de Boyne Pollard]

On 2012-11-21 16:19, Chris Lattner wrote:
> Definitely! Please send patches to the cfe-commits mailing list! 

The output of svn diff turns out to be larger, at 28KiB, than the file 
itself, which is 27KiB.  So I'm attaching the file as-is. Enjoy.  I 
might be persuaded to fill in some more of the missing bits.  (-:
-------------- next part --------------
##===-- clang.pod - Clang manual page -------------------------------------===##
##
##                     The LLVM Compiler Infrastructure
##
## This file is distributed under the University of Illinois Open Source
## License. See LICENSE.TXT for details.
##
##===----------------------------------------------------------------------===##
##
## This is the source for the Clang manual page in Perl's .pod format,
## suitable for passing to perldoc, pod2html, and so forth.
##
##===----------------------------------------------------------------------===##

=pod

=head1 NAME

clang, clang++ - the Clang/LLVM C, C++, Objective-C, and Objective-C++ compiler

=head1 SYNOPSIS

B<clang> [B<-c>|B<-S>|B<-E>] 
  S<B<-g>[I<type>]> B<-s>
  S<B<-O>[I<optimization-level>]>
  S<B<-W>[I<warnings...>]> B<-pedantic>
  S<B<-I> I<dir...>> S<B<-L> I<dir...>>
  S<B<-D> I<macro[=defn]>>
  S<B<-U> I<macro>>
  S<B<-l> I<library...>>
  S<B<-o> I<output-file>>
  S<B<-f>I<feature-option...>>
  S<B<-m>I<machine-option...>>
  B<-std=>I<standard> 
  B<-stdlib=>I<library> 
  I<input-filenames...>

B<clang> B<-cc1> I<internal-parser-options...> I<input-filenames...>

B<clang> B<-cc1as> I<internal-assembler-options...> I<input-filenames...>

B<clang++> I<as-above>

=head1 DESCRIPTION

B<clang> is a C, C++, Objective-C, and Objective-C++ compiler which
encompasses preprocessing, parsing, optimization, code generation, assembly,
and linking.  Its option syntax is (with one exception, see OPTIONS below) 
a superset of that of the the POSIX.1:2008 C<c99> utility, and is intended to
be compatible (hence one of the exceptions) with that of GCC version 4.

It can be used as a drop-in replacement for GCC, with C<clang> replacing
C<gcc> and C<clang++> replacing C<g++>.  However, note that it is not intended
to be a slavish duplicate of GCC.  Only some of the GCC command options
(outside of the common POSIX standardized subset) are supported, and B<clang> is
functionally different to GCC, meaning that some GCC things simply do not
apply with B<clang> (and vice versa, of course).

B<clang> conceptually comprises:

=over

=item * 

a I<driver> which 
controls the overall execution of the other parts of the compiler, depending
from how the program is invoked (see INVOCATION below).

=item * 

a I<preprocessor> which 
handles tokenization of an input source file, macro expansion,
C<#include> expansion and handling of other preprocessor directives.

=item * 

a I<parser and semantic analyzer> which 
takes the output of the preprocessor, translating tokens into a parse
tree.  It then applies semantic analysis to that parse tree to compute
types for expressions as well and determine whether the code is well formed.
It outputs an I<Abstract Syntax Tree> (AST).

=item * 

an I<IR builder> which 
takes the output of the semantic analyzer, the AST, and translates it into an
I<Intermediate Representation> (IR), namely the LLVM IR.

=item * 

an I<optimizer and code generator> which 
take LLVM IR, perform optimizations on it, and generate machine code for the
target instruction set architecture.

=item * 

a I<linker> which 
takes the machine code output of the code generator, and code from standard
and user-supplied libraries, and produces an executable file, 

=back

Unlike some traditional compilers, with B<clang> all of these, bar the linker,
are contained in one single program.  B<clang> expects to be able to use the
L<ld(1)> program for linking.  (And unless the integrated assembler is
enabled, more on which in OPTIONS below, it also expects to be able to use the
L<as(1)> program for assembling assembly language source files.)  Otherwise,
it uses no additional executables.

Technically, Clang is a "front end", built on top of the LLVM Core, and some
documentation (as well as the compiler's own source code) refers to it as
"CFE", the C-like languages Front End.  This "front end" comprises the driver,
pre-processor, parser, semantic analyzer, and IR builder parts.  The LLVM Core
comprises the optimizer and code generator, a "back end".  

The program named B<clang> is both "front end" and "back end" linked together,
along with some additional tools such as a standalone assembler and the
Clang Static Analyzer, into a single binary.  The Clang Static Analyzer is
a code analysis tool that scans source code to try to find bugs.

=head1 INVOCATION

How B<clang> is invoked controls the operation of its driver.  In its most
basic mode of invocation, without options specifying otherwise, the driver
will invoke the other parts of B<clang> so as to compile all of the input
files and libraries (see FILES below), and create a single executable file
with them linked together.  For compatibility with traditional Unix semantics
and the POSIX.1:2008 C<c99> utility, this file is named F<a.out>.

B<clang> is sensitive to the name passed as its 0th argument (which is normally
the name of the file found and executed by the shell, see L<execve(2)>).
If invoked with the names F<clang>, F<cc>, or F<cpp>, it will (by default)
make available only the standard headers and libraries appropriate to the C
and Objective-C languages.  
If invoked with the name F<clang++>, it will make available additional
standard headers and libraries appropriate to the C++ and Objective-C++
languages.
In addition, if invoked with the name F<cpp>, it will stop after
preprocessing, as if the B<-E> option (see OPTIONS below) had been used.

The same effects can be achieved "by hand", by employing the appropriate
driver, language selection, and system header/library options.

With other options (see OPTIONS below) the B<clang> driver can variously also:

=over

=item *

Stop after preprocessing, emitting the output of the pre-processor to standard
output or to file.

=item *

Stop after IR generation, emitting the LLVM IR in its I<bitcode> format,
suitable for processing with other LLVM tools or for combining with other
program modules as input to a subsequent invocation of B<clang> in order
to perform whole program optimization.

=item *

Stop after code generation, emitting the machine code as a file containing
either an assembly language listing (suitable for submitting to B<clang>'s own
assembler or the GNU assembler) or an I<object module> (suitable for adding to
a library, or submitting to a subsequent invocation of B<clang> or to a linker).

=back

=head1 OPTIONS

The POSIX.1:2008 standard specifies that in order to conform to the standard,
the B<-I>, B<-L>, B<-D>, B<-U>, and B<-l> options must be given separately
from their following arguments.  S<C<-l y>> must be two separate arguments,
for example.  Per the backwards compatibility requirements of chapter XBD
§12.1 of the standard, B<clang> also supports combining these options with their
following arguments, as C<-ly> for example.

B<clang> may reinvoke itself using B<-cc1> or B<-cc1as>.  The internal options
used differ from the options here, although there is some overlap (just enough
to be highly confusing), and are not documented here.

=head2 Major Driver Options

These options control the basic flow of control within B<clang>, selected by the
driver.

=over

=item B<-E>

Stop after preprocessing.  By default, the result of preprocessing is written to
standard output.  If there is only one input file, however, the B<-o> option
can be used to direct the output to a file.

=item B<-fsyntax-only>

Stop after generating the AST.  Since this generates no output by default, but
runs the parser, where most of the syntax and error checking is performed, this
is effectively a "just check the syntax" option.

=item B<-S>

Stop after generating machine code.  By default, the generated machine code is
written to file as an assembly language source listing suitable for input to
an assembler or to B<clang>.  If there is only one input file, the B<-o> option
can be used to override the default choice of output filename (see FILES
below).

=item B<-c>

Stop after generating machine code.  By default, the generated machine code is
written to file as an object module suitable for input to a linker or to
B<clang>.  If there is only one input file, the B<-o> option can be used to
override the default choice of output filename (see FILES below).

=item B<--analyze>

Run the Clang Static Analyzer.

=item B<-integrated-as> and B<-no-integrated-as>

Enable and disable the integrated assembler.  B<clang> has an integrated
assembler that bypasses the need to generate assembly language source files as
an intermediate stage in compilation, and that produces the same detailed
error reports for assembly language (in particular inline assembly language)
as are produced for C and C++ code.  Without it, B<clang> will use the L<as(1)>
program to assemble assembly language files.  

This option is not necessarily a permanent feature, and on future versions of
B<clang> the integrated assembler may be the universal default.  Currently, the
integrated assembler is enabled by default for some targets, and disabled by
default for others.

=back

=head2 Language Selection and Mode Options

=over

=item B<-x> I<language>

Treat subsequent input files as having type I<language>.

=item B<-std>=I<standard>

Specify the language standard to compile for.  The standards are:

=over

=item B<iso9899:1990> alias B<c89> and B<c90>

ISO/IEC 9899:1990, the 1990 C standard.

=item B<gnu89> alias B<gnu90>

ISO/IEC 9899:1990, the 1990 C standard, plus some GNU extensions.

=item B<iso9899:199409> alias B<c94>

ISO/IEC 9899:1994, the 1990 C standard with the 1994 amendment.

=item B<iso9899:2011> alias B<c11>

ISO/IEC 9899:2011, the 2011 C standard.

=item B<gnu99>

ISO/IEC 9899:2011, the 2011 C standard, plus some GNU extensions.

=item B<c++98>

ISO/IEC 14882:1998, the 1998 C++ standard.

=item B<gnu++98>

ISO/IEC 14882:1998, the 1998 C++ standard, plus some GNU extensions.

=item B<c++03>

ISO/IEC 14882:2003, the 1998 C++ standard with the 2003 amendement.

=item B<c++11>

ISO/IEC 14882:2011, the 2011 C++ standard.

=item B<gnu++11>

ISO/IEC 14882:2011, the 2011 C++ standard, plus some GNU extensions.

=item B<c++1y>

Working drafts of the proposed next revision of the C++ standard.

=item B<gnu++1y>

Working drafts of the proposed next revision of the C++ standard, plus some GNU extensions.

=back

=item B<-stdlib>=I<library>

Specify the C++ standard library to use; supported options are libstdc++ and
libc++.

=item B<-ansi>

Same as B<-std=c89>.

=item B<-ObjC++>

Treat source input files as Objective-C++ inputs.

=item B<-ObjC>

Treat source input files as Objective-C inputs.

=item B<-trigraphs>

Enable trigraphs.

=item B<-ffreestanding>

Indicate that the file should be compiled for a freestanding, not a hosted,
environment.

=item B<-fno-builtin>

Disable special handling and optimizations of builtin functions like strlen and
malloc.

=item B<-fmath-errno>

Indicate that math functions should be treated as updating errno.

=item B<-fpascal-strings>

Enable support for Pascal-style strings with "\pfoo".

=item B<-fms-extensions>

Enable support for Microsoft extensions.

=item B<-fmsc-version=>

Set the C<_MSC_VER> macro. Defaults to 1300 on Windows. Not set otherwise.

=item B<-fborland-extensions>

Enable support for Borland extensions.

=item B<-fwritable-strings>

Make all string literals default to writable.  This disables uniquing of
strings and other optimizations.

=item B<-flax-vector-conversions>

Allow loose type checking rules for implicit vector conversions.

=item B<-fblocks>

Enable the "Blocks" language feature.

=item B<-fobjc-gc-only>

Indicate that Objective-C code should be compiled in GC-only mode, which only
works when Objective-C Garbage Collection is enabled.

=item B<-fobjc-gc>

Indicate that Objective-C code should be compiled in hybrid-GC mode, which works
with both GC and non-GC mode.

=item B<-fobjc-abi-version>=I<version>

Select the Objective-C ABI version to use. Available versions are 1 (legacy
"fragile" ABI), 2 (non-fragile ABI 1), and 3 (non-fragile ABI 2).

=item B<-fobjc-nonfragile-abi-version>=I<version>

Select the Objective-C non-fragile ABI version to use by default. This will only
be used as the Objective-C ABI when the non-fragile ABI is enabled (either via
-fobjc-nonfragile-abi, or because it is the platform default).

=item B<-fobjc-nonfragile-abi>

Enable use of the Objective-C non-fragile ABI. On platforms for which this is
the default ABI, it can be disabled with B<-fno-objc-nonfragile-abi>.

=back

=head2 Target Selection Options

B<clang> fully supports cross compilation as an inherent part of its design.
Depending on how your version of B<clang> is configured, it may have support for
a number of cross compilers, or may only support a native target.

=over

=item B<-arch> I<architecture>

Specify the architecture to build for.

=item B<-mmacosx-version-min>=I<version>

When building for Mac OS/X, specify the minimum version supported by your
application.

=item B<-miphoneos-version-min>

When building for iPhone OS, specify the minimum version supported by your
application.


=item B<-march>=I<cpu>

Specify that B<clang> should generate code for a specific processor family member
and later.  For example, if you specify -march=i486, the compiler is allowed to
generate instructions that are valid on i486 and later processors, but which
may not exist on earlier ones.

=back

=head2 Code Generation Options

=over

=item S<B<-O>I<level>>

(B<clang> is not wholly compatible with the POSIX C<c99> utility here.  The
I<level> argument is mandatory per the POSIX standard, but optional with
B<clang>.  Therefore it I<must> be directly combined with the B<-O> option, as
C<-Os> for example.  Standard-conformant invokers of the compiler are 
required by the standard to use S<C<-O s>> and so forth.  This will not work 
with B<clang>.  B<clang> trades standards conformance here for backwards 
compatibility with the traditional use of allowing just C<-O> on its own.)

Specify which optimization level to use.  The levels are:

=over

=item S< >B<0>

No optimization.  This level compiles the fastest and generates the most
easily debuggable code.  

=item S< >B<1>

An optimization level that is "somewhere between 0 and 2".  It is not
documented which optimizations are performed at this level.

=item S< >B<2>

Moderate optimization.  Most optimizations are performed at this level.

=item B<s>

Optimize for size.  This is like B<2>, but also performs some extra
optimizations intended for reducing machine code size.

=item B<z>

Optimize for size, harder.  This is like B<s>, but performs more of the extra
optimizations intended for reducing machine code size.

=item S< >B<3>

Full optimization.  This is like B<2>, but also performs further
optimizations, intended for increasing execution speed, that may trade space
for time, increasing program code size in order to make it run faster, or that
may cause the optimizer to take longer to run.

=item S< >B<4>

Whole program optimization.  This is only supported on some platforms, as it
relies upon extended functionality in the L<ld(1)> utility.
Object files are stored in the LLVM I<bitcode> format, and
optimization is deferred until the object files are combined by the linker.
This allows optimizations to operate across all modules of the program.

=back

If B<-O> is not used, the default is no optimization.  Using C<-O> without an
argument is equivalent to C<-O2>.

=item B<-g>I<type>

Generate debug information, in both object files and final linked executables.  
The types of debug information are:

=over

=item S< >B<0>

No debug information at all.  This is the default if B<-g> is not specified.

=item B<line-tables-only>

Generate only file, function name, and line number information.  Information
about variables is not generated

=back

Using C<-g> without an argument generates full debugging information.

Note that B<clang> debug information works best at B<-O0>.  At higher
optimization levels, only line number information is currently available.

=item B<-fexceptions>

Enable generation of unwind information, this allows exceptions to be thrown
through B<clang> compiled stack frames.  This is on by default in x86-64.

=item B<-ftrapv>

Generate code to catch integer overflow errors.  Signed integer overflow is
undefined in C, with this flag, extra code is generated to detect this and abort
when it happens.


=item B<-fvisibility>

This flag sets the default visibility level.

=item B<-fcommon>

This flag specifies that variables without initializers get common linkage.  It
can be disabled with B<-fno-common>.

=item B<-ftls-model>

Set the default thread-local storage (TLS) model to use for thread-local
variables. Valid values are: "global-dynamic", "local-dynamic", "initial-exec"
and "local-exec". The default is "global-dynamic". The default model can be
overridden with the tls_model attribute. The compiler will try to choose a more
efficient model if possible.

=item B<-flto> B<-emit-llvm>

Generate output files in LLVM formats, suitable for link time optimization. When
used with B<-S> this generates LLVM intermediate language assembly files,
otherwise this generates LLVM bitcode format object files (which may be passed
to the linker depending on the stage selection options).

=cut

##=item B<-fnext-runtime> B<-fobjc-nonfragile-abi> B<-fgnu-runtime>
##These options specify which Objective-C runtime the code generator should
##target.  FIXME: we don't want people poking these generally.

=pod

=back

=head2 Other Driver Options

=over

=item B<-###>

Print the commands to run for this compilation.

=item B<--help>

Display available options.

=item B<-Qunused-arguments>

Don't emit warning for unused driver arguments.

=item B<-Wa,>I<args>

Pass the comma separated arguments in I<args> to the assembler.

=item B<-Wl,>I<args>

Pass the comma separated arguments in I<args> to the linker.

=item B<-Wp,>I<args>

Pass the comma separated arguments in I<args> to the preprocessor.

=item B<-Xanalyzer> I<arg>

Pass I<arg> to the static analyzer.

=item B<-Xassembler> I<arg>

Pass I<arg> to the assembler.

=item B<-Xlinker> I<arg>

Pass I<arg> to the linker.

=item B<-Xpreprocessor> I<arg>

Pass I<arg> to the preprocessor.

=item B<-o> I<file>

Write output to I<file>.  This interacts with the B<-E>, B<-S>, B<-c>, and
B<-MD> options.

=item B<-print-file-name>=I<file>

Print the full library path of I<file>.

=item B<-print-libgcc-file-name>

Print the library path for "libgcc.a".

=item B<-print-prog-name>=I<name>

Print the full program path of I<name>.

=item B<-print-search-dirs>

Print the paths used for finding libraries and programs.  See DIRECTORIES
below.

=item B<-save-temps>

Save intermediate compilation results.

=item B<-time>

Time individual commands.

=item B<-ftime-report>

Print timing summary of each stage of compilation.

=item B<-v>

Show commands to run and use verbose output.

=back

=head2 Diagnostics Options

=over

=item S<B<-W>I<warning>>

(Note that the argument is optional.  C<-W> is, for compatibility reasons, a
synonym for C<-Wextra>.  Therefore, per chapter XBD §12.1 of the POSIX
standard, B<-W> may I<not> be given separately from its following argument.)

Specify warning messages to enable/disable.  Warnings can be enabled/disabled
either individually, by name, or as groups.  To disable a warning or group of
warnings, simply prefix the name with C<no->.  The individual warnings are too
numerous to list here.  See the Clang User Guide.  The groups are:

=over

=item B<all>

This enables all warnings that have a high rate of usefulness and a low rate
of false positives, and that can be worked around without major convolutions in
the code.

=item B<extra>

The enables more warnings, that may be less generally useful or that might
have a higher rate of false positives.

=item B<conversion>

This enables a group of warnings about arithmetic conversions, not covered by
C<-Wextra>.

=item B<everything>

This enables every warning in the compiler.  The advice of the B<clang>
developers is not to use this in a production system, as some warnings enabled
by this are experimental, may have inordinately high rates of false positives,
or may be simply impossible to work around.

=back

=cut
### TODO: -Werror
=pod

=item S<B<-w>

Disable all warnings.  This has priority over all B<-W> options.

=item B<-fshow-column>
B<-fshow-source-location>
B<-fcaret-diagnostics>
B<-fdiagnostics-fixit-info>
B<-fdiagnostics-parseable-fixits>
B<-fdiagnostics-print-source-range-info>
B<-fprint-source-range-info>
B<-fdiagnostics-show-option>
B<-fmessage-length>

These options control how B<clang> prints out information about diagnostics (errors
and warnings).  Please see the Clang User's Manual for more information.

=back

=head2 Preprocessor Options

=over

=item B<-D>I<macroname=value>

Adds an implicit #define into the predefines buffer which is read before the
source file is preprocessed.

=item B<-U>I<macroname>

Adds an implicit #undef into the predefines buffer which is read before the
source file is preprocessed.

=item B<-include> I<filename>

Adds an implicit #include into the predefines buffer which is read before the
source file is preprocessed.

=item B<-I>I<directory>

Add the specified directory to the search path for include files.

=item B<-F>I<directory>

Add the specified directory to the search path for framework include files.

=item B<-nostdinc>

Do not search the standard system directories or compiler builtin directories
for include files.  See DIRECTORIES below.

=item B<-nostdlibinc>

Do not search the standard system directories for include files, but do search
compiler builtin include directories.  See DIRECTORIES below.

=item B<-nobuiltininc>

Do not search clang's builtin directory for include files.  See DIRECTORIES
below.

=cut

## TODO, but do we really want people using this stuff?
#=item B<-idirafter>I<directory>
#=item B<-iquote>I<directory>
#=item B<-isystem>I<directory>
#=item B<-iprefix>I<directory>
#=item B<-iwithprefix>I<directory>
#=item B<-iwithprefixbefore>I<directory>
#=item B<-isysroot>

=pod

=back

=cut

### TODO someday.
#=head2 Code Generation and Optimization Options
#=over
#=back
#=head2 Assembler Options
#=over
#=back
#=head2 Linker Options
#=over
#=back
#=head2 Static Analyzer Options
#=over
#=back

=pod

=head1 FILES

B<clang> accepts input files and generates output files.  The POSIX standard
for the C<c99> utility defines some standard file naming conventions, which
B<clang> extends.  For input files, the file name affects what B<clang> does
with the file, because by default (in the absence of an B<-x> option) B<clang>
deduces what an input file is from its name.  For output files, the
conventions dictate how the filename is synthesized from input filenames in
the absence of an explicit option for specifying the output filename such as
B<-MF> or B<-o>.

Here are the conventions:

=over

=item I<file>F<.h>

C or C++ language header.

=item I<file>F<.h.pch>

C or C++ language pre-compiled header.  (See the User Guide for more
information on precompiled headers.)

=item I<file>F<.c>

C language source file.  This can only be an input file.

=item I<file>F<.cpp>, I<file>F<.cc>, I<file>F<.CC>, or I<file>F<.C>

C++ language source file.  This can only be an input file.

=item I<file>F<.m>

Objective-C language source file.  This can only be an input file.

=item I<file>F<.mm> or I<file>F<.M>

Objective-C++ language source file.  This can only be an input file.

=item I<file>F<.i>

Preprocessed C language source file.

=item I<file>F<.ii>

Preprocessed C++ language source file.

=item I<file>F<.mi>

Preprocessed Objective-C language source file.

=item I<file>F<.mii>

Preprocessed Objective-C++ language source file.

=item I<file>F<.s>

Assembly language source file.  Assembly language files output by B<clang> can be
fed back into B<clang> as inputs.

=item I<file>F<.o>

Machine code object file.  Object files output by B<clang> can be fed back into
B<clang> as inputs.  
It is not an error to supply them as inputs when B<clang> is instructed to stop
before linking the final program, but a warning will be generated about unused
input files.

=item I<file>F<.a>

Archive of object files, as generated by L<ar(1)>.  This can only be an input
file, as B<clang> does not generate libraries itself.
It is not an error to supply archives as inputs when B<clang> is instructed to stop
before linking the final program, but a warning will be generated about unused
input files.

=item I<file>F<.so> or I<file>F<.dylib>

Dynamically linked library.

=back

Output filenames are synthesized usually by stripping off one of the
aforegiven suffixes and replacing it with another.
So, for example, if S<C<clang -S>> is passed the files F<a.c> and F<b.cpp>, it
will assume that the former is in the C langauage and the latter in the C++
language, and create output files named F<a.s> and F<b.s>.

=head1 DIRECTORIES

B<clang> automatically, unless instructed otherwise, searches for standard
headers and libraries in various places.  In the following, C<$CLANGROOT> is
the root of the tree where B<clang> is installed, C<$GCCROOT> is the root of the
tree where GCC is installed, and C<$CLANGMAJOR> and C<$CLANGMINOR> are the
major and minor version numbers of B<clang>.  (The roots are usually F</usr> or
F</usr/local>.)

There is no place from which B<clang> can read C<$GCCTARGET> and C<$GCCVERSION>,
and so it enumerates a host-dependent built-in list of targets and version numbers
until a match is found or its list is exhausted.

=over

=item F<$CLANGROOT/lib/$CLANGMAJOR.$CLANGMINOR/include>

Clang compiler-supplied header files, such as F<stddef.h>.

=item F<$GCCROOT/lib/gcc/$GCCTARGET/$GCCVERSION/include>

GCC compiler-supplied header files, such as F<stddef.h>.

=item F<$GCCROOT/lib/gcc/$GCCTARGET/$GCCVERSION/>

GCC compiler-supplied libraries, such as libgcc.a.

=item 
F<$GCCROOT/include/c++/$GCCVERSION/$GCCTARGET>,
F<$GCCROOT/include/c++/$GCCVERSION>, and
F<$GCCROOT/include/c++/$GCCVERSION/backward>

The GNU libstdc++ header files.

=item F<$GCCROOT/include/c++/v1>

The BSD libc++ header files.

=item F<$GCCROOT/include/>

The GNU libc header files.

=item F<$GCCROOT/lib/>

The GNU libc library files.

=item F<$CLANGROOT/include/>

The BSD libc header files.

=item F<$CLANGROOT/lib/>

The BSD libc library files.

=back

=head1 ENVIRONMENT

=over

=item B<TMPDIR>, B<TEMP>, B<TMP>

These environment variables are checked, in order, for the location to
write temporary files used during the compilation process.

=item B<CPATH>

If this environment variable is present, it is treated as a delimited
list of paths to be added to the default system include path list. The
delimiter is the platform dependent delimitor, as used in the I<PATH>
environment variable.

Empty components in the environment variable are ignored.

=item B<C_INCLUDE_PATH>, B<OBJC_INCLUDE_PATH>, B<CPLUS_INCLUDE_PATH>,
B<OBJCPLUS_INCLUDE_PATH>

These environment variables specify additional paths, as for B<CPATH>,
which are only used when processing the appropriate language.

=item B<MACOSX_DEPLOYMENT_TARGET>

If B<-mmacosx-version-min> is unspecified, the default deployment target
is read from this environment variable.  This option only affects Darwin
targets.

=back

=head1 BUGS

To report bugs, please visit L<http://llvm.org/bugs/>.  Most bug reports should
include preprocessed source files (use the B<-E> option) and the full output of 
the compiler, along with information to reproduce.

=head2 Known bugs in this manual page itself

The search path creation is actually even more complex than is described in
DIRECTORIES.  There are lots of platform-specific additions and quirks.  On
one x86-64 system running CentOS, for example, B<clang> scans approximately 160
directories at startup, probing for the various system headers and libraries
so that it can construct its header and library search paths.

There are a number of options not yet listed in OPTIONS, including B<-l> and
B<-pedantic>.

The automatic inference of target name from the 0th argument is not mentioned.
Nor is B<clang>'s use of target-specific L<as(1)> and L<ld(1)>.

Targets aren't even mentioned at all.  Cross-compilation is glossed over.

The B<-MF> option is referred to, but not documented.
Likewise B<-MD>.

=head1 SEE ALSO

L<as(1)>, L<ld(1)>

=head1 AUTHOR

Maintained by the Clang / LLVM Team (L<http://clang.llvm.org>).

=cut