From 8eb384a97cfdc244a5ab81026677bcbaf8cf2ecf Mon Sep 17 00:00:00 2001 From: Andrew Wilkins <axwalk@gmail.com> Date: Tue, 30 Jun 2015 02:52:38 +0000 Subject: [PATCH] Sphinx-based clang man pages Summary: This diff introduces .rst files, Sphinx config, and a CMake target for building clang man pages. This will deprecate the existing .pod- based man page, and will integrate nicely with CMake. This diff does not remove the existing man page; that will be done in a follow-up once packagers have had a chance to react to the change. For now, only clang(1) has been done; others can be added over time by dropping additional files into the docs/CommandGuide directory. The index page for CommandGuide has been copied from LLVM's docs/CommandGuide. The man page itself is mostly the same, with a few minor cosmetic changes. The only major change is the SYNOPSIS section. I was unable to get .rst/Sphinx produce the same style as in the existing man page. Instead, I changed it to match the LLVM tools' relatively simple style. To build the man pages, use the "docs-clang-man" target if building with CMake. Otherwise, use "make -f Makefile.sphinx man". Reviewers: cmatthews, silvas Subscribers: dim, gaeke, beanz, cfe-commits Differential Revision: http://reviews.llvm.org/D10562 git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@241037 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CMakeLists.txt | 3 + docs/CommandGuide/clang.rst | 484 ++++++++++++++++++++++++++++ docs/CommandGuide/index.rst | 17 + docs/Makefile | 1 - docs/conf.py | 40 ++- docs/index.rst | 1 + docs/tools/Makefile | 116 ------- docs/tools/clang.pod | 614 ------------------------------------ docs/tools/manpage.css | 256 --------------- 9 files changed, 540 insertions(+), 992 deletions(-) create mode 100644 docs/CommandGuide/clang.rst create mode 100644 docs/CommandGuide/index.rst delete mode 100644 docs/tools/Makefile delete mode 100644 docs/tools/clang.pod delete mode 100644 docs/tools/manpage.css diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 20a1396c487..47bb2e0c4b9 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -87,5 +87,8 @@ if (LLVM_ENABLE_SPHINX) if (${SPHINX_OUTPUT_HTML}) add_sphinx_target(html clang) endif() + if (${SPHINX_OUTPUT_MAN}) + add_sphinx_target(man clang) + endif() endif() endif() diff --git a/docs/CommandGuide/clang.rst b/docs/CommandGuide/clang.rst new file mode 100644 index 00000000000..39dbe02a0b4 --- /dev/null +++ b/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 <http://clang-analyzer.llvm.org> 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 <language> + + Treat subsequent input files as having type language. + +.. option:: -std=<language> + + Specify the language standard to compile for. + +.. option:: -stdlib=<library> + + 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=<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 <architecture> + + Specify the architecture to build for. + +.. option:: -mmacosx-version-min=<version> + + 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=<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. + + +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=<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,<args> + + Pass the comma separated arguments in args to the assembler. + +.. option:: -Wl,<args> + + Pass the comma separated arguments in args to the linker. + +.. option:: -Wp,<args> + + Pass the comma separated arguments in args to the preprocessor. + +.. option:: -Xanalyzer <arg> + + Pass arg to the static analyzer. + +.. option:: -Xassembler <arg> + + Pass arg to the assembler. + +.. option:: -Xlinker <arg> + + Pass arg to the linker. + +.. option:: -Xpreprocessor <arg> + + Pass arg to the preprocessor. + +.. option:: -o <file> + + Write output to file. + +.. option:: -print-file-name=<file> + + Print the full library path of file. + +.. option:: -print-libgcc-file-name + + Print the library path for "libgcc.a". + +.. option:: -print-prog-name=<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<macroname>=<value> + + Adds an implicit #define into the predefines buffer which is read before the + source file is preprocessed. + +.. option:: -U<macroname> + + Adds an implicit #undef into the predefines buffer which is read before the + source file is preprocessed. + +.. option:: -include <filename> + + Adds an implicit #include into the predefines buffer which is read before the + source file is preprocessed. + +.. option:: -I<directory> + + Add the specified directory to the search path for include files. + +.. option:: -F<directory> + + 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 <http://llvm.org/bugs/>. 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)` + diff --git a/docs/CommandGuide/index.rst b/docs/CommandGuide/index.rst new file mode 100644 index 00000000000..826ed971198 --- /dev/null +++ b/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 diff --git a/docs/Makefile b/docs/Makefile index 96978d893ef..a409cf6025b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -8,7 +8,6 @@ ##===----------------------------------------------------------------------===## CLANG_LEVEL := .. -DIRS := tools ifdef BUILD_FOR_WEBSITE PROJ_OBJ_DIR = . diff --git a/docs/conf.py b/docs/conf.py index 9030c2c2875..b7ed23ac66d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,7 +41,7 @@ master_doc = 'index' # 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 @@ latex_documents = [ # 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 (<http://clang.llvm.org>)' +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 '<name> - <description>')") % ( + 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 diff --git a/docs/index.rst b/docs/index.rst index dec2bc828c1..d50667d5669 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,6 +32,7 @@ Using Clang as a Compiler SafeStack Modules MSVCCompatibility + CommandGuide/index FAQ Using Clang as a Library diff --git a/docs/tools/Makefile b/docs/tools/Makefile deleted file mode 100644 index 5521d6b764c..00000000000 --- a/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)' diff --git a/docs/tools/clang.pod b/docs/tools/clang.pod deleted file mode 100644 index 153f97b2caa..00000000000 --- a/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<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 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). - -=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>. - -=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> - -Do not emit any warnings 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 delimiter, 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 diff --git a/docs/tools/manpage.css b/docs/tools/manpage.css deleted file mode 100644 index c922564dc3c..00000000000 --- a/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; -} -- GitLab