97 lines
3.2 KiB
ReStructuredText
97 lines
3.2 KiB
ReStructuredText
|
.. 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.
|