347 lines
9.7 KiB
Groff
347 lines
9.7 KiB
Groff
.\" 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)
|