โมดูล 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 ที่เฉพาะเจาะจง หน้าโมดูล Protobufs และเครื่องมือสร้างแหล่งข้อมูล
rust_bindgenสร้างแหล่งที่มาและผลิตไลบรารี Rust ที่มี Binding ของ Rust กับไลบรารี C โมดูลการเชื่อมโยง Bindgen และหน้าเครื่องมือสร้างแหล่งข้อมูล

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

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

เศษผ้า

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

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

clippy_lints

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

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

ฉบับ

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

ธง

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

ld_flags

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

ฟีเจอร์

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

cfgs

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

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

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

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

แถบ

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

host_supported

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

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

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

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