https://github.com/MichelleCDjunaidi updated https://github.com/llvm/llvm-project/pull/106672
>From 3518ede871664d3d0f45a51b9e462b53ffa4a7d4 Mon Sep 17 00:00:00 2001 From: MichelleCDjunaidi <87893361+michellecdjuna...@users.noreply.github.com> Date: Fri, 30 Aug 2024 14:40:39 +0800 Subject: [PATCH 1/4] update outdated information like directing to Phabricator --- clang-tools-extra/docs/clang-tidy/Contributing.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/clang-tools-extra/docs/clang-tidy/Contributing.rst b/clang-tools-extra/docs/clang-tidy/Contributing.rst index 92074bd4dae8ba..176a112d3013ed 100644 --- a/clang-tools-extra/docs/clang-tidy/Contributing.rst +++ b/clang-tools-extra/docs/clang-tidy/Contributing.rst @@ -130,11 +130,12 @@ 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 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 .. _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/ @@ -690,8 +691,8 @@ warnings and errors. The script provides multiple configuration flags. that the file names are matched against. ``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 using the ``-exclude-header-filter`` flag. It has the same + behavior as the corresponding :program:`clang-tidy` flag. * 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 +759,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 >From 70c9c6a154ec9df2114f140b827e8b30d59eda2f Mon Sep 17 00:00:00 2001 From: MichelleCDjunaidi <87893361+michellecdjuna...@users.noreply.github.com> Date: Fri, 30 Aug 2024 14:41:49 +0800 Subject: [PATCH 2/4] update clang-query section to be more detailed Also disclaims the mismatch between clang-query and clang-tidy as discussed here https://discourse.llvm.org/t/inconsistency-between-hasdescendant-in-clang-query-and-clang-libtooling-matchers/80799/ --- .../docs/clang-tidy/Contributing.rst | 25 +++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/clang-tools-extra/docs/clang-tidy/Contributing.rst b/clang-tools-extra/docs/clang-tidy/Contributing.rst index 176a112d3013ed..7bb6c116259f68 100644 --- a/clang-tools-extra/docs/clang-tidy/Contributing.rst +++ b/clang-tools-extra/docs/clang-tidy/Contributing.rst @@ -337,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 tab after a previous matcher's open brace 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 will be the same or similar to your +interactively constructed matcher (there will be cases where they differ slightly). +You can use local variables to preserve your intention-revealing names that you applied +to nested matchers. Creating private matchers ^^^^^^^^^^^^^^^^^^^^^^^^^ >From 88b1013260433fe05929c5796f3e67eea787b9b8 Mon Sep 17 00:00:00 2001 From: MichelleCDjunaidi <87893361+michellecdjuna...@users.noreply.github.com> Date: Fri, 30 Aug 2024 14:43:23 +0800 Subject: [PATCH 3/4] update out-of-tree guide --- .../docs/clang-tidy/Contributing.rst | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/clang-tools-extra/docs/clang-tidy/Contributing.rst b/clang-tools-extra/docs/clang-tidy/Contributing.rst index 7bb6c116259f68..e92e86621c684d 100644 --- a/clang-tools-extra/docs/clang-tidy/Contributing.rst +++ b/clang-tools-extra/docs/clang-tidy/Contributing.rst @@ -658,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. @@ -676,6 +679,17 @@ 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 checks out of tree might involve getting ``llvm-lit`` from an +installed version of LLVM through the `Stand-alone Builds`_ section. 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. + +.. _Stand-alone Builds: 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 -------------------------- >From 2d0ce91ddb5e61679da5156bfa8cd252f83ace75 Mon Sep 17 00:00:00 2001 From: MichelleCDjunaidi <87893361+michellecdjuna...@users.noreply.github.com> Date: Fri, 30 Aug 2024 21:13:46 +0800 Subject: [PATCH 4/4] fix wording and formatting, add flags --- .../docs/clang-tidy/Contributing.rst | 36 ++++++++++--------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/clang-tools-extra/docs/clang-tidy/Contributing.rst b/clang-tools-extra/docs/clang-tidy/Contributing.rst index e92e86621c684d..b04809c3308f17 100644 --- a/clang-tools-extra/docs/clang-tidy/Contributing.rst +++ b/clang-tools-extra/docs/clang-tidy/Contributing.rst @@ -127,13 +127,13 @@ 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 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 Github: https://github.com/llvm/llvm-project @@ -343,16 +343,16 @@ matching expressions to simplify your matcher. clang-query> let c1 cxxRecordDecl() clang-query> match c1 -Alternatively, pressing tab after a previous matcher's open brace would also show which -matchers can be chained with the previous matcher, though some matchers that work may not -be listed. +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 will be the same or similar to your -interactively constructed matcher (there will be cases where they differ slightly). +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 differ slightly). You can use local variables to preserve your intention-revealing names that you applied to nested matchers. @@ -664,7 +664,7 @@ 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. If using CMake, use the keyword -MODULE while invoking add_library or llvm_add_library. +``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. @@ -679,12 +679,14 @@ 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 checks out of tree might involve getting ``llvm-lit`` from an -installed version of LLVM through the `Stand-alone Builds`_ section. 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. +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. -.. _Stand-alone Builds: https://llvm.org/docs/GettingStarted.html +.. _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 @@ -714,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 ``-exclude-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`` _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
