[clang-tools-extra] r191091 - Added modularize documentation.
Sean Silva
silvas at purdue.edu
Fri Sep 20 16:40:21 PDT 2013
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 <
John.Thompson.JTSoftware at gmail.com> 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
> cfe-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20130920/79889f1e/attachment.html>
More information about the cfe-commits
mailing list