เป็นผู้ใหญ่
v1.7.8
เดิมคือ pyo3-pack
สร้างและเผยแพร่ลังที่มีการผูก pyo3, cffi และ uniffi รวมถึงไบนารีสนิมเป็นแพ็คเกจ Python ที่มีการกำหนดค่าน้อยที่สุด รองรับการสร้างวงล้อสำหรับ python 3.8+ บน windows, linux, mac และ freebsd สามารถอัปโหลดไปยัง pypi และรองรับ pypy และ graalpy พื้นฐาน
ดูคู่มือผู้ใช้!
คุณสามารถดาวน์โหลดไบนารีจากรุ่นล่าสุดหรือติดตั้งด้วย pipx:
pipx install maturinบันทึก
pip install maturin ควรใช้งานได้หากคุณไม่ต้องการใช้ pipx
มีสี่คำสั่งหลัก:
maturin new สร้างโครงการขนส่งสินค้าใหม่โดยมีการกำหนดค่า maturinmaturin publish สร้างลังลงในแพ็คเกจ python และเผยแพร่ไปยัง pypimaturin build สร้างล้อและเก็บไว้ในโฟลเดอร์ ( target/wheels ตามค่าเริ่มต้น) แต่ไม่ได้อัปโหลด เป็นไปได้ที่จะอัปโหลดแบบเกลียวหรือ maturin uploadmaturin develop สร้างลังและติดตั้งเป็นโมดูล python โดยตรงใน virtualenv ปัจจุบัน โปรดทราบว่าแม้ว่า maturin develop จะเร็วกว่า แต่ก็ไม่รองรับฟีเจอร์ทั้งหมดที่รัน pip install หลังจากรองรับ maturin build ตรวจพบการเชื่อมโยง pyo3 โดยอัตโนมัติ สำหรับ cffi หรือไบนารี คุณต้องผ่าน -b cffi หรือ -b bin maturin ไม่ต้องการไฟล์การกำหนดค่าเพิ่มเติม และไม่ขัดแย้งกับการกำหนดค่า setuptools-rust หรือ milksnake ที่มีอยู่ คุณยังสามารถรวมเข้ากับเครื่องมือทดสอบ เช่น สารพิษ ได้อีกด้วย มีตัวอย่างสำหรับการผูกข้อมูลต่างๆ ในโฟลเดอร์ test-crates
ชื่อของบรรจุภัณฑ์จะเป็นชื่อของโครงการขนส่งสินค้า กล่าวคือ ฟิลด์ชื่อในส่วน [package] ของ Cargo.toml ชื่อของโมดูลที่คุณใช้เมื่อนำเข้าจะเป็นค่า name ในส่วน [lib] (ซึ่งเป็นค่าเริ่มต้นเป็นชื่อของแพ็คเกจ) สำหรับไบนารี มันเป็นเพียงชื่อของไบนารีที่สร้างโดยสินค้า
เมื่อใช้คำสั่ง maturin build และ maturin develop คุณสามารถคอมไพล์โปรแกรมที่เพิ่มประสิทธิภาพการทำงานได้โดยการเพิ่มแฟล็ก -r หรือ --release
แพ็คเกจ Python มี 2 รูปแบบ: รูปแบบที่สร้างขึ้นเรียกว่าการแจกแจงแบบล้อและแหล่งที่มา (sdist) ซึ่งทั้งสองรูปแบบนี้เป็นไฟล์เก็บถาวร วงล้อสามารถเข้ากันได้กับเวอร์ชันหลามใด ๆ ล่าม (โดยเฉพาะ cpython และ pypy) ระบบปฏิบัติการและสถาปัตยกรรมฮาร์ดแวร์ (สำหรับวงล้อหลามบริสุทธิ์) สามารถถูกจำกัดไว้ที่แพลตฟอร์มและสถาปัตยกรรมเฉพาะ (เช่น เมื่อใช้ ctypes หรือ cffi) หรือ ล่ามหลามเฉพาะและเวอร์ชันบนสถาปัตยกรรมและระบบปฏิบัติการเฉพาะ (เช่นด้วย pyo3)
เมื่อใช้ pip install บนแพ็คเกจ pip จะพยายามค้นหาวงล้อที่ตรงกันและติดตั้งสิ่งนั้น หากไม่พบ ระบบจะดาวน์โหลดการแจกจ่ายซอร์สและสร้างวงล้อสำหรับแพลตฟอร์มปัจจุบัน ซึ่งจำเป็นต้องติดตั้งคอมไพเลอร์ที่ถูกต้อง การติดตั้งล้อนั้นเร็วกว่าการติดตั้งการกระจายแหล่งที่มามาก เนื่องจากโดยทั่วไปแล้วล้อสำหรับการสร้างจะช้า
เมื่อคุณเผยแพร่แพ็คเกจเพื่อให้สามารถติดตั้งได้ด้วย pip install คุณจะอัปโหลดไปยัง pypi ซึ่งเป็นที่เก็บแพ็คเกจอย่างเป็นทางการ สำหรับการทดสอบ คุณสามารถใช้ test pypi แทน ซึ่งคุณสามารถใช้กับ pip install --index-url https://test.pypi.org/simple/ โปรดทราบว่าสำหรับการเผยแพร่สำหรับ linux คุณต้องใช้คอนเทนเนอร์ docker ของ manylinux ในขณะที่สำหรับการเผยแพร่จากพื้นที่เก็บข้อมูลของคุณ คุณสามารถใช้การดำเนินการ GitHub PyO3/maturin-action ได้
สำหรับ pyo3 นั้น maturin สามารถสร้างแพ็คเกจสำหรับเวอร์ชัน python ที่ติดตั้งไว้เท่านั้น บน linux และ mac จะใช้เวอร์ชัน python ทั้งหมดใน PATH หากคุณไม่ได้ตั้งค่าล่ามของคุณเองด้วย -i ระบบจะใช้การวิเคราะห์พฤติกรรมเพื่อค้นหาการติดตั้งหลาม บน windows ทุกรุ่นจากตัวเรียกใช้งาน python (ซึ่งติดตั้งโดยค่าเริ่มต้นโดยตัวติดตั้ง python.org) และสภาพแวดล้อม conda ทั้งหมดยกเว้นฐานจะถูกใช้ คุณสามารถตรวจสอบเวอร์ชันที่ถูกเลือกได้ด้วยคำสั่งย่อย list-python
pyo3 จะตั้งค่าล่ามหลามที่ใช้ในตัวแปรสภาพแวดล้อม PYTHON_SYS_EXECUTABLE ซึ่งสามารถใช้ได้จากสคริปต์บิลด์ที่กำหนดเอง Maturin สามารถสร้างและอัปโหลดวงล้อสำหรับ pypy ด้วย pyo3 แม้ว่าจะมีการทดสอบเฉพาะ pypy3.7-7.3 บน linux เท่านั้น
Cffi wheel เข้ากันได้กับ python ทุกรุ่นรวมถึง pypy หากไม่ได้ติดตั้ง cffi และ python กำลังทำงานอยู่ใน virtualenv, maturin จะติดตั้งมัน ไม่เช่นนั้นคุณจะต้องติดตั้งมันด้วยตัวเอง ( pip install cffi )
maturin ใช้ cbindgen เพื่อสร้างไฟล์ส่วนหัว ซึ่งสามารถปรับแต่งได้โดยการกำหนดค่า cbindgen ผ่านไฟล์ cbindgen.toml ภายในรูทโปรเจ็กต์ของคุณ หรือคุณสามารถใช้สคริปต์บิลด์ที่เขียนไฟล์ส่วนหัวไปที่ $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 wheel เข้ากันได้กับ python ทุกรุ่นรวมถึง pypy
หากต้องการสร้างโปรเจ็กต์สนิม/หลามแบบผสม ให้สร้างโฟลเดอร์ที่มีชื่อโมดูลของคุณ (เช่น lib.name ใน Cargo.toml) ถัดจาก Cargo.toml ของคุณ และเพิ่มแหล่งที่มาของหลามของคุณที่นั่น:
my-project
├── Cargo.toml
├── my_project
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
└── src
└── lib.rs
คุณสามารถระบุไดเร็กทอรีซอร์สของ python อื่นใน pyproject.toml ได้โดยการตั้งค่า tool.maturin.python-source เช่น
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 ของคุณ เมื่อใช้ Develop Maturin จะคัดลอกไลบรารีเนทิฟและสำหรับ cffi ก็จะรวมโค้ดกาวไปยังโฟลเดอร์ Python ของคุณ คุณควรเพิ่มไฟล์เหล่านั้นลงใน gitignore ของคุณ
ด้วย cffi คุณสามารถทำได้ from .my_project import lib จากนั้นใช้ lib.my_native_function ด้วย pyo3 คุณสามารถโดยตรง from .my_project import my_native_function
ตัวอย่างเค้าโครงด้วย pyo3 หลังจาก maturin develop :
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 คุณสามารถระบุข้อมูลเมตาของแพ็คเกจ python ใน pyproject.toml ได้ maturin ผสานข้อมูลเมตาจาก Cargo.toml และ pyproject.toml โดย pyproject.toml จะมีความสำคัญมากกว่า Cargo.toml
หากต้องการระบุการพึ่งพาหลาม ให้เพิ่ม dependencies รายการในส่วน [project] ใน pyproject.toml รายการนี้เทียบเท่ากับ install_requires ใน setuptools:
[ 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 " คุณยังสามารถระบุตัวแยกประเภท Trove ใน pyproject.toml ของคุณภายใต้ project.classifiers :
[ project ]
name = " my-project "
classifiers = [ " Programming Language :: Python " ] maturin รองรับการสร้างผ่าน pyproject.toml หากต้องการใช้งาน ให้สร้าง pyproject.toml ถัดจาก Cargo.toml โดยมีเนื้อหาดังต่อไปนี้:
[ build-system ]
requires = [ " maturin>=1.0,<2.0 " ]
build-backend = " maturin " หากมี pyproject.toml ที่มีรายการ [build-system] maturin สามารถสร้างการกระจายซอร์สของแพ็กเกจของคุณได้เมื่อระบุ --sdist การแจกจ่ายต้นทางจะมีไฟล์เดียวกันกับ cargo package หากต้องการสร้างเฉพาะการแจกแจงแหล่งที่มา ให้ส่ง --interpreter ล่าม โดยไม่มีค่าใดๆ
จากนั้นคุณสามารถติดตั้งแพ็คเกจของคุณด้วย pip install . - ด้วย pip install . -v คุณสามารถเห็นผลลัพธ์ของสินค้าและสุกร
คุณสามารถใช้ตัวเลือก compatibility , skip-auditwheel , bindings , strip และตัวเลือกการสร้างสินค้าทั่วไปเช่น features ภายใต้ [tool.maturin] เช่นเดียวกับที่คุณทำเมื่อรันมาตูรินโดยตรง จำเป็นต้องมีคีย์ bindings สำหรับโปรเจ็กต์ cffi และ bin เนื่องจากไม่สามารถตรวจพบได้โดยอัตโนมัติ ขณะนี้บิลด์ทั้งหมดอยู่ในโหมดรีลีส (ดูรายละเอียดในกระทู้นี้)
สำหรับบิลด์ที่ไม่ใช่หลายลินุกซ์ที่มีการผูก cffi คุณสามารถใช้สิ่งต่อไปนี้:
[ build-system ]
requires = [ " maturin>=1.0,<2.0 " ]
build-backend = " maturin "
[ tool . maturin ]
bindings = " cffi "
compatibility = " linux " ตัวเลือก manylinux ยังได้รับการยอมรับว่าเป็นนามแฝงของ compatibility สำหรับความเข้ากันได้แบบย้อนหลังกับ maturin เวอร์ชันเก่า
หากต้องการรวมไฟล์ที่กำหนดเองใน sdist เพื่อใช้ในระหว่างการคอมไพล์ให้ระบุ include เป็นอาร์เรย์ของ path globs ด้วย format ที่ตั้งค่าเป็น sdist :
[ tool . maturin ]
include = [{ path = " path/**/* " , format = " sdist " }] มีคำสั่ง maturin sdist สำหรับสร้างเฉพาะการแจกแจงแหล่งที่มาเพื่อใช้เป็นวิธีแก้ปัญหาสำหรับ pypa/pip#6041
ด้วยเหตุผลด้านความสามารถในการพกพา โมดูล python แบบเนทิฟบน linux จะต้องเชื่อมโยงชุดของไลบรารีเพียงไม่กี่ไลบรารีแบบไดนามิกเท่านั้น ซึ่งติดตั้งโดยทั่วไปทุกที่ จึงเป็นที่มาของชื่อ manylinux pypa นำเสนออิมเมจนักเทียบท่าพิเศษและเครื่องมือที่เรียกว่า auditwheel เพื่อให้มั่นใจว่าสอดคล้องกับกฎของ Manylinux หากคุณต้องการเผยแพร่ wheel ที่ใช้งานกันอย่างแพร่หลายสำหรับ linux pypi คุณต้องใช้ manylinux docker image
คอมไพเลอร์ Rust ตั้งแต่เวอร์ชัน 1.64 ต้องการอย่างน้อย glibc 2.17 ดังนั้นคุณต้องใช้อย่างน้อย manylinux2014 สำหรับการเผยแพร่ เราขอแนะนำให้บังคับใช้เวอร์ชัน manylinux เดียวกันกับรูปภาพที่มีแฟล็ก manylinux เช่น ใช้ --manylinux 2014 หากคุณกำลังสร้างใน quay.io/pypa/manylinux2014_x86_64 การกระทำ GitHub ของ PyO3/maturin-action จะดูแลเรื่องนี้อยู่แล้วหากคุณตั้งค่าเช่น manylinux: 2014
maturin มีการปรับใช้ auditwheel อีกครั้งซึ่งจะตรวจสอบไลบรารีที่สร้างขึ้นโดยอัตโนมัติและให้แท็กแพลตฟอร์มที่เหมาะสมแก่วงล้อ หาก glibc ของระบบของคุณใหม่เกินไป หรือคุณเชื่อมโยงไลบรารีที่แบ่งใช้อื่นๆ ระบบจะกำหนดแท็ก linux คุณยังสามารถปิดการใช้งานการตรวจสอบเหล่านั้นได้ด้วยตนเองและใช้เป้าหมาย linux ดั้งเดิมโดยตรง --manylinux off
เพื่อให้เป็นไปตามข้อกำหนดของ manylinux อย่างสมบูรณ์ คุณจะต้องคอมไพล์ในคอนเทนเนอร์นักเทียบท่า CentOS อิมเมจ pyo3/maturin อิงตามอิมเมจ manylinux2014 และส่งผ่านอาร์กิวเมนต์ไปยังไบนารี maturin คุณสามารถใช้มันเช่นนี้:
docker run --rm -v $(pwd):/io ghcr.io/pyo3/maturin build --release # or other maturin arguments
โปรดทราบว่ารูปภาพนี้เป็นภาพพื้นฐานและมีเพียง python, maturin และสนิมที่เสถียรเท่านั้น หากคุณต้องการเครื่องมือเพิ่มเติม คุณสามารถรันคำสั่งภายในคอนเทนเนอร์ manylinux ได้ ดู konstin/complex-manylinux-maturin-docker สำหรับตัวอย่างการศึกษาขนาดเล็ก หรือ nanoporetech/fast-ctc-decode สำหรับการตั้งค่าในโลกแห่งความเป็นจริง
maturin เองนั้นสอดคล้องกับ manylinux เมื่อคอมไพล์สำหรับเป้าหมาย musl
เรายินดีให้ทุกคนมีส่วนร่วมใน Maturin! การสนับสนุนโครงการมีหลายวิธี เช่น
บันทึกการมีส่วนร่วมของเรามีแหล่งข้อมูลเพิ่มเติมหากคุณต้องการสละเวลาเป็นอาสาสมัครเพื่อมาตูรินและกำลังค้นหาว่าจะเริ่มต้นจากตรงไหน
หากคุณไม่มีเวลามีส่วนร่วมแต่ยังคงต้องการสนับสนุนความสำเร็จในอนาคตของโครงการ ผู้ดูแลของเราบางคนมีหน้าผู้สนับสนุน GitHub:
ได้รับอนุญาตภายใต้ข้อใดข้อหนึ่ง:
ตามตัวเลือกของคุณ
