From 26ecaf95a29676ba83508b0ba78b4a6344138f8e Mon Sep 17 00:00:00 2001 From: John Thompson Date: Wed, 16 Oct 2013 13:44:21 +0000 Subject: Added module map generation docs and some clean-up. llvm-svn: 192792 --- clang-tools-extra/docs/ModularizeUsage.rst | 16 +++- clang-tools-extra/docs/modularize.rst | 118 +++++++++++++++++++++++++++++ 2 files changed, 131 insertions(+), 3 deletions(-) (limited to 'clang-tools-extra/docs') diff --git a/clang-tools-extra/docs/ModularizeUsage.rst b/clang-tools-extra/docs/ModularizeUsage.rst index 64c89ed50bc..dc335431ba7 100644 --- a/clang-tools-extra/docs/ModularizeUsage.rst +++ b/clang-tools-extra/docs/ModularizeUsage.rst @@ -1,5 +1,5 @@ ================ -modularize Usage +Modularize Usage ================ ``modularize [] [...]`` @@ -20,7 +20,7 @@ but must be on the same line. For example:: 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. @@ -38,4 +38,14 @@ Modularize Command Line Options 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= + + Generate a module map and output it to the given file. See the description + in :ref:`module-map-generation`. + +.. option:: -root-module= + + 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`. diff --git a/clang-tools-extra/docs/modularize.rst b/clang-tools-extra/docs/modularize.rst index a389a7ab2b8..6e964dd337b 100644 --- a/clang-tools-extra/docs/modularize.rst +++ b/clang-tools-extra/docs/modularize.rst @@ -17,6 +17,11 @@ under different circumstances. These conditions cause modules built from the 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 =============== @@ -101,3 +106,116 @@ and can produce error message like the following:: extern "C" { ^ The "extern "C" {}" block is here. + +.. _module-map-generation: + +Module Map Generation +===================== + +If you specify the ``-module-map-path=``, +: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 + // Generated by: modularize -module-map-path=Output/NoProblemsAssistant.txt \ + -root-module=Root NoProblemsAssistant.modularize + + module SomeTypes { + header "SomeTypes.h" + export * + } + module SomeDecls { + header "SomeDecls.h" + export * + } + module SubModule1 { + module Header1 { + header "SubModule1/Header1.h" + export * + } + module Header2 { + header "SubModule1/Header2.h" + export * + } + } + module SubModule2 { + module Header3 { + header "SubModule2/Header3.h" + export * + } + module Header4 { + header "SubModule2/Header4.h" + export * + } + header "SubModule2.h" + export * + } + +An optional ``-root-module=`` 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 + // Generated by: modularize -module-map-path=Output/NoProblemsAssistant.txt \ + -root-module=Root NoProblemsAssistant.modularize + + module Root { + module SomeTypes { + header "SomeTypes.h" + export * + } + module SomeDecls { + header "SomeDecls.h" + export * + } + module SubModule1 { + module Header1 { + header "SubModule1/Header1.h" + export * + } + module Header2 { + header "SubModule1/Header2.h" + export * + } + } + module SubModule2 { + module Header3 { + header "SubModule2/Header3.h" + export * + } + module Header4 { + header "SubModule2/Header4.h" + export * + } + header "SubModule2.h" + export * + } + } + +Note that headers with dependents will be ignored with a warning, as the +Clang module mechanism doesn't support headers the rely on other headers +to be included first. + +The module map format defines some keywords which can't be used in module +names. If a header has one of these names, an underscore ('_') will be +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 `_ -- cgit v1.2.1