[clang-tidy] Add avoid-pragma-once.

clang-tools-extra/clang-tidy/portability/AvoidPragmaOnceCheck.cpp

@@ -31,7 +31,8 @@ class PragmaOnceCallbacks : public PPCallbacks {
     }
     Str = Str.trim();
     if (Str.starts_with("once")) {
-      Check->diag(Loc, "Avoid pragma once.");
+      Check->diag(Loc,
+                  "avoid 'pragma once' directive; use include guards instead");
     }
   }
 

clang-tools-extra/clang-tidy/portability/AvoidPragmaOnceCheck.h

@@ -13,7 +13,9 @@
 
 namespace clang::tidy::portability {
 
-/// FIXME: Write a short description.
+/// Finds uses of ``#pragma once`` and suggests replacing them with standard
+/// include guards (``#ifndef``/``#define``/``#endif``) for improved
+/// portability.
 ///
 /// For the user-facing documentation see:
 /// http://clang.llvm.org/extra/clang-tidy/checks/portability/avoid-pragma-once.html

clang-tools-extra/docs/ReleaseNotes.rst

@@ -145,7 +145,8 @@ New checks
 - New :doc:`portability-avoid-pragma-once
   <clang-tidy/checks/portability/avoid-pragma-once>` check.
 
-  A check that catches pragma once.
+  Finds uses of ``#pragma once`` and suggests replacing them with standard
+  include guards (``#ifndef``/``#define``/``#endif``) for improved portability.
 
 New check aliases
 ^^^^^^^^^^^^^^^^^

clang-tools-extra/docs/clang-tidy/checks/list.rst

@@ -351,7 +351,7 @@ Clang-Tidy Checks
    :doc:`performance-type-promotion-in-math-fn <performance/type-promotion-in-math-fn>`, "Yes"
    :doc:`performance-unnecessary-copy-initialization <performance/unnecessary-copy-initialization>`, "Yes"
    :doc:`performance-unnecessary-value-param <performance/unnecessary-value-param>`, "Yes"
-   :doc:`portability-avoid-pragma-once <portability/avoid-pragma-once>`, "Yes"
+   :doc:`portability-avoid-pragma-once <portability/avoid-pragma-once>`,
    :doc:`portability-restrict-system-includes <portability/restrict-system-includes>`, "Yes"
    :doc:`portability-simd-intrinsics <portability/simd-intrinsics>`,
    :doc:`portability-std-allocator-const <portability/std-allocator-const>`,

clang-tools-extra/docs/clang-tidy/checks/portability/avoid-pragma-once.rst

@@ -3,10 +3,22 @@
 portability-avoid-pragma-once
 =============================
 
-This check catches pragma once usage.
+Finds uses of ``#pragma once`` and suggests replacing them with standard
+include guards (``#ifndef``/``#define``/``#endif``) for improved portability.
 
-For example:
+`#pragma once` is a non-standard extension, despite being widely supported
+by modern compilers. Relying on it can lead to portability issues in
+environments.
 
-```
-#pragma once // Bad: Avoid pragma once.
-```
+Some older or specialized C/C++ compilers, particularly in embedded systems,
+may not fully support #pragma once.
+
+Also it can fail in certain file system configurations,like network drives
+or complex symbolic links, potentially leading to compilation issues.
+
+Consider the following header file:
+
+.. code:: c++
+
+  // my_header.h
+  #pragma once // warning: avoid 'pragma once' directive; use include guards instead

clang-tools-extra/test/clang-tidy/checkers/portability/Inputs/avoid-pragma-once/lib1.h

@@ -0,0 +1 @@
+# pragma once

clang-tools-extra/test/clang-tidy/checkers/portability/Inputs/avoid-pragma-once/lib2.h

@@ -0,0 +1 @@
+# pragma   once

clang-tools-extra/test/clang-tidy/checkers/portability/avoid-pragma-once.cpp

@@ -1,5 +1,15 @@
 // RUN: %check_clang_tidy %s portability-avoid-pragma-once %t \
 // RUN:   -- --header-filter='.*' --  -I%S/Inputs/avoid-pragma-once
 
-#include "lib.h"
-// CHECK-MESSAGES: lib.h:1:1: warning: Avoid pragma once.
+// #pragma once
+#include "lib0.h"
+// CHECK-MESSAGES: lib0.h:1:1:  warning: avoid 'pragma once' directive; use include guards instead
+
+
+// # pragma once
+#include "lib1.h"
+// CHECK-MESSAGES: lib1.h:1:1:  warning: avoid 'pragma once' directive; use include guards instead
+
+// # pragma   once 
+#include "lib2.h"
+// CHECK-MESSAGES: lib2.h:1:1:  warning: avoid 'pragma once' directive; use include guards instead