[clang-tools-extra] [clang-tidy] New portability-avoid-pragma-comment (PR #215239)
via cfe-commits
cfe-commits at lists.llvm.org
Mon Aug 10 07:48:49 PDT 2026
https://github.com/t-a-james updated https://github.com/llvm/llvm-project/pull/215239
>From 5c76f8d1f42b643dc4f6a8b912d798af210e745a Mon Sep 17 00:00:00 2001
From: Tom James <tom.james at siemens.com>
Date: Mon, 10 Aug 2026 11:52:40 +0100
Subject: [PATCH 1/4] [clang-tidy] New portability-avoid-pragma-comment
Finds uses of `#pragma comment` and, for `lib` or `linker` comments,
suggests using the build system for improved portability.
`#pragma comment` is not widely supported outside of MSVC. Clang
supports the use of `#pragma comment` to link libraries on both Windows
and Linux, but other kinds are only supported on Windows. Using `pragma
comment` to change link flags may be unexpected in projects that prefer
to set these flags in the build system.
---
.../portability/AvoidPragmaCommentCheck.cpp | 50 +++++++++++++++++++
.../portability/AvoidPragmaCommentCheck.h | 37 ++++++++++++++
.../clang-tidy/portability/CMakeLists.txt | 1 +
.../portability/PortabilityTidyModule.cpp | 3 ++
clang-tools-extra/docs/ReleaseNotes.md | 6 +++
.../docs/clang-tidy/checks/list.md | 1 +
.../portability/avoid-pragma-comment.rst | 23 +++++++++
.../avoid-pragma-comment-linux.cpp | 21 ++++++++
.../avoid-pragma-comment-windows.cpp | 42 ++++++++++++++++
9 files changed, 184 insertions(+)
create mode 100644 clang-tools-extra/clang-tidy/portability/AvoidPragmaCommentCheck.cpp
create mode 100644 clang-tools-extra/clang-tidy/portability/AvoidPragmaCommentCheck.h
create mode 100644 clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-comment.rst
create mode 100644 clang-tools-extra/test/clang-tidy/checkers/portability/avoid-pragma-comment-linux.cpp
create mode 100644 clang-tools-extra/test/clang-tidy/checkers/portability/avoid-pragma-comment-windows.cpp
diff --git a/clang-tools-extra/clang-tidy/portability/AvoidPragmaCommentCheck.cpp b/clang-tools-extra/clang-tidy/portability/AvoidPragmaCommentCheck.cpp
new file mode 100644
index 0000000000000..1b2f5d92687b8
--- /dev/null
+++ b/clang-tools-extra/clang-tidy/portability/AvoidPragmaCommentCheck.cpp
@@ -0,0 +1,50 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "AvoidPragmaCommentCheck.h"
+#include "clang/ASTMatchers/ASTMatchFinder.h"
+
+#include <string>
+
+using namespace clang::ast_matchers;
+
+namespace clang::tidy::portability {
+
+static const internal::VariadicDynCastAllOfMatcher<Decl, PragmaCommentDecl>
+ // All other node matchers declared in this way are camelCase
+ // NOLINTNEXTLINE(readability-identifier-naming)
+ pragmaCommentDecl;
+
+void AvoidPragmaCommentCheck::registerMatchers(MatchFinder *Finder) {
+ Finder->addMatcher(pragmaCommentDecl().bind("pragma"), this);
+}
+
+void AvoidPragmaCommentCheck::check(const MatchFinder::MatchResult &Result) {
+ const auto *Pragma = Result.Nodes.getNodeAs<PragmaCommentDecl>("pragma");
+
+ std::string Msg{"avoid 'pragma comment' directive"};
+
+ // We can give specific advice about comments that add linker flags, but other
+ // kinds are too generic
+ const PragmaMSCommentKind &Kind = Pragma->getCommentKind();
+ switch (Kind) {
+ case PragmaMSCommentKind::PCK_Lib:
+ Msg.append("; use the build system to link libraries");
+ break;
+ case PragmaMSCommentKind::PCK_Linker:
+ Msg.append("; use the build system to set linker options");
+ break;
+ case PragmaMSCommentKind::PCK_Unknown:
+ llvm_unreachable("unexpected pragma comment kind");
+ default:
+ break;
+ }
+ diag(Pragma->getBeginLoc(), Msg);
+}
+
+} // namespace clang::tidy::portability
diff --git a/clang-tools-extra/clang-tidy/portability/AvoidPragmaCommentCheck.h b/clang-tools-extra/clang-tidy/portability/AvoidPragmaCommentCheck.h
new file mode 100644
index 0000000000000..47f326374b97a
--- /dev/null
+++ b/clang-tools-extra/clang-tidy/portability/AvoidPragmaCommentCheck.h
@@ -0,0 +1,37 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_PORTABILITY_AVOIDPRAGMACOMMENTCHECK_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_PORTABILITY_AVOIDPRAGMACOMMENTCHECK_H
+
+#include "../ClangTidyCheck.h"
+
+namespace clang::tidy::portability {
+
+/// Finds uses of ``#pragma comment`` and for ``lib`` or ``linker`` comments
+/// suggests using the build system for improved portability.
+///
+/// Only the "lib" pragma comment type is implemented on Linux, the rest are
+/// Windows-only and should be caught by "-Wunknown-pragmas" on Linux.
+///
+/// For the user-facing documentation see:
+/// https://clang.llvm.org/extra/clang-tidy/checks/portability/avoid-pragma-comment.html
+class AvoidPragmaCommentCheck : public ClangTidyCheck {
+public:
+ AvoidPragmaCommentCheck(StringRef Name, ClangTidyContext *Context)
+ : ClangTidyCheck(Name, Context) {}
+ void registerMatchers(ast_matchers::MatchFinder *Finder) override;
+ void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
+ bool isLanguageVersionSupported(const LangOptions &LangOpts) const override {
+ return LangOpts.CPlusPlus;
+ }
+};
+
+} // namespace clang::tidy::portability
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_PORTABILITY_AVOIDPRAGMACOMMENTCHECK_H
diff --git a/clang-tools-extra/clang-tidy/portability/CMakeLists.txt b/clang-tools-extra/clang-tidy/portability/CMakeLists.txt
index 170fedf52130e..f9bcb149b8145 100644
--- a/clang-tools-extra/clang-tidy/portability/CMakeLists.txt
+++ b/clang-tools-extra/clang-tidy/portability/CMakeLists.txt
@@ -5,6 +5,7 @@ set(LLVM_LINK_COMPONENTS
)
add_clang_library(clangTidyPortabilityModule STATIC
+ AvoidPragmaCommentCheck.cpp
AvoidPragmaOnceCheck.cpp
NoAssemblerCheck.cpp
PortabilityTidyModule.cpp
diff --git a/clang-tools-extra/clang-tidy/portability/PortabilityTidyModule.cpp b/clang-tools-extra/clang-tidy/portability/PortabilityTidyModule.cpp
index 1f2340502f685..c12ef3d20e871 100644
--- a/clang-tools-extra/clang-tidy/portability/PortabilityTidyModule.cpp
+++ b/clang-tools-extra/clang-tidy/portability/PortabilityTidyModule.cpp
@@ -8,6 +8,7 @@
#include "../ClangTidy.h"
#include "../ClangTidyModule.h"
+#include "AvoidPragmaCommentCheck.h"
#include "AvoidPragmaOnceCheck.h"
#include "NoAssemblerCheck.h"
#include "RestrictSystemIncludesCheck.h"
@@ -22,6 +23,8 @@ namespace {
class PortabilityModule : public ClangTidyModule {
public:
void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
+ CheckFactories.registerCheck<AvoidPragmaCommentCheck>(
+ "portability-avoid-pragma-comment");
CheckFactories.registerCheck<AvoidPragmaOnceCheck>(
"portability-avoid-pragma-once");
CheckFactories.registerCheck<NoAssemblerCheck>("portability-no-assembler");
diff --git a/clang-tools-extra/docs/ReleaseNotes.md b/clang-tools-extra/docs/ReleaseNotes.md
index 29de9aef9e4b6..0f1dcf1ed20de 100644
--- a/clang-tools-extra/docs/ReleaseNotes.md
+++ b/clang-tools-extra/docs/ReleaseNotes.md
@@ -106,6 +106,12 @@ infrastructure are described first, followed by tool-specific sections.
Finds calls to `value_or` (and alternative spellings `valueOr`,
`ValueOr`) on optional types where the return type is expensive to copy.
+- New {doc}`portability-avoid-pragma-comment
+ <clang-tidy/checks/portability/avoid-pragma-comment>` check.
+
+ Finds uses of `#pragma comment` and, for `lib` or `linker` comments, suggests
+ using the build system for improved portability.
+
#### New check aliases
#### Changes in existing checks
diff --git a/clang-tools-extra/docs/clang-tidy/checks/list.md b/clang-tools-extra/docs/clang-tidy/checks/list.md
index 77c9eafa7835c..5d279824714e7 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/list.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/list.md
@@ -372,6 +372,7 @@ readability/*
| {doc}`performance-unnecessary-copy-initialization <performance/unnecessary-copy-initialization>` | Yes |
| {doc}`performance-unnecessary-value-param <performance/unnecessary-value-param>` | Yes |
| {doc}`performance-use-std-move <performance/use-std-move>` | Yes |
+| {doc}`portability-avoid-pragma-comment <portability/avoid-pragma-comment>` | |
| {doc}`portability-avoid-pragma-once <portability/avoid-pragma-once>` | |
| {doc}`portability-no-assembler <portability/no-assembler>` | |
| {doc}`portability-restrict-system-includes <portability/restrict-system-includes>` | Yes |
diff --git a/clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-comment.rst b/clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-comment.rst
new file mode 100644
index 0000000000000..d38541710ac3c
--- /dev/null
+++ b/clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-comment.rst
@@ -0,0 +1,23 @@
+.. title:: clang-tidy - portability-avoid-pragma-comment
+
+portability-avoid-pragma-comment
+================================
+
+Finds uses of ``#pragma comment`` and, for ``lib`` or ``linker`` comments,
+suggests using the build system for improved portability.
+
+``#pragma comment`` is not widely supported outside of MSVC. Clang supports the
+use of ``#pragma comment`` to link libraries on both Windows and Linux, but
+other kinds are only supported on Windows. Using ``pragma comment`` to change
+link flags may be unexpected in projects that prefer to set these flags in the
+build system.
+
+.. code:: c++
+ // Clang supports the `lib` kind on Windows and Linux, but setting link flags
+ // outside the build system may be unexpected
+ #pragma comment(lib, "some_lib")
+ #pragma comment(linker, "some_linker_flag")
+
+ // Clang only supports the `compiler` and `user` kinds when targeting Windows
+ #pragma comment(compiler)
+ #pragma comment(user, "Some string")
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-tidy/checkers/portability/avoid-pragma-comment-linux.cpp b/clang-tools-extra/test/clang-tidy/checkers/portability/avoid-pragma-comment-linux.cpp
new file mode 100644
index 0000000000000..165371be06933
--- /dev/null
+++ b/clang-tools-extra/test/clang-tidy/checkers/portability/avoid-pragma-comment-linux.cpp
@@ -0,0 +1,21 @@
+// Only the "lib" pragma comment type is implemented on Linux, the rest are
+// Windows-only. Therefore, this file always targets linux.
+// RUN: %check_clang_tidy %s portability-avoid-pragma-comment %t -- -- -target x86_64-unknown-linux-gnu
+
+#pragma comment(lib, "some_lib")
+// CHECK-MESSAGES: :[[@LINE-1]]:9: warning: avoid 'pragma comment' directive; use the build system to link libraries [portability-avoid-pragma-comment]
+
+_Pragma("comment(lib, \"some_lib\")")
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: avoid 'pragma comment' directive; use the build system to link libraries [portability-avoid-pragma-comment]
+
+// Only the "lib" pragma comment type is implemented on Linux, the rest are
+// Windows-only and should be caught by "-Wunknown-pragmas" or
+// "-Wignored-pragmas" on Linux. They won't show up in the Linux AST, so
+// portability-avoid-pragma-comment won't detect the below instances.
+#pragma comment(linker, "some_linker_flag")
+#pragma comment(compiler)
+#pragma comment(user, "Some string")
+
+_Pragma("comment(linker, \"some_linker_flag\")")
+_Pragma("comment(compiler)")
+_Pragma("comment(user, \"Some string\")")
diff --git a/clang-tools-extra/test/clang-tidy/checkers/portability/avoid-pragma-comment-windows.cpp b/clang-tools-extra/test/clang-tidy/checkers/portability/avoid-pragma-comment-windows.cpp
new file mode 100644
index 0000000000000..24166898c0691
--- /dev/null
+++ b/clang-tools-extra/test/clang-tidy/checkers/portability/avoid-pragma-comment-windows.cpp
@@ -0,0 +1,42 @@
+// Only the "lib" pragma comment type is implemented on Linux, the rest are
+// Windows-only. Therefore, this file always targets windows-msvc.
+// RUN: %check_clang_tidy %s portability-avoid-pragma-comment %t -- -- -target x86_64-pc-windows-msvc
+
+
+#pragma comment(lib, "some_lib")
+// CHECK-MESSAGES: :[[@LINE-1]]:9: warning: avoid 'pragma comment' directive; use the build system to link libraries [portability-avoid-pragma-comment]
+
+_Pragma("comment(lib, \"some_lib\")")
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: avoid 'pragma comment' directive; use the build system to link libraries [portability-avoid-pragma-comment]
+
+
+#pragma comment(linker, "some_linker_flag")
+// CHECK-MESSAGES: :[[@LINE-1]]:9: warning: avoid 'pragma comment' directive; use the build system to set linker options [portability-avoid-pragma-comment]
+
+#pragma comment(compiler)
+// CHECK-MESSAGES: :[[@LINE-1]]:9: warning: avoid 'pragma comment' directive [portability-avoid-pragma-comment]
+
+#pragma comment(user, "Some string")
+// CHECK-MESSAGES: :[[@LINE-1]]:9: warning: avoid 'pragma comment' directive [portability-avoid-pragma-comment]
+
+// __pragma() is a Microsoft-specific extension
+__pragma(comment(lib, "some_lib"))
+// CHECK-MESSAGES: :[[@LINE-1]]:10: warning: avoid 'pragma comment' directive; use the build system to link libraries [portability-avoid-pragma-comment]
+
+__pragma(comment(linker, "some_linker_flag"))
+// CHECK-MESSAGES: :[[@LINE-1]]:10: warning: avoid 'pragma comment' directive; use the build system to set linker options [portability-avoid-pragma-comment]
+
+__pragma(comment(compiler))
+// CHECK-MESSAGES: :[[@LINE-1]]:10: warning: avoid 'pragma comment' directive [portability-avoid-pragma-comment]
+
+__pragma(comment(user, "Some string"))
+// CHECK-MESSAGES: :[[@LINE-1]]:10: warning: avoid 'pragma comment' directive [portability-avoid-pragma-comment]
+
+_Pragma("comment(linker, \"some_linker_flag\")")
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: avoid 'pragma comment' directive; use the build system to set linker options [portability-avoid-pragma-comment]
+
+_Pragma("comment(compiler)")
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: avoid 'pragma comment' directive [portability-avoid-pragma-comment]
+
+_Pragma("comment(user, \"Some string\")")
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: avoid 'pragma comment' directive [portability-avoid-pragma-comment]
\ No newline at end of file
>From f9246260b9c5192dcd1402910d1699494cf80bd2 Mon Sep 17 00:00:00 2001
From: Tom James <tom.james at siemens.com>
Date: Mon, 10 Aug 2026 12:22:37 +0100
Subject: [PATCH 2/4] fixup! [clang-tidy] New portability-avoid-pragma-comment
---
.../checks/portability/avoid-pragma-comment.rst | 15 ++++++++-------
1 file changed, 8 insertions(+), 7 deletions(-)
diff --git a/clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-comment.rst b/clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-comment.rst
index d38541710ac3c..8fcc9146d2003 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-comment.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-comment.rst
@@ -13,11 +13,12 @@ link flags may be unexpected in projects that prefer to set these flags in the
build system.
.. code:: c++
- // Clang supports the `lib` kind on Windows and Linux, but setting link flags
- // outside the build system may be unexpected
- #pragma comment(lib, "some_lib")
- #pragma comment(linker, "some_linker_flag")
- // Clang only supports the `compiler` and `user` kinds when targeting Windows
- #pragma comment(compiler)
- #pragma comment(user, "Some string")
\ No newline at end of file
+ // Clang supports the `lib` kind on Windows and Linux, but setting link flags
+ // outside the build system may be unexpected
+ #pragma comment(lib, "some_lib")
+ #pragma comment(linker, "some_linker_flag")
+
+ // Clang only supports the `compiler` and `user` kinds when targeting Windows
+ #pragma comment(compiler)
+ #pragma comment(user, "Some string")
\ No newline at end of file
>From 91dddd69a8d9aa8f76cf85d735f1da6dff8134ad Mon Sep 17 00:00:00 2001
From: Tom James <tom.james at siemens.com>
Date: Mon, 10 Aug 2026 12:36:02 +0100
Subject: [PATCH 3/4] fixup! [clang-tidy] New portability-avoid-pragma-comment
---
.../docs/clang-tidy/checks/portability/avoid-pragma-comment.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-comment.rst b/clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-comment.rst
index 8fcc9146d2003..2e333ab726a54 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-comment.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-comment.rst
@@ -21,4 +21,4 @@ build system.
// Clang only supports the `compiler` and `user` kinds when targeting Windows
#pragma comment(compiler)
- #pragma comment(user, "Some string")
\ No newline at end of file
+ #pragma comment(user, "Some string")
>From a1d50fc52c44beb8dee8c1a3ea473f3700bd3e98 Mon Sep 17 00:00:00 2001
From: Tom James <tom.james at siemens.com>
Date: Mon, 10 Aug 2026 15:48:04 +0100
Subject: [PATCH 4/4] fixup! [clang-tidy] New portability-avoid-pragma-comment
---
.../clang-tidy/portability/AvoidPragmaCommentCheck.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang-tools-extra/clang-tidy/portability/AvoidPragmaCommentCheck.h b/clang-tools-extra/clang-tidy/portability/AvoidPragmaCommentCheck.h
index 47f326374b97a..8f11f9399f248 100644
--- a/clang-tools-extra/clang-tidy/portability/AvoidPragmaCommentCheck.h
+++ b/clang-tools-extra/clang-tidy/portability/AvoidPragmaCommentCheck.h
@@ -28,7 +28,7 @@ class AvoidPragmaCommentCheck : public ClangTidyCheck {
void registerMatchers(ast_matchers::MatchFinder *Finder) override;
void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
bool isLanguageVersionSupported(const LangOptions &LangOpts) const override {
- return LangOpts.CPlusPlus;
+ return LangOpts.CPlusPlus || LangOpts.C99;
}
};
More information about the cfe-commits
mailing list