โมดูล 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 หน้าโมดูลไบนารี
rust_libraryสร้างไลบรารี Rust และมีทั้งตัวแปร rlib และ dylib rust_library หน้าโมดูลคลัง
rust_ffiสร้างไลบรารี C Rust ที่โมดูลสำเนาใช้งานได้ และจัดเตรียมตัวแปรแบบคงที่และตัวแปรที่แชร์ rust_ffi, หน้าโมดูลคลัง
rust_proc_macroสร้างไลบรารี proc-macro Rust (ปลั๊กอินเหล่านี้คล้ายกับปลั๊กอินคอมไพเลอร์) rust_proc_macro หน้าโมดูลคลัง
rust_testสร้างไบนารีการทดสอบ Rust ที่ใช้ชุดทดสอบ Rust มาตรฐาน หน้าโมดูลทดสอบ
rust_fuzzสร้างไบนารี 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.*

src

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_* ทั้งหมด แต่ต้องระบุสำหรับโมดูลที่สร้างไลบรารี Rust (เช่น rust_library rust_ffi, rust_bindgen, rust_protobuf และ rust_proc_macro) โมดูลเหล่านี้บังคับใช้ข้อกำหนด rustc เกี่ยวกับความสัมพันธ์ระหว่าง crate_name กับชื่อไฟล์เอาต์พุต ดูข้อมูลเพิ่มเติมได้ที่ส่วนโมดูลไลบรารี

Lints

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

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

โปรแกรมลบลิงก์

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

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

ฉบับ

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

แฟล็ก

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

ld_flags

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

ฟีเจอร์

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

cfgs

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

รองรับโฮสต์

สำหรับโมดูลอุปกรณ์ พารามิเตอร์ 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%