clang-tools-extra/docs/ModularizeUsage.rst

   1 ================
   2 Modularize 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
   9 specific 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
  13 existing module map. The module map must be well-formed in
  14 terms of syntax. Modularize will extract the header file names
  15 from the map. Only normal headers are checked, assuming headers
  16 marked "private", "textual", or "exclude" are not to be checked
  17 as a top-level include, assuming they either are included by
  18 other headers which are checked, or they are not suitable for
  19 modules.
  20
  21 ``<include-files-list>`` specifies the path of a file name for a
  22 file containing the newline-separated list of headers to check
  23 with respect to each other. Lines beginning with '#' and empty
  24 lines are ignored. Header file names followed by a colon and
  25 other space-separated file names will include those extra files
  26 as dependencies. The file names can be relative or full paths,
  27 but must be on the same line. For example::
  28
  29   header1.h
  30   header2.h
  31   header3.h: header1.h header2.h
  32
  33 Note that unless a ``-prefix (header path)`` option is specified,
  34 non-absolute file paths in the header list file will be relative
  35 to the header list file directory. Use -prefix to specify a different
  36 directory.
  37
  38 ``<front-end-options>`` is a place-holder for regular Clang
  39 front-end arguments, which must follow the <include-files-list>.
  40 Note that by default, modularize assumes .h files
  41 contain C++ source, so if you are using a different language,
  42 you might need to use a ``-x`` option to tell Clang that the
  43 header contains another language, i.e.:  ``-x c``
  44
  45 Note also that because modularize does not use the clang driver,
  46 you will likely need to pass in additional compiler front-end
  47 arguments to match those passed in by default by the driver.
  48
  49 Modularize 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.