diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 3d3776acbc7bea..b914d3397b6dda 100644 --- 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 `. - - * ``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 `. + + * ``no``: Don't build the JIT. + * ``yes``: Enable the JIT. To disable it at runtime, set the environment + variable :envvar:`PYTHON_JIT=0 `. + * ``yes-off``: Build the JIT, but disable it by default. To enable it at + runtime, set the environment variable :envvar:`PYTHON_JIT=1 `. + * ``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 `. + + ``--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 c35e4365de025b..7b5f6cc1efdf0f 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -77,6 +77,7 @@ Summary -- release highlights :ref:`argparse `, :ref:`json ` and :ref:`calendar ` CLIs +* :ref:`Binary releases for the experimental just-in-time 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 ` 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 ff4b3964e65bad..8e817574b4d72b 100644 --- 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/)