mirror of
https://github.com/pybind/pybind11.git
synced 2024-12-05 03:17:11 +00:00
a97e9d8cac
* Changing `_MSC_VER` guard to `< 1910` (dropping MSVC 2015). * Removing MSVC 2015 from ci.yml, and .appveyor.yml entirely. * Bringing back .appveyor.yml from master. * appveyor Visual Studio 2017 * 1st manual pass, builds & tests with unix_clang, before pre-commit. * After clang-format (via pre-commit). * Manual pass looking for "2015", builds & tests with unix_clang, before pre-commit. * Backtracking for include/pybind11 changes in previous commit. git checkoutd07865846c
include/pybind11/attr.h include/pybind11/detail/common.h include/pybind11/functional.h -------------------- CI #4160 errors observed:2a26873727
https://github.com/pybind/pybind11/runs/5168332130?check_suite_focus=true $ grep ' error C' *.txt | sed 's/2022-02-12[^ ]*//' | sed 's/^[0-9][0-9]*//' | sed 's/^.*\.txt: //' | sort | uniqD:\a\pybind11\pybind11\include\pybind11\cast.h(1364,1): error C2752: 'pybind11::detail::type_caster<Eigen::Ref<Eigen::Vector3f,0,pybind11::EigenDStride>,void>': more than one partial specialization matches the template argument list [D:\a\pybind11\pybind11\build\tests\pybind11_tests.vcxproj] d:\a\pybind11\pybind11\include\pybind11\detail/common.h(1023): error C2737: 'pybind11::overload_cast': 'constexpr' object must be initialized [D:\a\pybind11\pybind11\build\tests\cross_module_gil_utils.vcxproj] d:\a\pybind11\pybind11\include\pybind11\detail/common.h(1023): error C2737: 'pybind11::overload_cast': 'constexpr' object must be initialized [D:\a\pybind11\pybind11\build\tests\pybind11_cross_module_tests.vcxproj] d:\a\pybind11\pybind11\include\pybind11\detail/common.h(1023): error C2737: 'pybind11::overload_cast': 'constexpr' object must be initialized [D:\a\pybind11\pybind11\build\tests\pybind11_tests.vcxproj] d:\a\pybind11\pybind11\include\pybind11\detail/common.h(1023): error C2737: 'pybind11::overload_cast': 'constexpr' object must be initialized [D:\a\pybind11\pybind11\build\tests\test_embed\external_module.vcxproj] D:\a\pybind11\pybind11\include\pybind11\detail/common.h(624): fatal error C1001: Internal compiler error. [D:\a\pybind11\pybind11\build\tests\pybind11_tests.vcxproj] D:\a\pybind11\pybind11\include\pybind11\detail/common.h(624): fatal error C1001: Internal compiler error. [D:\a\pybind11\pybind11\tests\pybind11_tests.vcxproj] $ grep ': error C2737' *.txt | sed 's/^.*MSVC//' | sed 's/___.*//' | sort | uniq _2017 $ grep ': error C2752' *.txt 3______3.8_____MSVC_2019_____x86_-DCMAKE_CXX_STANDARD=17.txt:2022-02-12T16:12:45.9921122Z D:\a\pybind11\pybind11\include\pybind11\cast.h(1364,1): error C2752: 'pybind11::detail::type_caster<Eigen::Ref<Eigen::Vector3f,0,pybind11::EigenDStride>,void>': more than one partial specialization matches the template argument list [D:\a\pybind11\pybind11\build\tests\pybind11_tests.vcxproj] $ grep ': fatal error C1001:' *.txt 10______pypy-3.8-v7.3.7_____windows-2022_____x64.txt:2022-02-12T16:12:56.3163683Z D:\a\pybind11\pybind11\include\pybind11\detail/common.h(624): fatal error C1001: Internal compiler error. [D:\a\pybind11\pybind11\tests\pybind11_tests.vcxproj] 1______3.6_____MSVC_2019_____x86.txt:2022-02-12T16:12:47.6774625Z D:\a\pybind11\pybind11\include\pybind11\detail/common.h(624): fatal error C1001: Internal compiler error. [D:\a\pybind11\pybind11\build\tests\pybind11_tests.vcxproj] 16______3.6_____windows-latest_____x64_-DPYBIND11_FINDPYTHON=ON.txt:2022-02-12T16:12:27.0556151Z D:\a\pybind11\pybind11\include\pybind11\detail/common.h(624): fatal error C1001: Internal compiler error. [D:\a\pybind11\pybind11\tests\pybind11_tests.vcxproj] 17______3.9_____windows-2019_____x64.txt:2022-02-12T16:12:30.3822566Z D:\a\pybind11\pybind11\include\pybind11\detail/common.h(624): fatal error C1001: Internal compiler error. [D:\a\pybind11\pybind11\tests\pybind11_tests.vcxproj] 2______3.7_____MSVC_2019_____x86.txt:2022-02-12T16:12:38.7018911Z D:\a\pybind11\pybind11\include\pybind11\detail/common.h(624): fatal error C1001: Internal compiler error. [D:\a\pybind11\pybind11\build\tests\pybind11_tests.vcxproj] 6______3.6_____windows-2022_____x64.txt:2022-02-12T16:12:00.4513642Z D:\a\pybind11\pybind11\include\pybind11\detail/common.h(624): fatal error C1001: Internal compiler error. [D:\a\pybind11\pybind11\tests\pybind11_tests.vcxproj] 7______3.9_____windows-2022_____x64.txt:2022-02-12T16:11:43.6306160Z D:\a\pybind11\pybind11\include\pybind11\detail/common.h(624): fatal error C1001: Internal compiler error. [D:\a\pybind11\pybind11\tests\pybind11_tests.vcxproj] 8______3.10_____windows-2022_____x64.txt:2022-02-12T16:11:49.9589644Z D:\a\pybind11\pybind11\include\pybind11\detail/common.h(624): fatal error C1001: Internal compiler error. [D:\a\pybind11\pybind11\tests\pybind11_tests.vcxproj] 9______pypy-3.7-v7.3.7_____windows-2022_____x64.txt:2022-02-12T16:11:53.7912112Z D:\a\pybind11\pybind11\include\pybind11\detail/common.h(624): fatal error C1001: Internal compiler error. [D:\a\pybind11\pybind11\tests\pybind11_tests.vcxproj] * common.h: is_template_base_of * Re-applying 4 changes from2a26873727
that work universally. * `overload_cast = {};` only for MSVC 2017 and Clang 5 * Refining condition for using is_template_base_of workaround. * Undoing MSVC 2015 workaround in test_constants_and_functions.cpp * CentOS7: silence_unused_warnings * Tweaks in response to reviews. * Adding windows-2022 C++20 * Trying another way of adding windows-2022 C++20
308 lines
13 KiB
ReStructuredText
308 lines
13 KiB
ReStructuredText
Frequently asked questions
|
||
##########################
|
||
|
||
"ImportError: dynamic module does not define init function"
|
||
===========================================================
|
||
|
||
1. Make sure that the name specified in PYBIND11_MODULE is identical to the
|
||
filename of the extension library (without suffixes such as ``.so``).
|
||
|
||
2. If the above did not fix the issue, you are likely using an incompatible
|
||
version of Python that does not match what you compiled with.
|
||
|
||
"Symbol not found: ``__Py_ZeroStruct`` / ``_PyInstanceMethod_Type``"
|
||
========================================================================
|
||
|
||
See the first answer.
|
||
|
||
"SystemError: dynamic module not initialized properly"
|
||
======================================================
|
||
|
||
See the first answer.
|
||
|
||
The Python interpreter immediately crashes when importing my module
|
||
===================================================================
|
||
|
||
See the first answer.
|
||
|
||
.. _faq_reference_arguments:
|
||
|
||
Limitations involving reference arguments
|
||
=========================================
|
||
|
||
In C++, it's fairly common to pass arguments using mutable references or
|
||
mutable pointers, which allows both read and write access to the value
|
||
supplied by the caller. This is sometimes done for efficiency reasons, or to
|
||
realize functions that have multiple return values. Here are two very basic
|
||
examples:
|
||
|
||
.. code-block:: cpp
|
||
|
||
void increment(int &i) { i++; }
|
||
void increment_ptr(int *i) { (*i)++; }
|
||
|
||
In Python, all arguments are passed by reference, so there is no general
|
||
issue in binding such code from Python.
|
||
|
||
However, certain basic Python types (like ``str``, ``int``, ``bool``,
|
||
``float``, etc.) are **immutable**. This means that the following attempt
|
||
to port the function to Python doesn't have the same effect on the value
|
||
provided by the caller -- in fact, it does nothing at all.
|
||
|
||
.. code-block:: python
|
||
|
||
def increment(i):
|
||
i += 1 # nope..
|
||
|
||
pybind11 is also affected by such language-level conventions, which means that
|
||
binding ``increment`` or ``increment_ptr`` will also create Python functions
|
||
that don't modify their arguments.
|
||
|
||
Although inconvenient, one workaround is to encapsulate the immutable types in
|
||
a custom type that does allow modifications.
|
||
|
||
An other alternative involves binding a small wrapper lambda function that
|
||
returns a tuple with all output arguments (see the remainder of the
|
||
documentation for examples on binding lambda functions). An example:
|
||
|
||
.. code-block:: cpp
|
||
|
||
int foo(int &i) { i++; return 123; }
|
||
|
||
and the binding code
|
||
|
||
.. code-block:: cpp
|
||
|
||
m.def("foo", [](int i) { int rv = foo(i); return std::make_tuple(rv, i); });
|
||
|
||
|
||
How can I reduce the build time?
|
||
================================
|
||
|
||
It's good practice to split binding code over multiple files, as in the
|
||
following example:
|
||
|
||
:file:`example.cpp`:
|
||
|
||
.. code-block:: cpp
|
||
|
||
void init_ex1(py::module_ &);
|
||
void init_ex2(py::module_ &);
|
||
/* ... */
|
||
|
||
PYBIND11_MODULE(example, m) {
|
||
init_ex1(m);
|
||
init_ex2(m);
|
||
/* ... */
|
||
}
|
||
|
||
:file:`ex1.cpp`:
|
||
|
||
.. code-block:: cpp
|
||
|
||
void init_ex1(py::module_ &m) {
|
||
m.def("add", [](int a, int b) { return a + b; });
|
||
}
|
||
|
||
:file:`ex2.cpp`:
|
||
|
||
.. code-block:: cpp
|
||
|
||
void init_ex2(py::module_ &m) {
|
||
m.def("sub", [](int a, int b) { return a - b; });
|
||
}
|
||
|
||
:command:`python`:
|
||
|
||
.. code-block:: pycon
|
||
|
||
>>> import example
|
||
>>> example.add(1, 2)
|
||
3
|
||
>>> example.sub(1, 1)
|
||
0
|
||
|
||
As shown above, the various ``init_ex`` functions should be contained in
|
||
separate files that can be compiled independently from one another, and then
|
||
linked together into the same final shared object. Following this approach
|
||
will:
|
||
|
||
1. reduce memory requirements per compilation unit.
|
||
|
||
2. enable parallel builds (if desired).
|
||
|
||
3. allow for faster incremental builds. For instance, when a single class
|
||
definition is changed, only a subset of the binding code will generally need
|
||
to be recompiled.
|
||
|
||
"recursive template instantiation exceeded maximum depth of 256"
|
||
================================================================
|
||
|
||
If you receive an error about excessive recursive template evaluation, try
|
||
specifying a larger value, e.g. ``-ftemplate-depth=1024`` on GCC/Clang. The
|
||
culprit is generally the generation of function signatures at compile time
|
||
using C++14 template metaprogramming.
|
||
|
||
.. _`faq:hidden_visibility`:
|
||
|
||
"'SomeClass' declared with greater visibility than the type of its field 'SomeClass::member' [-Wattributes]"
|
||
============================================================================================================
|
||
|
||
This error typically indicates that you are compiling without the required
|
||
``-fvisibility`` flag. pybind11 code internally forces hidden visibility on
|
||
all internal code, but if non-hidden (and thus *exported*) code attempts to
|
||
include a pybind type (for example, ``py::object`` or ``py::list``) you can run
|
||
into this warning.
|
||
|
||
To avoid it, make sure you are specifying ``-fvisibility=hidden`` when
|
||
compiling pybind code.
|
||
|
||
As to why ``-fvisibility=hidden`` is necessary, because pybind modules could
|
||
have been compiled under different versions of pybind itself, it is also
|
||
important that the symbols defined in one module do not clash with the
|
||
potentially-incompatible symbols defined in another. While Python extension
|
||
modules are usually loaded with localized symbols (under POSIX systems
|
||
typically using ``dlopen`` with the ``RTLD_LOCAL`` flag), this Python default
|
||
can be changed, but even if it isn't it is not always enough to guarantee
|
||
complete independence of the symbols involved when not using
|
||
``-fvisibility=hidden``.
|
||
|
||
Additionally, ``-fvisibility=hidden`` can deliver considerably binary size
|
||
savings. (See the following section for more details.)
|
||
|
||
|
||
.. _`faq:symhidden`:
|
||
|
||
How can I create smaller binaries?
|
||
==================================
|
||
|
||
To do its job, pybind11 extensively relies on a programming technique known as
|
||
*template metaprogramming*, which is a way of performing computation at compile
|
||
time using type information. Template metaprogramming usually instantiates code
|
||
involving significant numbers of deeply nested types that are either completely
|
||
removed or reduced to just a few instructions during the compiler's optimization
|
||
phase. However, due to the nested nature of these types, the resulting symbol
|
||
names in the compiled extension library can be extremely long. For instance,
|
||
the included test suite contains the following symbol:
|
||
|
||
.. only:: html
|
||
|
||
.. code-block:: none
|
||
|
||
__ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_
|
||
|
||
.. only:: not html
|
||
|
||
.. code-block:: cpp
|
||
|
||
__ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_
|
||
|
||
which is the mangled form of the following function type:
|
||
|
||
.. code-block:: cpp
|
||
|
||
pybind11::cpp_function::cpp_function<void, Example2, std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&, pybind11::name, pybind11::sibling, pybind11::is_method, char [28]>(void (Example2::*)(std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&), pybind11::name const&, pybind11::sibling const&, pybind11::is_method const&, char const (&) [28])
|
||
|
||
The memory needed to store just the mangled name of this function (196 bytes)
|
||
is larger than the actual piece of code (111 bytes) it represents! On the other
|
||
hand, it's silly to even give this function a name -- after all, it's just a
|
||
tiny cog in a bigger piece of machinery that is not exposed to the outside
|
||
world. So we'll generally only want to export symbols for those functions which
|
||
are actually called from the outside.
|
||
|
||
This can be achieved by specifying the parameter ``-fvisibility=hidden`` to GCC
|
||
and Clang, which sets the default symbol visibility to *hidden*, which has a
|
||
tremendous impact on the final binary size of the resulting extension library.
|
||
(On Visual Studio, symbols are already hidden by default, so nothing needs to
|
||
be done there.)
|
||
|
||
In addition to decreasing binary size, ``-fvisibility=hidden`` also avoids
|
||
potential serious issues when loading multiple modules and is required for
|
||
proper pybind operation. See the previous FAQ entry for more details.
|
||
|
||
How can I properly handle Ctrl-C in long-running functions?
|
||
===========================================================
|
||
|
||
Ctrl-C is received by the Python interpreter, and holds it until the GIL
|
||
is released, so a long-running function won't be interrupted.
|
||
|
||
To interrupt from inside your function, you can use the ``PyErr_CheckSignals()``
|
||
function, that will tell if a signal has been raised on the Python side. This
|
||
function merely checks a flag, so its impact is negligible. When a signal has
|
||
been received, you must either explicitly interrupt execution by throwing
|
||
``py::error_already_set`` (which will propagate the existing
|
||
``KeyboardInterrupt``), or clear the error (which you usually will not want):
|
||
|
||
.. code-block:: cpp
|
||
|
||
PYBIND11_MODULE(example, m)
|
||
{
|
||
m.def("long running_func", []()
|
||
{
|
||
for (;;) {
|
||
if (PyErr_CheckSignals() != 0)
|
||
throw py::error_already_set();
|
||
// Long running iteration
|
||
}
|
||
});
|
||
}
|
||
|
||
CMake doesn't detect the right Python version
|
||
=============================================
|
||
|
||
The CMake-based build system will try to automatically detect the installed
|
||
version of Python and link against that. When this fails, or when there are
|
||
multiple versions of Python and it finds the wrong one, delete
|
||
``CMakeCache.txt`` and then add ``-DPYTHON_EXECUTABLE=$(which python)`` to your
|
||
CMake configure line. (Replace ``$(which python)`` with a path to python if
|
||
your prefer.)
|
||
|
||
You can alternatively try ``-DPYBIND11_FINDPYTHON=ON``, which will activate the
|
||
new CMake FindPython support instead of pybind11's custom search. Requires
|
||
CMake 3.12+, and 3.15+ or 3.18.2+ are even better. You can set this in your
|
||
``CMakeLists.txt`` before adding or finding pybind11, as well.
|
||
|
||
Inconsistent detection of Python version in CMake and pybind11
|
||
==============================================================
|
||
|
||
The functions ``find_package(PythonInterp)`` and ``find_package(PythonLibs)``
|
||
provided by CMake for Python version detection are modified by pybind11 due to
|
||
unreliability and limitations that make them unsuitable for pybind11's needs.
|
||
Instead pybind11 provides its own, more reliable Python detection CMake code.
|
||
Conflicts can arise, however, when using pybind11 in a project that *also* uses
|
||
the CMake Python detection in a system with several Python versions installed.
|
||
|
||
This difference may cause inconsistencies and errors if *both* mechanisms are
|
||
used in the same project.
|
||
|
||
There are three possible solutions:
|
||
|
||
1. Avoid using ``find_package(PythonInterp)`` and ``find_package(PythonLibs)``
|
||
from CMake and rely on pybind11 in detecting Python version. If this is not
|
||
possible, the CMake machinery should be called *before* including pybind11.
|
||
2. Set ``PYBIND11_FINDPYTHON`` to ``True`` or use ``find_package(Python
|
||
COMPONENTS Interpreter Development)`` on modern CMake (3.12+, 3.15+ better,
|
||
3.18.2+ best). Pybind11 in these cases uses the new CMake FindPython instead
|
||
of the old, deprecated search tools, and these modules are much better at
|
||
finding the correct Python.
|
||
3. Set ``PYBIND11_NOPYTHON`` to ``TRUE``. Pybind11 will not search for Python.
|
||
However, you will have to use the target-based system, and do more setup
|
||
yourself, because it does not know about or include things that depend on
|
||
Python, like ``pybind11_add_module``. This might be ideal for integrating
|
||
into an existing system, like scikit-build's Python helpers.
|
||
|
||
How to cite this project?
|
||
=========================
|
||
|
||
We suggest the following BibTeX template to cite pybind11 in scientific
|
||
discourse:
|
||
|
||
.. code-block:: bash
|
||
|
||
@misc{pybind11,
|
||
author = {Wenzel Jakob and Jason Rhinelander and Dean Moldovan},
|
||
year = {2017},
|
||
note = {https://github.com/pybind/pybind11},
|
||
title = {pybind11 -- Seamless operability between C++11 and Python}
|
||
}
|