99 lines
3.8 KiB
ReStructuredText
99 lines
3.8 KiB
ReStructuredText
================
|
|
Modularize Usage
|
|
================
|
|
|
|
``modularize [<modularize-options>] [<module-map>|<include-files-list>]*
|
|
[<front-end-options>...]``
|
|
|
|
``<modularize-options>`` is a place-holder for options
|
|
specific to modularize, which are described below in
|
|
`Modularize Command Line Options`.
|
|
|
|
``<module-map>`` specifies the path of a file name for an
|
|
existing module map. The module map must be well-formed in
|
|
terms of syntax. Modularize will extract the header file names
|
|
from the map. Only normal headers are checked, assuming headers
|
|
marked "private", "textual", or "exclude" are not to be checked
|
|
as a top-level include, assuming they either are included by
|
|
other headers which are checked, or they are not suitable for
|
|
modules.
|
|
|
|
``<include-files-list>`` specifies the path of a file name for a
|
|
file containing the newline-separated list of headers to check
|
|
with respect to each other. Lines beginning with '#' and empty
|
|
lines are ignored. Header file names followed by a colon and
|
|
other space-separated file names will include those extra files
|
|
as dependencies. The file names can be relative or full paths,
|
|
but must be on the same line. For example::
|
|
|
|
header1.h
|
|
header2.h
|
|
header3.h: header1.h header2.h
|
|
|
|
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.
|
|
|
|
``<front-end-options>`` is a place-holder for regular Clang
|
|
front-end arguments, which must follow the <include-files-list>.
|
|
Note that by default, modularize assumes .h files
|
|
contain C++ source, so if you are using a different language,
|
|
you might need to use a ``-x`` option to tell Clang that the
|
|
header contains another language, i.e.: ``-x c``
|
|
|
|
Note also that because modularize does not use the clang driver,
|
|
you will likely need to pass in additional compiler front-end
|
|
arguments to match those passed in by default by the driver.
|
|
|
|
Modularize Command Line Options
|
|
===============================
|
|
|
|
.. option:: -prefix=<header-path>
|
|
|
|
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.
|
|
|
|
.. 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:: -problem-files-list=<problem-files-list-file-name>
|
|
|
|
For use only with module map assistant. Input list of files that
|
|
have problems with respect to modules. These will still be
|
|
included in the generated module map, but will be marked as
|
|
"excluded" headers.
|
|
|
|
.. 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`.
|
|
|
|
.. option:: -block-check-header-list-only
|
|
|
|
Limit the #include-inside-extern-or-namespace-block
|
|
check to only those headers explicitly listed in the header list.
|
|
This is a work-around for avoiding error messages for private includes that
|
|
purposefully get included inside blocks.
|
|
|
|
.. option:: -no-coverage-check
|
|
|
|
Don't do the coverage check for a module map.
|
|
|
|
.. option:: -coverage-check-only
|
|
|
|
Only do the coverage check for a module map.
|
|
|
|
.. option:: -display-file-lists
|
|
|
|
Display lists of good files (no compile errors), problem files,
|
|
and a combined list with problem files preceded by a '#'.
|
|
This can be used to quickly determine which files have problems.
|
|
The latter combined list might be useful in starting to modularize
|
|
a set of headers. You can start with a full list of headers,
|
|
use -display-file-lists option, and then use the combined list as
|
|
your intermediate list, uncommenting-out headers as you fix them.
|