include-what-you-use.1

.\" 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 "2022-02-21" 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
.BI \-\-comment_style= verbosity
Controls the style and verbosity of \(lqwhy\(rq comments at the end of
suggested includes. Options for
.I verbosity
are:
.RS
.TP
.B none
No \(lqwhy\(rq comments.
.TP
.B short
\(lqWhy\(rq comments include symbol names, but no namespaces. This is the
default.
.TP
.B long
\(lqWhy\(rq comments include symbol names with namespaces.
.RE
.TP
.B \-\-cxx17ns
Suggest the more concise syntax for nested namespaces introduced in C++17.
.TP
.BR \-\-error [ =\fIN ]
Exit with error code
.IR N
(defaults to 1 if omitted) if there are \(lqinclude-what-you-use\(rq
violations.
.TP
.BR \-\-error_always [ =\fIN ]
Exit with error code
.IR N
(defaults to 1 if omitted) whether there are \(lqinclude-what-you-use\(rq
violations or not (for use with \fBmake\fR(1)).
.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
.BI \-\-regex= dialect
Use the specified regex
.IR dialect
for matching in IWYU:
.RS
.TP
.B llvm
Fast and simple extended regular expressions. This is the default.
.TP
.B ecmascript
Slower but more full-featured regular expressions with support for lookaround
assertions, etc.
.RE
.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 \-\-update_comments
Print full include list with comments, even if there are no
\(lqinclude-what-you-use\(rq violations.
.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
By default
.B include-what-you-use
exits with zero exit code unless there's a critical error, but
.B \-\-error
or
.B \-\-error_always
can be used to customize the exit code depending on invoker expectations.
For an example see below.

.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
.BR "// IWYU pragma: begin_keep" , " // IWYU pragma: end_keep"
Has the same effect as the previous pragma comment, but applies to a range of
.BR #include s
and forward declarations instead of a single line.
.TP
.B // IWYU pragma: export
Used after an
.B #include
directive or forward declaration it indicates that the current file is
considered to be a provider of any symbol from the included file or declaration.
.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
or forward declarations 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
It is possible to put
.B include-what-you-use
in place of your compiler to process all source files known to your build system
.PP
.RS
.EX
make \-k CC=include-what-you-use CFLAGS="-Xiwyu --error_always"
.EE

.EX
make \-k CXX=include-what-you-use CXXFLAGS="-Xiwyu --error_always"
.EE
.RE
.PP
With
.B -Xiwyu --error_always
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)