โมดูล Rust ของ Android
จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

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

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

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

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

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

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

พร็อพเพอร์ตี้เหล่านี้เป็นพร็อพเพอร์ตี้ทั่วไปของโมดูล 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 ที่สร้างขึ้น

เคล็ดลับ: srcs จะจัดการแหล่งที่มาที่สร้างขึ้นซึ่งมาโคร include! อ้างอิงด้วย แหล่งที่มาเหล่านี้ต้องมาจากโมดูลอื่น (เช่น genrule หรือ rust_protobuf เป็นต้น) หากต้องการรวมแหล่งที่มา ให้เพิ่มชื่อของโมดูลที่ให้แหล่งที่มาที่สร้างขึ้นลงใน srcs และใส่ : ไว้ข้างหน้า (เช่น ":libmyproto" ไฟล์ต้นทางหลักต้องเป็นรายการแรกในอาร์เรย์เมื่อใช้ฟังก์ชันการทำงานนี้

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

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 ผ่านพร็อพเพอร์ตี้ต่อไปนี้

ชื่อพร็อพเพอร์ตี้	คำอธิบาย
`rustlibs`	รายการโมดูล `rust_library` ที่เป็นข้อกําหนด ใช้รูปแบบนี้ในการประกาศการพึ่งพาที่ต้องการ เนื่องจากจะช่วยให้ระบบบิลด์เลือกการลิงก์ที่ต้องการได้ (ดูเมื่อลิงก์กับไลบรารี 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` ที่ได้ เคล็ดลับ: การดำเนินการนี้จะป้องกันไม่ให้คุณประกาศการพึ่งพาของรายการที่ขึ้นต่อกันสำหรับคลังนี้อีกครั้ง อย่างไรก็ตาม ในบางกรณี วิธีนี้อาจทําให้ไฟล์มีขนาดใหญ่ขึ้นหากมีการใช้คลังแบบคงที่ซ้ำกันภายในลําดับชั้นของข้อกําหนด ไลบรารีแบบคงที่ที่รวมไว้ทั้งหมดใน `rlibs` จะรวมอยู่ใน `dylibs` ที่ขึ้นต่อกันทั้งหมด ซึ่งเป็นแหล่งที่มาของไฟล์ที่อาจมีขนาดเกินอีกแหล่งหนึ่ง

เมื่อลิงก์กับไลบรารี 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%