General pybind11 에 대해서

pybind11은 주로 기존 C++ 코드의 Python 바인딩을 생성하기 위해 Python에 C++ 타입을 노출하고 그 반대로 노출하는 경량의 헤더 전용 라이브러리이다.

Boost.Python 라이브러리와 유사하다. 컴파일 시간 검사를 사용하여 타입 정보를 유추하고 기존 확장 모듈의 상용구 코드를 최소화한다. Boost.Python과 유사한 이 프로젝트가 시작된 이유는 Boost 에 있다. Boost는 존재하는 거의 모든 C++ 컴파일러와 함께 작동하는 엄청나게 크고 복잡한 유틸리티 라이브러리 모음이다. 즉, Python 바인딩만을 원할 때 지나치게 크고 불필요한 종속성이 많다고 볼 수 있다. (Boost.Python 바인딩에 대한 내용은 이전에 다룬 적이 있다.)
pybind11은 바인딩 생성과 관련이 없는 모든 것이 제거된 작은 Boost.Python 자체만 있는 버전으로 생각하면 된다. 여러 가지 면에서 Boost.Python 대비 많은 일반적인 상황에서 바인딩 코드를 훨씬 더 간단하게 만들었다.

pybind11은 BSD 스타일 라이선스에 따라 제공되고 Python(3.6+ 또는 PyPy) 및 C++ 표준 라이브러리에 의존한다.

빠르게 시작하기

빠르게 시작할 수 있도록 python_example 및 cmake_example 를 제공한다. 이것은 좋은 시작점이 될 수 있다.
두가지 프로젝트 사이의 유일한 차이점은 python_example은 Python의 설정 도구를 사용하여 모듈을 빌드하는 반면 cmake_example은 CMake(기존 C++ 프로젝트에 더 적합할 수 있음)를 사용한다는 것이다.

cmake_example 을 실행해보려면 이 저장소를 복제하고 pip 설치를 하면 된다. --recursive 옵션으로 하위 모듈로 pybind11을 가져온다.

git clone --recursive https://github.com/pybind/cmake_example.git
pip install ./cmake_example

빌드까지 성공하면 Python으로 가져올 수 있는 이진 모듈 파일이 생성된다. 다음은 현재 디렉터리에 있다고 가정하고 다음 대화형 Python 세션에서 예제를 로드하고 실행하는 방법을 보여준다.

E:\project\python>python
Python 3.11.4 (tags/v3.11.4:d2340ef, Jun  7 2023, 05:45:37) [MSC v.1934 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import cmake_example
>>> cmake_example.add(123,321)
444
>>>

간단한 함수에 대한 바인딩

두 개의 숫자를 더하고 그 결과를 반환하는 매우 간단한 함수에 대한 Python 바인딩을 생성하는 것으로 시작하자.

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

간단하게 하기 위해 이 함수와 바인딩 코드를 모두 example.cpp라는 파일에 작성한다.

#include <pybind11/pybind11.h>

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

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

    m.def("add", &add, "A function that adds two numbers");
}

PYBIND11_MODULE() 매크로는 Python 내에서 가져오기 문이 실행될 때 호출될 함수를 만든다. 모듈 이름(example)은 첫 번째 매크로 인수로 제공된다(따옴표 안에 있으면 안 됨). 두 번째 인수(m)는 바인딩 생성을 위한 기본 인터페이스인 py::module_ 유형의 변수를 정의한다. module_::def() 메서드는 add() 함수를 Python에 노출하는 바인딩 코드를 생성한다.

pybind11은 헤더 전용 라이브러리이므로 특수 라이브러리에 연결할 필요가 없으며 중간(매직) 변환 단계가 없다. Linux에서 위의 예제는 다음 명령을 사용하여 컴파일할 수 있다.

$ c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix)

위의 C++ 코드를 빌드하면 Python으로 가져올 수 있는 바이너리 모듈 파일이 생성된다. 컴파일된 모듈이 현재 디렉터리에 있다고 가정하면 다음 대화형 Python 세션은 예제를 로드하고 실행하는 방법을 보여준다.

$ python
Python 3.9.10 (main, Jan 15 2022, 11:48:04)
[Clang 13.0.0 (clang-1300.0.29.3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import example
>>> example.add(1, 2)
3
>>>

더 많은 사용방법은 공식 문서에서 찾을 수 있다.