llvm-project/clang-tools-extra/docs/ModularizeUsage.rst

================
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, the underlying Clang front end assumes .h files
contain C source, so you might need to specify the ``-x c++`` Clang option
to tell Clang that the header contains C++ definitions.

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:: -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.