Author: MichelleCDjunaidi Date: 2024-08-30T09:55:13-04:00 New Revision: 362d37aeab7e8ba5dc4125480de3d45cc6bb23dc
URL: https://github.com/llvm/llvm-project/commit/362d37aeab7e8ba5dc4125480de3d45cc6bb23dc DIFF: https://github.com/llvm/llvm-project/commit/362d37aeab7e8ba5dc4125480de3d45cc6bb23dc.diff LOG: Update clang tidy Contributing guide (#106672) Update the documentation to direct new users to the Github instead of the discontinued Phabricator archive. Also details more ways and information regarding clang-query usage. Partially resolves/disclaims #106656 and #106663 as per discussion in https://discourse.llvm.org/t/inconsistency-between-hasdescendant-in-clang-query-and-clang-libtooling-matchers/80799/. Also updates the out-of-tree guide. For context, I recently went through the Contributing guide while writing https://github.com/llvm/llvm-project/pull/102299, and many of these updates were from my experience trying to follow the guide. e.g. I was trying to link the shared library of an out-of-tree check as SHARED in CMake and encountered duplicate symbols like _ZTIN5clang4tidy14ClangTidyCheckE. It wasn't until I saw https://github.com/llvm/llvm-project/commit/84f137a590e7de25c4105303e5938c40566c2dfb that I found out I had to use MODULE. I also encountered the clang-query difference which was a surprise as the documentation said the two matchers were "virtually identical". Also, the -header-filter thing tripped me out until I found https://github.com/llvm/llvm-project/issues/25590 and https://github.com/llvm/llvm-project/pull/91400. Usually, when people say restrict and filter, they mean filter out (since -header-filter instead includes/filters in said headers). Added: Modified: clang-tools-extra/docs/clang-tidy/Contributing.rst Removed: ################################################################################ diff --git a/clang-tools-extra/docs/clang-tidy/Contributing.rst b/clang-tools-extra/docs/clang-tidy/Contributing.rst index 92074bd4dae8ba..b04809c3308f17 100644 --- a/clang-tools-extra/docs/clang-tidy/Contributing.rst +++ b/clang-tools-extra/docs/clang-tidy/Contributing.rst @@ -127,14 +127,15 @@ Writing a clang-tidy Check So you have an idea of a useful check for :program:`clang-tidy`. -First, if you're not familiar with LLVM development, read through the `Getting -Started with LLVM`_ document for instructions on setting up your workflow and +First, if you're not familiar with LLVM development, read through the `Getting Started +with the LLVM System`_ document for instructions on setting up your workflow and the `LLVM Coding Standards`_ document to familiarize yourself with the coding -style used in the project. For code reviews we mostly use `LLVM Phabricator`_. +style used in the project. For code reviews we currently use `LLVM Github`_, +though historically we used Phabricator. -.. _Getting Started with LLVM: https://llvm.org/docs/GettingStarted.html +.. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html .. _LLVM Coding Standards: https://llvm.org/docs/CodingStandards.html -.. _LLVM Phabricator: https://llvm.org/docs/Phabricator.html +.. _LLVM Github: https://github.com/llvm/llvm-project Next, you need to decide which module the check belongs to. Modules are located in subdirectories of `clang-tidy/ @@ -336,13 +337,24 @@ a starting point for your test cases. A rough outline of the process looks like The quickest way to prototype your matcher is to use :program:`clang-query` to interactively build up your matcher. For complicated matchers, build up a matching expression incrementally and use :program:`clang-query`'s ``let`` command to save named -matching expressions to simplify your matcher. Just like breaking up a huge function -into smaller chunks with intention-revealing names can help you understand a complex -algorithm, breaking up a matcher into smaller matchers with intention-revealing names -can help you understand a complicated matcher. Once you have a working matcher, the -C++ API will be virtually identical to your interactively constructed matcher. You can -use local variables to preserve your intention-revealing names that you applied to -nested matchers. +matching expressions to simplify your matcher. + +.. code-block:: console + clang-query> let c1 cxxRecordDecl() + clang-query> match c1 + +Alternatively, pressing the tab key after a previous matcher's open parentheses would also +show which matchers can be chained with the previous matcher, though some matchers that work +may not be listed. + +Just like breaking up a huge function into smaller chunks with intention-revealing names +can help you understand a complex algorithm, breaking up a matcher into smaller matchers +with intention-revealing names can help you understand a complicated matcher. + +Once you have a working clang-query matcher, the C++ API matchers will be the same or similar +to your interactively constructed matcher (there can be cases where they diff er slightly). +You can use local variables to preserve your intention-revealing names that you applied +to nested matchers. Creating private matchers ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -646,10 +658,13 @@ directory. The path to this directory is available in a lit test with the varia Out-of-tree check plugins ------------------------- + Developing an out-of-tree check as a plugin largely follows the steps -outlined above. The plugin is a shared library whose code lives outside +outlined above, including creating a new module and doing the hacks to +register the module. The plugin is a shared library whose code lives outside the clang-tidy build system. Build and link this shared library against -LLVM as done for other kinds of Clang plugins. +LLVM as done for other kinds of Clang plugins. If using CMake, use the keyword +``MODULE`` while invoking ``add_library`` or ``llvm_add_library``. The plugin can be loaded by passing `-load` to `clang-tidy` in addition to the names of the checks to enable. @@ -664,6 +679,19 @@ compiled against the version of clang-tidy that will be loading the plugin. The plugins can use threads, TLS, or any other facilities available to in-tree code which is accessible from the external headers. +Note that testing out-of-tree checks might involve getting ``llvm-lit`` from an LLVM +installation compiled from source. See `Getting Started with the LLVM System`_ for ways +to do so. + +Alternatively, get `lit`_ following the `test-suite guide`_ and get the `FileCheck`_ binary, +and write a version of `check_clang_tidy.py`_ to suit your needs. + +.. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html +.. _test-suite guide: https://llvm.org/docs/TestSuiteGuide.html +.. _lit: https://llvm.org/docs/CommandGuide/lit.html +.. _FileCheck: https://llvm.org/docs/CommandGuide/FileCheck.html +.. _check_clang_tidy.py: https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/test/clang-tidy/check_clang_tidy.py + Running clang-tidy on LLVM -------------------------- @@ -688,10 +716,10 @@ warnings and errors. The script provides multiple configuration flags. * To restrict the files examined you can provide one or more regex arguments that the file names are matched against. - ``run-clang-tidy.py clang-tidy/.*Check\.cpp`` will only analyze clang-tidy + ``run-clang-tidy.py clang-tidy/.*Check\.cpp`` will only analyze `clang-tidy` checks. It may also be necessary to restrict the header files that warnings - are displayed from using the ``-header-filter`` flag. It has the same behavior - as the corresponding :program:`clang-tidy` flag. + are displayed from by using the ``-header-filter`` and ``-exclude-header-filter`` flags. + They have the same behavior as the corresponding :program:`clang-tidy` flags. * To apply suggested fixes ``-fix`` can be passed as an argument. This gathers all changes in a temporary directory and applies them. Passing ``-format`` @@ -758,4 +786,4 @@ There is only one argument that controls profile storage: * If you run :program:`clang-tidy` from within ``/foo`` directory, and specify ``-store-check-profile=.``, then the profile will still be saved to - ``/foo/<ISO8601-like timestamp>-example.cpp.json`` + ``/foo/<ISO8601-like timestamp>-example.cpp.json`` \ No newline at end of file _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
