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:: -root-module=<root-name>
64
65  Put modules generated by the -module-map-path option in an enclosing
66  module with the given name.  See the description in :ref:`module-map-generation`.
67
68.. option:: -block-check-header-list-only
69
70  Limit the #include-inside-extern-or-namespace-block
71  check to only those headers explicitly listed in the header list.
72  This is a work-around for avoiding error messages for private includes that
73  purposefully get included inside blocks.
74
75.. option:: -no-coverage-check
76
77  Don't do the coverage check for a module map.
78
79.. option:: -coverage-check-only
80
81  Only do the coverage check for a module map.
82