================
-modularize Usage
+Modularize Usage
================
``modularize [<modularize-options>] <include-files-list> [<front-end-options>...]``
header2.h
header3.h: header1.h header2.h
-Note that unless a "-prefix (header path)" option is specified,
+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.
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.
+ directory. Use ``-prefix`` to specify a different directory.
+
+.. option:: -module-map-path=<module-map-path>
+
+ Generate a module map and output it to the given file. See the description
+ in :ref:`module-map-generation`.
+
+.. option:: -root-module=<root-name>
+
+ Put modules generated by the -module-map-path option in an enclosing
+ module with the given name. See the description in :ref:`module-map-generation`.
headers to behave poorly, and should be fixed before introducing a module
map.
+:program:`modularize` also has an assistant mode option for generating
+a module map file based on the provided header list. The generated file
+is a functional module map that can be used as a starting point for a
+module.map file.
+
Getting Started
===============
extern "C" {
^
The "extern "C" {}" block is here.
+
+.. _module-map-generation:
+
+Module Map Generation
+=====================
+
+If you specify the ``-module-map-path=<module map file>``,
+:program:`modularize` will output a module map based on the input header list.
+A module will be created for each header. Also, if the header in the header
+list is a partial path, a nested module hierarchy will be created in which a
+module will be created for each subdirectory component in the header path,
+with the header itself represented by the innermost module. If other headers
+use the same subdirectories, they will be enclosed in these same modules also.
+
+For example, for the header list::
+
+ SomeTypes.h
+ SomeDecls.h
+ SubModule1/Header1.h
+ SubModule1/Header2.h
+ SubModule2/Header3.h
+ SubModule2/Header4.h
+ SubModule2.h
+
+The following module map will be generated::
+
+ // Output/NoProblemsAssistant.txt\r
+ // Generated by: modularize -module-map-path=Output/NoProblemsAssistant.txt \
+ -root-module=Root NoProblemsAssistant.modularize\r
+ \r
+ module SomeTypes {\r
+ header "SomeTypes.h"\r
+ export *\r
+ }\r
+ module SomeDecls {\r
+ header "SomeDecls.h"\r
+ export *\r
+ }\r
+ module SubModule1 {\r
+ module Header1 {\r
+ header "SubModule1/Header1.h"\r
+ export *\r
+ }\r
+ module Header2 {\r
+ header "SubModule1/Header2.h"\r
+ export *\r
+ }\r
+ }\r
+ module SubModule2 {\r
+ module Header3 {\r
+ header "SubModule2/Header3.h"\r
+ export *\r
+ }\r
+ module Header4 {\r
+ header "SubModule2/Header4.h"\r
+ export *\r
+ }\r
+ header "SubModule2.h"\r
+ export *\r
+ }\r
+
+An optional ``-root-module=<root-name>`` option can be used to cause a root module
+to be created which encloses all the modules.
+
+For example, with the same header list from above::
+
+ // Output/NoProblemsAssistant.txt\r
+ // Generated by: modularize -module-map-path=Output/NoProblemsAssistant.txt \
+ -root-module=Root NoProblemsAssistant.modularize\r
+ \r
+ module Root {\r
+ module SomeTypes {\r
+ header "SomeTypes.h"\r
+ export *\r
+ }\r
+ module SomeDecls {\r
+ header "SomeDecls.h"\r
+ export *\r
+ }\r
+ module SubModule1 {\r
+ module Header1 {\r
+ header "SubModule1/Header1.h"\r
+ export *\r
+ }\r
+ module Header2 {\r
+ header "SubModule1/Header2.h"\r
+ export *\r
+ }\r
+ }\r
+ module SubModule2 {\r
+ module Header3 {\r
+ header "SubModule2/Header3.h"\r
+ export *\r
+ }\r
+ module Header4 {\r
+ header "SubModule2/Header4.h"\r
+ export *\r
+ }\r
+ header "SubModule2.h"\r
+ export *\r
+ }\r
+ }\r
+\r
+Note that headers with dependents will be ignored with a warning, as the\r
+Clang module mechanism doesn't support headers the rely on other headers\r
+to be included first.\r
+\r
+The module map format defines some keywords which can't be used in module\r
+names. If a header has one of these names, an underscore ('_') will be\r
+prepended to the name. For example, if the header name is ``header.h``,
+because ``header`` is a keyword, the module name will be ``_header``.
+For a list of the module map keywords, please see:
+`Lexical structure <http://clang.llvm.org/docs/Modules.html#lexical-structure>`_\r