Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update nanobind-bazel docs with latest developments #842

Merged
merged 2 commits into from
Jan 7, 2025
Merged

Update nanobind-bazel docs with latest developments #842

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d0fd372
Update nanobind-bazel docs with latest developments
nicholasjng Jan 5, 2025
0330596
Add section on free-threaded extension builds with nanobind_bazel
nicholasjng Jan 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 0 additions & 12 deletions docs/api_bazel.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.*
30 changes: 27 additions & 3 deletions docs/bazel.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
-----------------------------------

Expand Down
Loading