102bad9fbSJohn Thompson================ 226ecaf95SJohn ThompsonModularize Usage 302bad9fbSJohn Thompson================ 42d2d45e3SJohn Thompson 59cb79646SJohn Thompson``modularize [<modularize-options>] [<module-map>|<include-files-list>]* 6469bbc00SJohn Thompson[<front-end-options>...]`` 72d2d45e3SJohn Thompson 82d2d45e3SJohn Thompson``<modularize-options>`` is a place-holder for options 92d2d45e3SJohn Thompsonspecific to modularize, which are described below in 102d2d45e3SJohn Thompson`Modularize Command Line Options`. 112d2d45e3SJohn Thompson 129cb79646SJohn Thompson``<module-map>`` specifies the path of a file name for an 139cb79646SJohn Thompsonexisting module map. The module map must be well-formed in 149cb79646SJohn Thompsonterms of syntax. Modularize will extract the header file names 159cb79646SJohn Thompsonfrom the map. Only normal headers are checked, assuming headers 169cb79646SJohn Thompsonmarked "private", "textual", or "exclude" are not to be checked 179cb79646SJohn Thompsonas a top-level include, assuming they either are included by 189cb79646SJohn Thompsonother headers which are checked, or they are not suitable for 199cb79646SJohn Thompsonmodules. 209cb79646SJohn Thompson 212d2d45e3SJohn Thompson``<include-files-list>`` specifies the path of a file name for a 222d2d45e3SJohn Thompsonfile containing the newline-separated list of headers to check 232d2d45e3SJohn Thompsonwith respect to each other. Lines beginning with '#' and empty 242d2d45e3SJohn Thompsonlines are ignored. Header file names followed by a colon and 252d2d45e3SJohn Thompsonother space-separated file names will include those extra files 262d2d45e3SJohn Thompsonas dependencies. The file names can be relative or full paths, 2702bad9fbSJohn Thompsonbut must be on the same line. For example:: 282d2d45e3SJohn Thompson 2902bad9fbSJohn Thompson header1.h 3002bad9fbSJohn Thompson header2.h 3102bad9fbSJohn Thompson header3.h: header1.h header2.h 322d2d45e3SJohn Thompson 3326ecaf95SJohn ThompsonNote that unless a ``-prefix (header path)`` option is specified, 342d2d45e3SJohn Thompsonnon-absolute file paths in the header list file will be relative 352d2d45e3SJohn Thompsonto the header list file directory. Use -prefix to specify a different 362d2d45e3SJohn Thompsondirectory. 372d2d45e3SJohn Thompson 382d2d45e3SJohn Thompson``<front-end-options>`` is a place-holder for regular Clang 392d2d45e3SJohn Thompsonfront-end arguments, which must follow the <include-files-list>. 40f9f62b11SJohn ThompsonNote that by default, modularize assumes .h files 41f9f62b11SJohn Thompsoncontain C++ source, so if you are using a different language, 42f9f62b11SJohn Thompsonyou might need to use a ``-x`` option to tell Clang that the 43f9f62b11SJohn Thompsonheader contains another language, i.e.: ``-x c`` 442d2d45e3SJohn Thompson 458eb8d936SJohn ThompsonNote also that because modularize does not use the clang driver, 468eb8d936SJohn Thompsonyou will likely need to pass in additional compiler front-end 478eb8d936SJohn Thompsonarguments to match those passed in by default by the driver. 488eb8d936SJohn Thompson 492d2d45e3SJohn ThompsonModularize Command Line Options 5002bad9fbSJohn Thompson=============================== 512d2d45e3SJohn Thompson 5281cf1e89SJohn Thompson.. option:: -prefix=<header-path> 532d2d45e3SJohn Thompson 542d2d45e3SJohn Thompson Prepend the given path to non-absolute file paths in the header list file. 552d2d45e3SJohn Thompson By default, headers are assumed to be relative to the header list file 5626ecaf95SJohn Thompson directory. Use ``-prefix`` to specify a different directory. 5726ecaf95SJohn Thompson 5826ecaf95SJohn Thompson.. option:: -module-map-path=<module-map-path> 5926ecaf95SJohn Thompson 6026ecaf95SJohn Thompson Generate a module map and output it to the given file. See the description 6126ecaf95SJohn Thompson in :ref:`module-map-generation`. 6226ecaf95SJohn Thompson 63*4018c624SJohn Thompson.. option:: -problem-files-list=<problem-files-list-file-name> 64*4018c624SJohn Thompson 65*4018c624SJohn Thompson For use only with module map assistant. Input list of files that 66*4018c624SJohn Thompson have problems with respect to modules. These will still be 67*4018c624SJohn Thompson included in the generated module map, but will be marked as 68*4018c624SJohn Thompson "excluded" headers. 69*4018c624SJohn Thompson 7026ecaf95SJohn Thompson.. option:: -root-module=<root-name> 7126ecaf95SJohn Thompson 7226ecaf95SJohn Thompson Put modules generated by the -module-map-path option in an enclosing 7326ecaf95SJohn Thompson module with the given name. See the description in :ref:`module-map-generation`. 74ecd3b04cSJohn Thompson 75ecd3b04cSJohn Thompson.. option:: -block-check-header-list-only 76ecd3b04cSJohn Thompson 77ecd3b04cSJohn Thompson Limit the #include-inside-extern-or-namespace-block 78ecd3b04cSJohn Thompson check to only those headers explicitly listed in the header list. 79ecd3b04cSJohn Thompson This is a work-around for avoiding error messages for private includes that 80ecd3b04cSJohn Thompson purposefully get included inside blocks. 818eb8d936SJohn Thompson 828eb8d936SJohn Thompson.. option:: -no-coverage-check 838eb8d936SJohn Thompson 848eb8d936SJohn Thompson Don't do the coverage check for a module map. 858eb8d936SJohn Thompson 868eb8d936SJohn Thompson.. option:: -coverage-check-only 878eb8d936SJohn Thompson 888eb8d936SJohn Thompson Only do the coverage check for a module map. 89*4018c624SJohn Thompson 90*4018c624SJohn Thompson.. option:: -display-file-lists 91*4018c624SJohn Thompson 92*4018c624SJohn Thompson Display lists of good files (no compile errors), problem files, 93*4018c624SJohn Thompson and a combined list with problem files preceded by a '#'. 94*4018c624SJohn Thompson This can be used to quickly determine which files have problems. 95*4018c624SJohn Thompson The latter combined list might be useful in starting to modularize 96*4018c624SJohn Thompson a set of headers. You can start with a full list of headers, 97*4018c624SJohn Thompson use -display-file-lists option, and then use the combined list as 98*4018c624SJohn Thompson your intermediate list, uncommenting-out headers as you fix them. 99