Thanks! On Fri, Sep 20, 2013 at 4:40 PM, Sean Silva <[email protected]> wrote:
> Diagnostics are typically read in monospace (and caret diagnostics don't > make sense without monospace) so please use monospace for the example > diagnostics. See <http://sphinx-doc.org/rest.html#source-code>. > > If you haven't stumbled across it already, you may find < > http://llvm.org/docs/SphinxQuickstartTemplate.html> useful. > > -- Sean Silva > > > On Fri, Sep 20, 2013 at 10:40 AM, John Thompson < > [email protected]> wrote: > >> Author: jtsoftware >> Date: Fri Sep 20 09:40:52 2013 >> New Revision: 191091 >> >> URL: http://llvm.org/viewvc/llvm-project?rev=191091&view=rev >> Log: >> Added modularize documentation. >> >> Added: >> clang-tools-extra/trunk/docs/ModularizeUsage.rst >> clang-tools-extra/trunk/docs/modularize.rst >> Modified: >> clang-tools-extra/trunk/docs/index.rst >> >> Added: clang-tools-extra/trunk/docs/ModularizeUsage.rst >> URL: >> http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/ModularizeUsage.rst?rev=191091&view=auto >> >> ============================================================================== >> --- clang-tools-extra/trunk/docs/ModularizeUsage.rst (added) >> +++ clang-tools-extra/trunk/docs/ModularizeUsage.rst Fri Sep 20 09:40:52 >> 2013 >> @@ -0,0 +1,41 @@ >> +===================== >> +modularize Usage >> +===================== >> + >> +``modularize [<modularize-options>] <include-files-list> >> [<front-end-options>...]`` >> + >> +``<modularize-options>`` is a place-holder for options >> +specific to modularize, which are described below in >> +`Modularize Command Line Options`. >> + >> +``<include-files-list>`` specifies the path of a file name for a >> +file containing the newline-separated list of headers to check >> +with respect to each other. Lines beginning with '#' and empty >> +lines are ignored. Header file names followed by a colon and >> +other space-separated file names will include those extra files >> +as dependencies. The file names can be relative or full paths, >> +but must be on the same line. For example: >> + >> + | header1.h >> + | header2.h >> + | header3.h: header1.h header2.h >> + >> +Note that unless a "-prefix (header path)" option is specified, >> +non-absolute file paths in the header list file will be relative >> +to the header list file directory. Use -prefix to specify a different >> +directory. >> + >> +``<front-end-options>`` is a place-holder for regular Clang >> +front-end arguments, which must follow the <include-files-list>. >> +Note that by default, the underlying Clang front end assumes .h files >> +contain C source, so you might need to specify the ``-x c++`` Clang >> option >> +to tell Clang that the header contains C++ definitions. >> + >> +Modularize Command Line Options >> +============================ >> + >> +.. option:: -prefix <header-path> >> + >> + Prepend the given path to non-absolute file paths in the header list >> file. >> + By default, headers are assumed to be relative to the header list file >> + directory. Use -prefix to specify a different directory. >> >> Modified: clang-tools-extra/trunk/docs/index.rst >> URL: >> http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/index.rst?rev=191091&r1=191090&r2=191091&view=diff >> >> ============================================================================== >> --- clang-tools-extra/trunk/docs/index.rst (original) >> +++ clang-tools-extra/trunk/docs/index.rst Fri Sep 20 09:40:52 2013 >> @@ -16,6 +16,7 @@ Contents >> :maxdepth: 1 >> >> clang-modernize >> + modularize >> >> >> Doxygen Documentation >> >> Added: clang-tools-extra/trunk/docs/modularize.rst >> URL: >> http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/modularize.rst?rev=191091&view=auto >> >> ============================================================================== >> --- clang-tools-extra/trunk/docs/modularize.rst (added) >> +++ clang-tools-extra/trunk/docs/modularize.rst Fri Sep 20 09:40:52 2013 >> @@ -0,0 +1,96 @@ >> +.. index:: modularize >> + >> +================================== >> +Modularize User's Manual >> +================================== >> + >> +.. toctree:: >> + :hidden: >> + >> + ModularizeUsage >> + >> +:program:`modularize` is a standalone tool that checks whether a set of >> headers >> +provides the consistent definitions required to use modules. For >> example, it >> +detects whether the same entity (say, a NULL macro or size_t typedef) is >> +defined in multiple headers or whether a header produces different >> definitions >> +under different circumstances. These conditions cause modules built from >> the >> +headers to behave poorly, and should be fixed before introducing a module >> +map. >> + >> +Getting Started >> +=============== >> + >> +To build from source: >> + >> +1. Read `Getting Started with the LLVM System`_ and `Clang Tools >> + Documentation`_ for information on getting sources for LLVM, Clang, >> and >> + Clang Extra Tools. >> + >> +2. `Getting Started with the LLVM System`_ and `Building LLVM with >> CMake`_ give >> + directions for how to build. With sources all checked out into the >> + right place the LLVM build will build Clang Extra Tools and their >> + dependencies automatically. >> + >> + * If using CMake, you can also use the ``modularize`` target to build >> + just the modularize tool and its dependencies. >> + >> +Before continuing, take a look at :doc:`ModularizeUsage` to see how to >> invoke >> +modularize. >> + >> +.. _Getting Started with the LLVM System: >> http://llvm.org/docs/GettingStarted.html >> +.. _Building LLVM with CMake: http://llvm.org/docs/CMake.html >> +.. _Clang Tools Documentation: >> http://clang.llvm.org/docs/ClangTools.html >> + >> +What Modularize Checks >> +====================== >> + >> +Modularize will do normal C/C++ parsing, reporting normal errors and >> warnings, >> +but will also report special error messages like the following: >> + >> + | error: '(symbol)' defined at multiple locations: >> + | (file):(row):(column) >> + | (file):(row):(column) >> + >> + error: header '(file)' has different contents depending on how it was >> + included >> + >> +The latter might be followed by messages like the following: >> + >> + | note: '(symbol)' in (file) at (row):(column) not always provided >> + >> +Checks will also be performed for macro expansions, defined(macro) >> +expressions, and preprocessor conditional directives that evaluate >> +inconsistently, and can produce error messages like the following: >> + >> + | (...)/SubHeader.h:11:5: >> + | #if SYMBOL == 1 >> + | ^ >> + | error: Macro instance 'SYMBOL' has different values in this header, >> + | depending on how it was included. >> + | 'SYMBOL' expanded to: '1' with respect to these inclusion paths: >> + | (...)/Header1.h >> + | (...)/SubHeader.h >> + | (...)/SubHeader.h:3:9: >> + | #define SYMBOL 1 >> + | ^ >> + | Macro defined here. >> + | 'SYMBOL' expanded to: '2' with respect to these inclusion paths: >> + | (...)/Header2.h >> + | (...)/SubHeader.h >> + | (...)/SubHeader.h:7:9: >> + | #define SYMBOL 2 >> + | ^ >> + | Macro defined here. >> + >> +Checks will also be performed for '#include' directives that are >> +nested inside 'extern "C/C++" {}' or 'namespace (name) {}' blocks, >> +and can produce error message like the following: >> + >> + | IncludeInExtern.h:2:3: >> + | #include "Empty.h" >> + | ^ >> + | error: Include directive within extern "C" {}. >> + | IncludeInExtern.h:1:1: >> + | extern "C" { >> + | ^ >> + | The "extern "C" {}" block is here. >> >> >> _______________________________________________ >> cfe-commits mailing list >> [email protected] >> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits >> > > -- John Thompson [email protected]
_______________________________________________ cfe-commits mailing list [email protected] http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
