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 @@ -31,6 +31,8 @@ using namespace clang::tooling; using namespace llvm; +static StringRef TrimFirstChar(StringRef x) { return x.substr(1); } + static cl::OptionCategory ClangTidyCategory("clang-tidy options"); static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage); @@ -38,13 +40,44 @@ 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: + some-check.SomeOption: 'some value' + Checks - Same as '--checks'. + ExtraArgs - Same as '--extra-args'. + ExtraArgsBefore - Same as '--extra-args-before'. + FormatStyle - Same as '--format-style'. + HeaderFileExtensions - File extensions to consider to determine if a + given diagnostic is located in a header file. + Default: ['','h','hh','hpp','hxx'] + HeaderFilterRegex - Same as '--header-filter-regex'. + ImplementationFileExtensions - File extensions to consider to determine if a + given diagnostic is located in an + implementation file. + Default: ['c','cc','cpp','cxx'] + 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: '' @@ -64,7 +97,7 @@ "clang-diagnostic-*," // * compiler diagnostics "clang-analyzer-*"; // * Static Analyzer checks -static cl::opt Checks("checks", cl::desc(R"( +static cl::opt Checks("checks", cl::desc(TrimFirstChar(R"( Comma-separated list of globs with optional '-' prefix. Globs are processed in order of appearance in the list. Globs without '-' @@ -74,20 +107,22 @@ checks. This option's value is appended to the value of the 'Checks' option in .clang-tidy file, if any. -)"), +)")), cl::init(""), cl::cat(ClangTidyCategory)); -static cl::opt WarningsAsErrors("warnings-as-errors", cl::desc(R"( +static cl::opt WarningsAsErrors("warnings-as-errors", + cl::desc(TrimFirstChar(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 file, if any. -)"), +)")), cl::init(""), cl::cat(ClangTidyCategory)); -static cl::opt HeaderFilter("header-filter", cl::desc(R"( +static cl::opt HeaderFilter("header-filter", + cl::desc(TrimFirstChar(R"( Regular expression matching the names of the headers to output diagnostics from. Diagnostics from the main file of each translation unit are @@ -95,7 +130,7 @@ Can be used together with -line-filter. This option overrides the 'HeaderFilterRegex' option in .clang-tidy file, if any. -)"), +)")), cl::init(""), cl::cat(ClangTidyCategory)); @@ -103,7 +138,7 @@ 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"( +static cl::opt LineFilter("line-filter", cl::desc(TrimFirstChar(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 @@ -112,35 +147,36 @@ {"name":"file1.cpp","lines":[[1,3],[5,7]]}, {"name":"file2.h"} ] -)"), +)")), cl::init(""), cl::cat(ClangTidyCategory)); -static cl::opt Fix("fix", cl::desc(R"( +static cl::opt Fix("fix", cl::desc(TrimFirstChar(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"( +static cl::opt FixErrors("fix-errors", cl::desc(TrimFirstChar(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"( +static cl::opt FixNotes("fix-notes", cl::desc(TrimFirstChar(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"( +static cl::opt FormatStyle("format-style", + cl::desc(TrimFirstChar(R"( Style for formatting code around applied fixes: - 'none' (default) turns off formatting - 'file' (literally 'file', not a placeholder) @@ -153,44 +189,44 @@ information about formatting styles and options. This option overrides the 'FormatStyle` option in .clang-tidy file, if any. -)"), - cl::init("none"), - cl::cat(ClangTidyCategory)); +)")), + cl::init("none"), + cl::cat(ClangTidyCategory)); -static cl::opt ListChecks("list-checks", cl::desc(R"( +static cl::opt ListChecks("list-checks", cl::desc(TrimFirstChar(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"( +static cl::opt ExplainConfig("explain-config", cl::desc(TrimFirstChar(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"( +static cl::opt Config("config", cl::desc(TrimFirstChar(R"( Specifies a configuration in YAML/JSON format: -config="{Checks: '*', 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. -)"), +)")), cl::init(""), cl::cat(ClangTidyCategory)); -static cl::opt ConfigFile("config-file", cl::desc(R"( +static cl::opt ConfigFile("config-file", cl::desc(TrimFirstChar(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. Use either --config-file or --config, not both. -)"), +)")), cl::init(""), cl::cat(ClangTidyCategory)); -static cl::opt DumpConfig("dump-config", cl::desc(R"( +static cl::opt DumpConfig("dump-config", cl::desc(TrimFirstChar(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 @@ -199,22 +235,23 @@ printed. Use along with -checks=* to include configuration of all checks. -)"), +)")), cl::init(false), cl::cat(ClangTidyCategory)); -static cl::opt EnableCheckProfile("enable-check-profile", cl::desc(R"( +static cl::opt EnableCheckProfile("enable-check-profile", + cl::desc(TrimFirstChar(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"( + cl::desc(TrimFirstChar(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. -)"), +)")), cl::value_desc("prefix"), cl::cat(ClangTidyCategory)); @@ -226,43 +263,43 @@ cl::init(false), cl::Hidden, cl::cat(ClangTidyCategory)); -static cl::opt ExportFixes("export-fixes", cl::desc(R"( +static cl::opt ExportFixes("export-fixes", + cl::desc(TrimFirstChar(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"( +static cl::opt Quiet("quiet", cl::desc(TrimFirstChar(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. -)"), - cl::init(false), - cl::cat(ClangTidyCategory)); +)")), + cl::init(false), cl::cat(ClangTidyCategory)); -static cl::opt VfsOverlay("vfsoverlay", cl::desc(R"( +static cl::opt VfsOverlay("vfsoverlay", cl::desc(TrimFirstChar(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"( +static cl::opt UseColor("use-color", cl::desc(TrimFirstChar(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 .clang-tidy file, if any. -)"), +)")), cl::init(false), cl::cat(ClangTidyCategory)); -static cl::opt VerifyConfig("verify-config", cl::desc(R"( +static cl::opt VerifyConfig("verify-config", cl::desc(TrimFirstChar(R"( Check the config files to ensure each check and option is recognized. -)"), +)")), cl::init(false), cl::cat(ClangTidyCategory)); namespace clang::tidy { 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 @@ -110,6 +110,7 @@ .. code-block:: console $ clang-tidy --help + USAGE: clang-tidy [options] [... ] OPTIONS: @@ -122,170 +123,171 @@ clang-tidy options: - --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 - set, globs with the '-' prefix remove checks - with matching names from the set of enabled - 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="{Checks: '*', - 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: + --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 + set, globs with the '-' prefix remove checks + with matching names from the set of enabled + 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="{Checks: '*', + 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: e.g. --config-file=/some/path/myTidyConfigFile 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 - stdout. This option can be used along with a - file name (and '--' if the file is outside of a - project with configured compilation database). - The configuration used for this file will be - printed. - Use along with -checks=* to include - configuration of all checks. - --enable-check-profile - - Enable per-check timing profiles, and print a - report to stderr. - --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 - 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 - clang-tidy will bail out if any compilation - errors were found. - --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 - 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: - - 'none' (default) turns off formatting - - 'file' (literally 'file', not a placeholder) - uses .clang-format file in the closest parent - directory - - '{ }' specifies options inline, e.g. - -format-style='{BasedOnStyle: llvm, IndentWidth: 8}' - - 'llvm', 'google', 'webkit', 'mozilla' - See clang-format documentation for the up-to-date - 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 - 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 - warnings. Can be used together with - -header-filter. The format of the list is a - JSON array of objects: - [ - {"name":"file1.cpp","lines":[[1,3],[5,7]]}, - {"name":"file2.h"} - ] - --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. + --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). + The configuration used for this file will be + printed. + Use along with -checks=* to include + configuration of all checks. + --enable-check-profile - Enable per-check timing profiles, and print a + report to stderr. + --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 + 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 + --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 + 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 + 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: + - 'none' (default) turns off formatting + - 'file' (literally 'file', not a placeholder) + uses .clang-format file in the closest parent + directory + - '{ }' specifies options inline, e.g. + -format-style='{BasedOnStyle: llvm, IndentWidth: 8}' + - 'llvm', 'google', 'webkit', 'mozilla' + See clang-format documentation for the up-to-date + 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 + 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 + warnings. Can be used together with + -header-filter. The format of the list is a + JSON array of objects: + [ + {"name":"file1.cpp","lines":[[1,3],[5,7]]}, + {"name":"file2.h"} + ] + --list-checks - List all enabled checks and exit. Use with + -checks=* to list all available checks. + --load= - Load the specified plugin -p - Build path - --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 - format to stderr. When this option is passed, - these per-TU profiles are instead stored as JSON. + --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 + 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 + --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 - over the real file system. - --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 - 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 + over the real file system. + --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 + file, if any. -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: + some-check.SomeOption: 'some value' + Checks - Same as '--checks'. + ExtraArgs - Same as '--extra-args'. + ExtraArgsBefore - Same as '--extra-args-before'. + FormatStyle - Same as '--format-style'. + HeaderFileExtensions - File extensions to consider to determine if a + given diagnostic is located in a header file. + Default: ['','h','hh','hpp','hxx'] + HeaderFilterRegex - Same as '--header-filter-regex'. + ImplementationFileExtensions - File extensions to consider to determine if a + given diagnostic is located in an + implementation file. + Default: ['c','cc','cpp','cxx'] + 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: ''