本文使用Anaconda环境进行演示，python版本为3.8，若读者不使用Anaconda，需自行配置环境。
Pybind11是一个纯头文件库，用于将C++函数封装出Python接口。该库可以很方便地使用conda进行安装，执行命令conda install pybind11 pytest。完成安装后，我们开始编写第一个程序，命名为hello.cpp。
// hello.cpp
#include <pybind11/pybind11.h>
#include <iostream>
namespace py = pybind11;
using namespace std;
void say_hello(const char* name)
{
cout << "Hello, " << name << "! This is a message from C++ library!" << endl;
}
PYBIND11_MODULE(hello, m)
{
m.def("say_hello", &say_hello, "Print hello to the name.");
}
上面的cpp文件中，say_hello为程序函数，PYBIND11_MODULE为包装函数，此二者在实际应用中一般会分别存放在不同的文件中，但在本例中为演示需要，我将他们放在了同一个文件中。
PYBIND11_MODULE是一个宏定义，其功能是创建一个函数，这个函数会在Python执行import语句时被调用，其接受两个参数，第一个参数为模块名称，这里我们直接将hello填入，稍候可以在Python中使用import hello导入该模块；第二个参数m是创建Python关联代码的主接口，其类型为py::module_。module_::def()用于生成能够将say_hello函数暴露给Python的代码，其第一个参数为字符串，将会成为Python中调用的函数名；第二个参数是C++函数的引用；第三个参数是说明字符串，在Python中可以使用help(say_hello)查看。
现在，我们可以着手编译这个库了，这里我使用g++进行编译，通过-shared参数将其编译为共享库，在Linux和MacOS上的编译命令稍有不同：
- Linux
g++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) hello.cpp -o hello$(python3-config --extension-suffix)
- MacOS
g++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) hello.cpp -o hello$(python3-config --extension-suffix) -undefined dynamic_lookup
在我的系统中，会生成一个名为hello.cpython-38-darwin.so的文件，这就是编译产生的共享库文件。现在，在当前目录进入python解释器，即可导入包并运行函数：
$ python
Python 3.8.12 (default, Oct 12 2021, 06:23:56)
[Clang 10.0.0 ] :: Anaconda, Inc. on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import hello
>>> hello.say_hello("Tom")
Hello, Tom! This is a message from C++ library!
除了手动编译外，还可以使用cmake工具进行跨平台编译配置，在当前目录下新建一个CMakeLists.txt文件，然后写入下面的命令：
cmake_minimum_required(VERSION 3.4...3.18)
project(hello)
find_package(Python COMPONENTS Interpreter Development REQUIRED)
find_package(pybind11 REQUIRED)
pybind11_add_module(hello hello.cpp)
其中，find_package函数会自动找到正确的依赖包，pybind11_add_module函数添加了一个名为hello的模块。
保存退出后，执行cmake . && make命令，即可看到编译产生的共享库文件。
使用py::arg参数可以将变量名也暴露给python，同时，若有需要，还可以设置参数默认值：
PYBIND11_MODULE(hello, m)
{
m.def("say_hello", &say_hello, "Print hello to the name.", py::arg("name")="Jack");
}
Python运行效果：
>>> import hello
>>> hello.say_hello()
Hello, Jack! This is a message from C++ library!
>>> hello.say_hello("Nic")
Hello, Nic! This is a message from C++ library!
>>> hello.say_hello(name="George")
Hello, George! This is a message from C++ library!
>>> help(hello.say_hello)
Help on built-in function say_hello in module hello:
say_hello(...) method of builtins.PyCapsule instance
say_hello(name: str = 'Jack') -> None
Print hello to the name.
(END)
py::arg参数还有一种简化写法，通过引入名称空间pybind11::literals，可以使用_a后缀来替代py::arg，例如，上面的一条m.def函数可以写成：
using namespace pybind11::literals;
PYBIND11_MODULE(hello, m)
{
m.def("say_hello", &say_hello, "name"_a="Jack");
}
除了包装函数外，通过使用module_::attr函数可以将C++中的变量暴露给Python，例如下面的C++程序：
// hello.cpp
#include <pybind11/pybind11.h>
#include <iostream>
namespace py = pybind11;
using namespace std;
using namespace pybind11::literals;
const char* where = "This is a message from C++ library!";
const char* cst = "This is an auto cast string by pybind11.";
void say_hello(const char* name)
{
cout << "Hello, " << name << "!" << endl;
}
PYBIND11_MODULE(hello, m)
{
m.def("say_hello", &say_hello, "name"_a="Jack");
m.attr("where") = where;
m.attr("cast") = py::cast(cst);
}
Python中运行效果：
>>> import hello
>>> hello.say_hello("Tom")
Hello, Tom!
>>> print(hello.where)
This is a message from C++ library!
>>> print(hello.cast)
This is an auto cast string by pybind11.
>>> type(hello.cast)
<class 'str'>
