1 files changed, 518 insertions, 0 deletions
diff --git a/docs/main/tools/clang.pod b/docs/main/tools/clang.pod
new file mode 100644
index 0000000000..42cf8fa2d7
--- /dev/null
+++ b/docs/main/tools/clang.pod
@@ -0,0 +1,518 @@
+=pod
+
+=head1 NAME
+
+clang - the Clang 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<-Os>|B<-O3>|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>
+  I<input-filenames>
+
+=head1 DESCRIPTION
+
+B<clang> is a 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) or ".mi" (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 (depending on the optimization level).  This
+phase is responsible for optimizing the generated code and handling
+target-specfic code generation.  The output of this stage is typically called a
+".s" file or "assembly" file.
+
+=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
+though code analysis.  This tool uses many parts of Clang and is built into the
+same driver.
+
+
+=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.
+
+=item B<--analyze>
+
+Run the Clang Static Analyzer.
+
+=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<-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<-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.
+
+=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<-Os> B<-O3> B<-O4>
+
+Specify which optimization level to use.  B<-O0> means "no optimization": this
+level compiles the fastest and generates the most debuggable code.  B<-O2> is a
+moderate level of optimization which enables most optimizations.  B<-Os> is like
+B<-O2> with extra optimizations to reduce code size.  B<-O3> is 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).  On
+supported platforms, B<-O4> enables link-time optimization; object files are
+stored in the LLVM bitcode file format and whole program optimization is done at
+link time. B<-O1> is somewhere between B<-O0> and B<-O2>.
+
+=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<-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<-Xclang> I<arg>
+
+Pass I<arg> to the clang compiler.
+
+=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<-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-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 for include files.
+
+=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
+
+Clang currently does not have C++ support, and this manual page is incomplete.
+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