From 5c423318c99246bd28c973c4c3255700fdd50b0c Mon Sep 17 00:00:00 2001 From: Alexander Kornienko Date: Wed, 3 Dec 2014 14:03:03 +0000 Subject: [PATCH] [clang-tidy] Update help messages and docs. Fixed incorrect examples of configuration, clarified the usage of -dump-config. llvm-svn: 223235 --- .../clang-tidy/tool/ClangTidyMain.cpp | 27 +++- clang-tools-extra/docs/clang-tidy.rst | 144 +++++++++++------- 2 files changed, 108 insertions(+), 63 deletions(-) diff --git a/clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp b/clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp index 44843b48b7e7..9bbec3b6269e 100644 --- a/clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp +++ b/clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp @@ -33,7 +33,19 @@ static cl::extrahelp ClangTidyHelp( " .clang-tidy file located in the closest parent directory of the source\n" " file. If any configuration options have a corresponding command-line\n" " option, command-line option takes precedence. The effective\n" - " configuration can be inspected using -dump-config.\n\n"); + " configuration can be inspected using -dump-config:\n" + "\n" + " $ clang-tidy -dump-config - --\n" + " ---\n" + " Checks: '-*,some-check'\n" + " HeaderFilterRegex: ''\n" + " AnalyzeTemporaryDtors: false\n" + " User: user\n" + " CheckOptions: \n" + " - key: some-check.SomeOption\n" + " value: 'some value'\n" + " ...\n" + "\n\n"); const char DefaultChecks[] = // Enable these checks: "clang-diagnostic-*," // * compiler diagnostics @@ -100,16 +112,19 @@ ListChecks("list-checks", static cl::opt Config( "config", cl::desc("Specifies a configuration in YAML/JSON format:\n" - " -config=\"{Checks: '*', CheckOptions: {key: x, value: y}}\"\n" + " -config=\"{Checks: '*', CheckOptions: [{key: x, value: y}]}\"\n" "When the value is empty, clang-tidy will attempt to find\n" "a file named .clang-tidy for each source file in its parent\n" "directories."), cl::init(""), cl::cat(ClangTidyCategory)); -static cl::opt -DumpConfig("dump-config", - cl::desc("Dumps configuration in the YAML format to stdout."), - cl::init(false), cl::cat(ClangTidyCategory)); +static cl::opt DumpConfig( + "dump-config", + cl::desc("Dumps configuration in the YAML format to stdout. This option\n" + "should be used along with a file name (and '--' if the file is\n" + "outside of a project with configured compilation database). The\n" + "configuration used for this file will be printed."), + cl::init(false), cl::cat(ClangTidyCategory)); static cl::opt EnableCheckProfile( "enable-check-profile", diff --git a/clang-tools-extra/docs/clang-tidy.rst b/clang-tools-extra/docs/clang-tidy.rst index 42c6c34a399c..49144dea3483 100644 --- a/clang-tools-extra/docs/clang-tidy.rst +++ b/clang-tools-extra/docs/clang-tidy.rst @@ -86,71 +86,95 @@ An overview of all the command-line options: clang-tidy options: - -analyze-temporary-dtors - Enable temporary destructor-aware analysis in - clang-analyzer- checks. - -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 read - from a .clang-tidy file, if any. - -config= - Specifies a configuration in YAML/JSON format: - -config="{Checks: '*', CheckOptions: {key: x, value: 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. - -dump-config - Dumps configuration in the YAML format to stdout. - -export-fixes= - YAML file to store suggested fixes in. The - stored fixes can be applied to the input source - code with clang-apply-replacements. - -fix - Fix detected errors if possible. - -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 value read from a - .clang-tidy file. - -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. - -p= - Build path - -system-headers - Display the errors from system headers + -analyze-temporary-dtors - Enable temporary destructor-aware analysis in + clang-analyzer- checks. + This option overrides the value read from a + .clang-tidy 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 read + from a .clang-tidy file, if any. + -config= - Specifies a configuration in YAML/JSON format: + -config="{Checks: '*', CheckOptions: [{key: x, value: 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. + -dump-config - Dumps configuration in the YAML format to stdout. This option + should 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. + -enable-check-profile - Enable per-check timing profiles, and print a report to stderr. + -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. + -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 value read from a + .clang-tidy file. + -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. + -p= - Build path + -system-headers - Display the errors from system headers. -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: - http://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: + http://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 any configuration options have a corresponding command-line option, command-line option takes precedence. The effective - configuration can be inspected using -dump-config. + configuration can be inspected using -dump-config: + + $ clang-tidy -dump-config - -- + --- + Checks: '-*,some-check' + HeaderFilterRegex: '' + AnalyzeTemporaryDtors: false + User: user + CheckOptions: + - key: some-check.SomeOption + value: 'some value' + ... .. _LibTooling: http://clang.llvm.org/docs/LibTooling.html .. _How To Setup Tooling For LLVM: http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html @@ -384,7 +408,7 @@ the check implements and what the current values are (e.g. for the SomeOption(Options.get("SomeOption1", -1U)), SomeOption(Options.get("SomeOption2", "some default")) {} - void storeOptions(ClangTidyOptions::OptionMap &Opts) { + void storeOptions(ClangTidyOptions::OptionMap &Opts) override { Options.store(Opts, "SomeOption1", SomeOption1); Options.store(Opts, "SomeOption2", SomeOption2); } @@ -395,12 +419,18 @@ be set in a ``.clang-tidy`` file in the following way: .. code-block:: yaml - CheckOptions: { + CheckOptions: - key: my-check.SomeOption1 value: 123 - key: my-check.SomeOption2 value: 'some other value' - } + +If you need to specify check options on a command line, you can use the inline +YAML format: + +.. code-block:: bash + + $ clang-tidy -config="{CheckOptions: [{key: a, value: b}, {key: x, value: y}]}" ... Testing Checks