[clang-tools-extra] r191091 - Added modularize documentation.
John Thompson
john.thompson.jtsoftware at gmail.com
Mon Sep 23 07:22:04 PDT 2013
Thanks!
On Fri, Sep 20, 2013 at 4:40 PM, Sean Silva <silvas at purdue.edu> 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 <
> 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
>>
>
>
--
John Thompson
John.Thompson.JTSoftware at gmail.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20130923/0838c5fc/attachment.html>
More information about the cfe-commits
mailing list