โมดูล Android Rust

ตามหลักการทั่วไป คำจำกัดความของโมดูล rust_* จะยึดตามการใช้งานและความคาดหวังของ cc_* อย่างใกล้ชิด ต่อไปนี้เป็นตัวอย่างของคำจำกัดความโมดูลสำหรับไบนารี ของ Rust :

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/hello_rust.rs"],
    host_supported: true,
}

หน้านี้ครอบคลุมคุณสมบัติที่พบบ่อยที่สุดสำหรับโมดูล rust_* สำหรับข้อมูลเพิ่มเติมเกี่ยวกับประเภทโมดูลเฉพาะและตัวอย่างคำจำกัดความของโมดูล โปรดดูที่ โมดูลไบนารี , โมดูลไลบรารี หรือ โมดูลทดสอบ

ประเภทโมดูลพื้นฐาน

พิมพ์	คำนิยาม	สำหรับข้อมูลเพิ่มเติม
rust_binary	ไบนารี สนิม	หน้า โมดูลไบนารี
rust_library	สร้างไลบรารี่ Rust และจัดเตรียมทั้งตัวแปร rlib และ dylib	rust_library หน้าโมดูลไลบรารี
rust_ffi	สร้างไลบรารี Rust C ที่ใช้งานได้โดยโมดูล cc และจัดเตรียมตัวแปรทั้งแบบคงที่และแบบแชร์	rust_ffi หน้าโมดูลไลบรารี
rust_proc_macro	สร้างไลบรารี proc-macro Rust (สิ่งเหล่านี้คล้ายคลึงกับปลั๊กอินคอมไพเลอร์)	rust_proc_macro หน้าโมดูลไลบรารี
rust_test	สร้างไบนารีทดสอบ สนิม ที่ใช้ชุดทดสอบ สนิม มาตรฐาน	หน้า ทดสอบโมดูล
rust_fuzz	สร้างไบนารีฟัซซี่ สนิม ที่ใช้ประโยชน์ libfuzzer	ตัวอย่างโมดูล rust_fuzz
rust_protobuf	สร้างซอร์สและสร้างไลบรารี่ Rust ที่จัดเตรียมอินเทอร์เฟซสำหรับโปรโตบัฟเฉพาะ	หน้าโมดูล Protobufs และ ตัวสร้างแหล่งที่มา
rust_bindgen	สร้างซอร์สและสร้างไลบรารี่ Rust ที่มีการเชื่อม Rust กับไลบรารี C	หน้า Bindgen Bindings Modules และ Source Generators

คุณสมบัติทั่วไปที่สำคัญ

คุณสมบัติเหล่านี้พบได้ทั่วไปใน Android Rust Modules ทั้งหมด คุณสมบัติเพิ่มเติม (เฉพาะ) ที่เกี่ยวข้องกับโมดูล Rust แต่ละโมดูลจะแสดงรายการอยู่ในหน้าของโมดูลนั้น

ชื่อ

name คือชื่อของโมดูลของคุณ เช่นเดียวกับโมดูล Soong อื่นๆ สิ่งนี้จะต้องไม่ซ้ำกันในโมดูล Android.bp ส่วนใหญ่ ตามค่าเริ่มต้น name จะถูกใช้เป็นชื่อไฟล์เอาต์พุต หากชื่อไฟล์เอาต์พุตต้องแตกต่างจากชื่อโมดูล ให้ใช้คุณสมบัติ stem เพื่อกำหนด

ลำต้น

stem (เป็นทางเลือก) ให้การควบคุมชื่อไฟล์เอาต์พุตโดยตรง (ไม่รวมนามสกุลไฟล์และส่วนต่อท้ายอื่นๆ) ตัวอย่างเช่น ไลบรารี rust_library_rlib ที่มีค่าสเต็มเป็น libfoo จะสร้างไฟล์ libfoo.rlib หากคุณไม่ได้ระบุค่าสำหรับคุณสมบัติ stem กำเนิด ชื่อไฟล์เอาต์พุตจะใช้ชื่อโมดูลตามค่าเริ่มต้น

ใช้ฟังก์ชัน stem เมื่อคุณไม่สามารถตั้งชื่อโมดูลเป็นชื่อไฟล์เอาต์พุตที่ต้องการได้ ตัวอย่างเช่น rust_library สำหรับลัง log มีชื่อว่า liblog_rust เนื่องจากมี liblog cc_library อยู่แล้ว การใช้คุณสมบัติ stem ในกรณีนี้ช่วยให้แน่ใจว่าไฟล์เอาต์พุตมีชื่อว่า liblog.* แทนที่จะเป็น liblog_rust.*

srcs

srcs มีไฟล์ต้นฉบับเดียวที่แสดงถึงจุดเริ่มต้นไปยังโมดูลของคุณ (โดยปกติคือ main.rs หรือ lib.rs ) rustc จัดการความละเอียดและการค้นหาไฟล์ต้นฉบับอื่นๆ ทั้งหมดที่จำเป็นสำหรับการคอมไพล์ และสิ่งเหล่านี้ถูกแจกแจงไว้ในไฟล์ deps ที่สร้างขึ้น

เมื่อเป็นไปได้ ให้หลีกเลี่ยงการใช้โค้ดแพลตฟอร์มนี้ ดู เครื่องกำเนิดแหล่งที่มา สำหรับข้อมูลเพิ่มเติม

crate_name

crate_name ตั้งค่าข้อมูลเมตาของชื่อลังผ่านแฟล็ก rustc --crate_name สำหรับโมดูลที่สร้างไลบรารี สิ่งนี้ จะต้อง ตรงกับชื่อลังที่ใช้ในแหล่งที่มา ตัวอย่างเช่น หากโมดูล libfoo_bar ถูกอ้างอิงในซอร์สเป็น extern crate foo_bar จะ ต้อง เป็น crate_name: "foo_bar"

คุณสมบัติ rust_bindgen เป็นเรื่องปกติสำหรับโมดูล rust_* ทั้งหมด แต่ จำเป็น สำหรับโมดูลที่สร้างไลบรารี ของRust (เช่น rust_library , rust_ffi , rust_protobuf และ rust_proc_macro ) โมดูลเหล่านี้บังคับใช้ข้อกำหนด rustc กับความสัมพันธ์ระหว่าง crate_name และชื่อไฟล์เอาต์พุต สำหรับข้อมูลเพิ่มเติม โปรดดูส่วน โมดูลห้องสมุด

ผ้าสำลี

rubc linter จะถูกรันตามค่าเริ่มต้นสำหรับโมดูลทุกประเภท ยกเว้นตัวสร้างต้นทาง ชุดผ้าสำลีบางชุดถูกกำหนดและใช้เพื่อตรวจสอบแหล่งที่มาของโมดูล ค่าที่เป็นไปได้สำหรับชุดผ้าสำลีดังกล่าวมีดังนี้:

• default เริ่มต้นของชุดผ้าสำลีเริ่มต้น ขึ้นอยู่กับตำแหน่งของโมดูล
• android เป็นชุดผ้าสำลีที่เข้มงวดที่สุดที่ใช้กับโค้ดแพลตฟอร์ม Android ทั้งหมด
• vendor ชุดผ้าสำลีที่ผ่อนคลายนำไปใช้กับรหัสผู้ขาย
• none ที่จะเพิกเฉยต่อคำเตือนและข้อผิดพลาดเกี่ยวกับผ้าสำลีทั้งหมด

clippy_lints

Clippy linter ยังทำงานตามค่าเริ่มต้นสำหรับโมดูลทุกประเภท ยกเว้นตัวสร้างต้นทาง มีการกำหนด Lints สองสามชุดซึ่งใช้เพื่อตรวจสอบแหล่งที่มาของโมดูล ค่าเหล่านี้คือค่าที่เป็นไปได้:

• default ชุดเริ่มต้นของผ้าสำลีขึ้นอยู่กับตำแหน่งของโมดูล
• android เป็นชุดผ้าสำลีที่เข้มงวดที่สุดที่ใช้กับโค้ดแพลตฟอร์ม Android ทั้งหมด
• vendor ชุดผ้าสำลีที่ผ่อนคลายนำไปใช้กับรหัสผู้ขาย
• none ที่จะเพิกเฉยต่อคำเตือนและข้อผิดพลาดเกี่ยวกับผ้าสำลีทั้งหมด

ฉบับ

edition กำหนดรุ่น Rust เพื่อใช้ในการรวบรวมโค้ดนี้ ซึ่งคล้ายกับเวอร์ชันมาตรฐานสำหรับ C และ C++ ค่าที่ถูกต้องคือ 2015 และ 2018 (ค่าเริ่มต้น)

ธง

flags มีรายการสตริงของ flag ที่จะส่งผ่านไปยัง rustc ในระหว่างการคอมไพล์

ld_flags

ld-flags มีรายการสตริงของแฟล็กที่จะส่งผ่านไปยังตัวเชื่อมโยงเมื่อทำการคอมไพล์ซอร์ส สิ่งเหล่านี้ถูกส่งผ่านโดยแฟล็ก -C linker-args clang ถูกใช้เป็นส่วนหน้าของตัวเชื่อมโยง โดยเรียกใช้ lld สำหรับการเชื่อมโยงจริง

คุณสมบัติ

features คือรายการสตริงของคุณสมบัติที่ต้องเปิดใช้งานระหว่างการคอมไพล์ สิ่งนี้ถูกส่งผ่านไปยังสนิมโดย --cfg 'feature="foo"' คุณลักษณะส่วนใหญ่เป็นคุณลักษณะเพิ่มเติม ดังนั้นในหลายกรณี คุณลักษณะนี้จึงประกอบด้วยคุณลักษณะทั้งหมดที่กำหนดโดยโมดูลที่ต้องพึ่งพาทั้งหมด อย่างไรก็ตาม ในกรณีที่คุณลักษณะแยกจากกัน ให้กำหนดโมดูลเพิ่มเติมในไฟล์บิลด์ใดๆ ที่มีคุณลักษณะที่ขัดแย้งกัน

ซีเอฟจี

cfgs มีรายการสตริงของแฟล็ก cfg ที่จะเปิดใช้งานในระหว่างการคอมไพล์ สิ่งนี้ถูกส่งผ่านไปยัง rustc โดย --cfg foo และ --cfg "fizz=buzz"

ระบบบิลด์จะตั้งค่าสถานะ cfg บางอย่างโดยอัตโนมัติในสถานการณ์เฉพาะตามรายการด้านล่าง:

• โมดูลที่สร้างเป็น dylib จะมีชุด android_dylib cfg

• โมดูลที่จะใช้ VNDK จะมีชุด android_vndk cfg ซึ่งคล้ายกับคำจำกัดความ __ANDROID_VNDK__ สำหรับ C++

เปลื้องผ้า

strip ควบคุมว่าจะตัดไฟล์เอาต์พุตหรือไม่และอย่างไร (ถ้ามี) หากไม่ได้ตั้งค่าไว้ โมดูลอุปกรณ์จะมีค่าเริ่มต้นที่จะตัดทุกอย่างยกเว้นข้อมูลการแก้ไขจุดบกพร่องขนาดเล็ก ตามค่าเริ่มต้น โมดูลโฮสต์จะไม่ตัดสัญลักษณ์ใดๆ ค่าที่ถูกต้องได้แก่ none เพื่อปิดใช้งานการสตริป และ all เพื่อตัดทุกอย่าง รวมถึง mini debuginfo สามารถดูค่าเพิ่มเติมได้ใน Soong Modules Reference

โฮสต์_สนับสนุน

สำหรับโมดูลอุปกรณ์ พารามิเตอร์ host_supported ระบุว่าโมดูลควรจัดเตรียมตัวแปรโฮสต์ด้วยหรือไม่

กำหนดการพึ่งพาห้องสมุด

โมดูล Rust สามารถขึ้นอยู่กับทั้งไลบรารี CC และ Rust ผ่านคุณสมบัติต่อไปนี้:

ชื่อคุณสมบัติ	คำอธิบาย
rustlibs	รายการโมดูล rust_library ที่มีการขึ้นต่อกันด้วย ใช้สิ่งนี้เป็นวิธีที่คุณต้องการในการประกาศการขึ้นต่อกัน เนื่องจากจะทำให้ระบบ build สามารถเลือกการเชื่อมโยงที่ต้องการได้ (ดู เมื่อเชื่อมโยงกับไลบรารี่ ของ Rust ด้านล่าง)
rlibs	รายการโมดูล rust_library ที่ต้องเชื่อมโยงแบบคงที่เป็น rlibs (ใช้ด้วยความระมัดระวัง ดู เมื่อเชื่อมโยงกับไลบรารี Rust ด้านล่าง)
shared_libs	รายการโมดูล cc_library ที่ต้องเชื่อมโยงแบบไดนามิกเป็นไลบรารีที่แบ่งใช้
static_libs	รายการโมดูล cc_library ที่ต้องเชื่อมโยงแบบคงที่เป็นไลบรารีแบบคงที่
whole_static_libs	รายการโมดูล cc_library ที่ควรเชื่อมโยงแบบคงที่เป็นไลบรารีแบบคงที่และรวมทั้งหมดไว้ในไลบรารีผลลัพธ์ สำหรับตัวแปร rust_ffi_static whole_static_libraries จะถูกรวมไว้ในไฟล์เก็บถาวรไลบรารีแบบคงที่ที่เป็นผลลัพธ์ สำหรับตัวแปร rust_library_rlib ไลบรารี whole_static_libraries จะถูกรวมเข้ากับไลบรารี rlib ที่เป็นผลลัพธ์

เมื่อเชื่อมโยงกับไลบรารี Rust ตามแนวทางปฏิบัติที่ดีที่สุด ให้ทำเช่นนั้นโดยใช้คุณสมบัติ rustlibs แทนที่จะใช้ rlibs หรือ dylibs เว้นแต่คุณจะมีเหตุผลเฉพาะเจาะจงในการดำเนินการดังกล่าว ซึ่งช่วยให้ระบบบิลด์สามารถเลือกการเชื่อมโยงที่ถูกต้องตามสิ่งที่โมดูลรูทต้องการ และลดโอกาสที่แผนผังการพึ่งพามีทั้งเวอร์ชัน rlib และ dylib ของไลบรารี (ซึ่งจะทำให้การคอมไพล์ล้มเหลว)

คุณสมบัติการสร้างการสนับสนุนที่ไม่รองรับและจำกัด

Soong's Rust ให้การสนับสนุนอย่างจำกัดสำหรับอิมเมจและสแนปชอต vendor และ vendor_ramdisk อย่างไรก็ตาม รองรับ staticlibs , cdylibs , rlibs และ binaries สำหรับเป้าหมายการสร้างอิมเมจของผู้ขาย คุณสมบัติ android_vndk cfg จะถูกตั้งค่า คุณสามารถใช้สิ่งนี้ในโค้ดได้หากมีความแตกต่างระหว่างระบบและเป้าหมายของผู้ขาย rust_proc_macros ไม่ได้ถูกบันทึกเป็นส่วนหนึ่งของสแน็ปช็อตของผู้ขาย หากสิ่งเหล่านี้ขึ้นอยู่กับ ตรวจสอบให้แน่ใจว่าคุณควบคุมเวอร์ชันได้อย่างเหมาะสม

ไม่รองรับอิมเมจผลิตภัณฑ์, VNDK และการกู้คืน

การสร้างที่เพิ่มขึ้น

นักพัฒนาสามารถเปิดใช้งานการคอมไพล์ที่เพิ่มขึ้นของแหล่งที่มาของ Rust ได้โดยการตั้งค่าตัวแปรสภาพแวดล้อม SOONG_RUSTC_INCREMENTAL เป็น true

คำเตือน : ไม่รับประกันว่าจะสร้างไบนารีที่เหมือนกับที่สร้างโดย buildbots ที่อยู่ของฟังก์ชันหรือข้อมูลที่มีอยู่ในไฟล์อ็อบเจ็กต์อาจแตกต่างกัน เพื่อให้แน่ใจว่าอาร์ติแฟกต์ที่สร้างขึ้นจะเหมือนกับอาร์ติแฟกต์ที่สร้างโดยโครงสร้างพื้นฐาน EngProd 100% โปรดปล่อยค่านี้ไว้โดยไม่ได้ตั้งค่า