1INCLUDE-WHAT-YOU-USE(1) User Commands INCLUDE-WHAT-YOU-USE(1)
2
6 include-what-you-use - analyze includes in C and C++ source files.
7
9 include-what-you-use [-Xiwyu option]... [clang-options] file
10
12 “Include what you use” means this: for every symbol (type, function,
13 variable, or macro) that you use in foo.cpp, either foo.cpp or foo.h
14 should include a header file that exports the declaration of that sym‐
15 bol. include-what-you-use is a tool to analyze includes of source
16 files to find “include-what-you-use” violations, and suggest fixes for
17 them.
18 The main goal of include-what-you-use is to remove superfluous in‐
20 cludes. It does this both by figuring out what includes are not actu‐
21 ally needed for this file (for both source and header files), and by
22 replacing includes with forward declarations when possible.
23
25 Options for include-what-you-use have to be preceded with -Xiwyu. All
26 other options are interpreted as clang(1) compiler options.
27 --check_also=glob
29 Print “include-what-you-use”-violation info for all files match‐
30 ing the given glob pattern (in addition to the default of re‐
31 porting for the input source file and associated header files).
32 This flag may be specified multiple times to specify multiple
33 glob patterns.
34 --comment_style=verbosity
36 Controls the style and verbosity of “why” comments at the end of
37 suggested includes. Options for verbosity are:
38 none No “why” comments.
40 short “Why” comments include symbol names, but no namespaces.
42 This is the default.
43 long “Why” comments include symbol names with namespaces.
45 --cxx17ns
47 Suggest the more concise syntax for nested namespaces introduced
48 in C++17.
49 --error[=N]
51 Exit with error code N (defaults to 1 if omitted) if there are
52 “include-what-you-use” violations.
53 --error_always[=N]
55 Exit with error code N (defaults to 1 if omitted) whether there
56 are “include-what-you-use” violations or not (for use with
57 make(1)).
58 --keep=glob
60 Always keep the includes matched by glob. This flag may be used
61 multiple times to specify more than one glob pattern.
62 --mapping_file=filename
64 Use the given mapping file.
65 --max_line_length
67 Maximum line length for includes. Note that this only affects
68 the comments and their alignment, the maximum line length can
69 still be exceeded with long filenames (default: 80).
70 --no_comments
72 Do not add comments after includes about which symbols the
73 header was required for.
74 --no_default_mappings
76 Do not use the default mappings.
77 --no_fwd_decls
79 Do not use forward declarations, and instead always include the
80 required header.
81 --pch_in_code
83 Mark the first include in a translation unit as a precompiled
84 header. Use --pch_in_code to prevent removal of necessary PCH
85 includes. Although clang(1) forces PCHs to be listed as prefix
86 headers, the PCH-in-code pattern can be used with gcc(1).
87 --prefix_header_includes=value
89 Controls how includes and forward declarations involving prefix
90 headers should be handled. Prefix headers are files included
91 via the command-line option -include. This option specifies
92 what to do if a prefix header makes includes or forward declara‐
93 tions obsolete. The following values are allowed:
94 add New includes are added. This is the default.
96 keep No new includes are added, existing ones are kept intact.
98 remove No new includes are added, existing ones are removed.
100 --quoted_includes_first
102 When sorting includes, place quoted includes first.
103 --regex=dialect
105 Use the specified regex dialect for matching in IWYU:
106 llvm Fast and simple extended regular expressions. This is the
108 default.
109 ecmascript
111 Slower but more full-featured regular expressions with
112 support for lookaround assertions, etc.
113 --transitive_includes_only
115 Do not suggest that a file should add foo.h unless foo.h is al‐
116 ready visible in the file's transitive includes.
117 --update_comments
119 Print full include list with comments, even if there are no “in‐
120 clude-what-you-use” violations.
121 --verbose=level
123 Set verbosity. At the highest level, this will dump the AST of
124 the source file and explain all decisions.
125
127 By default include-what-you-use exits with zero exit code unless
128 there's a critical error, but --error or --error_always can be used to
129 customize the exit code depending on invoker expectations. For an ex‐
130 ample see below.
131
134 Sometimes headers are not meant to be included directly, and sometimes
135 headers are guaranteed to include other headers. Since this is hard to
136 tell from the source code alone, these relationships have to be pro‐
137 vided via mapping files or pragma comments.
138 A mapping file consists of a comma-separated list of rules enclosed by
140 square brackets []. A rule can be any of the following:
141 { include: [header, header] }
143 Declares that instead of the first header the second can be
144 used. A header can appear on the left-hand side in multiple
145 rules, meaning that any of the right-hand side headers can be
146 used instead.
147 { symbol: [symbol, header] }
149 Declares that to use a symbol, a certain header should be in‐
150 cluded.
151 { ref: mapping-file }
153 Includes the contents of another mapping-file.
154 The descriptions of headers and symbols are as follows:
156 header := "include-spec", visibility
158 Describes a header file. The include-spec specifies the header
159 file and visibility specifies whether the header is public or
160 private. Private headers are not allowed to be included di‐
161 rectly. So every private header file should appear on the left-
162 hand side of a mapping at least once. The visibility of a
163 header file has to be the same for all rules it appears in!
164 include-spec := <system-header-file> | \"project-header-file\"
166 How the header is #included in a source file. Quotation marks
167 need to be escaped.
168 symbol := "symbol-name", visibility
170 Describes a symbol, for example a type, function or macro. The
171 visibility is ignored, by convention private is used.
172 Lines starting with # are treated as comments.
174
176 Pragma comments provide information about the relations between source
177 and header files and allow to whitelist or blacklist #includes and for‐
178 ward declarations.
179 All arguments should be enclosed in quotation marks.
181 // IWYU pragma: keep
183 Used after #include directives or forward declarations it en‐
184 sures that they won't be removed.
185 // IWYU pragma: begin_keep, // IWYU pragma: end_keep
187 Has the same effect as the previous pragma comment, but applies
188 to a range of #includes and forward declarations instead of a
189 single line.
190 // IWYU pragma: export
192 Used after an #include directive or forward declaration it indi‐
193 cates that the current file is considered to be a provider of
194 any symbol from the included file or declaration.
195 // IWYU pragma: begin_exports, // IWYU pragma: end_exports
197 Has the same effect as the previous pragma comment, but applies
198 to a range of #includes or forward declarations instead of a
199 single line.
200 // IWYU pragma: private[, include header]
202 Indicates that the current file is considered private, and (op‐
203 tionally) that any symbol will be provided by header.
204 // IWYU pragma: no_include header
206 States that header should not be suggested for inclusion.
207 // IWYU pragma: no_forward_declare symbol
209 States that symbol should not be forward-declared.
210 // IWYU pragma: friend regex
212 Used in a private header, this indicates that all files matching
213 regex are allowed to #include it.
214 // IWYU pragma: associated
216 Used in a source file after an #include directive, this marks
217 the header as associated to the source file. This is required
218 if source and header filename differ in more than their ending.
219 Includes from an associated header are assumed in the source
220 file.
221
223 /usr/share/include-what-you-use
224 Directory containing the standard mapping files.
225
227 See the issue tracker ⟨https://github.com/include-what-you-use/include-
228 what-you-use/issues⟩ on GitHub.
229
231 It is possible to put include-what-you-use in place of your compiler to
232 process all source files known to your build system
233 make -k CC=include-what-you-use CFLAGS="-Xiwyu --error_always"
235 make -k CXX=include-what-you-use CXXFLAGS="-Xiwyu --error_always"
237 With -Xiwyu --error_always the program always exits with an error code,
239 so the build system knows that it didn't build an object file. Hence
240 the need for -k. It only analyzes source files built by make(1) along
241 with their corresponding header files. If a project has a header file
242 with no corresponding source file, include-what-you-use will ignore it
243 unless you use the --check_also option to add it for analysis together
244 with a source file.
245 CMake has built-in support for include-what-you-use as of version 3.3.
247 With the CMAKE_CXX_INCLUDE_WHAT_YOU_USE option, CMake runs it on every
248 source file after compilation:
249 cmake -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="include-what-you-use <args>" ..
251 The option is supported for both C and C++, so use CMAKE_C_IN‐
253 CLUDE_WHAT_YOU_USE for C code.
254
256 clang(1), make(1)
257include-what-you-use 2022-02-21 INCLUDE-WHAT-YOU-USE(1)