llvm-project
667 строк · 23.7 Кб
1#!/usr/bin/env python3
2#
3# ===- add_new_check.py - clang-tidy check generator ---------*- python -*--===#
4#
5# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
6# See https://llvm.org/LICENSE.txt for license information.
7# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
8#
9# ===-----------------------------------------------------------------------===#
10
11from __future__ import print_function
12from __future__ import unicode_literals
13
14import argparse
15import io
16import os
17import re
18import sys
19
20# Adapts the module's CMakelist file. Returns 'True' if it could add a new
21# entry and 'False' if the entry already existed.
22def adapt_cmake(module_path, check_name_camel):
23filename = os.path.join(module_path, "CMakeLists.txt")
24
25# The documentation files are encoded using UTF-8, however on Windows the
26# default encoding might be different (e.g. CP-1252). To make sure UTF-8 is
27# always used, use `io.open(filename, mode, encoding='utf8')` for reading and
28# writing files here and elsewhere.
29with io.open(filename, "r", encoding="utf8") as f:
30lines = f.readlines()
31
32cpp_file = check_name_camel + ".cpp"
33
34# Figure out whether this check already exists.
35for line in lines:
36if line.strip() == cpp_file:
37return False
38
39print("Updating %s..." % filename)
40with io.open(filename, "w", encoding="utf8", newline="\n") as f:
41cpp_found = False
42file_added = False
43for line in lines:
44cpp_line = line.strip().endswith(".cpp")
45if (not file_added) and (cpp_line or cpp_found):
46cpp_found = True
47if (line.strip() > cpp_file) or (not cpp_line):
48f.write(" " + cpp_file + "\n")
49file_added = True
50f.write(line)
51
52return True
53
54
55# Adds a header for the new check.
56def write_header(module_path, module, namespace, check_name, check_name_camel):
57filename = os.path.join(module_path, check_name_camel) + ".h"
58print("Creating %s..." % filename)
59with io.open(filename, "w", encoding="utf8", newline="\n") as f:
60header_guard = (
61"LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_"
62+ module.upper()
63+ "_"
64+ check_name_camel.upper()
65+ "_H"
66)
67f.write("//===--- ")
68f.write(os.path.basename(filename))
69f.write(" - clang-tidy ")
70f.write("-" * max(0, 42 - len(os.path.basename(filename))))
71f.write("*- C++ -*-===//")
72f.write(
73"""
74//
75// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
76// See https://llvm.org/LICENSE.txt for license information.
77// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
78//
79//===----------------------------------------------------------------------===//
80
81#ifndef %(header_guard)s
82#define %(header_guard)s
83
84#include "../ClangTidyCheck.h"
85
86namespace clang::tidy::%(namespace)s {
87
88/// FIXME: Write a short description.
89///
90/// For the user-facing documentation see:
91/// http://clang.llvm.org/extra/clang-tidy/checks/%(module)s/%(check_name)s.html
92class %(check_name_camel)s : public ClangTidyCheck {
93public:
94%(check_name_camel)s(StringRef Name, ClangTidyContext *Context)
95: ClangTidyCheck(Name, Context) {}
96void registerMatchers(ast_matchers::MatchFinder *Finder) override;
97void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
98};
99
100} // namespace clang::tidy::%(namespace)s
101
102#endif // %(header_guard)s
103"""
104% {
105"header_guard": header_guard,
106"check_name_camel": check_name_camel,
107"check_name": check_name,
108"module": module,
109"namespace": namespace,
110}
111)
112
113
114# Adds the implementation of the new check.
115def write_implementation(module_path, module, namespace, check_name_camel):
116filename = os.path.join(module_path, check_name_camel) + ".cpp"
117print("Creating %s..." % filename)
118with io.open(filename, "w", encoding="utf8", newline="\n") as f:
119f.write("//===--- ")
120f.write(os.path.basename(filename))
121f.write(" - clang-tidy ")
122f.write("-" * max(0, 51 - len(os.path.basename(filename))))
123f.write("-===//")
124f.write(
125"""
126//
127// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
128// See https://llvm.org/LICENSE.txt for license information.
129// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
130//
131//===----------------------------------------------------------------------===//
132
133#include "%(check_name)s.h"
134#include "clang/ASTMatchers/ASTMatchFinder.h"
135
136using namespace clang::ast_matchers;
137
138namespace clang::tidy::%(namespace)s {
139
140void %(check_name)s::registerMatchers(MatchFinder *Finder) {
141// FIXME: Add matchers.
142Finder->addMatcher(functionDecl().bind("x"), this);
143}
144
145void %(check_name)s::check(const MatchFinder::MatchResult &Result) {
146// FIXME: Add callback implementation.
147const auto *MatchedDecl = Result.Nodes.getNodeAs<FunctionDecl>("x");
148if (!MatchedDecl->getIdentifier() || MatchedDecl->getName().starts_with("awesome_"))
149return;
150diag(MatchedDecl->getLocation(), "function %%0 is insufficiently awesome")
151<< MatchedDecl
152<< FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_");
153diag(MatchedDecl->getLocation(), "insert 'awesome'", DiagnosticIDs::Note);
154}
155
156} // namespace clang::tidy::%(namespace)s
157"""
158% {"check_name": check_name_camel, "module": module, "namespace": namespace}
159)
160
161
162# Returns the source filename that implements the module.
163def get_module_filename(module_path, module):
164modulecpp = list(
165filter(
166lambda p: p.lower() == module.lower() + "tidymodule.cpp",
167os.listdir(module_path),
168)
169)[0]
170return os.path.join(module_path, modulecpp)
171
172
173# Modifies the module to include the new check.
174def adapt_module(module_path, module, check_name, check_name_camel):
175filename = get_module_filename(module_path, module)
176with io.open(filename, "r", encoding="utf8") as f:
177lines = f.readlines()
178
179print("Updating %s..." % filename)
180with io.open(filename, "w", encoding="utf8", newline="\n") as f:
181header_added = False
182header_found = False
183check_added = False
184check_fq_name = module + "-" + check_name
185check_decl = (
186" CheckFactories.registerCheck<"
187+ check_name_camel
188+ '>(\n "'
189+ check_fq_name
190+ '");\n'
191)
192
193lines = iter(lines)
194try:
195while True:
196line = next(lines)
197if not header_added:
198match = re.search('#include "(.*)"', line)
199if match:
200header_found = True
201if match.group(1) > check_name_camel:
202header_added = True
203f.write('#include "' + check_name_camel + '.h"\n')
204elif header_found:
205header_added = True
206f.write('#include "' + check_name_camel + '.h"\n')
207
208if not check_added:
209if line.strip() == "}":
210check_added = True
211f.write(check_decl)
212else:
213match = re.search(
214r'registerCheck<(.*)> *\( *(?:"([^"]*)")?', line
215)
216prev_line = None
217if match:
218current_check_name = match.group(2)
219if current_check_name is None:
220# If we didn't find the check name on this line, look on the
221# next one.
222prev_line = line
223line = next(lines)
224match = re.search(' *"([^"]*)"', line)
225if match:
226current_check_name = match.group(1)
227if current_check_name > check_fq_name:
228check_added = True
229f.write(check_decl)
230if prev_line:
231f.write(prev_line)
232f.write(line)
233except StopIteration:
234pass
235
236
237# Adds a release notes entry.
238def add_release_notes(module_path, module, check_name):
239check_name_dashes = module + "-" + check_name
240filename = os.path.normpath(
241os.path.join(module_path, "../../docs/ReleaseNotes.rst")
242)
243with io.open(filename, "r", encoding="utf8") as f:
244lines = f.readlines()
245
246lineMatcher = re.compile("New checks")
247nextSectionMatcher = re.compile("New check aliases")
248checkMatcher = re.compile("- New :doc:`(.*)")
249
250print("Updating %s..." % filename)
251with io.open(filename, "w", encoding="utf8", newline="\n") as f:
252note_added = False
253header_found = False
254add_note_here = False
255
256for line in lines:
257if not note_added:
258match = lineMatcher.match(line)
259match_next = nextSectionMatcher.match(line)
260match_check = checkMatcher.match(line)
261if match_check:
262last_check = match_check.group(1)
263if last_check > check_name_dashes:
264add_note_here = True
265
266if match_next:
267add_note_here = True
268
269if match:
270header_found = True
271f.write(line)
272continue
273
274if line.startswith("^^^^"):
275f.write(line)
276continue
277
278if header_found and add_note_here:
279if not line.startswith("^^^^"):
280f.write(
281"""- New :doc:`%s
282<clang-tidy/checks/%s/%s>` check.
283
284FIXME: add release notes.
285
286"""
287% (check_name_dashes, module, check_name)
288)
289note_added = True
290
291f.write(line)
292
293
294# Adds a test for the check.
295def write_test(module_path, module, check_name, test_extension):
296check_name_dashes = module + "-" + check_name
297filename = os.path.normpath(
298os.path.join(
299module_path,
300"..",
301"..",
302"test",
303"clang-tidy",
304"checkers",
305module,
306check_name + "." + test_extension,
307)
308)
309print("Creating %s..." % filename)
310with io.open(filename, "w", encoding="utf8", newline="\n") as f:
311f.write(
312"""// RUN: %%check_clang_tidy %%s %(check_name_dashes)s %%t
313
314// FIXME: Add something that triggers the check here.
315void f();
316// CHECK-MESSAGES: :[[@LINE-1]]:6: warning: function 'f' is insufficiently awesome [%(check_name_dashes)s]
317
318// FIXME: Verify the applied fix.
319// * Make the CHECK patterns specific enough and try to make verified lines
320// unique to avoid incorrect matches.
321// * Use {{}} for regular expressions.
322// CHECK-FIXES: {{^}}void awesome_f();{{$}}
323
324// FIXME: Add something that doesn't trigger the check here.
325void awesome_f2();
326"""
327% {"check_name_dashes": check_name_dashes}
328)
329
330
331def get_actual_filename(dirname, filename):
332if not os.path.isdir(dirname):
333return ""
334name = os.path.join(dirname, filename)
335if os.path.isfile(name):
336return name
337caselessname = filename.lower()
338for file in os.listdir(dirname):
339if file.lower() == caselessname:
340return os.path.join(dirname, file)
341return ""
342
343
344# Recreates the list of checks in the docs/clang-tidy/checks directory.
345def update_checks_list(clang_tidy_path):
346docs_dir = os.path.join(clang_tidy_path, "../docs/clang-tidy/checks")
347filename = os.path.normpath(os.path.join(docs_dir, "list.rst"))
348# Read the content of the current list.rst file
349with io.open(filename, "r", encoding="utf8") as f:
350lines = f.readlines()
351# Get all existing docs
352doc_files = []
353for subdir in filter(
354lambda s: os.path.isdir(os.path.join(docs_dir, s)), os.listdir(docs_dir)
355):
356for file in filter(
357lambda s: s.endswith(".rst"), os.listdir(os.path.join(docs_dir, subdir))
358):
359doc_files.append([subdir, file])
360doc_files.sort()
361
362# We couldn't find the source file from the check name, so try to find the
363# class name that corresponds to the check in the module file.
364def filename_from_module(module_name, check_name):
365module_path = os.path.join(clang_tidy_path, module_name)
366if not os.path.isdir(module_path):
367return ""
368module_file = get_module_filename(module_path, module_name)
369if not os.path.isfile(module_file):
370return ""
371with io.open(module_file, "r") as f:
372code = f.read()
373full_check_name = module_name + "-" + check_name
374name_pos = code.find('"' + full_check_name + '"')
375if name_pos == -1:
376return ""
377stmt_end_pos = code.find(";", name_pos)
378if stmt_end_pos == -1:
379return ""
380stmt_start_pos = code.rfind(";", 0, name_pos)
381if stmt_start_pos == -1:
382stmt_start_pos = code.rfind("{", 0, name_pos)
383if stmt_start_pos == -1:
384return ""
385stmt = code[stmt_start_pos + 1 : stmt_end_pos]
386matches = re.search(r'registerCheck<([^>:]*)>\(\s*"([^"]*)"\s*\)', stmt)
387if matches and matches[2] == full_check_name:
388class_name = matches[1]
389if "::" in class_name:
390parts = class_name.split("::")
391class_name = parts[-1]
392class_path = os.path.join(
393clang_tidy_path, module_name, "..", *parts[0:-1]
394)
395else:
396class_path = os.path.join(clang_tidy_path, module_name)
397return get_actual_filename(class_path, class_name + ".cpp")
398
399return ""
400
401# Examine code looking for a c'tor definition to get the base class name.
402def get_base_class(code, check_file):
403check_class_name = os.path.splitext(os.path.basename(check_file))[0]
404ctor_pattern = check_class_name + r"\([^:]*\)\s*:\s*([A-Z][A-Za-z0-9]*Check)\("
405matches = re.search(r"\s+" + check_class_name + "::" + ctor_pattern, code)
406
407# The constructor might be inline in the header.
408if not matches:
409header_file = os.path.splitext(check_file)[0] + ".h"
410if not os.path.isfile(header_file):
411return ""
412with io.open(header_file, encoding="utf8") as f:
413code = f.read()
414matches = re.search(" " + ctor_pattern, code)
415
416if matches and matches[1] != "ClangTidyCheck":
417return matches[1]
418return ""
419
420# Some simple heuristics to figure out if a check has an autofix or not.
421def has_fixits(code):
422for needle in [
423"FixItHint",
424"ReplacementText",
425"fixit",
426"TransformerClangTidyCheck",
427]:
428if needle in code:
429return True
430return False
431
432# Try to figure out of the check supports fixits.
433def has_auto_fix(check_name):
434dirname, _, check_name = check_name.partition("-")
435
436check_file = get_actual_filename(
437os.path.join(clang_tidy_path, dirname),
438get_camel_check_name(check_name) + ".cpp",
439)
440if not os.path.isfile(check_file):
441# Some older checks don't end with 'Check.cpp'
442check_file = get_actual_filename(
443os.path.join(clang_tidy_path, dirname),
444get_camel_name(check_name) + ".cpp",
445)
446if not os.path.isfile(check_file):
447# Some checks aren't in a file based on the check name.
448check_file = filename_from_module(dirname, check_name)
449if not check_file or not os.path.isfile(check_file):
450return ""
451
452with io.open(check_file, encoding="utf8") as f:
453code = f.read()
454if has_fixits(code):
455return ' "Yes"'
456
457base_class = get_base_class(code, check_file)
458if base_class:
459base_file = os.path.join(clang_tidy_path, dirname, base_class + ".cpp")
460if os.path.isfile(base_file):
461with io.open(base_file, encoding="utf8") as f:
462code = f.read()
463if has_fixits(code):
464return ' "Yes"'
465
466return ""
467
468def process_doc(doc_file):
469check_name = doc_file[0] + "-" + doc_file[1].replace(".rst", "")
470
471with io.open(os.path.join(docs_dir, *doc_file), "r", encoding="utf8") as doc:
472content = doc.read()
473match = re.search(".*:orphan:.*", content)
474
475if match:
476# Orphan page, don't list it.
477return "", ""
478
479match = re.search(r".*:http-equiv=refresh: \d+;URL=(.*).html(.*)", content)
480# Is it a redirect?
481return check_name, match
482
483def format_link(doc_file):
484check_name, match = process_doc(doc_file)
485if not match and check_name and not check_name.startswith("clang-analyzer-"):
486return " :doc:`%(check_name)s <%(module)s/%(check)s>`,%(autofix)s\n" % {
487"check_name": check_name,
488"module": doc_file[0],
489"check": doc_file[1].replace(".rst", ""),
490"autofix": has_auto_fix(check_name),
491}
492else:
493return ""
494
495def format_link_alias(doc_file):
496check_name, match = process_doc(doc_file)
497if (match or (check_name.startswith("clang-analyzer-"))) and check_name:
498module = doc_file[0]
499check_file = doc_file[1].replace(".rst", "")
500if not match or match.group(1) == "https://clang.llvm.org/docs/analyzer/checkers":
501title = "Clang Static Analyzer " + check_file
502# Preserve the anchor in checkers.html from group 2.
503target = "" if not match else match.group(1) + ".html" + match.group(2)
504autofix = ""
505ref_begin = ""
506ref_end = "_"
507else:
508redirect_parts = re.search(r"^\.\./([^/]*)/([^/]*)$", match.group(1))
509title = redirect_parts[1] + "-" + redirect_parts[2]
510target = redirect_parts[1] + "/" + redirect_parts[2]
511autofix = has_auto_fix(title)
512ref_begin = ":doc:"
513ref_end = ""
514
515if target:
516# The checker is just a redirect.
517return (
518" :doc:`%(check_name)s <%(module)s/%(check_file)s>`, %(ref_begin)s`%(title)s <%(target)s>`%(ref_end)s,%(autofix)s\n"
519% {
520"check_name": check_name,
521"module": module,
522"check_file": check_file,
523"target": target,
524"title": title,
525"autofix": autofix,
526"ref_begin" : ref_begin,
527"ref_end" : ref_end
528})
529else:
530# The checker is just a alias without redirect.
531return (
532" :doc:`%(check_name)s <%(module)s/%(check_file)s>`, %(title)s,%(autofix)s\n"
533% {
534"check_name": check_name,
535"module": module,
536"check_file": check_file,
537"target": target,
538"title": title,
539"autofix": autofix,
540})
541return ""
542
543checks = map(format_link, doc_files)
544checks_alias = map(format_link_alias, doc_files)
545
546print("Updating %s..." % filename)
547with io.open(filename, "w", encoding="utf8", newline="\n") as f:
548for line in lines:
549f.write(line)
550if line.strip() == ".. csv-table::":
551# We dump the checkers
552f.write(' :header: "Name", "Offers fixes"\n\n')
553f.writelines(checks)
554# and the aliases
555f.write("\n\n")
556f.write(".. csv-table:: Aliases..\n")
557f.write(' :header: "Name", "Redirect", "Offers fixes"\n\n')
558f.writelines(checks_alias)
559break
560
561
562# Adds a documentation for the check.
563def write_docs(module_path, module, check_name):
564check_name_dashes = module + "-" + check_name
565filename = os.path.normpath(
566os.path.join(
567module_path, "../../docs/clang-tidy/checks/", module, check_name + ".rst"
568)
569)
570print("Creating %s..." % filename)
571with io.open(filename, "w", encoding="utf8", newline="\n") as f:
572f.write(
573""".. title:: clang-tidy - %(check_name_dashes)s
574
575%(check_name_dashes)s
576%(underline)s
577
578FIXME: Describe what patterns does the check detect and why. Give examples.
579"""
580% {
581"check_name_dashes": check_name_dashes,
582"underline": "=" * len(check_name_dashes),
583}
584)
585
586
587def get_camel_name(check_name):
588return "".join(map(lambda elem: elem.capitalize(), check_name.split("-")))
589
590
591def get_camel_check_name(check_name):
592return get_camel_name(check_name) + "Check"
593
594
595def main():
596language_to_extension = {
597"c": "c",
598"c++": "cpp",
599"objc": "m",
600"objc++": "mm",
601}
602parser = argparse.ArgumentParser()
603parser.add_argument(
604"--update-docs",
605action="store_true",
606help="just update the list of documentation files, then exit",
607)
608parser.add_argument(
609"--language",
610help="language to use for new check (defaults to c++)",
611choices=language_to_extension.keys(),
612default="c++",
613metavar="LANG",
614)
615parser.add_argument(
616"module",
617nargs="?",
618help="module directory under which to place the new tidy check (e.g., misc)",
619)
620parser.add_argument(
621"check", nargs="?", help="name of new tidy check to add (e.g. foo-do-the-stuff)"
622)
623args = parser.parse_args()
624
625if args.update_docs:
626update_checks_list(os.path.dirname(sys.argv[0]))
627return
628
629if not args.module or not args.check:
630print("Module and check must be specified.")
631parser.print_usage()
632return
633
634module = args.module
635check_name = args.check
636check_name_camel = get_camel_check_name(check_name)
637if check_name.startswith(module):
638print(
639'Check name "%s" must not start with the module "%s". Exiting.'
640% (check_name, module)
641)
642return
643clang_tidy_path = os.path.dirname(sys.argv[0])
644module_path = os.path.join(clang_tidy_path, module)
645
646if not adapt_cmake(module_path, check_name_camel):
647return
648
649# Map module names to namespace names that don't conflict with widely used top-level namespaces.
650if module == "llvm":
651namespace = module + "_check"
652else:
653namespace = module
654
655write_header(module_path, module, namespace, check_name, check_name_camel)
656write_implementation(module_path, module, namespace, check_name_camel)
657adapt_module(module_path, module, check_name, check_name_camel)
658add_release_notes(module_path, module, check_name)
659test_extension = language_to_extension.get(args.language)
660write_test(module_path, module, check_name, test_extension)
661write_docs(module_path, module, check_name)
662update_checks_list(clang_tidy_path)
663print("Done. Now it's your turn!")
664
665
666if __name__ == "__main__":
667main()
668