1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
.. _api_bazel:
Bazel API Reference (3rd party)
===============================
This page contains a reference of the basic APIs of
`nanobind-bazel <https://github.com/nicholasjng/nanobind-bazel>`__.
.. _rules-bazel:
Rules
-----
nanobind-bazel's rules can be used to declare different types of targets in
your Bazel project. Each of these rules is a thin wrapper around a
corresponding builtin Bazel rule producing the equivalent C++ target.
The main tool to build nanobind extensions is the ``nanobind_extension`` rule.
.. py:function:: nanobind_extension
Declares a Bazel target representing a nanobind extension, which contains
the Python bindings of your C++ code.
.. code-block:: python
def nanobind_extension(
name,
domain = "",
srcs = [],
copts = [],
deps = [],
local_defines = [],
**kwargs):
It corresponds directly to the builtin
`cc_binary <https://bazel.build/reference/be/c-cpp#cc_binary>`__ rule,
with all keyword arguments being directly forwarded to a ``cc_binary``
target.
The ``domain`` argument can be used to build the target extension under a
different ABI domain, as described in the :ref:`FAQ <type-visibility>`
section.
To generate typing stubs for an extension, you can use the ``nanobind_stubgen``
rule.
.. py:function:: nanobind_stubgen
Declares a Bazel target for generating a stub file from a previously
built nanobind bindings extension.
.. code-block:: python
def nanobind_stubgen(
name,
module,
output_file = None,
output_directory = None,
imports = [],
pattern_file = None,
marker_file = None,
include_private_members = False,
exclude_docstrings = False,
recursive = False):
It generates a `py_binary <https://bazel.build/reference/be/python#py_binary>`__
rule with a corresponding runfiles distribution, which invokes nanobind's
builtin stubgen script, outputs a stub file and, optionally,
a typing marker file into ``output_directory`` (defaults to
the build output directory, commonly called "bindir" in Bazel terms).
All arguments (except the name, which is used only to refer to the target
in Bazel) correspond directly to nanobind's stubgen command line interface,
which is described in more detail in the :ref:`typing documentation <stubs>`.
*New in nanobind-bazel version 2.1.0.*
*New in nanobind-bazel v2.5.0: Added the "output_directory" and "recursive"
keyword arguments.*
To build a C++ library with nanobind as a dependency, use the
``nanobind_library`` rule.
.. py:function:: nanobind_library
Declares a Bazel target representing a C++ library depending on nanobind.
.. code-block:: python
def nanobind_library(
name,
copts = [],
deps = [],
**kwargs):
It corresponds directly to the builtin
`cc_library <https://bazel.build/reference/be/c-cpp#cc_library>`__ rule,
with all keyword arguments being directly forwarded to a ``cc_library``
target.
To build a C++ shared library with nanobind as a dependency, use the
``nanobind_shared_library`` rule.
.. py:function:: nanobind_shared_library
Declares a Bazel target representing a C++ shared library depending on
nanobind.
.. code-block:: python
def nanobind_shared_library(
name,
deps = [],
**kwargs):
It corresponds directly to the builtin
`cc_shared_library <https://bazel.build/reference/be/c-cpp#cc_shared_library>`__
rule, with all keyword arguments being directly forwarded to a
``cc_shared_library`` target.
*New in nanobind-bazel version 2.1.0.*
To build a C++ static library containing nanobind, use the
``nanobind_static_library`` rule.
.. py:function:: nanobind_static_library
Declares a Bazel target representing a static library (or archive) containing
nanobind.
.. code-block:: python
def nanobind_static_library(name, deps, **kwargs):
It corresponds directly to the builtin
`cc_static_library <https://bazel.build/reference/be/c-cpp#cc_static_library>`__
rule, with all keyword arguments being directly
forwarded to a ``cc_static_library`` target.
NB: This macro requires Bazel 7.4.0 or greater to use, as well as setting the
``--experimental_cc_static_library`` flag for the build, since the
``cc_static_library`` rule is considered experimental.
*New in nanobind-bazel version 2.7.0.*
To build a C++ test target requiring nanobind, use the ``nanobind_test`` rule.
.. py:function:: nanobind_test
Declares a Bazel target representing a C++ test depending on nanobind.
.. code-block:: python
def nanobind_test(
name,
copts = [],
deps = [],
**kwargs):
It corresponds directly to the builtin
`cc_test <https://bazel.build/reference/be/c-cpp#cc_test>`__ rule, with all
keyword arguments being directly forwarded to a ``cc_test`` target.
.. _flags-bazel:
Flags
-----
To customize some of nanobind's build options, nanobind-bazel exposes the
following flag settings.
.. py:function:: @nanobind_bazel//:minsize (boolean)
Apply nanobind's size optimizations to the built extensions. Size
optimizations are turned on by default, similarly to the CMake build.
To turn off size optimizations, you can use the shorthand notation
``--no@nanobind_bazel//:minsize``.
.. py:function:: @nanobind_bazel//:py-limited-api (string)
Build nanobind extensions against the stable ABI of the configured Python
version. Allowed values are ``"cp312"``, ``"cp313"``, and ``"cp314"``, which
target the stable ABI starting from CPython 3.12, 3.13, or 3.14 respectively.
By default, all extensions are built without any ABI limitations.
|
