clang-tidy.md

API for calling declaring a clang-tidy lint aspect.

Typical usage:

First, install clang-tidy with llvm_toolchain or as a native binary (llvm_toolchain does not support Windows as of 06/2024, but providing a native clang-tidy.exe works)

Next, declare a binary target for it, typically in tools/lint/BUILD.bazel:

e.g. using llvm_toolchain:

native_binary(
    name = "clang_tidy",
    src = "@llvm_toolchain_llvm//:bin/clang-tidy"
    out = "clang_tidy",
)

e.g as native binary:

native_binary(
    name = "clang_tidy",
    src = "clang-tidy.exe"
    out = "clang_tidy",
)

Finally, create the linter aspect, typically in tools/lint/linters.bzl:

load("@aspect_rules_lint//lint:clang_tidy.bzl", "lint_clang_tidy_aspect")

clang_tidy = lint_clang_tidy_aspect(
    binary = Label("//path/to:clang-tidy"),
    configs = [Label("//path/to:.clang-tidy")],
)

clang_tidy_action

load("@aspect_rules_lint//lint:clang_tidy.bzl", "clang_tidy_action")

clang_tidy_action(ctx, compilation_context, executable, src, stdout, exit_code)

Create a Bazel Action that spawns a clang-tidy process.

Adapter for wrapping Bazel around https://clang.llvm.org/extra/clang-tidy/

PARAMETERS

Name	Description	Default Value
ctx	an action context OR aspect context	none
compilation_context	from target	none
executable	struct with a clang-tidy field	none
src	file object to lint	none
stdout	output file containing the stdout or --output-file of clang-tidy	none
exit_code	output file containing the exit code of clang-tidy. If None, then fail the build when clang-tidy exits non-zero.	none

clang_tidy_fix

load("@aspect_rules_lint//lint:clang_tidy.bzl", "clang_tidy_fix")

clang_tidy_fix(ctx, compilation_context, executable, src, patch, stdout, exit_code)

Create a Bazel Action that spawns clang-tidy with --fix.

PARAMETERS

Name	Description	Default Value
ctx	an action context OR aspect context	none
compilation_context	from target	none
executable	struct with a clang_tidy field	none
src	file object to lint	none
patch	output file containing the applied fixes that can be applied with the patch(1) command.	none
stdout	output file containing the stdout or --output-file of clang-tidy	none
exit_code	output file containing the exit code of clang-tidy	none

is_parent_in_list

load("@aspect_rules_lint//lint:clang_tidy.bzl", "is_parent_in_list")

is_parent_in_list(dir, list)

PARAMETERS

Name	Description	Default Value
dir	-	none
list	-	none

lint_clang_tidy_aspect

load("@aspect_rules_lint//lint:clang_tidy.bzl", "lint_clang_tidy_aspect")

lint_clang_tidy_aspect(binary, configs, global_config, header_filter, lint_target_headers,
                       angle_includes_are_system, verbose)

A factory function to create a linter aspect.

PARAMETERS

Name	Description	Default Value
binary	the clang-tidy binary, typically a rule like native_binary( name = "clang_tidy", src = "clang-tidy.exe" out = "clang_tidy", )	none
configs	labels of the .clang-tidy files to make available to clang-tidy's config search. These may be in subdirectories and clang-tidy will apply them if appropriate. This may also include .clang-format files which may be used for formatting fixes.	[]
global_config	label of a single global .clang-tidy file to pass to clang-tidy on the command line. This will cause clang-tidy to ignore any other config files in the source directories.	[]
header_filter	optional, set to a posix regex to supply to clang-tidy with the -header-filter option	""
lint_target_headers	optional, set to True to pass a pattern that includes all headers with the target's directory prefix. This crude control may include headers from the linted target in the results. If supplied, overrides the header_filter option.	False
angle_includes_are_system	controls how angle includes are passed to clang-tidy. By default, Bazel passes these as -isystem. Change this to False to pass these as -I, which allows clang-tidy to regard them as regular header files.	True
verbose	print debug messages including clang-tidy command lines being invoked.	False