성숙한
v1.7.8
이전에는 pyo3-pack
최소한의 구성으로 pyo3, cffi 및 uniffi 바인딩과 Rust 바이너리를 Python 패키지로 사용하여 크레이트를 빌드하고 게시하세요. Windows, Linux, Mac 및 FreeBSD에서 Python 3.8+용 빌딩 휠을 지원하고 이를 pypi에 업로드할 수 있으며 기본 pypy 및 graalpy를 지원합니다.
사용자 가이드를 확인해보세요!
최신 릴리스에서 바이너리를 다운로드하거나 pipx를 사용하여 설치할 수 있습니다.
pipx install maturin메모
pip install maturin pipx를 사용하지 않으려는 경우에도 작동합니다.
네 가지 주요 명령이 있습니다:
maturin new maturin이 구성된 새로운 화물 프로젝트를 생성합니다.maturin publish 크레이트를 Python 패키지로 빌드하고 이를 pypi에 게시합니다.maturin build 휠을 빌드하고 폴더(기본적으로 target/wheels )에 저장하지만 업로드하지는 않습니다. Twine이나 maturin upload 로 업로드하는 것이 가능합니다.maturin develop 크레이트를 빌드하고 현재 virtualenv에 직접 Python 모듈로 설치합니다. maturin develop 이 더 빠르지만 maturin build 지원하는 후에 pip install 실행하는 모든 기능을 지원하지는 않습니다. pyo3 바인딩이 자동으로 감지됩니다. cffi 또는 바이너리의 경우 -b cffi 또는 -b bin 전달해야 합니다. maturin은 추가 구성 파일이 필요하지 않으며 기존 setuptools-rust 또는 milksnake 구성과 충돌하지 않습니다. Tox와 같은 테스트 도구와 통합할 수도 있습니다. test-crates 폴더에는 다양한 바인딩에 대한 예가 있습니다.
패키지 이름은 화물 프로젝트의 이름이 됩니다. 즉, Cargo.toml 의 [package] 섹션에 있는 이름 필드입니다. 가져올 때 사용하는 모듈 이름은 [lib] 섹션의 name 값이 됩니다(기본값은 패키지 이름). 바이너리의 경우 단순히 화물에 의해 생성된 바이너리의 이름입니다.
maturin build 및 maturin develop 명령을 사용할 때 -r 또는 --release 플래그를 추가하여 성능 최적화 프로그램을 컴파일할 수 있습니다.
Python 패키지는 두 가지 형식으로 제공됩니다. 휠 및 소스 배포(sdist)라는 빌드 형식, 둘 다 아카이브입니다. 휠은 모든 Python 버전, 인터프리터(주로 cpython 및 pypy), 운영 체제 및 하드웨어 아키텍처(순수 Python 휠의 경우)와 호환될 수 있으며 특정 플랫폼 및 아키텍처(예: ctypes 또는 cffi를 사용하는 경우)로 제한될 수 있습니다. 특정 아키텍처 및 운영 체제(예: pyo3 사용)의 특정 Python 인터프리터 및 버전.
패키지에서 pip install 사용하면 pip는 일치하는 휠을 찾아서 설치하려고 시도합니다. 찾지 못하면 소스 배포판을 다운로드하고 현재 플랫폼에 맞는 휠을 빌드합니다. 이를 위해서는 올바른 컴파일러를 설치해야 합니다. 휠을 설치하는 것은 일반적으로 휠을 만드는 것이 느리기 때문에 소스 배포판을 설치하는 것보다 훨씬 빠릅니다.
pip install 사용하여 설치할 수 있는 패키지를 게시하면 공식 패키지 저장소인 pypi에 업로드됩니다. 테스트를 위해 pip install --index-url https://test.pypi.org/simple/ 과 함께 사용할 수 있는 test pypi를 대신 사용할 수 있습니다. Linux용으로 게시하려면 Manylinux docker 컨테이너를 사용해야 하고, 저장소에서 게시하려면 PyO3/maturin-action github 작업을 사용할 수 있습니다.
pyo3의 경우 maturin은 설치된 Python 버전용 패키지만 빌드할 수 있습니다. Linux 및 Mac에서는 PATH 의 모든 Python 버전이 사용됩니다. -i 사용하여 자체 인터프리터를 설정하지 않으면 경험적 방법을 사용하여 Python 설치를 검색합니다. Windows에서는 Python 실행 프로그램(python.org 설치 프로그램에 의해 기본적으로 설치됨)의 모든 버전과 기본을 제외한 모든 conda 환경이 사용됩니다. list-python 하위 명령을 사용하면 어떤 버전이 선택되었는지 확인할 수 있습니다.
pyo3은 사용자 정의 빌드 스크립트에서 사용할 수 있는 환경 변수 PYTHON_SYS_EXECUTABLE 에 사용된 Python 인터프리터를 설정합니다. Linux에서 pypy3.7-7.3만 테스트되었음에도 불구하고 Maturin은 pyo3을 사용하여 pypy용 휠을 빌드하고 업로드할 수 있습니다.
Cffi 휠은 pypy를 포함한 모든 Python 버전과 호환됩니다. cffi 설치되지 않았고 Python이 virtualenv 내에서 실행 중이면 maturin이 이를 설치합니다. 그렇지 않으면 직접 설치해야 합니다( pip install cffi ).
maturin은 cbindgen을 사용하여 프로젝트 루트 내의 cbindgen.toml 파일을 통해 cbindgen을 구성하여 사용자 정의할 수 있는 헤더 파일을 생성합니다. 또는 $PROJECT_ROOT/target/header.h 에 헤더 파일을 쓰는 빌드 스크립트를 사용할 수 있습니다.
헤더 파일을 기반으로 maturin은 ffi 및 lib 개체를 내보내는 모듈을 생성합니다.
use cbindgen ;
use std :: env ;
use std :: path :: Path ;
fn main ( ) {
let crate_dir = env :: var ( "CARGO_MANIFEST_DIR" ) . unwrap ( ) ;
let bindings = cbindgen :: Builder :: new ( )
. with_no_includes ( )
. with_language ( cbindgen :: Language :: C )
. with_crate ( crate_dir )
. generate ( )
. unwrap ( ) ;
bindings . write_to_file ( Path :: new ( "target" ) . join ( "header.h" ) ) ;
} uniffi 바인딩은 uniffi-rs를 사용하여 인터페이스 정의 파일에서 Python ctypes 바인딩을 생성합니다. uniffi 휠은 pypy를 포함한 모든 Python 버전과 호환됩니다.
Rust/Python 혼합 프로젝트를 만들려면 Cargo.toml 옆에 모듈 이름(예: Cargo.toml의 lib.name )이 포함된 폴더를 만들고 거기에 Python 소스를 추가하세요.
my-project
├── Cargo.toml
├── my_project
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
└── src
└── lib.rs
예를 들어, tool.maturin.python-source 설정하여 pyproject.toml 에서 다른 Python 소스 디렉터리를 지정할 수 있습니다.
pyproject.toml
[ tool . maturin ]
python-source = " python "
module-name = " my_project._lib_name "그러면 프로젝트 구조는 다음과 같습니다.
my-project
├── Cargo.toml
├── python
│ └── my_project
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
└── src
└── lib.rs
메모
이 구조는 일반적인 ImportError 함정을 피하기 위해 권장됩니다.
maturin은 Python 폴더에 기본 확장을 모듈로 추가합니다. 개발을 사용할 때 maturin은 네이티브 라이브러리를 복사하고 cffi의 경우 글루 코드도 Python 폴더에 복사합니다. 해당 파일을 gitignore에 추가해야 합니다.
cffi를 사용하면 from .my_project import lib 수행한 다음 lib.my_native_function 사용할 수 있고, pyo3을 사용하면 from .my_project import my_native_function 직접 사용할 수 있습니다.
maturin develop 후 pyo3을 사용한 레이아웃 예:
my-project
├── Cargo.toml
├── my_project
│ ├── __init__.py
│ ├── bar.py
│ └── _lib_name.cpython-36m-x86_64-linux-gnu.so
├── README.md
└── src
└── lib.rs
이 작업을 수행할 때 코드의 모듈 이름이 module-name 의 마지막 부분과 일치하도록 설정해야 합니다(패키지 경로는 포함하지 않음).
# [ pymodule ] # [ pyo3 ( name= "_lib_name" ) ] fn my_lib_name ( _py : Python < ' _ > , m : & PyModule ) -> PyResult < ( ) > { m . add_class :: < MyPythonRustClass > ( ) ? ; Ok ( ( ) ) }
maturin은 PEP 621을 지원하므로 pyproject.toml 에서 Python 패키지 메타데이터를 지정할 수 있습니다. maturin은 Cargo.toml 과 pyproject.toml 의 메타데이터를 병합하며, pyproject.toml Cargo.toml 보다 우선합니다.
Python 종속성을 지정하려면 pyproject.toml 의 [project] 섹션에 dependencies 목록을 추가하세요. 이 목록은 setuptools의 install_requires 와 동일합니다.
[ project ]
name = " my-project "
dependencies = [ " flask~=1.1.0 " , " toml==0.10.0 " ] Pip을 사용하면 프로그램에서 일부 기능을 실행하는 셸 명령인 소위 콘솔 스크립트를 추가할 수 있습니다. [project.scripts] 섹션에 콘솔 스크립트를 추가할 수 있습니다. 키는 스크립트 이름이고 값은 some.module.path:class.function 형식의 함수 경로입니다. 여기서 class 부분은 선택 사항입니다. 함수는 인수 없이 호출됩니다. 예:
[ project . scripts ]
get_42 = " my_project:DummyClass.get_42 " project.classifiers 아래의 pyproject.toml 에서 trove 분류자를 지정할 수도 있습니다.
[ project ]
name = " my-project "
classifiers = [ " Programming Language :: Python " ] maturin은 pyproject.toml 통한 빌드를 지원합니다. 이를 사용하려면 다음 내용으로 Cargo.toml 옆에 pyproject.toml 을 만듭니다.
[ build-system ]
requires = [ " maturin>=1.0,<2.0 " ]
build-backend = " maturin " [build-system] 항목이 있는 pyproject.toml 이 있으면 --sdist 지정되면 maturin이 패키지의 소스 배포판을 빌드할 수 있습니다. 소스 배포판에는 cargo package 와 동일한 파일이 포함됩니다. 소스 배포판만 빌드하려면 값 없이 --interpreter 전달하세요.
그런 다음 pip install . . pip install . -v 화물과 maturin의 출력을 볼 수 있습니다.
maturin을 직접 실행할 때와 동일한 방식으로 compatibility , skip-auditwheel , bindings , strip 및 [tool.maturin] 아래의 features 과 같은 공통 Cargo 빌드 옵션을 사용할 수 있습니다. cffi 및 bin 프로젝트에는 자동으로 감지할 수 없으므로 bindings 키가 필요합니다. 현재 모든 빌드는 릴리스 모드에 있습니다(자세한 내용은 이 스레드 참조).
cffi 바인딩을 사용하는 non-manylinux 빌드의 경우 다음을 사용할 수 있습니다.
[ build-system ]
requires = [ " maturin>=1.0,<2.0 " ]
build-backend = " maturin "
[ tool . maturin ]
bindings = " cffi "
compatibility = " linux " manylinux 옵션은 이전 버전의 maturin과의 하위 호환성을 위한 compatibility 별칭으로도 허용됩니다.
컴파일 중에 사용하기 위해 sdist에 임의의 파일을 포함하려면 sdist format 으로 설정된 path glob 배열로 include 지정하십시오.
[ tool . maturin ]
include = [{ path = " path/**/* " , format = " sdist " }] pypa/pip#6041에 대한 해결 방법으로 소스 배포판만 빌드하기 위한 maturin sdist 명령이 있습니다.
이식성의 이유로 Linux의 기본 Python 모듈은 기본적으로 모든 곳에 설치되는 극소수의 라이브러리 세트만 동적으로 연결해야 하므로 이름은 ManyLinux입니다. pypa는 ManyLinux 규칙을 준수하도록 보장하기 위해 특수 도커 이미지와 auditwheel이라는 도구를 제공합니다. 널리 사용 가능한 Linux pypi용 휠을 게시하려면 Manylinux docker image 를 사용해야 합니다 .
버전 1.64 이후의 Rust 컴파일러에는 최소한 glibc 2.17이 필요하므로 최소한 Manylinux2014를 사용해야 합니다. 게시하려면 Manylinux 플래그를 사용하여 이미지와 동일한 Manylinux 버전을 적용하는 것이 좋습니다. 예를 들어 quay.io/pypa/manylinux2014_x86_64 에 빌드하는 경우 --manylinux 2014 사용하세요. 예를 들어 manylinux: 2014 설정하면 PyO3/maturin-action github 작업이 이미 이를 처리합니다.
maturin에는 생성된 라이브러리를 자동으로 확인하고 휠에 적절한 플랫폼 태그를 제공하는 auditwheel의 재구현이 포함되어 있습니다. 시스템의 glibc가 너무 새롭거나 다른 공유 라이브러리를 연결하면 linux 태그가 할당됩니다. 또한 해당 검사를 수동으로 비활성화하고 --manylinux off 와 함께 기본 Linux 대상을 직접 사용할 수도 있습니다.
완전한 ManyLinux 규정 준수를 위해서는 CentOS Docker 컨테이너에서 컴파일해야 합니다. pyo3/maturin 이미지는 Manylinux2014 이미지를 기반으로 하며 maturin 바이너리에 인수를 전달합니다. 다음과 같이 사용할 수 있습니다.
docker run --rm -v $(pwd):/io ghcr.io/pyo3/maturin build --release # or other maturin arguments
이 이미지는 매우 기본적이며 Python, maturin 및 stable Rust만 포함되어 있습니다. 추가 도구가 필요한 경우 Manylinux 컨테이너 내에서 명령을 실행할 수 있습니다. 간단한 교육용 예제는 konstin/complex-manylinux-maturin-docker를 참조하고 실제 설정은 nanoporetech/fast-ctc-decode를 참조하세요.
maturin 자체는 musl 대상용으로 컴파일할 때 많은 Linux와 호환됩니다.
maturin에 기여하는 모든 분들을 환영합니다! 프로젝트를 지원하는 방법은 다음과 같이 다양합니다.
우리의 기여 노트에는 maturin에 대한 자원 봉사 시간을 원하고 어디서부터 시작해야 할지 검색하는 경우 더 많은 리소스가 있습니다.
직접 기여할 시간은 없지만 프로젝트의 향후 성공을 지원하고 싶다면 일부 관리자에게 GitHub 후원 페이지가 있습니다.
다음 중 하나에 따라 라이선스가 부여됩니다.
귀하의 선택에 따라.
