diff --git a/AGENTS.md b/AGENTS.md index b7d60f6610..06c90331c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,6 +100,7 @@ Packaging produces two distributions: the normal `pybind11` (headers live inside introduces or broadens a path that can discard or replace the primary error, flag it to the human reviewer and explain whether the policy's exceptional-case allowance is justified. +- If you change a minimum supported version (headers, CMake, `pyproject.toml`, or the CI matrix), update `docs/supported.rst`. - Try to add to an existing test file if possible (more files slow down tests). - Default C++ standard follows the consumer's toolchain; CI exercises a wide matrix (CPython 3.9+, PyPy, GraalPy; multiple compilers and C++ standards). Keep changes portable across that matrix. - PR descriptions follow a template, the key part is under "Suggested changelog entry", which is how we generate our changelog (with `nox -s make_changelog`) diff --git a/README.rst b/README.rst index c68f03bbf3..467f15bcf1 100644 --- a/README.rst +++ b/README.rst @@ -81,7 +81,7 @@ Goodies In addition to the core functionality, pybind11 provides some extra goodies: -- CPython 3.9+, PyPy3 7.3.17+, and GraalPy 24.1+ are supported with an +- CPython 3.9+, PyPy3 7.3.17+, and GraalPy 25.0+ are supported with an implementation-agnostic interface (see older versions for older CPython and PyPy versions). @@ -124,7 +124,9 @@ Supported platforms & compilers ------------------------------- pybind11 is exercised in continuous integration across a range of operating -systems, Python versions, C++ standards, and toolchains. For an up-to-date +systems, Python versions, C++ standards, and toolchains. The +`supported versions `_ +page lists the minimum version of each one. For an up-to-date view of the combinations we currently test, please see the `pybind11 GitHub Actions `_ and `AppVeyor `_ logs. diff --git a/docs/index.rst b/docs/index.rst index a25684f54f..f10e51779e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -46,5 +46,6 @@ faq benchmark limitations + supported reference cmake/index diff --git a/docs/limitations.rst b/docs/limitations.rst index 1b06ea8728..6de87573fb 100644 --- a/docs/limitations.rst +++ b/docs/limitations.rst @@ -24,21 +24,6 @@ pybind11; see `pybind11_json `_ for an example. -Known bugs -^^^^^^^^^^ - -These are issues that hopefully will one day be fixed, but currently are -unsolved. If you know how to help with one of these issues, contributions -are welcome! - -- Intel 20.2 is currently having an issue with the test suite. - `#2573 `_ - -- Debug mode Python does not support 1-5 tests in the test suite currently. - `#2422 `_ - -- PyPy3 7.3.1 and 7.3.2 have issues with several tests on 32-bit Windows. - Known limitations ^^^^^^^^^^^^^^^^^ @@ -53,16 +38,8 @@ clean, well written patch would likely be accepted to solve them. Python 3.9.0 warning ^^^^^^^^^^^^^^^^^^^^ -Combining older versions of pybind11 (< 2.6.0) with Python on exactly 3.9.0 -will trigger undefined behavior that typically manifests as crashes during -interpreter shutdown (but could also destroy your data. **You have been -warned**). - -This issue was `fixed in Python `_. -As a mitigation for this bug, pybind11 2.6.0 or newer includes a workaround -specifically when Python 3.9.0 is detected at runtime, leaking about 50 bytes -of memory when a callback function is garbage collected. For reference, the -pybind11 test suite has about 2,000 such callbacks, but only 49 are garbage -collected before the end-of-process. Wheels (even if built with Python 3.9.0) -will correctly avoid the leak when run in Python 3.9.1, and this does not -affect other 3.X versions. +pybind11 older than 2.6.0 with Python 3.9.0 causes undefined behavior, which +usually shows as a crash at interpreter shutdown. The bug was `fixed in Python +3.9.1 `_. pybind11 2.6.0 and newer +detect 3.9.0 at runtime and leak about 50 bytes each time a callback function is +garbage collected to avoid the bug. Use Python 3.9.1 or newer. diff --git a/docs/supported.rst b/docs/supported.rst new file mode 100644 index 0000000000..83708f56ae --- /dev/null +++ b/docs/supported.rst @@ -0,0 +1,123 @@ +.. _supported: + +Supported versions +################## + +This page lists the oldest version of each tool or dependency that pybind11 +supports. Each entry has two values: + +**Minimum tested** + The oldest version that CI tests. + +**Minimum expected** + The oldest version that we hope works. Usually the headers or the build + system reject older versions with an error. We fix bugs reported for this + version and later, but CI does not test them. + +Python +====== + +.. list-table:: + :header-rows: 1 + :widths: 30 20 20 30 + + * - Implementation + - Minimum expected + - Minimum tested + - Notes + * - CPython + - 3.9 + - 3.9 + - + * - CPython, free-threaded + - 3.13t + - 3.14t + - See :ref:`misc_free_threading`. + * - CPython, stable ABI (``abi3``) + - 3.12 + - 3.12 + - See :doc:`advanced/stable_abi`. + * - CPython, free-threaded stable ABI (``abi3t``) + - 3.15t + - 3.15t + - First release of ``abi3t``. + * - PyPy + - 3.10 (v7.3.17) + - 3.11 (v7.3.23) + - We support v8 too. + * - GraalPy + - 25.0 + - 25.0 + - CI tested 24.x before pybind11 3.1. It can work, but we do not test it. + +We plan to drop 3.13t support soon, as it was experimental. Use 3.14t or newer. + +C++ standard and compilers +========================== + +We support C++11 through C++23. + +.. list-table:: + :header-rows: 1 + :widths: 30 20 20 30 + + * - Compiler + - Minimum expected + - Minimum tested + - Notes + * - GCC + - 4.8 + - 8 (AlmaLinux 8) + - + * - Clang + - 3.3 + - 5 + - + * - Apple Clang + - Xcode 5 + - Xcode 16 + - The version of the default macOS runner. + * - MSVC + - 2019 (19.20) + - 2022 + - GitHub Actions does not have MSVC 2019 runners. + * - Intel ICC (classic) + - 18 (C++11), 19 (C++14) + - Latest classic ICC + - + * - NVCC (CUDA) + - + - 12.2 + - + * - NVIDIA HPC SDK + - + - 26.5 + - + +Build tools and optional dependencies +===================================== + +.. list-table:: + :header-rows: 1 + :widths: 30 20 20 30 + + * - Tool + - Minimum expected + - Minimum tested + - Notes + * - CMake + - 3.15 + - 3.15 + - 4.x supported too. + * - Eigen + - 3.2.7 + - 3.3.9 + - ``pybind11/eigen/tensor.h`` needs Eigen 3.3.0 or newer. + * - NumPy + - + - 1.21 + - NumPy 2 needs pybind11 2.12 or newer. + * - scikit-build-core + - 0.11.2 + - latest + - Only needed to build the pybind11 Python package from source.