GH-113464: Add the JIT to What's New (GH-133486)

diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index 3d3776acbc7bea668e0c5d0e201968bd1ec28e9d..b914d3397b6dda42eaed0dbbb6047cdb77b1e4f8 100644 (file)
--- a/Doc/using/configure.rst
+++ b/Doc/using/configure.rst
@@ -302,14 +302,21 @@ General Options
 
 .. option:: --enable-experimental-jit=[no|yes|yes-off|interpreter]
 
-   Indicate how to integrate the :ref:`JIT compiler <whatsnew313-jit-compiler>`.
-
-   * ``no`` - build the interpreter without the JIT.
-   * ``yes`` - build the interpreter with the JIT.
-   * ``yes-off`` - build the interpreter with the JIT but disable it by default.
-   * ``interpreter`` - build the interpreter without the JIT, but with the tier 2 enabled interpreter.
-
-   By convention, ``--enable-experimental-jit`` is a shorthand for ``--enable-experimental-jit=yes``.
+   Indicate how to integrate the :ref:`experimental just-in-time compiler <whatsnew314-jit-compiler>`.
+
+   * ``no``: Don't build the JIT.
+   * ``yes``: Enable the JIT. To disable it at runtime, set the environment
+     variable :envvar:`PYTHON_JIT=0 <PYTHON_JIT>`.
+   * ``yes-off``: Build the JIT, but disable it by default. To enable it at
+     runtime, set the environment variable :envvar:`PYTHON_JIT=1 <PYTHON_JIT>`.
+   * ``interpreter``: Enable the "JIT interpreter" (only useful for those
+     debugging the JIT itself). To disable it at runtime, set the environment
+     variable :envvar:`PYTHON_JIT=0 <PYTHON_JIT>`.
+
+   ``--enable-experimental-jit=no`` is the default behavior if the option is not
+   provided, and ``--enable-experimental-jit`` is shorthand for
+   ``--enable-experimental-jit=yes``.  See :file:`Tools/jit/README.md` for more
+   information, including how to install the necessary build-time dependencies.
 
    .. note::
 

diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
index a345687813f16b4286c4e4f9749a991dafc8222b..8f427fff76b0ba0c4c2f6bfac9416ad590b6b33b 100644 (file)
--- a/Doc/whatsnew/3.14.rst
+++ b/Doc/whatsnew/3.14.rst
@@ -77,6 +77,7 @@ Summary -- release highlights
   :ref:`argparse <whatsnew314-color-argparse>`,
   :ref:`json <whatsnew314-color-json>` and
   :ref:`calendar <whatsnew314-color-calendar>` CLIs
+* :ref:`Binary releases for the experimental just-in-time compiler <whatsnew314-jit-compiler>`
 
 
 Incompatible changes
@@ -715,6 +716,36 @@ in the :envvar:`PYTHONSTARTUP` script.
 (Contributed by Łukasz Langa in :gh:`131507`.)
 
 
+.. _whatsnew314-jit-compiler:
+
+Binary releases for the experimental just-in-time compiler
+----------------------------------------------------------
+
+The official macOS and Windows release binaries now include an *experimental*
+just-in-time (JIT) compiler. Although it is **not** recommended for production
+use, it can be tested by setting :envvar:`PYTHON_JIT=1 <PYTHON_JIT>` as an
+environment variable. Downstream source builds and redistributors can use the
+:option:`--enable-experimental-jit=yes-off` configuration option for similar
+behavior.
+
+The JIT is at an early stage and still in active development. As such, the
+typical performance impact of enabling it can range from 10% slower to 20%
+faster, depending on workload. To aid in testing and evaluation, a set of
+introspection functions has been provided in the :data:`sys._jit` namespace.
+:func:`sys._jit.is_available` can be used to determine if the current executable
+supports JIT compilation, while :func:`sys._jit.is_enabled` can be used to tell
+if JIT compilation has been enabled for the current process.
+
+Currently, the most significant missing functionality is that native debuggers
+and profilers like ``gdb`` and ``perf`` are unable to unwind through JIT frames
+(Python debuggers and profilers, like :mod:`pdb` or :mod:`profile`, continue to
+work without modification). Free-threaded builds do not support JIT compilation.
+
+Please report any bugs or major performance regressions that you encounter!
+
+.. seealso:: :pep:`744`
+
+
 Other language changes
 ======================
 

diff --git a/Tools/jit/README.md b/Tools/jit/README.md
index ff4b3964e65bad69dd6ed548f6092b8424550a2d..8e817574b4d72b28c6a929f2dabc0a81ad75efa4 100644 (file)
--- a/Tools/jit/README.md
+++ b/Tools/jit/README.md
@@ -54,13 +54,13 @@ choco install llvm --version=19.1.0
 
 ## Building
 
-For `PCbuild`-based builds, pass the new `--experimental-jit` option to `build.bat`.
+For `PCbuild`-based builds, pass the `--experimental-jit` option to `build.bat`.
 
-For all other builds, pass the new `--enable-experimental-jit` option to `configure`.
+For all other builds, pass the `--enable-experimental-jit` option to `configure`.
 
 Otherwise, just configure and build as you normally would. Cross-compiling "just works", since the JIT is built for the host platform.
 
-The JIT can also be enabled or disabled using the `PYTHON_JIT` environment variable, even on builds where it is enabled or disabled by default. More details about configuring CPython with the JIT and optional values for `--enable-experimental-jit` can be found [here](https://docs.python.org/dev/whatsnew/3.13.html#experimental-jit-compiler).
+The JIT can also be enabled or disabled using the `PYTHON_JIT` environment variable, even on builds where it is enabled or disabled by default. More details about configuring CPython with the JIT and optional values for `--enable-experimental-jit` can be found [here](https://docs.python.org/dev/using/configure.html#cmdoption-enable-experimental-jit).
 
 [^pep-744]: [PEP 744](https://peps.python.org/pep-0744/)