diff options
Diffstat (limited to 'ext/pybind11/docs/faq.rst')
| -rw-r--r-- | ext/pybind11/docs/faq.rst | 96 |
1 files changed, 60 insertions, 36 deletions
diff --git a/ext/pybind11/docs/faq.rst b/ext/pybind11/docs/faq.rst index 8f33eb014..93ccf10e5 100644 --- a/ext/pybind11/docs/faq.rst +++ b/ext/pybind11/docs/faq.rst @@ -4,9 +4,13 @@ Frequently asked questions "ImportError: dynamic module does not define init function" =========================================================== -You are likely using an incompatible version of Python (for instance, the -extension library was compiled against Python 2, while the interpreter is -running on top of some version of Python 3, or vice versa). +1. Make sure that the name specified in PYBIND11_MODULE is identical to the +filename of the extension library (without prefixes such as .so) + +2. If the above did not fix the issue, you are likely using an incompatible +version of Python (for instance, the extension library was compiled against +Python 2, while the interpreter is running on top of some version of Python +3, or vice versa). "Symbol not found: ``__Py_ZeroStruct`` / ``_PyInstanceMethod_Type``" ======================================================================== @@ -35,6 +39,8 @@ multiple versions of Python and it finds the wrong one, delete cmake -DPYTHON_EXECUTABLE:FILEPATH=<path-to-python-executable> . +.. _faq_reference_arguments: + Limitations involving reference arguments ========================================= @@ -116,7 +122,7 @@ following example: .. code-block:: cpp - void init_ex1(py::module &m) { + void init_ex2(py::module &m) { m.def("sub", [](int a, int b) { return a - b; }); } @@ -228,46 +234,64 @@ 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. -Another aspect that can require a fair bit of code are function signature -descriptions. pybind11 automatically generates human-readable function -signatures for docstrings, e.g.: - -.. code-block:: none - - | __init__(...) - | __init__(*args, **kwargs) - | Overloaded function. - | - | 1. __init__(example.Example1) -> NoneType - | - | Docstring for overload #1 goes here - | - | 2. __init__(example.Example1, int) -> NoneType - | - | Docstring for overload #2 goes here - | - | 3. __init__(example.Example1, example.Example1) -> NoneType - | - | Docstring for overload #3 goes here - - -In C++11 mode, these are generated at run time using string concatenation, -which can amount to 10-20% of the size of the resulting binary. If you can, -enable C++14 language features (using ``-std=c++14`` for GCC/Clang), in which -case signatures are efficiently pre-generated at compile time. Unfortunately, -Visual Studio's C++14 support (``constexpr``) is not good enough as of April -2016, so it always uses the more expensive run-time approach. - -Working with ancient Visual Studio 2009 builds on Windows +Working with ancient Visual Studio 2008 builds on Windows ========================================================= The official Windows distributions of Python are compiled using truly ancient versions of Visual Studio that lack good C++11 support. Some users implicitly assume that it would be impossible to load a plugin built with Visual Studio 2015 into a Python distribution that was compiled using Visual -Studio 2009. However, no such issue exists: it's perfectly legitimate to +Studio 2008. However, no such issue exists: it's perfectly legitimate to interface DLLs that are built with different compilers and/or C libraries. Common gotchas to watch out for involve not ``free()``-ing memory region that that were ``malloc()``-ed in another shared library, using data structures with incompatible ABIs, and so on. pybind11 is very careful not to make these types of mistakes. + +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 not used by pybind11 due to unreliability and limitations that make +them unsuitable for pybind11's needs. Instead pybind 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. Consider the following +Cmake code executed in a system with Python 2.7 and 3.x installed: + +.. code-block:: cmake + + find_package(PythonInterp) + find_package(PythonLibs) + find_package(pybind11) + +It will detect Python 2.7 and pybind11 will pick it as well. + +In contrast this code: + +.. code-block:: cmake + + find_package(pybind11) + find_package(PythonInterp) + find_package(PythonLibs) + +will detect Python 3.x for pybind11 and may crash on ``find_package(PythonLibs)`` afterwards. + +It is advised to avoid using ``find_package(PythonInterp)`` and ``find_package(PythonLibs)`` from CMake and rely +on pybind11 in detecting Python version. If this is not possible CMake machinery should be called *before* including pybind11. + +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} + } |