release/19.x: Ofast deprecation clarifications (#101005)

[llvmbot]

Backport 48d4d4b

Requested by: @AaronBallman

[llvmbot]

@AaronBallman What do you think about merging this PR to the release branch?

[llvmbot]

@llvm/pr-subscribers-clang

Author: None (llvmbot)

Changes

Backport 48d4d4b

Requested by: @AaronBallman

---

Full diff: https://github.com/llvm/llvm-project/pull/101663.diff

1 Files Affected:

• (modified) clang/docs/CommandGuide/clang.rst (+6-2)

diff --git a/clang/docs/CommandGuide/clang.rst b/clang/docs/CommandGuide/clang.rst
index 663aca1f6ddcb..a0c2594d06c61 100644
--- a/clang/docs/CommandGuide/clang.rst
+++ b/clang/docs/CommandGuide/clang.rst
@@ -429,8 +429,12 @@ Code Generation Options
 
     :option:`-Ofast` Enables all the optimizations from :option:`-O3` along
     with other aggressive optimizations that may violate strict compliance with
-    language standards. This is deprecated in favor of :option:`-O3`
-    in combination with :option:`-ffast-math`.
+    language standards. This is deprecated in Clang 19 and a warning is emitted
+    that :option:`-O3` in combination with :option:`-ffast-math` should be used
+    instead if the request for non-standard math behavior is intended. There
+    is no timeline yet for removal; the aim is to discourage use of
+    :option:`-Ofast` due to the surprising behavior of an optimization flag
+    changing the observable behavior of correct code.
 
     :option:`-Os` Like :option:`-O2` with extra optimizations to reduce code
     size.

[AaronBallman]

LGTM! There's no chance these changes are what is breaking the ABI precommit CI tests. ;-)

[github-actions]

@AaronBallman (or anyone else). If you would like to add a note about this fix in the release notes (completely optional). Please reply to this comment with a one or two sentence description of the fix. When you are done, please add the release:note label to this PR.

[AaronBallman]

The current release note reads as:

- The ``-Ofast`` command-line option has been deprecated. This option both
  enables the ``-O3`` optimization-level, as well as enabling non-standard
  ``-ffast-math`` behaviors. As such, it is somewhat misleading as an
  "optimization level". Users are advised to switch to ``-O3 -ffast-math`` if
  the use of non-standard math behavior is intended, and ``-O3`` otherwise.
  See `RFC <https://discourse.llvm.org/t/rfc-deprecate-ofast/78687>`_ for details.

and I think we'd like this to be changed to instead read:

- The ``-Ofast`` command-line option has been deprecated. This option both
  enables the ``-O3`` optimization-level, as well as enabling other
  options, including non-standard ``-ffast-math`` behaviors. As such, 
  it is somewhat misleading as an "optimization level". Users are
  advised to switch to ``-O3 -ffast-math -fstrict-aliasing``
  to retain the previous behavior, and ``-O3`` otherwise.
  **Note**: there is no firm date for removal of the option; its
  use is discouraged and the option may or may not be removed
  in the future. See
  `RFC <https://discourse.llvm.org/t/rfc-deprecate-ofast/78687>`_
  for details.

WDYT @sjoerdmeijer ?

[sjoerdmeijer]

Excellent, thanks, LGTM