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