เครื่องกำเนิดแหล่งที่มา

หน้านี้แสดงมุมมองระดับสูงเกี่ยวกับวิธีการสนับสนุนแหล่งที่มาที่สร้างขึ้น และวิธีใช้แหล่งที่มาในระบบบิลด์

ตัวสร้างซอร์สทั้งหมดมีฟังก์ชันการทำงานของระบบบิลด์ที่คล้ายคลึงกัน กรณีการใช้งานการสร้างต้นทางที่สนับสนุนระบบบิลด์สามกรณีกำลังสร้างการเชื่อมโยง C โดยใช้ Bingen, อินเทอร์เฟซ AIDL และอินเทอร์เฟซ Protobuf

ลังจากแหล่งที่สร้างขึ้น

โมดูล Rust ทุกโมดูลที่สร้างซอร์สโค้ดสามารถใช้เป็นลังได้ เหมือนกับว่ามันถูกกำหนดให้เป็น rust_library (ซึ่งหมายความว่าสามารถกำหนดเป็นการพึ่งพาในคุณสมบัติ rustlibs , rlibs และ dylibs ) รูปแบบการใช้งานที่ดีที่สุดสำหรับโค้ดแพลตฟอร์มคือการใช้ซอร์สที่สร้างขึ้นเป็นลัง แม้ว่าการ include! มาโครได้รับการสนับสนุนสำหรับแหล่งที่มาที่สร้างขึ้น วัตถุประสงค์หลักคือเพื่อรองรับโค้ดของบุคคลที่สามที่อยู่ใน external/ .

มีหลายกรณีที่โค้ดแพลตฟอร์มอาจยังคงใช้ซอร์สที่สร้างขึ้นผ่าน include!() เช่น เมื่อคุณใช้โมดูล genrule เพื่อสร้างซอร์สในลักษณะเฉพาะ

ใช้ include!() เพื่อรวมแหล่งที่มาที่สร้างขึ้น

การใช้แหล่งที่มาที่สร้างขึ้นเป็นลังจะครอบคลุมอยู่ในตัวอย่างในแต่ละหน้าโมดูลเฉพาะ (ตามลำดับ) ส่วนนี้จะแสดงวิธีอ้างอิงแหล่งที่มาที่สร้างขึ้นผ่านมาโคร include!() โปรดทราบว่ากระบวนการนี้คล้ายกันสำหรับเครื่องกำเนิดแหล่งที่มาทั้งหมด

ข้อกำหนดเบื้องต้น

ตัวอย่างนี้อิงตามสมมติฐานที่คุณกำหนดโมดูล rust_bindgen ( libbuzz_bindgen ) และสามารถดำเนินการ ขั้นตอนในการรวมซอร์สที่สร้างขึ้น สำหรับการใช้แมโคร include!() หากคุณยังไม่ได้ โปรดไปที่ Dนิยามโมดูลการผูกสนิม สร้าง libbuzz_bindgen จากนั้นกลับมาที่นี่

โปรดทราบว่าส่วนไฟล์บิลด์นี้ใช้ได้กับตัวสร้างต้นทางทั้งหมด

ขั้นตอนในการรวมแหล่งที่มาที่สร้างขึ้น

สร้าง external/rust/hello_bindgen/Android.bp ด้วยเนื้อหาต่อไปนี้:

rust_binary {
   name: "hello_bzip_bindgen_include",
   srcs: [
         // The primary rust source file must come first in this list.
         "src/lib.rs",

         // The module providing the bindgen bindings is
         // included in srcs prepended by ":".
         ":libbuzz_bindgen",
    ],

    // Dependencies need to be redeclared when generated source is used via srcs.
    shared_libs: [
        "libbuzz",
    ],
}

สร้าง external/rust/hello_bindgen/src/bindings.rs ด้วยเนื้อหาต่อไปนี้:

#![allow(clippy::all)]
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(unused)]
#![allow(missing_docs)]

// Note that "bzip_bindings.rs" here must match the source_stem property from
// the rust_bindgen module.
include!(concat!(env!("OUT_DIR"), "/bzip_bindings.rs"));

สร้าง external/rust/hello_bindgen/src/lib.rs ด้วยเนื้อหาต่อไปนี้:

mod bindings;

fn main() {
    let mut x = bindings::foo { x: 2 };
    unsafe { bindings::fizz(1, &mut x as *mut bindings::foo) }
}

ทำไมต้องลังสำหรับแหล่งที่สร้างขึ้น

ไม่เหมือนกับคอมไพเลอร์ C/C++ ตรงที่ rustc ยอมรับเฉพาะไฟล์ต้นฉบับเดียวที่แสดงถึงจุดเข้าสู่ไบนารีหรือไลบรารี คาดว่าแผนผังต้นทางจะมีโครงสร้างเพื่อให้สามารถค้นพบไฟล์ต้นฉบับที่จำเป็นทั้งหมดได้โดยอัตโนมัติ ซึ่งหมายความว่าแหล่งที่มาที่สร้างขึ้นจะต้องวางไว้ในแผนผังแหล่งที่มาหรือระบุผ่านคำสั่งรวมในแหล่งที่มา:

include!("/path/to/hello.rs");

ชุมชน Rust ขึ้นอยู่กับสคริปต์ build.rs และสมมติฐานเกี่ยวกับสภาพแวดล้อมการสร้าง Cargo เพื่อ ทำงานกับความแตกต่างนี้ เมื่อสร้าง คำสั่ง cargo จะตั้งค่า ตัวแปรสภาพแวดล้อม OUT_DIR ซึ่งสคริปต์ build.rs คาดว่าจะวางซอร์สโค้ดที่สร้างขึ้น ใช้คำสั่งต่อไปนี้เพื่อรวมซอร์สโค้ด:

include!(concat!(env!("OUT_DIR"), "/hello.rs"));

สิ่งนี้นำเสนอความท้าทายสำหรับ Soong เนื่องจากเอาต์พุตสำหรับแต่ละโมดูลถูกวางไว้ใน out/ directory ¹ ของตัวเอง ไม่มี OUT_DIR เดียวที่การอ้างอิงส่งออกแหล่งที่มาที่สร้างขึ้น

สำหรับรหัสแพลตฟอร์ม AOSP ชอบบรรจุภัณฑ์ที่สร้างจากแหล่งที่มาลงในลังที่สามารถนำเข้าได้ ด้วยเหตุผลหลายประการ:

• ป้องกันชื่อไฟล์ต้นฉบับที่สร้างขึ้นจากการชนกัน
• ลดการเช็ค อินโค้ดสำเร็จรูป ตลอดทั้งทรีที่ต้องการการบำรุงรักษา ต้นแบบใด ๆ ที่จำเป็นในการทำให้ แหล่งที่มาที่สร้างขึ้นรวบรวม ลงในลังสามารถรักษาได้จากส่วนกลาง
• หลีกเลี่ยงการโต้ตอบโดยนัย ^{2 ครั้ง} ระหว่างโค้ดที่สร้างขึ้นและลังโดยรอบ
• ลดแรงกดดันต่อหน่วยความจำและดิสก์โดยการเชื่อมโยงแหล่งข้อมูลที่สร้างขึ้นโดยทั่วไปแบบไดนามิก

ด้วยเหตุนี้ ประเภทโมดูลการสร้างซอร์ส Rust ของ Android ทั้งหมดจึงสร้างโค้ดที่สามารถคอมไพล์และใช้ เป็นลัง ได้ Soong ยังคงสนับสนุนลังของบุคคลที่สามโดยไม่มีการแก้ไข หากการพึ่งพาแหล่งที่มาที่สร้างขึ้นทั้งหมดสำหรับโมดูลถูกคัดลอกไปยังไดเร็กทอรีต่อโมดูลเดียว คล้ายกับ Cargo ในกรณีเช่นนี้ Soong จะตั้งค่าตัวแปรสภาพแวดล้อม OUT_DIR ให้กับไดเร็กทอรีนั้นเมื่อทำการคอมไพล์โมดูล เพื่อให้สามารถค้นหาแหล่งที่มาที่สร้างขึ้นได้ อย่างไรก็ตาม ด้วยเหตุผลที่อธิบายไว้แล้ว แนวทางปฏิบัติที่ดีที่สุดคือใช้กลไกนี้ในโค้ดแพลตฟอร์มเมื่อจำเป็นจริงๆ เท่านั้น

-

หน้านี้แสดงมุมมองระดับสูงเกี่ยวกับวิธีการสนับสนุนแหล่งที่มาที่สร้างขึ้น และวิธีใช้แหล่งที่มาในระบบบิลด์

ตัวสร้างซอร์สทั้งหมดมีฟังก์ชันการทำงานของระบบบิลด์ที่คล้ายคลึงกัน กรณีการใช้งานการสร้างต้นทางที่สนับสนุนระบบบิลด์สามกรณีกำลังสร้างการเชื่อมโยง C โดยใช้ Bingen, อินเทอร์เฟซ AIDL และอินเทอร์เฟซ Protobuf

ลังจากแหล่งที่สร้างขึ้น

โมดูล Rust ทุกโมดูลที่สร้างซอร์สโค้ดสามารถใช้เป็นลังได้ เหมือนกับว่ามันถูกกำหนดให้เป็น rust_library (ซึ่งหมายความว่าสามารถกำหนดเป็นการพึ่งพาในคุณสมบัติ rustlibs , rlibs และ dylibs ) รูปแบบการใช้งานที่ดีที่สุดสำหรับโค้ดแพลตฟอร์มคือการใช้ซอร์สที่สร้างขึ้นเป็นลัง แม้ว่าการ include! มาโครได้รับการสนับสนุนสำหรับแหล่งที่มาที่สร้างขึ้น วัตถุประสงค์หลักคือเพื่อรองรับโค้ดของบุคคลที่สามที่อยู่ใน external/ .

มีหลายกรณีที่โค้ดแพลตฟอร์มอาจยังคงใช้ซอร์สที่สร้างขึ้นผ่าน include!() เช่น เมื่อคุณใช้โมดูล genrule เพื่อสร้างซอร์สในลักษณะเฉพาะ

ใช้ include!() เพื่อรวมแหล่งที่มาที่สร้างขึ้น

การใช้แหล่งที่มาที่สร้างขึ้นเป็นลังจะครอบคลุมอยู่ในตัวอย่างในแต่ละหน้าโมดูลเฉพาะ (ตามลำดับ) ส่วนนี้จะแสดงวิธีอ้างอิงแหล่งที่มาที่สร้างขึ้นผ่านมาโคร include!() โปรดทราบว่ากระบวนการนี้คล้ายกันสำหรับเครื่องกำเนิดแหล่งที่มาทั้งหมด

ข้อกำหนดเบื้องต้น

ตัวอย่างนี้อิงตามสมมติฐานที่คุณกำหนดโมดูล rust_bindgen ( libbuzz_bindgen ) และสามารถดำเนินการ ขั้นตอนในการรวมซอร์สที่สร้างขึ้น สำหรับการใช้แมโคร include!() หากคุณยังไม่ได้ โปรดไปที่ Dนิยามโมดูลการผูกสนิม สร้าง libbuzz_bindgen จากนั้นกลับมาที่นี่

โปรดทราบว่าส่วนไฟล์บิลด์นี้ใช้ได้กับตัวสร้างต้นทางทั้งหมด

ขั้นตอนในการรวมแหล่งที่มาที่สร้างขึ้น

สร้าง external/rust/hello_bindgen/Android.bp ด้วยเนื้อหาต่อไปนี้:

rust_binary {
   name: "hello_bzip_bindgen_include",
   srcs: [
         // The primary rust source file must come first in this list.
         "src/lib.rs",

         // The module providing the bindgen bindings is
         // included in srcs prepended by ":".
         ":libbuzz_bindgen",
    ],

    // Dependencies need to be redeclared when generated source is used via srcs.
    shared_libs: [
        "libbuzz",
    ],
}

สร้าง external/rust/hello_bindgen/src/bindings.rs ด้วยเนื้อหาต่อไปนี้:

#![allow(clippy::all)]
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(unused)]
#![allow(missing_docs)]

// Note that "bzip_bindings.rs" here must match the source_stem property from
// the rust_bindgen module.
include!(concat!(env!("OUT_DIR"), "/bzip_bindings.rs"));

สร้าง external/rust/hello_bindgen/src/lib.rs ด้วยเนื้อหาต่อไปนี้:

mod bindings;

fn main() {
    let mut x = bindings::foo { x: 2 };
    unsafe { bindings::fizz(1, &mut x as *mut bindings::foo) }
}

ทำไมต้องลังสำหรับแหล่งที่สร้างขึ้น

ไม่เหมือนกับคอมไพเลอร์ C/C++ ตรงที่ rustc ยอมรับเฉพาะไฟล์ต้นฉบับเดียวที่แสดงถึงจุดเข้าสู่ไบนารีหรือไลบรารี คาดว่าแผนผังต้นทางจะมีโครงสร้างเพื่อให้สามารถค้นพบไฟล์ต้นฉบับที่จำเป็นทั้งหมดได้โดยอัตโนมัติ ซึ่งหมายความว่าแหล่งที่มาที่สร้างขึ้นจะต้องวางไว้ในแผนผังแหล่งที่มาหรือระบุผ่านคำสั่งรวมในแหล่งที่มา:

include!("/path/to/hello.rs");

ชุมชน Rust ขึ้นอยู่กับสคริปต์ build.rs และสมมติฐานเกี่ยวกับสภาพแวดล้อมการสร้าง Cargo เพื่อ ทำงานกับความแตกต่างนี้ เมื่อสร้าง คำสั่ง cargo จะตั้งค่า ตัวแปรสภาพแวดล้อม OUT_DIR ซึ่งสคริปต์ build.rs คาดว่าจะวางซอร์สโค้ดที่สร้างขึ้น ใช้คำสั่งต่อไปนี้เพื่อรวมซอร์สโค้ด:

include!(concat!(env!("OUT_DIR"), "/hello.rs"));

สิ่งนี้นำเสนอความท้าทายสำหรับ Soong เนื่องจากเอาต์พุตสำหรับแต่ละโมดูลถูกวางไว้ใน out/ directory ¹ ของตัวเอง ไม่มี OUT_DIR เดียวที่การอ้างอิงส่งออกแหล่งที่มาที่สร้างขึ้น

สำหรับรหัสแพลตฟอร์ม AOSP ชอบบรรจุภัณฑ์ที่สร้างจากแหล่งที่มาลงในลังที่สามารถนำเข้าได้ ด้วยเหตุผลหลายประการ:

• ป้องกันชื่อไฟล์ต้นฉบับที่สร้างขึ้นจากการชนกัน
• ลดการเช็ค อินโค้ดสำเร็จรูป ตลอดทั้งทรีที่ต้องการการบำรุงรักษา ต้นแบบใด ๆ ที่จำเป็นในการทำให้ แหล่งที่มาที่สร้างขึ้นรวบรวม ลงในลังสามารถรักษาได้จากส่วนกลาง
• หลีกเลี่ยงการโต้ตอบโดยนัย ^{2 ครั้ง} ระหว่างโค้ดที่สร้างขึ้นและลังโดยรอบ
• ลดแรงกดดันต่อหน่วยความจำและดิสก์โดยการเชื่อมโยงแหล่งข้อมูลที่สร้างขึ้นโดยทั่วไปแบบไดนามิก

ด้วยเหตุนี้ ประเภทโมดูลการสร้างซอร์ส Rust ของ Android ทั้งหมดจึงสร้างโค้ดที่สามารถคอมไพล์และใช้ เป็นลัง ได้ Soong ยังคงสนับสนุนลังของบุคคลที่สามโดยไม่มีการแก้ไข หากการพึ่งพาแหล่งที่มาที่สร้างขึ้นทั้งหมดสำหรับโมดูลถูกคัดลอกไปยังไดเร็กทอรีต่อโมดูลเดียว คล้ายกับ Cargo ในกรณีเช่นนี้ Soong จะตั้งค่าตัวแปรสภาพแวดล้อม OUT_DIR ให้กับไดเร็กทอรีนั้นเมื่อทำการคอมไพล์โมดูล เพื่อให้สามารถค้นหาแหล่งที่มาที่สร้างขึ้นได้ อย่างไรก็ตาม ด้วยเหตุผลที่อธิบายไว้แล้ว แนวทางปฏิบัติที่ดีที่สุดคือใช้กลไกนี้ในโค้ดแพลตฟอร์มเมื่อจำเป็นจริงๆ เท่านั้น

-

หน้านี้แสดงมุมมองระดับสูงเกี่ยวกับวิธีการสนับสนุนแหล่งที่มาที่สร้างขึ้น และวิธีใช้แหล่งที่มาในระบบบิลด์

ตัวสร้างซอร์สทั้งหมดมีฟังก์ชันการทำงานของระบบบิลด์ที่คล้ายคลึงกัน กรณีการใช้งานการสร้างต้นทางที่สนับสนุนระบบบิลด์สามกรณีกำลังสร้างการเชื่อมโยง C โดยใช้ Bingen, อินเทอร์เฟซ AIDL และอินเทอร์เฟซ Protobuf

ลังจากแหล่งที่สร้างขึ้น

โมดูล Rust ทุกโมดูลที่สร้างซอร์สโค้ดสามารถใช้เป็นลังได้ เหมือนกับว่ามันถูกกำหนดให้เป็น rust_library (ซึ่งหมายความว่าสามารถกำหนดเป็นการพึ่งพาในคุณสมบัติ rustlibs , rlibs และ dylibs ) รูปแบบการใช้งานที่ดีที่สุดสำหรับโค้ดแพลตฟอร์มคือการใช้ซอร์สที่สร้างขึ้นเป็นลัง แม้ว่าการ include! มาโครได้รับการสนับสนุนสำหรับแหล่งที่มาที่สร้างขึ้น วัตถุประสงค์หลักคือเพื่อรองรับโค้ดของบุคคลที่สามที่อยู่ใน external/ .

มีหลายกรณีที่โค้ดแพลตฟอร์มอาจยังคงใช้ซอร์สที่สร้างขึ้นผ่าน include!() เช่น เมื่อคุณใช้โมดูล genrule เพื่อสร้างซอร์สในลักษณะเฉพาะ

ใช้ include!() เพื่อรวมแหล่งที่มาที่สร้างขึ้น

การใช้แหล่งที่มาที่สร้างขึ้นเป็นลังจะครอบคลุมอยู่ในตัวอย่างในแต่ละหน้าโมดูลเฉพาะ (ตามลำดับ) ส่วนนี้จะแสดงวิธีอ้างอิงแหล่งที่มาที่สร้างขึ้นผ่านมาโคร include!() โปรดทราบว่ากระบวนการนี้คล้ายกันสำหรับเครื่องกำเนิดแหล่งที่มาทั้งหมด

ข้อกำหนดเบื้องต้น

ตัวอย่างนี้อิงตามสมมติฐานที่คุณกำหนดโมดูล rust_bindgen ( libbuzz_bindgen ) และสามารถดำเนินการ ขั้นตอนในการรวมซอร์สที่สร้างขึ้น สำหรับการใช้แมโคร include!() หากคุณยังไม่ได้ โปรดไปที่ Dนิยามโมดูลการผูกสนิม สร้าง libbuzz_bindgen จากนั้นกลับมาที่นี่

โปรดทราบว่าส่วนไฟล์บิลด์นี้ใช้ได้กับตัวสร้างต้นทางทั้งหมด

ขั้นตอนในการรวมแหล่งที่มาที่สร้างขึ้น

สร้าง external/rust/hello_bindgen/Android.bp ด้วยเนื้อหาต่อไปนี้:

rust_binary {
   name: "hello_bzip_bindgen_include",
   srcs: [
         // The primary rust source file must come first in this list.
         "src/lib.rs",

         // The module providing the bindgen bindings is
         // included in srcs prepended by ":".
         ":libbuzz_bindgen",
    ],

    // Dependencies need to be redeclared when generated source is used via srcs.
    shared_libs: [
        "libbuzz",
    ],
}

สร้าง external/rust/hello_bindgen/src/bindings.rs ด้วยเนื้อหาต่อไปนี้:

#![allow(clippy::all)]
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(unused)]
#![allow(missing_docs)]

// Note that "bzip_bindings.rs" here must match the source_stem property from
// the rust_bindgen module.
include!(concat!(env!("OUT_DIR"), "/bzip_bindings.rs"));

สร้าง external/rust/hello_bindgen/src/lib.rs ด้วยเนื้อหาต่อไปนี้:

mod bindings;

fn main() {
    let mut x = bindings::foo { x: 2 };
    unsafe { bindings::fizz(1, &mut x as *mut bindings::foo) }
}

ทำไมต้องลังสำหรับแหล่งที่สร้างขึ้น

ไม่เหมือนกับคอมไพเลอร์ C/C++ ตรงที่ rustc ยอมรับเฉพาะไฟล์ต้นฉบับเดียวที่แสดงถึงจุดเข้าสู่ไบนารีหรือไลบรารี คาดว่าแผนผังต้นทางจะมีโครงสร้างเพื่อให้สามารถค้นพบไฟล์ต้นฉบับที่จำเป็นทั้งหมดได้โดยอัตโนมัติ ซึ่งหมายความว่าแหล่งที่มาที่สร้างขึ้นจะต้องวางไว้ในแผนผังแหล่งที่มาหรือระบุผ่านคำสั่งรวมในแหล่งที่มา:

include!("/path/to/hello.rs");

ชุมชน Rust ขึ้นอยู่กับสคริปต์ build.rs และสมมติฐานเกี่ยวกับสภาพแวดล้อมการสร้าง Cargo เพื่อ ทำงานกับความแตกต่างนี้ เมื่อสร้าง คำสั่ง cargo จะตั้งค่า ตัวแปรสภาพแวดล้อม OUT_DIR ซึ่งสคริปต์ build.rs คาดว่าจะวางซอร์สโค้ดที่สร้างขึ้น ใช้คำสั่งต่อไปนี้เพื่อรวมซอร์สโค้ด:

include!(concat!(env!("OUT_DIR"), "/hello.rs"));

สิ่งนี้นำเสนอความท้าทายสำหรับ Soong เนื่องจากเอาต์พุตสำหรับแต่ละโมดูลถูกวางไว้ใน out/ directory ¹ ของตัวเอง ไม่มี OUT_DIR เดียวที่การอ้างอิงส่งออกแหล่งที่มาที่สร้างขึ้น

สำหรับรหัสแพลตฟอร์ม AOSP ชอบบรรจุภัณฑ์ที่สร้างจากแหล่งที่มาลงในลังที่สามารถนำเข้าได้ ด้วยเหตุผลหลายประการ:

• ป้องกันชื่อไฟล์ต้นฉบับที่สร้างขึ้นจากการชนกัน
• ลดการเช็ค อินโค้ดสำเร็จรูป ตลอดทั้งทรีที่ต้องการการบำรุงรักษา ต้นแบบใด ๆ ที่จำเป็นในการทำให้ แหล่งที่มาที่สร้างขึ้นรวบรวม ลงในลังสามารถรักษาได้จากส่วนกลาง
• หลีกเลี่ยงการโต้ตอบโดยนัย ^{2 ครั้ง} ระหว่างโค้ดที่สร้างขึ้นและลังโดยรอบ
• ลดแรงกดดันต่อหน่วยความจำและดิสก์โดยการเชื่อมโยงแหล่งข้อมูลที่สร้างขึ้นโดยทั่วไปแบบไดนามิก

ด้วยเหตุนี้ ประเภทโมดูลการสร้างซอร์ส Rust ของ Android ทั้งหมดจึงสร้างโค้ดที่สามารถคอมไพล์และใช้ เป็นลัง ได้ Soong ยังคงสนับสนุนลังของบุคคลที่สามโดยไม่มีการแก้ไข หากการพึ่งพาแหล่งที่มาที่สร้างขึ้นทั้งหมดสำหรับโมดูลถูกคัดลอกไปยังไดเร็กทอรีต่อโมดูลเดียว คล้ายกับ Cargo ในกรณีเช่นนี้ Soong จะตั้งค่าตัวแปรสภาพแวดล้อม OUT_DIR ให้กับไดเร็กทอรีนั้นเมื่อทำการคอมไพล์โมดูล เพื่อให้สามารถค้นหาแหล่งที่มาที่สร้างขึ้นได้ อย่างไรก็ตาม ด้วยเหตุผลที่อธิบายไว้แล้ว แนวทางปฏิบัติที่ดีที่สุดคือใช้กลไกนี้ในโค้ดแพลตฟอร์มเมื่อจำเป็นจริงๆ เท่านั้น