[cfe-commits] r71059 - /cfe/trunk/docs/tools/clang.pod
sabre at nondot.org
Tue May 5 19:47:51 PDT 2009
Date: Tue May 5 21:47:51 2009
New Revision: 71059
add some content
--- cfe/trunk/docs/tools/clang.pod (original)
+++ cfe/trunk/docs/tools/clang.pod Tue May 5 21:47:51 2009
@@ -2,38 +2,123 @@
-clang - the clang C and Objective-C compiler
+clang - the Clang C and Objective-C compiler
-B<clang> [I<options>] I<filenames...>
-FIXME: Fill in synposis and options.
+B<clang> [B<-c>|B<-S>|B<-E>] B<-std=>I<standard> B<-g>
+ B<-W>I<warnings...> B<-pedantic>
+ B<-I>I<dir...> B<-L>I<dir...>
+ B<-o> I<output-file>
-FIXME: Fill in 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:
-Print the commands to run for this compilation.
+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.
-Run the static analyzer.
+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 or 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.
+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"
+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.
+The Clang compiler supports a large number of options to control each of these
+=head2 Stage Selection Options
Display available options.
+Print the commands to run for this compilation.
Only run the preprocessor.
+Only run preprocess and compilation steps.
+Only run preprocess, compile, and assemble steps.
+Use the LLVM representation for assembler and object files.
+Run the static analyzer.
Treat source input files as Objective-C++ inputs.
@@ -46,10 +131,6 @@
Don't emit warning for unused driver arguments.
-Only run preprocess and compilation steps.
Pass the comma separated arguments in I<args> to the assembler.
@@ -82,14 +163,6 @@
Pass I<arg> to the preprocessor.
-Only run preprocess, compile, and assemble steps.
-Use the LLVM representation for assembler and object files.
=item B<-o> I<file>
Write output to I<file>.
@@ -138,7 +211,7 @@
+It is inconceivable that Clang may have a bug.
=head1 SEE ALSO
More information about the cfe-commits