Pybind11 (global install marker)

Warnings

• breaking Pybind11 3.0.0 introduced a significant ABI (Application Binary Interface) bump. This means that C++ extensions compiled with older versions of pybind11 (e.g., 2.x) are not binary compatible with pybind11 3.x.
  Fix: All existing C++ extensions built with pybind11 2.x must be recompiled when upgrading to pybind11 3.x or later. Ensure all dependencies using pybind11 are also updated and recompiled if they link against pybind11.
• gotcha Pybind11 is fundamentally a C++ header-only library for creating Python bindings. Its core functionality is written in C++ and compiled into a shared library (e.g., .so, .pyd). The Python package (e.g., `pybind11-global` or `pybind11`) primarily provides the C++ headers and Python-side build-time utilities (like `pybind11.get_include()`) for tools like `setuptools` or `CMake`, not direct Python runtime imports for binding features.
  Fix: Focus on C++ development for defining your bindings. Use `import pybind11` only in your build scripts (`setup.py` or similar) to locate the necessary include directories.
• gotcha The `pybind11-global` package is often a marker or a dependency wrapper. The actual Python utility functions (e.g., `pybind11.get_include()`) that help with the build process are provided by the `pybind11` package, which is a dependency of `pybind11-global`. While installing `pybind11-global` will bring in `pybind11`, remember that the Python-side helpers are prefixed with `pybind11.`
  Fix: When writing build scripts, import `pybind11` (not `pybind11_global`) to access functions like `pybind11.get_include()`.
• breaking Pybind11 3.0.0 dropped official support for older Python versions. Specifically, Python 3.6 and 3.7 are no longer supported.
  Fix: Ensure your project targets Python 3.8 or newer when using pybind11 3.x. If you need to support older Python versions, you must use a pybind11 2.x release (e.g., `pip install pybind11<3`).
• gotcha Pybind11 requires a C++11 compatible compiler at a minimum. For full feature support and modern C++ best practices, using a compiler that supports C++17 or C++20 is often recommended.
  Fix: Ensure your build system (e.g., `CMakeLists.txt` or `setup.py` `extra_compile_args`) specifies a C++ standard of C++11 or higher (e.g., `-std=c++17` for GCC/Clang, `/std:c++17` for MSVC).

Install

• pip install pybind11-global Install pybind11-global (includes pybind11)

Imports

• get_include

  import pybind11
  # ... then use pybind11.get_include() in your setup.py

  Pybind11 is primarily a C++ library. The `pybind11` package (a dependency of `pybind11-global`) provides Python utilities like `get_include()` for build systems (e.g., setuptools), not for direct runtime Python functionality.

Quickstart

This quickstart provides a `setup.py` script that defines a simple Python extension module written in C++ using pybind11. To run it, save the code as `setup.py` in a directory, then open a terminal in that directory and execute `python setup.py install`. This will compile the C++ code and install the `my_module` package into your Python environment. After installation, you can open a Python interpreter and import `my_module` to use its `add` and `square_list` functions.

import setuptools
import pybind11
import os

# This part makes the quickstart runnable by creating a dummy C++ source file.
# In a real project, this file would exist independently.
cpp_source_code = """
#include <pybind11/pybind11.h>
#include <pybind11/stl.h> // Optional: for STL containers

namespace py = pybind11;

int add(int i, int j) {
    return i + j;
}

std::vector<int> square_list(const std::vector<int>& input) {
    std::vector<int> result;
    for (int x : input) {
        result.push_back(x * x);
    }
    return result;
}

PYBIND11_MODULE(my_module, m) {
    m.doc() = "pybind11 example plugin"; // optional module docstring

    m.def("add", &add, "A function which adds two numbers");
    m.def("square_list", &square_list, "Squares elements of an integer list");
}
"""

cpp_file_name = "my_module.cpp"
if not os.path.exists(cpp_file_name):
    with open(cpp_file_name, "w") as f:
        f.write(cpp_source_code)

# Standard setup.py for a pybind11 extension
setuptools.setup(
    name="my_pybind11_package",
    version="0.0.1",
    author="Checklist.day",
    description="A minimal pybind11 example buildable via setup.py",
    ext_modules=[
        setuptools.Extension(
            "my_module", # Name of the Python module
            [cpp_file_name],
            include_dirs=[pybind11.get_include()], # Get pybind11 headers
            language='c++',
            extra_compile_args=["-O3", "-Wall", "-std=c++17"],
        ),
    ],
    zip_safe=False,
    python_requires=">=3.8",
)

print(f"To build and install: python {os.path.basename(__file__)} install")
print("Then, in Python: import my_module; print(my_module.add(1, 2)); print(my_module.square_list([1,2,3]))")