diff --git a/clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp b/clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp --- a/clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp +++ b/clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp @@ -38,13 +38,37 @@ Configuration files: clang-tidy attempts to read configuration for each source file from a .clang-tidy file located in the closest parent directory of the source - file. If InheritParentConfig is true in a config file, the configuration file - in the parent directory (if any exists) will be taken and current config file - will be applied on top of the parent one. If any configuration options have - a corresponding command-line option, command-line option takes precedence. - The effective configuration can be inspected using -dump-config: - - $ clang-tidy -dump-config + file. The .clang-tidy file is specified in YAML format. If any configuration + options have a corresponding command-line option, command-line option takes + precedence. + + The following configuration options may be used in a .clang-tidy file: + + CheckOptions - List of key-value pairs defining check-specific + options. Example: + CheckOptions: + - key: check-a.SomeOption + value: value-a + - key: check-b.OtherOption + value: value-b + Checks - Same as '--checks'. + FormatStyle - Same as '--format-style'. + HeaderFilterRegex - Same as '--header-filter-regex'. + InheritParentConfig - If this option is true in a config file, the + configuration file in the parent directory (if any + exists) will be taken and the current config file will + be applied on top of the parent one. + SystemHeaders - Same as '--system-headers'. + UseColor - Same as '--use-color'. + User - Specifies the name or e-mail of the user running + clang-tidy. This option is used, for example, to place + the correct user name in TODO() comments in the + relevant check. + WarningsAsErrors - Same as '--warnings-as-errors'. + + The effective configuration can be inspected using --dump-config: + + $ clang-tidy --dump-config --- Checks: '-*,some-check' WarningsAsErrors: '' @@ -53,7 +77,8 @@ InheritParentConfig: true User: user CheckOptions: - some-check.SomeOption: 'some value' + - key: some-check.SomeOption + value: 'some value' ... )"); @@ -62,8 +87,8 @@ "clang-diagnostic-*," // * compiler diagnostics "clang-analyzer-*"; // * Static Analyzer checks -static cl::opt Checks("checks", cl::desc(R"( -Comma-separated list of globs with optional '-' +static cl::opt Checks("checks", cl::desc( +R"(Comma-separated list of globs with optional '-' prefix. Globs are processed in order of appearance in the list. Globs without '-' prefix add checks with matching names to the @@ -75,8 +100,8 @@ )"), cl::init(""), cl::cat(ClangTidyCategory)); -static cl::opt WarningsAsErrors("warnings-as-errors", cl::desc(R"( -Upgrades warnings to errors. Same format as +static cl::opt WarningsAsErrors("warnings-as-errors", cl::desc( +R"(Upgrades warnings to errors. Same format as '-checks'. This option's value is appended to the value of the 'WarningsAsErrors' option in .clang-tidy @@ -85,8 +110,8 @@ cl::init(""), cl::cat(ClangTidyCategory)); -static cl::opt HeaderFilter("header-filter", cl::desc(R"( -Regular expression matching the names of the +static cl::opt HeaderFilter("header-filter", cl::desc( +R"(Regular expression matching the names of the headers to output diagnostics from. Diagnostics from the main file of each translation unit are always displayed. @@ -101,8 +126,8 @@ SystemHeaders("system-headers", cl::desc("Display the errors from system headers."), cl::init(false), cl::cat(ClangTidyCategory)); -static cl::opt LineFilter("line-filter", cl::desc(R"( -List of files with line ranges to filter the +static cl::opt LineFilter("line-filter", cl::desc( +R"(List of files with line ranges to filter the warnings. Can be used together with -header-filter. The format of the list is a JSON array of objects: @@ -114,32 +139,32 @@ cl::init(""), cl::cat(ClangTidyCategory)); -static cl::opt Fix("fix", cl::desc(R"( -Apply suggested fixes. Without -fix-errors +static cl::opt Fix("fix", cl::desc( +R"(Apply suggested fixes. Without -fix-errors clang-tidy will bail out if any compilation errors were found. )"), cl::init(false), cl::cat(ClangTidyCategory)); -static cl::opt FixErrors("fix-errors", cl::desc(R"( -Apply suggested fixes even if compilation +static cl::opt FixErrors("fix-errors", cl::desc( +R"(Apply suggested fixes even if compilation errors were found. If compiler errors have attached fix-its, clang-tidy will apply them as well. )"), cl::init(false), cl::cat(ClangTidyCategory)); -static cl::opt FixNotes("fix-notes", cl::desc(R"( -If a warning has no fix, but a single fix can -be found through an associated diagnostic note, -apply the fix. -Specifying this flag will implicitly enable the +static cl::opt FixNotes("fix-notes", cl::desc( +R"(If a warning has no fix, but a single fix can +be found through an associated diagnostic note, +apply the fix. +Specifying this flag will implicitly enable the '--fix' flag. )"), cl::init(false), cl::cat(ClangTidyCategory)); -static cl::opt FormatStyle("format-style", cl::desc(R"( -Style for formatting code around applied fixes: +static cl::opt FormatStyle("format-style", cl::desc( +R"(Style for formatting code around applied fixes: - 'none' (default) turns off formatting - 'file' (literally 'file', not a placeholder) uses .clang-format file in the closest parent @@ -155,21 +180,21 @@ cl::init("none"), cl::cat(ClangTidyCategory)); -static cl::opt ListChecks("list-checks", cl::desc(R"( -List all enabled checks and exit. Use with +static cl::opt ListChecks("list-checks", cl::desc( +R"(List all enabled checks and exit. Use with -checks=* to list all available checks. )"), cl::init(false), cl::cat(ClangTidyCategory)); -static cl::opt ExplainConfig("explain-config", cl::desc(R"( -For each enabled check explains, where it is +static cl::opt ExplainConfig("explain-config", cl::desc( +R"(For each enabled check explains, where it is enabled, i.e. in clang-tidy binary, command line or a specific configuration file. )"), cl::init(false), cl::cat(ClangTidyCategory)); -static cl::opt Config("config", cl::desc(R"( -Specifies a configuration in YAML/JSON format: +static cl::opt Config("config", cl::desc( +R"(Specifies a configuration in YAML/JSON format: -config="{Checks: '*', CheckOptions: {x: y}}" When the value is empty, clang-tidy will @@ -178,8 +203,8 @@ )"), cl::init(""), cl::cat(ClangTidyCategory)); -static cl::opt ConfigFile("config-file", cl::desc(R"( -Specify the path of .clang-tidy or custom config file: +static cl::opt ConfigFile("config-file", cl::desc( +R"(Specify the path of .clang-tidy or custom config file: e.g. --config-file=/some/path/myTidyConfigFile This option internally works exactly the same way as --config option after reading specified config file. @@ -188,8 +213,8 @@ cl::init(""), cl::cat(ClangTidyCategory)); -static cl::opt DumpConfig("dump-config", cl::desc(R"( -Dumps configuration in the YAML format to +static cl::opt DumpConfig("dump-config", cl::desc( +R"(Dumps configuration in the YAML format to stdout. This option can be used along with a file name (and '--' if the file is outside of a project with configured compilation database). @@ -200,16 +225,16 @@ )"), cl::init(false), cl::cat(ClangTidyCategory)); -static cl::opt EnableCheckProfile("enable-check-profile", cl::desc(R"( -Enable per-check timing profiles, and print a +static cl::opt EnableCheckProfile("enable-check-profile", cl::desc( +R"(Enable per-check timing profiles, and print a report to stderr. )"), cl::init(false), cl::cat(ClangTidyCategory)); static cl::opt StoreCheckProfile("store-check-profile", - cl::desc(R"( -By default reports are printed in tabulated + cl::desc( +R"(By default reports are printed in tabulated format to stderr. When this option is passed, these per-TU profiles are instead stored as JSON. )"), @@ -224,16 +249,16 @@ cl::init(false), cl::Hidden, cl::cat(ClangTidyCategory)); -static cl::opt ExportFixes("export-fixes", cl::desc(R"( -YAML file to store suggested fixes in. The +static cl::opt ExportFixes("export-fixes", cl::desc( +R"(YAML file to store suggested fixes in. The stored fixes can be applied to the input source code with clang-apply-replacements. )"), cl::value_desc("filename"), cl::cat(ClangTidyCategory)); -static cl::opt Quiet("quiet", cl::desc(R"( -Run clang-tidy in quiet mode. This suppresses +static cl::opt Quiet("quiet", cl::desc( +R"(Run clang-tidy in quiet mode. This suppresses printing statistics about ignored warnings and warnings treated as errors if the respective options are specified. @@ -241,15 +266,15 @@ cl::init(false), cl::cat(ClangTidyCategory)); -static cl::opt VfsOverlay("vfsoverlay", cl::desc(R"( -Overlay the virtual filesystem described by file +static cl::opt VfsOverlay("vfsoverlay", cl::desc( +R"(Overlay the virtual filesystem described by file over the real file system. )"), cl::value_desc("filename"), cl::cat(ClangTidyCategory)); -static cl::opt UseColor("use-color", cl::desc(R"( -Use colors in diagnostics. If not set, colors +static cl::opt UseColor("use-color", cl::desc( +R"(Use colors in diagnostics. If not set, colors will be used if the terminal connected to standard output supports colors. This option overrides the 'UseColor' option in @@ -257,8 +282,8 @@ )"), cl::init(false), cl::cat(ClangTidyCategory)); -static cl::opt VerifyConfig("verify-config", cl::desc(R"( -Check the config files to ensure each check and +static cl::opt VerifyConfig("verify-config", cl::desc( +R"(Check the config files to ensure each check and option is recognized. )"), cl::init(false), cl::cat(ClangTidyCategory)); diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst --- a/clang-tools-extra/docs/clang-tidy/index.rst +++ b/clang-tools-extra/docs/clang-tidy/index.rst @@ -122,8 +122,7 @@ clang-tidy options: - --checks= - - Comma-separated list of globs with optional '-' + --checks= - Comma-separated list of globs with optional '-' prefix. Globs are processed in order of appearance in the list. Globs without '-' prefix add checks with matching names to the @@ -132,21 +131,18 @@ checks. This option's value is appended to the value of the 'Checks' option in .clang-tidy file, if any. - --config= - - Specifies a configuration in YAML/JSON format: + --config= - Specifies a configuration in YAML/JSON format: -config="{Checks: '*', - CheckOptions: {x, y}}" + CheckOptions: {x: y}}" When the value is empty, clang-tidy will attempt to find a file named .clang-tidy for each source file in its parent directories. - --config-file= - - Specify the path of .clang-tidy or custom config file: + --config-file= - Specify the path of .clang-tidy or custom config file: e.g. --config-file=/some/path/myTidyConfigFile - This option internally works exactly the same way as + This option internally works exactly the same way as --config option after reading specified config file. - Use either --config-file or --config, not both. - --dump-config - - Dumps configuration in the YAML format to + Use either --config-file or --config, not both. + --dump-config - Dumps configuration in the YAML format to stdout. This option can be used along with a file name (and '--' if the file is outside of a project with configured compilation database). @@ -154,38 +150,29 @@ printed. Use along with -checks=* to include configuration of all checks. - --enable-check-profile - - Enable per-check timing profiles, and print a + --enable-check-profile - Enable per-check timing profiles, and print a report to stderr. - --explain-config - - For each enabled check explains, where it is + --explain-config - For each enabled check explains, where it is enabled, i.e. in clang-tidy binary, command line or a specific configuration file. - --export-fixes= - - YAML file to store suggested fixes in. The + --export-fixes= - YAML file to store suggested fixes in. The stored fixes can be applied to the input source code with clang-apply-replacements. - --extra-arg= - Additional argument to append to the compiler command line. - Can be used several times. - --extra-arg-before= - Additional argument to prepend to the compiler command line. - Can be used several times. - --fix - - Apply suggested fixes. Without -fix-errors + --extra-arg= - Additional argument to append to the compiler command line + --extra-arg-before= - Additional argument to prepend to the compiler command line + --fix - Apply suggested fixes. Without -fix-errors clang-tidy will bail out if any compilation errors were found. - --fix-errors - - Apply suggested fixes even if compilation + --fix-errors - Apply suggested fixes even if compilation errors were found. If compiler errors have attached fix-its, clang-tidy will apply them as well. - --fix-notes - - If a warning has no fix, but a single fix can + --fix-notes - If a warning has no fix, but a single fix can be found through an associated diagnostic note, apply the fix. Specifying this flag will implicitly enable the '--fix' flag. - --format-style= - - Style for formatting code around applied fixes: + --format-style= - Style for formatting code around applied fixes: - 'none' (default) turns off formatting - 'file' (literally 'file', not a placeholder) uses .clang-format file in the closest parent @@ -197,16 +184,14 @@ information about formatting styles and options. This option overrides the 'FormatStyle` option in .clang-tidy file, if any. - --header-filter= - - Regular expression matching the names of the + --header-filter= - Regular expression matching the names of the headers to output diagnostics from. Diagnostics from the main file of each translation unit are always displayed. Can be used together with -line-filter. This option overrides the 'HeaderFilterRegex' option in .clang-tidy file, if any. - --line-filter= - - List of files with line ranges to filter the + --line-filter= - List of files with line ranges to filter the warnings. Can be used together with -header-filter. The format of the list is a JSON array of objects: @@ -214,43 +199,28 @@ {"name":"file1.cpp","lines":[[1,3],[5,7]]}, {"name":"file2.h"} ] - --list-checks - - List all enabled checks and exit. Use with + --list-checks - List all enabled checks and exit. Use with -checks=* to list all available checks. - -load= - - Load the dynamic object ``plugin``. This - object should register new static analyzer - or clang-tidy passes. Once loaded, the - object will add new command line options - to run various analyses. To see the new - complete list of passes, use the - :option:`--list-checks` and - :option:`-load` options together. + --load= - Load the specified plugin -p - Build path - --quiet - - Run clang-tidy in quiet mode. This suppresses + --quiet - Run clang-tidy in quiet mode. This suppresses printing statistics about ignored warnings and warnings treated as errors if the respective options are specified. - --store-check-profile= - - By default reports are printed in tabulated + --store-check-profile= - By default reports are printed in tabulated format to stderr. When this option is passed, these per-TU profiles are instead stored as JSON. --system-headers - Display the errors from system headers. - --use-color - - Use colors in diagnostics. If not set, colors - will be used if the terminal connected to - standard output supports colors. - This option overrides the 'UseColor' option in - .clang-tidy file, if any. - --verify-config - - Check the config files to ensure each check and + --use-color - Use colors in diagnostics. If not set, colors + will be used if the terminal connected to + standard output supports colors. + This option overrides the 'UseColor' option in + .clang-tidy file, if any. + --verify-config - Check the config files to ensure each check and option is recognized. - --vfsoverlay= - - Overlay the virtual filesystem described by file + --vfsoverlay= - Overlay the virtual filesystem described by file over the real file system. - --warnings-as-errors= - - Upgrades warnings to errors. Same format as + --warnings-as-errors= - Upgrades warnings to errors. Same format as '-checks'. This option's value is appended to the value of the 'WarningsAsErrors' option in .clang-tidy @@ -258,34 +228,58 @@ -p is used to read a compile command database. - For example, it can be a CMake build directory in which a file named - compile_commands.json exists (use -DCMAKE_EXPORT_COMPILE_COMMANDS=ON - CMake option to get this output). When no build path is specified, - a search for compile_commands.json will be attempted through all - parent paths of the first input file . See: - https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an - example of setting up Clang Tooling on a source tree. + For example, it can be a CMake build directory in which a file named + compile_commands.json exists (use -DCMAKE_EXPORT_COMPILE_COMMANDS=ON + CMake option to get this output). When no build path is specified, + a search for compile_commands.json will be attempted through all + parent paths of the first input file . See: + https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an + example of setting up Clang Tooling on a source tree. ... specify the paths of source files. These paths are - looked up in the compile command database. If the path of a file is - absolute, it needs to point into CMake's source tree. If the path is - relative, the current working directory needs to be in the CMake - source tree and the file must be in a subdirectory of the current - working directory. "./" prefixes in the relative files will be - automatically removed, but the rest of a relative path must be a - suffix of a path in the compile command database. + looked up in the compile command database. If the path of a file is + absolute, it needs to point into CMake's source tree. If the path is + relative, the current working directory needs to be in the CMake + source tree and the file must be in a subdirectory of the current + working directory. "./" prefixes in the relative files will be + automatically removed, but the rest of a relative path must be a + suffix of a path in the compile command database. Configuration files: clang-tidy attempts to read configuration for each source file from a .clang-tidy file located in the closest parent directory of the source - file. If InheritParentConfig is true in a config file, the configuration file - in the parent directory (if any exists) will be taken and current config file - will be applied on top of the parent one. If any configuration options have - a corresponding command-line option, command-line option takes precedence. - The effective configuration can be inspected using -dump-config: - - $ clang-tidy -dump-config + file. The .clang-tidy file is specified in YAML format. If any configuration + options have a corresponding command-line option, command-line option takes + precedence. + + The following configuration options may be used in a .clang-tidy file: + + CheckOptions - List of key-value pairs defining check-specific + options. Example: + CheckOptions: + - key: check-a.SomeOption + value: value-a + - key: check-b.OtherOption + value: value-b + Checks - Same as '--checks'. + FormatStyle - Same as '--format-style'. + HeaderFilterRegex - Same as '--header-filter-regex'. + InheritParentConfig - If this option is true in a config file, the + configuration file in the parent directory (if any + exists) will be taken and the current config file will + be applied on top of the parent one. + SystemHeaders - Same as '--system-headers'. + UseColor - Same as '--use-color'. + User - Specifies the name or e-mail of the user running + clang-tidy. This option is used, for example, to place + the correct user name in TODO() comments in the + relevant check. + WarningsAsErrors - Same as '--warnings-as-errors'. + + The effective configuration can be inspected using --dump-config: + + $ clang-tidy --dump-config --- Checks: '-*,some-check' WarningsAsErrors: '' @@ -294,7 +288,8 @@ InheritParentConfig: true User: user CheckOptions: - some-check.SomeOption: 'some value' + - key: some-check.SomeOption + value: 'some value' ... .. _clang-tidy-nolint: