โมดูล 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

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

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

srcs

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

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

crate_name

crate_name ตั้งค่าข้อมูลเมตาของชื่อ crate ผ่านแฟล็ก 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 โดยค่าเริ่มต้นสำหรับโมดูลทุกประเภท ยกเว้นเครื่องมือสร้างซอร์สโค้ด มีการกำหนดและใช้ชุด lint บางชุดเพื่อตรวจสอบซอร์สโค้ดของโมดูล ค่าที่เป็นไปได้สำหรับชุด lint ดังกล่าวมีดังนี้

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

clippy_lints

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

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

edition

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

flags

flags มีรายการสตริงของแฟล็กที่จะส่งไปยัง rustc ระหว่างการคอมไพล์

ld_flags

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

features

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

cfgs

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

ระบบบิลด์จะตั้งค่าแฟล็ก cfg บางรายการโดยอัตโนมัติในบางสถานการณ์ที่ระบุไว้ด้านล่าง

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

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

strip

strip ควบคุมว่าจะลบสัญลักษณ์ออกจากไฟล์เอาต์พุตหรือไม่และลบอย่างไร (หากมี) หากไม่ได้ตั้งค่าไว้ โมดูลอุปกรณ์จะลบสัญลักษณ์ทั้งหมดออกโดยค่าเริ่มต้น ยกเว้นข้อมูลการแก้ไขข้อบกพร่องขนาดเล็ก โมดูลโฮสต์จะไม่ลบสัญลักษณ์ใดๆ ออกโดยค่าเริ่มต้น ค่าที่ใช้ได้ ได้แก่ none เพื่อปิดใช้การลบสัญลักษณ์ และ all เพื่อลบสัญลักษณ์ทั้งหมดออก รวมถึงข้อมูลการแก้ไขข้อบกพร่องขนาดเล็ก ดูค่าเพิ่มเติมได้ใน ข้อมูลอ้างอิงโมดูล 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 สำหรับเป้าหมายบิลด์รูปภาพของผู้ให้บริการ ระบบจะตั้งค่าพร็อพเพอร์ตี้ cfg android_vndk คุณสามารถใช้พร็อพเพอร์ตี้นี้ในโค้ดได้หากเป้าหมายของระบบและของผู้ให้บริการแตกต่างกัน ระบบจะไม่บันทึก rust_proc_macros เป็นส่วนหนึ่งของสแนปช็อตของผู้ให้บริการ หากโมดูลอื่นขึ้นอยู่กับโมดูลเหล่านี้ โปรดตรวจสอบว่าคุณได้ควบคุมเวอร์ชันของโมดูลเหล่านี้อย่างเหมาะสม

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

บิลด์แบบเพิ่ม

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

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