clang-tidy

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 = "@@//path/to:clang-tidy",
    configs = "@@//path/to:.clang-tidy",
)

Macros and Functions

is_parent_in_list

Example usage (generated):

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

is_parent_in_list(
    dir = None,
    list = None,
)

dir

Required.

list

Required.

clang_tidy_action

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

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

Example usage (generated):

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

clang_tidy_action(
    # an action context OR aspect context
    ctx = None,
    # from target
    compilation_context = None,
    # struct with a clang-tidy field
    executable = None,
    # file objects to lint
    srcs = [],
    # output file containing the stdout or --output-file of clang-tidy
    stdout = None,
    # output file containing the exit code of clang-tidy
    exit_code = None,
)

ctx

Required.

an action context OR aspect context

compilation_context

Required.

from target

executable

Required.

struct with a clang-tidy field

srcs

Required.

file objects to lint

stdout

Required.

output file containing the stdout or --output-file of clang-tidy

exit_code

Required.

output file containing the exit code of clang-tidy. If None, then fail the build when clang-tidy exits non-zero.

clang_tidy_fix

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

Example usage (generated):

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

clang_tidy_fix(
    # an action context OR aspect context
    ctx = None,
    # from target
    compilation_context = None,
    # struct with a clang_tidy field
    executable = None,
    # list of file objects to lint
    srcs = [],
    # output file containing the applied fixes that can be applied with the patch(1) command.
    patch = None,
    # output file containing the stdout or --output-file of clang-tidy
    stdout = None,
    # output file containing the exit code of clang-tidy
    exit_code = None,
)

ctx

Required.

an action context OR aspect context

compilation_context

Required.

from target

executable

Required.

struct with a clang_tidy field

srcs

Required.

list of file objects to lint

patch

Required.

output file containing the applied fixes that can be applied with the patch(1) command.

stdout

Required.

output file containing the stdout or --output-file of clang-tidy

exit_code

Required.

output file containing the exit code of clang-tidy

lint_clang_tidy_aspect

A factory function to create a linter aspect.

Example usage (generated):

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

lint_clang_tidy_aspect(
    # the clang-tidy binary, typically a rule like
    binary = None,
)

binary

Required.

the clang-tidy binary, typically a rule like

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

configs

Optional. Default: []

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

Optional. Default: []

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. Default: ""

optional, set to a posix regex to supply to clang-tidy with the -header-filter option

lint_target_headers

Optional. Default: False

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.

angle_includes_are_system

Optional. Default: True

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.

verbose

Optional. Default: False

print debug messages including clang-tidy command lines being invoked.