1================ 2Modularize Usage 3================ 4 5``modularize [<modularize-options>] [<module-map>|<include-files-list>]* 6[<front-end-options>...]`` 7 8``<modularize-options>`` is a place-holder for options 9specific to modularize, which are described below in 10`Modularize Command Line Options`. 11 12``<module-map>`` specifies the path of a file name for an 13existing module map. The module map must be well-formed in 14terms of syntax. Modularize will extract the header file names 15from the map. Only normal headers are checked, assuming headers 16marked "private", "textual", or "exclude" are not to be checked 17as a top-level include, assuming they either are included by 18other headers which are checked, or they are not suitable for 19modules. 20 21``<include-files-list>`` specifies the path of a file name for a 22file containing the newline-separated list of headers to check 23with respect to each other. Lines beginning with '#' and empty 24lines are ignored. Header file names followed by a colon and 25other space-separated file names will include those extra files 26as dependencies. The file names can be relative or full paths, 27but must be on the same line. For example:: 28 29 header1.h 30 header2.h 31 header3.h: header1.h header2.h 32 33Note that unless a ``-prefix (header path)`` option is specified, 34non-absolute file paths in the header list file will be relative 35to the header list file directory. Use -prefix to specify a different 36directory. 37 38``<front-end-options>`` is a place-holder for regular Clang 39front-end arguments, which must follow the <include-files-list>. 40Note that by default, modularize assumes .h files 41contain C++ source, so if you are using a different language, 42you might need to use a ``-x`` option to tell Clang that the 43header contains another language, i.e.: ``-x c`` 44 45Note also that because modularize does not use the clang driver, 46you will likely need to pass in additional compiler front-end 47arguments to match those passed in by default by the driver. 48 49Modularize Command Line Options 50=============================== 51 52.. option:: -prefix=<header-path> 53 54 Prepend the given path to non-absolute file paths in the header list file. 55 By default, headers are assumed to be relative to the header list file 56 directory. Use ``-prefix`` to specify a different directory. 57 58.. option:: -module-map-path=<module-map-path> 59 60 Generate a module map and output it to the given file. See the description 61 in :ref:`module-map-generation`. 62 63.. option:: -problem-files-list=<problem-files-list-file-name> 64 65 For use only with module map assistant. Input list of files that 66 have problems with respect to modules. These will still be 67 included in the generated module map, but will be marked as 68 "excluded" headers. 69 70.. option:: -root-module=<root-name> 71 72 Put modules generated by the -module-map-path option in an enclosing 73 module with the given name. See the description in :ref:`module-map-generation`. 74 75.. option:: -block-check-header-list-only 76 77 Limit the #include-inside-extern-or-namespace-block 78 check to only those headers explicitly listed in the header list. 79 This is a work-around for avoiding error messages for private includes that 80 purposefully get included inside blocks. 81 82.. option:: -no-coverage-check 83 84 Don't do the coverage check for a module map. 85 86.. option:: -coverage-check-only 87 88 Only do the coverage check for a module map. 89 90.. option:: -display-file-lists 91 92 Display lists of good files (no compile errors), problem files, 93 and a combined list with problem files preceded by a '#'. 94 This can be used to quickly determine which files have problems. 95 The latter combined list might be useful in starting to modularize 96 a set of headers. You can start with a full list of headers, 97 use -display-file-lists option, and then use the combined list as 98 your intermediate list, uncommenting-out headers as you fix them. 99