From d0fd372fc423e33df30d03c6fd34e67544e37b2d Mon Sep 17 00:00:00 2001
From: Nicholas Junge <nicholas.junge@web.de>
Date: Sun, 5 Jan 2025 21:14:06 +0100
Subject: [PATCH 1/2] Update nanobind-bazel docs with latest developments

`nanobind_bazel` v2.4.0 was released on the BCR. The MODULE.bazel code example
was thus updated, as is tradition, along with two more user-facing changes:

1. The minimum Bazel version was increased to Bazel 7, since we need to use a
sufficiently new `rules_python` for free-threading support.
2. The `@nanobind_bazel//:free_threading` flag was removed, since it was not
that useful - you still needed to give `rules_python`'s free-threading flag
separately to request a free-threaded toolchain, and supplying it did not
even guarantee a free-threading build. Now, we just use `rules_python`'s
free-threading flag value directly instead.
---
 docs/api_bazel.rst | 12 ------------
 docs/bazel.rst     |  6 +++---
 2 files changed, 3 insertions(+), 15 deletions(-)

diff --git a/docs/api_bazel.rst b/docs/api_bazel.rst
index f035cf3a..4788956a 100644
--- a/docs/api_bazel.rst
+++ b/docs/api_bazel.rst
@@ -155,15 +155,3 @@ following flag settings.
     version. Allowed values are ``"cp312"``, ``"cp313"``, which target the
     stable ABI starting from Python 3.12 or 3.13, respectively. By default, all
     extensions are built without any ABI limitations.
-
-.. py:function:: @nanobind_bazel//:free_threading (boolean)
-
-    Build nanobind extensions with a Python toolchain in free-threaded mode.
-    If given, the currently configured Python toolchain must support free-threading,
-    otherwise, the build will result in a compilation error.
-    Only relevant for CPython 3.13+, since support for free-threaded Python was
-    introduced in CPython 3.13.
-    For more information on free-threaded extension support in nanobind, refer to the
-    relevant :ref:`documentation section <free-threaded>`.
-
-    *New in nanobind-bazel version 2.2.0.*
diff --git a/docs/bazel.rst b/docs/bazel.rst
index e6ba2054..72f48daa 100644
--- a/docs/bazel.rst
+++ b/docs/bazel.rst
@@ -27,8 +27,8 @@ in your MODULE.bazel file:
     # Place this in your MODULE.bazel file.
     # The major version of nanobind-bazel is equal to the version
     # of the internally used nanobind.
-    # In this case, we are building bindings with nanobind v2.2.0.
-    bazel_dep(name = "nanobind_bazel", version = "2.2.0")
+    # In this case, we are building bindings with nanobind v2.4.0.
+    bazel_dep(name = "nanobind_bazel", version = "2.4.0")
 
 To instead use a development version from GitHub, you can declare the
 dependency as a ``git_override()`` in your MODULE.bazel:
@@ -57,7 +57,7 @@ and then declare it as a ``local_path_override()`` dependency:
 
 .. note::
 
-    At minimum, Bazel version 6.4.0 is required to use nanobind-bazel.
+    At minimum, Bazel version 7.0.0 is required to use nanobind-bazel.
 
 
 .. _bazel-build:

From 0330596f308aa3095c4e1461aab655228718c845 Mon Sep 17 00:00:00 2001
From: Nicholas Junge <nicholas.junge@web.de>
Date: Mon, 6 Jan 2025 13:06:31 +0100
Subject: [PATCH 2/2] Add section on free-threaded extension builds with
 nanobind_bazel

Presents the necessary toolchain setup in a code block, and mentions the
flag name that must be set for a free-threaded libnanobind build.
---
 docs/bazel.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/bazel.rst b/docs/bazel.rst
index 72f48daa..3277cd86 100644
--- a/docs/bazel.rst
+++ b/docs/bazel.rst
@@ -139,6 +139,30 @@ Naturally, since stub generation relies on the given shared object files, the
 actual extensions are built in the process before invocation of the stub
 generation script.
 
+Building extensions for free-threaded Python
+--------------------------------------------
+
+Starting from CPython 3.13, bindings extensions can be built for a free-threaded
+CPython interpreter. This requires two things: First, an eligible toolchain must
+be defined in your MODULE.bazel file, e.g. like so:
+
+.. code-block:: python
+
+    bazel_dep(name = "rules_python", version = "1.0.0")
+
+    python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+    python.toolchain(python_version = "3.13")
+
+And secondly, the ``@rules_python//python/config_settings:py_freethreaded`` flag must
+be set to "yes" when building your nanobind extension target, e.g. as
+``bazel build //path/to:my_ext --@rules_python//python/config_settings:py_freethreaded=yes``.
+
+Then, ``rules_python`` will bootstrap a free-threaded version of your target interpreter,
+and ``nanobind_bazel`` will define the ``NB_FREE_THREADED`` macro for the libnanobind
+build, indicating that nanobind should be built with free-threading support.
+For a comprehensive overview on nanobind with free-threaded Python, refer to the
+:ref:`free-threading documentation <free-threaded>`.
+
 nanobind-bazel and Python packaging
 -----------------------------------