| .\" t -*- coding: UTF-8 -*- |
| .\" Man page for include-what-you-use |
| .\" |
| .\" This file is distributed under the University of Illinois Open Source |
| .\" License. See LICENSE.TXT for details. |
| .\" |
| .TH INCLUDE-WHAT-YOU-USE 1 "2019-11-02" include-what-you-use "User Commands" |
| .SH NAME |
| include-what-you-use \- analyze includes in C and C++ source files. |
| .SH SYNOPSIS |
| .SY include-what-you-use |
| .RB [ \-Xiwyu |
| .IR option "]\&.\|.\|. [" clang-options "] " file |
| .YS |
| .SH DESCRIPTION |
| \(lqInclude what you use\(rq means this: for every symbol (type, function, |
| variable, or macro) that you use in |
| .IR foo.cpp , |
| either |
| .IR foo.cpp " or " foo.h |
| should include a header file that exports the declaration of that symbol. |
| .B include-what-you-use |
| is a tool to analyze includes of source files to find |
| \(lqinclude-what-you-use\(rq violations, and suggest fixes for them. |
| .PP |
| The main goal of |
| .B include-what-you-use |
| is to remove superfluous includes. |
| It does this both by figuring out what includes are not actually needed for this |
| file (for both source and header files), and by replacing includes with forward |
| declarations when possible. |
| .SH OPTIONS |
| Options for |
| .B include-what-you-use |
| have to be preceded with |
| .BR \-Xiwyu . |
| All other options are interpreted as |
| .BR clang (1) |
| compiler options. |
| .TP |
| .BI \-\-check_also= glob |
| Print \(lqinclude-what-you-use\(rq-violation info for all files matching the |
| given glob pattern (in addition to the default of reporting for the input |
| source file and associated header files). |
| This flag may be specified multiple times to specify multiple glob patterns. |
| .TP |
| .B \-\-cxx17ns |
| Suggest the more concise syntax for nested namespaces introduced in C++17. |
| .TP |
| .BI \-\-keep= glob |
| Always keep the includes matched by |
| .IR glob . |
| This flag may be used multiple times to specify more than one glob pattern. |
| .TP |
| .BI \-\-mapping_file= filename |
| Use the given mapping file. |
| .TP |
| .B \-\-max_line_length |
| Maximum line length for includes. |
| Note that this only affects the comments and their alignment, the maximum line |
| length can still be exceeded with long filenames (default: 80). |
| .TP |
| .B \-\-no_comments |
| Do not add comments after includes about which symbols the header was required |
| for. |
| .TP |
| .B \-\-no_default_mappings |
| Do not use the default mappings. |
| .TP |
| .B \-\-no_fwd_decls |
| Do not use forward declarations, and instead always include the required header. |
| .TP |
| .B \-\-pch_in_code |
| Mark the first include in a translation unit as a precompiled header. Use |
| .B \-\-pch_in_code |
| to prevent removal of necessary PCH includes. Although |
| .BR clang (1) |
| forces PCHs to be listed as prefix headers, the PCH-in-code pattern can be used |
| with |
| .BR gcc (1). |
| .TP |
| .BI \-\-prefix_header_includes= value |
| Controls how includes and forward declarations involving prefix headers should |
| be handled. |
| Prefix headers are files included via the command-line option |
| .BR -include . |
| This option specifies what to do if a prefix header makes includes or forward |
| declarations obsolete. |
| The following |
| .IR value s |
| are allowed: |
| .RS |
| .TP |
| .B add |
| New includes are added. This is the default. |
| .TP |
| .B keep |
| No new includes are added, existing ones are kept intact. |
| .TP |
| .B remove |
| No new includes are added, existing ones are removed. |
| .RE |
| .TP |
| .B \-\-quoted_includes_first |
| When sorting includes, place quoted includes first. |
| .TP |
| .B \-\-transitive_includes_only |
| Do not suggest that a file should add |
| .IR foo.h " unless " foo.h |
| is already visible in the file's transitive includes. |
| .TP |
| .BI \-\-verbose= level |
| Set verbosity. At the highest level, this will dump the AST of the source file |
| and explain all decisions. |
| .SH EXIT STATUS |
| .B include-what-you-use |
| always returns with a nonzero status code to make usage with |
| .BR make (1) |
| feasible. |
| .SH MAPPING FILES |
| Sometimes headers are not meant to be included directly, |
| and sometimes headers are guaranteed to include other headers. |
| Since this is hard to tell from the source code alone, |
| these relationships have to be provided via mapping files or pragma comments. |
| .PP |
| A mapping file consists of a comma-separated list of rules enclosed by square |
| brackets |
| .BR [] . |
| A rule can be any of the following: |
| .TP |
| .BI "{ include: [" header ", " header "] }" |
| Declares that instead of the first |
| .I header |
| the second can be used. |
| A header can appear on the left-hand side in multiple rules, |
| meaning that any of the right-hand side headers can be used instead. |
| .TP |
| .BI "{ symbol: [" symbol ", " header "] }" |
| Declares that to use a |
| .IR symbol , |
| a certain |
| .I header |
| should be included. |
| .TP |
| .BI "{ ref: " mapping-file " }" |
| Includes the contents of another |
| .IR mapping-file . |
| .PP |
| The descriptions of headers and symbols are as follows: |
| .TP |
| .IB "header\fR := " \(dq include-spec "\(dq, " visibility |
| Describes a header file. The |
| .I include-spec |
| specifies the header file and |
| .I visibility |
| specifies whether the header is |
| .BR public " or " private . |
| Private headers are not allowed to be included directly. |
| So every private header file should appear on the left-hand side of a mapping |
| at least once. |
| The visibility of a header file has to be the same for all rules it appears in! |
| .TP |
| .IB "include-spec\fR := " < system-header-file > \ |
| "\fR | " \e\(dq project-header-file \e\(dq |
| How the header is |
| .BR #include d |
| in a source file. |
| Quotation marks need to be escaped. |
| .TP |
| .IB "symbol\fR := " \(dq symbol-name "\(dq, " visibility |
| Describes a symbol, for example a type, function or macro. The |
| .I visibility |
| is ignored, by convention |
| .B private |
| is used. |
| .PP |
| Lines starting with |
| .B # |
| are treated as comments. |
| .SH PRAGMA COMMENTS |
| Pragma comments provide information about the relations between source and |
| header files and allow to whitelist or blacklist |
| .BR #include s |
| and forward declarations. |
| .PP |
| All arguments should be enclosed in quotation marks. |
| .TP |
| .B // IWYU pragma: keep |
| Used after |
| .B #include |
| directives or forward declarations it ensures that they won't be removed. |
| .TP |
| .B // IWYU pragma: export |
| Used after an |
| .B #include |
| directive it indicates that the current file is considered to be a provider of |
| the included file. |
| .TP |
| .BR "// IWYU pragma: begin_exports" , " // IWYU pragma: end_exports" |
| Has the same effect as the previous pragma comment, but applies to a range of |
| .BR #include s |
| instead of a single line. |
| .TP |
| .BR "// IWYU pragma: private" [ ", include \fIheader" ] |
| Indicates that the current file is considered private, |
| and (optionally) that any symbol will be provided by |
| .IR header . |
| .TP |
| .BI "// IWYU pragma: no_include " header |
| States that |
| .I header |
| should not be suggested for inclusion. |
| .TP |
| .BI "// IWYU pragma: no_forward_declare "symbol |
| States that |
| .I symbol |
| should not be forward-declared. |
| .TP |
| .BI "// IWYU pragma: friend " regex |
| Used in a private header, this indicates that all files matching |
| .I regex |
| are allowed to |
| .B #include |
| it. |
| .TP |
| .B // IWYU pragma: associated |
| Used in a source file after an |
| .B #include |
| directive, this marks the header as associated to the source file. |
| This is required if source and header filename differ in more than their ending. |
| Includes from an associated header are assumed in the source file. |
| .SH FILES |
| .I /usr/share/include-what-you-use |
| .RS |
| Directory containing the standard mapping files. |
| .SH BUGS |
| See the |
| .UR https://github.com/include-what-you-use/include-what-you-use/issues |
| issue tracker |
| .UE |
| on GitHub. |
| .SH EXAMPLE |
| The easiest way to run |
| .B include-what-you-use |
| over your codebase is to run |
| .PP |
| .RS |
| .EX |
| make \-k CC=include-what-you-use CXX=include-what-you-use |
| .EE |
| .RE |
| .PP |
| The program always exits with an error code, so the build system knows that it |
| didn't build an object file. Hence the need for |
| .BR -k . |
| It only analyzes source files built by |
| .BR make (1) |
| along with their corresponding header files. |
| If a project has a header file with no corresponding source file, |
| .B include-what-you-use |
| will ignore it unless you use the |
| .B \-\-check_also |
| option to add it for analysis together with a source file. |
| .PP |
| CMake has built-in support for |
| .B include-what-you-use |
| as of version 3.3. With the |
| .B CMAKE_CXX_INCLUDE_WHAT_YOU_USE |
| option, CMake runs it on every source file after compilation: |
| .PP |
| .RS |
| .EX |
| cmake \-DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="include-what-you-use <args>" .. |
| .EE |
| .RE |
| .PP |
| The option is supported for both C and C++, so use |
| .B CMAKE_C_INCLUDE_WHAT_YOU_USE |
| for C code. |
| .SH "SEE ALSO" |
| .BR clang (1), |
| .BR make (1) |