Index: docs/CMakeLists.txt =================================================================== --- docs/CMakeLists.txt +++ docs/CMakeLists.txt @@ -87,5 +87,8 @@ if (${SPHINX_OUTPUT_HTML}) add_sphinx_target(html clang) endif() + if (${SPHINX_OUTPUT_MAN}) + add_sphinx_target(man clang) + endif() endif() endif() Index: docs/CommandGuide/clang.rst =================================================================== --- /dev/null +++ docs/CommandGuide/clang.rst @@ -0,0 +1,484 @@ +clang - the Clang C, C++, and Objective-C compiler +================================================== + +SYNOPSIS +-------- + +:program:`clang` [*options*] *filename ...* + +DESCRIPTION +----------- + +:program:`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: + +Driver + The 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. + +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. + +Parsing and Semantic Analysis + This stage parses the input file, translating preprocessor tokens into a + parse tree. Once in the form of a parse 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). + +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. + +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. + +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. + +:program:`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 for more details +on how to use the static analyzer. + +OPTIONS +------- + +Stage Selection Options +~~~~~~~~~~~~~~~~~~~~~~~ + +.. option:: -E + + Run the preprocessor stage. + +.. option:: -fsyntax-only + + Run the preprocessor, parser and type checking stages. + +.. option:: -S + + Run the previous stages as well as LLVM generation and optimization stages + and target-specific code generation, producing an assembly file. + +.. option:: -c + + Run all of the above, plus the assembler, generating a target ".o" object file. + +.. option:: 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. + +Language Selection and Mode Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. option:: -x + + Treat subsequent input files as having type language. + +.. option:: -std= + + Specify the language standard to compile for. + +.. option:: -stdlib= + + Specify the C++ standard library to use; supported options are libstdc++ and + libc++. + +.. option:: -ansi + + Same as -std=c89. + +.. option:: -ObjC, -ObjC++ + + Treat source input files as Objective-C and Object-C++ inputs respectively. + +.. option:: -trigraphs + + Enable trigraphs. + +.. option:: -ffreestanding + + Indicate that the file should be compiled for a freestanding, not a hosted, + environment. + +.. option:: -fno-builtin + + Disable special handling and optimizations of builtin functions like + :c:func:`strlen` and :c:func:`malloc`. + +.. option:: -fmath-errno + + Indicate that math functions should be treated as updating :c:data:`errno`. + +.. option:: -fpascal-strings + + Enable support for Pascal-style strings with "\\pfoo". + +.. option:: -fms-extensions + + Enable support for Microsoft extensions. + +.. option:: -fmsc-version= + + Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise. + +.. option:: -fborland-extensions + + Enable support for Borland extensions. + +.. option:: -fwritable-strings + + Make all string literals default to writable. This disables uniquing of + strings and other optimizations. + +.. option:: -flax-vector-conversions + + Allow loose type checking rules for implicit vector conversions. + +.. option:: -fblocks + + Enable the "Blocks" language feature. + +.. option:: -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. + +.. option:: -fobjc-gc + + Indicate that Objective-C code should be compiled in hybrid-GC mode, which + works with both GC and non-GC mode. + +.. option:: -fobjc-abi-version=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). + +.. option:: -fobjc-nonfragile-abi-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 :option:`-fobjc-nonfragile-abi`, or because it is the platform + default). + +.. option:: -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 :option:`-fno-objc-nonfragile-abi`. + +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. + +.. option:: -arch + + Specify the architecture to build for. + +.. option:: -mmacosx-version-min= + + When building for Mac OS X, specify the minimum version supported by your + application. + +.. option:: -miphoneos-version-min + + When building for iPhone OS, specify the minimum version supported by your + application. + +.. option:: -march= + + 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. + + +Code Generation Options +~~~~~~~~~~~~~~~~~~~~~~~ + +.. option:: -O0, -O1, -O2, -O3, -Ofast, -Os, -Oz, -O, -O4 + + Specify which optimization level to use: + + :option:`-O0` Means "no optimization": this level compiles the fastest and + generates the most debuggable code. + + :option:`-O1` Somewhere between :option:`-O0` and :option:`-O2`. + + :option:`-O2` Moderate level of optimization which enables most + optimizations. + + :option:`-O3` Like :option:`-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). + + :option:`-Ofast` Enables all the optimizations from :option:`-O3` along + with other aggressive optimizations that may violate strict compliance with + language standards. + + :option:`-Os` Like :option:`-O2` with extra optimizations to reduce code + size. + + :option:`-Oz` Like :option:`-Os` (and thus :option:`-O2`), but reduces code + size further. + + :option:`-O` Equivalent to :option:`-O2`. + + :option:`-O4` and higher + + Currently equivalent to :option:`-O3` + +.. option:: -g + + Generate debug information. Note that Clang debug information works best at -O0. + +.. option:: -fstandalone-debug -fno-standalone-debug + + Clang supports a number of optimizations to reduce the size of debug + information in the binary. They work based on the assumption that the + debug type information can be spread out over multiple compilation units. + For instance, Clang will not emit type definitions for types that are not + needed by a module and could be replaced with a forward declaration. + Further, Clang will only emit type info for a dynamic C++ class in the + module that contains the vtable for the class. + + The :option:`-fstandalone-debug` option turns off these optimizations. + This is useful when working with 3rd-party libraries that don't come with + debug information. This is the default on Darwin. Note that Clang will + never emit type information for types that are not referenced at all by the + program. + +.. option:: -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. + +.. option:: -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. + +.. option:: -fvisibility + + This flag sets the default visibility level. + +.. option:: -fcommon + + This flag specifies that variables without initializers get common linkage. + It can be disabled with :option:`-fno-common`. + +.. option:: -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. + +.. option:: -flto, -emit-llvm + + Generate output files in LLVM formats, suitable for link time optimization. + When used with :option:`-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). + +Driver Options +~~~~~~~~~~~~~~ + +.. option:: -### + + Print (but do not run) the commands to run for this compilation. + +.. option:: --help + + Display available options. + +.. option:: -Qunused-arguments + + Do not emit any warnings for unused driver arguments. + +.. option:: -Wa, + + Pass the comma separated arguments in args to the assembler. + +.. option:: -Wl, + + Pass the comma separated arguments in args to the linker. + +.. option:: -Wp, + + Pass the comma separated arguments in args to the preprocessor. + +.. option:: -Xanalyzer + + Pass arg to the static analyzer. + +.. option:: -Xassembler + + Pass arg to the assembler. + +.. option:: -Xlinker + + Pass arg to the linker. + +.. option:: -Xpreprocessor + + Pass arg to the preprocessor. + +.. option:: -o + + Write output to file. + +.. option:: -print-file-name= + + Print the full library path of file. + +.. option:: -print-libgcc-file-name + + Print the library path for "libgcc.a". + +.. option:: -print-prog-name= + + Print the full program path of name. + +.. option:: -print-search-dirs + + Print the paths used for finding libraries and programs. + +.. option:: -save-temps + + Save intermediate compilation results. + +.. option:: -integrated-as, -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. + +.. option:: -time + + Time individual commands. + +.. option:: -ftime-report + + Print timing summary of each stage of compilation. + +.. option:: -v + + Show commands to run and use verbose output. + + +Diagnostics Options +~~~~~~~~~~~~~~~~~~~ + +.. option:: -fshow-column, -fshow-source-location, -fcaret-diagnostics, -fdiagnostics-fixit-info, -fdiagnostics-parseable-fixits, -fdiagnostics-print-source-range-info, -fprint-source-range-info, -fdiagnostics-show-option, -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. + +Preprocessor Options +~~~~~~~~~~~~~~~~~~~~ + +.. option:: -D= + + Adds an implicit #define into the predefines buffer which is read before the + source file is preprocessed. + +.. option:: -U + + Adds an implicit #undef into the predefines buffer which is read before the + source file is preprocessed. + +.. option:: -include + + Adds an implicit #include into the predefines buffer which is read before the + source file is preprocessed. + +.. option:: -I + + Add the specified directory to the search path for include files. + +.. option:: -F + + Add the specified directory to the search path for framework include files. + +.. option:: -nostdinc + + Do not search the standard system directories or compiler builtin directories + for include files. + +.. option:: -nostdlibinc + + Do not search the standard system directories for include files, but do + search compiler builtin include directories. + +.. option:: -nobuiltininc + + Do not search clang's builtin directory for include files. + + +ENVIRONMENT +----------- + +.. envvar:: TMPDIR, TEMP, TMP + + These environment variables are checked, in order, for the location to write + temporary files used during the compilation process. + +.. envvar:: 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 delimiter, as used in the PATH environment variable. + + Empty components in the environment variable are ignored. + +.. envvar:: C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH + + These environment variables specify additional paths, as for :envvar:`CPATH`, which are + only used when processing the appropriate language. + +.. envvar:: MACOSX_DEPLOYMENT_TARGET + + If :option:`-mmacosx-version-min` is unspecified, the default deployment + target is read from this environment variable. This option only affects + Darwin targets. + +BUGS +---- + +To report bugs, please visit . Most bug reports should +include preprocessed source files (use the :option:`-E` option) and the full +output of the compiler, along with information to reproduce. + +SEE ALSO +-------- + +:manpage:`as(1)`, :manpage:`ld(1)` + Index: docs/CommandGuide/index.rst =================================================================== --- /dev/null +++ docs/CommandGuide/index.rst @@ -0,0 +1,17 @@ +Clang "man" pages +----------------- + +The following documents are command descriptions for all of the Clang tools. +These pages describe how to use the Clang commands and what their options are. +Note that these pages do not describe all of the options available for all +tools. To get a complete listing, pass the ``--help`` (general options) or +``--help-hidden`` (general and debugging options) arguments to the tool you are +interested in. + +Basic Commands +~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + clang Index: docs/Makefile =================================================================== --- docs/Makefile +++ docs/Makefile @@ -8,7 +8,6 @@ ##===----------------------------------------------------------------------===## CLANG_LEVEL := .. -DIRS := tools ifdef BUILD_FOR_WEBSITE PROJ_OBJ_DIR = . Index: docs/conf.py =================================================================== --- docs/conf.py +++ docs/conf.py @@ -41,7 +41,7 @@ # General information about the project. project = u'Clang' -copyright = u'2007-2014, The Clang Team' +copyright = u'2007-2015, The Clang Team' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -212,10 +212,40 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'clang', u'Clang Documentation', - [u'The Clang Team'], 1) -] +man_pages = [] + +# Automatically derive the list of man pages from the contents of the command +# guide subdirectory. This was copied from llvm/docs/conf.py. +basedir = os.path.dirname(__file__) +man_page_authors = u'Maintained by the Clang / LLVM Team ()' +command_guide_subpath = 'CommandGuide' +command_guide_path = os.path.join(basedir, command_guide_subpath) +for name in os.listdir(command_guide_path): + # Ignore non-ReST files and the index page. + if not name.endswith('.rst') or name in ('index.rst',): + continue + + # Otherwise, automatically extract the description. + file_subpath = os.path.join(command_guide_subpath, name) + with open(os.path.join(command_guide_path, name)) as f: + title = f.readline().rstrip('\n') + header = f.readline().rstrip('\n') + + if len(header) != len(title): + print >>sys.stderr, ( + "error: invalid header in %r (does not match title)" % ( + file_subpath,)) + if ' - ' not in title: + print >>sys.stderr, ( + ("error: invalid title in %r " + "(expected ' - ')") % ( + file_subpath,)) + + # Split the name out of the title. + name,description = title.split(' - ', 1) + man_pages.append((file_subpath.replace('.rst',''), name, + description, man_page_authors, 1)) + # If true, show URL addresses after external links. #man_show_urls = False Index: docs/index.rst =================================================================== --- docs/index.rst +++ docs/index.rst @@ -31,6 +31,7 @@ ControlFlowIntegrity Modules MSVCCompatibility + CommandGuide/index FAQ Using Clang as a Library Index: docs/tools/Makefile =================================================================== --- docs/tools/Makefile +++ /dev/null @@ -1,116 +0,0 @@ -##===- docs/tools/Makefile ---------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -ifdef BUILD_FOR_WEBSITE - -# FIXME: This was copied from the CommandGuide makefile. Figure out -# how to get this stuff on the website. - -# This special case is for keeping the CommandGuide on the LLVM web site -# up to date automatically as the documents are checked in. It must build -# the POD files to HTML only and keep them in the src directories. It must also -# build in an unconfigured tree, hence the ifdef. To use this, run -# make -s BUILD_FOR_WEBSITE=1 inside the cvs commit script. -SRC_DOC_DIR= -DST_HTML_DIR=html/ -DST_MAN_DIR=man/man1/ -DST_PS_DIR=ps/ -CLANG_VERSION := trunk - -# If we are in BUILD_FOR_WEBSITE mode, default to the all target. -all:: html man ps - -clean: - rm -f pod2htm*.*~~ $(HTML) $(MAN) $(PS) - -# To create other directories, as needed, and timestamp their creation -%/.dir: - -mkdir $* > /dev/null - date > $@ - -else - -# Otherwise, if not in BUILD_FOR_WEBSITE mode, use the project info. -CLANG_LEVEL := ../.. -include $(CLANG_LEVEL)/Makefile - -CLANG_VERSION := $(word 3,$(shell grep "CLANG_VERSION " \ - $(PROJ_OBJ_DIR)/$(CLANG_LEVEL)/include/clang/Basic/Version.inc)) - -SRC_DOC_DIR=$(PROJ_SRC_DIR)/ -DST_HTML_DIR=$(PROJ_OBJ_DIR)/ -DST_MAN_DIR=$(PROJ_OBJ_DIR)/ -DST_PS_DIR=$(PROJ_OBJ_DIR)/ - -endif - - -POD := $(wildcard $(SRC_DOC_DIR)*.pod) -HTML := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_HTML_DIR)%.html, $(POD)) -MAN := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_MAN_DIR)%.1, $(POD)) -PS := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_PS_DIR)%.ps, $(POD)) - -ifdef ONLY_MAN_DOCS -INSTALL_TARGETS := install-man -else -INSTALL_TARGETS := install-html install-man install-ps -endif - -.SUFFIXES: -.SUFFIXES: .html .pod .1 .ps - -$(DST_HTML_DIR)%.html: %.pod $(DST_HTML_DIR)/.dir - pod2html --css=manpage.css --htmlroot=. \ - --podpath=. --infile=$< --outfile=$@ --title=$* - -$(DST_MAN_DIR)%.1: %.pod $(DST_MAN_DIR)/.dir - pod2man --release "clang $(CLANG_VERSION)" --center="Clang Tools Documentation" $< $@ - -$(DST_PS_DIR)%.ps: $(DST_MAN_DIR)%.1 $(DST_PS_DIR)/.dir - groff -Tps -man $< > $@ - - -html: $(HTML) -man: $(MAN) -ps: $(PS) - -EXTRA_DIST := $(POD) - -clean-local:: - $(Verb) $(RM) -f pod2htm*.*~~ $(HTML) $(MAN) $(PS) - -HTML_DIR := $(DESTDIR)$(PROJ_docsdir)/html/clang -MAN_DIR := $(DESTDIR)$(PROJ_mandir)/man1 -PS_DIR := $(DESTDIR)$(PROJ_docsdir)/ps - -install-html:: $(HTML) - $(Echo) Installing HTML Clang Tools Documentation - $(Verb) $(MKDIR) $(HTML_DIR) - $(Verb) $(DataInstall) $(HTML) $(HTML_DIR) - $(Verb) $(DataInstall) $(PROJ_SRC_DIR)/manpage.css $(HTML_DIR) - -install-man:: $(MAN) - $(Echo) Installing MAN Clang Tools Documentation - $(Verb) $(MKDIR) $(MAN_DIR) - $(Verb) $(DataInstall) $(MAN) $(MAN_DIR) - -install-ps:: $(PS) - $(Echo) Installing PS Clang Tools Documentation - $(Verb) $(MKDIR) $(PS_DIR) - $(Verb) $(DataInstall) $(PS) $(PS_DIR) - -install-local:: $(INSTALL_TARGETS) - -uninstall-local:: - $(Echo) Uninstalling Clang Tools Documentation - $(Verb) $(RM) -rf $(HTML_DIR) $(MAN_DIR) $(PS_DIR) - -printvars:: - $(Echo) "POD : " '$(POD)' - $(Echo) "HTML : " '$(HTML)' Index: docs/tools/clang.pod =================================================================== --- docs/tools/clang.pod +++ /dev/null @@ -1,614 +0,0 @@ -=pod - -=head1 NAME - -clang - the Clang C, C++, and Objective-C compiler - -=head1 SYNOPSIS - -B [B<-c>|B<-S>|B<-E>] B<-std=>I B<-g> - [B<-O0>|B<-O1>|B<-O2>|B<-O3>|B<-Ofast>|B<-Os>|B<-Oz>|B<-O>|B<-O4>] - B<-W>I B<-pedantic> - B<-I>I B<-L>I - B<-D>I - B<-f>I - B<-m>I - B<-o> I - B<-stdlib=>I - I - -=head1 DESCRIPTION - -B 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 - -The B 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 - -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 - -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 - -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 - -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 - -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 - -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 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 - -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 - -Treat subsequent input files as having type I. - -=item B<-std>=I - -Specify the language standard to compile for. - -=item B<-stdlib>=I - -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 - -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 - -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 - -Specify the architecture to build for. - -=item B<-mmacosx-version-min>=I - -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 - -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>. - -=item B<-fstandalone-debug> B<-fno-standalone-debug> - -Clang supports a number of optimizations to reduce the size of debug -information in the binary. They work based on the assumption that the -debug type information can be spread out over multiple compilation -units. For instance, Clang will not emit type definitions for types -that are not needed by a module and could be replaced with a forward -declaration. Further, Clang will only emit type info for a dynamic -C++ class in the module that contains the vtable for the class. - -The B<-fstandalone-debug> option turns off these optimizations. This -is useful when working with 3rd-party libraries that don't come with -debug information. This is the default on Darwin. Note that Clang -will never emit type information for types that are not referenced at -all by the program. - -=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 (but do not run) 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 - -Pass the comma separated arguments in I to the assembler. - -=item B<-Wl,>I - -Pass the comma separated arguments in I to the linker. - -=item B<-Wp,>I - -Pass the comma separated arguments in I to the preprocessor. - -=item B<-Xanalyzer> I - -Pass I to the static analyzer. - -=item B<-Xassembler> I - -Pass I to the assembler. - -=item B<-Xlinker> I - -Pass I to the linker. - -=item B<-Xpreprocessor> I - -Pass I to the preprocessor. - -=item B<-o> I - -Write output to I. - -=item B<-print-file-name>=I - -Print the full library path of I. - -=item B<-print-libgcc-file-name> - -Print the library path for "libgcc.a". - -=item B<-print-prog-name>=I - -Print the full program path of I. - -=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 - -Adds an implicit #define into the predefines buffer which is read before the -source file is preprocessed. - -=item B<-U>I - -Adds an implicit #undef into the predefines buffer which is read before the -source file is preprocessed. - -=item B<-include> I - -Adds an implicit #include into the predefines buffer which is read before the -source file is preprocessed. - -=item B<-I>I - -Add the specified directory to the search path for include files. - -=item B<-F>I - -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 -#=item B<-iquote>I -#=item B<-isystem>I -#=item B<-iprefix>I -#=item B<-iwithprefix>I -#=item B<-iwithprefixbefore>I -#=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, B, B - -These environment variables are checked, in order, for the location to -write temporary files used during the compilation process. - -=item B - -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 -environment variable. - -Empty components in the environment variable are ignored. - -=item B, B, B, -B - -These environment variables specify additional paths, as for CPATH, -which are only used when processing the appropriate language. - -=item B - -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. 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). - -=cut Index: docs/tools/manpage.css =================================================================== --- docs/tools/manpage.css +++ /dev/null @@ -1,256 +0,0 @@ -/* Based on http://www.perldoc.com/css/perldoc.css */ - -@import url("../llvm.css"); - -body { font-family: Arial,Helvetica; } - -blockquote { margin: 10pt; } - -h1, a { color: #336699; } - - -/*** Top menu style ****/ -.mmenuon { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #ff6600; font-size: 10pt; -} -.mmenuoff { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #ffffff; font-size: 10pt; -} -.cpyright { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #ffffff; font-size: xx-small; -} -.cpyrightText { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #ffffff; font-size: xx-small; -} -.sections { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: 11pt; -} -.dsections { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: 12pt; -} -.slink { - font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; - color: #000000; font-size: 9pt; -} - -.slink2 { font-family: Arial,Helvetica; text-decoration: none; color: #336699; } - -.maintitle { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: 18pt; -} -.dblArrow { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: small; -} -.menuSec { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: small; -} - -.newstext { - font-family: Arial,Helvetica; font-size: small; -} - -.linkmenu { - font-family: Arial,Helvetica; color: #000000; font-weight: bold; - text-decoration: none; -} - -P { - font-family: Arial,Helvetica; -} - -PRE { - font-size: 10pt; -} -.quote { - font-family: Times; text-decoration: none; - color: #000000; font-size: 9pt; font-style: italic; -} -.smstd { font-family: Arial,Helvetica; color: #000000; font-size: x-small; } -.std { font-family: Arial,Helvetica; color: #000000; } -.meerkatTitle { - font-family: sans-serif; font-size: x-small; color: black; } - -.meerkatDescription { font-family: sans-serif; font-size: 10pt; color: black } -.meerkatCategory { - font-family: sans-serif; font-size: 9pt; font-weight: bold; font-style: italic; - color: brown; } -.meerkatChannel { - font-family: sans-serif; font-size: 9pt; font-style: italic; color: brown; } -.meerkatDate { font-family: sans-serif; font-size: xx-small; color: #336699; } - -.tocTitle { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #333333; font-size: 10pt; -} - -.toc-item { - font-family: Arial,Helvetica; font-weight: bold; - color: #336699; font-size: 10pt; text-decoration: underline; -} - -.perlVersion { - font-family: Arial,Helvetica; font-weight: bold; - color: #336699; font-size: 10pt; text-decoration: none; -} - -.podTitle { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #000000; -} - -.docTitle { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #000000; font-size: 10pt; -} -.dotDot { - font-family: Arial,Helvetica; font-weight: bold; - color: #000000; font-size: 9pt; -} - -.docSec { - font-family: Arial,Helvetica; font-weight: normal; - color: #333333; font-size: 9pt; -} -.docVersion { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: 10pt; -} - -.docSecs-on { - font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; - color: #ff0000; font-size: 10pt; -} -.docSecs-off { - font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; - color: #333333; font-size: 10pt; -} - -h2 { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: medium; -} -h1 { - font-family: Verdana,Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: large; -} - -DL { - font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; - color: #333333; font-size: 10pt; -} - -UL > LI > A { - font-family: Arial,Helvetica; font-weight: bold; - color: #336699; font-size: 10pt; -} - -.moduleInfo { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #333333; font-size: 11pt; -} - -.moduleInfoSec { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: 10pt; -} - -.moduleInfoVal { - font-family: Arial,Helvetica; font-weight: normal; text-decoration: underline; - color: #000000; font-size: 10pt; -} - -.cpanNavTitle { - font-family: Arial,Helvetica; font-weight: bold; - color: #ffffff; font-size: 10pt; -} -.cpanNavLetter { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #333333; font-size: 9pt; -} -.cpanCat { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: 9pt; -} - -.bttndrkblue-bkgd-top { - background-color: #225688; - background-image: url(/global/mvc_objects/images/bttndrkblue_bgtop.gif); -} -.bttndrkblue-bkgd-left { - background-color: #225688; - background-image: url(/global/mvc_objects/images/bttndrkblue_bgleft.gif); -} -.bttndrkblue-bkgd { - padding-top: 0px; - padding-bottom: 0px; - margin-bottom: 0px; - margin-top: 0px; - background-repeat: no-repeat; - background-color: #225688; - background-image: url(/global/mvc_objects/images/bttndrkblue_bgmiddle.gif); - vertical-align: top; -} -.bttndrkblue-bkgd-right { - background-color: #225688; - background-image: url(/global/mvc_objects/images/bttndrkblue_bgright.gif); -} -.bttndrkblue-bkgd-bottom { - background-color: #225688; - background-image: url(/global/mvc_objects/images/bttndrkblue_bgbottom.gif); -} -.bttndrkblue-text a { - color: #ffffff; - text-decoration: none; -} -a.bttndrkblue-text:hover { - color: #ffDD3C; - text-decoration: none; -} -.bg-ltblue { - background-color: #f0f5fa; -} - -.border-left-b { - background: #f0f5fa url(/i/corner-leftline.gif) repeat-y; -} - -.border-right-b { - background: #f0f5fa url(/i/corner-rightline.gif) repeat-y; -} - -.border-top-b { - background: #f0f5fa url(/i/corner-topline.gif) repeat-x; -} - -.border-bottom-b { - background: #f0f5fa url(/i/corner-botline.gif) repeat-x; -} - -.border-right-w { - background: #ffffff url(/i/corner-rightline.gif) repeat-y; -} - -.border-top-w { - background: #ffffff url(/i/corner-topline.gif) repeat-x; -} - -.border-bottom-w { - background: #ffffff url(/i/corner-botline.gif) repeat-x; -} - -.bg-white { - background-color: #ffffff; -} - -.border-left-w { - background: #ffffff url(/i/corner-leftline.gif) repeat-y; -}