dwyu_aspect.md

dwyu_cc_aspect_factory

load("@depend_on_what_you_use//dwyu/cc/aspect:factory.bzl", "dwyu_cc_aspect_factory")

dwyu_cc_aspect_factory(analysis_ignores_private_headers_from_deps, analysis_optimizes_impl_deps,
                       analysis_reports_missing_direct_deps, analysis_reports_unused_deps,
                       ignored_includes, ignored_unused_deps, preprocessing_mode, recursive,
                       skip_external_targets, skip_toolchain_features, skipped_tags, target_mapping,
                       verbose)

Create and configure a "Depend on What You Use" (DWYU) aspect.

You might have targets which require different DWYU settings than the ones set by you with the aspect factory. If this is the case for a separate part of your project, an easy solution can be to create a second aspect instance with different settings and use that for the targets in question. However, if the issue is with individual targets, you can also use the following tags to override the DWYU settings for those specific targets. Using tags to control the DWYU behavior is demonstrated in the configuration_via_tags example.
The detailed description for the features controlled by these tags can be found below in the documentation of the aspect factory parameters. If a tag sets a single value attribute, the tag value will override the value set by the aspect factory or via --aspects_parameters. If a tag sets a list attribute, the tag value will be appended to the list set by the aspect factory.

Tag	Description
dwyu:skip	Do not perform any DWYU analysis.
dwyu:ignore_private_headers_from_deps=[True|False]	Control whether to consider private headers from the srcs attribute of dependencies.
dwyu:optimize_impl_deps=[True|False]	Control optimizing implementation dependencies.
dwyu:report_missing_direct_deps=[True|False]	Control reporting missing direct dependencies.
dwyu:report_unused_deps=[True|False]	Control reporting unused dependencies.
dwyu:ignore_include=<include>	Ignore the specified include for the missing direct dependencies check. Provide without quoting (aka < or "). Does not support setting patterns. Multiple uses are accumulated.
dwyu:ignore_unused_dep=<dep>	Ignore the specified dependency for the unused dependencies check. Has to use the canonical repo name. The examples show an elegant way to do this. Multiple uses are accumulated.
dwyu:preprocessing_mode=<mode>	Control the preprocessing mode.

PARAMETERS

Name	Description	Default Value
analysis_ignores_private_headers_from_deps	Setting this to False will allow headers listed in the srcs attributes of a dependency to fulfill the DWYU checks on top of those from the hdrs attribute. By default, DWYU uses only headers from the hdrs attribute. Strictly speaking, using headers from the srcs attribute of a dependency is wrong, as they are an implementation detail of the dependency. However, Bazel does not enforce this and forwards those private headers to the compile step. Use this flag if you have code outside your control using private headers or simply are not interested in the distinction of public and private headers. This flag can also be controlled in a Bazel config or on the command line via --aspects_parameters=dwyu_analysis_ignores_private_headers_from_deps=[True|False].	True
analysis_optimizes_impl_deps	Setting this to True will raise an error for cc_library targets where headers from a deps dependency are used only in private files. Such dependencies should be moved from deps to implementation_deps to optimize the dependency graph of the project. This flag can also be controlled in a Bazel config or on the command line via --aspects_parameters=dwyu_analysis_optimizes_impl_deps=[True|False]. This feature is demonstrated in the basic_usage example.	False
analysis_reports_missing_direct_deps	Setting this to True will report include statements in the files of the target under inspection which are not covered by any of the direct dependencies of the target. This is useful to identify missing dependencies in the dependency graph of the project. This flag can also be controlled in a Bazel config or on the command line via --aspects_parameters=dwyu_analysis_reports_missing_direct_deps=[True|False].	True
analysis_reports_unused_deps	Setting this to True will report dependencies which are not used in any of the files of the target under inspection as unused. This is useful to identify dependencies which can be removed from the dependency graph of the project. This flag is only supported by the C++ based implementation of DWYU. This flag can also be controlled in a Bazel config or on the command line via --aspects_parameters=dwyu_analysis_reports_unused_deps=[True|False]	True
ignored_includes	The DWYU analysis ignores all files which are provided by the Bazel CC toolchain (e.g. the standard library headers). If you want to ignore additional headers, you can provide a json file with the information to this attribute. The ignore logic works on the path provided to the include statement, e.g. #include <foo/bar.h> will be checked against the ignore list as foo/bar.h. Json file specification: ignore_include_paths : List of include paths which are ignored by the analysis. ignore_include_patterns : List of patterns which are ignored by the analysis. The boost regex library is used to parse the patterns. The boost::regex_search function is used to compare the patterns to the include statements. This feature is demonstrated in the ignoring_includes example.	None
ignored_unused_deps	There might be dependencies triggering the DWYU check for unused dependencies which you want to ignore. You can provide here a list of targets which will be ignored for the unused dependencies check. You have to use the Label constructor, you can't use bare strings. For example: ignored_unused_deps = [Label("//some:target")]	[]
preprocessing_mode	DWYU performs a preprocessing step on the code to extract the relevant include statements. This options allows configuring different strategies for this with varying speed and capabilities tradeoffs. We perform a preprocessing to be able to ignore CC toolchain headers and resolve conditional include logic (#ifdef around include statements) and other preprocessor directives influencing include statements (e.g. a macro defining the to be included header path). The available preprocessing modes are: full: (Default). In this mode, we use the boost::wave library to preprocess the code. This also involves recursively preprocessing all included header files. While this mode is the slowest, it is able to handle most kinds of conditional include logic or macros influencing include statements. ignore_system_includes: Works similar to full, but should be faster for most projects. In this mode, we do not look into header files included as system includes (aka using the '<>' notation) during the preprocessing step. Often, the system includes are not relevant for the conditional include logic in the user's code. At the same time they can point to large and complex headers which take a lot of time to preprocess (e.g. <gtest/gtest.h>). fast: The fastest preprocessing mode, which does however not support conditional include logic or macros influencing include statements. In this mode, we do not use boost::wave to preprocess the code. We simply extract all existing include statements without looking into the recursively included headers.	"full"
recursive	By default, the DWYU aspect analyzes only the target it is being applied to. You can change this to recursively analyzing dependencies following the deps and implementation_deps attributes by setting this to True. This feature is demonstrated in the recursion example.	False
skip_external_targets	Sometimes external dependencies are not our under control and thus analyzing them is of little value. If this flag is True, DWYU will automatically skip all targets from external workspaces. This can be useful in combination with the recursive analysis mode. This feature is demonstrated in the skipping_targets example.	False
skip_toolchain_features	A list of C++ toolchain feature strings that control when the DWYU analysis is skipped. When a feature name is prefixed with - (e.g. -layering_check), the analysis is skipped if that feature is disabled. When a feature name has no prefix (e.g. some_feature), the analysis is skipped if that feature is enabled. This allows gating DWYU on the state of C++ toolchain features configured via the standard features attribute. Please note, this is based on the features the active toolchain understands and not string comparison done with the features attribute values. Meaning, changing the toolchain can change the skipping behavior, even if the features attributes of your cc_* targets remain constant.	[]
skipped_tags	Do not execute the DWYU analysis on targets with at least one of those tags. By default skips the analysis for targets tagged with 'dwyu:skip'. The legacy tag 'no-dwyu' is also skipped by default. This feature is demonstrated in the skipping_targets example.	["no-dwyu", "dwyu:skip"]
target_mapping	Accepts a dwyu_make_cc_info_mapping target. Allows virtually combining targets regarding which header can be provided by which dependency. For the full details see the dwyu_make_cc_info_mapping documentation. This feature is demonstrated in the target_mapping example.	None
verbose	If True, print debugging information about the individual DWYU actions. This flag can also be controlled in a Bazel config or on the command line via --aspects_parameters=dwyu_verbose=[True|False].	False

RETURNS

Configured DWYU aspect