โมดูล Rust ของ Android

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

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

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

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

พร็อพเพอร์ตี้ทั่วไปที่สําคัญ

พร็อพเพอร์ตี้เหล่านี้เป็นพร็อพเพอร์ตี้ทั่วไปของโมดูล Rust ทั้งหมดใน Android พร็อพเพอร์ตี้เพิ่มเติม (ที่ไม่ซ้ำกัน) ที่เชื่อมโยงกับแต่ละโมดูล 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 ตั้งค่าข้อมูลเมตาชื่อกล่องผ่าน Flag rustc --crate_name สําหรับโมดูลที่สร้างไลบรารี ค่านี้ต้องตรงกับชื่อ crate ที่คาดไว้ซึ่งใช้ในแหล่งที่มา เช่น หากมีการอ้างอิงโมดูล libfoo_bar ในซอร์สโค้ดเป็น extern crate foo_bar ต้องเป็น crate_name: "foo_bar"

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

Lints

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

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

clippy_lints

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

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

ฉบับ

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

ธง

flags มีรายการสตริงของ Flag เพื่อส่งไปยัง rustc ระหว่างการคอมไพล์

ld_flags

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

ฟีเจอร์

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

cfgs

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

ระบบบิลด์จะตั้งค่า Flag cfg บางรายการโดยอัตโนมัติในสถานการณ์ต่อไปนี้

• โมดูลที่สร้างเป็น dylib จะมีandroid_dylib cfg ตั้งค่าไว้

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

แถบ

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

host_supported

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

กำหนดทรัพยากร Dependency ของไลบรารี

โมดูล Rust สามารถใช้ทั้งไลบรารี CC และ Rust ผ่านพร็อพเพอร์ตี้ต่อไปนี้

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

ฟีเจอร์ของรุ่นที่รองรับและรองรับอย่างจำกัด

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

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

บิวด์ที่เพิ่มขึ้น

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

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