599 lines
14 KiB
Text
599 lines
14 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
clang - the Clang C, C++, and Objective-C compiler
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<clang> [B<-c>|B<-S>|B<-E>] B<-std=>I<standard> B<-g>
|
|
[B<-O0>|B<-O1>|B<-O2>|B<-O3>|B<-Ofast>|B<-Os>|B<-Oz>|B<-O>|B<-O4>]
|
|
B<-W>I<warnings...> B<-pedantic>
|
|
B<-I>I<dir...> B<-L>I<dir...>
|
|
B<-D>I<macro[=defn]>
|
|
B<-f>I<feature-option...>
|
|
B<-m>I<machine-option...>
|
|
B<-o> I<output-file>
|
|
B<-stdlib=>I<library>
|
|
I<input-filenames>
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
B<clang> is a C, C++, and Objective-C compiler which encompasses preprocessing,
|
|
parsing, optimization, code generation, assembly, and linking. Depending on
|
|
which high-level mode setting is passed, Clang will stop before doing a full
|
|
link. While Clang is highly integrated, it is important to understand the
|
|
stages of compilation, to understand how to invoke it. These stages are:
|
|
|
|
=over
|
|
|
|
=item B<Driver>
|
|
|
|
The B<clang> executable is actually a small driver which controls the overall
|
|
execution of other tools such as the compiler, assembler and linker. Typically
|
|
you do not need to interact with the driver, but you transparently use it to run
|
|
the other tools.
|
|
|
|
=item B<Preprocessing>
|
|
|
|
This stage handles tokenization of the input source file, macro expansion,
|
|
#include expansion and handling of other preprocessor directives. The output of
|
|
this stage is typically called a ".i" (for C), ".ii" (for C++), ".mi" (for
|
|
Objective-C) , or ".mii" (for Objective-C++) file.
|
|
|
|
=item B<Parsing and Semantic Analysis>
|
|
|
|
This stage parses the input file, translating preprocessor tokens into a parse
|
|
tree. Once in the form of a parser tree, it applies semantic analysis to compute
|
|
types for expressions as well and determine whether the code is well formed. This
|
|
stage is responsible for generating most of the compiler warnings as well as
|
|
parse errors. The output of this stage is an "Abstract Syntax Tree" (AST).
|
|
|
|
=item B<Code Generation and Optimization>
|
|
|
|
This stage translates an AST into low-level intermediate code (known as "LLVM
|
|
IR") and ultimately to machine code. This phase is responsible for optimizing
|
|
the generated code and handling target-specific code generation. The output of
|
|
this stage is typically called a ".s" file or "assembly" file.
|
|
|
|
Clang also supports the use of an integrated assembler, in which the code
|
|
generator produces object files directly. This avoids the overhead of generating
|
|
the ".s" file and of calling the target assembler.
|
|
|
|
=item B<Assembler>
|
|
|
|
This stage runs the target assembler to translate the output of the compiler
|
|
into a target object file. The output of this stage is typically called a ".o"
|
|
file or "object" file.
|
|
|
|
=item B<Linker>
|
|
|
|
This stage runs the target linker to merge multiple object files into an
|
|
executable or dynamic library. The output of this stage is typically called an
|
|
"a.out", ".dylib" or ".so" file.
|
|
|
|
=back
|
|
|
|
The Clang compiler supports a large number of options to control each of these
|
|
stages. In addition to compilation of code, Clang also supports other tools:
|
|
|
|
B<Clang Static Analyzer>
|
|
|
|
The Clang Static Analyzer is a tool that scans source code to try to find bugs
|
|
through code analysis. This tool uses many parts of Clang and is built into the
|
|
same driver. Please see L<http://clang-analyzer.llvm.org> for more details
|
|
on how to use the static analyzer.
|
|
|
|
|
|
=head1 OPTIONS
|
|
|
|
=head2 Stage Selection Options
|
|
|
|
=over
|
|
|
|
=item B<-E>
|
|
|
|
Run the preprocessor stage.
|
|
|
|
=item B<-fsyntax-only>
|
|
|
|
Run the preprocessor, parser and type checking stages.
|
|
|
|
=item B<-S>
|
|
|
|
Run the previous stages as well as LLVM generation and optimization stages and
|
|
target-specific code generation, producing an assembly file.
|
|
|
|
=item B<-c>
|
|
|
|
Run all of the above, plus the assembler, generating a target ".o" object file.
|
|
|
|
=item B<no stage selection option>
|
|
|
|
If no stage selection option is specified, all stages above are run, and the
|
|
linker is run to combine the results into an executable or shared library.
|
|
|
|
=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<language>
|
|
|
|
Specify the language standard to compile for.
|
|
|
|
=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 _MSC_VER. 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
|
|
|
|
Clang fully supports cross compilation as an inherent part of its design.
|
|
Depending on how your version of 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 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 B<-O0> B<-O1> B<-O2> B<-O3> B<-Ofast> B<-Os> B<-Oz> B<-O> B<-O4>
|
|
|
|
Specify which optimization level to use:
|
|
|
|
=over
|
|
|
|
=item B<-O0>
|
|
|
|
Means "no optimization": this level compiles the fastest and
|
|
generates the most debuggable code.
|
|
|
|
=item B<-O1>
|
|
|
|
Somewhere between B<-O0> and B<-O2>.
|
|
|
|
=item B<-O2>
|
|
|
|
Moderate level of optimization which enables most optimizations.
|
|
|
|
=item B<-O3>
|
|
|
|
Like B<-O2>, except that it enables optimizations that take longer to perform
|
|
or that may generate larger code (in an attempt to make the program run faster).
|
|
|
|
=item B<-Ofast>
|
|
|
|
Enables all the optimizations from B<-O3> along with other aggressive
|
|
optimizations that may violate strict compliance with language standards.
|
|
|
|
=item B<-Os>
|
|
|
|
Like B<-O2> with extra optimizations to reduce code size.
|
|
|
|
=item B<-Oz>
|
|
|
|
Like B<-Os> (and thus B<-O2>), but reduces code size further.
|
|
|
|
=item B<-O>
|
|
|
|
Equivalent to B<-O2>.
|
|
|
|
=item B<-O4> and higher
|
|
|
|
Currently equivalent to B<-O3>
|
|
|
|
=back
|
|
|
|
=item B<-g>
|
|
|
|
Generate debug information. Note that 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 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 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>.
|
|
|
|
=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.
|
|
|
|
=item B<-save-temps>
|
|
|
|
Save intermediate compilation results.
|
|
|
|
=item B<-integrated-as> B<-no-integrated-as>
|
|
|
|
Used to enable and disable, respectively, the use of the integrated
|
|
assembler. Whether the integrated assembler is on by default is target
|
|
dependent.
|
|
|
|
=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 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 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.
|
|
|
|
=item B<-nostdlibinc>
|
|
|
|
Do not search the standard system directories for include files, but do search
|
|
compiler builtin include directories.
|
|
|
|
=item B<-nobuiltininc>
|
|
|
|
Do not search clang's builtin directory for include files.
|
|
|
|
=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 Warning Control Options
|
|
#=over
|
|
#=back
|
|
#=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 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 CPATH,
|
|
which are only used when processing the appropriate language.
|
|
|
|
=item B<MACOSX_DEPLOYMENT_TARGET>
|
|
|
|
If -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.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
as(1), ld(1)
|
|
|
|
=head1 AUTHOR
|
|
|
|
Maintained by the Clang / LLVM Team (L<http://clang.llvm.org>).
|
|
|
|
=cut
|