| .. index:: module-map-checker |
| |
| ================================ |
| Module-Map-Checker User's Manual |
| ================================ |
| |
| :program:`module-map-checker` is a tool that validates a module map by |
| checking that all headers in the corresponding directories are accounted for. |
| |
| This program uses the Clang ModuleMap class to read and parse the module |
| map file. Starting at the module map file directory, or just the include |
| paths, if specified, it will collect the names of all the files it |
| considers headers. It then compares the headers against those referenced |
| in the module map, either explicitly named, or implicitly named via an |
| umbrella directory or umbrella file, as parsed by the ModuleMap object. |
| If headers are found which are not referenced or covered by an umbrella |
| directory or file, warning messages will be produced, and this program |
| will return an error code of 1. Other errors result in an error code of 2. |
| If no problems are found, an error code of 0 is returned. |
| |
| Note that in the case of umbrella headers, this tool invokes the compiler |
| to preprocess the file, and uses a callback to collect the header files |
| included by the umbrella header or any of its nested includes. If any |
| front end options are needed for these compiler invocations, these |
| can be included on the command line after the module map file argument. |
| |
| Warning message have the form:: |
| |
| warning: module.map does not account for file: header.h |
| |
| Note that for the case of the module map referencing a file that does |
| not exist, the module map parser in Clang will display an error message. |
| |
| 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 ``module-map-checker`` target to build |
| just the module-map-checker tool and its dependencies. |
| |
| .. _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 |
| |
| Module-Map-Checker Usage |
| ======================== |
| |
| ``module-map-checker [<module-map-checker-options>] <module-map-file> [<front-end-options>...]`` |
| |
| ``<module-map-checker-options>`` is a place-holder for options |
| specific to module-map-checker, which are described below in |
| `Module-Map-Checker Command Line Options`. |
| |
| ``<module-map-file>`` specifies the path of a module map |
| file. The path can be relative to the current directory. |
| |
| ``<front-end-options>`` is a place-holder for regular Clang |
| front-end arguments, which must follow the <module-map-file>. |
| |
| Module-Map-Checker Command Line Options |
| ======================================= |
| |
| .. option:: -I(include path) |
| |
| Look at headers only in this directory tree. |
| Must be a path relative to the module.map file. |
| There can be multiple ``-I`` options, for when the |
| module map covers multiple directories, and |
| excludes higher or sibling directories not |
| specified. If this option is omitted, the |
| directory containing the module-map-file is |
| the root of the header tree to be searched for |
| headers. |
| |
| .. option:: -dump-module-map |
| |
| Dump the module map object during the check. |
| This displays the modules and headers. |