Author: Aaron Ballman Date: 2023-03-27T09:55:47-04:00 New Revision: ce548b6130b675a433de7fecb37db8f3b56d5c5a
URL: https://github.com/llvm/llvm-project/commit/ce548b6130b675a433de7fecb37db8f3b56d5c5a DIFF: https://github.com/llvm/llvm-project/commit/ce548b6130b675a433de7fecb37db8f3b56d5c5a.diff LOG: Document the Clang policies on claiming support for a feature We do not currently have this written down anywhere, and as a result, we're sometimes inconsistent with how we handle feature test macros and the feature status pages. This is an attempt to document what I understand our existing policies to be instead of defining a new policy. Note, this is being added to the Clang internals manual because we don't have a separate document for Clang developer policies. At some point, I think we may want a standalone document for that, and this content can be moved there at that time. Differential Revision: https://reviews.llvm.org/D146420 Added: Modified: clang/docs/InternalsManual.rst Removed: ################################################################################ diff --git a/clang/docs/InternalsManual.rst b/clang/docs/InternalsManual.rst index a20fe623a5c8..3ba8ed8c0ef6 100644 --- a/clang/docs/InternalsManual.rst +++ b/clang/docs/InternalsManual.rst @@ -3268,3 +3268,39 @@ are similar. proper visitation for your expression, enabling various IDE features such as syntax highlighting, cross-referencing, and so on. The ``c-index-test`` helper program can be used to test these features. + +Feature Test Macros +=================== +Clang implements several ways to test whether a feature is supported or not. +Some of these feature tests are standardized, like ``__has_cpp_attribute`` or +``__cpp_lambdas``, while others are Clang extensions, like ``__has_builtin``. +The common theme among all the various feature tests is that they are a utility +to tell users that we think a particular feature is complete. However, +completeness is a diff icult property to define because features may still have +lingering bugs, may only work on some targets, etc. We use the following +criteria when deciding whether to expose a feature test macro (or particular +result value for the feature test): + + * Are there known issues where we reject valid code that should be accepted? + * Are there known issues where we accept invalid code that should be rejected? + * Are there known crashes, failed assertions, or miscompilations? + * Are there known issues on a particular relevant target? + +If the answer to any of these is "yes", the feature test macro should either +not be defined or there should be very strong rationale for why the issues +should not prevent defining it. Note, it is acceptable to define the feature +test macro on a per-target basis if needed. + +When in doubt, being conservative is better than being aggressive. If we don't +claim support for the feature but it does useful things, users can still use it +and provide us with useful feedback on what is missing. But if we claim support +for a feature that has significant bugs, we've eliminated most of the utility +of having a feature testing macro at all because users are then forced to test +what compiler version is in use to get a more accurate answer. + +The status reported by the feature test macro should always be reflected in the +language support page for the corresponding feature (`C++ +<https://clang.llvm.org/cxx_status.html>`_, `C +<https://clang.llvm.org/c_status.html>`_) if applicable. This page can give +more nuanced information to the user as well, such as claiming partial support +for a feature and specifying details as to what remains to be done. _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
