mirror of
https://github.com/pybind/pybind11.git
synced 2024-11-22 13:15:12 +00:00
Update the docs to reflect the new test structure
Test compilation instructions for Windows were changed to use the `cmake --build` command line invocation which should be easier than manually setting up using the CMake GUI and Visual Studio.
This commit is contained in:
Dean Moldovan
parent
18319d5598
commit
ec0d38ef25
@ -102,7 +102,7 @@ C++ side, or to perform other types of customization.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The file :file:`example/example-operator-overloading.cpp` contains a
|
||||
The file :file:`tests/test_operator_overloading.cpp` contains a
|
||||
complete example that demonstrates how to work with overloaded operators in
|
||||
more detail.
|
||||
|
||||
@ -203,14 +203,14 @@ The following interactive session shows how to call them from Python.
|
||||
is passed as an argument to another C++ function exposed in Python. In this
|
||||
case, there is no overhead. Pybind11 will extract the underlying C++
|
||||
function pointer from the wrapped function to sidestep a potential C++ ->
|
||||
Python -> C++ roundtrip. This is demonstrated in Example 5.
|
||||
Python -> C++ roundtrip. This is demonstrated in :file:`tests/test_callbacks.cpp`.
|
||||
|
||||
.. note::
|
||||
|
||||
This functionality is very useful when generating bindings for callbacks in
|
||||
C++ libraries (e.g. GUI libraries, asynchronous networking libraries, etc.).
|
||||
|
||||
The file :file:`example/example-callbacks.cpp` contains a complete example
|
||||
The file :file:`tests/test_callbacks.cpp` contains a complete example
|
||||
that demonstrates how to work with callbacks and anonymous functions in
|
||||
more detail.
|
||||
|
||||
@ -354,7 +354,7 @@ Please take a look at the :ref:`macro_notes` before using this feature.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The file :file:`example/example-virtual-functions.cpp` contains a complete
|
||||
The file :file:`tests/test_virtual_functions.cpp` contains a complete
|
||||
example that demonstrates how to override virtual functions using pybind11
|
||||
in more detail.
|
||||
|
||||
@ -472,7 +472,7 @@ can now create a python class that inherits from ``Dog``:
|
||||
|
||||
.. seealso::
|
||||
|
||||
See the file :file:`example-virtual-functions.cpp` for complete examples
|
||||
See the file :file:`tests/test_virtual_functions.cpp` for complete examples
|
||||
using both the duplication and templated trampoline approaches.
|
||||
|
||||
.. _macro_notes:
|
||||
@ -556,7 +556,7 @@ out of the box with just the core :file:`pybind11/pybind11.h` header.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The file :file:`example/example-python-types.cpp` contains a complete
|
||||
The file :file:`tests/test_python_types.cpp` contains a complete
|
||||
example that demonstrates how to pass STL data types in more detail.
|
||||
|
||||
Binding sequence data types, iterators, the slicing protocol, etc.
|
||||
@ -566,7 +566,7 @@ Please refer to the supplemental example for details.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The file :file:`example/example-sequences-and-iterators.cpp` contains a
|
||||
The file :file:`tests/test_sequences_and_iterators.cpp` contains a
|
||||
complete example that shows how to bind a sequence data type, including
|
||||
length queries (``__len__``), iterators (``__iter__``), the slicing
|
||||
protocol and other kinds of useful operations.
|
||||
@ -690,7 +690,7 @@ container:
|
||||
|
||||
.. seealso::
|
||||
|
||||
The file :file:`example/example-keep-alive.cpp` contains a complete example
|
||||
The file :file:`tests/test_keep_alive.cpp` contains a complete example
|
||||
that demonstrates using :class:`keep_alive` in more detail.
|
||||
|
||||
Implicit type conversions
|
||||
@ -892,7 +892,7 @@ Please take a look at the :ref:`macro_notes` before using this feature.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The file :file:`example/example-smart-ptr.cpp` contains a complete example
|
||||
The file :file:`tests/test_smart_ptr.cpp` contains a complete example
|
||||
that demonstrates how to work with custom reference-counting holder types
|
||||
in more detail.
|
||||
|
||||
@ -1005,7 +1005,7 @@ a first shot at handling the exception).
|
||||
Inside the translator, ``std::rethrow_exception`` should be used within
|
||||
a try block to re-throw the exception. A catch clause can then use
|
||||
``PyErr_SetString`` to set a Python exception as demonstrated
|
||||
in :file:`example-custom-exceptions.cpp``.
|
||||
in :file:`tests/test_exceptions.cpp`.
|
||||
|
||||
This example also demonstrates how to create custom exception types
|
||||
with ``py::exception``.
|
||||
@ -1143,7 +1143,7 @@ Please take a look at the :ref:`macro_notes` before using this feature.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The file :file:`example/example-opaque-types.cpp` contains a complete
|
||||
The file :file:`tests/test_opaque_types.cpp` contains a complete
|
||||
example that demonstrates how to create and expose opaque types using
|
||||
pybind11 in more detail.
|
||||
|
||||
@ -1198,7 +1198,7 @@ with NumPy and SciPy.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The file :file:`example/eigen.cpp` contains a complete example that
|
||||
The file :file:`tests/test_eigen.cpp` contains a complete example that
|
||||
shows how to pass Eigen sparse and dense data types in more detail.
|
||||
|
||||
Buffer protocol
|
||||
@ -1326,7 +1326,7 @@ limitations), refer to the section on :ref:`eigen`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The file :file:`example/example-buffers.cpp` contains a complete example
|
||||
The file :file:`tests/test_buffers.cpp` contains a complete example
|
||||
that demonstrates using the buffer protocol with pybind11 in more detail.
|
||||
|
||||
.. [#f2] http://docs.python.org/3/c-api/buffer.html
|
||||
@ -1493,7 +1493,7 @@ simply using ``vectorize``).
|
||||
|
||||
.. seealso::
|
||||
|
||||
The file :file:`example/example-numpy-vectorize.cpp` contains a complete
|
||||
The file :file:`tests/test_numpy_vectorize.cpp` contains a complete
|
||||
example that demonstrates using :func:`vectorize` in more detail.
|
||||
|
||||
Functions taking Python objects as arguments
|
||||
@ -1557,9 +1557,9 @@ with other parameters.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The file :file:`example/example-python-types.cpp` contains a complete
|
||||
The file :file:`tests/test_python_types.cpp` contains a complete
|
||||
example that demonstrates passing native Python types in more detail. The
|
||||
file :file:`example/example-arg-keywords-and-defaults.cpp` discusses usage
|
||||
file :file:`tests/test_kwargs_and_defaults.cpp` discusses usage
|
||||
of ``args`` and ``kwargs``.
|
||||
|
||||
Default arguments revisited
|
||||
@ -1633,7 +1633,7 @@ Such functions can also be created using pybind11:
|
||||
/// Binding code
|
||||
m.def("generic", &generic);
|
||||
|
||||
(See ``example/example-arg-keywords-and-defaults.cpp``). The class ``py::args``
|
||||
(See ``tests/test_kwargs_and_defaults.cpp``). The class ``py::args``
|
||||
derives from ``py::list`` and ``py::kwargs`` derives from ``py::dict`` Note
|
||||
that the ``kwargs`` argument is invalid if no keyword arguments were actually
|
||||
provided. Please refer to the other examples for details on how to iterate
|
||||
@ -1783,7 +1783,7 @@ memory corruption and/or segmentation faults.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The file :file:`example/example-pickling.cpp` contains a complete example
|
||||
The file :file:`tests/test_pickling.cpp` contains a complete example
|
||||
that demonstrates how to pickle and unpickle types using pybind11 in more
|
||||
detail.
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ First steps
|
||||
|
||||
This sections demonstrates the basic features of pybind11. Before getting
|
||||
started, make sure that development environment is set up to compile the
|
||||
included set of examples, which also double as test cases.
|
||||
included set of test cases.
|
||||
|
||||
|
||||
Compiling the test cases
|
||||
@ -22,44 +22,42 @@ After installing the prerequisites, run
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cmake .
|
||||
make -j 4
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
make pytest -j 4
|
||||
|
||||
followed by
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make test
|
||||
The last line will both compile and run the tests.
|
||||
|
||||
Windows
|
||||
-------
|
||||
|
||||
On Windows, use the `CMake GUI`_ to create a Visual Studio project. Note that
|
||||
only the 2015 release and newer versions are supported since pybind11 relies on
|
||||
various C++11 language features that break older versions of Visual Studio.
|
||||
After running CMake, open the created :file:`pybind11.sln` file and perform a
|
||||
release build, which will will produce a file named
|
||||
:file:`Release\\example.pyd`. Copy this file to the :file:`example` directory
|
||||
and run :file:`example\\run_test.py` using the targeted Python version.
|
||||
On Windows, only **Visual Studio 2015** and newer are supported since pybind11 relies
|
||||
on various C++11 language features that break older versions of Visual Studio.
|
||||
|
||||
.. _`CMake GUI`: https://cmake.org/runningcmake
|
||||
To compile and run the tests:
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
cmake --build . --config Release --target pytest
|
||||
|
||||
This will create a Visual Studio project, compile and run the target, all from the
|
||||
command line.
|
||||
|
||||
.. Note::
|
||||
|
||||
When all tests fail, make sure that
|
||||
|
||||
1. The Python binary and the testcases are compiled for the same processor
|
||||
type and bitness (i.e. either **i386** or **x86_64**)
|
||||
|
||||
2. The Python binary used to run :file:`example\\run_test.py` matches the
|
||||
Python version specified in the CMake GUI. This is controlled via
|
||||
the ``PYTHON_EXECUTABLE`` ``PYTHON_INCLUDE_DIR``, and
|
||||
``PYTHON_LIBRARY`` variables.
|
||||
If all tests fail, make sure that the Python binary and the testcases are compiled
|
||||
for the same processor type and bitness (i.e. either **i386** or **x86_64**). You
|
||||
can specify **x86_64** as the target architecture for the generated Visual Studio
|
||||
project using ``cmake -A x64 ..``.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Advanced users who are already familiar with Boost.Python may want to skip
|
||||
the tutorial and look at the test cases in the :file:`example` directory,
|
||||
the tutorial and look at the test cases in the :file:`tests` directory,
|
||||
which exercise all features of pybind11.
|
||||
|
||||
Creating bindings for a simple function
|
||||
|
||||
Loading…
Reference in New Issue
Block a user